001 /*
002 * Copyright 1997-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.security;
027
028 /**
029 * Abstract class for representing access to a system resource.
030 * All permissions have a name (whose interpretation depends on the subclass),
031 * as well as abstract functions for defining the semantics of the
032 * particular Permission subclass.
033 *
034 * <p>Most Permission objects also include an "actions" list that tells the actions
035 * that are permitted for the object. For example,
036 * for a <code>java.io.FilePermission</code> object, the permission name is
037 * the pathname of a file (or directory), and the actions list
038 * (such as "read, write") specifies which actions are granted for the
039 * specified file (or for files in the specified directory).
040 * The actions list is optional for Permission objects, such as
041 * <code>java.lang.RuntimePermission</code>,
042 * that don't need such a list; you either have the named permission (such
043 * as "system.exit") or you don't.
044 *
045 * <p>An important method that must be implemented by each subclass is
046 * the <code>implies</code> method to compare Permissions. Basically,
047 * "permission p1 implies permission p2" means that
048 * if one is granted permission p1, one is naturally granted permission p2.
049 * Thus, this is not an equality test, but rather more of a
050 * subset test.
051 *
052 * <P> Permission objects are similar to String objects in that they
053 * are immutable once they have been created. Subclasses should not
054 * provide methods that can change the state of a permission
055 * once it has been created.
056 *
057 * @see Permissions
058 * @see PermissionCollection
059 *
060 * @version 1.46 07/05/05
061 *
062 * @author Marianne Mueller
063 * @author Roland Schemers
064 */
065
066 public abstract class Permission implements Guard, java.io.Serializable {
067
068 private static final long serialVersionUID = -5636570222231596674L;
069
070 private String name;
071
072 /**
073 * Constructs a permission with the specified name.
074 *
075 * @param name name of the Permission object being created.
076 *
077 */
078
079 public Permission(String name) {
080 this .name = name;
081 }
082
083 /**
084 * Implements the guard interface for a permission. The
085 * <code>SecurityManager.checkPermission</code> method is called,
086 * passing this permission object as the permission to check.
087 * Returns silently if access is granted. Otherwise, throws
088 * a SecurityException.
089 *
090 * @param object the object being guarded (currently ignored).
091 *
092 * @throws SecurityException
093 * if a security manager exists and its
094 * <code>checkPermission</code> method doesn't allow access.
095 *
096 * @see Guard
097 * @see GuardedObject
098 * @see SecurityManager#checkPermission
099 *
100 */
101 public void checkGuard(Object object) throws SecurityException {
102 SecurityManager sm = System.getSecurityManager();
103 if (sm != null)
104 sm.checkPermission(this );
105 }
106
107 /**
108 * Checks if the specified permission's actions are "implied by"
109 * this object's actions.
110 * <P>
111 * This must be implemented by subclasses of Permission, as they are the
112 * only ones that can impose semantics on a Permission object.
113 *
114 * <p>The <code>implies</code> method is used by the AccessController to determine
115 * whether or not a requested permission is implied by another permission that
116 * is known to be valid in the current execution context.
117 *
118 * @param permission the permission to check against.
119 *
120 * @return true if the specified permission is implied by this object,
121 * false if not.
122 */
123
124 public abstract boolean implies(Permission permission);
125
126 /**
127 * Checks two Permission objects for equality.
128 * <P>
129 * Do not use the <code>equals</code> method for making access control
130 * decisions; use the <code>implies</code> method.
131 *
132 * @param obj the object we are testing for equality with this object.
133 *
134 * @return true if both Permission objects are equivalent.
135 */
136
137 public abstract boolean equals(Object obj);
138
139 /**
140 * Returns the hash code value for this Permission object.
141 * <P>
142 * The required <code>hashCode</code> behavior for Permission Objects is
143 * the following: <p>
144 * <ul>
145 * <li>Whenever it is invoked on the same Permission object more than
146 * once during an execution of a Java application, the
147 * <code>hashCode</code> method
148 * must consistently return the same integer. This integer need not
149 * remain consistent from one execution of an application to another
150 * execution of the same application. <p>
151 * <li>If two Permission objects are equal according to the
152 * <code>equals</code>
153 * method, then calling the <code>hashCode</code> method on each of the
154 * two Permission objects must produce the same integer result.
155 * </ul>
156 *
157 * @return a hash code value for this object.
158 */
159
160 public abstract int hashCode();
161
162 /**
163 * Returns the name of this Permission.
164 * For example, in the case of a <code>java.io.FilePermission</code>,
165 * the name will be a pathname.
166 *
167 * @return the name of this Permission.
168 *
169 */
170
171 public final String getName() {
172 return name;
173 }
174
175 /**
176 * Returns the actions as a String. This is abstract
177 * so subclasses can defer creating a String representation until
178 * one is needed. Subclasses should always return actions in what they
179 * consider to be their
180 * canonical form. For example, two FilePermission objects created via
181 * the following:
182 *
183 * <pre>
184 * perm1 = new FilePermission(p1,"read,write");
185 * perm2 = new FilePermission(p2,"write,read");
186 * </pre>
187 *
188 * both return
189 * "read,write" when the <code>getActions</code> method is invoked.
190 *
191 * @return the actions of this Permission.
192 *
193 */
194
195 public abstract String getActions();
196
197 /**
198 * Returns an empty PermissionCollection for a given Permission object, or null if
199 * one is not defined. Subclasses of class Permission should
200 * override this if they need to store their permissions in a particular
201 * PermissionCollection object in order to provide the correct semantics
202 * when the <code>PermissionCollection.implies</code> method is called.
203 * If null is returned,
204 * then the caller of this method is free to store permissions of this
205 * type in any PermissionCollection they choose (one that uses a Hashtable,
206 * one that uses a Vector, etc).
207 *
208 * @return a new PermissionCollection object for this type of Permission, or
209 * null if one is not defined.
210 */
211
212 public PermissionCollection newPermissionCollection() {
213 return null;
214 }
215
216 /**
217 * Returns a string describing this Permission. The convention is to
218 * specify the class name, the permission name, and the actions in
219 * the following format: '("ClassName" "name" "actions")'.
220 *
221 * @return information about this Permission.
222 */
223
224 public String toString() {
225 String actions = getActions();
226 if ((actions == null) || (actions.length() == 0)) { // OPTIONAL
227 return "(" + getClass().getName() + " " + name + ")";
228 } else {
229 return "(" + getClass().getName() + " " + name + " "
230 + actions + ")";
231 }
232 }
233 }
|