Permission


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