Bric::Util::Attribute(3)

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

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2005-10-13 13:37:00 -0700 (Thu, 13 Oct 2005) $

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:

    *   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

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

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

    *   Cannot assign new object ID.

    Side Effects:

    NONE

    Notes:

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

    *   name

        The name of the attribute

    *   subsys

        The subsystem to use.

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

    *   name

        The attribute name

    *   subsys

        The subsystem to use.

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

    *   name

        The name of the attribute

    *   subsys

        The subsystem to use.

    *   attr_id

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

    *   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)

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

    *   name

        A name substring to search for in the attribute system.

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

    *   name

        The name of the attribute

    *   subsys

        The subsystem to use.

    *   sql_type

        The storage type of this attribute.

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

    *   name

        The name of the attribute to clear.

    *   subsys

        The subsystem to use.

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

    *   name

        The name of the attribute to clear.

    *   subsys

        The subsystem to use.

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

    *   name

        The name of the attribute for which to add metadata.

    *   subsys

        The subsystem to use.

    *   attr_id

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

    *   field

        The name of the metadata field.

    *   value

        The metadata value.

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

    *   name

        The name of the attribute for which to retrieve metadata.

    *   subsys

        The subsystem to use.

    *   attr_id

        The type of attribute (represents a name/subsys)

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

    *   attr_id

        The attribute ID to which this metadata applies.

    *   name

        The name of the attribute for which to clear metadata.

    *   subsys

        The subsystem to use.

    *   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