    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.api.core;
    020
    021import java.security.Permission;
    022import java.security.Principal;
    023import java.util.Enumeration;
    024
    025
    026/**
    027 * <p>Represents one entry in an Access Control List (ACL).</p>
    028 * <p>
    029 * An ACL can be thought of as a data structure with multiple ACL entry objects. Each ACL entry object contains a set of positive page
    030 * permissions associated with a particular principal. (A principal represents an entity such as an individual user, group, or role).
    031 * Each principal can have at most one ACL entry; that is, multiple ACL entries are not allowed for any principal.
    032 * </p>
    033 * <p>This interface is functionally equivalent to the java.security.acl.AclEntry interface, minus negative permissions. </p>
    034 *
    035 * @see Acl
    036 * @since 2.3
    037 */
    038public interface AclEntry {
    039
    040    /**
    041     * Adds the specified permission to this ACL entry. The permission <em>must</em> be of type
    042     * {@link org.apache.wiki.auth.permissions.PagePermission}. Note: An entry can have multiple permissions.
    043     *
    044     * @param permission the permission to be associated with the principal in this entry
    045     * @return <code>true</code> if the permission was added, <code>false</code> if the permission was
    046     *         already part of this entry's permission set, and <code>false</code> if the permission is not of type PagePermission
    047     */
    048    boolean addPermission( Permission permission );
    049
    050    /**
    051     * Checks if the specified permission is part of the permission set in this entry.
    052     *
    053     * @param permission the permission to be checked for.
    054     * @return true if the permission is part of the permission set in this entry, false otherwise.
    055     */
    056    boolean checkPermission( Permission permission );
    057
    058    /**
    059     * Returns the principal for which permissions are granted by this ACL entry. Returns null if there is no principal set for this
    060     * entry yet.
    061     *
    062     * @return the principal associated with this entry.
    063     */
    064    Principal getPrincipal();
    065
    066    /**
    067     * Returns an enumeration of the permissions in this ACL entry.
    068     *
    069     * @return an enumeration of the permissions
    070     */
    071    Enumeration< Permission > permissions();
    072
    073    /**
    074     * Removes the specified permission from this ACL entry.
    075     *
    076     * @param permission the permission to be removed from this entry.
    077     * @return true if the permission is removed, false if the permission was not part of this entry's permission set.
    078     */
    079    boolean removePermission( Permission permission );
    080
    081    /**
    082     * Specifies the principal for which permissions are granted or denied by this ACL entry. If a principal was already set for
    083     * this ACL entry, false is returned, otherwise true is returned.
    084     *
    085     * @param user the principal to be set for this entry
    086     * @return true if the principal is set, false if there was already a principal set for this entry
    087     */
    088    boolean setPrincipal( Principal user );
    089
    090}