1. /*
  2. * @(#)AclEntry.java 1.18 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.acl;
  8. import java.util.Enumeration;
  9. import java.security.Principal;
  10. /**
  11. * This is the interface used for representing one entry in an Access
  12. * Control List (ACL).<p>
  13. *
  14. * An ACL can be thought of as a data structure with multiple ACL entry
  15. * objects. Each ACL entry object contains a set of permissions associated
  16. * with a particular principal. (A principal represents an entity such as
  17. * an individual user or a group). Additionally, each ACL entry is specified
  18. * as being either positive or negative. If positive, the permissions are
  19. * to be granted to the associated principal. If negative, the permissions
  20. * are to be denied. Each principal can have at most one positive ACL entry
  21. * and one negative entry; that is, multiple positive or negative ACL
  22. * entries are not allowed for any principal.
  23. *
  24. * Note: ACL entries are by default positive. An entry becomes a
  25. * negative entry only if the
  26. * {@link #setNegativePermissions() setNegativePermissions}
  27. * method is called on it.
  28. *
  29. * @see java.security.acl.Acl
  30. *
  31. * @author Satish Dharmaraj
  32. */
  33. public interface AclEntry extends Cloneable {
  34. /**
  35. * Specifies the principal for which permissions are granted or denied
  36. * by this ACL entry. If a principal was already set for this ACL entry,
  37. * false is returned, otherwise true is returned.
  38. *
  39. * @param user the principal to be set for this entry.
  40. *
  41. * @return true if the principal is set, false if there was
  42. * already a principal set for this entry.
  43. *
  44. * @see #getPrincipal
  45. */
  46. public boolean setPrincipal(Principal user);
  47. /**
  48. * Returns the principal for which permissions are granted or denied by
  49. * this ACL entry. Returns null if there is no principal set for this
  50. * entry yet.
  51. *
  52. * @return the principal associated with this entry.
  53. *
  54. * @see #setPrincipal
  55. */
  56. public Principal getPrincipal();
  57. /**
  58. * Sets this ACL entry to be a negative one. That is, the associated
  59. * principal (e.g., a user or a group) will be denied the permission set
  60. * specified in the entry.
  61. *
  62. * Note: ACL entries are by default positive. An entry becomes a
  63. * negative entry only if this <code>setNegativePermissions</code>
  64. * method is called on it.
  65. */
  66. public void setNegativePermissions();
  67. /**
  68. * Returns true if this is a negative ACL entry (one denying the
  69. * associated principal the set of permissions in the entry), false
  70. * otherwise.
  71. *
  72. * @return true if this is a negative ACL entry, false if it's not.
  73. */
  74. public boolean isNegative();
  75. /**
  76. * Adds the specified permission to this ACL entry. Note: An entry can
  77. * have multiple permissions.
  78. *
  79. * @param permission the permission to be associated with
  80. * the principal in this entry.
  81. *
  82. * @return true if the permission was added, false if the
  83. * permission was already part of this entry's permission set.
  84. */
  85. public boolean addPermission(Permission permission);
  86. /**
  87. * Removes the specified permission from this ACL entry.
  88. *
  89. * @param permission the permission to be removed from this entry.
  90. *
  91. * @return true if the permission is removed, false if the
  92. * permission was not part of this entry's permission set.
  93. */
  94. public boolean removePermission(Permission permission);
  95. /**
  96. * Checks if the specified permission is part of the
  97. * permission set in this entry.
  98. *
  99. * @param permission the permission to be checked for.
  100. *
  101. * @return true if the permission is part of the
  102. * permission set in this entry, false otherwise.
  103. */
  104. public boolean checkPermission(Permission permission);
  105. /**
  106. * Returns an enumeration of the permissions in this ACL entry.
  107. *
  108. * @return an enumeration of the permissions in this ACL entry.
  109. */
  110. public Enumeration permissions();
  111. /**
  112. * Returns a string representation of the contents of this ACL entry.
  113. *
  114. * @return a string representation of the contents.
  115. */
  116. public String toString();
  117. /**
  118. * Clones this ACL entry.
  119. *
  120. * @return a clone of this ACL entry.
  121. */
  122. public Object clone();
  123. }