Bric::Biz::Person::UseUser)Contributed Perl DocumenBric::Biz::Person::User(3p)



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

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-06-14 05:25:10 +0200 (Wed, 14 Jun 2006) $

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:

           o   lname

           o   fname

           o   mname

           o   prefix

           o   suffix

           o   login

           Call $u->save() to save the new object.

           Throws:

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

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

           o   id - Returns the User with that ID, if it exists.

           o   login - Returns the active User with that login, if it exists.
               Inactive users with that login will be ignored.

           Throws:

           o   Too many Bric::Biz::Person::User objects found.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

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

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: READ access for field 'id' required.

           o   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 "save"d, 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:

           o   Cannot change ID of existing user.

           o   Bric::_get() - Problems retrieving fields.

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

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

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

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: READ access for field 'login' required.

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

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

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

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

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

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

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

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

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

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

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

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

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

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

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

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

           o   Unable to select row.

           o   Incorrect number of args to _set.

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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 <david@justatheory.com>

SEE ALSO
       Bric, Bric::Biz::Person



perl v5.12.2                      2006-06-13       Bric::Biz::Person::User(3p)
