Name

Bric::Dist::Resource - Interface to distribution files and directories.

Synopsis

use Bric::Dist::Resource;

# Constructors.
# Create a new resource.
my $res = Bric::Dist::Resource->new;
# Look up an existing resource.
$res = Bric::Dist::Resource->lookup({ id => 1 });
# Get a list of resources.
my @res = Bric::Dist::Resource->list({ path => '/tech/feature%' });

# Class methods.
# Get a list of resource IDs.
my @res_ids = Bric::Dist::Resource->list_ids({ path => '/tech/feature%' });
# Get an introspection hashref.
my $int = Bric::Dist::Resource->my_meths;

# Instance methods.
my $id = $res->get_id;
my $path = $res->get_path;
$res = $res->set_path($path);
my $uri = $res->get_uri;
$res = $res->set_uri($uri);
my $tmp_path = $res->get_tmp_path;
$res = $res->set_tmp_path($tmp_path);
my $size = $res->get_size;
$res = $res->set_size($size);
my $mod_time = $res->get_mod_time;
$res = $res->set_mod_time($mod_time)
my $media_type = $res->get_media_type;
$res = $res->set_media_type($media_type)
print "It's a directory!\n" if $res->is_dir;

# Reload size and mod_time, from the resource on the file system.
$res = $res->stat_me;

# Story relationships.
my @story_ids = $res->get_story_ids;
$res = $res->add_story_ids(@story_ids);
$res = $res->del_story_ids(@story_ids);

# Media relationships.
my @media_ids = $res->get_media_ids;
$res = $res->add_media_ids(@media_ids);
$res = $res->del_media_ids(@media_ids);

# File relationships.
if ($res->is_dir) {
    my @file_ids = $res->get_file_ids;
    $res = $res->add_file_ids(@file_ids);
    $res = $res->del_file_ids(@file_ids);
}

# Save it!
$res = $res->save;

Description

This class manages distribution resources. A resource is a file or directory. Directory resources can be associated with file resources (in order to keep a list of the contents of a directory), but not vice versa. Resources may also track associations with assets, such that they can have story and/or media associations. Other properties of resources are filesystem path, file size, MEDIA type, and last modified date.

Interface

Constructors

my $res = Bric::Dist::Resource->new($init)

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

Call $res->save() to save the new object.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $res = Bric::Dist::Resource->lookup({ id => $id })
my $res = Bric::Dist::Resource->lookup({ path => $path, uri => $uri })

Looks up and instantiates a new Bric::Dist::Resource object based on the Bric::Dist::Resource object ID or based on the path and uri. If a Bric::Dist::Resource object is not found in the database, lookup() returns undef.

Throws:

Side Effects: If $id or $path is found, populates the new Bric::Dist::Resource object with data from the database before returning it.

Notes: NONE.

my (@res || $res_aref) = Bric::Dist::Resource->list($params)

Returns a list or anonymous array of Bric::Dist::Resource objects based on the search parameters passed via an anonymous hash. The supported lookup keys are:

id

Resource ID. May use ANY for a list of possible values.

path

The path to the resource on the file system. Usually used in combination with uri. May use ANY for a list of possible values.

uri

The URI for a resource. Usually used in combination with path. May use ANY for a list of possible values.

not_uri

Search for resources with URIs not like the specified URI. May use ANY for a list of possible values.

media_type

The resources' MEDIA type. May use ANY for a list of possible values.

mod_time

The resources' last modified time. If passed as an anonymous array of two values, those values will be used to retreive resources whose mod_times are between the two times. Otherwise, may use ANY for a list of possible values.

size

The size, in bytes, of the file. If passed as an anonymous array of two values, those values will be used to retreive resources whose sizes are between the two sizes. Otherwise, may use ANY for a list of possible values.

is_dir

If true, return only those resources that are directories.

story_id

Resources associated with a given story ID. May use ANY for a list of possible values.

media_id

Resources associated with a given media ID. May use ANY for a list of possible values.

media_id

Resources associated with a given media ID. May use ANY for a list of possible values.

