Bric::Util::Job(3)

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:

    *   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 "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:

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

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:

    *   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 $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:

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

  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:

    *   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
(@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:

    *   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 "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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

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

    Throws:

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

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

$self = $st->set_user_id($user_id)
    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.

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:

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

    *   Unable to unpack date.

    *   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:

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

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:

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

    *   Unable to unpack date.

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

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

$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:

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

$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:

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

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:

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

$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:

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

$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:

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

$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:

    *   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:

    *   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:

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

$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:

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

    *   Cannot reset completed job.

    *   Cannot reset executing job.

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

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

    *   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:

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

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

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

$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:

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

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:

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

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:

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

NOTES
NONE.

AUTHORS
David Wheeler <david@justatheory.com>

Mark Jaroski <jaroskim@who.int>

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