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