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

Diff of /FigKernelPackages/UserData.pm

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1, Mon Nov 7 20:26:40 2005 UTC revision 1.6, Thu Dec 6 13:59:34 2007 UTC
# Line 1  Line 1 
1  #!/usr/bin/perl -w  #!/usr/bin/perl -w
2    #
3    # Copyright (c) 2003-2006 University of Chicago and Fellowship
4    # for Interpretations of Genomes. All Rights Reserved.
5    #
6    # This file is part of the SEED Toolkit.
7    #
8    # The SEED Toolkit is free software. You can redistribute
9    # it and/or modify it under the terms of the SEED Toolkit
10    # Public License.
11    #
12    # You should have received a copy of the SEED Toolkit Public License
13    # along with this program; if not write to the University of Chicago
14    # at info@ci.uchicago.edu or the Fellowship for Interpretation of
15    # Genomes at veronika@thefig.info or download a copy from
16    # http://www.theseed.org/LICENSE.TXT.
17    #
18    
19    
20  package UserData;  package UserData;
21    
# Line 53  Line 70 
70  large, the category concept will enable us to restructure the data to reduce  large, the category concept will enable us to restructure the data to reduce
71  the memory footprint.  the memory footprint.
72    
73    Every user has his own set of preferences. The default user C<basic> should
74    have a complete set of preferences; if a preference is not specified for a
75    particular user, the basic user's value will be used instead.
76    
77  =head2 Access Objects  =head2 Access Objects
78    
79  This module does not access the actual data. Instead, it accepts as input  This module does not access the actual data. Instead, it accepts as input
# Line 63  Line 84 
84  database tables and supports both reads and updates. The SFXlate object  database tables and supports both reads and updates. The SFXlate object
85  uses a pure database scheme and is mostly read-only.  uses a pure database scheme and is mostly read-only.
86    
87  =head3 GetDefault  #: Constructor UserData->new();
88    
89  C<< my ($group, $level) = $fig->GetDefault($objectID, $objectType); >>  =head2 Public Methods
90    
91  Return the group name and default access level for the specified object.  =head3 new
92    
93        my $userData = UserData->new($user, $fig);
94    
95    Construct the capabilities object for a specified user.
96    
97    =over 4
98    
99    =item user
100    
101    Name of the current user.
102    
103    =item fig
104    
105    Access object for retrieving user data.
106    
107    =back
108    
109    =cut
110    
111    sub new {
112        # Get the parameters.
113        my ($class, $user, $fig) = @_;
114        # Get the user's capabilities.
115        my $capable = $fig->GetCapabilities($user);
116        # Create the userdata object.
117        my $retVal = {
118                      capable => $capable,
119                      newCapable => { },
120                      user => $user,
121                      preferences => { },
122                      newPreferences => { },
123                      fig => $fig
124                     };
125        # Bless and return it.
126        bless $retVal, $class;
127        return $retVal;
128    }
129    
130    =head3 GetCapability
131    
132        my $level = $userData->GetCapability($objectID, $objectType);
133    
134    Get this user's access level for the specified object-- either C<RW> (full access),
135    C<RO> (read-only), or C<NO> (no access).
136    
137  =over 4  =over 4
138    
139  =item objectID  =item objectID
140    
141  ID of the object whose capabilities data is desired.  ID of the relevant object.
142    
143  =item objectType  =item objectType
144    
145  Type of the object whose capabilities data is desired. This should be expressed  Type of the relevant object. This should be the Sprout entity name for the
146  as a Sprout entity name. Currently, the only types supported are C<Genome>  object type. Currently, only C<Subsystem> and C<Genome> are supported.
 and C<Subsystem>.  
147    
148  =item RETURN  =item RETURN
149    
150  Returns a two-element list. The first element is the name of the group  Returns C<RW> if the user has full access, C<RO> if the user has read-only
151  to witch the object belongs; the second is the default access level  access, and C<NO> if the user should not have any access to the object.
 (C<RW>, C<RO>, or C<NO>). If the object is not found, an empty list  
 should be returned.  
