[Bio] / FigKernelPackages / UserData.pm Repository:
ViewVC logotype

View of /FigKernelPackages/UserData.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (download) (as text) (annotate)
Mon Nov 7 20:26:40 2005 UTC (14 years, 6 months ago) by parrello
Branch: MAIN
CVS Tags: caBIG-00-00-00
Added with documentation.

#!/usr/bin/perl -w

package UserData;

    require Exporter;
    @ISA = ('Exporter');
    @EXPORT = qw();
    @EXPORT_OK = qw();

    use strict;
    use Tracer;
    use PageBuilder;

=head1 FIG User Configuration Module

=head2 Introduction

The user data object allows the SEED to determine the privileges and
preferences of SEED users. This is not intended as an ironclad security
system; rather, its goal is to prevent one group stepping on another group's
work and to allow individual users to customize the look and feel of the
SEED.

=head3 Capabilities

Capabilities provide three access levels-- C<RW> (read-write), C<RO> (read-only),
and C<NO> (no access). Capabilities are managed using arbitrary classes of genomes
and subsystems called I<groups>. Groups are stored globally. Each group has a
name and a default access level. The default group is called C<normal> and has
a default access level of C<RW>.

Each user has a list of capabilities, each consisting of a group name and an
access level. A group name / access level pair is called a I<subscription>.
When a user attempts to access a subsystem or genome, we get the genome or
subsystem's group name and ask if the user has a subscription to the group.
If he does, the access level in the subscription is used. If he does not, the
default access level for the group is used.

If the user name is not known, the default user-- C<basic>-- will be used.
Initially, this default user will have no subscriptions, and as a result
will have default access to all genome and subsystem groups; however, if this
is not desirable it can be changed by adding subscriptions to the basic user
record.

=head3 Preferences

Preferences are simple key-value pairs. For each key, there is a single string
value. The key name cannot contain any white space. The keys are treated like
simple unformatted keys; however, it is highly recommened that the colon
character (C<:>) be used to separate the name into a category and a subkey
name. For example, C<genomes:columnList> would indicate the column-list
preference for the B<genomes> category. If the number of keys becomes
large, the category concept will enable us to restructure the data to reduce
the memory footprint.

=head2 Access Objects

This module does not access the actual data. Instead, it accepts as input
an I<access object>. The access object hides the details of data access
from the User Data object so that different data stores can be plugged
in. Currently, the access objects used by most of the SEED are the
B<FIG> and B<SFXlate> objects. FIG uses a combination of flat files and
database tables and supports both reads and updates. The SFXlate object
uses a pure database scheme and is mostly read-only.

=head3 GetDefault

C<< my ($group, $level) = $fig->GetDefault($objectID, $objectType); >>

Return the group name and default access level for the specified object.

=over 4

=item objectID

ID of the object whose capabilities data is desired.

=item objectType

Type of the object whose capabilities data is desired. This should be expressed
as a Sprout entity name. Currently, the only types supported are C<Genome>
and C<Subsystem>.

=item RETURN

Returns a two-element list. The first element is the name of the group
to witch the object belongs; the second is the default access level
(C<RW>, C<RO>, or C<NO>). If the object is not found, an empty list
should be returned.

=back

=head3 GetPreferences

C<< my $preferences = $fig->GetPreferences($userID, $category); >>

Return a map of preference keys to values for the specified user in the
specified category.

=over 4

=item userID

ID of the user whose preferences are desired.

=item category (optional)

Name of the category whose preferences are desired. If omitted, all
preferences should be returned.

=item RETURN

Returns a reference to a hash mapping each preference key to a value. The
keys are fully-qualified; in other words, the category name is included.
It is acceptable for the hash to contain key-value pairs outside the
category. In other words, if it's easier for you to read the entire
preference set into memory, you can return that one set every time
this method is called without worrying about the extra keys.

=back

=head3 GetCapability

C<< my $level = $fig->GetCapability($group, $userID); >>

Return the access level (C<RW>, C<RO>, or C<NO>) for the specified user
and the specified group, or C<undef> if the user wants the default
access for the group.

=over 4

=item group

Name of the group relevant to the desired user's activity.

=item userID

ID of the user whose access level is desired.

=item RETURN

Returns C<RW> if the user has full access, C<RO> if the user has read-only
access, C<NO> if the user is not allowed to even see items belonging
to the group, and C<undef> if the user should go with default access.

=back

=head3 AllowsUpdates

C<< my $flag = $fig->AllowsUpdates(); >>

Return TRUE if this access object supports updates, else FALSE. If the access object
does not support updates, none of the B<SetXXXX> methods will be called.

=head3 SetDefault

