Bric::Util::Attribute(User Contributed Perl DocumentaBric::Util::Attribute(3p)



NAME
       Bric::Util::Attribute - A module to manage attributes for various
       objects.

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-06-15 21:46:46 +0200 (Thu, 15 Jun 2006) $

SYNOPSIS
        # Object creation methods
        $attr_obj = new($init);

        ##-- Methods that apply to the object to which these attributes apply --##
        $id       = $attr_obj->get_object_id();
        $id       = $attr_obj->set_object_id();

        # Return an abbrievated name for the object these attributes represent.
        $short    = $attr_obj->short_object_type();


        ##-- Subsystem methods --##
        $subsys   = $attr_obj->get_subsys();
        $success  = $attr_obj->set_subsys($subsys);

        # Return a list of subsystem names for this object.
        @names    = $attr_obj->subsys_names($subsys);

        # All attributes and metadata for a given subsys.
        $all      = $attr_obj->all_for_subsys($subsys);

        # Get the sql_type of a value.
        $sqltype  = $attr_obj->get_sqltype($param);


        ##-- Single attribute methods --##
        $value    = $attr_obj->get_attr($param);
        $id       = $attr_obj->get_attr_id($param);

        $success  = $attr_obj->set_attr($param);

        $success  = $attr_obj->deactivate_attr($param);
        $success  = $attr_obj->delete_attr($param);

        ##-- Methods that act on multiple attribute values --##
        $values   = $attr_obj->get_attr_hash($param);
        $attr_val = $attr_obj->search_attr($param);


        ##-- Manipulate metadata about an attribute --##
        $success  = $attr_obj->add_meta($param);

        $value    = $attr_obj->get_meta($param);

        $success  = $attr_obj->delete_meta($param);

        ##-- Other methods --##
        $success  = $attr_obj->save();

DESCRIPTION
       The attribute module allows key/value pairs to be associated with an
       object. Attributes apply to a specific object of a specific type.
       Attributes keys can also have metadata associated with them. This is
       data that helps define additional information about an attribute key,
       but says nothing about the attribute value. Finally, attributes keys
       can be grouped into 'subsystems'. A subsystem simply holds a group of
       related attributes. Specifying subsystems or metadata is not necessary
       for using the attribute class.

       Attribute values can be one of three types, 'short', 'date' and 'blob'.
       This is called the 'sql_type'. Each of these types has a different
       storabe type in the database. If an attribute value is a 'short' value
       its data is limited to a length of 1024 characters. If an attribute
       value is a 'date' value, it must be in a database date format. If an
       attribute value is a 'blob' value its length is limited only by disk
       space and database performance.

       Metadata on an attribute key can give more context to the attribute
       key, or simply be a storage space for information associated with that
       key. Metadata is a field name and a value. For instance, an attribute
       for a user class might be 'notify_email' with values set to 'yes' or
       'no'. A metadata field name for the 'notify_email' key might be
       'description' and a value might be 'Should the user be notified via
       email of new announcements'. There is no limit to the number of
       metadata fields for a given attribute.

       A subsystem is a way to organize attributes. Every attribute lives
       within a subsystem. If an attribute is not given a subsystem
       explicitly, it will automatically be placed inside of a default
       subsystem. Most methods in the attribute class can be passed a
       subsystem name, but will use the default name if one is not passed.

       You can think about the attribute system like a perl hash:

         $attribute = {'subsystem1' =>
                          {'attr_key1' =>
                              {'metadata' =>
                                  {'meta_field1' => 'meta_data1',
                                   'meta_field2' => 'meta_data2',
                                   ...
                                  },
                               'value'    => 'attribute_value1'
                              },
                           'attr_key2' =>
                              {'metadata' =>
                                  {...
                                  },
                               'value'    => 'attribute_value2'
                              },
                           ...
                          },
                       'subsystem2' =>
                           {'attr_key1' => {...},
                            'attr_key2' => {...},
                            'attr_key3' => {...},
                           },
                       ...
                      }

       where everything ending with a number is data that you as the attribute
       user sets, and everything else (ie 'metadata' and 'value') is there
       just to give you and idea of the relationships. The '...' denotes
       possible additional values following the same pattern.

       So, to set value 'attribute_value1', one would call:

         $attr_obj->set_attr({'subsys'   => 'subsystem1',
                              'name'     => 'attr_key1',
                              'sql_type' => 'short',
                              'value'    => 'attribute_value1'});

       To set 'meta_data2', one would call:

         $attr_obj->set_meta({'subsys' => 'subsystem1',
                              'name'   => 'attr_key1',
                              'field'  => 'meta_field2',
                              'value'  => 'meta_data2'});

       To retrieve 'attribute_value2', one would call:

         $attr_obj->get_meta({'subsys' => 'subsystem1',
                              'name'   => $attr_key2});

       Note that specifying an 'sql_type' is only necessary when setting
       values, to let the module know how to store them. When a value is
       retrieved, the attribute module can tell what type of data is stored.

       One final note. The examples do not explicitly show this, but any
       metadata set on a particular attribute name will be available to all
       objects of the same type if they use the same attribute name. For
       instance, if a user object with id = 5 sets metadata field 'cereal' on
       attribute name 'breakfast' to 'cracklin oat bran', then all user
       objects that set attribute 'breakfast' will have a metadata field
       'cereal' with value 'cracklin oat bran'. This is intentional and is
       meant to promote attribute reusablility.

INTERFACE
   Public Methods
       $obj = new Bric::Util::Attribute($init);
           Creates a new attribute object for an object type with ID given by
           argument 'id'.

           Keys of $init are:

           o   subsys

               The subsystem to use by default for all subsequent method calls
               requiring a subsystem. If this is not given the package default
               subsytem, DEFAULT_SUBSYS, will be used. Any method requiring a
               subsystem will use the value passed here by default if a
               subsystem is not passed to that method.

               This field is optional

           o   object_id

               The object ID for which this attribute applies. Attributes
               values are specific to the objects that set them.

               ** This is a required field **

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $type = Bric::Util::Attribute::short_object_type();
           Returns the short object type name used to construct the attribute
           table name where the attributes for this class type are stored.
           This should be overridden in all subclasses of Attribute. Oh, did I
           mention that the Attribute class should never be used directly? It
           is an abstract class and only subclasses of Attribute should be
           instantiated.

           This method is used internally by the Attribute object.

           Throws:

           o   Short object type not defined

               Thrown when the short object type name has not been defined by
               the programmer.

           Side Effects:

           NONE

           Notes:

           Values for this method look like 'grp' given a full object type of
           'Bric::Util::Grp'

       $id = $attr_obj->get_subsys();
           Return the current default subsys name. This subsys is used for any
           query requiring a subsys when the user has not supplied a subsys.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $id = $attr_obj->set_subsys();
           Sets the default subsys name.  This subsys is used for any query
           requiring a subsys when the user has not supplied a subsys.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       @names = $attr_obj->subsys_names($inactive);
           Returns a list of subsystem names for this object. If argument
           'inactive' is true, then inactive subsystem names will be returned.
           Otherwise only active subsys names will be returned.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $id = $attr_obj->get_object_id();
           Return the object ID for this attribute object. This is the object
           to which these attributes apply.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $attr_obj = $attr_obj->set_object_id($id);
           Set the object ID for this attribute object. This is the object to
           which these attributes apply. The object ID can be set only once.

           Throws:

           o   Cannot assign new object ID.

           Side Effects:

           NONE

           Notes:

       $sqltype = $attr_obj->get_sqltype($param);
           Keys of $param are:

           o   name

               The name of the attribute

           o   subsys

               The subsystem to use.

           o   attr_id

               The attribute type to use, given instead of a 'name'/'subsys'
               pair.

           Returns the sqltype (the datatype) for the value of this attribute.

           If no subsystem is given, it will use the default subsystem passed
           to the new constructor or via the 'set_subsys' method.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $attr_val = $attr_obj->get_attr($param);
           Keys of $param are:

           o   name

               The attribute name

           o   subsys

               The subsystem to use.

           o   attr_id

               The attribute type ID to use rather than use the
               'name'/'subsys' combination.

           Returns the value of the attribute for the given attribute type.

           If no subsystem is given, but a name is given it will use the
           default subsystem passed to the new constructor or via the
           'set_subsys' method.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $attr_id = $attr_obj->get_attr_id($subsys, $name);
           Returns an ID for an attribute type which uniquely identifies a
           subsystem name pair. This ID can be used in place of an attribute
           name and subsystem for methods that require those values.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $attr_val = $attr_obj->get_attr_hash($param);
           Keys of $param are:

           o   name

               The name of the attribute

           o   subsys

               The subsystem to use.

           o   attr_id

               The type ID to use rather than use the 'name'/'subsys'
               combination.

           o   ret_set_only

               Only return attribute names when that name has a corresponding
               row in one of the value tables if set to 1. Default is setting
               this to 0 and all attribute names will be returned, even if no
               value is set (undef will be returned as the value)

           o   inactive

               If true, inactive attributes will be returned.

           Returns a hash of key/values for the given parameters.

           If no subsystem is given, but a name is given it will use the
           default subsystem passed to the new constructor or via the
           'set_subsys' method.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $all = $attr_obj->all_for_subsys($subsys);
           Return all attribute/value pairs AND metadata for a given
           subsystem. If $subsys is not passed the default subsys will be
           used. Format of the return value is:

             $all = {'attr_name' => {'value' => 'attr_value',
                                     'meta'  => {'attr_meta_field1' => 'attr_meta_value1',
                                                 ...,
                                                },
                                    },
                     ...,
                    };

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $attr_val = $attr_obj->search_attr($param);
           Keys of $param are:

           o   name

               A name substring to search for in the attribute system.

           o   subsys

               The subsystem in which to search.

           Returns a hash of key/values for the given parameters.

           If no subsystem is given, but a name is given it will use the
           default subsystem passed to the new constructor or via the
           'set_subsys' method.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       %attr = $attr_obj->set_attr($param);
           Keys of $param are:

           o   name

               The name of the attribute

           o   subsys

               The subsystem to use.

           o   sql_type

               The storage type of this attribute.

           o   attr_id

               The type ID to use rather than use the 'name'/'subsys'
               combination.

           Sets the value of a particular attribute.

           If no subsys is given, it will use the default subsystem passed to
           the new constructor or via the 'set_subsys' method.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $success = $attr_obj->deactivate_attr($param);
           Deactivates an attribute value. This means that the value is still
           in the database, but it has been made inactive. Inactive values
           will not be retrieved unless specifically sought after.

           The keys of $param are:

           o   name

               The name of the attribute to clear.

           o   subsys

               The subsystem to use.

           o   attr_id

               The type of object (represents a name/subsys pair).

           If no subsys is given, it will use the default subsystem passed to
           the new constructor or via the 'set_subsys' method.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $success = $attr_obj->delete_attr($param);
           Deletes an attribute value from the database...permanently!

           The keys of $param are:

           o   name

               The name of the attribute to clear.

           o   subsys

               The subsystem to use.

           o   attr_id

               The type of object (represents a name/subsys pair).

           If no subsys is given, it will use the default subsystem passed to
           the new constructor or via the 'set_subsys' method.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $success  = $attr_obj->add_meta($param);
           The keys for $param are:

           o   name

               The name of the attribute for which to add metadata.

           o   subsys

               The subsystem to use.

           o   attr_id

               The type of attribute (a substitute for a name and subsys)

           o   field

               The name of the metadata field.

           o   value

               The metadata value.

           o   metadata

               A hash ref of field/value metadata pairs.

           Adds metadata about a particular attribute name/subsys pair.
           Metadata can be things such as attribute descriptions, default
           values, etc.

           If no subsys is given, it will use the default subsystem passed to
           the new constructor or via the 'set_subsys' method.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $value  = $attr_obj->get_meta($param);
           The keys for $param are:

           o   name

               The name of the attribute for which to retrieve metadata.

           o   subsys

               The subsystem to use.

           o   attr_id

               The type of attribute (represents a name/subsys)

           o   field

               The name of the metadata field.

           Either 'name' and optional 'subsys' (if not given the current
           default will be used) must be given, or an 'attr_id' must be given.
           If a field name is given, the metadata associated with that field
           will be returned. If no field name is given, then all metadata for
           the name/subsys or attr_id will be returned in a hash.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $success  = $attr_obj->delete_meta($param);
           The keys for $param are:

           o   attr_id

               The attribute ID to which this metadata applies.

           o   name

               The name of the attribute for which to clear metadata.

           o   subsys

               The subsystem to use.

           o   field

               The name of the metadata field.

           These keys can be used in the following combinations:

           1.  An 'attr_id' and a 'field'

           2.  A 'subsys', 'name' and a 'field'

           Deletes a metadata entry for a given metadata name and attribute
           name/subsys pair.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

       $success  = $attr_obj->save();
           Saves the information set on this object to the database.

           Throws: NONE

           Side Effects: NONE

           Notes:

   Private Methods
       _table_info
           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_get_meta($param)
           Returns an attribute metadata value.  Keys to $param are:

           subsys
               The subsystem to use, overriding the default. (optional)

           name
               The name of the attribute upon which to set metadata.

           field
               The name of the metadata data point.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_get_val($param)
           Returns an attribute value.  Keys to $param are:

           subsys
               The subsystem to use, overriding the default. (optional)

           name
               The name of the attribute to set. (optional)

           If 'name' is not passed a data structure of all attributes in
           'subsys' (or the default subsys) are returned. If name is passed,
           then a data structure for that attribute alone is returned.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_set_meta($param)
           Sets an attribute metadata value.  Keys to $param are:

           subsys
               The subsystem to use, overriding the default. (optional)

           name
               The name of the attribute upon which to set metadata.

           field
               The name of the metadata data point.

           value
               The value of the metadata data point.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_set_val($param)
           Sets an attribute value.  Keys to $param are:

           subsys
               The subsystem to use, overriding the default. (optional)

           name
               The name of the attribute to set.

           value
               The value of the attribute

           sql_type
               The sql_type of the value (optional if updating an existing
               value)

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_load_subsys($subsys);
           Loads all the attributes and attribute metadata for the given
           subsystem.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_select_table($type, $where, $bind);
           Select rows from a table in the database.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_insert_table($type, $bind);
           Insert a row into a table in the database.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_update_table($type, $where, $bind);
           Update a table in the database.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_delete_from_table($type, $where, $bind);
           Update a table in the database.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

NOTES
       NONE

AUTHOR
       Garth Webb <garth@perijove.com>

SEE ALSO
       perl, Bric, Bric::Util::Group



perl v5.12.2                      2006-06-15         Bric::Util::Attribute(3p)
