1 /*

     2  * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.security.acl;

    27 

    28 import java.util.Enumeration;

    29 import java.security.Principal;

    30 

    31 /**

    32  * This is the interface used for representing one entry in an Access

    33  * Control List (ACL).<p>

    34  *

    35  * An ACL can be thought of as a data structure with multiple ACL entry

    36  * objects. Each ACL entry object contains a set of permissions associated

    37  * with a particular principal. (A principal represents an entity such as

    38  * an individual user or a group). Additionally, each ACL entry is specified

    39  * as being either positive or negative. If positive, the permissions are

    40  * to be granted to the associated principal. If negative, the permissions

    41  * are to be denied. Each principal can have at most one positive ACL entry

    42  * and one negative entry; that is, multiple positive or negative ACL

    43  * entries are not allowed for any principal.

    44  *

    45  * Note: ACL entries are by default positive. An entry becomes a

    46  * negative entry only if the

    47  * {@link #setNegativePermissions() setNegativePermissions}

    48  * method is called on it.

    49  *

    50  * @see java.security.acl.Acl

    51  *

    52  * @author      Satish Dharmaraj

    53  */

    54 public interface AclEntry extends Cloneable {

    55 

    56     /**

    57      * Specifies the principal for which permissions are granted or denied

    58      * by this ACL entry. If a principal was already set for this ACL entry,

    59      * false is returned, otherwise true is returned.

    60      *

    61      * @param user the principal to be set for this entry.

    62      *

    63      * @return true if the principal is set, false if there was

    64      * already a principal set for this entry.

    65      *

    66      * @see #getPrincipal

    67      */

    68     public boolean setPrincipal(Principal user);

    69 

    70     /**

    71      * Returns the principal for which permissions are granted or denied by

    72      * this ACL entry. Returns null if there is no principal set for this

    73      * entry yet.

    74      *

    75      * @return the principal associated with this entry.

    76      *

    77      * @see #setPrincipal

    78      */

    79     public Principal getPrincipal();

    80 

    81     /**

    82      * Sets this ACL entry to be a negative one. That is, the associated

    83      * principal (e.g., a user or a group) will be denied the permission set

    84      * specified in the entry.

    85      *

    86      * Note: ACL entries are by default positive. An entry becomes a

    87      * negative entry only if this {@code setNegativePermissions}

    88      * method is called on it.

    89      */

    90     public void setNegativePermissions();

    91 

    92     /**

    93      * Returns true if this is a negative ACL entry (one denying the

    94      * associated principal the set of permissions in the entry), false

    95      * otherwise.

    96      *

    97      * @return true if this is a negative ACL entry, false if it's not.

    98      */

    99     public boolean isNegative();

   100 

   101     /**

   102      * Adds the specified permission to this ACL entry. Note: An entry can

   103      * have multiple permissions.

   104      *

   105      * @param permission the permission to be associated with

   106      * the principal in this entry.

   107      *

   108      * @return true if the permission was added, false if the

   109      * permission was already part of this entry's permission set.

   110      */

   111     public boolean addPermission(Permission permission);

   112 

   113     /**

   114      * Removes the specified permission from this ACL entry.

   115      *

   116      * @param permission the permission to be removed from this entry.

   117      *

   118      * @return true if the permission is removed, false if the

   119      * permission was not part of this entry's permission set.

   120      */

   121     public boolean removePermission(Permission permission);

   122 

   123     /**

   124      * Checks if the specified permission is part of the

   125      * permission set in this entry.

   126      *

   127      * @param permission the permission to be checked for.

   128      *

   129      * @return true if the permission is part of the

   130      * permission set in this entry, false otherwise.

   131      */

   132     public boolean checkPermission(Permission permission);

   133 

   134     /**

   135      * Returns an enumeration of the permissions in this ACL entry.

   136      *

   137      * @return an enumeration of the permissions in this ACL entry.

   138      */

   139     public Enumeration<Permission> permissions();

   140 

   141     /**

   142      * Returns a string representation of the contents of this ACL entry.

   143      *

   144      * @return a string representation of the contents.

   145      */

   146     public String toString();

   147 

   148     /**

   149      * Clones this ACL entry.

   150      *

   151      * @return a clone of this ACL entry.

   152      */

   153     public Object clone();

   154 }