Name

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

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:

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:

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:

Side Effects:

NONE

Notes:

$sqltype = $attr_obj->get_sqltype($param);

Keys of $param are:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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