1 /*
2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.security;
27
28 /**
29 * Abstract class for representing access to a system resource.
30 * All permissions have a name (whose interpretation depends on the subclass),
31 * as well as abstract functions for defining the semantics of the
32 * particular Permission subclass.
33 *
34 * <p>Most Permission objects also include an "actions" list that tells the actions
35 * that are permitted for the object. For example,
36 * for a {@code java.io.FilePermission} object, the permission name is
37 * the pathname of a file (or directory), and the actions list
38 * (such as "read, write") specifies which actions are granted for the
39 * specified file (or for files in the specified directory).
40 * The actions list is optional for Permission objects, such as
41 * {@code java.lang.RuntimePermission},
42 * that don't need such a list; you either have the named permission (such
43 * as "system.exit") or you don't.
44 *
45 * <p>An important method that must be implemented by each subclass is
46 * the {@code implies} method to compare Permissions. Basically,
47 * "permission p1 implies permission p2" means that
48 * if one is granted permission p1, one is naturally granted permission p2.
49 * Thus, this is not an equality test, but rather more of a
50 * subset test.
51 *
52 * <P> Permission objects are similar to String objects in that they
53 * are immutable once they have been created. Subclasses should not
54 * provide methods that can change the state of a permission
55 * once it has been created.
56 *
57 * @see Permissions
58 * @see PermissionCollection
59 *
60 *
61 * @author Marianne Mueller
62 * @author Roland Schemers
63 * @since 1.2
64 */
65
66 public abstract class Permission implements Guard, java.io.Serializable {
67
68 private static final long serialVersionUID = -5636570222231596674L;
69
70 private String name;
71
72 /**
73 * Constructs a permission with the specified name.
74 *
75 * @param name name of the Permission object being created.
76 *
77 */
78
79 public Permission(String name) {
80 this.name = name;
81 }
82
83 /**
84 * Implements the guard interface for a permission. The
85 * {@code SecurityManager.checkPermission} method is called,
86 * passing this permission object as the permission to check.
87 * Returns silently if access is granted. Otherwise, throws
88 * a SecurityException.
89 *
90 * @param object the object being guarded (currently ignored).
91 *
92 * @throws SecurityException
93 * if a security manager exists and its
94 * {@code checkPermission} method doesn't allow access.
95 *
96 * @see Guard
97 * @see GuardedObject
98 * @see SecurityManager#checkPermission
99 *
100 */
101 public void checkGuard(Object object) throws SecurityException {
102 SecurityManager sm = System.getSecurityManager();
103 if (sm != null) sm.checkPermission(this);
104 }
105
106 /**
107 * Checks if the specified permission's actions are "implied by"
108 * this object's actions.
109 * <P>
110 * This must be implemented by subclasses of Permission, as they are the
111 * only ones that can impose semantics on a Permission object.
112 *
113 * <p>The {@code implies} method is used by the AccessController to determine
114 * whether or not a requested permission is implied by another permission that
115 * is known to be valid in the current execution context.
116 *
117 * @param permission the permission to check against.
118 *
119 * @return true if the specified permission is implied by this object,
120 * false if not.
121 */
122
123 public abstract boolean implies(Permission permission);
124
125 /**
126 * Checks two Permission objects for equality.
127 * <P>
128 * Do not use the {@code equals} method for making access control
129 * decisions; use the {@code implies} method.
130 *
131 * @param obj the object we are testing for equality with this object.
132 *
133 * @return true if both Permission objects are equivalent.
134 */
135
136 public abstract boolean equals(Object obj);
137
138 /**
139 * Returns the hash code value for this Permission object.
140 * <P>
141 * The required {@code hashCode} behavior for Permission Objects is
142 * the following:
143 * <ul>
144 * <li>Whenever it is invoked on the same Permission object more than
145 * once during an execution of a Java application, the
146 * {@code hashCode} method
147 * must consistently return the same integer. This integer need not
148 * remain consistent from one execution of an application to another
149 * execution of the same application.
150 * <li>If two Permission objects are equal according to the
151 * {@code equals}
152 * method, then calling the {@code hashCode} method on each of the
153 * two Permission objects must produce the same integer result.
154 * </ul>
155 *
156 * @return a hash code value for this object.
157 */
158
159 public abstract int hashCode();
160
161 /**
162 * Returns the name of this Permission.
163 * For example, in the case of a {@code java.io.FilePermission},
164 * the name will be a pathname.
165 *
166 * @return the name of this Permission.
167 *
168 */
169
170 public final String getName() {
171 return name;
172 }
173
174 /**
175 * Returns the actions as a String. This is abstract
176 * so subclasses can defer creating a String representation until
177 * one is needed. Subclasses should always return actions in what they
178 * consider to be their
179 * canonical form. For example, two FilePermission objects created via
180 * the following:
181 *
182 * <pre>
183 * perm1 = new FilePermission(p1,"read,write");
184 * perm2 = new FilePermission(p2,"write,read");
185 * </pre>
186 *
187 * both return
188 * "read,write" when the {@code getActions} method is invoked.
189 *
190 * @return the actions of this Permission.
191 *
192 */
193
194 public abstract String getActions();
195
196 /**
197 * Returns an empty PermissionCollection for a given Permission object, or null if
198 * one is not defined. Subclasses of class Permission should
199 * override this if they need to store their permissions in a particular
200 * PermissionCollection object in order to provide the correct semantics
201 * when the {@code PermissionCollection.implies} method is called.
202 * If null is returned,
203 * then the caller of this method is free to store permissions of this
204 * type in any PermissionCollection they choose (one that uses a Hashtable,
205 * one that uses a Vector, etc).
206 *
207 * @return a new PermissionCollection object for this type of Permission, or
208 * null if one is not defined.
209 */
210
211 public PermissionCollection newPermissionCollection() {
212 return null;
213 }
214
215 /**
216 * Returns a string describing this Permission. The convention is to
217 * specify the class name, the permission name, and the actions in
218 * the following format: '("ClassName" "name" "actions")', or
219 * '("ClassName" "name")' if actions list is null or empty.
220 *
221 * @return information about this Permission.
222 */
223 public String toString() {
224 String actions = getActions();
225 if ((actions == null) || (actions.length() == 0)) { // OPTIONAL
226 return "(\"" + getClass().getName() + "\" \"" + name + "\")";
227 } else {
228 return "(\"" + getClass().getName() + "\" \"" + name +
229 "\" \"" + actions + "\")";
230 }
231 }
232 }