dir_id

File resources that are associated with a directory Resource's ID. May use ANY for a list of possible values.

job_id

Resources associated with a given job ID. May use ANY for a list of possible values.

not_job_id

Resources not associated with a given job ID. Best used in combination with story_id or media_id. May use ANY for a list of possible values.

oc_id

Resources associated with an output channel ID. Only returns the correct results if the job table has not been cleared, because it joins to job__resource, job__server_type, and server_type__output_channel.

Throws:

Side Effects: Populates each Bric::Dist::Resource object with data from the database before returning them all.

Notes: NONE.

my $res_href = Bric::Dist::Resource->href($params)

Returns a list or anonymous array of Bric::Dist::Resource objects based on the search parameters passed via an anonymous hash. The supported lookup keys are the same as for list().

Throws:

Side Effects: Populates each Bric::Dist::Resource object with data from the database before returning them all.

Notes: NONE.

Destructors

$res->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Class Methods

my (@res_ids || $res_ids_aref) = Bric::Dist::Resource->list_ids($params)

Returns a list or anonymous array of Bric::Dist::Resource 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::Dist::Resource->my_meths
(@meths || $meths_aref) = Bric::Dist::Resource->my_meths(TRUE)
my (@meths || $meths_aref) = Bric::Dist::Resource->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 representing the values and display names to use in a select list.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Instance Methods

my $id = $res->get_id

Returns the ID of the Bric::Dist::Resource object.

Throws:

Side Effects: NONE.

Notes: If the Bric::Dist::Resource 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 $media_type = $res->get_media_type

Returns the MEDIA type of the resource. Returns undef in the resource is a directory.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->set_media_type($media_type)

Sets the MEDIA type of the resource. Call Bric::Util::MediaType->list() to get a list of available MEDIA types. Setting the MEDIA type to "none" will cause is_dir() to return true, while any other MEDIA type setting will cause is_dir() to return false.

Throws:

Side Effects: NONE.

Notes: NONE.

my $path = $res->get_path

Returns the file system path to the resource.

Throws:

Side Effects: NONE.

Notes: For cross-platform portability, we may later want to implement the get_path() and set_path() methods using File::Spec.

$self = $res->set_path($path)

Sets the file system path to the resource. This property cannot be changed in an existing Bric::Dist::Resource object. The resource must exist on the file system to set the path. In addition, once the resource has been found on the file system the media_type, size, and mod_time properties will also be filled out, as best as possible. These settings can be overridden by calling their own set_ methods.

Throws:

Side Effects: NONE.

Notes: For cross-platform portability, we may later want to implement the get_path() and set_path() methods using File::Spec.

my $uri = $res->get_uri

Returns the resource's URI.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->set_uri($uri)

Sets the resource's URI.

Throws:

Side Effects: NONE.

Notes: NONE.

my $tmp_path = $res->get_tmp_path

Returns the file system path to the a temporary copy of the resource. Used by Bric::Util::Job and does not persist to the database.

Throws:

Side Effects: NONE.

Notes: For cross-platform portability, we may later want to implement the get_path() and set_path() methods using File::Spec.

$self = $res->set_tmp_path($tmp_path)

Sets the file system path to a temporary copy of the resource. Used by Bric::Util::Job and does not persist to the database.

Throws:

Side Effects: NONE.

Notes: For cross-platform portability, we may later want to implement the get_path() and set_path() methods using File::Spec.

$self = $res->stat_me

Finds the resource on the file system and reloads the size, mod_time, and media_type properties. If the MEDIA type cannot be determined from the file the existing media_type property setting is retained.

Throws:

Side Effects: NONE.

Notes: For cross-platform portability, we may later want to implement the get_path() and set_path() methods using File::Spec.

my $size = $res->get_size

Returns the size of the resource in bytes. If the resource is a directory, this method will return 0.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->set_size($size)

Sets the size of the resource in bytes. If the resource is a directory, set the size to 0. Chances are that if you called set_path() first, this property will already be enumerated.

Throws:

Side Effects: NONE.

