Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation for writing ruote participants

  • Loading branch information...
commit eb7cae70fc7df3e362501998c9e88b52de49c44c 1 parent 4cec49a
@kennethkalmer authored Kenneth Kalmer committed
Showing with 115 additions and 1 deletion.
  1. +2 −1  Manifest.txt
  2. +113 −0 RuoteParticipants.txt
View
3  Manifest.txt
@@ -6,6 +6,7 @@ Manifest.txt
PostInstall.txt
README.rdoc
Rakefile
+RuoteParticipants.txt
TODO.txt
app_generators/daemon_kit/USAGE
app_generators/daemon_kit/daemon_kit_generator.rb
@@ -68,7 +69,6 @@ daemon_generators/rspec/templates/tasks/rspec.rake
daemon_generators/ruote/USAGE
daemon_generators/ruote/ruote_generator.rb
daemon_generators/ruote/templates/config/amqp.yml
-daemon_generators/ruote/templates/config/ruote.yml
daemon_generators/ruote/templates/config/initializers/ruote.rb
daemon_generators/ruote/templates/config/ruote.yml
daemon_generators/ruote/templates/lib/sample.rb
@@ -91,6 +91,7 @@ lib/daemon_kit/em.rb
lib/daemon_kit/error_handlers/base.rb
lib/daemon_kit/error_handlers/hoptoad.rb
lib/daemon_kit/error_handlers/mail.rb
+lib/daemon_kit/exceptions.rb
lib/daemon_kit/initializer.rb
lib/daemon_kit/jabber.rb
lib/daemon_kit/nanite.rb
View
113 RuoteParticipants.txt
@@ -0,0 +1,113 @@
+= Writing remote ruote participants with daemon-kit
+
+daemon-kit is an ideal housing for remote ruote participants, providing a lot
+of convenience in terms of receiving and sending workitems, delegating work to
+pseudo-participant classes, handling configuration of the communication channel
+between ruote and the remote participant, and much more.
+
+== What is ruote?
+
+Ruote is a Ruby workflow engine. It is a powerful tool for defining, running and
+orchestrating business processes.
+
+* http://openwferu.rubyforge.org/
+* http://www.opensourcery.co.za/2009/03/04/ruote-in-20-minutes/
+* http://www.opensourcery.co.za/2009/07/06/driving-business-processes-in-ruby/
+
+== What are remote participants?
+
+Remote participants are participants that perform their work in a different
+Ruby processes from the one running the engine. This is useful in two cases,
+possibily many more, that involves autonomous participants.
+
+* Autonomous participants located on remote servers, driven by identity
+* Clustering autonomous participants to process workitems from a queue
+
+To learn more about the differences between local and remote participants
+please see http://openwferu.rubyforge.org/part.html
+
+Currently on the AMQP components are in place in daemon-kit, with XMPP coming
+soon.
+
+== Creating a remote participant with daemon-kit
+
+Generate your daemon using the 'ruote' generator:
+
+ $ daemon_kit partd -i ruote
+
+Make sure you have the JSON gem install, and the AMQP gem as well.
+
+== Configuring the daemon
+
+You need to review +config/ruote.yml+ to specify the AMQP queues that the daemon
+will subscribe to for receiving workitems. You'll also need to configure the
+AMQP gem be updating +config/amqp.yml+
+
+The generated daemon in +libexec/+ already defaults to using AMQP as a transport
+for workitems.
+
+== Writing pseudo-participants
+
+Pseudo-participants in daemon-kit are pure Ruby classes. Implement your classes
+in +lib/+ and require them from +lib/<daemon_name>.rb+.
+
+Register your classes as pseudo-participants by registering them in the daemon
+file in +libexec+, just as the Sample class is registered in the generated
+code. Your class will be instantiated upon registration, and will be re-used
+for every incoming workitem passed to it.
+
+All your public methods in the pseudo-participant classes should be accept
+a single parameter, which is a ruote workitem in pure Hash form.
+
+== Wiring up the remote participant in ruote
+
+See the complete code here: http://gist.github.com/144861
+
+A sample process definition might look something like this:
+
+ class QuoteProcess < OpenWFE::ProcessDefinition
+ sequence do
+ kit :command => '/sample/quote', :queue => 'work1'
+
+ console
+ end
+ end
+
++kit+ in the above process definition is registered with the ruote engine as an
+AMQPParticipant. The AMQPParticipant delivers workitems to the specified AMQP
+queue.
+
+Based on the values in +config/ruote.yml+, your daemon will be subscribed to
+those queues.
+
+The second part is delegating the workitem inside the daemon to the correct
+pseudo-participant. This is handled by the +:command+ parameter in the process
+definition. DaemonKit::Workitem looks at the command parameter of the incoming
+workitem, and then finds a registered pseudo-participant instance and calls the
+requested method on that class.
+
+The +:command+ parameter follows the following convention (stolen shamelessly
+from Nanite):
+
+ :command => '/class_name/method_name'
+
+When classes are registered, the name of the class is downcased and camel-case
+words are separated by underscores. Method names are not changed, but methods
+are required to be public.
+
+== Processing workitems and replying to the engine
+
+The methods called in the pseudo-participants receive a single parameter, a
+ruote workitem as a hash. The participant is then free to analyze the hash
+and perform the appropriate actions required. The return value of the method
+is discarded, and the workitem is returned back to the engine. If the method
+modified the workitem, these changes will be sent along as well.
+
+== Random other notes
+
+Apart from configuring the AMPQ client (or XMPP in future) and the ruote.yml
+file, daemon developers don't need to worry about anything related to receiving
+workitems or sending replies.
+
+Our aim is to allow you to swap between participants on both sides of the
+transport without changing any of your code.
Please sign in to comment.
Something went wrong with that request. Please try again.