Bric::Util::Job(3p)   User Contributed Perl Documentation  Bric::Util::Job(3p)



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

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-03-18 01:26:34 +0100 (Sat, 18 Mar 2006) $

SYNOPSIS
         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;

DESCRIPTION
       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".

INTERFACE
   Constructors
       my $job = Bric::Util::Job->new($init)
           Instantiates a Bric::Util::Job object. An anonymous hash of initial
           values may be passed. The supported initial value keys are:

           o   name - A name for the job. Required.

           o   user_id - The ID of the user scheduling the job.

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

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

           o   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.

           o   type - The type of job. Pass a true value for an expire job and
               a false value (or no "type" 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:

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

           o   Bric::set() - Problems setting fields.

           o   Bric::_get() - Problems retrieving fields.

           o   Cannot add resources to a completed job.

           o   Cannot add resources to a executing job.

           Side Effects: NONE.

           Notes: NONE.

       my $job = Bric::Util::Job->lookup({ id => $id })
           Looks up and instantiates a new Bric::Util::Job object based on the
           Bric::Util::Job object ID passed. If $id is not found in the
           database, lookup() returns undef.

           Throws:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: If $id is found, populates the new Bric::Util::Job
           object with data from the database before returning it.

           Notes: NONE.

       my (@jobs || $jobs_aref) = Bric::Util::Job->list($params)
           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:

           id  Job ID. May use "ANY" for a list of possible values.

           name
               The name of the jobs. May use typical SQL wildcard '%'. Note
               that the query is case-insensitve. May use "ANY" for a list of
               possible values.

           user_id
               The ID of the user who scheduled the jobs. May use "ANY" for a
               list of possible values.

           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'. May also use "ANY" for a list of possible values.

           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'. May also use "ANY" for a list of possible values.

           resource_id
               A Bric::Dist::Resource object ID. May use "ANY" for a list of
               possible values.

           server_type_id
               A Bric::Dist::ServerType object ID. May use "ANY" for a list of
               possible values.

           story_id
               A story ID. May use "ANY" for a list of possible values.

           story_instance_id
               A story instance ID. May use "ANY" for a list of possible
               values.

           media_id
               A media ID. May use "ANY" for a list of possible values.

           media_instance_id
               A media instance ID. May use "ANY" for a list of possible
               values.

           grp_id
               A Bric::Util::Grp::Job object ID. May use "ANY" for a list of
               possible values.

           failed
               A boolean indicating whether or not a job is considered a
               failure. May use "ANY" for a list of possible values.

           executing
               A boolean indicating whether some process is running
               "execute_me" on this job.

           type
               A boolean indicating the type of the job. Pass true for an
               expiring job and false for a publishing job.

           Throws:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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.

   Destructors
       $job->DESTROY
           Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

   Public Class Methods
       my (@job_ids || $job_ids_aref) = Bric::Util::Job->list_ids($params)
           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: NONE.

           Notes: NONE.

       $meths = Bric::Util::Job->my_meths
       (@meths || $meths_aref) = Bric::Util::Job->my_meths(TRUE)
       my (@meths || $meths_aref) = Bric::Util::Job->my_meths(0, TRUE)
           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 "id", 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.

   Public Instance Methods
       my $id = $job->get_id
           Returns the ID of the Bric::Util::Job object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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 "save"d, the object will not
           yet have an ID, so this method call will return undef.

       my $priority = $job->get_priority
           Returns the priority of the Bric::Util::Job object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->set_priority($priority)
           Sets the server type name.

           Throws:

           o   Priority must be between 1 and 5 inclusive

           Side Effects: NONE.

           Notes: NONE.

       my $name = $job->get_name
           Returns the name of the Bric::Util::Job object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       $self = $st->set_name($name)
           Sets the server type name.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       my $user_id = $job->get_user_id
           Returns the user_id of the Bric::Util::Job object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       $self = $st->set_user_id($user_id)
           Sets the server type user_id.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       my $sched_time = $job->get_sched_time($format)
           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:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to unpack date.

           o   Unable to format date.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->set_sched_time($sched_time)
           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:

           o   Cannot change scheduled time on completed job.

           o   Cannot change scheduled time on executing job.

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to unpack date.

           o   Unable to format date.

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

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

       my $comp_time = $job->get_comp_time($format)
           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:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to unpack date.

           o   Unable to format date.

           Side Effects: NONE.

           Notes: NONE.

       my $tries = $foo->get_tries
           Returns the number of times the job attempted to be executed.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       my (@resources || $resources_aref) = $job->get_resources
       my (@resources || $resources_aref) = $job->get_resources(@resource_ids)
           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:

           o   Bric::_get() - Problems retrieving fields.

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

           o   Bric::set() - Problems setting fields.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: NONE.

           Notes: NONE.

       $job = $job->add_resources(@resources)
           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:

           o   Bric::_get() - Problems retrieving fields.

           o   Cannot add resources to a completed job.

           o   Cannot add resources to a executing job.

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

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: Uses Bric::Util::Coll::Server internally.

       $self = $job->del_resources(@resources)
           Dissociates resources, represented as Bric::Dist::Resource objects,
           from the job.  call save() to save the dissociations to the
           database.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Cannot delete resources from a completed job.

           o   Cannot delete resources from a executing job.

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

           o   Bric::set() - Problems setting fields.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: NONE.

           Notes: NONE.

       my (@server_types || $server_types_aref) = $job->get_server_types
       my (@server_types || $server_types_aref) =
       $job->get_server_types(@server_type_ids)
           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:

           o   Bric::_get() - Problems retrieving fields.

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

           o   Bric::set() - Problems setting fields.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: NONE.

           Notes: NONE.

       $job = $job->add_server_types(@server_types)
           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:

           o   Bric::_get() - Problems retrieving fields.

           o   Cannot add server types to a completed job.

           o   Cannot add server types to a executing job.

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

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: Uses Bric::Util::Coll::Server internally.

       $self = $job->del_server_types(@server_types)
           Dissociates server types, represented as Bric::Dist::ServerType
           objects, from the job. call save() to save the dissociations to the
           database.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Cannot delete server types from a completed job.

           o   Cannot delete server types from a executing job.

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

           o   Bric::set() - Problems setting fields.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->is_executing
           Returns true ($self) if the job is executing (that is, in the
           process of being executed), and undef it is not.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->has_failed
           Returns true ($self) if the job threw an error on execution,
           returns false otherwise.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->cancel
           Markes this job for cancellation. Call save() to delete it from the
           database.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Cannot cancel completed job.

           o   Cannot cancel executing job.

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

           o   Bric::set() - Problems setting fields.

           o   Bric::_get() - Problems retrieving fields.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->reset
           Resets the job. If it had failed, the error message will be reset
           to "undef" and the "has_failed()" method will return false. Whether
           or not it has failed, the number of tries will be reset to 0.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Cannot reset completed job.

           o   Cannot reset executing job.

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

           o   Bric::set() - Problems setting fields.

           o   Bric::_get() - Problems retrieving fields.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->save
           Saves any changes to the Bric::Util::Job object. Returns $self on
           success and undef on failure.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

           o   Unable to select row.

           o   Incorrect number of args to _set.

           o   Bric::_set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->execute_me
           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.

           o   Cannot execute job before its scheduled time.

           o   Cannot execute job that has already been executed.

           o   Can't get a lock on job.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

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

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

       $self = $job->handle_error($msg)
           Concatinates the msg to the top of the error_message field.  After
           Bric::Config::DIST_ATTEMPTS it also marks the Job as having failed.

PRIVATE
   Private Class Methods
       NONE.

   Private Instance Methods
       $job = $job->_do_it
           This is an abstract method that must be implemented in subclasses.
           In subclasses, "_do_it()" carries out the tasks that constitute a
           job. Here in the base class, it throws an exception.

   Private Functions
       my $_aref = &$get_em( $pkg, $params )
       my $_ids_aref = &$get_em( $pkg, $params, 1 )
           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:

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: NONE.

           Notes: NONE.

       my $coll = $get_coll->($self, $class, $key)
           Returns the collection for this job. Pass in the $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:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

       my $bool = $check_priority->($priority)
           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.

       my $bool = $set_executing->($self, $value)
           Sets the executing column in the database, as well as the executing
           property in the job object. Used by "execute_me()".

           Throws:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

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

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

NOTES
       NONE.

AUTHORS
       David Wheeler <david@justatheory.com>

       Mark Jaroski <jaroskim@who.int>

SEE ALSO
       Bric, Bric::Dist::Resource, Bric::Dist::ServerType



perl v5.12.2                      2006-03-17               Bric::Util::Job(3p)
