1. /*
  2. * @(#)Permission.java 1.39 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.security;
  8. /**
  9. * Abstract class for representing access to a system resource.
  10. * All permissions have a name (whose interpretation depends on the subclass),
  11. * as well as abstract functions for defining the semantics of the
  12. * particular Permission subclass.
  13. *
  14. * <p>Most Permission objects also include an "actions" list that tells the actions
  15. * that are permitted for the object. For example,
  16. * for a <code>java.io.FilePermission</code> object, the permission name is
  17. * the pathname of a file (or directory), and the actions list
  18. * (such as "read, write") specifies which actions are granted for the
  19. * specified file (or for files in the specified directory).
  20. * The actions list is optional for Permission objects, such as
  21. * <code>java.lang.RuntimePermission</code>,
  22. * that don't need such a list; you either have the named permission (such
  23. * as "system.exit") or you don't.
  24. *
  25. * <p>An important method that must be implemented by each subclass is
  26. * the <code>implies</code> method to compare Permissions. Basically,
  27. * "permission p1 implies permission p2" means that
  28. * if one is granted permission p1, one is naturally granted permission p2.
  29. * Thus, this is not an equality test, but rather more of a
  30. * subset test.
  31. *
  32. * <P> Permission objects are similar to String objects in that they
  33. * are immutable once they have been created. Subclasses should not
  34. * provide methods that can change the state of a permission
  35. * once it has been created.
  36. *
  37. * @see Permissions
  38. * @see PermissionCollection
  39. *
  40. * @version 1.39 03/12/19
  41. *
  42. * @author Marianne Mueller
  43. * @author Roland Schemers
  44. */
  45. public abstract class Permission implements Guard, java.io.Serializable {
  46. private static final long serialVersionUID = -5636570222231596674L;
  47. private String name;
  48. /**
  49. * Constructs a permission with the specified name.
  50. *
  51. * @param name name of the Permission object being created.
  52. *
  53. */
  54. public Permission(String name) {
  55. this.name = name;
  56. }
  57. /**
  58. * Implements the guard interface for a permission. The
  59. * <code>SecurityManager.checkPermission</code> method is called,
  60. * passing this permission object as the permission to check.
  61. * Returns silently if access is granted. Otherwise, throws
  62. * a SecurityException.
  63. *
  64. * @param object the object being guarded (currently ignored).
  65. *
  66. * @throws SecurityException
  67. * if a security manager exists and its
  68. * <code>checkPermission</code> method doesn't allow access.
  69. *
  70. * @see Guard
  71. * @see GuardedObject
  72. * @see SecurityManager#checkPermission
  73. *
  74. */
  75. public void checkGuard(Object object) throws SecurityException {
  76. SecurityManager sm = System.getSecurityManager();
  77. if (sm != null) sm.checkPermission(this);
  78. }
  79. /**
  80. * Checks if the specified permission's actions are "implied by"
  81. * this object's actions.
  82. * <P>
  83. * This must be implemented by subclasses of Permission, as they are the
  84. * only ones that can impose semantics on a Permission object.
  85. *
  86. * <p>The <code>implies</code> method is used by the AccessController to determine
  87. * whether or not a requested permission is implied by another permission that
  88. * is known to be valid in the current execution context.
  89. *
  90. * @param permission the permission to check against.
  91. *
  92. * @return true if the specified permission is implied by this object,
  93. * false if not.
  94. */
  95. public abstract boolean implies(Permission permission);
  96. /**
  97. * Checks two Permission objects for equality.
  98. * <P>
  99. * Do not use the <code>equals</code> method for making access control
  100. * decisions; use the <code>implies</code> method.
  101. *
  102. * @param obj the object we are testing for equality with this object.
  103. *
  104. * @return true if both Permission objects are equivalent.
  105. */
  106. public abstract boolean equals(Object obj);
  107. /**
  108. * Returns the hash code value for this Permission object.
  109. * <P>
  110. * The required <code>hashCode</code> behavior for Permission Objects is
  111. * the following: <p>
  112. * <ul>
  113. * <li>Whenever it is invoked on the same Permission object more than
  114. * once during an execution of a Java application, the
  115. * <code>hashCode</code> method
  116. * must consistently return the same integer. This integer need not
  117. * remain consistent from one execution of an application to another
  118. * execution of the same application. <p>
  119. * <li>If two Permission objects are equal according to the
  120. * <code>equals</code>
  121. * method, then calling the <code>hashCode</code> method on each of the
  122. * two Permission objects must produce the same integer result.
  123. * </ul>
  124. *
  125. * @return a hash code value for this object.
  126. */
  127. public abstract int hashCode();
  128. /**
  129. * Returns the name of this Permission.
  130. * For example, in the case of a <code>java.io.FilePermission</code>,
  131. * the name will be a pathname.
  132. *
  133. * @return the name of this Permission.
  134. *
  135. */
  136. public final String getName() {
  137. return name;
  138. }
  139. /**
  140. * Returns the actions as a String. This is abstract
  141. * so subclasses can defer creating a String representation until
  142. * one is needed. Subclasses should always return actions in what they
  143. * consider to be their
  144. * canonical form. For example, two FilePermission objects created via
  145. * the following:
  146. *
  147. * <pre>
  148. * perm1 = new FilePermission(p1,"read,write");
  149. * perm2 = new FilePermission(p2,"write,read");
  150. * </pre>
  151. *
  152. * both return
  153. * "read,write" when the <code>getActions</code> method is invoked.
  154. *
  155. * @return the actions of this Permission.
  156. *
  157. */
  158. public abstract String getActions();
  159. /**
  160. * Returns an empty PermissionCollection for a given Permission object, or null if
  161. * one is not defined. Subclasses of class Permission should
  162. * override this if they need to store their permissions in a particular
  163. * PermissionCollection object in order to provide the correct semantics
  164. * when the <code>PermissionCollection.implies</code> method is called.
  165. * If null is returned,
  166. * then the caller of this method is free to store permissions of this
  167. * type in any PermissionCollection they choose (one that uses a Hashtable,
  168. * one that uses a Vector, etc).
  169. *
  170. * @return a new PermissionCollection object for this type of Permission, or
  171. * null if one is not defined.
  172. */
  173. public PermissionCollection newPermissionCollection() {
  174. return null;
  175. }
  176. /**
  177. * Returns a string describing this Permission. The convention is to
  178. * specify the class name, the permission name, and the actions in
  179. * the following format: '("ClassName" "name" "actions")'.
  180. *
  181. * @return information about this Permission.
  182. */
  183. public String toString() {
  184. String actions = getActions();
  185. if ((actions == null) || (actions.length() == 0)) { // OPTIONAL
  186. return "(" + getClass().getName() + " " + name + ")";
  187. } else {
  188. return "(" + getClass().getName() + " " + name + " " +
  189. actions + ")";
  190. }
  191. }
  192. }