152    
153  =back  =back
154    
155  =head3 GetPreferences  =cut
156    
157  C<< my $preferences = $fig->GetPreferences($userID, $category); >>  sub GetCapability {
158        # Get the parameters.
159        my ($self, $objectID, $objectType) = @_;
160        # Look for the group and default access level of the target object.
161        my ($group, $level) = $self->{fig}->GetDefault($objectID, $objectType);
162        # If it wasn't found, the group is 'normal' and the access level is RW.
163        if (! $group) {
164            ($group, $level) = ('normal', 'RW');
165        }
166        # If this group is in the user's capability hash, we use the result to
167        # override the level.
168        if (exists $self->{capable}->{$group}) {
169            $level = $self->{capable}->{$group};
170        }
171        # Return the level.
172        return $level;
173    }
174    
175  Return a map of preference keys to values for the specified user in the  =head3 GetPreference
 specified category.  
176    
177  =over 4      my $value = $userData->GetPreference($key);
178    
179  =item userID  Return the user's preference value for the specified key.
180    
181  ID of the user whose preferences are desired.  =over 4
182    
183  =item category (optional)  =item key
184    
185  Name of the category whose preferences are desired. If omitted, all  Fully-qualified key for the preference value.
 preferences should be returned.  
186    
187  =item RETURN  =item RETURN
188    
189  Returns a reference to a hash mapping each preference key to a value. The  Returns the preference value for the key. If the user has no explicit preference
190  keys are fully-qualified; in other words, the category name is included.  value for that key, returns the corresponding value for the default user.
 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.  
191    
192  =back  =back
193    
194  =head3 GetCapability  =cut
195    
196  C<< my $level = $fig->GetCapability($group, $userID); >>  sub GetPreference {
197        # Get the parameters.
198        my ($self, $key) = @_;
199        # Extract the category name.
200        my $category = ParseCategory($key);
201        # Insure this category is in memory.
202        my $categoryHash = $self->GetCategoryHash($category);
203        # Return the value for the specified preference key.
204        my $retVal = $categoryHash->{$key};
205        return $retVal;
206    }
207    
208  Return the access level (C<RW>, C<RO>, or C<NO>) for the specified user  =head3 SetCapabilities
209  and the specified group, or C<undef> if the user wants the default  
210  access for the group.      $userData->SetCapabilities(\%groupMap);
211    
212    Set capabilities for this user. This does not replace all existing capabilities.
213    Instead, the capabilities specified in the group map are updated or deleted,
214    and any capabilities not specified are unchanged. Note that the actual changes
215    are cached in memory, and are not written until the L</SaveChanges> method is
216    called.
217    
218  =over 4  =over 4
219    
220  =item group  =item groupMap
221    
222  Name of the group relevant to the desired user's activity.  Reference to a hash mapping group names to access levels (C<RW> full access,
223    C<RO> read-only access, C<NO> no access) or an undefined value if the user
224    is to have default access to the specified group.
225    
226  =item userID  =back
227    
228  ID of the user whose access level is desired.  =cut
229    
230  =item RETURN  sub SetCapabilities {
231        # Get the parameters.
232        my ($self, $groupMap) = @_;
233        # Loop through the settings, adding them to the update hash and the actual
234        # hash. The update hash is used when we save changes. The actual hash
235        # needs to be updated as well so that the new values are retrieved when
236        # the client asks for capability data.
237        my $accessMap = $self->{capable};
238        my $changeMap = $self->{newCapable};
239        for my $group (keys %{$groupMap}) {
240            $accessMap->{$group} = $groupMap->{$group};
241            $changeMap->{$group} = $groupMap->{$group};
242        }
243    }
244    
245  Returns C<RW> if the user has full access, C<RO> if the user has read-only  =head3 SetPreferences
 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.  
