NAME
VERSION
DATE
SYNOPSIS
DESCRIPTION
INTERFACE
PRIVATE
NOTES
AUTHOR
SEE ALSO

NAME

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

VERSION

$Revision: 1.18.4.3 $

DATE

$Date: 2003/08/14 22:04:07 $

SYNOPSIS

use Bric::Dist::Job;

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

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

# Class Methods.
my @job_ids = Bric::Dist::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_timeget_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);

# 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::Dist::Job->new($init)

Instantiates a Bric::Dist::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::ServerTypeBric::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.

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 pending job.

Side Effects: NONE.

Notes: NONE.

my $job = Bric::Dist::Job->lookup({ id => $id })

Looks up and instantiates a new Bric::Dist::Job object based on the Bric::Dist::Job object ID passed. If $id is not found in the database, lookup() returns undef.

Throws:

Too many Bric::Dist::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::Dist::Job object with data from the database before returning it.

Notes: NONE.

my (@jobs || $jobs_aref) = Bric::Dist::Job->list($params)

Returns a list or anonymous array of Bric::Dist::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.

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::Dist::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::Dist::Job->list_ids($params)

Returns a list or anonymous array of Bric::Dist::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::Dist::Job->my_meths

(@meths || $meths_aref) = Bric::Dist::Job->my_meths(TRUE)

my (@meths || $meths_aref) = Bric::Dist::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::Dist::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::Dist::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 $name = $job->get_name

Returns the name of the Bric::Dist::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::Dist::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 pending 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 pending 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 pending 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 pending 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 pending 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_pending

Returns true ($self) if the job is pending (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->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 pending 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::Dist::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.

PRIVATE

Private Class Methods

NONE.

Private Instance Methods

NONE.

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::Dist::Job objects or, if called with an optional third argument, returns a listof Bric::Dist::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 = &$set_pend($self, $value)

Sets the pending column in the database, as well as the pending property in the job object. Used by execute().

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.

AUTHOR

David Wheeler <david@wheeler.net>

NAME

VERSION

DATE

SYNOPSIS

DESCRIPTION

INTERFACE

Constructors

Destructors

Public Class Methods

Public Instance Methods

PRIVATE

Private Class Methods

Private Instance Methods

Private Functions

NOTES

AUTHOR

SEE ALSO