NAME

Bric::Biz::Person::User - Interface to Bricolage User Objects

VERSION

$LastChangedRevision$

DATE

$LastChangedDate$

SYNOPSIS

use Bric::Biz::Person::User;

# Constructors.
my $u = Bric::Biz::Person::User->new;
my $u = Bric::Biz::Person::User->lookup({ id => $id })
my $u = Bric::Biz::Person::User->lookup({ login => $login })
my @users = Bric::Biz::Person::User->list($search_href)

# Class Methods.
my @uids = Bric::Biz::Person::User->list_ids($search_href)

# Instance Methods - in addition to those inherited from Bric::Biz::Person.
my $login = $u->get_login;
$u = $login->set_login($login);
$u = $u->set_password($password);
$u = $u->chk_password($password);

$u = $u->can_do($obj, READ);
$u = $u->no_can_do($obj, CREATE);

$u = $u->activate;
$u = $u->deactivate;
$u = $u->is_active;

my @gids = $u->get_grp_ids;
my @groups = $u->get_grps;

$u = $u->save;

DESCRIPTION

This Class provides the basic interface to all Bricolage and users. Bric::Biz::Person::User objects are special Bric::Biz::Person objects that represent members of the Bric::Util::Group::Person group "User". Only members of this group can actually use the application. All other Bric::Biz::Person objects cannot use Bricolage, although they can be associated with Bricolage objects (e.g., writers can be associated with stories).

Bric::Biz::Person::User extends the Bric::Biz::Person interface to allow the setting and checking of passwords, the setting of login names, and the activation or deactivation of the person as a user. It also offers methods by which to set permissions for individual users, although these permissions really should be assigned via membership in other groups. (For example, put editors in an editors group, and allow members of that group to edit stories. See Bric::Util::Group::Person for more information.)

INTERFACE

Constructors

my $u = Bric::Biz::Person::User->new($init)
Instantiates a Bric::Biz::Person::User object. An anonymous hash of intial values may be passed. The supported intial hash keys are:
- lname
- fname
- mname
- prefix
- suffix
- login
Call $u->save() to save the new object.

Throws:
- Incorrect number of args to Bric::_set().
- Bric::set() - Problems setting fields.
Side Effects: NONE.

Notes: NONE.
my $p = Bric::Biz::Person->lookup($params)
Looks up and instantiates a new Bric::Biz::Person::User object based on the Bric::Biz::Person::User object ID or login name. If the existing object is not found in the database, lookup() returns undef. The two possible lookup parameters are:
- id - Returns the User with that ID, if it exists.
- login - Returns the active User with that login, if it exists. Inactive users with that login will be ignored.
Throws:
- Too many Bric::Biz::Person::User objects found.
- Unable to prepare SQL statement.
- Unable to connect to database.
- Unable to select column into arrayref.
- Unable to execute SQL statement.
- Unable to bind to columns to statement handle.
- Unable to fetch row from statement handle.
Side Effects: If id or login name is found, populates the new Bric::Biz::Person object with data from the database before returning it.

Notes: This method is overriding the lookup() method of the Bric::Biz::Person object, including all of its SQL. Thus, the Bric::Biz::Person::lookup method will not be called here, and it's SQL queries will not be executed.
my (@users || $users_aref) = Bric::Biz::Person::User->list($params)
Returns a list or anonymous array of Bric::Biz::Person::User objects based on the search criteria passed via an anonymous hash. The supported lookup keys are:
- id
  User ID. May use ANY for a list of possible values.
- prefix
  A name prefix, such as "Mr." May use ANY for a list of possible values.
- lname
  Last name or surname. May use ANY for a list of possible values.
- fname
  First name or given name. May use ANY for a list of possible values.
- mname
  Middle name or second name. May use ANY for a list of possible values.
- suffix
  Name suffix, such as "Jr." May use ANY for a list of possible values.
- grp_id
  The ID of a Bric::Util::Grp object of which person objects may be a member. May use ANY for a list of possible values.
