File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\security\Permission.java.html

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi, Yahoo! Inc.
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 */
24 package hudson.security;
25
26 import com.google.common.collect.ImmutableSet;
27 import hudson.model.Hudson;
28 import jenkins.model.Jenkins;
29 import net.sf.json.util.JSONUtils;
30
31 import java.util.Collections;
32 import java.util.Comparator;
33 import java.util.List;
34 import java.util.Set;
35 import java.util.concurrent.CopyOnWriteArrayList;
36
37 import org.jvnet.localizer.Localizable;
38
39 /**
40 * Permission, which represents activity that requires a security privilege.
41 *
42 * <p>
43 * Each permission is represented by a specific instance of {@link Permission}.
44 *
45 * @author Kohsuke Kawaguchi
46 * @see https://wiki.jenkins-ci.org/display/JENKINS/Making+your+plugin+behave+in+secured+Jenkins
47 */
48 public final class Permission {
49
50 /**
51 * Comparator that orders {@link Permission} objects based on their ID.
52 */
53 public static final Comparator<Permission> ID_COMPARATOR = new Comparator<Permission>() {
54
55 /**
56 * {@inheritDoc}
57 */
58 // break eclipse compilation
59 //Override
60 public int compare(Permission one, Permission two) {
61 return one.getId().compareTo(two.getId());
62 }
63 };
64
65 public final Class owner;
66
67 public final PermissionGroup group;
68
69 /**
70 * Human readable ID of the permission.
71 *
72 * <p>
73 * This name should uniquely determine a permission among
74 * its owner class. The name must be a valid Java identifier.
75 * <p>
76 * The expected naming convention is something like "BrowseWorkspace".
77 */
78 public final String name;
79
80 /**
81 * Human-readable description of this permission.
82 * Used as a tooltip to explain this permission, so this message
83 * should be a couple of sentences long.
84 *
85 * <p>
86 * If null, there will be no description text.
87 */
88 public final Localizable description;
89
90 /**
91 * Bundled {@link Permission} that also implies this permission.
92 *
93 * <p>
94 * This allows us to organize permissions in a hierarchy, so that
95 * for example we can say "view workspace" permission is implied by
96 * the (broader) "read" permission.
97 *
98 * <p>
99 * The idea here is that for most people, access control based on
100 * such broad permission bundle is good enough, and those few
101 * that need finer control can do so.
102 */
103 public final Permission impliedBy;
104
105 /**
106 * Whether this permission is available for use.
107 *
108 * <p>
109 * This allows us to dynamically enable or disable the visibility of
110 * permissions, so administrators can control the complexity of their
111 * permission matrix.
112 *
113 * @since 1.325
114 */
115 public boolean enabled;
116
117 /**
118 * Scopes that this permission is directly contained by.
119 */
120 private final Set<PermissionScope> scopes;
121
122 /**
123 * Defines a new permission.
124 *
125 * @param group
126 * Permissions are grouped per classes that own them. Specify the permission group
127 * created for that class. The idiom is:
128 *
129 * <pre>
130 * class Foo {
131 * private static final PermissionGroup PERMISSIONS = new PermissionGroup(Foo.class,...);
132 * public static final Permission ABC = new Permission(PERMISSION,...) ;
133 * }
134 * </pre>
135 *
136 * Because of the classloading problems and the difficulty for Hudson to enumerate them,
137 * the permission constants really need to be static field of the owner class.
138 *
139 * @param name
140 * See {@link #name}.
141 * @param description
142 * See {@link #description}.
143 * @param impliedBy
144 * See {@link #impliedBy}.
145 */
146 public Permission(PermissionGroup group, String name, Localizable description, Permission impliedBy, boolean enable, PermissionScope[] scopes) {
147 if(!JSONUtils.isJavaIdentifier(name))
148 throw new IllegalArgumentException(name+" is not a Java identifier");
149 this.owner = group.owner;
150 this.group = group;
151 this.name = name;
152 this.description = description;
153 this.impliedBy = impliedBy;
154 this.enabled = enable;
155 this.scopes = ImmutableSet.copyOf(scopes);
156
157 group.add(this);
158 ALL.add(this);
159 }
160
161 public Permission(PermissionGroup group, String name, Localizable description, Permission impliedBy, PermissionScope scope) {
162 this(group,name,description,impliedBy,true,new PermissionScope[]{scope});
163 assert scope!=null;
164 }
165
166 /**
167 * @deprecated as of 1.421
168 * Use {@link #Permission(PermissionGroup, String, Localizable, Permission, boolean, PermissionScope[])}
169 */
170 public Permission(PermissionGroup group, String name, Localizable description, Permission impliedBy, boolean enable) {
171 this(group,name,description,impliedBy,enable,new PermissionScope[]{PermissionScope.JENKINS});
172 }
173
174 /**
175 * @deprecated as of 1.421
176 * Use {@link #Permission(PermissionGroup, String, Localizable, Permission, PermissionScope)}
177 */
178 public Permission(PermissionGroup group, String name, Localizable description, Permission impliedBy) {
179 this(group, name, description, impliedBy, PermissionScope.JENKINS);
180 }
181
182 /**
183 * @deprecated since 1.257.
184 * Use {@link #Permission(PermissionGroup, String, Localizable, Permission)}
185 */
186 public Permission(PermissionGroup group, String name, Permission impliedBy) {
187 this(group,name,null,impliedBy);
188 }
189
190 private Permission(PermissionGroup group, String name) {
191 this(group,name,null,null);
192 }
193
194 /**
195 * Checks if this permission is contained in the specified scope, (either directly or indirectly.)
196 */
197 public boolean isContainedBy(PermissionScope s) {
198 for (PermissionScope c : scopes) {
199 if (c.isContainedBy(s))
200 return true;
201 }
202 return false;
203 }
204
205 /**
206 * Returns the string representation of this {@link Permission},
207 * which can be converted back to {@link Permission} via the
208 * {@link #fromId(String)} method.
209 *
210 * <p>
211 * This string representation is suitable for persistence.
212 *
213 * @see #fromId(String)
214 */
215 public String getId() {
216 return owner.getName()+'.'+name;
217 }
218
219 /**
220 * Convert the ID representation into {@link Permission} object.
221 *
222 * @return
223 * null if the conversion failed.
224 * @see #getId()
225 */
226 public static Permission fromId(String id) {
227 int idx = id.lastIndexOf('.');
228 if(idx<0) return null;
229
230 try {
231 // force the initialization so that it will put all its permissions into the list.
232 Class cl = Class.forName(id.substring(0,idx),true, Jenkins.getInstance().getPluginManager().uberClassLoader);
233 PermissionGroup g = PermissionGroup.get(cl);
234 if(g ==null) return null;
235 return g.find(id.substring(idx+1));
236 } catch (ClassNotFoundException e) {
237 return null;
238 }
239 }
240
241 @Override
242 public String toString() {
243 return "Permission["+owner+','+name+']';
244 }
245
246 public void setEnabled(boolean enable) {
247 enabled = enable;
248 }
249
250 public boolean getEnabled() {
251 return enabled;
252 }
253
254 /**
255 * Returns all the {@link Permission}s available in the system.
256 * @return
257 * always non-null. Read-only.
258 */
259 public static List<Permission> getAll() {
260 return ALL_VIEW;
261 }
262
263 /**
264 * All permissions in the system but in a single list.
265 */
266 private static final List<Permission> ALL = new CopyOnWriteArrayList<Permission>();
267
268 private static final List<Permission> ALL_VIEW = Collections.unmodifiableList(ALL);
269
270 //
271 //
272 // Because of the initialization order issue, these two fields need to be defined here,
273 // even though they logically belong to Jenkins.
274 //
275
276 /**
277 * {@link PermissionGroup} for {@link jenkins.model.Jenkins}.
278 *
279 * @deprecated since 2009-01-23.
280 * Access {@link jenkins.model.Jenkins#PERMISSIONS} instead.
281 */
282 public static final PermissionGroup HUDSON_PERMISSIONS = new PermissionGroup(Hudson.class, hudson.model.Messages._Hudson_Permissions_Title());
283 /**
284 * {@link Permission} that represents the God-like access. Equivalent of Unix root.
285 *
286 * <p>
287 * All permissions are eventually {@linkplain Permission#impliedBy implied by} this permission.
288 *
289 * @deprecated since 2009-01-23.
290 * Access {@link jenkins.model.Jenkins#ADMINISTER} instead.
291 */
292 public static final Permission HUDSON_ADMINISTER = new Permission(HUDSON_PERMISSIONS,"Administer", hudson.model.Messages._Hudson_AdministerPermission_Description(),null);
293
294 //
295 //
296 // Root Permissions.
297 //
298 // These permisisons are meant to be used as the 'impliedBy' permission for other more specific permissions.
299 // The intention is to allow a simplified AuthorizationStrategy implementation agnostic to
300 // specific permissions.
301
302 public static final PermissionGroup GROUP = new PermissionGroup(Permission.class,Messages._Permission_Permissions_Title());
303
304 /**
305 * Historically this was separate from {@link #HUDSON_ADMINISTER} but such a distinction doesn't make sense
306 * any more, so deprecated.
307 *
308 * @deprecated since 2009-01-23.
309 * Use {@link jenkins.model.Jenkins#ADMINISTER}.
310 */
311 public static final Permission FULL_CONTROL = new Permission(GROUP, "FullControl",null, HUDSON_ADMINISTER);
312
313 /**
314 * Generic read access.
315 */
316 public static final Permission READ = new Permission(GROUP,"GenericRead",null,HUDSON_ADMINISTER);
317
318 /**
319 * Generic write access.
320 */
321 public static final Permission WRITE = new Permission(GROUP,"GenericWrite",null,HUDSON_ADMINISTER);
322
323 /**
324 * Generic create access.
325 */
326 public static final Permission CREATE = new Permission(GROUP,"GenericCreate",null,WRITE);
327
328 /**
329 * Generic update access.
330 */
331 public static final Permission UPDATE = new Permission(GROUP,"GenericUpdate",null,WRITE);
332
333 /**
334 * Generic delete access.
335 */
336 public static final Permission DELETE = new Permission(GROUP,"GenericDelete",null,WRITE);
337
338 /**
339 * Generic configuration access.
340 */
341 public static final Permission CONFIGURE = new Permission(GROUP,"GenericConfigure",null,UPDATE);
342 }
343