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