/* * Copyright (c) 2007, 2011, 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). * *

The ACL entry represented by this class is based on the ACL model * specified in RFC 3530: * Network File System (NFS) version 4 Protocol. Each entry has four * components as follows: * *

    *

  1. The {@link #type() type} component determines if the entry * grants or denies access.

    2. * *

  2. 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 *

    3. * *

  3. The {@link #permissions permissions} component is a set of * {@link AclEntryPermission permissions} *

    4. * *

  4. The {@link #flags flags} component is a set of {@link AclEntryFlag * flags} to indicate how entries are inherited and propagated

    5. *
* *

ACL entries are created using an associated {@link Builder} object by * invoking its {@link Builder#build build} method. * *

ACL entries are immutable and are safe for use by multiple concurrent * threads. * * @since 1.7 */ public final class AclEntry { private final AclEntryType type; private final UserPrincipal who; private final Set perms; private final Set flags; // cached hash code private volatile int hash; // private constructor private AclEntry(AclEntryType type, UserPrincipal who, Set perms, Set flags) { this.type = type; this.who = who; this.perms = perms; this.flags = flags; } /** * A builder of {@link AclEntry} objects. * *

A {@code Builder} object is obtained by invoking one of the {@link * AclEntry#newBuilder newBuilder} methods defined by the {@code AclEntry} * class. * *

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 AclEntryType type; private UserPrincipal who; private Set perms; private Set flags; private Builder(AclEntryType type, UserPrincipal who, Set perms, Set 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 */ 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. * * @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. * * @return this builder */ public Builder setPrincipal(UserPrincipal who) { if (who == null) throw new NullPointerException(); this.who = who; 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); } } /** * Sets the permissions component of this builder. On return, the * permissions component of this builder is a copy of the given set. * * @return this builder * * @throws ClassCastException * if the set contains elements that are not of type {@code * AclEntryPermission} */ public Builder setPermissions(Set perms) { // 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. * * @return this builder */ public Builder setPermissions(AclEntryPermission... perms) { Set 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. * * @return this builder * * @throws ClassCastException * if the set contains elements that are not of type {@code * AclEntryFlag} */ public Builder setFlags(Set flags) { // 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. * * @return this builder */ public Builder setFlags(AclEntryFlag... flags) { Set 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; } } /** * 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 */ public static Builder newBuilder() { Set perms = Collections.emptySet(); Set 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 */ public static Builder newBuilder(AclEntry entry) { return new Builder(entry.type, entry.who, entry.perms, entry.flags); } /** * Returns the ACL entry type. */ public AclEntryType type() { return type; } /** * Returns the principal component. */ public UserPrincipal principal() { return who; } /** * Returns a copy of the permissions component. * *

The returned set is a modifiable copy of the permissions. */ public Set permissions() { return new HashSet(perms); } /** * Returns a copy of the flags component. * *

The returned set is a modifiable copy of the flags. */ public Set flags() { return new HashSet(flags); } /** * Compares the specified object with this ACL entry for equality. * *

If the given object is not an {@code AclEntry} then this method * immediately returns {@code false}. * *

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. * *

This method satisfies the general contract of the {@link * java.lang.Object#equals(Object) Object.equals} method.

* * @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; if (!this.flags.equals(other.flags)) return false; return true; } private static int hash(int h, Object o) { return h * 127 + o.hashCode(); } /** * Returns the hash-code value for this ACL entry. * *

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(); } }