001: /*
002: * @(#)PermissionCollection.java 1.34 06/10/11
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.security;
029:
030: import java.util.*;
031:
032: /**
033: * Abstract class representing a collection of Permission objects.
034: *
035: * <p>With a PermissionCollection, you can:
036: * <UL>
037: * <LI> add a permission to the collection using the <code>add</code> method.
038: * <LI> check to see if a particular permission is implied in the
039: * collection, using the <code>implies</code> method.
040: * <LI> enumerate all the permissions, using the <code>elements</code> method.
041: * </UL>
042: * <P>
043: *
044: * <p>When it is desirable to group together a number of Permission objects
045: * of the same type, the <code>newPermissionCollection</code> method on that
046: * particular type of Permission object should first be called. The default
047: * behavior (from the Permission class) is to simply return null.
048: * Subclasses of class Permission override the method if they need to store
049: * their permissions in a particular PermissionCollection object in order
050: * to provide the correct semantics when the
051: * <code>PermissionCollection.implies</code> method is called.
052: * If a non-null value is returned, that PermissionCollection must be used.
053: * If null is returned, then the caller of <code>newPermissionCollection</code>
054: * is free to store permissions of the
055: * given type in any PermissionCollection they choose
056: * (one that uses a Hashtable, one that uses a Vector, etc).
057: *
058: * <p>The PermissionCollection returned by the
059: * <code>Permission.newPermissionCollection</code>
060: * method is a homogeneous collection, which stores only Permission objects
061: * for a given Permission type. A PermissionCollection may also be
062: * heterogenous. For example, Permissions is a PermissionCollection
063: * subclass that represents a collection of PermissionCollections.
064: * That is, its members are each a homogeneous PermissionCollection.
065: * For example, a Permissions object might have a FilePermissionCollection
066: * for all the FilePermission objects, a SocketPermissionCollection for all the
067: * SocketPermission objects, and so on. Its <code>add</code> method adds a
068: * permission to the appropriate collection.
069: *
070: * <p>Whenever a permission is added to a heterogeneous PermissionCollection
071: * such as Permissions, and the PermissionCollection doesn't yet contain a
072: * PermissionCollection of the specified permission's type, the
073: * PermissionCollection should call
074: * the <code>newPermissionCollection</code> method on the permission's class
075: * to see if it requires a special PermissionCollection. If
076: * <code>newPermissionCollection</code>
077: * returns null, the PermissionCollection
078: * is free to store the permission in any type of PermissionCollection it
079: * desires (one using a Hastable, one using a Vector, etc.). For example,
080: * the Permissions object uses a default PermissionCollection implementation
081: * that stores the permission objects in a Hashtable.
082: *
083: * <p> Subclass implementations of PermissionCollection should assume
084: * that they may be called simultaneously from multiple threads,
085: * and therefore should be synchronized properly. Furthermore,
086: * Enumerations returned via the <code>elements</code> method are
087: * not <em>fail-fast</em>. Modifications to a collection should not be
088: * performed while enumerating over that collection.
089: *
090: * @see Permission
091: * @see Permissions
092: *
093: * @version 1.26 00/02/02
094: *
095: * @author Roland Schemers
096: */
097:
098: public abstract class PermissionCollection implements
099: java.io.Serializable {
100:
101: private static final long serialVersionUID = -6727011328946861783L;
102:
103: // when set, add will throw an exception.
104: private boolean readOnly;
105:
106: /**
107: * Adds a permission object to the current collection of permission objects.
108: *
109: * @param permission the Permission object to add.
110: *
111: * @exception SecurityException - if this PermissionCollection object
112: * has been marked readonly
113: */
114: public abstract void add(Permission permission);
115:
116: /**
117: * Checks to see if the specified permission is implied by
118: * the collection of Permission objects held in this PermissionCollection.
119: *
120: * @param permission the Permission object to compare.
121: *
122: * @return true if "permission" is implied by the permissions in
123: * the collection, false if not.
124: */
125: public abstract boolean implies(Permission permission);
126:
127: /**
128: * Returns an enumeration of all the Permission objects in the collection.
129: *
130: * @return an enumeration of all the Permissions.
131: */
132: public abstract Enumeration elements();
133:
134: /**
135: * Marks this PermissionCollection object as "readonly". After
136: * a PermissionCollection object
137: * is marked as readonly, no new Permission objects can be added to it
138: * using <code>add</code>.
139: */
140: public void setReadOnly() {
141: readOnly = true;
142: }
143:
144: /**
145: * Returns true if this PermissionCollection object is marked as readonly.
146: * If it is readonly, no new Permission objects can be added to it
147: * using <code>add</code>.
148: *
149: * <p>By default, the object is <i>not</i> readonly. It can be set to
150: * readonly by a call to <code>setReadOnly</code>.
151: *
152: * @return true if this PermissionCollection object is marked as readonly,
153: * false otherwise.
154: */
155: public boolean isReadOnly() {
156: return readOnly;
157: }
158:
159: /**
160: * Returns a string describing this PermissionCollection object,
161: * providing information about all the permissions it contains.
162: * The format is:
163: * <pre>
164: * super.toString() (
165: * // enumerate all the Permission
166: * // objects and call toString() on them,
167: * // one per line..
168: * )</pre>
169: *
170: * <code>super.toString</code> is a call to the <code>toString</code>
171: * method of this
172: * object's superclass, which is Object. The result is
173: * this PermissionCollection's type name followed by this object's
174: * hashcode, thus enabling clients to differentiate different
175: * PermissionCollections object, even if they contain the same permissions.
176: *
177: * @return information about this PermissionCollection object,
178: * as described above.
179: *
180: */
181: public String toString() {
182: Enumeration enum_ = elements();
183: StringBuffer sb = new StringBuffer();
184: sb.append(super .toString() + " (\n");
185: while (enum_.hasMoreElements()) {
186: try {
187: sb.append(" ");
188: sb.append(enum_.nextElement().toString());
189: sb.append("\n");
190: } catch (NoSuchElementException e) {
191: // ignore
192: }
193: }
194: sb.append(")\n");
195: return sb.toString();
196: }
197: }
|