Filename | /var/www/foswikidev/core/lib/Foswiki/AccessControlException.pm |
Statements | Executed 9 statements in 271µs |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
1 | 1 | 1 | 13µs | 25µs | BEGIN@84 | Foswiki::AccessControlException::
1 | 1 | 1 | 9µs | 13µs | BEGIN@85 | Foswiki::AccessControlException::
1 | 1 | 1 | 4µs | 4µs | BEGIN@90 | 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 | 29µs | 2 | 38µs | # spent 25µs (13+12) within Foswiki::AccessControlException::BEGIN@84 which was called:
# once (13µs+12µs) by Foswiki::Plugin::BEGIN@14 at line 84 # spent 25µs making 1 call to Foswiki::AccessControlException::BEGIN@84
# spent 12µs making 1 call to strict::import |
85 | 2 | 23µs | 2 | 17µs | # spent 13µs (9+4) within Foswiki::AccessControlException::BEGIN@85 which was called:
# once (9µs+4µs) by Foswiki::Plugin::BEGIN@14 at line 85 # spent 13µs making 1 call to Foswiki::AccessControlException::BEGIN@85
# spent 4µs making 1 call to warnings::import |
86 | |||||
87 | 2 | 56µ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 | 8µs | our @ISA = ('Error'); # base class | ||
89 | |||||
90 | # spent 4µs within Foswiki::AccessControlException::BEGIN@90 which was called:
# once (4µs+0s) by Foswiki::Plugin::BEGIN@14 at line 95 | ||||
91 | 1 | 28µs | if ( $Foswiki::cfg{UseLocale} ) { | ||
92 | require locale; | ||||
93 | import locale(); | ||||
94 | } | ||||
95 | 1 | 124µs | 1 | 4µs | } # spent 4µs making 1 call to Foswiki::AccessControlException::BEGIN@90 |
96 | |||||
97 | =begin TML | ||||
98 | |||||
99 | ---+ ClassMethod new($mode, $user, $web, $topic, $reason) | ||||
100 | |||||
101 | * =$mode= - mode of access (view, change etc) | ||||
102 | * =$user= - canonical user name of user doing the accessing | ||||
103 | * =$web= - web being accessed | ||||
104 | * =$topic= - topic being accessed | ||||
105 | * =$reason= - string reason for failure | ||||
106 | |||||
107 | All the above fields are accessible from the object in a catch clause | ||||
108 | in the usual way e.g. =$e->{web}= and =$e->{reason}= | ||||
109 | |||||
110 | =cut | ||||
111 | |||||
112 | sub new { | ||||
113 | my ( $class, $mode, $user, $web, $topic, $reason ) = @_; | ||||
114 | |||||
115 | return $class->SUPER::new( | ||||
116 | web => $web, | ||||
117 | topic => $topic, | ||||
118 | user => $user, | ||||
119 | mode => $mode, | ||||
120 | reason => $reason, | ||||
121 | ); | ||||
122 | } | ||||
123 | |||||
124 | =begin TML | ||||
125 | |||||
126 | ---++ ObjectMethod stringify() -> $string | ||||
127 | |||||
128 | Generate a summary string. This is mainly for debugging. | ||||
129 | |||||
130 | =cut | ||||
131 | |||||
132 | sub stringify { | ||||
133 | my $this = shift; | ||||
134 | my $topic = $this->{topic} | ||||
135 | || ''; # Access checks of Web objects causes uninitialized string errors | ||||
136 | return | ||||
137 | "AccessControlException: Access to $this->{mode} $this->{web}.$topic for $this->{user} is denied. $this->{reason}"; | ||||
138 | } | ||||
139 | |||||
140 | 1 | 3µs | 1; | ||
141 | __END__ |