Class: Updater::ORM::Base

Inherits:

Object

• Object
• Updater::ORM::Base

Defined in:

lib/updater/orm/orm.rb

Overview

This is the root class for ORM inplimentations. It provides some very basicfunctionality that may be useful for implimenting actuall ORM’s but cannot itself be run or instantiated. The documentation for this class also serves as the cannonical reference for the ORM API.

for purposes of this documentation instances of a class inheriting form this class will be refered to as ‘jobs.’

In addation to the methods listed below, it MUST provide accessors for the 12 fields below. Most ORMs will add these when the fields are setup

Fields

These fields with thier getters and setters (except id which is read only) are expected to be implimented in every ORM implimention. Other fields may be implimented as well, but clients SHOULD NOT depend on or manipulate them. ORM will need to impliment some persistant way to lock records, and should do so in such a way as the name of the worker can be tracked, and jobs cleared for that worker should it crach if the underlying datastore allows.

id: a unique value asigned to each job. For purposes of the API it is a black box which should be paseed to the ClassMethods#get method to retrieve the job. If the ORM uses a different name for this value such as _id or key, a reader method must be implimented as id.

time [Integer]: This is the time in seconds at which the job should be run. It is always in reference to Updater::Update.time (by default Time). This value will be nil for chained methods.

target [Class]: The class of the target for this job. The API spesifies that it must be a Ruby class currently in scope in both the workers’ and clients’ frames of reference. (see configuration documentation for how to achieve this.) The writer must accept an actual class, which it may store in the datastore as a string (by calling to_s on it). The reader method must return the actual class by if ecessary calling Object.const_get(str) with the stored value.

finder [String]: A method to call on the Target in orderto get the target instance. The API limits its length to no more then 50 charactors. If the class itself is the target, this value will either not be set or set to nil. The reader should MUST return nil in this case.

finder_args [Array]: A possibly complex array of valuse that will be paseed to the finder method in order to retrieve the target instance. The API spesifies that the array and all subelements must impliment the #to_yaml and #to_json method in addation to being Marshalable. If the class itself is the target, this value will either not be set or set to nil. The reader should MUST return nil in this case.

method [String]: The method to be sent to the target instance. The API limits this value to 50 charictars. It MAY NOT be nil or empty.

method_args [Array]: A possibly complex array of values to pass to the spesified method of the target instance. It must be marshalable. The ORM layer is responcible to Marshal.dump and Marshal.load these values.

name [String]: If the ORM impliments the for method, then it MUST store a name which the API spesifies SHOULD be unique per target. The ORM SHOULD NOT enforce this restriction, but MAY assume it. ORM’s that do not impliment for must none the less have a #name= method that returns the value passed to it (as is normal with setter methods) and must not raise an error when a hash of values includes name. It must also respond to the name method with nil. When inplimented, name may be no longer then 255 characters.

persistant [Boolean]: if this value is set to true a worker will not call destroy after running the job. If it is nil or not set it may be assumed to be false, and ORM may return nil instead of false in this case.

Chained Jobs

Chained Jobs are run after a job and allow for various function to take place such as logging and error handleing. There are three(3) categories for chaining :failure, :success, and :ensure. The ORM must impliment a getter and setter for each as described below. This version does not inpliment it, but ORMs should be be designed in such a way that :prior and :instead chains can be added in future version of this API.

Getters:

getters should return an array of structures (Struct or equivelent) representing the chained jobs for this job. The structure should have three(3) members and MAY be read-only.

caller: An instance of the ORM class for the job in question (i.e. self)

target: An instance of the ORM class for the chained job

params: a Hash or other object that will be substituted for the special value ‘__params__’ when calling the target job.

The object returned may have other methods and functionality. Clients SHOULD NOT antisipate or use these methods.

Setters:

setters must accept five(5) differnt types of input. Except as described below setters are NOT distructive, that is job.failure=logme adds logme to the list of failure jobs and does not remove jobs that may have previously been chained. Clients should call save after using the setter to write the changes to disk

ORM or Updater::Update: Add this job to the chain, with no parameters. Updater::Update#orm will give the job.

Array<ORM or Updater::Update>: Add each job in the array to the chain

Hash(<ORM or Updater::Update>, params): Add the keys to the chain with the valuse as params. Clients should note that it is not possible to add multiple calls to the same job using this method.

nil: remove all jobs from this chain. Clients Note, that this is the only way to remove a previously added job from a chain.

Constant Summary

FINDER =

Every ORM should set this constant to a symbol that matches the most obvious method used to retrive a known instance. :get or :find are likely candidates.

nil

ID =

every ORM should set this to a method when called on an object producted by that ORM will give a value that can be passed to the FINDER method to retrieve the object from the datastore. :id, _id, or :key are likely candidates

nil

Instance Method Summary

• #destroy ⇒ Object

  Remove this job from the datastore.

• #lock(worker) ⇒ Object

  Workers will call this method on a job before running it to insure that in the case of multiple workers hiting the same queue only one will run the job.

• #save ⇒ Object

  write any changes made to the job back to the datastore.

Instance Method Details

#destroy ⇒ Object

Remove this job from the datastore.

# File 'lib/updater/orm/orm.rb', line 137

def destroy
  NotImplementedError
end

#lock(worker) ⇒ Object

Workers will call this method on a job before running it to insure that in the case of multiple workers hiting the same queue only one will run the job. The worker MUST pass itself to Lock, and the implimentation MAY use the name of the worker to identify who has locked this job.

If a worker is successfully able to lock this job, or has already locked the Job, this method MUST return a true value. If a lock was unsuccessful, it MUST return the value false, and MAY use the ‘say’ method of the suplied worker to explain why a lock could not be aquired.

# File 'lib/updater/orm/orm.rb', line 127

def lock(worker)
  NotImplementedError
end

#save ⇒ Object

write any changes made to the job back to the datastore.

# File 'lib/updater/orm/orm.rb', line 132

def save
  NotImplementedError
end