Notes: NONE.

my $mod_time = $res->get_mod_time($format)

Returns the last modified time of the resource. Pass in a strftime format string to get the last modified time returned in that format.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->set_mod_time($mod_time)

Sets the mod_time of the resource in bytes. Chances are that if you called set_path() first, this property will already be enumerated.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->is_dir

Returns true if the resources is a directory.

Throws:

Side Effects: NONE.

Notes: NONE.

my (@story_ids || $story_ids_aref) = $res->get_story_ids

Returns a list or anonymous array of story IDs representing the stories with which this resources is associated.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->add_story_ids(@story_ids)

Associates this resource with the story IDs passed in.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->del_story_ids(@story_ids)

Dissociates this resource with the story IDs passed in. If no story IDs are passed, then all story IDs will be dissociated from this resource.

Throws:

Side Effects: NONE.

Notes: NONE.

my (@media_ids || $media_ids_aref) = $res->get_media_ids

Returns a list or anonymous array of media IDs representing the stories with which this resources is associated.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->add_media_ids(@media_ids)

Associates this resource with the media IDs passed in.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->del_media_ids(@media_ids)

Dissociates this resource with the media IDs passed in. If no media IDs are passed, then all media IDs will be dissociated from this resource.

Throws:

Side Effects: NONE.

Notes: NONE.

my (@resource_ids || $resource_ids_aref) = $res->get_file_ids

Returns a list or anonymous array of Bric::Dist::Resource object IDs representing the files that are the contents of this resource, assuming that this resource is a directory. If this resource is a file, this method will return an empty list.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->add_file_ids(@file_ids)

Associates this resource with the File IDs passed in. Note that is_dir() must return true in order to associate files with this resource.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->del_file_ids(@file_ids)

Dissociates this resource with the file IDs passed in. If no file IDs are passed, then all file IDs will be dissociated from this resource. If this is_dir() returns false, then this resource cannot be assocated with files and will return undef.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $res->save

Saves any changes to the Bric::Dist::Resource object. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: NONE.

$contents = $res->get_contents

Returns the contents of the file represented by the Bric::Dist::Resource object.

Throws:

Side Effects: NONE.

Notes: NONE.

Private

Private Class Methods

NONE.

Private Instance Methods

NONE.

Private Functions

my $res_aref = &$get_em( $pkg, $params )
my $res_ids_aref = &$get_em( $pkg, $params, 1 )

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

Throws:

Side Effects: NONE.

Notes:

my (@ids || $ids_aref) = &$get_ids($self, $type)

Returns the Asset IDs associated with this resource. If $type is 'story', it returns Story IDs. If $type is 'media', it returns Media IDs.

Throws:

Side Effects: NONE.

Notes:

my $bool = &$add_ids($self, $type)

Associates asset IDs with this resource. If $type is 'story', it associates Story IDs. If $type is 'media', it associates Media IDs. Returns true.

Throws:

Side Effects: NONE.

Notes:

my $bool = &$del_ids($self, $type)

Dissociates asset IDs from this resource. If $type is 'story', it dissociates Story IDs. If $type is 'media', it dissociates Media IDs. Returns true.

Throws:

Side Effects: NONE.

Notes:

my $ids_href = &$load_ids($self, $type)

Returns the Asset IDs associated with this resource. If $type is 'story', it returns Story IDs. If $type is 'media', it returns Media IDs. The anonymous hash returned has the following keys, each of which contains another anonymous hash where the relevant IDs are the hash keys.

Throws:

Side Effects: NONE.

Notes:

$self = &$stat($self, $path)

Finds $path on the file system and loads the properties size, mod_time, and media_type (if $path is a directory).

Throws:

Side Effects: NONE.

Notes:

$bool = &$save_ids($id, $ids, $type)

Saves the associated Story, Media, or File IDs by deleting those that need deleting and inserting those that need inserting.

Throws:

Side Effects: NONE.

Notes:

Notes

NONE.

Author

David Wheeler <david@justatheory.com>

See Also

Bric, Bric::Util::Job