- login
  The user's username. May use ANY for a list of possible values.
Throws:
- Unable to prepare SQL statement.
- Unable to connect to database.
- Unable to select column into arrayref.
- Unable to execute SQL statement.
- Unable to bind to columns to statement handle.
- Unable to fetch row from statement handle.
Side Effects: Populates each Bric::Biz::Person::User object with data from the database before returning them all.

Notes: This method is overriding the list() method of the Bric::Biz::Person object, including all of its SQL. Thus, the Bric::Biz::Person::list method will not be called here, and it's SQL queries will not be executed.

Destructors

$p->DESTROY
Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Throws:> NONE.

Side Effects: NONE.

Notes: NONE.

Public Class Methods

my (@uids || $uids_aref) = Bric::Biz::Person::User->list_ids($params)
Returns a list or anonymous array of Bric::Biz::Person::User object IDs based on the search criteria passed via an anonymous hash. The supported lookup keys are the same as those for list().

Throws:
- Unable to prepare SQL statement.
- Unable to connect to database.
- Unable to select column into arrayref.
- Unable to execute SQL statement.
- Unable to bind to columns to statement handle.
- Unable to fetch row from statement handle.
Side Effects: NONE.

Notes: This method is overriding the list_ids() method of the Bric::Biz::Person object, including all of its SQL. Thus, the Bric::Biz::Person::list_ids method will not be called here, and it's SQL queries will not be executed.
$self = $u->login_avail($login)
Returns true if $login is not already in use by an active user, and undef if it is. Use this method to make ensure that a login is available for use before actually using it. A login is considered available even if a deactivated user has the same login.

Throws:
- Unable to prepare SQL statement.
- Unable to connect to database.
- Unable to select column into arrayref.
- Unable to execute SQL statement.
- Unable to bind to columns to statement handle.
- Unable to fetch row from statement handle.
Side Effects: NONE.

Notes: NONE.
$meths = Bric::Biz::Person::User->my_meths
(@meths || $meths_aref) = Bric::Biz::Person::User->my_meths(TRUE)
my (@meths || $meths_aref) = Bric::Biz::Person::User->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 reprsenting the values and display names to use in a select list.
Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Instance Methods

Bric::Biz::Person::User inherits from Bric::Biz::Person and makes available all Bric::Biz::Person instance methods. See the Bric::Biz::Person documentation for a description of those methods. Additional methods available for Bric::Biz::Person::User objects only are documented here.

my $id = $u->get_id
Returns the ID of the Bric::Biz::Person::User object.

Throws:
- Bad AUTOLOAD method format.
- Cannot AUTOLOAD private methods.
- Access denied: READ access for field 'id' required.
- No AUTOLOAD method.
Side Effects: NONE.

Notes: If the Bric::Biz::Person::User object has been instantiated via the new() constructor and has not yet been saved, the object will not yet have an ID, so this method call will return undef.
$self = $u->set_person($person)
Sets the ID representing Bric::Biz::Person object from which the Bric::Biz::Person::User object inherits.

Throws:
- Cannot change ID of existing user.
- Bric::_get() - Problems retrieving fields.
- Incorrect number of args to Bric::_set().
- Bric::set() - Problems setting fields.
Side Effects: NONE.

Notes: NONE.
my $login = $u->get_login
Returns the login name of the user.

Throws:
- Bad AUTOLOAD method format.
- Cannot AUTOLOAD private methods.
- Access denied: READ access for field 'login' required.
- No AUTOLOAD method.
Side Effects: NONE.

Notes: NONE.
$self = $u->set_login($login)
Sets the login name of the user. Be sure to call $u->save to save the change to the database. Returns $self on success and undef on failure.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$self = $u->set_password($password)
Sets the user's password. The internal authentication engine uses a double MD-5 hash algorithm to encrypt it. Be sure to call $u->save to save the change to the database. Returns $self on success and undef on failure.

