418 lines
13 KiB
Java
418 lines
13 KiB
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 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
|
|
*/
|
|
|
|
public final class AclEntry {
|
|
|
|
private final AclEntryType type;
|
|
private final UserPrincipal who;
|
|
private final Set<AclEntryPermission> perms;
|
|
private final Set<AclEntryFlag> flags;
|
|
|
|
// 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;
|
|
}
|
|
|
|
/**
|
|
* 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 AclEntryType type;
|
|
private UserPrincipal who;
|
|
private Set<AclEntryPermission> perms;
|
|
private Set<AclEntryFlag> flags;
|
|
|
|
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
|
|
*/
|
|
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;
|
|
}
|
|
|
|
// 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.
|
|
*
|
|
* @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;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 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<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
|
|
*/
|
|
public static Builder newBuilder(AclEntry entry) {
|
|
return new Builder(entry.type, entry.who, entry.perms, entry.flags);
|
|
}
|
|
|
|
/**
|
|
* Returns the ACL entry type.
|
|
*
|
|
* @return the ACL entry type
|
|
*/
|
|
public AclEntryType type() {
|
|
return type;
|
|
}
|
|
|
|
/**
|
|
* Returns the principal component.
|
|
*
|
|
* @return the principal component
|
|
*/
|
|
public UserPrincipal principal() {
|
|
return who;
|
|
}
|
|
|
|
/**
|
|
* 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 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);
|
|
}
|
|
|
|
/**
|
|
* 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;
|
|
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.
|
|
*
|
|
* <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();
|
|
}
|
|
}
|