AclEntry.java

/*
 * Copyright (c) 2007, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.nio.file.attribute;

import java.util.*;

/**
 * An entry in an access control list (ACL).
 *
 * <p> The ACL entry represented by this class is based on the ACL model
 * specified in <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC&nbsp;3530:
 * Network File System (NFS) version 4 Protocol</i></a>. Each entry has four
 * components as follows:
 *
 * <ol>
 *    <li><p> The {@link #type() type} component determines if the entry
 *    grants or denies access. </p></li>
 *
 *    <li><p> The {@link #principal() principal} component, sometimes called the
 *    "who" component, is a {@link UserPrincipal} corresponding to the identity
 *    that the entry grants or denies access
 *    </p></li>
 *
 *    <li><p> The {@link #permissions permissions} component is a set of
 *    {@link AclEntryPermission permissions}
 *    </p></li>
 *
 *    <li><p> The {@link #flags() flags} component is a set of {@link AclEntryFlag
 *    flags} to indicate how entries are inherited and propagated </p></li>
 * </ol>
 *
 * <p> ACL entries are created using an associated {@link Builder} object by
 * invoking its {@link Builder#build build} method.
 *
 * <p> ACL entries are immutable and are safe for use by multiple concurrent
 * threads.
 *
 * @since 1.7
 */
// 访问控制项(ACE)，用来描述与特定SID关联的访问权限，一组ACE构成了访问控制列表(ACL)
public final class AclEntry {
    
    private final Set<AclEntryFlag> flags;          // ACE继承规则
    private final AclEntryType type;                // 访问控制权限
    private final Set<AclEntryPermission> perms;    // 实体访问权限
    private final UserPrincipal who;                // 实体"所有者"，内含SID
    
    // cached hash code
    private volatile int hash;
    
    
    // private constructor
    private AclEntry(AclEntryType type, UserPrincipal who, Set<AclEntryPermission> perms, Set<AclEntryFlag> flags) {
        this.type = type;
        this.who = who;
        this.perms = perms;
        this.flags = flags;
    }
    
    /**
     * Constructs a new builder. The initial value of the type and who
     * components is {@code null}. The initial value of the permissions and
     * flags components is the empty set.
     *
     * @return a new builder
     */
    // 构造一个空的ACE构建器
    public static Builder newBuilder() {
        Set<AclEntryPermission> perms = Collections.emptySet();
        Set<AclEntryFlag> flags = Collections.emptySet();
        return new Builder(null, null, perms, flags);
    }
    
    /**
     * Constructs a new builder with the components of an existing ACL entry.
     *
     * @param entry an ACL entry
     *
     * @return a new builder
     */
    // 使用指定的AclEntry构造一个ACE构建器
    public static Builder newBuilder(AclEntry entry) {
        return new Builder(entry.type, entry.who, entry.perms, entry.flags);
    }
    
    /**
     * Returns a copy of the flags component.
     *
     * <p> The returned set is a modifiable copy of the flags.
     *
     * @return the flags component
     */
    public Set<AclEntryFlag> flags() {
        return new HashSet<>(flags);
    }
    
    /**
     * Returns the ACL entry type.
     *
     * @return the ACL entry type
     */
    public AclEntryType type() {
        return type;
    }
    
    /**
     * Returns a copy of the permissions component.
     *
     * <p> The returned set is a modifiable copy of the permissions.
     *
     * @return the permissions component
     */
    public Set<AclEntryPermission> permissions() {
        return new HashSet<>(perms);
    }
    
    /**
     * Returns the principal component.
     *
     * @return the principal component
     */
    public UserPrincipal principal() {
        return who;
    }
    
    
    /**
     * Compares the specified object with this ACL entry for equality.
     *
     * <p> If the given object is not an {@code AclEntry} then this method
     * immediately returns {@code false}.
     *
     * <p> For two ACL entries to be considered equals requires that they are
     * both the same type, their who components are equal, their permissions
     * components are equal, and their flags components are equal.
     *
     * <p> This method satisfies the general contract of the {@link
     * java.lang.Object#equals(Object) Object.equals} method. </p>
     *
     * @param ob the object to which this object is to be compared
     *
     * @return {@code true} if, and only if, the given object is an AclEntry that
     * is identical to this AclEntry
     */
    @Override
    public boolean equals(Object ob) {
        if(ob == this) {
            return true;
        }
        
        if(ob == null || !(ob instanceof AclEntry)) {
            return false;
        }
        
        AclEntry other = (AclEntry) ob;
        if(this.type != other.type) {
            return false;
        }
        if(!this.who.equals(other.who)) {
            return false;
        }
        if(!this.perms.equals(other.perms)) {
            return false;
        }
        return this.flags.equals(other.flags);
    }
    
    /**
     * Returns the hash-code value for this ACL entry.
     *
     * <p> This method satisfies the general contract of the {@link
     * Object#hashCode} method.
     */
    @Override
    public int hashCode() {
        // return cached hash if available
        if(hash != 0) {
            return hash;
        }
        int h = type.hashCode();
        h = hash(h, who);
        h = hash(h, perms);
        h = hash(h, flags);
        hash = h;
        return hash;
    }
    
    /**
     * Returns the string representation of this ACL entry.
     *
     * @return the string representation of this entry
     */
    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();
        
        // who
        sb.append(who.getName());
        sb.append(':');
        
