Filename | /var/www/foswiki11/lib/Foswiki/AccessControlException.pm |
Statements | Executed 8 statements in 206µs |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
1 | 1 | 1 | 19µs | 32µs | BEGIN@84 | Foswiki::AccessControlException::
1 | 1 | 1 | 9µs | 14µs | BEGIN@85 | Foswiki::AccessControlException::
1 | 1 | 1 | 3µs | 3µs | BEGIN@87 | Foswiki::AccessControlException::
0 | 0 | 0 | 0s | 0s | new | Foswiki::AccessControlException::
0 | 0 | 0 | 0s | 0s | stringify | Foswiki::AccessControlException::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | # See bottom of file for license and copyright information | ||||
2 | |||||
3 | =begin TML | ||||
4 | |||||
5 | ---+ package Foswiki::AccessControlException | ||||
6 | |||||
7 | Exception used raise an access control violation. This exception has the | ||||
8 | following fields: | ||||
9 | * =web= - the web which was being accessed | ||||
10 | * =topic= - the topic being accessed (if any) | ||||
11 | * =user= - canonical username of the person doing the accessing. Use | ||||
12 | the methods of the Foswiki::Users class to get more information about the | ||||
13 | user. | ||||
14 | * =mode= - the access mode e.g. CHANGE, VIEW etc | ||||
15 | * =reason= a text string giving the reason for the refusal. | ||||
16 | |||||
17 | The exception may be thrown by plugins. If a plugin throws the exception, it | ||||
18 | will normally be caught and the browser redirected to a login screen (if the | ||||
19 | user is not logged in) or reported (if they are and just don't have access). | ||||
20 | |||||
21 | ---++ Throwing an exception | ||||
22 | |||||
23 | If your code needs to abort processing and inform the user (or the higher level caller) | ||||
24 | that some operation was denied, throw an =AccessControlException=. | ||||
25 | |||||
26 | <verbatim> | ||||
27 | use Error qw(:try); | ||||
28 | use Foswiki::AccessControlException; | ||||
29 | ... | ||||
30 | unless ( | ||||
31 | Foswiki::Func::checkAccessPermission( | ||||
32 | "VIEW", $session->{user}, undef, $topic, $web | ||||
33 | ) | ||||
34 | ) | ||||
35 | { | ||||
36 | throw Foswiki::AccessControlException( "VIEW", $session->{user}, $web, | ||||
37 | $topic, $Foswiki::Meta::reason ); | ||||
38 | } | ||||
39 | </verbatim> | ||||
40 | |||||
41 | ---++ Catching an exception | ||||
42 | |||||
43 | If you are calling a function that can detect and throw an access violation, and | ||||
44 | you would prefer to intercept the exception to perform some further processing, | ||||
45 | use the =try { } catch { }= structure. | ||||
46 | |||||
47 | <verbatim> | ||||
48 | my $exception; | ||||
49 | try { | ||||
50 | Foswiki::Func::moveWeb( "Oldweb", "Newweb" ); | ||||
51 | } catch Foswiki::AccessControlException with { | ||||
52 | $exception = shift; | ||||
53 | } otherwise { | ||||
54 | ... | ||||
55 | }; | ||||
56 | </verbatim> | ||||
57 | |||||
58 | ---++ Notes | ||||
59 | |||||
60 | *Since* _date_ indicates where functions or parameters have been added since | ||||
61 | the baseline of the API (TWiki release 4.2.3). The _date_ indicates the | ||||
62 | earliest date of a Foswiki release that will support that function or | ||||
63 | parameter. | ||||
64 | |||||
65 | *Deprecated* _date_ indicates where a function or parameters has been | ||||
66 | [[http://en.wikipedia.org/wiki/Deprecation][deprecated]]. Deprecated | ||||
67 | functions will still work, though they should | ||||
68 | _not_ be called in new plugins and should be replaced in older plugins | ||||
69 | as soon as possible. Deprecated parameters are simply ignored in Foswiki | ||||
70 | releases after _date_. | ||||
71 | |||||
72 | *Until* _date_ indicates where a function or parameter has been removed. | ||||
73 | The _date_ indicates the latest date at which Foswiki releases still supported | ||||
74 | the function or parameter. | ||||
75 | |||||
76 | =cut | ||||
77 | |||||
78 | # THIS PACKAGE IS PART OF THE PUBLISHED API USED BY EXTENSION AUTHORS. | ||||
79 | # DO NOT CHANGE THE EXISTING APIS (well thought out extensions are OK) | ||||
80 | # AND ENSURE ALL POD DOCUMENTATION IS COMPLETE AND ACCURATE. | ||||
81 | |||||
82 | package Foswiki::AccessControlException; | ||||
83 | |||||
84 | 2 | 30µs | 2 | 45µs | # spent 32µs (19+13) within Foswiki::AccessControlException::BEGIN@84 which was called:
# once (19µs+13µs) by Foswiki::Plugin::BEGIN@14 at line 84 # spent 32µs making 1 call to Foswiki::AccessControlException::BEGIN@84
# spent 13µs making 1 call to strict::import |
85 | 2 | 23µs | 2 | 19µs | # spent 14µs (9+5) within Foswiki::AccessControlException::BEGIN@85 which was called:
# once (9µs+5µs) by Foswiki::Plugin::BEGIN@14 at line 85 # spent 14µs making 1 call to Foswiki::AccessControlException::BEGIN@85
# spent 5µs making 1 call to warnings::import |
86 | |||||
87 | 2 | 143µs | 1 | 3µs | # spent 3µs within Foswiki::AccessControlException::BEGIN@87 which was called:
# once (3µs+0s) by Foswiki::Plugin::BEGIN@14 at line 87 # spent 3µs making 1 call to Foswiki::AccessControlException::BEGIN@87 |
88 | 1 | 7µs | our @ISA = ('Error'); # base class | ||
89 | |||||
90 | =begin TML | ||||
91 | |||||
92 | ---+ ClassMethod new($mode, $user, $web, $topic, $reason) | ||||
93 | |||||
94 | * =$mode= - mode of access (view, change etc) | ||||
95 | * =$user= - canonical user name of user doing the accessing | ||||
96 | * =$web= - web being accessed | ||||
97 | * =$topic= - topic being accessed | ||||
98 | * =$reason= - string reason for failure | ||||
99 | |||||
100 | All the above fields are accessible from the object in a catch clause | ||||
101 | in the usual way e.g. =$e->{web}= and =$e->{reason}= | ||||
102 | |||||
103 | =cut | ||||
104 | |||||
105 | sub new { | ||||
106 | my ( $class, $mode, $user, $web, $topic, $reason ) = @_; | ||||
107 | |||||
108 | return $class->SUPER::new( | ||||
109 | web => $web, | ||||
110 | topic => $topic, | ||||
111 | user => $user, | ||||
112 | mode => $mode, | ||||
113 | reason => $reason, | ||||
114 | ); | ||||
115 | } | ||||
116 | |||||
117 | =begin TML | ||||
118 | |||||
119 | ---++ ObjectMethod stringify() -> $string | ||||
120 | |||||
121 | Generate a summary string. This is mainly for debugging. | ||||
122 | |||||
123 | =cut | ||||
124 | |||||
125 | sub stringify { | ||||
126 | my $this = shift; | ||||
127 | my $topic = $this->{topic} | ||||
128 | || ''; # Access checks of Web objects causes uninitialized string errors | ||||
129 | return | ||||
130 | "AccessControlException: Access to $this->{mode} $this->{web}.$topic for $this->{user} is denied. $this->{reason}"; | ||||
131 | } | ||||
132 | |||||
133 | 1 | 3µs | 1; | ||
134 | __END__ |