PermissionCollection


1   /*
2    * @(#)PermissionCollection.java    1.35 04/05/05
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  import java.util.*;
11  
12  /**
13   * Abstract class representing a collection of Permission objects.
14   *
15   * <p>With a PermissionCollection, you can:
16   * <UL>
17   * <LI> add a permission to the collection using the <code>add</code> method.
18   * <LI> check to see if a particular permission is implied in the
19   *      collection, using the <code>implies</code> method.
20   * <LI> enumerate all the permissions, using the <code>elements</code> method.
21   * </UL>
22   * <P>
23   *
24   * <p>When it is desirable to group together a number of Permission objects
25   * of the same type, the <code>newPermissionCollection</code> method on that
26   * particular type of Permission object should first be called. The default
27   * behavior (from the Permission class) is to simply return null.
28   * Subclasses of class Permission override the method if they need to store
29   * their permissions in a particular PermissionCollection object in order
30   * to provide the correct semantics when the
31   * <code>PermissionCollection.implies</code> method is called.
32   * If a non-null value is returned, that PermissionCollection must be used.
33   * If null is returned, then the caller of <code>newPermissionCollection</code>
34   * is free to store permissions of the
35   * given type in any PermissionCollection they choose
36   * (one that uses a Hashtable, one that uses a Vector, etc).
37   *
38   * <p>The PermissionCollection returned by the
39   * <code>Permission.newPermissionCollection</code>
40   * method is a homogeneous collection, which stores only Permission objects
41   * for a given Permission type.  A PermissionCollection may also be
42   * heterogeneous.  For example, Permissions is a PermissionCollection
43   * subclass that represents a collection of PermissionCollections.
44   * That is, its members are each a homogeneous PermissionCollection.
45   * For example, a Permissions object might have a FilePermissionCollection
46   * for all the FilePermission objects, a SocketPermissionCollection for all the
47   * SocketPermission objects, and so on. Its <code>add</code> method adds a
48   * permission to the appropriate collection.
49   *
50   * <p>Whenever a permission is added to a heterogeneous PermissionCollection
51   * such as Permissions, and the PermissionCollection doesn't yet contain a
52   * PermissionCollection of the specified permission's type, the
53   * PermissionCollection should call
54   * the <code>newPermissionCollection</code> method on the permission's class
55   * to see if it requires a special PermissionCollection. If
56   * <code>newPermissionCollection</code>
57   * returns null, the PermissionCollection
58   * is free to store the permission in any type of PermissionCollection it
59   * desires (one using a Hashtable, one using a Vector, etc.). For example,
60   * the Permissions object uses a default PermissionCollection implementation
61   * that stores the permission objects in a Hashtable.
62   *
63   * <p> Subclass implementations of PermissionCollection should assume
64   * that they may be called simultaneously from multiple threads,
65   * and therefore should be synchronized properly.  Furthermore,
66   * Enumerations returned via the <code>elements</code> method are
67   * not <em>fail-fast</em>.  Modifications to a collection should not be
68   * performed while enumerating over that collection.
69   *
70   * @see Permission
71   * @see Permissions
72   *
73   * @version 1.35 04/05/05
74   *
75   * @author Roland Schemers
76   */
77  
78  public abstract class PermissionCollection implements java.io.Serializable   {
79  
80      private static final long serialVersionUID = -6727011328946861783L;
81  
82      // when set, add will throw an exception.
83      private volatile boolean readOnly;
84  
85      /**
86       * Adds a permission object to the current collection of permission objects.
87       *
88       * @param permission the Permission object to add.
89       *
90       * @exception SecurityException -  if this PermissionCollection object
91       *                                 has been marked readonly
92       */
93      public abstract void add(Permission   permission);
94  
95      /**
96       * Checks to see if the specified permission is implied by
97       * the collection of Permission objects held in this PermissionCollection.
98       *
99       * @param permission the Permission object to compare.
100      *
101      * @return true if "permission" is implied by the  permissions in
102      * the collection, false if not.
103      */
104     public abstract boolean implies(Permission   permission);
105 
106     /**
107      * Returns an enumeration of all the Permission objects in the collection.
108      *
109      * @return an enumeration of all the Permissions.
110      */
111     public abstract Enumeration<Permission  > elements();
112 
113     /**
114      * Marks this PermissionCollection object as "readonly". After
115      * a PermissionCollection object
116      * is marked as readonly, no new Permission objects can be added to it
117      * using <code>add</code>.
118      */
119     public void setReadOnly() {
120     readOnly = true;
121     }
122 
123     /**
124      * Returns true if this PermissionCollection object is marked as readonly.
125      * If it is readonly, no new Permission objects can be added to it
126      * using <code>add</code>.
127      *
128      * <p>By default, the object is <i>not</i> readonly. It can be set to
129      * readonly by a call to <code>setReadOnly</code>.
130      *
131      * @return true if this PermissionCollection object is marked as readonly,
132      * false otherwise.
133      */
134     public boolean isReadOnly() {
135     return readOnly;
136     }
137 
138     /**
139      * Returns a string describing this PermissionCollection object,
140      * providing information about all the permissions it contains.
141      * The format is:
142      * <pre>
143      * super.toString() (
144      *   // enumerate all the Permission
145      *   // objects and call toString() on them,
146      *   // one per line..
147      * )</pre>
148      *
149      * <code>super.toString</code> is a call to the <code>toString</code>
150      * method of this
151      * object's superclass, which is Object. The result is
152      * this PermissionCollection's type name followed by this object's
153      * hashcode, thus enabling clients to differentiate different
154      * PermissionCollections object, even if they contain the same permissions.
155      *
156      * @return information about this PermissionCollection object,
157      *         as described above.
158      *
159      */
160     public String   toString() {
161     Enumeration enum_ = elements();
162     StringBuilder   sb = new StringBuilder  ();
163     sb.append(super.toString()+" (\n");
164     while (enum_.hasMoreElements()) {
165         try {
166         sb.append(" ");
167         sb.append(enum_.nextElement().toString());
168         sb.append("\n");
169         } catch (NoSuchElementException e){
170         // ignore
171         }
172     }
173     sb.append(")\n");
174     return sb.toString();
175     }
176 }
177
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags