activeentity 0.0.1.beta1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/MIT-LICENSE +42 -0
- data/README.md +145 -0
- data/Rakefile +29 -0
- data/lib/active_entity.rb +73 -0
- data/lib/active_entity/aggregations.rb +276 -0
- data/lib/active_entity/associations.rb +146 -0
- data/lib/active_entity/associations/embedded/association.rb +134 -0
- data/lib/active_entity/associations/embedded/builder/association.rb +100 -0
- data/lib/active_entity/associations/embedded/builder/collection_association.rb +69 -0
- data/lib/active_entity/associations/embedded/builder/embedded_in.rb +38 -0
- data/lib/active_entity/associations/embedded/builder/embeds_many.rb +13 -0
- data/lib/active_entity/associations/embedded/builder/embeds_one.rb +16 -0
- data/lib/active_entity/associations/embedded/builder/singular_association.rb +28 -0
- data/lib/active_entity/associations/embedded/collection_association.rb +188 -0
- data/lib/active_entity/associations/embedded/collection_proxy.rb +310 -0
- data/lib/active_entity/associations/embedded/embedded_in_association.rb +31 -0
- data/lib/active_entity/associations/embedded/embeds_many_association.rb +15 -0
- data/lib/active_entity/associations/embedded/embeds_one_association.rb +19 -0
- data/lib/active_entity/associations/embedded/singular_association.rb +35 -0
- data/lib/active_entity/attribute_assignment.rb +85 -0
- data/lib/active_entity/attribute_decorators.rb +90 -0
- data/lib/active_entity/attribute_methods.rb +330 -0
- data/lib/active_entity/attribute_methods/before_type_cast.rb +78 -0
- data/lib/active_entity/attribute_methods/primary_key.rb +98 -0
- data/lib/active_entity/attribute_methods/query.rb +35 -0
- data/lib/active_entity/attribute_methods/read.rb +47 -0
- data/lib/active_entity/attribute_methods/serialization.rb +90 -0
- data/lib/active_entity/attribute_methods/time_zone_conversion.rb +91 -0
- data/lib/active_entity/attribute_methods/write.rb +63 -0
- data/lib/active_entity/attributes.rb +165 -0
- data/lib/active_entity/base.rb +303 -0
- data/lib/active_entity/coders/json.rb +15 -0
- data/lib/active_entity/coders/yaml_column.rb +50 -0
- data/lib/active_entity/core.rb +281 -0
- data/lib/active_entity/define_callbacks.rb +17 -0
- data/lib/active_entity/enum.rb +234 -0
- data/lib/active_entity/errors.rb +80 -0
- data/lib/active_entity/gem_version.rb +17 -0
- data/lib/active_entity/inheritance.rb +278 -0
- data/lib/active_entity/integration.rb +78 -0
- data/lib/active_entity/locale/en.yml +45 -0
- data/lib/active_entity/model_schema.rb +115 -0
- data/lib/active_entity/nested_attributes.rb +592 -0
- data/lib/active_entity/readonly_attributes.rb +47 -0
- data/lib/active_entity/reflection.rb +441 -0
- data/lib/active_entity/serialization.rb +25 -0
- data/lib/active_entity/store.rb +242 -0
- data/lib/active_entity/translation.rb +24 -0
- data/lib/active_entity/type.rb +73 -0
- data/lib/active_entity/type/date.rb +9 -0
- data/lib/active_entity/type/date_time.rb +9 -0
- data/lib/active_entity/type/decimal_without_scale.rb +15 -0
- data/lib/active_entity/type/hash_lookup_type_map.rb +25 -0
- data/lib/active_entity/type/internal/timezone.rb +17 -0
- data/lib/active_entity/type/json.rb +30 -0
- data/lib/active_entity/type/modifiers/array.rb +72 -0
- data/lib/active_entity/type/registry.rb +92 -0
- data/lib/active_entity/type/serialized.rb +71 -0
- data/lib/active_entity/type/text.rb +11 -0
- data/lib/active_entity/type/time.rb +21 -0
- data/lib/active_entity/type/type_map.rb +62 -0
- data/lib/active_entity/type/unsigned_integer.rb +17 -0
- data/lib/active_entity/validate_embedded_association.rb +305 -0
- data/lib/active_entity/validations.rb +50 -0
- data/lib/active_entity/validations/absence.rb +25 -0
- data/lib/active_entity/validations/associated.rb +60 -0
- data/lib/active_entity/validations/length.rb +26 -0
- data/lib/active_entity/validations/presence.rb +68 -0
- data/lib/active_entity/validations/subset.rb +76 -0
- data/lib/active_entity/validations/uniqueness_in_embedding.rb +99 -0
- data/lib/active_entity/version.rb +10 -0
- data/lib/tasks/active_entity_tasks.rake +6 -0
- metadata +155 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 2e112f03678388841535d5384522961d51cc1d329ca4d1a89fdf7ce2ac7f60de
|
4
|
+
data.tar.gz: 4b28acea8267bdffe02ff95a4d17522e69bd81475301e7a4f721f9097ab79fb7
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: b0c1ba8f2a0b214a556442a32f01777622a556e3e3e07884c5e8cf7ddef8d1bf60daab6807942f04e62c936c19a271ce9db79bc91437f55b94f608992647923b
|
7
|
+
data.tar.gz: 9066e333b4dc888dd705726a44ce644438f9619ea0631507716c7a1e3553a32d99cc0deb44f8ea3ee716412cbb48688f69150aeeddc46327e57c9c9c8e1d7cbb
|
data/MIT-LICENSE
ADDED
@@ -0,0 +1,42 @@
|
|
1
|
+
Copyright (c) 2019 jasl
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
a copy of this software and associated documentation files (the
|
5
|
+
"Software"), to deal in the Software without restriction, including
|
6
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be
|
12
|
+
included in all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
21
|
+
|
22
|
+
|
23
|
+
Copyright (c) 2005-2019 David Heinemeier Hansson
|
24
|
+
|
25
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
26
|
+
a copy of this software and associated documentation files (the
|
27
|
+
"Software"), to deal in the Software without restriction, including
|
28
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
29
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
30
|
+
permit persons to whom the Software is furnished to do so, subject to
|
31
|
+
the following conditions:
|
32
|
+
|
33
|
+
The above copyright notice and this permission notice shall be
|
34
|
+
included in all copies or substantial portions of the Software.
|
35
|
+
|
36
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
37
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
38
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
39
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
40
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
41
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
42
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,145 @@
|
|
1
|
+
Active Entity
|
2
|
+
====
|
3
|
+
|
4
|
+
Active Entity is a Rails virtual model solution based on ActiveModel and it's design for Rails 6+.
|
5
|
+
|
6
|
+
Active Entity is forked from Active Record by removing all database relates codes, so it nearly no need to learn how to use.
|
7
|
+
|
8
|
+
## About Virtual Model
|
9
|
+
|
10
|
+
Virtual Model is the model not backed by a database table, usually used as "form model" or "presenter", because it's implement interfaces of Active Model, so you can use it like a normal Active Record model in your Rails app.
|
11
|
+
|
12
|
+
## Features
|
13
|
+
|
14
|
+
### Attribute declaration
|
15
|
+
|
16
|
+
```ruby
|
17
|
+
class Book < ActiveEntity::Base
|
18
|
+
attribute :title, :string
|
19
|
+
attribute :tags, :string, array: true, default: []
|
20
|
+
end
|
21
|
+
```
|
22
|
+
|
23
|
+
Same usage with Active Record, [Learn more](https://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html#method-i-attribute).
|
24
|
+
|
25
|
+
One enhancement is `array: true` that transform the attribute to an array that can accept multiple values.
|
26
|
+
|
27
|
+
### Nested attributes
|
28
|
+
|
29
|
+
Active Entity supports its own variant of nested attributes via the `embeds_one` / `embeds_many` macros. The intention is to be mostly compatible with ActiveRecord's `accepts_nested_attributes` functionality.
|
30
|
+
|
31
|
+
```ruby
|
32
|
+
class Holiday < ActiveRecord::Base
|
33
|
+
validates :date, presence: true
|
34
|
+
end
|
35
|
+
|
36
|
+
class HolidaysForm < ActiveType::Object
|
37
|
+
nests_many :holidays, reject_if: :all_blank
|
38
|
+
end
|
39
|
+
```
|
40
|
+
|
41
|
+
### Validations
|
42
|
+
|
43
|
+
```ruby
|
44
|
+
class Book < ActiveEntity::Base
|
45
|
+
attribute :title, :string
|
46
|
+
validates :title, presence: true
|
47
|
+
end
|
48
|
+
```
|
49
|
+
|
50
|
+
Supported Active Record validations:
|
51
|
+
|
52
|
+
- [acceptance](https://guides.rubyonrails.org/active_record_validations.html#acceptance)
|
53
|
+
- [confirmation](https://guides.rubyonrails.org/active_record_validations.html#confirmation)
|
54
|
+
- [exclusion](https://guides.rubyonrails.org/active_record_validations.html#exclusion)
|
55
|
+
- [format](https://guides.rubyonrails.org/active_record_validations.html#format)
|
56
|
+
- [inclusion](https://guides.rubyonrails.org/active_record_validations.html#inclusion)
|
57
|
+
- [length](https://guides.rubyonrails.org/active_record_validations.html#length)
|
58
|
+
- [numericality](https://guides.rubyonrails.org/active_record_validations.html#numericality)
|
59
|
+
- [presence](https://guides.rubyonrails.org/active_record_validations.html#presence)
|
60
|
+
- [absence](https://guides.rubyonrails.org/active_record_validations.html#absence)
|
61
|
+
|
62
|
+
[Common validation options](https://guides.rubyonrails.org/active_record_validations.html#common-validation-options) supported too.
|
63
|
+
|
64
|
+
#### `subset` validation
|
65
|
+
|
66
|
+
Because Active Entity supports array attribute, for some reason, we may want to test values of an array attribute are all included in a given set.
|
67
|
+
|
68
|
+
Active Entity provides `subset` validation to achieve that, it usage similar to `inclusion` or `exclusion`
|
69
|
+
|
70
|
+
```ruby
|
71
|
+
class Steak < ActiveEntity::Base
|
72
|
+
attribute :side_dishes, :string, array: true, default: []
|
73
|
+
validates :side_dishes, subset: { in: %w(chips mashed_potato salad)
|
74
|
+
end
|
75
|
+
```
|
76
|
+
|
77
|
+
#### `uniqueness_in_embedding` validation
|
78
|
+
|
79
|
+
Active Entity provides `uniqueness_in_embedding` validation to test duplicate nesting virtual record.
|
80
|
+
|
81
|
+
```ruby
|
82
|
+
class Category < ActiveEntity::Base
|
83
|
+
attribute :name
|
84
|
+
end
|
85
|
+
|
86
|
+
class Book < ActiveEntity::Base
|
87
|
+
embeds_many :categories
|
88
|
+
|
89
|
+
validates :categories, uniqueness_in_embedding: {key: :name}
|
90
|
+
end
|
91
|
+
```
|
92
|
+
|
93
|
+
Argument `key` is attribute name of nested model, it also supports multiple attributes by given an array.
|
94
|
+
|
95
|
+
### Others
|
96
|
+
|
97
|
+
These Active Record feature also available in Active Entity
|
98
|
+
|
99
|
+
- [`composed_of`](https://api.rubyonrails.org/classes/ActiveRecord/Aggregations/ClassMethods.html)
|
100
|
+
- [`enum`](https://api.rubyonrails.org/v5.2.2/classes/ActiveRecord/Enum.html) (You must declare the attribute which use for `enum` first)
|
101
|
+
- [`serializable_hash`](https://api.rubyonrails.org/classes/ActiveModel/Serialization.html#method-i-serializable_hash)
|
102
|
+
- [`serialize`](https://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Serialization/ClassMethods.html#method-i-serialize)
|
103
|
+
- [`store`](https://api.rubyonrails.org/classes/ActiveRecord/Store.html)
|
104
|
+
|
105
|
+
#### I18n
|
106
|
+
|
107
|
+
Same to [Active Record I18n](https://guides.rubyonrails.org/i18n.html#translations-for-active-record-models), the only different is the root of locale YAML is `active_entity` instead of `activerecord`
|
108
|
+
|
109
|
+
#### Read-only attributes
|
110
|
+
|
111
|
+
You can use `attr_readonly :title, :author` to prevent assign value to attribute after initialized.
|
112
|
+
|
113
|
+
You can use `enable_readonly!` and `disable_readonly!` to control the behavior.
|
114
|
+
|
115
|
+
**Important: It's no effect with embeds or array attributes !!!**
|
116
|
+
|
117
|
+
## Installation
|
118
|
+
|
119
|
+
Add this line to your application's Gemfile:
|
120
|
+
|
121
|
+
```ruby
|
122
|
+
gem 'activeentity'
|
123
|
+
```
|
124
|
+
|
125
|
+
And then execute:
|
126
|
+
```bash
|
127
|
+
$ bundle
|
128
|
+
```
|
129
|
+
|
130
|
+
Or install it yourself as:
|
131
|
+
```bash
|
132
|
+
$ gem install activeentity
|
133
|
+
```
|
134
|
+
|
135
|
+
## Contributing
|
136
|
+
|
137
|
+
- Fork the project.
|
138
|
+
- Make your feature addition or bug fix.
|
139
|
+
- Add tests for it. This is important so I don't break it in a future version unintentionally.
|
140
|
+
- Commit, do not mess with Rakefile or version (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
|
141
|
+
- Send me a pull request. Bonus points for topic branches.
|
142
|
+
|
143
|
+
## License
|
144
|
+
|
145
|
+
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
data/Rakefile
ADDED
@@ -0,0 +1,29 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
begin
|
4
|
+
require "bundler/setup"
|
5
|
+
rescue LoadError
|
6
|
+
puts "You must `gem install bundler` and `bundle install` to run rake tasks"
|
7
|
+
end
|
8
|
+
|
9
|
+
require "rdoc/task"
|
10
|
+
|
11
|
+
RDoc::Task.new(:rdoc) do |rdoc|
|
12
|
+
rdoc.rdoc_dir = "rdoc"
|
13
|
+
rdoc.title = "MyPlugin"
|
14
|
+
rdoc.options << "--line-numbers"
|
15
|
+
rdoc.rdoc_files.include("README.md")
|
16
|
+
rdoc.rdoc_files.include("lib/**/*.rb")
|
17
|
+
end
|
18
|
+
|
19
|
+
require "bundler/gem_tasks"
|
20
|
+
|
21
|
+
require "rake/testtask"
|
22
|
+
|
23
|
+
Rake::TestTask.new(:test) do |t|
|
24
|
+
t.libs << "test"
|
25
|
+
t.pattern = "test/**/*_test.rb"
|
26
|
+
t.verbose = false
|
27
|
+
end
|
28
|
+
|
29
|
+
task default: :test
|
@@ -0,0 +1,73 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
require "active_support"
|
4
|
+
require "active_support/rails"
|
5
|
+
require "yaml"
|
6
|
+
|
7
|
+
require "active_model"
|
8
|
+
require "active_model/attribute_set"
|
9
|
+
|
10
|
+
require "active_entity/version"
|
11
|
+
|
12
|
+
module ActiveEntity
|
13
|
+
extend ActiveSupport::Autoload
|
14
|
+
|
15
|
+
autoload :Base
|
16
|
+
autoload :Core
|
17
|
+
autoload :Enum
|
18
|
+
autoload :Inheritance
|
19
|
+
autoload :Integration
|
20
|
+
autoload :ModelSchema
|
21
|
+
autoload :NestedAttributes
|
22
|
+
autoload :ReadonlyAttributes
|
23
|
+
autoload :Reflection
|
24
|
+
autoload :Serialization
|
25
|
+
autoload :Store
|
26
|
+
autoload :Translation
|
27
|
+
autoload :Validations
|
28
|
+
|
29
|
+
eager_autoload do
|
30
|
+
autoload :ActiveEntityError, "active_entity/errors"
|
31
|
+
|
32
|
+
autoload :Aggregations
|
33
|
+
autoload :Associations
|
34
|
+
autoload :AttributeAssignment
|
35
|
+
autoload :AttributeMethods
|
36
|
+
autoload :ValidateEmbeddedAssociation
|
37
|
+
|
38
|
+
autoload :Type
|
39
|
+
end
|
40
|
+
|
41
|
+
module Coders
|
42
|
+
autoload :YAMLColumn, "active_entity/coders/yaml_column"
|
43
|
+
autoload :JSON, "active_entity/coders/json"
|
44
|
+
end
|
45
|
+
|
46
|
+
module AttributeMethods
|
47
|
+
extend ActiveSupport::Autoload
|
48
|
+
|
49
|
+
eager_autoload do
|
50
|
+
autoload :BeforeTypeCast
|
51
|
+
autoload :PrimaryKey
|
52
|
+
autoload :Query
|
53
|
+
autoload :Serialization
|
54
|
+
autoload :Read
|
55
|
+
autoload :TimeZoneConversion
|
56
|
+
autoload :Write
|
57
|
+
end
|
58
|
+
end
|
59
|
+
|
60
|
+
def self.eager_load!
|
61
|
+
super
|
62
|
+
|
63
|
+
ActiveEntity::Associations.eager_load!
|
64
|
+
ActiveEntity::AttributeMethods.eager_load!
|
65
|
+
end
|
66
|
+
end
|
67
|
+
|
68
|
+
ActiveSupport.on_load(:i18n) do
|
69
|
+
I18n.load_path << File.expand_path("active_entity/locale/en.yml", __dir__)
|
70
|
+
end
|
71
|
+
|
72
|
+
YAML.load_tags["!ruby/object:ActiveEntity::AttributeSet"] = "ActiveModel::AttributeSet"
|
73
|
+
YAML.load_tags["!ruby/object:ActiveEntity::LazyAttributeHash"] = "ActiveModel::LazyAttributeHash"
|
@@ -0,0 +1,276 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
module ActiveEntity
|
4
|
+
# See ActiveEntity::Aggregations::ClassMethods for documentation
|
5
|
+
module Aggregations
|
6
|
+
def initialize_dup(*) # :nodoc:
|
7
|
+
@aggregation_cache = {}
|
8
|
+
super
|
9
|
+
end
|
10
|
+
|
11
|
+
private
|
12
|
+
|
13
|
+
def init_internals
|
14
|
+
@aggregation_cache = {}
|
15
|
+
super
|
16
|
+
end
|
17
|
+
|
18
|
+
# Active Entity implements aggregation through a macro-like class method called #composed_of
|
19
|
+
# for representing attributes as value objects. It expresses relationships like "Account [is]
|
20
|
+
# composed of Money [among other things]" or "Person [is] composed of [an] address". Each call
|
21
|
+
# to the macro adds a description of how the value objects are created from the attributes of
|
22
|
+
# the entity object (when the entity is initialized either as a new object or from finding an
|
23
|
+
# existing object) and how it can be turned back into attributes (when the entity is saved to
|
24
|
+
# the database).
|
25
|
+
#
|
26
|
+
# class Customer < ActiveEntity::Base
|
27
|
+
# composed_of :balance, class_name: "Money", mapping: %w(balance amount)
|
28
|
+
# composed_of :address, mapping: [ %w(address_street street), %w(address_city city) ]
|
29
|
+
# end
|
30
|
+
#
|
31
|
+
# The customer class now has the following methods to manipulate the value objects:
|
32
|
+
# * <tt>Customer#balance, Customer#balance=(money)</tt>
|
33
|
+
# * <tt>Customer#address, Customer#address=(address)</tt>
|
34
|
+
#
|
35
|
+
# These methods will operate with value objects like the ones described below:
|
36
|
+
#
|
37
|
+
# class Money
|
38
|
+
# include Comparable
|
39
|
+
# attr_reader :amount, :currency
|
40
|
+
# EXCHANGE_RATES = { "USD_TO_DKK" => 6 }
|
41
|
+
#
|
42
|
+
# def initialize(amount, currency = "USD")
|
43
|
+
# @amount, @currency = amount, currency
|
44
|
+
# end
|
45
|
+
#
|
46
|
+
# def exchange_to(other_currency)
|
47
|
+
# exchanged_amount = (amount * EXCHANGE_RATES["#{currency}_TO_#{other_currency}"]).floor
|
48
|
+
# Money.new(exchanged_amount, other_currency)
|
49
|
+
# end
|
50
|
+
#
|
51
|
+
# def ==(other_money)
|
52
|
+
# amount == other_money.amount && currency == other_money.currency
|
53
|
+
# end
|
54
|
+
#
|
55
|
+
# def <=>(other_money)
|
56
|
+
# if currency == other_money.currency
|
57
|
+
# amount <=> other_money.amount
|
58
|
+
# else
|
59
|
+
# amount <=> other_money.exchange_to(currency).amount
|
60
|
+
# end
|
61
|
+
# end
|
62
|
+
# end
|
63
|
+
#
|
64
|
+
# class Address
|
65
|
+
# attr_reader :street, :city
|
66
|
+
# def initialize(street, city)
|
67
|
+
# @street, @city = street, city
|
68
|
+
# end
|
69
|
+
#
|
70
|
+
# def close_to?(other_address)
|
71
|
+
# city == other_address.city
|
72
|
+
# end
|
73
|
+
#
|
74
|
+
# def ==(other_address)
|
75
|
+
# city == other_address.city && street == other_address.street
|
76
|
+
# end
|
77
|
+
# end
|
78
|
+
#
|
79
|
+
# Now it's possible to access attributes from the database through the value objects instead. If
|
80
|
+
# you choose to name the composition the same as the attribute's name, it will be the only way to
|
81
|
+
# access that attribute. That's the case with our +balance+ attribute. You interact with the value
|
82
|
+
# objects just like you would with any other attribute:
|
83
|
+
#
|
84
|
+
# customer.balance = Money.new(20) # sets the Money value object and the attribute
|
85
|
+
# customer.balance # => Money value object
|
86
|
+
# customer.balance.exchange_to("DKK") # => Money.new(120, "DKK")
|
87
|
+
# customer.balance > Money.new(10) # => true
|
88
|
+
# customer.balance == Money.new(20) # => true
|
89
|
+
# customer.balance < Money.new(5) # => false
|
90
|
+
#
|
91
|
+
# Value objects can also be composed of multiple attributes, such as the case of Address. The order
|
92
|
+
# of the mappings will determine the order of the parameters.
|
93
|
+
#
|
94
|
+
# customer.address_street = "Hyancintvej"
|
95
|
+
# customer.address_city = "Copenhagen"
|
96
|
+
# customer.address # => Address.new("Hyancintvej", "Copenhagen")
|
97
|
+
#
|
98
|
+
# customer.address = Address.new("May Street", "Chicago")
|
99
|
+
# customer.address_street # => "May Street"
|
100
|
+
# customer.address_city # => "Chicago"
|
101
|
+
#
|
102
|
+
# == Writing value objects
|
103
|
+
#
|
104
|
+
# Value objects are immutable and interchangeable objects that represent a given value, such as
|
105
|
+
# a Money object representing $5. Two Money objects both representing $5 should be equal (through
|
106
|
+
# methods such as <tt>==</tt> and <tt><=></tt> from Comparable if ranking makes sense). This is
|
107
|
+
# unlike entity objects where equality is determined by identity. An entity class such as Customer can
|
108
|
+
# easily have two different objects that both have an address on Hyancintvej. Entity identity is
|
109
|
+
# determined by object or relational unique identifiers (such as primary keys). Normal
|
110
|
+
# ActiveEntity::Base classes are entity objects.
|
111
|
+
#
|
112
|
+
# It's also important to treat the value objects as immutable. Don't allow the Money object to have
|
113
|
+
# its amount changed after creation. Create a new Money object with the new value instead. The
|
114
|
+
# <tt>Money#exchange_to</tt> method is an example of this. It returns a new value object instead of changing
|
115
|
+
# its own values. Active Entity won't persist value objects that have been changed through means
|
116
|
+
# other than the writer method.
|
117
|
+
#
|
118
|
+
# The immutable requirement is enforced by Active Entity by freezing any object assigned as a value
|
119
|
+
# object. Attempting to change it afterwards will result in a +RuntimeError+.
|
120
|
+
#
|
121
|
+
# Read more about value objects on http://c2.com/cgi/wiki?ValueObject and on the dangers of not
|
122
|
+
# keeping value objects immutable on http://c2.com/cgi/wiki?ValueObjectsShouldBeImmutable
|
123
|
+
#
|
124
|
+
# == Custom constructors and converters
|
125
|
+
#
|
126
|
+
# By default value objects are initialized by calling the <tt>new</tt> constructor of the value
|
127
|
+
# class passing each of the mapped attributes, in the order specified by the <tt>:mapping</tt>
|
128
|
+
# option, as arguments. If the value class doesn't support this convention then #composed_of allows
|
129
|
+
# a custom constructor to be specified.
|
130
|
+
#
|
131
|
+
# When a new value is assigned to the value object, the default assumption is that the new value
|
132
|
+
# is an instance of the value class. Specifying a custom converter allows the new value to be automatically
|
133
|
+
# converted to an instance of value class if necessary.
|
134
|
+
#
|
135
|
+
# For example, the +NetworkResource+ model has +network_address+ and +cidr_range+ attributes that should be
|
136
|
+
# aggregated using the +NetAddr::CIDR+ value class (http://www.rubydoc.info/gems/netaddr/1.5.0/NetAddr/CIDR).
|
137
|
+
# The constructor for the value class is called +create+ and it expects a CIDR address string as a parameter.
|
138
|
+
# New values can be assigned to the value object using either another +NetAddr::CIDR+ object, a string
|
139
|
+
# or an array. The <tt>:constructor</tt> and <tt>:converter</tt> options can be used to meet
|
140
|
+
# these requirements:
|
141
|
+
#
|
142
|
+
# class NetworkResource < ActiveEntity::Base
|
143
|
+
# composed_of :cidr,
|
144
|
+
# class_name: 'NetAddr::CIDR',
|
145
|
+
# mapping: [ %w(network_address network), %w(cidr_range bits) ],
|
146
|
+
# allow_nil: true,
|
147
|
+
# constructor: Proc.new { |network_address, cidr_range| NetAddr::CIDR.create("#{network_address}/#{cidr_range}") },
|
148
|
+
# converter: Proc.new { |value| NetAddr::CIDR.create(value.is_a?(Array) ? value.join('/') : value) }
|
149
|
+
# end
|
150
|
+
#
|
151
|
+
# # This calls the :constructor
|
152
|
+
# network_resource = NetworkResource.new(network_address: '192.168.0.1', cidr_range: 24)
|
153
|
+
#
|
154
|
+
# # These assignments will both use the :converter
|
155
|
+
# network_resource.cidr = [ '192.168.2.1', 8 ]
|
156
|
+
# network_resource.cidr = '192.168.0.1/24'
|
157
|
+
#
|
158
|
+
# # This assignment won't use the :converter as the value is already an instance of the value class
|
159
|
+
# network_resource.cidr = NetAddr::CIDR.create('192.168.2.1/8')
|
160
|
+
#
|
161
|
+
# # Saving and then reloading will use the :constructor on reload
|
162
|
+
# network_resource.save
|
163
|
+
# network_resource.reload
|
164
|
+
#
|
165
|
+
# == Finding records by a value object
|
166
|
+
#
|
167
|
+
# Once a #composed_of relationship is specified for a model, records can be loaded from the database
|
168
|
+
# by specifying an instance of the value object in the conditions hash. The following example
|
169
|
+
# finds all customers with +address_street+ equal to "May Street" and +address_city+ equal to "Chicago":
|
170
|
+
#
|
171
|
+
# Customer.where(address: Address.new("May Street", "Chicago"))
|
172
|
+
#
|
173
|
+
module ClassMethods
|
174
|
+
# Adds reader and writer methods for manipulating a value object:
|
175
|
+
# <tt>composed_of :address</tt> adds <tt>address</tt> and <tt>address=(new_address)</tt> methods.
|
176
|
+
#
|
177
|
+
# Options are:
|
178
|
+
# * <tt>:class_name</tt> - Specifies the class name of the association. Use it only if that name
|
179
|
+
# can't be inferred from the part id. So <tt>composed_of :address</tt> will by default be linked
|
180
|
+
# to the Address class, but if the real class name is +CompanyAddress+, you'll have to specify it
|
181
|
+
# with this option.
|
182
|
+
# * <tt>:mapping</tt> - Specifies the mapping of entity attributes to attributes of the value
|
183
|
+
# object. Each mapping is represented as an array where the first item is the name of the
|
184
|
+
# entity attribute and the second item is the name of the attribute in the value object. The
|
185
|
+
# order in which mappings are defined determines the order in which attributes are sent to the
|
186
|
+
# value class constructor.
|
187
|
+
# * <tt>:allow_nil</tt> - Specifies that the value object will not be instantiated when all mapped
|
188
|
+
# attributes are +nil+. Setting the value object to +nil+ has the effect of writing +nil+ to all
|
189
|
+
# mapped attributes.
|
190
|
+
# This defaults to +false+.
|
191
|
+
# * <tt>:constructor</tt> - A symbol specifying the name of the constructor method or a Proc that
|
192
|
+
# is called to initialize the value object. The constructor is passed all of the mapped attributes,
|
193
|
+
# in the order that they are defined in the <tt>:mapping option</tt>, as arguments and uses them
|
194
|
+
# to instantiate a <tt>:class_name</tt> object.
|
195
|
+
# The default is <tt>:new</tt>.
|
196
|
+
# * <tt>:converter</tt> - A symbol specifying the name of a class method of <tt>:class_name</tt>
|
197
|
+
# or a Proc that is called when a new value is assigned to the value object. The converter is
|
198
|
+
# passed the single value that is used in the assignment and is only called if the new value is
|
199
|
+
# not an instance of <tt>:class_name</tt>. If <tt>:allow_nil</tt> is set to true, the converter
|
200
|
+
# can return +nil+ to skip the assignment.
|
201
|
+
#
|
202
|
+
# Option examples:
|
203
|
+
# composed_of :temperature, mapping: %w(reading celsius)
|
204
|
+
# composed_of :balance, class_name: "Money", mapping: %w(balance amount)
|
205
|
+
# composed_of :address, mapping: [ %w(address_street street), %w(address_city city) ]
|
206
|
+
# composed_of :gps_location
|
207
|
+
# composed_of :gps_location, allow_nil: true
|
208
|
+
# composed_of :ip_address,
|
209
|
+
# class_name: 'IPAddr',
|
210
|
+
# mapping: %w(ip to_i),
|
211
|
+
# constructor: Proc.new { |ip| IPAddr.new(ip, Socket::AF_INET) },
|
212
|
+
# converter: Proc.new { |ip| ip.is_a?(Integer) ? IPAddr.new(ip, Socket::AF_INET) : IPAddr.new(ip.to_s) }
|
213
|
+
#
|
214
|
+
def composed_of(part_id, options = {})
|
215
|
+
options.assert_valid_keys(:class_name, :mapping, :allow_nil, :constructor, :converter)
|
216
|
+
|
217
|
+
unless self < Aggregations
|
218
|
+
include Aggregations
|
219
|
+
end
|
220
|
+
|
221
|
+
name = part_id.id2name
|
222
|
+
class_name = options[:class_name] || name.camelize
|
223
|
+
mapping = options[:mapping] || [ name, name ]
|
224
|
+
mapping = [ mapping ] unless mapping.first.is_a?(Array)
|
225
|
+
allow_nil = options[:allow_nil] || false
|
226
|
+
constructor = options[:constructor] || :new
|
227
|
+
converter = options[:converter]
|
228
|
+
|
229
|
+
reader_method(name, class_name, mapping, allow_nil, constructor)
|
230
|
+
writer_method(name, class_name, mapping, allow_nil, converter)
|
231
|
+
|
232
|
+
reflection = ActiveEntity::Reflection.create(:composed_of, part_id, nil, options, self)
|
233
|
+
Reflection.add_aggregate_reflection self, part_id, reflection
|
234
|
+
end
|
235
|
+
|
236
|
+
private
|
237
|
+
def reader_method(name, class_name, mapping, allow_nil, constructor)
|
238
|
+
define_method(name) do
|
239
|
+
if @aggregation_cache[name].nil? && (!allow_nil || mapping.any? { |key, _| !_read_attribute(key).nil? })
|
240
|
+
attrs = mapping.collect { |key, _| _read_attribute(key) }
|
241
|
+
object = constructor.respond_to?(:call) ?
|
242
|
+
constructor.call(*attrs) :
|
243
|
+
class_name.constantize.send(constructor, *attrs)
|
244
|
+
@aggregation_cache[name] = object
|
245
|
+
end
|
246
|
+
@aggregation_cache[name]
|
247
|
+
end
|
248
|
+
end
|
249
|
+
|
250
|
+
def writer_method(name, class_name, mapping, allow_nil, converter)
|
251
|
+
define_method("#{name}=") do |part|
|
252
|
+
klass = class_name.constantize
|
253
|
+
|
254
|
+
unless part.is_a?(klass) || converter.nil? || part.nil?
|
255
|
+
part = converter.respond_to?(:call) ? converter.call(part) : klass.send(converter, part)
|
256
|
+
end
|
257
|
+
|
258
|
+
hash_from_multiparameter_assignment = part.is_a?(Hash) &&
|
259
|
+
part.each_key.all? { |k| k.is_a?(Integer) }
|
260
|
+
if hash_from_multiparameter_assignment
|
261
|
+
raise ArgumentError unless part.size == part.each_key.max
|
262
|
+
part = klass.new(*part.sort.map(&:last))
|
263
|
+
end
|
264
|
+
|
265
|
+
if part.nil? && allow_nil
|
266
|
+
mapping.each { |key, _| self[key] = nil }
|
267
|
+
@aggregation_cache[name] = nil
|
268
|
+
else
|
269
|
+
mapping.each { |key, value| self[key] = part.send(value) }
|
270
|
+
@aggregation_cache[name] = part.freeze
|
271
|
+
end
|
272
|
+
end
|
273
|
+
end
|
274
|
+
end
|
275
|
+
end
|
276
|
+
end
|