KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > security > 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 JavaDoc {
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 JavaDoc 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 JavaDoc 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 JavaDoc> 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 JavaDoc toString() {
161     Enumeration enum_ = elements();
162     StringBuilder JavaDoc sb = new StringBuilder JavaDoc();
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
Popular Tags