NAME

Contentment::Security::Principal - object for representing principals

DESCRIPTION

This generic object is used by the Contentment security system to represent principals. A principal represents the client's identity. This principal is meant to allow for "identity" to be fairly losely defined. However, each identity should have the following attributes:

type

The type of the identity is a scalar that is useful to the security manager (see Contentment::Security::Manager). It can be used when a security manager needs to identify different kinds of principals. For example, the built-in system uses two types: "authenticated" and "anonymous".

profile

The profile for the principal stores the real information for the principal. Some convenience methods are applied to grab this data without referring to the profile directly.

roles

The principal may have zero or more roles associated with it.

permissions

The really important aspect of the princpal is that it has zero or more permissions associated with it.

METHODS

Every principal object defines the following methods:

$type = $principal->type

Returns the principal type. Since this value could be anything useful to the security manager, it's probably best if the plugins avoid relying upon this value.

$profile = $principal->profile

The $profile object returned will be an object implementing the interface given in Contentment::Security::Profile.

@roles = @{ $principal->roles }

Returns a list of role objects (of type Contentment::Security::Role) associated with the principal.

%permissions = %{ $principal->permissions }

Returns a hash of permission objects (of type Contentment::Security::Permission) associated with the principal. The keys will be the string names for the permissions and the values will be the actual permission object for that permission name.

$username = $principal->username

A short-hand for:

$username = $principal->profile->username

$full_name = $principal->full_name

A short-hand for:

$full_name = $principal->profile->full_name

$email_address = $principal->email_address

A short-hand for:

$email_address = $principal->profile->email_address

$web_site = $principal->web_site

A short-hand for:

$web_site = $principal->profile->web_site

$information = $principal->information

A short-hand for:

$information = $principal->profile->information

$preferences = $principal->preferences

A short-hand for:

$preferences = $principal->profile->preferences

SECURITY MANAGER METHODS

The following methods are provided for use by security managers only. Only code in the security managers should muck with these. PERIOD.

$principal = Contentment::Security::Principal->new;

Returns a blank principal object.

$principal->type($type)

Sets the type of the principal.

$principal->profile($profile)

Sets the profile for the principal.

$principal->roles(\@roles)

Sets the roles that have been associated with the profile.

$principal->update_permissions

This method loads all the permissions associated with the roles set on the roles attribute.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2005 Andrew Sterling Hanenkamp <hanenkamp@cpan.org>. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.