apollo 1.0.0
Sign up to get free protection for your applications and to get access to all the features.
- data/.gitignore +21 -0
- data/LICENSE +201 -0
- data/MIT-LICENSE +20 -0
- data/README.markdown +437 -0
- data/Rakefile +48 -0
- data/VERSION +1 -0
- data/apollo.gemspec +60 -0
- data/lib/apollo.rb +263 -0
- data/lib/apollo/active_record_instance_methods.rb +24 -0
- data/lib/apollo/event.rb +9 -0
- data/lib/apollo/specification.rb +43 -0
- data/lib/apollo/state.rb +17 -0
- data/test/couchtiny_example.rb +46 -0
- data/test/main_test.rb +418 -0
- data/test/readme_example.rb +37 -0
- data/test/test_helper.rb +16 -0
- data/test/without_active_record_test.rb +54 -0
- metadata +83 -0
data/.gitignore
ADDED
data/LICENSE
ADDED
@@ -0,0 +1,201 @@
|
|
1
|
+
Apache License
|
2
|
+
Version 2.0, January 2004
|
3
|
+
http://www.apache.org/licenses/
|
4
|
+
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
6
|
+
|
7
|
+
1. Definitions.
|
8
|
+
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
11
|
+
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
13
|
+
the copyright owner that is granting the License.
|
14
|
+
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
16
|
+
other entities that control, are controlled by, or are under common
|
17
|
+
control with that entity. For the purposes of this definition,
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
19
|
+
direction or management of such entity, whether by contract or
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
22
|
+
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
24
|
+
exercising permissions granted by this License.
|
25
|
+
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
27
|
+
including but not limited to software source code, documentation
|
28
|
+
source, and configuration files.
|
29
|
+
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
31
|
+
transformation or translation of a Source form, including but
|
32
|
+
not limited to compiled object code, generated documentation,
|
33
|
+
and conversions to other media types.
|
34
|
+
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
36
|
+
Object form, made available under the License, as indicated by a
|
37
|
+
copyright notice that is included in or attached to the work
|
38
|
+
(an example is provided in the Appendix below).
|
39
|
+
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
46
|
+
the Work and Derivative Works thereof.
|
47
|
+
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
49
|
+
the original version of the Work and any modifications or additions
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
61
|
+
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
64
|
+
subsequently incorporated within the Work.
|
65
|
+
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
72
|
+
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
78
|
+
where such license applies only to those patent claims licensable
|
79
|
+
by such Contributor that are necessarily infringed by their
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
82
|
+
institute patent litigation against any entity (including a
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
85
|
+
or contributory patent infringement, then any patent licenses
|
86
|
+
granted to You under this License for that Work shall terminate
|
87
|
+
as of the date such litigation is filed.
|
88
|
+
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
91
|
+
modifications, and in Source or Object form, provided that You
|
92
|
+
meet the following conditions:
|
93
|
+
|
94
|
+
(a) You must give any other recipients of the Work or
|
95
|
+
Derivative Works a copy of this License; and
|
96
|
+
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
98
|
+
stating that You changed the files; and
|
99
|
+
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
102
|
+
attribution notices from the Source form of the Work,
|
103
|
+
excluding those notices that do not pertain to any part of
|
104
|
+
the Derivative Works; and
|
105
|
+
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
108
|
+
include a readable copy of the attribution notices contained
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
111
|
+
of the following places: within a NOTICE text file distributed
|
112
|
+
as part of the Derivative Works; within the Source form or
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
114
|
+
within a display generated by the Derivative Works, if and
|
115
|
+
wherever such third-party notices normally appear. The contents
|
116
|
+
of the NOTICE file are for informational purposes only and
|
117
|
+
do not modify the License. You may add Your own attribution
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
120
|
+
that such additional attribution notices cannot be construed
|
121
|
+
as modifying the License.
|
122
|
+
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
124
|
+
may provide additional or different license terms and conditions
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
128
|
+
the conditions stated in this License.
|
129
|
+
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
133
|
+
this License, without any additional terms or conditions.
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
135
|
+
the terms of any separate license agreement you may have executed
|
136
|
+
with Licensor regarding such Contributions.
|
137
|
+
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
140
|
+
except as required for reasonable and customary use in describing the
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
142
|
+
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
152
|
+
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
158
|
+
incidental, or consequential damages of any character arising as a
|
159
|
+
result of this License or out of the use or inability to use the
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
162
|
+
other commercial damages or losses), even if such Contributor
|
163
|
+
has been advised of the possibility of such damages.
|
164
|
+
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
168
|
+
or other liability obligations and/or rights consistent with this
|
169
|
+
License. However, in accepting such obligations, You may act only
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
174
|
+
of your accepting any such warranty or additional liability.
|
175
|
+
|
176
|
+
END OF TERMS AND CONDITIONS
|
177
|
+
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
179
|
+
|
180
|
+
To apply the Apache License to your work, attach the following
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
182
|
+
replaced with your own identifying information. (Don't include
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
184
|
+
comment syntax for the file format. We also recommend that a
|
185
|
+
file or class name and description of purpose be included on the
|
186
|
+
same "printed page" as the copyright notice for easier
|
187
|
+
identification within third-party archives.
|
188
|
+
|
189
|
+
Copyright [yyyy] [name of copyright owner]
|
190
|
+
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
192
|
+
you may not use this file except in compliance with the License.
|
193
|
+
You may obtain a copy of the License at
|
194
|
+
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
196
|
+
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
200
|
+
See the License for the specific language governing permissions and
|
201
|
+
limitations under the License.
|
data/MIT-LICENSE
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
Copyright (c) 2008-2009 Vodafone
|
2
|
+
Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
|
3
|
+
|
4
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
5
|
+
of this software and associated documentation files (the "Software"), to deal
|
6
|
+
in the Software without restriction, including without limitation the rights
|
7
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
8
|
+
copies of the Software, and to permit persons to whom the Software is
|
9
|
+
furnished to do so, subject to the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be included in
|
12
|
+
all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
15
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
16
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
17
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
18
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
19
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
20
|
+
THE SOFTWARE.
|
data/README.markdown
ADDED
@@ -0,0 +1,437 @@
|
|
1
|
+
What is apollo?
|
2
|
+
===============
|
3
|
+
|
4
|
+
> In Greek and Roman mythology, Apollo (in Greek, Ἀπόλλων—Apóllōn or Ἀπέλλων—Apellōn),
|
5
|
+
> is one of the most important and diverse of the Olympian deities. The ideal of the
|
6
|
+
> kouros (a beardless youth), Apollo has been variously recognized as a god of light
|
7
|
+
> and the sun; truth and prophecy; archery; medicine, healing and plague; music,
|
8
|
+
> poetry, and the arts; and more. Apollo is the son of Zeus and Leto, and has a twin
|
9
|
+
> sister, the chaste huntress Artemis. [Wikipedia: Dionysus (2010/04/23)](http://en.wikipedia.org/wiki/Apollo)
|
10
|
+
|
11
|
+
Apollo is an fork of workflow.
|
12
|
+
|
13
|
+
What is workflow?
|
14
|
+
-----------------
|
15
|
+
|
16
|
+
Workflow is a finite-state-machine-inspired API for modeling and
|
17
|
+
interacting with what we tend to refer to as 'apollo'.
|
18
|
+
|
19
|
+
A lot of business modeling tends to involve apollo-like concepts, and
|
20
|
+
the aim of this library is to make the expression of these concepts as
|
21
|
+
clear as possible, using similar terminology as found in state machine
|
22
|
+
theory.
|
23
|
+
|
24
|
+
So, a workflow has a state. It can only be in one state at a time. When
|
25
|
+
a workflow changes state, we call that a transition. Transitions occur
|
26
|
+
on an event, so events cause transitions to occur. Additionally, when an
|
27
|
+
event fires, other arbitrary code can be executed, we call those actions.
|
28
|
+
So any given state has a bunch of events, any event in a state causes a
|
29
|
+
transition to another state and potentially causes code to be executed
|
30
|
+
(an action). We can hook into states when they are entered, and exited
|
31
|
+
from, and we can cause transitions to fail (guards), and we can hook in
|
32
|
+
to every transition that occurs ever for whatever reason we can come up
|
33
|
+
with.
|
34
|
+
|
35
|
+
Now, all that's a mouthful, but we'll demonstrate the API bit by bit
|
36
|
+
with a real-ish world example.
|
37
|
+
|
38
|
+
Let's say we're modeling article submission from journalists. An article
|
39
|
+
is written, then submitted. When it's submitted, it's awaiting review.
|
40
|
+
Someone reviews the article, and then either accepts or rejects it.
|
41
|
+
Here is the expression of this apollo using the API:
|
42
|
+
|
43
|
+
class Article
|
44
|
+
include Apollo
|
45
|
+
apollo do
|
46
|
+
state :new do
|
47
|
+
event :submit, :to => :awaiting_review
|
48
|
+
end
|
49
|
+
state :awaiting_review do
|
50
|
+
event :review, :to => :being_reviewed
|
51
|
+
end
|
52
|
+
state :being_reviewed do
|
53
|
+
event :accept, :to => :accepted
|
54
|
+
event :reject, :to => :rejected
|
55
|
+
end
|
56
|
+
state :accepted
|
57
|
+
state :rejected
|
58
|
+
end
|
59
|
+
end
|
60
|
+
|
61
|
+
Nice, isn't it!
|
62
|
+
|
63
|
+
Let's create an article instance and check in which state it is:
|
64
|
+
|
65
|
+
article = Article.new
|
66
|
+
article.accepted? # => false
|
67
|
+
article.new? # => true
|
68
|
+
|
69
|
+
You can also access the whole `current_state` object including the list
|
70
|
+
of possible events and other meta information:
|
71
|
+
|
72
|
+
article.current_state
|
73
|
+
=> #<Apollo::State:0x7f1e3d6731f0 @events={
|
74
|
+
:submit=>#<Apollo::Event:0x7f1e3d6730d8 @action=nil,
|
75
|
+
@to=:awaiting_review, @name=:submit, @meta={}>},
|
76
|
+
name:new, meta{}
|
77
|
+
|
78
|
+
Now we can call the submit event, which transitions to the
|
79
|
+
<tt>:awaiting_review</tt> state:
|
80
|
+
|
81
|
+
article.submit!
|
82
|
+
article.awaiting_review? # => true
|
83
|
+
|
84
|
+
Events are actually instance methods on a apollo, and depending on the
|
85
|
+
state you're in, you'll have a different set of events used to
|
86
|
+
transition to other states.
|
87
|
+
|
88
|
+
|
89
|
+
Installation
|
90
|
+
------------
|
91
|
+
|
92
|
+
gem install apollo
|
93
|
+
|
94
|
+
Alternatively you can just download the lib/apollo.rb and put it in
|
95
|
+
the lib folder of your Rails or Ruby application.
|
96
|
+
|
97
|
+
|
98
|
+
Examples
|
99
|
+
--------
|
100
|
+
|
101
|
+
After installation or downloading of the library you can easily try out
|
102
|
+
all the example code from this README in irb.
|
103
|
+
|
104
|
+
$ irb
|
105
|
+
require 'rubygems'
|
106
|
+
require 'apollo'
|
107
|
+
|
108
|
+
Now just copy and paste the source code from the beginning of this README
|
109
|
+
file snippet by snippet and observe the output.
|
110
|
+
|
111
|
+
|
112
|
+
Transition event handler
|
113
|
+
------------------------
|
114
|
+
|
115
|
+
The best way is to use convention over configuration and to define a
|
116
|
+
method with the same name as the event. Then it is automatically invoked
|
117
|
+
when event is raised. For the Article apollo defined earlier it would
|
118
|
+
be:
|
119
|
+
|
120
|
+
class Article
|
121
|
+
def reject
|
122
|
+
puts 'sending email to the author explaining the reason...'
|
123
|
+
end
|
124
|
+
end
|
125
|
+
|
126
|
+
`article.review!; article.reject!` will cause a state transition, persist the new state
|
127
|
+
(if integrated with ActiveRecord) and invoke this user defined reject
|
128
|
+
method.
|
129
|
+
|
130
|
+
You can also define event handler accepting/requiring additional
|
131
|
+
arguments:
|
132
|
+
|
133
|
+
class Article
|
134
|
+
def review(reviewer = '')
|
135
|
+
puts "[#{reviewer}] is now reviewing the article"
|
136
|
+
end
|
137
|
+
end
|
138
|
+
|
139
|
+
article2 = Article.new
|
140
|
+
article2.submit!
|
141
|
+
article2.review!('Homer Simpson') # => [Homer Simpson] is now reviewing the article
|
142
|
+
|
143
|
+
|
144
|
+
### The old, deprecated way
|
145
|
+
|
146
|
+
The old way, using a block is still supported but deprecated:
|
147
|
+
|
148
|
+
event :review, :to => :being_reviewed do |reviewer|
|
149
|
+
# store the reviewer
|
150
|
+
end
|
151
|
+
|
152
|
+
We've noticed, that mixing the list of events and states with the blocks
|
153
|
+
invoked for particular transitions leads to a bumpy and poorly readable code
|
154
|
+
due to a deep nesting. We tried (and dismissed) lambdas for this. Eventually
|
155
|
+
we decided to invoke an optional user defined callback method with the same
|
156
|
+
name as the event (convention over configuration) as explained before.
|
157
|
+
|
158
|
+
|
159
|
+
Integration with ActiveRecord
|
160
|
+
-----------------------------
|
161
|
+
|
162
|
+
Apollo library can handle the state persistence fully automatically. You
|
163
|
+
only need to define a string field on the table called `apollo_state`
|
164
|
+
and include the apollo mixin in your model class as usual:
|
165
|
+
|
166
|
+
class Order < ActiveRecord::Base
|
167
|
+
include Apollo
|
168
|
+
apollo do
|
169
|
+
# list states and transitions here
|
170
|
+
end
|
171
|
+
end
|
172
|
+
|
173
|
+
On a database record loading all the state check methods e.g.
|
174
|
+
`article.state`, `article.awaiting_review?` are immediately available.
|
175
|
+
For new records or if the apollo_state field is not set the state
|
176
|
+
defaults to the first state declared in the apollo specification. In
|
177
|
+
our example it is `:new`, so `Article.new.new?` returns true and
|
178
|
+
`Article.new.approved?` returns false.
|
179
|
+
|
180
|
+
At the end of a successful state transition like `article.approve!` the
|
181
|
+
new state is immediately saved in the database.
|
182
|
+
|
183
|
+
You can change this behaviour by overriding `persist_apollo_state`
|
184
|
+
method.
|
185
|
+
|
186
|
+
|
187
|
+
### Custom apollo database column
|
188
|
+
|
189
|
+
[meuble](http://imeuble.info/) contributed a solution for using
|
190
|
+
custom persistence column easily, e.g. for a legacy database schema:
|
191
|
+
|
192
|
+
class LegacyOrder < ActiveRecord::Base
|
193
|
+
include Apollo
|
194
|
+
|
195
|
+
apollo_column :foo_bar # use this legacy database column for
|
196
|
+
# persistence
|
197
|
+
end
|
198
|
+
|
199
|
+
|
200
|
+
|
201
|
+
### Single table inheritance
|
202
|
+
|
203
|
+
Single table inheritance is also supported. Descendant classes can either
|
204
|
+
inherit the apollo definition from the parent or override with its own
|
205
|
+
definition.
|
206
|
+
|
207
|
+
Custom apollo state persistence
|
208
|
+
---------------------------------
|
209
|
+
|
210
|
+
If you do not use a relational database and ActiveRecord, you can still
|
211
|
+
integrate the apollo very easily. To implement persistence you just
|
212
|
+
need to override `load_apollo_state` and
|
213
|
+
`persist_apollo_state(new_value)` methods. Lets see an example for
|
214
|
+
using CouchDB, a document oriented database.
|
215
|
+
|
216
|
+
Integration with CouchDB
|
217
|
+
------------------------
|
218
|
+
|
219
|
+
We are using the compact [couchtiny library](http://github.com/geekq/couchtiny)
|
220
|
+
here. But the implementation would look similar for the popular
|
221
|
+
couchrest library.
|
222
|
+
|
223
|
+
require 'couchtiny'
|
224
|
+
require 'couchtiny/document'
|
225
|
+
require 'apollo'
|
226
|
+
|
227
|
+
class User < CouchTiny::Document
|
228
|
+
include Apollo
|
229
|
+
apollo do
|
230
|
+
state :submitted do
|
231
|
+
event :activate_via_link, :to => :proved_email
|
232
|
+
end
|
233
|
+
state :proved_email
|
234
|
+
end
|
235
|
+
|
236
|
+
def load_apollo_state
|
237
|
+
self[:apollo_state]
|
238
|
+
end
|
239
|
+
|
240
|
+
def persist_apollo_state(new_value)
|
241
|
+
self[:apollo_state] = new_value
|
242
|
+
save!
|
243
|
+
end
|
244
|
+
end
|
245
|
+
|
246
|
+
Please also have a look at
|
247
|
+
[the full source code](http://github.com/geekq/apollo/blob/master/test/couchtiny_example.rb).
|
248
|
+
|
249
|
+
Accessing your apollo specification
|
250
|
+
-------------------------------------
|
251
|
+
|
252
|
+
You can easily reflect on apollo specification programmatically - for
|
253
|
+
the whole class or for the current object. Examples:
|
254
|
+
|
255
|
+
article2.current_state.events # lists possible events from here
|
256
|
+
article2.current_state.events[:reject].to # => :rejected
|
257
|
+
|
258
|
+
Article.apollo_spec.states.keys
|
259
|
+
#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
|
260
|
+
|
261
|
+
# list all events for all states
|
262
|
+
Article.apollo_spec.states.values.collect &:events
|
263
|
+
|
264
|
+
|
265
|
+
You can also store and later retrieve additional meta data for every
|
266
|
+
state and every event:
|
267
|
+
|
268
|
+
class MyProcess
|
269
|
+
include Apollo
|
270
|
+
apollo do
|
271
|
+
state :main, :meta => {:importance => 8}
|
272
|
+
state :supplemental, :meta => {:importance => 1}
|
273
|
+
end
|
274
|
+
end
|
275
|
+
puts MyProcess.apollo_spec.states[:supplemental].meta[:importance] # => 1
|
276
|
+
|
277
|
+
The apollo library itself uses this feature to tweak the graphical
|
278
|
+
representation of the apollo. See below.
|
279
|
+
|
280
|
+
|
281
|
+
Advanced transition hooks
|
282
|
+
-------------------------
|
283
|
+
|
284
|
+
### on_entry/on_exit
|
285
|
+
|
286
|
+
We already had a look at the declaring callbacks for particular apollo
|
287
|
+
events. If you would like to react to all transitions to/from the same state
|
288
|
+
in the same way you can use the on_entry/on_exit hooks. You can either define it
|
289
|
+
with a block inside the apollo definition or through naming
|
290
|
+
convention, e.g. for the state :pending just define the method
|
291
|
+
`on_pending_exit(new_state, event, *args)` somewhere in your class.
|
292
|
+
|
293
|
+
### on_transition
|
294
|
+
|
295
|
+
If you want to be informed about everything happening everywhere, e.g. for
|
296
|
+
logging then you can use the universal `on_transition` hook:
|
297
|
+
|
298
|
+
apollo do
|
299
|
+
state :one do
|
300
|
+
event :increment, :to => :two
|
301
|
+
end
|
302
|
+
state :two
|
303
|
+
on_transition do |from, to, triggering_event, *event_args|
|
304
|
+
Log.info "#{from} -> #{to}"
|
305
|
+
end
|
306
|
+
end
|
307
|
+
|
308
|
+
|
309
|
+
### Guards
|
310
|
+
|
311
|
+
If you want to halt the transition conditionally, you can just raise an
|
312
|
+
exception. There is a helper called `halt!`, which raises the
|
313
|
+
Apollo::TransitionHalted exception. You can provide an additional
|
314
|
+
`halted_because` parameter.
|
315
|
+
|
316
|
+
def reject(reason)
|
317
|
+
halt! 'We do not reject articles unless the reason is important' \
|
318
|
+
unless reason =~ /important/i
|
319
|
+
end
|
320
|
+
|
321
|
+
The traditional `halt` (without the exclamation mark) is still supported
|
322
|
+
too. This just prevents the state change without raising an
|
323
|
+
exception.
|
324
|
+
|
325
|
+
### Hook order
|
326
|
+
|
327
|
+
The whole event sequence is as follows:
|
328
|
+
|
329
|
+
* event specific action
|
330
|
+
* on_transition (if action did not halt)
|
331
|
+
* on_exit
|
332
|
+
* PERSIST WORKFLOW STATE, i.e. transition
|
333
|
+
* on_entry
|
334
|
+
|
335
|
+
|
336
|
+
Documenting with diagrams
|
337
|
+
-------------------------
|
338
|
+
|
339
|
+
You can generate a graphical representation of your apollo for
|
340
|
+
documentation purposes. S. Apollo::create_apollo_diagram.
|
341
|
+
|
342
|
+
|
343
|
+
Earlier versions
|
344
|
+
----------------
|
345
|
+
|
346
|
+
The `apollo` library was originally written by Ryan Allen.
|
347
|
+
|
348
|
+
The version 0.3 was almost completely (including ActiveRecord
|
349
|
+
integration, API for accessing apollo specification,
|
350
|
+
method_missing free implementation) rewritten by Vladimir Dobriakov
|
351
|
+
keeping the original apollo DSL spirit.
|
352
|
+
|
353
|
+
|
354
|
+
Migration from the original Ryan's library
|
355
|
+
------------------------------------------
|
356
|
+
|
357
|
+
Credit: Michael (rockrep)
|
358
|
+
|
359
|
+
Accessing apollo specification
|
360
|
+
|
361
|
+
my_instance.apollo # old
|
362
|
+
MyClass.apollo_spec # new
|
363
|
+
|
364
|
+
Accessing states, events, meta, e.g.
|
365
|
+
|
366
|
+
my_instance.apollo.states(:some_state).events(:some_event).meta[:some_meta_tag] # old
|
367
|
+
MyClass.apollo_spec.states[:some_state].events[:some_event].meta[:some_meta_tag] # new
|
368
|
+
|
369
|
+
Causing state transitions
|
370
|
+
|
371
|
+
my_instance.apollo.my_event # old
|
372
|
+
my_instance.my_event! # new
|
373
|
+
|
374
|
+
when using both a block and a callback method for an event, the block executes prior to the callback
|
375
|
+
|
376
|
+
|
377
|
+
Changelog
|
378
|
+
---------
|
379
|
+
|
380
|
+
### New in the version 0.4.0
|
381
|
+
|
382
|
+
* completely rewritten the documentation to match my branch. Every
|
383
|
+
described feature is backed up by an automated test.
|
384
|
+
|
385
|
+
### New in the version 0.3.0
|
386
|
+
|
387
|
+
Intermixing of transition graph definition (states, transitions)
|
388
|
+
on the one side and implementation of the actions on the other side
|
389
|
+
for a bigger state machine can introduce clutter.
|
390
|
+
|
391
|
+
To reduce this clutter it is now possible to use state entry- and
|
392
|
+
exit- hooks defined through a naming convention. For example, if there
|
393
|
+
is a state :pending, then instead of using a
|
394
|
+
block:
|
395
|
+
|
396
|
+
state :pending do
|
397
|
+
on_entry do
|
398
|
+
# your implementation here
|
399
|
+
end
|
400
|
+
end
|
401
|
+
|
402
|
+
you can hook in by defining method
|
403
|
+
|
404
|
+
def on_pending_exit(new_state, event, *args)
|
405
|
+
# your implementation here
|
406
|
+
end
|
407
|
+
|
408
|
+
anywhere in your class. You can also use a simpler function signature
|
409
|
+
like `def on_pending_exit(*args)` if your are not interested in
|
410
|
+
arguments. Please note: `def on_pending_exit()` with an empty list
|
411
|
+
would not work.
|
412
|
+
|
413
|
+
If both a function with a name according to naming convention and the
|
414
|
+
on_entry/on_exit block are given, then only on_entry/on_exit block is used.
|
415
|
+
|
416
|
+
|
417
|
+
Support
|
418
|
+
-------
|
419
|
+
|
420
|
+
### Reporting bugs
|
421
|
+
|
422
|
+
http://github.com/geekq/apollo/issues
|
423
|
+
|
424
|
+
|
425
|
+
About
|
426
|
+
-----
|
427
|
+
|
428
|
+
Author: Vladimir Dobriakov, http://www.innoq.com/blog/vd, http://blog.geekq.net/
|
429
|
+
|
430
|
+
Copyright (c) 2008-2009 Vodafone
|
431
|
+
|
432
|
+
Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
|
433
|
+
|
434
|
+
Based on the work of Ryan Allen and Scott Barron
|
435
|
+
|
436
|
+
Licensed under MIT license, see the MIT-LICENSE file.
|
437
|
+
|