Bric::Util::Job - Manages Bricolage distribution jobs.

$LastChangedRevision$

$LastChangedDate: 2005-06-02 13:04:43 -0700 (Thu, 02 Jun 2005) $

  use Bric::Util::Job;

  my $id = 1;
  my $format = "%D %T";

  # Constructors.
  my $job = Bric::Util::Job->new($init);
  $job = Bric::Util::Job->lookup({ id => $id });
  my @jobs = Bric::Util::Job->list($params);

  # Class Methods.
  my @job_ids = Bric::Util::Job->list_ids($params);

  # Instance Methods
  my $id = $job->get_id;

  my $type = $job->get_type;
  $job = $job->set_type($type);

  my $sched_time = $job->get_sched_time($format);
  $job = $job->set_sched_time($sched_time);
  my $comp_time = $job->get_comp_time($format);

  my @resources = $job->get_resources;
  my @resource_ids = $job->get_resource_ids;
  $job = $job->set_resource_ids(@resource_ids);

  my @server_types = $job->get_server_types;
  my @server_type_ids = $job->get_server_type_ids;
  $job = $job->set_server_type_ids(@server_type_ids);

  my $boolean = $job->get_failed;
  $job = $job->set_failed($boolean);

  my $err_msg = $job->get_error_message;

  my $boolean = $job->get_executing;

  # Save the job.
  $job = $job->save;

  # Cancel the job.
  $job = $job->cancel;

  # Execute the job.
  $job = $job->execute_me;

This class manages distribution jobs. A job is a list of things to be transformed by actions and moved out, all at a scheduled time. The idea is that Bricolage will schedule a job and then it will be executed at its scheduled times. There are two types of jobs, Deliver and Expire.

Instantiates a Bric::Util::Job object. An anonymous hash of initial values may be passed. The supported initial value keys are:

*

name - A name for the job. Required.

*

user_id - The ID of the user scheduling the job.

*

sched_time - The time at which to execute the job. If undef, the job will be executed immediately.

*

resources - An anonymous array of Bric::Dist::Resource objects representing the files and/or directories on which the job's actions will be executed.

*

server_types - An anonymous array of Bric::Dist::ServerType objects representing the types of servers for which the job must be executed. See Bric::Dist::ServerType for an interface for creating server types.

*

type - The type of job. Pass a true value for an expire job and a false value (or no CWtype parameter at all) for a distribution job. Either the resources, resource_names, or resource_ids anonymous array is must be passed in, as must either sever_types, server_type_names, or server_type_ids. Throws:

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields.

*

Bric::_get() - Problems retrieving fields.

*

Cannot add resources to a completed job.

*

Cannot add resources to a executing job. Side Effects: NONE. Notes: NONE. Looks up and instantiates a new Bric::Util::Job object based on the Bric::Util::Job object ID passed. If CW$id is not found in the database, lookup() returns undef. Throws:

*

Too many Bric::Util::Job objects found.

*

Unable to prepare SQL statement.

*

Unable to connect to database.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle. Side Effects: If CW$id is found, populates the new Bric::Util::Job object with data from the database before returning it. Notes: NONE. Returns a list or anonymous array of Bric::Util::Job objects based on the search parameters passed via an anonymous hash. The supported lookup keys are:

*

name - The name of the jobs. May use typical SQL wildcard '%'. Note that the query is case-insensitve.

*

user_id - The ID of the user who scheduled the jobs.

*

sched_time - May pass in as an anonymous array of two values, the first the minimum scheduled time, the second the maximum scheduled time. If the first array item is undefined, then the second will be considered the date that sched_time must be less than. If the second array item is undefined, then the first will be considered the date that sched_time must be greater than. If the value passed in is undefined, then the query will specify 'IS NULL'.

*

comp_time - May pass in as an anonymous array of two values, the first the minimum completion time, the second the maximum completion time. If the first array item is undefined, then the second will be considered the date that sched_time must be less than. If the second array item is undefined, then the first will be considered the date that sched_time must be greater than. If the value passed in is undefined, then the query will specify 'IS NULL'.

*

resource_id - A Bric::Dist::Resource object ID.

*

server_type_id - A Bric::Dist::ServerType object ID.

*

grp_id - A Bric::Util::Grp::Job object ID.

*

failed - A boolean indicating whether or not a job is considered a failure

*

executing - A boolean indicating whether some process is running CWexecute_me on this job Throws:

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle. Side Effects: Populates each Bric::Util::Job object with data from the database before returning them all. Notes: NONE.

$job->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY. Throws: NONE. Side Effects: NONE. Notes: NONE.

