View Javadoc

    1   /* Copyright 2004 Acegi Technology Pty Limited
    2    *
    3    * Licensed under the Apache License, Version 2.0 (the "License");
    4    * you may not use this file except in compliance with the License.
    5    * You may obtain a copy of the License at
    6    *
    7    *     http://www.apache.org/licenses/LICENSE-2.0
    8    *
    9    * Unless required by applicable law or agreed to in writing, software
    10   * distributed under the License is distributed on an "AS IS" BASIS,
    11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12   * See the License for the specific language governing permissions and
    13   * limitations under the License.
    14   */
    15
    16  package org.acegisecurity.acl.basic;
    17
    18  import org.acegisecurity.acl.AclEntry;
    19
    20
    21  /***
    22   * Represents an entry in an access control list.
    23   *
    24   * @author Ben Alex
    25   * @version $Id: BasicAclEntry.java,v 1.3 2005/11/17 00:55:47 benalex Exp $
    26   */
    27  public interface BasicAclEntry extends AclEntry {
    28      //~ Methods ================================================================
    29
    30      /***
    31       * This setter should <B>only</B> be used by DAO implementations.
    32       *
    33       * @param aclObjectIdentity an object which can be used to uniquely
    34       *        identify the domain object instance subject of this ACL entry
    35       */
    36      public void setAclObjectIdentity(AclObjectIdentity aclObjectIdentity);
    37
    38      /***
    39       * Indicates the domain object instance that is subject of this
    40       * <code>BasicAclEntry</code>. This information may be of interest to
    41       * relying classes (voters and business methods) that wish to know the
    42       * actual origination of the ACL entry (so as to distinguish individual
    43       * ACL entries from others contributed by the inheritance hierarchy).
    44       *
    45       * @return the ACL object identity that is subject of this ACL entry (never
    46       *         <code>null</code>)
    47       */
    48      public AclObjectIdentity getAclObjectIdentity();
    49
    50      /***
    51       * This setter should <B>only</B> be used by DAO implementations.
    52       *
    53       * @param aclObjectParentIdentity an object which represents the parent of
    54       *        the domain object instance subject of this ACL entry, or
    55       *        <code>null</code> if either the domain object instance has no
    56       *        parent or its parent should be not used to compute an
    57       *        inheritance hierarchy
    58       */
    59      public void setAclObjectParentIdentity(
    60          AclObjectIdentity aclObjectParentIdentity);
    61
    62      /***
    63       * Indicates any ACL parent of the domain object instance. This is used by
    64       * <code>BasicAclProvider</code> to walk the inheritance hierarchy. An
    65       * domain object instance need <b>not</b> have a parent.
    66       *
    67       * @return the ACL object identity that is the parent of this ACL entry
    68       *         (may be <code>null</code> if no parent should be consulted)
    69       */
    70      public AclObjectIdentity getAclObjectParentIdentity();
    71
    72      /***
    73       * This setter should <B>only</B> be used by DAO implementations.
    74       *
    75       * @param mask the integer representing the permissions bit mask
    76       */
    77      public void setMask(int mask);
    78
    79      /***
    80       * Access control lists in this package are based on bit masking. The
    81       * integer value of the bit mask can be obtained from this method.
    82       *
    83       * @return the bit mask applicable to this ACL entry (zero indicates a bit
    84       *         mask where no permissions have been granted)
    85       */
    86      public int getMask();
    87
    88      /***
    89       * This setter should <B>only</B> be used by DAO implementations.
    90       *
    91       * @param recipient a representation of the recipient of this ACL entry
    92       *        that makes sense to an <code>EffectiveAclsResolver</code>
    93       *        implementation
    94       */
    95      public void setRecipient(Object recipient);
    96
    97      /***
    98       * A domain object instance will usually have multiple
    99       * <code>BasicAclEntry</code>s. Each separate <code>BasicAclEntry</code>
    100      * applies to a particular "recipient". Typical examples of recipients
    101      * include (but do not necessarily have to include) usernames, role names,
    102      * complex granted authorities etc.
    103      *
    104      * <P>
    105      * <B>It is essential that only one <code>BasicAclEntry</code> exists for a
    106      * given recipient</B>. Otherwise conflicts as to the mask that should
    107      * apply to a given recipient will occur.
    108      * </p>
    109      *
    110      * <P>
    111      * This method indicates which recipient this <code>BasicAclEntry</code>
    112      * applies to. The returned object type will vary depending on the type of
    113      * recipient. For instance, it might be a <code>String</code> containing a
    114      * username, or a <code>GrantedAuthorityImpl</code> containing a complex
    115      * granted authority that is being granted the permissions contained in
    116      * this access control entry. The {@link EffectiveAclsResolver} and {@link
    117      * BasicAclProvider#getAcls(Object, Authentication)} can process the
    118      * different recipient types and return only those that apply to a
    119      * specified <code>Authentication</code> object.
    120      * </p>
    121      *
    122      * @return the recipient of this access control list entry (never
    123      *         <code>null</code>)
    124      */
    125     public Object getRecipient();
    126
    127     /***
    128      * Determine if the mask of this entry includes this permission or not
    129      *
    130      * @param permissionToCheck
    131      * @return if the entry's mask includes this permission
    132      */
    133     public boolean isPermitted(int permissionToCheck);
    134 }