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

$LastChangedRevision$

$LastChangedDate: 2004-11-08 12:02:25 -0800 (Mon, 08 Nov 2004) $

  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;

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

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 CW$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. 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, CWlookup() returns CWundef. 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. 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:

*

prefix

*

lname

*

fname

*

mname

*

suffix

*

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

$p->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY. Throws:> NONE. Side Effects: NONE. Notes: NONE.

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. Returns true if CW$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

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 CWid, 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.

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. 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 CWsaved, the object will not yet have an ID, so this method call will return undef. 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. 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. Sets the login name of the user. Be sure to call CW$u->save to save the change to the database. Returns CW$self on success and undef on failure. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the user's password. Uses a double MD-5 hash algorithm to encrypt it. Be sure to call CW$u->save to save the change to the database. Returns CW$self on success and undef on failure. Throws:

*

Incorrect number of args to Bric::_set().

*

Bric::set() - Problems setting fields. Side Effects: NONE. Notes: Uses the double MD-5 has rather than Perl's builtin crupt() function because, on my box at least, crypt() uses on the first 8 letters (bytes) of the password. Anything else is added junk. This isn't too cool, IMHO, so I went with MD-5, which supports passwords of any length. We may want to switch back to crypt(), however, in order to use the Apache::AuthDBI modules. But we should get a crypt on the system that uses all the bytes passed to it. Returns true if CW$password matches the password stored for this user. Returns undef if they don't match. Uses a double MD-5 hash algorithm to encrypt CW$password and then compare it to the value stored in the database. Returns CW$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(). Takes an object CW$obj or package name CW$pkg and returns the permission (as exported by Bric::Util::Priv::Parts::Const) that the user object has to CW$obj, or to the All group in CW$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 CW$obj is a member. Thus you can affect the permission returned by CW$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. Checks to see if the user has the privilege to perform an action. CW$obj is the object for which the user's privilege must be checked and CW$priv is the privilege required to perform the action. Returns CW$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. Exactly the same as CW$u->can_do, except that it returns CW$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. ;-) Flags the Bric::Biz::Person::User object as an active user in Bricolage. Be sure to call CW$u->save to save the change to the database. Returns CW$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 CW$self on success and undef on failure. Flags the Bric::Biz::Person::User object as an inactive user in Bricolage. Be sure to call CW$u->save to save the change to the database. Returns CW$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. Returns CW$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. ################################################################################ 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.] 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. 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 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 CW$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.

NONE.

NONE.

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.

NONE.

David Wheeler <david@wheeler.net>

Bric, Bric::Biz::Person