C<< $fig->SetDefault($objectID, $objectType, $group, $level); >>

Set the group and default access level for the specified object.

=over 4

=item objectID

ID of the object whose access level and group are to be set.

=item objectType

Type of the relevant object. This should be expressed as a Sprout entity name.
Currently, only C<Genome> and C<Subsystem> are supported.

=item group

Name of the group to which the object will belong. A user's access level for
this group will override the default access level.

=item level

Default access level. This is the access level used for user's who do not have
an explicit capability specified for the object's group.

=back

=head3 SetCapabilities

C<< $fig->SetCapabilities($userID, \%groupLevelMap); >>

Set the access levels by the specified user for the specified groups.

=over 4

=item userID

ID of the user whose capabilities are to be updated.

=item groupLevelMap

Reference to a hash that maps group names to access levels. The legal
access levels are C<RW> (read-write), C<RO> (read-only), and C<NO> (no
access). An undefined value for the access level indicates the default
level should be used for that group. The map will not replace all of
the user's capability date; instead, it overrides existing data, with
the undefined values indicating the specified group should be deleted
from the list.

=back

=head3 SetPreferences($userID, \%preferenceMap); >>

Set the preferences for the specified user.

=over 4

=item userID

ID of the user whose preferences are to be udpated.

=item preferenceMap

Reference to a hasn that maps each preference key to its value. The
keys should be fully-qualified (that is, they should include the
category name). A preference key mapped to an undefined value will
use the default preference value for that key. The map will not
replace all of the user's preference data; instead, it overrides
existing data, with the undefined values indicating the specified
preference should be deleted from the list.

=back

=cut

#: Constructor Capabilities->new();

=head2 Public Methods

=head3 new

C<< my $userdata = Capabilities->new($user, $fig); >>

Construct the capabilities object for a specified user.

=over 4

=item user

Name of the current user.

=item fig

Access object for retrieving user data.

=back

=cut

sub new {
    # Get the parameters.
    my ($class, $user, $fig) = @_;
    ## TODO ##
    # Create the userdata object.
    my $retVal = {
                  ##TODO
                 };
    # Bless and return it.
    bless $retVal;
    return $retVal;
}

=head3 GetCapability

C<< my $level = $fig->GetCapability($objectID, $objectType); >>

Get this user's access level for the specified object-- either C<RW> (full access),
C<RO> (read-only), or C<NO> (no access).

=over 4

=item objectID

ID of the relevant object.

=item objectType

Type of the relevant object. This should be the Sprout entity name for the
object type. Currently, only C<Subsystem> and C<Genome> are supported.

=item RETURN

Returns C<RW> if the user has full-acess, C<RO> if the user has read-only
access, and C<NO> if the user should not have any access to the object.

=back

=cut

sub GetCapability {
    #TODO
}

=head3 GetPreference

C<< my $value = $fig->GetPreference($key); >>

Return the user's preference value for the specified key.

=over 4

=item key

Fully-qualified key for the preference value.

=item RETURN

Returns the preference value for the key. If the user has no explicit preference
value for that key, returns the corresponding value for the default user.

=back

=cut

sub GetPreference {
    #TODO
}

=head3 SetCapabilities

C<< $fig->SetCapabilities(\%groupMap); >>

Set capabilities for this user. This does not replace all existing capabilities.
Instead, the capabilities specified in the group map are updated or deleted,
and any capabilities not specified are unchanged.

=over 4

=item groupMap

Reference to a hash mapping group names to access levels (C<RW> full access,
C<RO> read-only access, C<NO> no access) or an undefined value if the user
is to have default access to the specified group.

=back

=cut

sub SetCapabilities {
    #TODO
}

=head3 SetPreferences(\%preferences); >>

Set preferences for this user. This does not replace all existing preferences.
Instead, the preferences specified in the map are updated or deleted, and any
preferences not specified are unchanged.

=over 4

=item preferences

Reference to a hash mapping key names to preference values. Mapping a key
name to an undefined value indicates that the default preference value
should be used.

=back

=cut

sub SetPreferences {
    #TODO
}

=head3 SetDefault

C<< $fig->SetDefault($objectID, $objectType, $group, $level); >>

Set the group and default access level for the specified object.

=over 4

=item objectID

ID of the object whose access level and group are to be set.

=item objectType

Type of the relevant object. This should be expressed as a Sprout entity name.
Currently, only C<Genome> and C<Subsystem> are supported.

=item group

Name of the group to which the object will belong. A user's access level for
this group will override the default access level.

=item level

Default access level. This is the access level used for user's who do not have
an explicit capability specified for the object's group.

=back

=cut

sub SetDefault {
    #TODO
}

1;


MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3