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

$LastChangedRevision$

$LastChangedDate: 2005-09-12 06:50:15 -0700 (Mon, 12 Sep 2005) $

 # 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();

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.

$obj = new Bric::Util::Attribute($init);

Creates a new attribute object for an object type with ID given by argument 'id'. Keys of CW$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' 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: 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: 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: Return the object ID for this attribute object. This is the object to which these attributes apply. Throws: NONE Side Effects: NONE Notes: 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: Keys of CW$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: Keys of CW$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: 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 Keys of CW$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: Return all attribute/value pairs AND metadata for a given subsystem. If CW$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: Keys of CW$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: Keys of CW$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: 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 CW$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: Deletes an attribute value from the database...permanently! The keys of CW$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: The keys for CW$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: The keys for CW$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: The keys for CW$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: Saves the information set on this object to the database. Throws: NONE Side Effects: NONE Notes:

_table_info

Throws: NONE Side Effects: NONE Notes: NONE Returns an attribute metadata value. Keys to CW$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 Returns an attribute value. Keys to CW$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 Sets an attribute metadata value. Keys to CW$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 Sets an attribute value. Keys to CW$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 Loads all the attributes and attribute metadata for the given subsystem. Throws: NONE Side Effects: NONE Notes: NONE Select rows from a table in the database. Throws: NONE Side Effects: NONE Notes: NONE Insert a row into a table in the database. Throws: NONE Side Effects: NONE Notes: NONE Update a table in the database. Throws: NONE Side Effects: NONE Notes: NONE Update a table in the database. Throws: NONE Side Effects: NONE Notes: NONE

NONE

Garth Webb <garth@perijove.com>

perl, Bric, Bric::Util::Group