Returns a list or anonymous array of Bric::Util::Job object IDs based on the search criteria passed via an anonymous hash. The supported lookup keys are the same as those for list(). Throws:

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle. Side Effects: NONE. Notes: NONE.

$meths = Bric::Util::Job->my_meths

Returns an anonymous hash of introspection data for this object. If called with a true argument, it will return an ordered list or anonymous array of introspection data. If a second true argument is passed instead of a first, then a list or anonymous array of introspection data will be returned for properties that uniquely identify an object (excluding CWid, which is assumed). Each hash key is the name of a property or attribute of the object. The value for a hash key is another anonymous hash containing the following keys:

name

The name of the property or attribute. Is the same as the hash key when an anonymous hash is returned.

disp

The display name of the property or attribute.

get_meth

A reference to the method that will retrieve the value of the property or attribute.

get_args

An anonymous array of arguments to pass to a call to get_meth in order to retrieve the value of the property or attribute.

set_meth

A reference to the method that will set the value of the property or attribute.

set_args

An anonymous array of arguments to pass to a call to set_meth in order to set the value of the property or attribute.

type

The type of value the property or attribute contains. There are only three types:

short

date

blob

len

If the value is a 'short' value, this hash key contains the length of the field.

search

The property is searchable via the list() and list_ids() methods.

req

The property or attribute is required.

props

An anonymous hash of properties used to display the property or attribute. Possible keys include:

type

The display field type. Possible values are

text

textarea

password

hidden

radio

checkbox

select

length

The Length, in letters, to display a text or password field.

maxlength

The maximum length of the property or value - usually defined by the SQL DDL.

rows

The number of rows to format in a textarea field.

cols

The number of columns to format in a textarea field.

vals

An anonymous hash of key/value pairs reprsenting the values and display names to use in a select list. Throws: NONE. Side Effects: NONE. Notes: NONE.

Returns the ID of the Bric::Util::Job object. Throws:

*

Bad AUTOLOAD method format.

*

Cannot AUTOLOAD private methods.

*

Access denied: READ access for field 'id' required.

*

No AUTOLOAD method. Side Effects: NONE. Notes: If the Bric::Util::Job object has been instantiated via the new() constructor and has not yet been CWsaved, the object will not yet have an ID, so this method call will return undef. Returns the priority of the Bric::Util::Job object. Throws:

*

Bad AUTOLOAD method format.

*

Cannot AUTOLOAD private methods.

*

Access denied: READ access for field 'name' required.

*

No AUTOLOAD method. Side Effects: NONE. Notes: NONE. Sets the server type name. Throws:

*

Priority must be between 1 and 5 inclusive Side Effects: NONE. Notes: NONE. Returns the name of the Bric::Util::Job object. Throws:

*

Bad AUTOLOAD method format.

*

Cannot AUTOLOAD private methods.

*

Access denied: READ access for field 'name' required.

*

No AUTOLOAD method. Side Effects: NONE. Notes: NONE. Sets the server type name. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the user_id of the Bric::Util::Job object. Throws:

*

Bad AUTOLOAD method format.

*

Cannot AUTOLOAD private methods.

*

Access denied: READ access for field 'user_id' required.

*

No AUTOLOAD method. Side Effects: NONE. Notes: NONE. Sets the server type user_id. Throws:

*

Bad AUTOLOAD method format.

*

Cannot AUTOLOAD private methods.

*

Access denied: WRITE access for field 'user_id' required.

*

No AUTOLOAD method. Side Effects: NONE. Notes: NONE. Returns the time at which the job is scheduled to execute. Pass in a strftime format string to get the time back in that format. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Unable to unpack date.

*

Unable to format date. Side Effects: NONE. Notes: NONE. Sets the time at which the job is to be executed. This method will not set the scheduled time and will return undef if the job has already been completed. Throws:

*

Cannot change scheduled time on completed job.

*

Cannot change scheduled time on executing job.

*

Bric::_get() - Problems retrieving fields.

*

Unable to unpack date.

*

Unable to format date.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields. Side Effects: NONE. Notes: NONE. Returns the time at which the job was completed. Returns undef if the job has not yet been completed. Pass in a strftime format string to get the time back in that format. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Unable to unpack date.

*

Unable to format date. Side Effects: NONE. Notes: NONE. Returns the number of times the job attempted to be executed. Throws:

*

Bad AUTOLOAD method format.

*

Cannot AUTOLOAD private methods.

*

Access denied: READ access for field 'tries' required.

*