246    
247  =back      $userData->SetPreferences(\%preferences);
248    
249  =head3 AllowsUpdates  Set preferences for this user. This does not replace all existing preferences.
250    Instead, the preferences specified in the map are updated or deleted, and any
251    preferences not specified are unchanged. Note that the settings are not changed.
252    Instead, the changes are cached in memory until the L</SaveChanges> method is
253    called.
254    
255  C<< my $flag = $fig->AllowsUpdates(); >>  =over 4
256    
257  Return TRUE if this access object supports updates, else FALSE. If the access object  =item preferences
258  does not support updates, none of the B<SetXXXX> methods will be called.  
259    Reference to a hash mapping key names to preference values. Mapping a key
260    name to an undefined value indicates that the default preference value
261    should be used.
262    
263    =back
264    
265    =cut
266    
267    sub SetPreferences {
268        # Get the parameters.
269        my ($self, $preferences) = @_;
270        # Loop through the settings. Each one is added to the main hash and then
271        # cached in the update hash.
272        my $changeMap = $self->{newPreferences};
273        for my $key (keys %{$preferences}) {
274            # Extract the category name from the key.
275            my $category = ParseCategory($key);
276            # Insure we have the category in memory.
277            my $hash = $self->GetCategoryHash($category);
278            # Add the new value to the category hash.
279            $hash->{$key} = $preferences->{$key};
280            # Add it to the update hash.
281            $changeMap->{$key} = $preferences->{$key};
282        }
283    }
284    
285  =head3 SetDefault  =head3 SetDefault
286    
287  C<< $fig->SetDefault($objectID, $objectType, $group, $level); >>      $userData->SetDefault($objectID, $objectType, $group, $level);
288    
289  Set the group and default access level for the specified object.  Set the group and default access level for the specified object. This update
290    takes place immediately.
291    
292  =over 4  =over 4
293    
# Line 181  Line 312 
312    
313  =back  =back
314    
315  =head3 SetCapabilities  =cut
316    
317  C<< $fig->SetCapabilities($userID, \%groupLevelMap); >>  sub SetDefault {
318        # Get the parameters.
319        my ($self, $objectID, $objectType, $group, $level) = @_;
320        # Call the access method.
321        $self->{fig}->SetDefault($objectID, $objectType, $group, $level);
322    }
323    
324  Set the access levels by the specified user for the specified groups.  =head3 SaveChanges
325    
326  =over 4      $userData->SaveChanges();
327    
328  =item userID  Store accumulated preference and capability changes.
   
 ID of the user whose capabilities are to be updated.  
329    
330  =item groupLevelMap  =cut
331    
332  Reference to a hash that maps group names to access levels. The legal  sub SaveChanges {
333  access levels are C<RW> (read-write), C<RO> (read-only), and C<NO> (no      # Get the parameters.
334  access). An undefined value for the access level indicates the default      my ($self) = @_;
335  level should be used for that group. The map will not replace all of      # Check for capability updates.
336  the user's capability date; instead, it overrides existing data, with      my $capabilityUpdates = $self->{newCapable};
337  the undefined values indicating the specified group should be deleted      if (keys %{$capabilityUpdates}) {
338  from the list.          $self->{fig}->SetCapabilities($self->{user}, $capabilityUpdates);
339        }
340        # Check for preference updates.
341        my $preferenceUpdates = $self->{newPreferences};
342        if (keys %{$preferenceUpdates}) {
343            $self->{fig}->SetPreferences($self->{user}, $preferenceUpdates);
344        }
345    }
346    
347  =back  =head3 ParseCategory
348    
349  =head3 SetPreferences($userID, \%preferenceMap); >>      my $category = UserData::ParseCategory($key);
350    
351  Set the preferences for the specified user.  Return the category name from the specified preference key. If no category is
352    specified, an error will occur.
353    
354  =over 4  =over 4
355    
356  =item userID  =item key
357    
358  ID of the user whose preferences are to be udpated.  Preference key, which consists of alphanumeric characters with colons separating
359    the sections.
360    
361  =item preferenceMap  =item RETURN
362    
363  Reference to a hasn that maps each preference key to its value. The  Returns the category name from the specified key.
 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.  
