001: /*
002: * @(#)AclEntry.java 1.22 06/10/10
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.acl;
029:
030: import java.util.Enumeration;
031: import java.security.Principal;
032:
033: /**
034: * This is the interface used for representing one entry in an Access
035: * Control List (ACL).<p>
036: *
037: * An ACL can be thought of as a data structure with multiple ACL entry
038: * objects. Each ACL entry object contains a set of permissions associated
039: * with a particular principal. (A principal represents an entity such as
040: * an individual user or a group). Additionally, each ACL entry is specified
041: * as being either positive or negative. If positive, the permissions are
042: * to be granted to the associated principal. If negative, the permissions
043: * are to be denied. Each principal can have at most one positive ACL entry
044: * and one negative entry; that is, multiple positive or negative ACL
045: * entries are not allowed for any principal.
046: *
047: * Note: ACL entries are by default positive. An entry becomes a
048: * negative entry only if the
049: * {@link #setNegativePermissions() setNegativePermissions}
050: * method is called on it.
051: *
052: * @see java.security.acl.Acl
053: *
054: * @author Satish Dharmaraj
055: */
056: public interface AclEntry extends Cloneable {
057:
058: /**
059: * Specifies the principal for which permissions are granted or denied
060: * by this ACL entry. If a principal was already set for this ACL entry,
061: * false is returned, otherwise true is returned.
062: *
063: * @param user the principal to be set for this entry.
064: *
065: * @return true if the principal is set, false if there was
066: * already a principal set for this entry.
067: *
068: * @see #getPrincipal
069: */
070: public boolean setPrincipal(Principal user);
071:
072: /**
073: * Returns the principal for which permissions are granted or denied by
074: * this ACL entry. Returns null if there is no principal set for this
075: * entry yet.
076: *
077: * @return the principal associated with this entry.
078: *
079: * @see #setPrincipal
080: */
081: public Principal getPrincipal();
082:
083: /**
084: * Sets this ACL entry to be a negative one. That is, the associated
085: * principal (e.g., a user or a group) will be denied the permission set
086: * specified in the entry.
087: *
088: * Note: ACL entries are by default positive. An entry becomes a
089: * negative entry only if this <code>setNegativePermissions</code>
090: * method is called on it.
091: */
092: public void setNegativePermissions();
093:
094: /**
095: * Returns true if this is a negative ACL entry (one denying the
096: * associated principal the set of permissions in the entry), false
097: * otherwise.
098: *
099: * @return true if this is a negative ACL entry, false if it's not.
100: */
101: public boolean isNegative();
102:
103: /**
104: * Adds the specified permission to this ACL entry. Note: An entry can
105: * have multiple permissions.
106: *
107: * @param permission the permission to be associated with
108: * the principal in this entry.
109: *
110: * @return true if the permission was added, false if the
111: * permission was already part of this entry's permission set.
112: */
113: public boolean addPermission(Permission permission);
114:
115: /**
116: * Removes the specified permission from this ACL entry.
117: *
118: * @param permission the permission to be removed from this entry.
119: *
120: * @return true if the permission is removed, false if the
121: * permission was not part of this entry's permission set.
122: */
123: public boolean removePermission(Permission permission);
124:
125: /**
126: * Checks if the specified permission is part of the
127: * permission set in this entry.
128: *
129: * @param permission the permission to be checked for.
130: *
131: * @return true if the permission is part of the
132: * permission set in this entry, false otherwise.
133: */
134: public boolean checkPermission(Permission permission);
135:
136: /**
137: * Returns an enumeration of the permissions in this ACL entry.
138: *
139: * @return an enumeration of the permissions in this ACL entry.
140: */
141: public Enumeration permissions();
142:
143: /**
144: * Returns a string representation of the contents of this ACL entry.
145: *
146: * @return a string representation of the contents.
147: */
148: public String toString();
149:
150: /**
151: * Clones this ACL entry.
152: *
153: * @return a clone of this ACL entry.
154: */
155: public Object clone();
156: }
|