Throws:
- Incorrect number of args to Bric::_set().
- Bric::set() - Problems setting fields.
Side Effects: NONE.

Notes: NONE.
$self = $u->chk_password($password)
Returns true if $password matches the password stored for this user. Returns undef if they don't match. Uses a double MD-5 hash algorithm to encrypt $password and then compare it to the value stored in the database. Returns $self on success and undef on failure.

Throws:
- Incorrect number of args to Bric::_set().
- Bric::set() - Problems setting fields.
Side Effects: NONE.

Notes: See notes for set_password().
$priv = $u->what_can($obj || $pkg)
$priv = $u->what_can(($obj || $pkg), @group_ids)
Takes an object $obj or package name $pkg and returns the permission (as exported by Bric::Util::Priv::Parts::Const) that the user object has to $obj, or to the "All" group in $pkg. A false value is no permission.

Pass in a list of group IDs and they will be treated as if they are groups to which $obj is a member. Thus you can affect the permission returned by $obj by passing in the IDs of groups it's not necessarily a member of. The reason to do this is to check, for example, a user's permission to a workflow or a desk before an asset is created and put on that desk.

Throws:
- Bric::_get() - Problems retrieving fields.
- Unable to prepare SQL statement.
- Unable to connect to database.
- Unable to select column into arrayref.
- Unable to execute SQL statement.
- Unable to bind to columns to statement handle.
- Unable to fetch row from statement handle.
Side Effects: NONE.

Notes: In the future, the implementation of this method may use caching, where the first time this or another privilege method is called, the entire ACL is either fetched from cache or recomputed from the database and then cached.

For now, however, getting the ACL is one simple query, which probably is not any slower than caching, since it also takes a single query to get the last modified time for a user's ACL and compare it to the last modified time of the cached copy of the ACL. But it may become necessary to do the caching if we create a more complex privilege system that requires many or very complex queries to create an ACL.
$self = $u->can_do($obj, $priv)
Checks to see if the user has the privilege to perform an action. $obj is the object for which the user's privilege must be checked and $priv is the privilege required to perform the action. Returns $self if the user has the privilege and undef it the user does not. Intended primarily to be used by other API calls to check that the user triggering the API call actually has the privileges to do so.

Throws:
- Bric::_get() - Problems retrieving fields.
- Unable to prepare SQL statement.
- Unable to connect to database.
- Unable to select column into arrayref.
- Unable to execute SQL statement.
- Unable to bind to columns to statement handle.
- Unable to fetch row from statement handle.
Side Effects: NONE.

Notes: See what_can() above.
$self = $u->no_can_do($obj, $priv)
Exactly the same as $u->can_do, except that it returns $self if the user does not have the permission on the object, and undef if the user does have the permission on the object.

Throws:
- Bric::_get() - Problems retrieving fields.
- Unable to prepare SQL statement.
- Unable to connect to database.
- Unable to select column into arrayref.
- Unable to execute SQL statement.
- Unable to bind to columns to statement handle.
- Unable to fetch row from statement handle.
Side Effects: NONE.

Notes: Just does !can_do() internally. ;-)
$self = $u->activate
Flags the Bric::Biz::Person::User object as an active user in Bricolage. Be sure to call $u->save to save the change to the database. Returns $self on success and undef on failure.

Throws:
- Incorrect number of args to Bric::_set().
- Bric::set() - Problems setting fields.
Side Effects: Inherited from Bric::Biz::Person, but uses the active value specific to the user, rather than the person.

Notes: The activate(), deactivate(), and is_active() methods differ from those found in Bric::Biz::Person. In Bric::Biz::Person, they determine whether a person is active in the entire database, across groups. In Bric::Biz::Person::User, they determine only whether the person is an active user of the system. A person may be an inactive user but still an active person. Returns $self on success and undef on failure.
$self = $u->deactivate
Flags the Bric::Biz::Person::User object as an inactive user in Bricolage. Be sure to call $u->save to save the change to the database. Returns $self on success and undef on failure.

