Putting 4.2.0 on top of 4.0.17
[usit-rt.git] / lib / RT / SharedSetting.pm
1 # BEGIN BPS TAGGED BLOCK {{{
2 #
3 # COPYRIGHT:
4 #
5 # This software is Copyright (c) 1996-2013 Best Practical Solutions, LLC
6 #                                          <sales@bestpractical.com>
7 #
8 # (Except where explicitly superseded by other copyright notices)
9 #
10 #
11 # LICENSE:
12 #
13 # This work is made available to you under the terms of Version 2 of
14 # the GNU General Public License. A copy of that license should have
15 # been provided with this software, but in any event can be snarfed
16 # from www.gnu.org.
17 #
18 # This work is distributed in the hope that it will be useful, but
19 # WITHOUT ANY WARRANTY; without even the implied warranty of
20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21 # General Public License for more details.
22 #
23 # You should have received a copy of the GNU General Public License
24 # along with this program; if not, write to the Free Software
25 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
26 # 02110-1301 or visit their web page on the internet at
27 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
28 #
29 #
30 # CONTRIBUTION SUBMISSION POLICY:
31 #
32 # (The following paragraph is not intended to limit the rights granted
33 # to you to modify and distribute this software under the terms of
34 # the GNU General Public License and is only of importance to you if
35 # you choose to contribute your changes and enhancements to the
36 # community by submitting them to Best Practical Solutions, LLC.)
37 #
38 # By intentionally submitting any modifications, corrections or
39 # derivatives to this work, or any other work intended for use with
40 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
41 # you are the copyright holder for those contributions and you grant
42 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
43 # royalty-free, perpetual, license to use, copy, create derivative
44 # works based on those contributions, and sublicense and distribute
45 # those contributions and any derivatives thereof.
46 #
47 # END BPS TAGGED BLOCK }}}
48
49 =head1 NAME
50
51 RT::SharedSetting - an API for settings that belong to an RT::User or RT::Group
52
53 =head1 SYNOPSIS
54
55   use RT::SharedSetting;
56
57 =head1 DESCRIPTION
58
59 A RT::SharedSetting is an object that can belong to an L<RT::User> or an <RT::Group>.
60 It consists of an ID, a name, and some arbitrary data.
61
62 =cut
63
64 package RT::SharedSetting;
65 use strict;
66 use warnings;
67 use base qw/RT::Base/;
68
69 use RT::Attribute;
70 use Scalar::Util 'blessed';
71
72 =head1 METHODS
73
74 =head2 new
75
76 Returns a new L<RT::SharedSetting> object.
77 Takes the current user, see also L<RT::Base>.
78
79 =cut
80
81 sub new  {
82     my $proto = shift;
83     my $class = ref($proto) || $proto;
84     my $self  = {};
85     $self->{'Id'} = 0;
86     bless ($self, $class);
87     $self->CurrentUser(@_);
88     return $self;
89 }
90
91 =head2 Load
92
93 Takes a privacy specification and a shared-setting ID.  Loads the given object
94 ID if it belongs to the stated user or group. Calls the L</PostLoad> method on
95 success for any further initialization. Returns a tuple of status and message,
96 where status is true on success.
97
98 =cut
99
100 sub Load {
101     my $self = shift;
102     my ($privacy, $id) = @_;
103     my $object = $self->_GetObject($privacy);
104
105     if ($object) {
106         $self->{'Attribute'} = RT::Attribute->new($self->CurrentUser);
107         $self->{'Attribute'}->Load( $id );
108         if ($self->{'Attribute'}->Id) {
109             $self->{'Id'} = $self->{'Attribute'}->Id;
110             $self->{'Privacy'} = $privacy;
111             $self->PostLoad();
112
113             return wantarray ? (0, $self->loc("Permission Denied")) : 0
114                 unless $self->CurrentUserCanSee;
115
116             my ($ok, $msg) = $self->PostLoadValidate;
117             return wantarray ? ($ok, $msg) : $ok if !$ok;
118
119             return wantarray ? (1, $self->loc("Loaded [_1] [_2]", $self->ObjectName, $self->Name)) : 1;
120         } else {
121             $RT::Logger->error("Could not load attribute " . $id
122                     . " for object " . $privacy);
123             return wantarray ? (0, $self->loc("Failed to load [_1] [_2]", $self->ObjectName, $id)) : 0;
124         }
125     } else {
126         $RT::Logger->warning("Could not load object $privacy when loading " . $self->ObjectName);
127         return wantarray ? (0, $self->loc("Could not load object for [_1]", $privacy)) : 0;
128     }
129 }
130
131 =head2 LoadById
132
133 First loads up the L<RT::Attribute> for this shared setting by ID, then calls
134 L</Load> with the correct parameters. Returns a tuple of status and message,
135 where status is true on success.
136
137 =cut
138
139 sub LoadById {
140     my $self = shift;
141     my $id   = shift;
142
143     my $attr = RT::Attribute->new($self->CurrentUser);
144     my ($ok, $msg) = $attr->LoadById($id);
145
146     if (!$ok) {
147         return wantarray ? (0, $self->loc("Failed to load [_1] [_2]: [_3]", $self->ObjectName, $id, $msg)) : 0;
148     }
149
150     my $privacy = $self->_build_privacy($attr->ObjectType, $attr->ObjectId);
151     return wantarray ? (0, $self->loc("Bad privacy for attribute [_1]", $id)) : 0
152         if !$privacy;
153
154     return $self->Load($privacy, $id);
155 }
156
157 =head2 PostLoad
158
159 Called after a successful L</Load>.
160
161 =cut
162
163 sub PostLoad { }
164
165 =head2 PostLoadValidate
166
167 Called just before returning success from L</Load>; may be used to validate
168 that the record is correct. This method is expected to return a (ok, msg)
169 pair.
170
171 =cut
172
173 sub PostLoadValidate {
174     return 1;
175 }
176
177 =head2 Save
178
179 Creates a new shared setting. Takes a privacy, a name, and any other arguments.
180 Saves the given parameters to the appropriate user/group object, and loads the
181 resulting object. Arguments are passed to the L</SaveAttribute> method, which
182 does the actual update. Returns a tuple of status and message, where status is
183 true on success. Defaults are:
184
185   Privacy:  CurrentUser only
186   Name:     "new (ObjectName)"
187
188 =cut
189
190 sub Save {
191     my $self = shift;
192     my %args = (
193         'Privacy' => 'RT::User-' . $self->CurrentUser->Id,
194         'Name'    => "new " . $self->ObjectName,
195         @_,
196     );
197
198     my $privacy = $args{'Privacy'};
199     my $name    = $args{'Name'},
200     my $object  = $self->_GetObject($privacy);
201
202     return (0, $self->loc("Failed to load object for [_1]", $privacy))
203         unless $object;
204
205     return (0, $self->loc("Permission Denied"))
206         unless $self->CurrentUserCanCreate($privacy);
207
208     my ($att_id, $att_msg) = $self->SaveAttribute($object, \%args);
209
210     if ($att_id) {
211         $self->{'Attribute'} = RT::Attribute->new($self->CurrentUser);
212         $self->{'Attribute'}->Load( $att_id );
213         $self->{'Id'}        = $att_id;
214         $self->{'Privacy'}   = $privacy;
215         return ( 1, $self->loc( "Saved [_1] [_2]", $self->loc( $self->ObjectName ), $name ) );
216     }
217     else {
218         $RT::Logger->error($self->ObjectName . " save failure: $att_msg");
219         return ( 0, $self->loc("Failed to create [_1] attribute", $self->loc( $self->ObjectName ) ) );
220     }
221 }
222
223 =head2 SaveAttribute
224
225 An empty method for subclassing. Called from L</Save> method.
226
227 =cut
228
229 sub SaveAttribute { }
230
231 =head2 Update
232
233 Updates the parameters of an existing shared setting. Any arguments are passed
234 to the L</UpdateAttribute> method. Returns a tuple of status and message, where
235 status is true on success.
236
237 =cut
238
239 sub Update {
240     my $self = shift;
241     my %args = @_;
242
243     return(0, $self->loc("No [_1] loaded", $self->ObjectName)) unless $self->Id;
244     return(0, $self->loc("Could not load [_1] attribute", $self->ObjectName))
245         unless $self->{'Attribute'}->Id;
246
247     return (0, $self->loc("Permission Denied"))
248         unless $self->CurrentUserCanModify;
249
250     my ($status, $msg) = $self->UpdateAttribute(\%args);
251
252     return (1, $self->loc("[_1] update: Nothing changed", ucfirst($self->ObjectName)))
253         if !defined $msg;
254
255     # prevent useless warnings
256     return (1, $self->loc("[_1] updated"), ucfirst($self->ObjectName))
257         if $msg =~ /That is already the current value/;
258
259     return ($status, $self->loc("[_1] update: [_2]", ucfirst($self->ObjectName), $msg));
260 }
261
262 =head2 UpdateAttribute
263
264 An empty method for subclassing. Called from L</Update> method.
265
266 =cut
267
268 sub UpdateAttribute { }
269
270 =head2 Delete
271     
272 Deletes the existing shared setting. Returns a tuple of status and message,
273 where status is true upon success.
274
275 =cut
276
277 sub Delete {
278     my $self = shift;
279     return (0, $self->loc("Permission Denied"))
280         unless $self->CurrentUserCanDelete;
281
282     my ($status, $msg) = $self->{'Attribute'}->Delete;
283     $self->CurrentUser->ClearAttributes; # force the current user's attribute cache to be cleaned up
284     if ($status) {
285         return (1, $self->loc("Deleted [_1]", $self->ObjectName));
286     } else {
287         return (0, $self->loc("Delete failed: [_1]", $msg));
288     }
289 }
290
291 ### Accessor methods
292
293 =head2 Name
294
295 Returns the name of this shared setting.
296
297 =cut
298
299 sub Name {
300     my $self = shift;
301     return unless ref($self->{'Attribute'}) eq 'RT::Attribute';
302     return $self->{'Attribute'}->Description();
303 }
304
305 =head2 Id
306
307 Returns the numerical ID of this shared setting.
308
309 =cut
310
311 sub Id {
312     my $self = shift;
313     return $self->{'Id'};
314 }
315
316 *id = \&Id;
317
318
319 =head2 Privacy
320
321 Returns the principal object to whom this shared setting belongs, in a string
322 "<class>-<id>", e.g. "RT::Group-16".
323
324 =cut
325
326 sub Privacy {
327     my $self = shift;
328     return $self->{'Privacy'};
329 }
330
331 =head2 GetParameter
332
333 Returns the given named parameter of the setting.
334
335 =cut
336
337 sub GetParameter {
338     my $self = shift;
339     my $param = shift;
340     return unless ref($self->{'Attribute'}) eq 'RT::Attribute';
341     return $self->{'Attribute'}->SubValue($param);
342 }
343
344 =head2 IsVisibleTo Privacy
345
346 Returns true if the setting is visible to all principals of the given privacy.
347 This does not deal with ACLs, this only looks at membership.
348
349 =cut
350
351 sub IsVisibleTo {
352     my $self    = shift;
353     my $to      = shift;
354     my $privacy = $self->Privacy || '';
355
356     # if the privacies are the same, then they can be seen. this handles
357     # a personal setting being visible to that user.
358     return 1 if $privacy eq $to;
359
360     # If the setting is systemwide, then any user can see it.
361     return 1 if $privacy =~ /^RT::System/;
362
363     # Only privacies that are RT::System can be seen by everyone.
364     return 0 if $to =~ /^RT::System/;
365
366     # If the setting is group-wide...
367     if ($privacy =~ /^RT::Group-(\d+)$/) {
368         my $setting_group = RT::Group->new($self->CurrentUser);
369         $setting_group->Load($1);
370
371         if ($to =~ /-(\d+)$/) {
372             my $to_id = $1;
373
374             # then any principal that is a member of the setting's group can see
375             # the setting
376             return $setting_group->HasMemberRecursively($to_id);
377         }
378     }
379
380     return 0;
381 }
382
383 sub CurrentUserCanSee    { 1 }
384 sub CurrentUserCanCreate { 1 }
385 sub CurrentUserCanModify { 1 }
386 sub CurrentUserCanDelete { 1 }
387
388 ### Internal methods
389
390 # _GetObject: helper routine to load the correct object whose parameters
391 #  have been passed.
392
393 sub _GetObject {
394     my $self = shift;
395     my $privacy = shift;
396
397     # short circuit: if they pass the object we want anyway, just return it
398     if (blessed($privacy) && $privacy->isa('RT::Record')) {
399         return $privacy;
400     }
401
402     my ($obj_type, $obj_id) = split(/\-/, ($privacy || ''));
403
404     unless ($obj_type && $obj_id) {
405         $privacy = '(undef)' if !defined($privacy);
406         $RT::Logger->debug("Invalid privacy string '$privacy'");
407         return undef;
408     }
409
410     my $object = $self->_load_privacy_object($obj_type, $obj_id);
411
412     unless (ref($object) eq $obj_type) {
413         $RT::Logger->error("Could not load object of type $obj_type with ID $obj_id, got object of type " . (ref($object) || 'undef'));
414         return undef;
415     }
416
417     # Do not allow the loading of a user object other than the current
418     # user, or of a group object of which the current user is not a member.
419
420     if ($obj_type eq 'RT::User' && $object->Id != $self->CurrentUser->UserObj->Id) {
421         $RT::Logger->debug("Permission denied for user other than self");
422         return undef;
423     }
424
425     if (   $obj_type eq 'RT::Group'
426         && !$object->HasMemberRecursively($self->CurrentUser->PrincipalObj)
427         && !$self->CurrentUser->HasRight( Object => $RT::System, Right => 'SuperUser' ) ) {
428         $RT::Logger->debug("Permission denied, ".$self->CurrentUser->Name.
429                            " is not a member of group");
430         return undef;
431     }
432
433     return $object;
434 }
435
436 sub _load_privacy_object {
437     my ($self, $obj_type, $obj_id) = @_;
438     if ( $obj_type eq 'RT::User' ) {
439         if ( $obj_id == $self->CurrentUser->Id ) {
440             return $self->CurrentUser->UserObj;
441         } else {
442             $RT::Logger->warning("User #". $self->CurrentUser->Id ." tried to load container user #". $obj_id);
443             return undef;
444         }
445     }
446     elsif ($obj_type eq 'RT::Group') {
447         my $group = RT::Group->new($self->CurrentUser);
448         $group->Load($obj_id);
449         return $group;
450     }
451     elsif ($obj_type eq 'RT::System') {
452         return RT::System->new($self->CurrentUser);
453     }
454
455     $RT::Logger->error(
456         "Tried to load a ". $self->ObjectName 
457         ." belonging to an $obj_type, which is neither a user nor a group"
458     );
459
460     return undef;
461 }
462
463 sub _build_privacy {
464     my ($self, $obj_type, $obj_id) = @_;
465
466     # allow passing in just an object to find its privacy string
467     if (ref($obj_type)) {
468         my $Object = $obj_type;
469         return $Object->isa('RT::User')   ? 'RT::User-'   . $Object->Id
470              : $Object->isa('RT::Group')  ? 'RT::Group-'  . $Object->Id
471              : $Object->isa('RT::System') ? 'RT::System-' . $Object->Id
472              : undef;
473     }
474
475     return undef unless ($obj_type);  # undef workaround
476     return $obj_type eq 'RT::User'   ? "$obj_type-$obj_id"
477          : $obj_type eq 'RT::Group'  ? "$obj_type-$obj_id"
478          : $obj_type eq 'RT::System' ? "$obj_type-$obj_id"
479          : undef;
480 }
481
482 =head2 ObjectsForLoading
483
484 Returns a list of objects that can be used to load this shared setting. It
485 is ACL checked.
486
487 =cut
488
489 sub ObjectsForLoading {
490     my $self = shift;
491     return grep { $self->CurrentUserCanSee($_) } $self->_PrivacyObjects;
492 }
493
494 =head2 ObjectsForCreating
495
496 Returns a list of objects that can be used to create this shared setting. It
497 is ACL checked.
498
499 =cut
500
501 sub ObjectsForCreating {
502     my $self = shift;
503     return grep { $self->CurrentUserCanCreate($_) } $self->_PrivacyObjects;
504 }
505
506 =head2 ObjectsForModifying
507
508 Returns a list of objects that can be used to modify this shared setting. It
509 is ACL checked.
510
511 =cut
512
513 sub ObjectsForModifying {
514     my $self = shift;
515     return grep { $self->CurrentUserCanModify($_) } $self->_PrivacyObjects;
516 }
517
518 RT::Base->_ImportOverlays();
519
520 1;