Name

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

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:

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:

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:

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:

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:

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:

Side Effects: NONE.

Notes: If the Bric::Util::Job object has been instantiated via the new() constructor and has not yet been saved, 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:

Side Effects: NONE.

Notes: NONE.

$self = $job->set_priority($priority)

Sets the server type name.

Throws:

Side Effects: NONE.

Notes: NONE.

my $name = $job->get_name

Returns the name of the Bric::Util::Job object.

Throws:

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:

Side Effects: NONE.

Notes: NONE.

$self = $st->set_user_id($user_id)

Sets the server type user_id.

Throws:

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:

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:

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:

Side Effects: NONE.

Notes: NONE.

my $tries = $foo->get_tries

Returns the number of times the job attempted to be executed.

Throws:

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:

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:

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:

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:

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:

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:

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:

Side Effects: NONE.

Notes: NONE.

$self = $job->has_failed

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

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $job->cancel

Markes this job for cancellation. Call save() to delete it from the database.

Throws:

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:

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:

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.

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:

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:

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:

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