View Javadoc
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   */
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} 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} 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} 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} method for making access control
128      * decisions; use the {@code implies} 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} behavior for Permission Objects is
141      * the following:
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} 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.
149      * <li>If two Permission objects are equal according to the
150      *     {@code equals}
151      *     method, then calling the {@code hashCode} 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},
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} 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} 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")', or
218      * '("ClassName" "name")' if actions list is null or empty.
219      *
220      * @return information about this Permission.
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 }