        // permissions
        for(AclEntryPermission perm : perms) {
            sb.append(perm.name());
            sb.append('/');
        }
        sb.setLength(sb.length() - 1); // drop final slash
        sb.append(':');
        
        // flags
        if(!flags.isEmpty()) {
            for(AclEntryFlag flag : flags) {
                sb.append(flag.name());
                sb.append('/');
            }
            sb.setLength(sb.length() - 1);  // drop final slash
            sb.append(':');
        }
        
        // type
        sb.append(type.name());
        return sb.toString();
    }
    
    
    private static int hash(int h, Object o) {
        return h * 127 + o.hashCode();
    }
    
    
    /**
     * A builder of {@link AclEntry} objects.
     *
     * <p> A {@code Builder} object is obtained by invoking one of the {@link
     * AclEntry#newBuilder newBuilder} methods defined by the {@code AclEntry}
     * class.
     *
     * <p> Builder objects are mutable and are not safe for use by multiple
     * concurrent threads without appropriate synchronization.
     *
     * @since 1.7
     */
    public static final class Builder {
        private Set<AclEntryFlag> flags;
        private AclEntryType type;
        private Set<AclEntryPermission> perms;
        private UserPrincipal who;
        
        private Builder(AclEntryType type, UserPrincipal who, Set<AclEntryPermission> perms, Set<AclEntryFlag> flags) {
            assert perms != null && flags != null;
            this.type = type;
            this.who = who;
            this.perms = perms;
            this.flags = flags;
        }
        
        /**
         * Constructs an {@link AclEntry} from the components of this builder.
         * The type and who components are required to have been set in order
         * to construct an {@code AclEntry}.
         *
         * @return a new ACL entry
         *
         * @throws IllegalStateException if the type or who component have not been set
         */
        // 返回构造的ACE实体
        public AclEntry build() {
            if(type == null) {
                throw new IllegalStateException("Missing type component");
            }
            if(who == null) {
                throw new IllegalStateException("Missing who component");
            }
            return new AclEntry(type, who, perms, flags);
        }
        
        /**
         * Sets the type component of this builder.
         *
         * @param type the component type
         *
         * @return this builder
         */
        public Builder setType(AclEntryType type) {
            if(type == null) {
                throw new NullPointerException();
            }
            this.type = type;
            return this;
        }
        
        /**
         * Sets the principal component of this builder.
         *
         * @param who the principal component
         *
         * @return this builder
         */
        public Builder setPrincipal(UserPrincipal who) {
            if(who == null) {
                throw new NullPointerException();
            }
            this.who = who;
            return this;
        }
        
        /**
         * Sets the permissions component of this builder. On return, the
         * permissions component of this builder is a copy of the given set.
         *
         * @param perms the permissions component
         *
         * @return this builder
         *
         * @throws ClassCastException if the set contains elements that are not of type {@code
         *                            AclEntryPermission}
         */
        public Builder setPermissions(Set<AclEntryPermission> perms) {
            if(perms.isEmpty()) {
                // EnumSet.copyOf does not allow empty set
                perms = Collections.emptySet();
            } else {
                // copy and check for erroneous elements
                perms = EnumSet.copyOf(perms);
                checkSet(perms, AclEntryPermission.class);
            }
    
            this.perms = perms;
            return this;
        }
        
        /**
         * Sets the permissions component of this builder. On return, the
         * permissions component of this builder is a copy of the permissions in
         * the given array.
         *
         * @param perms the permissions component
         *
         * @return this builder
         */
        public Builder setPermissions(AclEntryPermission... perms) {
            Set<AclEntryPermission> set = EnumSet.noneOf(AclEntryPermission.class);
            // copy and check for null elements
            for(AclEntryPermission p : perms) {
                if(p == null) {
                    throw new NullPointerException();
                }
                set.add(p);
            }
            this.perms = set;
            return this;
        }
        
        /**
         * Sets the flags component of this builder. On return, the flags
         * component of this builder is a copy of the given set.
         *
         * @param flags the flags component
         *
         * @return this builder
         *
         * @throws ClassCastException if the set contains elements that are not of type {@code
         *                            AclEntryFlag}
         */
        public Builder setFlags(Set<AclEntryFlag> flags) {
            if(flags.isEmpty()) {
                // EnumSet.copyOf does not allow empty set
                flags = Collections.emptySet();
            } else {
                // copy and check for erroneous elements
                flags = EnumSet.copyOf(flags);
                checkSet(flags, AclEntryFlag.class);
            }
    
            this.flags = flags;
            return this;
        }
        
        /**
         * Sets the flags component of this builder. On return, the flags
         * component of this builder is a copy of the flags in the given
         * array.
         *
         * @param flags the flags component
         *
         * @return this builder
         */
        public Builder setFlags(AclEntryFlag... flags) {
            Set<AclEntryFlag> set = EnumSet.noneOf(AclEntryFlag.class);
            // copy and check for null elements
            for(AclEntryFlag f : flags) {
                if(f == null) {
                    throw new NullPointerException();
                }
                set.add(f);
            }
            this.flags = set;
            return this;
        }
        
        // check set only contains elements of the given type
        private static void checkSet(Set<?> set, Class<?> type) {
            for(Object e : set) {
                if(e == null) {
                    throw new NullPointerException();
                }
                type.cast(e);
            }
        }
    }
    
}