364    
365  =back  =back
366    
367  =cut  =cut
368    
369  #: Constructor Capabilities->new();  sub ParseCategory {
370        # Get the parameters.
371  =head2 Public Methods      my ($key) = @_;
372        # Declare the return variable.
373        my $retVal;
374        # Try to parse out the category.
375        if ($key =~ /([^:]+):/) {
376            # Return the category.
377            $retVal = $1;
378        } else {
379            # Here we have no category, so it's an error.
380            Confess("No category specified on preference key \"$key\".");
381        }
382        return $retVal;
383    }
384    
385  =head3 new  =head3 GetCategoryHash
386    
387  C<< my $userdata = Capabilities->new($user, $fig); >>      my $categoryHash = $self->GetCategoryHash($category);
388    
389  Construct the capabilities object for a specified user.  Return the hash for the specified category. If it is not in memory, it
390    will be read in.
391    
392  =over 4  =over 4
393    
394  =item user  =item key
395    
396  Name of the current user.  Preference key, which consists of alphanumeric characters with colons separating
397    the sections.
398    
399  =item fig  =item RETURN
400    
401  Access object for retrieving user data.  Returns the category name from the specified key.
402    
403  =back  =back
404    
405  =cut  =cut
406    
407  sub new {  sub GetCategoryHash {
408      # Get the parameters.      # Get the parameters.
409      my ($class, $user, $fig) = @_;      my ($self, $category) = @_;
410      ## TODO ##      # Declare the return variable.
411      # Create the userdata object.      my $retVal;
412      my $retVal = {      # Check to see if we have preferences for this category. If not, we need
413                    ##TODO      # to read them in.
414                   };      if (! exists $self->{preferences}->{$category}) {
415      # Bless and return it.          # Get the default preferences if this is not the default user.
416      bless $retVal;          my $defaults = {};
417            if ($self->{user} ne 'basic') {
418                $defaults = $self->{fig}->GetPreferences('basic', $category);
419            }
420            # Get the user's preferences and merge them in.
421            my $overrides = $self->{fig}->GetPreferences($self->{user}, $category);
422            for my $key0 (%{$overrides}) {
423                $defaults->{$key0} = $overrides->{$key0};
424            }
425            # Add the new hash to the preferences hash.
426            $self->{preferences}->{$category} = $defaults;
427            # Return it.
428            $retVal = $defaults;
429        } else {
430            # Here the hash is already in memory.
431            $retVal = $self->{preferences}->{$category};
432        }
433        # Return the category hash.
434      return $retVal;      return $retVal;
435  }  }
436    
437  =head3 GetCapability  =head2 Access Object Methods
438    
439  C<< my $level = $fig->GetCapability($objectID, $objectType); >>  The following methods must be implemented by the access object (e.g. I<$fig>) passed
440    to the constructor.
441    
442  Get this user's access level for the specified object-- either C<RW> (full access),  =head3 GetDefault
443  C<RO> (read-only), or C<NO> (no access).  
444        my ($group, $level) = $fig->GetDefault($objectID, $objectType);
445    
446    Return the group name and default access level for the specified object.
447    
448  =over 4  =over 4
449    
450  =item objectID  =item objectID
451    
452  ID of the relevant object.  ID of the object whose capabilities data is desired.
453    
454  =item objectType  =item objectType
455    
456  Type of the relevant object. This should be the Sprout entity name for the  Type of the object whose capabilities data is desired. This should be expressed
457  object type. Currently, only C<Subsystem> and C<Genome> are supported.  as a Sprout entity name. Currently, the only types supported are C<Genome>
458    and C<Subsystem>.
459    
460  =item RETURN  =item RETURN
461    
462  Returns C<RW> if the user has full-acess, C<RO> if the user has read-only  Returns a two-element list. The first element is the name of the group
463  access, and C<NO> if the user should not have any access to the object.  to witch the object belongs; the second is the default access level
464    (C<RW>, C<RO>, or C<NO>). If the object is not found, an empty list
465    should be returned.
466    
467  =back  =back
468    
469  =cut  =head3 GetPreferences
470    
471  sub GetCapability {      my $preferences = $fig->GetPreferences($userID, $category);
     #TODO  
 }  
472    
473  =head3 GetPreference  Return a map of preference keys to values for the specified user in the
474    specified category.
475    
476  C<< my $value = $fig->GetPreference($key); >>  =over 4
477    
478  Return the user's preference value for the specified key.  =item userID
479    
480  =over 4  ID of the user whose preferences are desired.
481    
482  =item key  =item category (optional)
483    
484  Fully-qualified key for the preference value.  Name of the category whose preferences are desired. If omitted, all
485    preferences should be returned.
486    
487  =item RETURN  =item RETURN
488    
489  Returns the preference value for the key. If the user has no explicit preference  Returns a reference to a hash mapping each preference key to a value. The
490  value for that key, returns the corresponding value for the default user.  keys are fully-qualified; in other words, the category name is included.
491    It is acceptable for the hash to contain key-value pairs outside the
492    category. In other words, if it's easier for you to read the entire
493    preference set into memory, you can return that one set every time
494    this method is called without worrying about the extra keys.
495    
496  =back  =back
497    
498  =cut  =head3 GetCapabilities
499    
500  sub GetPreference {      my $level = $fig->GetCapabilities($userID);
     #TODO  
 }  
   
 =head3 SetCapabilities  
