001: /*
002: JSPWiki - a JSP-based WikiWiki clone.
003:
004: Copyright (C) 2001-2002 Janne Jalkanen (Janne.Jalkanen@iki.fi)
005:
006: This program is free software; you can redistribute it and/or modify
007: it under the terms of the GNU Lesser General Public License as published by
008: the Free Software Foundation; either version 2.1 of the License, or
009: (at your option) any later version.
010:
011: This program is distributed in the hope that it will be useful,
012: but WITHOUT ANY WARRANTY; without even the implied warranty of
013: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: GNU Lesser General Public License for more details.
015:
016: You should have received a copy of the GNU Lesser General Public License
017: along with this program; if not, write to the Free Software
018: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: */
020: package com.ecyrd.jspwiki.auth.acl;
021:
022: import java.security.Permission;
023: import java.security.Principal;
024: import java.util.Enumeration;
025:
026: /**
027: * <p>
028: * Defines an access control list (ACL) for wiki pages. An Access Control List
029: * is a data structure used to guard access to resources. An ACL can be thought
030: * of as a data structure with multiple ACL entries. Each ACL entry, of
031: * interface type AclEntry, contains a set of positive permissions associated
032: * with a particular principal. (A principal represents an entity such as an
033: * individual user or a group). The ACL Entries in each ACL observe the
034: * following rules:
035: * </p>
036: * <ul>
037: * <li>Each principal can have at most one ACL entry; that is, multiple ACL
038: * entries are not allowed for any principal. Each entry specifies the set of
039: * permissions that are to be granted</li>
040: * <li>If there is no entry for a particular principal, then the principal is
041: * considered to have a null (empty) permission set</li>
042: * </ul>
043: * <p>
044: * This interface is a highly stripped-down derivation of the
045: * java.security.acl.Acl interface. In particular, the notion of an Acl "owner"
046: * has been eliminated, since JWPWiki pages do not have owners. An additional
047: * simplification compared to the standard Java package is that negative
048: * permissions have been eliminated. Instead, JSPWiki assumes a "default-deny"
049: * security stance: principals are granted no permissions by default, and
050: * posesses only those that have been explicitly granted to them. And finally,
051: * the getPermissions() and checkPermission() methods have been eliminated due
052: * to the complexities associated with resolving Role principal membership.
053: * </p>
054: * @author Janne Jalkanen
055: * @author Andrew Jaquith
056: * @since 2.3
057: */
058: public interface Acl {
059: /**
060: * Adds an ACL entry to this ACL. An entry associates a principal (e.g., an
061: * individual or a group) with a set of permissions. Each principal can have
062: * at most one positive ACL entry, specifying permissions to be granted to
063: * the principal. If there is already an ACL entry already in the ACL, false
064: * is returned.
065: * @param entry - the ACL entry to be added to this ACL
066: * @return true on success, false if an entry of the same type (positive or
067: * negative) for the same principal is already present in this ACL
068: */
069: public boolean addEntry(AclEntry entry);
070:
071: /**
072: * Returns an enumeration of the entries in this ACL. Each element in the
073: * enumeration is of type AclEntry.
074: * @return an enumeration of the entries in this ACL.
075: */
076: public Enumeration entries();
077:
078: /**
079: * Returns <code>true</code>, if this Acl is empty.
080: * @return the result
081: * @since 2.4.68
082: */
083: public boolean isEmpty();
084:
085: /**
086: * Returns all Principal objects assigned a given Permission in the access
087: * control list. The Princiapls returned are those that have been granted
088: * either the supplied permission, or a permission implied by the supplied
089: * permission. Principals are not "expanded" if they are a role or group.
090: * @param permission the permission to search for
091: * @return an array of Principals posessing the permission
092: */
093: public Principal[] findPrincipals(Permission permission);
094:
095: /**
096: * Returns an AclEntry for a supplied Principal, or <code>null</code> if
097: * the Principal does not have a matching AclEntry.
098: * @param principal the principal to search for
099: * @return the AclEntry associated with the principal, or <code>null</code>
100: */
101: public AclEntry getEntry(Principal principal);
102:
103: /**
104: * Removes an ACL entry from this ACL.
105: * @param entry the ACL entry to be removed from this ACL
106: * @return true on success, false if the entry is not part of this ACL
107: */
108: public boolean removeEntry(AclEntry entry);
109:
110: /**
111: * Returns a string representation of the contents of this Acl.
112: * @return the string representation
113: */
114: public String toString();
115:
116: }
|