No AUTOLOAD method. Side Effects: NONE. Notes: NONE. Returns a list or anonymous array of the Bric::Dist::Resource objects that represent the directories and/or files on which this job acts. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields.

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle. Side Effects: NONE. Notes: NONE. Adds resources to this job. Call save() to save the relationship. Resources cannot be added to a job after the job has executed. Trying to add resources after a job has completed will throw an exception. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Cannot add resources to a completed job.

*

Cannot add resources to a executing job.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields. Side Effects: NONE. Notes: Uses Bric::Util::Coll::Server internally. Dissociates resources, represented as Bric::Dist::Resource objects, from the job. call save() to save the dissociations to the database. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Cannot delete resources from a completed job.

*

Cannot delete resources from a executing job.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields.

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle. Side Effects: NONE. Notes: NONE. Returns a list or anonymous array of the Bric::Dist::ServerType objects that represent the directories and/or files on which this job acts. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields.

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle. Side Effects: NONE. Notes: NONE. Adds server types to this job. Call save() to save the relationship. Server types cannot be added to a job after the job has executed. Trying to add server types after a job has completed will throw an exception. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Cannot add server types to a completed job.

*

Cannot add server types to a executing job.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields. Side Effects: NONE. Notes: Uses Bric::Util::Coll::Server internally. Dissociates server types, represented as Bric::Dist::ServerType objects, from the job. call save() to save the dissociations to the database. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Cannot delete server types from a completed job.

*

Cannot delete server types from a executing job.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields.

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle. Side Effects: NONE. Notes: NONE. Returns true ($self) if the job is executing (that is, in the process of being executed), and undef it is not. Throws:

*

Bric::_get() - Problems retrieving fields. Side Effects: NONE. Notes: NONE. Returns true ($self) if the job threw an error on execution, returns false otherwise. Throws:

*

Bric::_get() - Problems retrieving fields. Side Effects: NONE. Notes: NONE. Markes this job for cancellation. Call save() to delete it from the database. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Cannot cancel completed job.

*

Cannot cancel executing job.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields.

*

Bric::_get() - Problems retrieving fields. Side Effects: NONE. Notes: NONE. Saves any changes to the Bric::Util::Job object. Returns CW$self on success and undef on failure. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to execute SQL statement.

*

Unable to select row.

*

Incorrect number of args to _set.

*

Bric::_set() - Problems setting fields. Side Effects: NONE. Notes: NONE. Executes the job. This means the for each of the server types associated with this job, the list of actions will be performed on each file, hopefully culminating in the distribution of the resources to the servers associated with the server type. At the end of the process, a completion time will be saved to the database. Attempting to execute a job before its scheduled time will throw an exception. Throws: Quite a few exceptions can be thrown here. Check the do_it() methods on all Bric::Dist::Action subclasses, as well as the put_res() methods of the mover classes (e.g., Bric::Util::Trans::FS). Here are the exceptions thrown from withing this method itself.

*

Cannot execute job before its scheduled time.

*

Cannot execute job that has already been executed.

*

Can't get a lock on job.

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to execute SQL statement.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields. Side Effects: NONE. Notes: NONE. Concatinates the msg to the top of the error_message field. After Bric::Config::DIST_ATTEMPTS it also marks the Job as having failed.

NONE.

This is an abstract method that must be implemented in subclasses. In subclasses, CW_do_it() carries out the tasks that constitute a job. Here in the base class, it throws an exception.

Function used by lookup() and list() to return a list of Bric::Util::Job objects or, if called with an optional third argument, returns a listof Bric::Util::Job object IDs (used by list_ids()). Throws:

*

Unable to prepare SQL statement.

*

Unable to connect to database.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle. Side Effects: NONE. Notes: NONE. Returns the collection for this job. Pass in the CW$job object itself, the property key for storing the collection, and the name of the collection class. The collection is a Bric::Util::Coll object. See Bric::Util::Coll for interface details. Throws:

*

Bric::_get() - Problems retrieving fields.

*

Unable to prepare SQL statement.

*

Unable to connect to database.

*

Unable to select column into arrayref.

*

Unable to execute SQL statement.

*

Unable to bind to columns to statement handle.

*

Unable to fetch row from statement handle.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields. Side Effects: NONE. Notes: NONE. Checks a number to see if it is in the correct range for a priority setting (1 to 5, inclusive), and throws an error if it isn't. Sets the executing column in the database, as well as the executing property in the job object. Used by CWexecute_me(). Throws:

*

Unable to connect to database.

*

Unable to prepare SQL statement.

*

Unable to execute SQL statement.

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields. Side Effects: NONE. Notes: NONE.

NONE.

David Wheeler <david@wheeler.net>

Mark Jaroski <jaroskim@who.int>

Bric, Bric::Dist::Resource, Bric::Dist::ServerType