501    
502  C<< $fig->SetCapabilities(\%groupMap); >>  Return a map of group names to access levels (C<RW>, C<RO>, or C<NO>) for the
503    specified user.
 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.  
504    
505  =over 4  =over 4
506    
507  =item groupMap  =item userID
   
 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.  
508    
509  =over 4  ID of the user whose access level is desired.
510    
511  =item preferences  =item RETURN
512    
513  Reference to a hash mapping key names to preference values. Mapping a key  Returns a reference to a hash mapping group names to the user's access level
514  name to an undefined value indicates that the default preference value  for that group.
 should be used.  
515    
516  =back  =back
517    
518  =cut  =head3 AllowsUpdates
519    
520  sub SetPreferences {      my $flag = $fig->AllowsUpdates();
521      #TODO  
522  }  Return TRUE if this access object supports updates, else FALSE. If the access object
523    does not support updates, none of the B<SetXXXX> methods will be called.
524    
525  =head3 SetDefault  =head3 SetDefault
526    
527  C<< $fig->SetDefault($objectID, $objectType, $group, $level); >>      $fig->SetDefault($objectID, $objectType, $group, $level);
528    
529  Set the group and default access level for the specified object.  Set the group and default access level for the specified object.
530    
# Line 397  Line 551 
551    
552  =back  =back
553    
554  =cut  =head3 SetCapabilities
555    
556  sub SetDefault {      $fig->SetCapabilities($userID, \%groupLevelMap);
     #TODO  
 }  
557    
558  1;  Set the access levels by the specified user for the specified groups.
559    
560    =over 4
561    
562    =item userID
563    
564    ID of the user whose capabilities are to be updated.
565    
566    =item groupLevelMap
567    
568    Reference to a hash that maps group names to access levels. The legal
569    access levels are C<RW> (read-write), C<RO> (read-only), and C<NO> (no
570    access). An undefined value for the access level indicates the default
571    level should be used for that group. The map will not replace all of
572    the user's capability date; instead, it overrides existing data, with
573    the undefined values indicating the specified group should be deleted
574    from the list.
575    
576    =back
577    
578    =head3 SetPreferences
579    
580        $fig->SetPreferences($userID, \%preferenceMap);
581    
582    Set the preferences for the specified user.
583    
584    =over 4
585    
586    =item userID
587    
588    ID of the user whose preferences are to be udpated.
589    
590    =item preferenceMap
591    
592    Reference to a hash that maps each preference key to its value. The
593    keys should be fully-qualified (that is, they should include the
594    category name). A preference key mapped to an undefined value will
595    use the default preference value for that key. The map will not
596    replace all of the user's preference data; instead, it overrides
597    existing data, with the undefined values indicating the specified
598    preference should be deleted from the list.
599    
600    =back
601    
602    =head3 CleanupUserData
603    
604        $fig->CleanupUserData();
605    
606    Release any data being held in memory for use by the UserData object.
607    
608    =head2 Fields
609    
610    The user data object contains the following fields.
611    
612    =over 4
613    
614    =item capable
615    
616    Reference to a hash containing all the user's capability data.
617    
618    =item preferences
619    
620    Reference to a hash of hashes. The key of the large hash is the preference
621    category, and the value is a small hash mapping preferences from that
622    category to values.
623    
624    =item userID
625    
626    Current user's ID.
627    
628    =item fig
629    
630    Fig-like object for accessing the data.
631    
632    =item newCapable
633    
634    Hash containing updated capabilities.
635    
636    =item newPreferences
637    
638    Hash containing updated preferences.
639    
640    =back
641    
642    =cut
643    
644    1;

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.6

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3