orchestrated 0.0.1 → 0.0.2

data/README.markdown

@@ -1,11 +1,11 @@
 Orchestrated
 ============
 
-The [delayed_job](https://github.com/collectiveidea/delayed_job) Ruby Gem provides a job queuing system for Ruby. It implements an elegant API for delaying execution of any object method. Not only is the execution of the method (message delivery) delayed in time, it is potentially shifted in space. By shifting in space, i.e. running in a separate virtual machine, possibly on a separate computer, multiple CPUs can be brought to bear on a computing problem.
+The [delayed_job](https://github.com/collectiveidea/delayed_job) Ruby Gem provides a job queuing system for Ruby. It implements an elegant API for delaying execution of any object method. Not only is the execution of the method (message delivery) delayed in time, it is potentially shifted in space too. By shifting in space, i.e. running in a separate virtual machine, possibly on a separate computer, multiple CPUs can be brought to bear on a computing problem.
 
-By breaking up otherwise serial execution into multiple queued jobs, a program can be made more scalable. Processing of (distributed) queues has a long and successful history in data processing for this reason.
+By breaking up otherwise serial execution into multiple queued jobs, a program can be made more scalable. This sort of distributed queue-processing architecture has a long and successful history in data processing.
 
-Queuing works well for simple tasks. By simple I mean, the task can be done all at once, in one piece. It has no dependencies on other tasks. This works well for performing a file upload task in the background (to avoid tying up a Ruby virtual machine process/thread). More complex (compound) multi-part tasks, however, do not fit this model. Examples of complex (compound) tasks include:
+Queuing works well for simple tasks. By simple we mean, the task can be done all at once, in one piece. It has no dependencies on other tasks. This works well for performing a file upload task in the background (to avoid tying up a Ruby virtual machine process/thread). More complex (compound) multi-part tasks, however, do not fit this model. Examples of complex (compound) tasks include:
 
 1. pipelined (multi-step) generation of complex PDF documents
 2. extract/transfer/load (ETL) jobs that may load thousands of database records
@@ -27,6 +27,13 @@ Or install it yourself as:
 
     $ gem install orchestrated
 
+Now generate the database migration:
+
+    $ rails g orchestrated:active_record
+    $ rake db:migrate
+
+If you do not already have [delayed_job](https://github.com/collectiveidea/delayed_job) set up, you'll need to do that as well.
+
 The API
 -------
 
@@ -53,14 +60,20 @@ Declaring ```acts_as_orchestrated``` on your class gives it two methods:
 * ```orchestrated```—call this to specify your workflow prerequisite, and designate a workflow step
 * ```orchestration```—call this in the context of a workflow step (execution) to access orchestration (and prerequisite) context
 
-After that you can orchestrate any method on such a class e.g.
+After that you can orchestrate any method on such a class. Let's say you needed to download files from a remote system (a slow process), transform each one, and then load it into your system. Imagine you had had a Downloader class that knew how to download and an Xform class that knew how to transform the downloaded file and load it into your system. You might write an orchestration like this:
 
 ```ruby
-gen = StatementGenerator.new
-gen.orchestrated( orchestrated.generate(stmt_id) ).render(stmt_id)
+xform = Xform.new
+xform.orchestrated(
+  xform.orchestrated(
+    Downloader.new.orchestrated.download(
+      :from=>'http://foo.bar.com/customer_fred', :to=>'fred_file'
+    )
+  ).transform('fred_file', 'fred_file_processed')
+).load('fred_file_processed')
 ```
 
-The next time you process a delayed job, the :generate message will be delivered. The time after that, the :render message will be delivered.
+The next time you process a delayed job, the :download message will be delivered to a Downloader. After the download is complete, the next time a delayed job is processed, the :transform message will be delivered to an Xform object.
 
 What happened there? The pattern is:
 
@@ -68,7 +81,7 @@ What happened there? The pattern is:
 2. call orchestrated on it: this returns an "orchestration"
 3. send a message to the orchestration (returned in the second step)
 
-Now the messages you can send in (3) are limited to the messages that your object can respond to. The message will be "remembered" by the framework and "replayed" (on a new instance of your object) somewhere on the network (later).
+Now the messages you can send in (3) are limited to the messages that your object can respond to. The message will be remembered by the framework and "replayed" (on a new instance of your object) somewhere on the network (later).
 
 Not accidentally, this is similar to the way [delayed_job](https://github.com/collectiveidea/delayed_job)'s delay method works. Under the covers, orchestrated is conspiring with [delayed_job](https://github.com/collectiveidea/delayed_job) when it comes time to actually execute a workflow step. Before that time though, orchestrated keeps track of everything.
 

data/Rakefile

@@ -1 +1,4 @@
 require "bundler/gem_tasks"
+# state_machine gem's Rake tasks aren't set up properly for use outside
+# of Rails projects, hence the .. below
+require 'state_machine/../tasks/state_machine'

data/lib/generators/orchestrated/active_record_generator.rb

@@ -0,0 +1,17 @@
+# borrowed from delayed_job_active_record, and modified…
+require 'rails/generators/migration'
+require 'rails/generators/active_record/migration'
+
+# Extend the DelayedJobGenerator so that it creates an AR migration
+module Orchestrated
+  class ActiveRecordGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    extend ActiveRecord::Generators::Migration
+
+    self.source_paths << File.join(File.dirname(__FILE__), 'templates')
+
+    def create_migration_file
+      migration_template 'migration.rb', 'db/migrate/create_orchestrated.rb'
+    end
+  end
+end

data/lib/generators/orchestrated/templates/migration.rb

@@ -0,0 +1,29 @@
+class CreateOrchestrated < ActiveRecord::Migration
+  def self.up
+    create_table :orchestrations do |table|
+      table.string     :state
+      table.text       :handler
+      table.references :prerequisite
+      table.references :delayed_job, :polymorphic => true
+      table.timestamps
+    end
+    create_table :completion_expressions do |table|
+      table.string     :type
+      # only one kind of completion expression needs this
+      # (OrchestrationCompletion) but I didn't want to put
+      # it in a separate table because it would really contort
+      # the Rails model
+      table.references :orchestration
+    end
+    create_table :composited_completions do |table|
+      table.references :composite_completion
+      table.references :completion_expression
+    end
+  end
+
+  def self.down
+    drop_table :composited_completions
+    drop_table :completion_expressions
+    drop_table :orchestrations
+  end
+end

data/lib/orchestrated/version.rb

@@ -1,3 +1,3 @@
 module Orchestrated
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/orchestrated.gemspec

@@ -18,16 +18,19 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_runtime_dependency     'delayed_job_active_record', '~> 0.3'
-  gem.add_runtime_dependency     'activerecord', ['>= 3']
+  gem.add_runtime_dependency     'delayed_job_active_record', '>= 0.3'
+  gem.add_runtime_dependency     'activerecord', ['~> 3']
   gem.add_runtime_dependency     'state_machine', ['>= 1']
 
-  gem.add_development_dependency 'rake'
-  gem.add_development_dependency 'rails', ['>= 3'] # for rspec-rails
-  gem.add_development_dependency 'rspec-rails'
+  gem.add_development_dependency 'rake', ['>= 10']
+  gem.add_development_dependency 'rails', ['~> 3'] # for rspec-rails
+  gem.add_development_dependency 'rspec-rails', ['>= 2.12']
   # I couldn't get rspecs transactional fixtures setting to do savepoints
   # in this project (which is not _really_ a Rails app). database_cleaner
   # claims it'll help us clean up the database so let's try it!
-  gem.add_development_dependency 'database_cleaner'
-  gem.add_development_dependency 'sqlite3'
+  gem.add_development_dependency 'database_cleaner', ['>= 0.9']
+  gem.add_development_dependency 'sqlite3', ['>= 1.3.6']
+  gem.add_development_dependency 'debugger'
+  # The state_machine:draw rake task needs this
+  gem.add_development_dependency 'ruby-graphviz', ['>= 0.9.0']
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orchestrated
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -16,7 +16,7 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.3'
   type: :runtime
@@ -24,7 +24,7 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.3'
 - !ruby/object:Gem::Dependency
@@ -32,7 +32,7 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3'
   type: :runtime
@@ -40,7 +40,7 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3'
 - !ruby/object:Gem::Dependency
@@ -66,7 +66,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -74,13 +74,13 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3'
   type: :development
@@ -88,7 +88,7 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3'
 - !ruby/object:Gem::Dependency
@@ -98,7 +98,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -106,7 +106,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.12'
 - !ruby/object:Gem::Dependency
   name: database_cleaner
   requirement: !ruby/object:Gem::Requirement
@@ -114,7 +114,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -122,9 +122,25 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+- !ruby/object:Gem::Dependency
+  name: debugger
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -139,6 +155,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-graphviz
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.9.0
 description: a workflow orchestration framework running on delayed_job and active_record
 email:
 - bill@paydici.com
@@ -152,6 +184,8 @@ files:
 - Orchestrated::Orchestration_state.png
 - README.markdown
 - Rakefile
+- lib/generators/orchestrated/active_record_generator.rb
+- lib/generators/orchestrated/templates/migration.rb
 - lib/orchestrated.rb
 - lib/orchestrated/base.rb
 - lib/orchestrated/completion.rb