1 /*
2 * Copyright 1997-2003 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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</code> 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</code>,
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</code> 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 */
64
65 public abstract class Permission implements Guard, java.io.Serializable {
66
67 private static final long serialVersionUID = -5636570222231596674L;
68
69 private String name;
70
71 /**
72 * Constructs a permission with the specified name.
73 *
74 * @param name name of the Permission object being created.
75 *
76 */
77
78 public Permission(String name) {
79 this.name = name;
80 }
81
82 /**
83 * Implements the guard interface for a permission. The
84 * <code>SecurityManager.checkPermission</code> method is called,
85 * passing this permission object as the permission to check.
86 * Returns silently if access is granted. Otherwise, throws
87 * a SecurityException.
88 *
89 * @param object the object being guarded (currently ignored).
90 *
91 * @throws SecurityException
92 * if a security manager exists and its
93 * <code>checkPermission</code> method doesn't allow access.
94 *
95 * @see Guard
96 * @see GuardedObject
97 * @see SecurityManager#checkPermission
98 *
99 */
100 public void checkGuard(Object object) throws SecurityException {
101 SecurityManager sm = System.getSecurityManager();
102 if (sm != null) sm.checkPermission(this);
103 }
104
105 /**
106 * Checks if the specified permission's actions are "implied by"
107 * this object's actions.
108 * <P>
109 * This must be implemented by subclasses of Permission, as they are the
110 * only ones that can impose semantics on a Permission object.
111 *
112 * <p>The <code>implies</code> method is used by the AccessController to determine
113 * whether or not a requested permission is implied by another permission that
114 * is known to be valid in the current execution context.
115 *
116 * @param permission the permission to check against.
117 *
118 * @return true if the specified permission is implied by this object,
119 * false if not.
120 */
121
122 public abstract boolean implies(Permission permission);
123
124 /**
125 * Checks two Permission objects for equality.
126 * <P>
127 * Do not use the <code>equals</code> method for making access control
128 * decisions; use the <code>implies</code> method.
129 *
130 * @param obj the object we are testing for equality with this object.
131 *
132 * @return true if both Permission objects are equivalent.
133 */
134
135 public abstract boolean equals(Object obj);
136
137 /**
138 * Returns the hash code value for this Permission object.
139 * <P>
140 * The required <code>hashCode</code> behavior for Permission Objects is
141 * the following: <p>
142 * <ul>
143 * <li>Whenever it is invoked on the same Permission object more than
144 * once during an execution of a Java application, the
145 * <code>hashCode</code> method
146 * must consistently return the same integer. This integer need not
147 * remain consistent from one execution of an application to another
148 * execution of the same application. <p>
149 * <li>If two Permission objects are equal according to the
150 * <code>equals</code>
151 * method, then calling the <code>hashCode</code> method on each of the
152 * two Permission objects must produce the same integer result.
153 * </ul>
154 *
155 * @return a hash code value for this object.
156 */
157
158 public abstract int hashCode();
159
160 /**
161 * Returns the name of this Permission.
162 * For example, in the case of a <code>java.io.FilePermission</code>,
163 * the name will be a pathname.
164 *
165 * @return the name of this Permission.
166 *
167 */
168
169 public final String getName() {
170 return name;
171 }
172
173 /**
174 * Returns the actions as a String. This is abstract
175 * so subclasses can defer creating a String representation until
176 * one is needed. Subclasses should always return actions in what they
177 * consider to be their
178 * canonical form. For example, two FilePermission objects created via
179 * the following:
180 *
181 * <pre>
182 * perm1 = new FilePermission(p1,"read,write");
183 * perm2 = new FilePermission(p2,"write,read");
184 * </pre>
185 *
186 * both return
187 * "read,write" when the <code>getActions</code> method is invoked.
188 *
189 * @return the actions of this Permission.
190 *
191 */
192
193 public abstract String getActions();
194
195 /**
196 * Returns an empty PermissionCollection for a given Permission object, or null if
197 * one is not defined. Subclasses of class Permission should
198 * override this if they need to store their permissions in a particular
199 * PermissionCollection object in order to provide the correct semantics
200 * when the <code>PermissionCollection.implies</code> method is called.
201 * If null is returned,
202 * then the caller of this method is free to store permissions of this
203 * type in any PermissionCollection they choose (one that uses a Hashtable,
204 * one that uses a Vector, etc).
205 *
206 * @return a new PermissionCollection object for this type of Permission, or
207 * null if one is not defined.
208 */
209
210 public PermissionCollection newPermissionCollection() {
211 return null;
212 }
213
214 /**
215 * Returns a string describing this Permission. The convention is to
216 * specify the class name, the permission name, and the actions in
217 * the following format: '("ClassName" "name" "actions")'.
218 *
219 * @return information about this Permission.
220 */
221
222 public String toString() {
223 String actions = getActions();
224 if ((actions == null) || (actions.length() == 0)) { // OPTIONAL
225 return "(" + getClass().getName() + " " + name + ")";
226 } else {
227 return "(" + getClass().getName() + " " + name + " " +
228 actions + ")";
229 }
230 }
231 }
Save This Page