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

Annotation of /FigKernelPackages/UserData.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (view) (download) (as text)

1 : parrello 1.1 #!/usr/bin/perl -w
2 :    
3 :     package UserData;
4 :    
5 :     require Exporter;
6 :     @ISA = ('Exporter');
7 :     @EXPORT = qw();
8 :     @EXPORT_OK = qw();
9 :    
10 :     use strict;
11 :     use Tracer;
12 :     use PageBuilder;
13 :    
14 :     =head1 FIG User Configuration Module
15 :    
16 :     =head2 Introduction
17 :    
18 :     The user data object allows the SEED to determine the privileges and
19 :     preferences of SEED users. This is not intended as an ironclad security
20 :     system; rather, its goal is to prevent one group stepping on another group's
21 :     work and to allow individual users to customize the look and feel of the
22 :     SEED.
23 :    
24 :     =head3 Capabilities
25 :    
26 :     Capabilities provide three access levels-- C<RW> (read-write), C<RO> (read-only),
27 :     and C<NO> (no access). Capabilities are managed using arbitrary classes of genomes
28 :     and subsystems called I<groups>. Groups are stored globally. Each group has a
29 :     name and a default access level. The default group is called C<normal> and has
30 :     a default access level of C<RW>.
31 :    
32 :     Each user has a list of capabilities, each consisting of a group name and an
33 :     access level. A group name / access level pair is called a I<subscription>.
34 :     When a user attempts to access a subsystem or genome, we get the genome or
35 :     subsystem's group name and ask if the user has a subscription to the group.
36 :     If he does, the access level in the subscription is used. If he does not, the
37 :     default access level for the group is used.
38 :    
39 :     If the user name is not known, the default user-- C<basic>-- will be used.
40 :     Initially, this default user will have no subscriptions, and as a result
41 :     will have default access to all genome and subsystem groups; however, if this
42 :     is not desirable it can be changed by adding subscriptions to the basic user
43 :     record.
44 :    
45 :     =head3 Preferences
46 :    
47 :     Preferences are simple key-value pairs. For each key, there is a single string
48 :     value. The key name cannot contain any white space. The keys are treated like
49 :     simple unformatted keys; however, it is highly recommened that the colon
50 :     character (C<:>) be used to separate the name into a category and a subkey
51 :     name. For example, C<genomes:columnList> would indicate the column-list
52 :     preference for the B<genomes> category. If the number of keys becomes
53 :     large, the category concept will enable us to restructure the data to reduce
54 :     the memory footprint.
55 :    
56 :     =head2 Access Objects
57 :    
58 :     This module does not access the actual data. Instead, it accepts as input
59 :     an I<access object>. The access object hides the details of data access
60 :     from the User Data object so that different data stores can be plugged
61 :     in. Currently, the access objects used by most of the SEED are the
62 :     B<FIG> and B<SFXlate> objects. FIG uses a combination of flat files and
63 :     database tables and supports both reads and updates. The SFXlate object
64 :     uses a pure database scheme and is mostly read-only.
65 :    
66 :     =head3 GetDefault
67 :    
68 :     C<< my ($group, $level) = $fig->GetDefault($objectID, $objectType); >>
69 :    
70 :     Return the group name and default access level for the specified object.
71 :    
72 :     =over 4
73 :    
74 :     =item objectID
75 :    
76 :     ID of the object whose capabilities data is desired.
77 :    
78 :     =item objectType
79 :    
80 :     Type of the object whose capabilities data is desired. This should be expressed
81 :     as a Sprout entity name. Currently, the only types supported are C<Genome>
82 :     and C<Subsystem>.
83 :    
84 :     =item RETURN
85 :    
86 :     Returns a two-element list. The first element is the name of the group
87 :     to witch the object belongs; the second is the default access level
88 :     (C<RW>, C<RO>, or C<NO>). If the object is not found, an empty list
89 :     should be returned.
90 :    
91 :     =back
92 :    
93 :     =head3 GetPreferences
94 :    
95 :     C<< my $preferences = $fig->GetPreferences($userID, $category); >>
96 :    
97 :     Return a map of preference keys to values for the specified user in the
98 :     specified category.
99 :    
100 :     =over 4
101 :    
102 :     =item userID
103 :    
104 :     ID of the user whose preferences are desired.
105 :    
106 :     =item category (optional)
107 :    
108 :     Name of the category whose preferences are desired. If omitted, all
109 :     preferences should be returned.
110 :    
111 :     =item RETURN
112 :    
113 :     Returns a reference to a hash mapping each preference key to a value. The
114 :     keys are fully-qualified; in other words, the category name is included.
115 :     It is acceptable for the hash to contain key-value pairs outside the
116 :     category. In other words, if it's easier for you to read the entire
117 :     preference set into memory, you can return that one set every time
118 :     this method is called without worrying about the extra keys.
119 :    
120 :     =back
121 :    
122 :     =head3 GetCapability
123 :    
124 :     C<< my $level = $fig->GetCapability($group, $userID); >>
125 :    
126 :     Return the access level (C<RW>, C<RO>, or C<NO>) for the specified user
127 :     and the specified group, or C<undef> if the user wants the default
128 :     access for the group.
129 :    
130 :     =over 4
131 :    
132 :     =item group
133 :    
134 :     Name of the group relevant to the desired user's activity.
135 :    
136 :     =item userID
137 :    
138 :     ID of the user whose access level is desired.
139 :    
140 :     =item RETURN
141 :    
142 :     Returns C<RW> if the user has full access, C<RO> if the user has read-only
143 :     access, C<NO> if the user is not allowed to even see items belonging
144 :     to the group, and C<undef> if the user should go with default access.
145 :    
146 :     =back
147 :    
148 :     =head3 AllowsUpdates
149 :    
150 :     C<< my $flag = $fig->AllowsUpdates(); >>
151 :    
152 :     Return TRUE if this access object supports updates, else FALSE. If the access object
153 :     does not support updates, none of the B<SetXXXX> methods will be called.
154 :    
155 :     =head3 SetDefault
156 :    
157 :     C<< $fig->SetDefault($objectID, $objectType, $group, $level); >>
158 :    
159 :     Set the group and default access level for the specified object.
160 :    
161 :     =over 4
162 :    
163 :     =item objectID
164 :    
165 :     ID of the object whose access level and group are to be set.
166 :    
167 :     =item objectType
168 :    
169 :     Type of the relevant object. This should be expressed as a Sprout entity name.
170 :     Currently, only C<Genome> and C<Subsystem> are supported.
171 :    
172 :     =item group
173 :    
174 :     Name of the group to which the object will belong. A user's access level for
175 :     this group will override the default access level.
176 :    
177 :     =item level
178 :    
179 :     Default access level. This is the access level used for user's who do not have
180 :     an explicit capability specified for the object's group.
181 :    
182 :     =back
183 :    
184 :     =head3 SetCapabilities
185 :    
186 :     C<< $fig->SetCapabilities($userID, \%groupLevelMap); >>
187 :    
188 :     Set the access levels by the specified user for the specified groups.
189 :    
190 :     =over 4
191 :    
192 :     =item userID
193 :    
194 :     ID of the user whose capabilities are to be updated.
195 :    
196 :     =item groupLevelMap
197 :    
198 :     Reference to a hash that maps group names to access levels. The legal
199 :     access levels are C<RW> (read-write), C<RO> (read-only), and C<NO> (no
200 :     access). An undefined value for the access level indicates the default
201 :     level should be used for that group. The map will not replace all of
202 :     the user's capability date; instead, it overrides existing data, with
203 :     the undefined values indicating the specified group should be deleted
204 :     from the list.
205 :    
206 :     =back
207 :    
208 :     =head3 SetPreferences($userID, \%preferenceMap); >>
209 :    
210 :     Set the preferences for the specified user.
211 :    
212 :     =over 4
213 :    
214 :     =item userID
215 :    
216 :     ID of the user whose preferences are to be udpated.
217 :    
218 :     =item preferenceMap
219 :    
220 :     Reference to a hasn that maps each preference key to its value. The
221 :     keys should be fully-qualified (that is, they should include the
222 :     category name). A preference key mapped to an undefined value will
223 :     use the default preference value for that key. The map will not
224 :     replace all of the user's preference data; instead, it overrides
225 :     existing data, with the undefined values indicating the specified
226 :     preference should be deleted from the list.
227 :    
228 :     =back
229 :    
230 :     =cut
231 :    
232 :     #: Constructor Capabilities->new();
233 :    
234 :     =head2 Public Methods
235 :    
236 :     =head3 new
237 :    
238 :     C<< my $userdata = Capabilities->new($user, $fig); >>
239 :    
240 :     Construct the capabilities object for a specified user.
241 :    
242 :     =over 4
243 :    
244 :     =item user
245 :    
246 :     Name of the current user.
247 :    
248 :     =item fig
249 :    
250 :     Access object for retrieving user data.
251 :    
252 :     =back
253 :    
254 :     =cut
255 :    
256 :     sub new {
257 :     # Get the parameters.
258 :     my ($class, $user, $fig) = @_;
259 :     ## TODO ##
260 :     # Create the userdata object.
261 :     my $retVal = {
262 :     ##TODO
263 :     };
264 :     # Bless and return it.
265 :     bless $retVal;
266 :     return $retVal;
267 :     }
268 :    
269 :     =head3 GetCapability
270 :    
271 :     C<< my $level = $fig->GetCapability($objectID, $objectType); >>
272 :    
273 :     Get this user's access level for the specified object-- either C<RW> (full access),
274 :     C<RO> (read-only), or C<NO> (no access).
275 :    
276 :     =over 4
277 :    
278 :     =item objectID
279 :    
280 :     ID of the relevant object.
281 :    
282 :     =item objectType
283 :    
284 :     Type of the relevant object. This should be the Sprout entity name for the
285 :     object type. Currently, only C<Subsystem> and C<Genome> are supported.
286 :    
287 :     =item RETURN
288 :    
289 :     Returns C<RW> if the user has full-acess, C<RO> if the user has read-only
290 :     access, and C<NO> if the user should not have any access to the object.
291 :    
292 :     =back
293 :    
294 :     =cut
295 :    
296 :     sub GetCapability {
297 :     #TODO
298 :     }
299 :    
300 :     =head3 GetPreference
301 :    
302 :     C<< my $value = $fig->GetPreference($key); >>
303 :    
304 :     Return the user's preference value for the specified key.
305 :    
306 :     =over 4
307 :    
308 :     =item key
309 :    
310 :     Fully-qualified key for the preference value.
311 :    
312 :     =item RETURN
313 :    
314 :     Returns the preference value for the key. If the user has no explicit preference
315 :     value for that key, returns the corresponding value for the default user.
316 :    
317 :     =back
318 :    
319 :     =cut
320 :    
321 :     sub GetPreference {
322 :     #TODO
323 :     }
324 :    
325 :     =head3 SetCapabilities
326 :    
327 :     C<< $fig->SetCapabilities(\%groupMap); >>
328 :    
329 :     Set capabilities for this user. This does not replace all existing capabilities.
330 :     Instead, the capabilities specified in the group map are updated or deleted,
331 :     and any capabilities not specified are unchanged.
332 :    
333 :     =over 4
334 :    
335 :     =item groupMap
336 :    
337 :     Reference to a hash mapping group names to access levels (C<RW> full access,
338 :     C<RO> read-only access, C<NO> no access) or an undefined value if the user
339 :     is to have default access to the specified group.
340 :    
341 :     =back
342 :    
343 :     =cut
344 :    
345 :     sub SetCapabilities {
346 :     #TODO
347 :     }
348 :    
349 :     =head3 SetPreferences(\%preferences); >>
350 :    
351 :     Set preferences for this user. This does not replace all existing preferences.
352 :     Instead, the preferences specified in the map are updated or deleted, and any
353 :     preferences not specified are unchanged.
354 :    
355 :     =over 4
356 :    
357 :     =item preferences
358 :    
359 :     Reference to a hash mapping key names to preference values. Mapping a key
360 :     name to an undefined value indicates that the default preference value
361 :     should be used.
362 :    
363 :     =back
364 :    
365 :     =cut
366 :    
367 :     sub SetPreferences {
368 :     #TODO
369 :     }
370 :    
371 :     =head3 SetDefault
372 :    
373 :     C<< $fig->SetDefault($objectID, $objectType, $group, $level); >>
374 :    
375 :     Set the group and default access level for the specified object.
376 :    
377 :     =over 4
378 :    
379 :     =item objectID
380 :    
381 :     ID of the object whose access level and group are to be set.
382 :    
383 :     =item objectType
384 :    
385 :     Type of the relevant object. This should be expressed as a Sprout entity name.
386 :     Currently, only C<Genome> and C<Subsystem> are supported.
387 :    
388 :     =item group
389 :    
390 :     Name of the group to which the object will belong. A user's access level for
391 :     this group will override the default access level.
392 :    
393 :     =item level
394 :    
395 :     Default access level. This is the access level used for user's who do not have
396 :     an explicit capability specified for the object's group.
397 :    
398 :     =back
399 :    
400 :     =cut
401 :    
402 :     sub SetDefault {
403 :     #TODO
404 :     }
405 :    
406 :     1;
407 :    

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3