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: }
| 