Throws:
- Incorrect number of args to Bric::_set().
- Bric::set() - Problems setting fields.
Side Effects: NONE.

Notes: NONE.

Side Effects: Inherited from Bric::Biz::Person, but uses the active value specific to the user, rather than the person.

Notes: See the notes for the activate() method above.
$self = $u->is_active
Returns $self if the Bric::Biz::Person::User object is active, and undef if it is not.

Throws: NONE.

Side Effects: Inherited from Bric::Biz::Person, but uses the active value specific to the user, rather than the person.

Notes: See the notes for the activate() method above.

################################################################################
my (@gids || $gids_aref) = $u->get_grp_ids
my (@gids || $gids_aref) = Bric::Biz::Person::User->get_grp_ids
Returns a list or anonymous array of Bric::Biz::Group object ids representing the groups of which this Bric::Biz::Person::User object is a member.

Throws: See Bric::Util::Grp::list().

Side Effects: NONE.

Notes: This method returns the group IDs for the current object both as a Bric::Biz::Person object and as a Bric::Biz::Person::User object. [Actually, I've commented this out for now, since it seems more likely at this point that we'll want only the user group IDs, not also the person IDs. We can uncomment this later if we decide we need it, though.]
my (@groups || $groups_aref) = $u->get_grps
Returns a list or anonymous array of Bric::Biz::Group::User objects representing the groups of which this Bric::Biz::Person::User object is a member.

Use the Bric::Biz::Group::User instance method calls add_members() and delete_members() to associate and dissociate Bric::Biz::Person::User objects with any given Bric::Biz::Group::Person::User object.

Throws: See Bric::Util::Grp::Person::list().

Side Effects: Uses Bric::Util::Grp::User internally.

Notes: This method differs from the Bric::Biz::Person->get_grps() method in that it returns only those groups of which the person is a member as a user, rather than as a person.
my $pref_value = $u->get_pref($pref_name)
Given a preference name, such as "Language" or "Time Zone", this method returns the corresponding value, for this user. It first checks to see if the user has overridden the global value for this preference. If not, the global setting is returned.

Preference values are cached after the first lookup.

Throws: I do not have a clue
$self = $u->save
Saves the properties of the Bric::Biz::Person::User object to the database, including all changes made via the methods inherited from Bric::Biz::Person. Returns $self on success and undef on failure.

Throws:
- Bric::_get() - Problems retrieving fields.
- Unable to connect to database.
- Unable to prepare SQL statement.
- Unable to execute SQL statement.
- Unable to select row.
- Incorrect number of args to _set.
- Bric::_set() - Problems setting fields.
Side Effects: Also calls Bric::Biz::Person save() method.

Notes: See also Bric::Biz::Person save() method documentation.

PRIVATE

Private Class Methods

NONE.

Private Instance Methods

NONE.

Private Functions

my $users_aref = &$get_em( $pkg, $search_href )
my $user_ids_aref = &$get_em( $pkg, $search_href, 1 )
Function used by lookup() and list() to return a list of Bric::Biz::Person::User objects or, if called with an optional third argument, returns a list of Bric::Biz::Person::User object IDs (used by list_ids()).

Throws:
- Unable to prepare SQL statement.
- Unable to connect to database.
- Unable to select column into arrayref.
- Unable to execute SQL statement.
- Unable to bind to columns to statement handle.
- Unable to fetch row from statement handle.
Side Effects: NONE.

Notes: SQL in this function overrides the SQL used in the same function in Bric::Biz::Person.

NOTES

NONE.

AUTHOR

David Wheeler

NAME

VERSION

DATE

SYNOPSIS

DESCRIPTION

INTERFACE

Constructors

Destructors

Public Class Methods

Public Instance Methods

PRIVATE

Private Class Methods

Private Instance Methods

Private Functions

NOTES

AUTHOR

SEE ALSO