Bric::Dist::Resource(3User Contributed Perl DocumentatBric::Dist::Resource(3p)



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

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-08-09 06:57:25 +0200 (Wed, 09 Aug 2006) $

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:

           o   path

           o   uri

           o   media_type

           o   size

           o   mod_time

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

           o   Unable to select row.

           o   Too many Bric::Dist::Resource objects found.

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

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

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

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

           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::Dist::Resource 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 $media_type = $res->get_media_type
           Returns the MEDIA type of the resource. Returns undef in the
           resource is a directory.

           Throws:

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

           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:

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

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

           Side Effects: NONE.

           Notes: NONE.

       my $path = $res->get_path
           Returns the file system path to the resource.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           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:

           o   Cannot change path in existing Bric::Dist::Resource object.

           o   Path does not exist.

           o   Unable to format date.

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

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

           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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       $self = $res->set_uri($uri)
           Sets the resource's URI.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           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:

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

           o   Bric::Dist::Resource::stat_me() requires the path property to
               be set.

           o   Path does not exist.

           o   Unable to format date.

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

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

           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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

           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:

           o   Unable to unpack date.

           o   Unable to format date.

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

           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:

           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.

       $self = $res->is_dir
           Returns true if the resources is a directory.

           Throws:

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           Side Effects: NONE.

           Notes: NONE.

       $self = $res->add_story_ids(@story_ids)
           Associates this resource with the story IDs passed in.

           Throws:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           Side Effects: NONE.

           Notes: NONE.

       $self = $res->add_media_ids(@media_ids)
           Associates this resource with the media IDs passed in.

           Throws:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Cannot associate file resources with another file resource.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           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.

       $contents = $res->get_contents
           Returns the contents of the file represented by the
           Bric::Dist::Resource object.

           Throws:

           o   Cannot open file.

           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:

           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:

       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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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.

           o   cur - All new IDs and IDs currently in the database.

           o   new - IDs to be added to the database.

           o   del - IDs to be deleted from the database.

           Throws:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

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

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

           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:

           o   Path does not exist.

           o   Unable to format date.

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

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

           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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

           Side Effects: NONE.

           Notes:

NOTES
       NONE.

AUTHOR
       David Wheeler <david@justatheory.com>

SEE ALSO
       Bric, Bric::Util::Job



perl v5.12.2                      2006-08-08          Bric::Dist::Resource(3p)
