archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 23:04:50 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8187443: Forest Consolidation: Move files to unified layout

Browse source 
Reviewed-by: darcy, ihse
This commit is contained in:
Erik Joelsson 2017-09-12 19:03:39 +02:00
parent 270fe13182
commit 3789983e89
56923 changed files with 3 additions and 15727 deletions
Download patch file Download diff file Expand all files Collapse all files

417
src/java.base/share/classes/java/nio/file/attribute/AclEntry.java Normal file
View file

@ -0,0 +1,417 @@
/*
* 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
*/
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();
}
}

65
src/java.base/share/classes/java/nio/file/attribute/AclEntryFlag.java Normal file
View file

@ -0,0 +1,65 @@
/*
* Copyright (c) 2007, 2009, 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;
/**
* Defines the flags for used by the flags component of an ACL {@link AclEntry
* entry}.
*
* <p> In this release, this class does not define flags related to {@link
* AclEntryType#AUDIT} and {@link AclEntryType#ALARM} entry types.
*
* @since 1.7
*/
public enum AclEntryFlag {
/**
* Can be placed on a directory and indicates that the ACL entry should be
* added to each new non-directory file created.
*/
FILE_INHERIT,
/**
* Can be placed on a directory and indicates that the ACL entry should be
* added to each new directory created.
*/
DIRECTORY_INHERIT,
/**
* Can be placed on a directory to indicate that the ACL entry should not
* be placed on the newly created directory which is inheritable by
* subdirectories of the created directory.
*/
NO_PROPAGATE_INHERIT,
/**
* Can be placed on a directory but does not apply to the directory,
* only to newly created files/directories as specified by the
* {@link #FILE_INHERIT} and {@link #DIRECTORY_INHERIT} flags.
*/
INHERIT_ONLY;
}

130
src/java.base/share/classes/java/nio/file/attribute/AclEntryPermission.java Normal file
View file

@ -0,0 +1,130 @@
/*
* Copyright (c) 2007, 2009, 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;
/**
* Defines the permissions for use with the permissions component of an ACL
* {@link AclEntry entry}.
*
* @since 1.7
*/
public enum AclEntryPermission {
/**
* Permission to read the data of the file.
*/
READ_DATA,
/**
* Permission to modify the file's data.
*/
WRITE_DATA,
/**
* Permission to append data to a file.
*/
APPEND_DATA,
/**
* Permission to read the named attributes of a file.
*
* <p> <a href="http://www.ietf.org/rfc/rfc3530.txt">RFC&nbsp;3530: Network
* File System (NFS) version 4 Protocol</a> defines <em>named attributes</em>
* as opaque files associated with a file in the file system.
*/
READ_NAMED_ATTRS,
/**
* Permission to write the named attributes of a file.
*
* <p> <a href="http://www.ietf.org/rfc/rfc3530.txt">RFC&nbsp;3530: Network
* File System (NFS) version 4 Protocol</a> defines <em>named attributes</em>
* as opaque files associated with a file in the file system.
*/
WRITE_NAMED_ATTRS,
/**
* Permission to execute a file.
*/
EXECUTE,
/**
* Permission to delete a file or directory within a directory.
*/
DELETE_CHILD,
/**
* The ability to read (non-acl) file attributes.
*/
READ_ATTRIBUTES,
/**
* The ability to write (non-acl) file attributes.
*/
WRITE_ATTRIBUTES,
/**
* Permission to delete the file.
*/
DELETE,
/**
* Permission to read the ACL attribute.
*/
READ_ACL,
/**
* Permission to write the ACL attribute.
*/
WRITE_ACL,
/**
* Permission to change the owner.
*/
WRITE_OWNER,
/**
* Permission to access file locally at the server with synchronous reads
* and writes.
*/
SYNCHRONIZE;
/**
* Permission to list the entries of a directory (equal to {@link #READ_DATA})
*/
public static final AclEntryPermission LIST_DIRECTORY = READ_DATA;
/**
* Permission to add a new file to a directory (equal to {@link #WRITE_DATA})
*/
public static final AclEntryPermission ADD_FILE = WRITE_DATA;
/**
* Permission to create a subdirectory to a directory (equal to {@link #APPEND_DATA})
*/
public static final AclEntryPermission ADD_SUBDIRECTORY = APPEND_DATA;
}

56
src/java.base/share/classes/java/nio/file/attribute/AclEntryType.java Normal file
View file

@ -0,0 +1,56 @@
/*
* Copyright (c) 2007, 2009, 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;
/**
* A typesafe enumeration of the access control entry types.
*
* @since 1.7
*/
public enum AclEntryType {
/**
* Explicitly grants access to a file or directory.
*/
ALLOW,
/**
* Explicitly denies access to a file or directory.
*/
DENY,
/**
* Log, in a system dependent way, the access specified in the
* permissions component of the ACL entry.
*/
AUDIT,
/**
* Generate an alarm, in a system dependent way, the access specified in the
* permissions component of the ACL entry.
*/
ALARM
}

214
src/java.base/share/classes/java/nio/file/attribute/AclFileAttributeView.java Normal file
View file

@ -0,0 +1,214 @@
/*
* 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.nio.file.*;
import java.util.List;
import java.io.IOException;
/**
* A file attribute view that supports reading or updating a file's Access
* Control Lists (ACL) or file owner attributes.
*
* <p> ACLs are used to specify access rights to file system objects. An ACL is
* an ordered list of {@link AclEntry access-control-entries}, each specifying a
* {@link UserPrincipal} and the level of access for that user principal. This
* file attribute view defines the {@link #getAcl() getAcl}, and {@link
* #setAcl(List) setAcl} methods to read and write ACLs 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>. This file attribute view
* is intended for file system implementations that support the NFSv4 ACL model
* or have a <em>well-defined</em> mapping between the NFSv4 ACL model and the ACL
* model used by the file system. The details of such mapping are implementation
* dependent and are therefore unspecified.
*
* <p> This class also extends {@code FileOwnerAttributeView} so as to define
* methods to get and set the file owner.
*
* <p> When a file system provides access to a set of {@link FileStore
* file-systems} that are not homogeneous then only some of the file systems may
* support ACLs. The {@link FileStore#supportsFileAttributeView
* supportsFileAttributeView} method can be used to test if a file system
* supports ACLs.
*
* <h2>Interoperability</h2>
*
* RFC&nbsp;3530 allows for special user identities to be used on platforms that
* support the POSIX defined access permissions. The special user identities
* are "{@code OWNER@}", "{@code GROUP@}", and "{@code EVERYONE@}". When both
* the {@code AclFileAttributeView} and the {@link PosixFileAttributeView}
* are supported then these special user identities may be included in ACL {@link
* AclEntry entries} that are read or written. The file system's {@link
* UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal}
* to represent these special identities by invoking the {@link
* UserPrincipalLookupService#lookupPrincipalByName lookupPrincipalByName}
* method.
*
* <p> <b>Usage Example:</b>
* Suppose we wish to add an entry to an existing ACL to grant "joe" access:
* <pre>
* // lookup "joe"
* UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
* .lookupPrincipalByName("joe");
*
* // get view
* AclFileAttributeView view = Files.getFileAttributeView(file, AclFileAttributeView.class);
*
* // create ACE to give "joe" read access
* AclEntry entry = AclEntry.newBuilder()
* .setType(AclEntryType.ALLOW)
* .setPrincipal(joe)
* .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES)
* .build();
*
* // read ACL, insert ACE, re-write ACL
* List&lt;AclEntry&gt; acl = view.getAcl();
* acl.add(0, entry); // insert before any DENY entries
* view.setAcl(acl);
* </pre>
*
* <h2> Dynamic Access </h2>
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view are as follows:
* <blockquote>
* <table class="striped">
* <caption style="display:none">Supported attributes</caption>
* <thead>
* <tr>
* <th scope="col"> Name </th>
* <th scope="col"> Type </th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"> "acl" </th>
* <td> {@link List}&lt;{@link AclEntry}&gt; </td>
* </tr>
* <tr>
* <th scope="row"> "owner" </th>
* <td> {@link UserPrincipal} </td>
* </tr>
* </tbody>
* </table>
* </blockquote>
*
* <p> The {@link Files#getAttribute getAttribute} method may be used to read
* the ACL or owner attributes as if by invoking the {@link #getAcl getAcl} or
* {@link #getOwner getOwner} methods.
*
* <p> The {@link Files#setAttribute setAttribute} method may be used to
* update the ACL or owner attributes as if by invoking the {@link #setAcl setAcl}
* or {@link #setOwner setOwner} methods.
*
* <h2> Setting the ACL when creating a file </h2>
*
* <p> Implementations supporting this attribute view may also support setting
* the initial ACL when creating a file or directory. The initial ACL
* may be provided to methods such as {@link Files#createFile createFile} or {@link
* Files#createDirectory createDirectory} as an {@link FileAttribute} with {@link
* FileAttribute#name name} {@code "acl:acl"} and a {@link FileAttribute#value
* value} that is the list of {@code AclEntry} objects.
*
* <p> Where an implementation supports an ACL model that differs from the NFSv4
* defined ACL model then setting the initial ACL when creating the file must
* translate the ACL to the model supported by the file system. Methods that
* create a file should reject (by throwing {@link IOException IOException})
* any attempt to create a file that would be less secure as a result of the
* translation.
*
* @since 1.7
*/
public interface AclFileAttributeView
extends FileOwnerAttributeView
{
/**
* Returns the name of the attribute view. Attribute views of this type
* have the name {@code "acl"}.
*/
@Override
String name();
/**
* Reads the access control list.
*
* <p> When the file system uses an ACL model that differs from the NFSv4
* defined ACL model, then this method returns an ACL that is the translation
* of the ACL to the NFSv4 ACL model.
*
* <p> The returned list is modifiable so as to facilitate changes to the
* existing ACL. The {@link #setAcl setAcl} method is used to update
* the file's ACL attribute.
*
* @return an ordered list of {@link AclEntry entries} representing the
* ACL
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link RuntimePermission}{@code ("accessUserInformation")}
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*/
List<AclEntry> getAcl() throws IOException;
/**
* Updates (replace) the access control list.
*
* <p> Where the file system supports Access Control Lists, and it uses an
* ACL model that differs from the NFSv4 defined ACL model, then this method
* must translate the ACL to the model supported by the file system. This
* method should reject (by throwing {@link IOException IOException}) any
* attempt to write an ACL that would appear to make the file more secure
* than would be the case if the ACL were updated. Where an implementation
* does not support a mapping of {@link AclEntryType#AUDIT} or {@link
* AclEntryType#ALARM} entries, then this method ignores these entries when
* writing the ACL.
*
* <p> If an ACL entry contains a {@link AclEntry#principal user-principal}
* that is not associated with the same provider as this attribute view then
* {@link ProviderMismatchException} is thrown. Additional validation, if
* any, is implementation dependent.
*
* <p> If the file system supports other security related file attributes
* (such as a file {@link PosixFileAttributes#permissions
* access-permissions} for example), the updating the access control list
* may also cause these security related attributes to be updated.
*
* @param acl
* the new access control list
*
* @throws IOException
* if an I/O error occurs or the ACL is invalid
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, it denies {@link RuntimePermission}{@code ("accessUserInformation")}
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
void setAcl(List<AclEntry> acl) throws IOException;
}

45
src/java.base/share/classes/java/nio/file/attribute/AttributeView.java Normal file
View file

@ -0,0 +1,45 @@
/*
* Copyright (c) 2007, 2013, 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;
/**
* An object that provides a read-only or updatable <em>view</em> of non-opaque
* values associated with an object in a filesystem. This interface is extended
* or implemented by specific attribute views that define the attributes
* supported by the view. A specific attribute view will typically define
* type-safe methods to read or update the attributes that it supports.
*
* @since 1.7
*/
public interface AttributeView {
/**
* Returns the name of the attribute view.
*
* @return the name of the attribute view
*/
String name();
}

182
src/java.base/share/classes/java/nio/file/attribute/BasicFileAttributeView.java Normal file
View file

@ -0,0 +1,182 @@
/*
* 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.io.IOException;
/**
* A file attribute view that provides a view of a <em>basic set</em> of file
* attributes common to many file systems. The basic set of file attributes
* consist of <em>mandatory</em> and <em>optional</em> file attributes as
* defined by the {@link BasicFileAttributes} interface.
* <p> The file attributes are retrieved from the file system as a <em>bulk
* operation</em> by invoking the {@link #readAttributes() readAttributes} method.
* This class also defines the {@link #setTimes setTimes} method to update the
* file's time attributes.
*
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view have the following names and types:
* <blockquote>
* <table class="striped">
* <caption style="display:none">Supported attributes</caption>
* <thead>
* <tr>
* <th scope="col"> Name </th>
* <th scope="col"> Type </th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"> "lastModifiedTime" </th>
* <td> {@link FileTime} </td>
* </tr>
* <tr>
* <th scope="row"> "lastAccessTime" </th>
* <td> {@link FileTime} </td>
* </tr>
* <tr>
* <th scope="row"> "creationTime" </th>
* <td> {@link FileTime} </td>
* </tr>
* <tr>
* <th scope="row"> "size" </th>
* <td> {@link Long} </td>
* </tr>
* <tr>
* <th scope="row"> "isRegularFile" </th>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <th scope="row"> "isDirectory" </th>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <th scope="row"> "isSymbolicLink" </th>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <th scope="row"> "isOther" </th>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <th scope="row"> "fileKey" </th>
* <td> {@link Object} </td>
* </tr>
* </tbody>
* </table>
* </blockquote>
*
* <p> The {@link java.nio.file.Files#getAttribute getAttribute} method may be
* used to read any of these attributes as if by invoking the {@link
* #readAttributes() readAttributes()} method.
*
* <p> The {@link java.nio.file.Files#setAttribute setAttribute} method may be
* used to update the file's last modified time, last access time or create time
* attributes as if by invoking the {@link #setTimes setTimes} method.
*
* @since 1.7
*/
public interface BasicFileAttributeView
extends FileAttributeView
{
/**
* Returns the name of the attribute view. Attribute views of this type
* have the name {@code "basic"}.
*/
@Override
String name();
/**
* Reads the basic file attributes as a bulk operation.
*
* <p> It is implementation specific if all file attributes are read as an
* atomic operation with respect to other file system operations.
*
* @return the file attributes
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, its {@link SecurityManager#checkRead(String) checkRead}
* method is invoked to check read access to the file
*/
BasicFileAttributes readAttributes() throws IOException;
/**
* Updates any or all of the file's last modified time, last access time,
* and create time attributes.
*
* <p> This method updates the file's timestamp attributes. The values are
* converted to the epoch and precision supported by the file system.
* Converting from finer to coarser granularities result in precision loss.
* The behavior of this method when attempting to set a timestamp that is
* not supported or to a value that is outside the range supported by the
* underlying file store is not defined. It may or not fail by throwing an
* {@code IOException}.
*
* <p> If any of the {@code lastModifiedTime}, {@code lastAccessTime},
* or {@code createTime} parameters has the value {@code null} then the
* corresponding timestamp is not changed. An implementation may require to
* read the existing values of the file attributes when only some, but not
* all, of the timestamp attributes are updated. Consequently, this method
* may not be an atomic operation with respect to other file system
* operations. Reading and re-writing existing values may also result in
* precision loss. If all of the {@code lastModifiedTime}, {@code
* lastAccessTime} and {@code createTime} parameters are {@code null} then
* this method has no effect.
*
* <p> <b>Usage Example:</b>
* Suppose we want to change a file's last access time.
* <pre>
* Path path = ...
* FileTime time = ...
* Files.getFileAttributeView(path, BasicFileAttributeView.class).setTimes(null, time, null);
* </pre>
*
* @param lastModifiedTime
* the new last modified time, or {@code null} to not change the
* value
* @param lastAccessTime
* the last access time, or {@code null} to not change the value
* @param createTime
* the file's create time, or {@code null} to not change the value
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, its {@link SecurityManager#checkWrite(String) checkWrite}
* method is invoked to check write access to the file
*
* @see java.nio.file.Files#setLastModifiedTime
*/
void setTimes(FileTime lastModifiedTime,
FileTime lastAccessTime,
FileTime createTime) throws IOException;
}

155
src/java.base/share/classes/java/nio/file/attribute/BasicFileAttributes.java Normal file
View file

@ -0,0 +1,155 @@
/*
* Copyright (c) 2007, 2013, 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;
/**
* Basic attributes associated with a file in a file system.
*
* <p> Basic file attributes are attributes that are common to many file systems
* and consist of mandatory and optional file attributes as defined by this
* interface.
*
* <p> <b>Usage Example:</b>
* <pre>
* Path file = ...
* BasicFileAttributes attrs = Files.readAttributes(file, BasicFileAttributes.class);
* </pre>
*
* @since 1.7
*
* @see BasicFileAttributeView
*/
public interface BasicFileAttributes {
/**
* Returns the time of last modification.
*
* <p> If the file system implementation does not support a time stamp
* to indicate the time of last modification then this method returns an
* implementation specific default value, typically a {@code FileTime}
* representing the epoch (1970-01-01T00:00:00Z).
*
* @return a {@code FileTime} representing the time the file was last
* modified
*/
FileTime lastModifiedTime();
/**
* Returns the time of last access.
*
* <p> If the file system implementation does not support a time stamp
* to indicate the time of last access then this method returns
* an implementation specific default value, typically the {@link
* #lastModifiedTime() last-modified-time} or a {@code FileTime}
* representing the epoch (1970-01-01T00:00:00Z).
*
* @return a {@code FileTime} representing the time of last access
*/
FileTime lastAccessTime();
/**
* Returns the creation time. The creation time is the time that the file
* was created.
*
* <p> If the file system implementation does not support a time stamp
* to indicate the time when the file was created then this method returns
* an implementation specific default value, typically the {@link
* #lastModifiedTime() last-modified-time} or a {@code FileTime}
* representing the epoch (1970-01-01T00:00:00Z).
*
* @return a {@code FileTime} representing the time the file was created
*/
FileTime creationTime();
/**
* Tells whether the file is a regular file with opaque content.
*
* @return {@code true} if the file is a regular file with opaque content
*/
boolean isRegularFile();
/**
* Tells whether the file is a directory.
*
* @return {@code true} if the file is a directory
*/
boolean isDirectory();
/**
* Tells whether the file is a symbolic link.
*
* @return {@code true} if the file is a symbolic link
*/
boolean isSymbolicLink();
/**
* Tells whether the file is something other than a regular file, directory,
* or symbolic link.
*
* @return {@code true} if the file something other than a regular file,
* directory or symbolic link
*/
boolean isOther();
/**
* Returns the size of the file (in bytes). The size may differ from the
* actual size on the file system due to compression, support for sparse
* files, or other reasons. The size of files that are not {@link
* #isRegularFile regular} files is implementation specific and
* therefore unspecified.
*
* @return the file size, in bytes
*/
long size();
/**
* Returns an object that uniquely identifies the given file, or {@code
* null} if a file key is not available. On some platforms or file systems
* it is possible to use an identifier, or a combination of identifiers to
* uniquely identify a file. Such identifiers are important for operations
* such as file tree traversal in file systems that support <a
* href="../package-summary.html#links">symbolic links</a> or file systems
* that allow a file to be an entry in more than one directory. On UNIX file
* systems, for example, the <em>device ID</em> and <em>inode</em> are
* commonly used for such purposes.
*
* <p> The file key returned by this method can only be guaranteed to be
* unique if the file system and files remain static. Whether a file system
* re-uses identifiers after a file is deleted is implementation dependent and
* therefore unspecified.
*
* <p> File keys returned by this method can be compared for equality and are
* suitable for use in collections. If the file system and files remain static,
* and two files are the {@link java.nio.file.Files#isSameFile same} with
* non-{@code null} file keys, then their file keys are equal.
*
* @return an object that uniquely identifies the given file, or {@code null}
*
* @see java.nio.file.Files#walkFileTree
*/
Object fileKey();
}

184
src/java.base/share/classes/java/nio/file/attribute/DosFileAttributeView.java Normal file
View file

@ -0,0 +1,184 @@
/*
* 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.io.IOException;
/**
* A file attribute view that provides a view of the legacy "DOS" file attributes.
* These attributes are supported by file systems such as the File Allocation
* Table (FAT) format commonly used in <em>consumer devices</em>.
*
* <p> A {@code DosFileAttributeView} is a {@link BasicFileAttributeView} that
* additionally supports access to the set of DOS attribute flags that are used
* to indicate if the file is read-only, hidden, a system file, or archived.
*
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view are as defined by {@code
* BasicFileAttributeView}, and in addition, the following attributes are
* supported:
* <blockquote>
* <table class="striped">
* <caption style="display:none">Supported attributes</caption>
* <thead>
* <tr>
* <th scope="col"> Name </th>
* <th scope="col"> Type </th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"> readonly </th>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <th scope="row"> hidden </th>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <th scope="row"> system </th>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <th scope="row"> archive </th>
* <td> {@link Boolean} </td>
* </tr>
* </tbody>
* </table>
* </blockquote>
*
* <p> The {@link java.nio.file.Files#getAttribute getAttribute} method may
* be used to read any of these attributes, or any of the attributes defined by
* {@link BasicFileAttributeView} as if by invoking the {@link #readAttributes
* readAttributes()} method.
*
* <p> The {@link java.nio.file.Files#setAttribute setAttribute} method may
* be used to update the file's last modified time, last access time or create
* time attributes as defined by {@link BasicFileAttributeView}. It may also be
* used to update the DOS attributes as if by invoking the {@link #setReadOnly
* setReadOnly}, {@link #setHidden setHidden}, {@link #setSystem setSystem}, and
* {@link #setArchive setArchive} methods respectively.
*
* @since 1.7
*/
public interface DosFileAttributeView
extends BasicFileAttributeView
{
/**
* Returns the name of the attribute view. Attribute views of this type
* have the name {@code "dos"}.
*/
@Override
String name();
/**
* @throws IOException {@inheritDoc}
* @throws SecurityException {@inheritDoc}
*/
@Override
DosFileAttributes readAttributes() throws IOException;
/**
* Updates the value of the read-only attribute.
*
* <p> It is implementation specific if the attribute can be updated as an
* atomic operation with respect to other file system operations. An
* implementation may, for example, require to read the existing value of
* the DOS attribute in order to update this attribute.
*
* @param value
* the new value of the attribute
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default, and a security manager is installed,
* its {@link SecurityManager#checkWrite(String) checkWrite} method
* is invoked to check write access to the file
*/
void setReadOnly(boolean value) throws IOException;
/**
* Updates the value of the hidden attribute.
*
* <p> It is implementation specific if the attribute can be updated as an
* atomic operation with respect to other file system operations. An
* implementation may, for example, require to read the existing value of
* the DOS attribute in order to update this attribute.
*
* @param value
* the new value of the attribute
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default, and a security manager is installed,
* its {@link SecurityManager#checkWrite(String) checkWrite} method
* is invoked to check write access to the file
*/
void setHidden(boolean value) throws IOException;
/**
* Updates the value of the system attribute.
*
* <p> It is implementation specific if the attribute can be updated as an
* atomic operation with respect to other file system operations. An
* implementation may, for example, require to read the existing value of
* the DOS attribute in order to update this attribute.
*
* @param value
* the new value of the attribute
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default, and a security manager is installed,
* its {@link SecurityManager#checkWrite(String) checkWrite} method
* is invoked to check write access to the file
*/
void setSystem(boolean value) throws IOException;
/**
* Updates the value of the archive attribute.
*
* <p> It is implementation specific if the attribute can be updated as an
* atomic operation with respect to other file system operations. An
* implementation may, for example, require to read the existing value of
* the DOS attribute in order to update this attribute.
*
* @param value
* the new value of the attribute
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default, and a security manager is installed,
* its {@link SecurityManager#checkWrite(String) checkWrite} method
* is invoked to check write access to the file
*/
void setArchive(boolean value) throws IOException;
}

84
src/java.base/share/classes/java/nio/file/attribute/DosFileAttributes.java Normal file
View file

@ -0,0 +1,84 @@
/*
* 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;
/**
* File attributes associated with a file in a file system that supports
* legacy "DOS" attributes.
*
* <p> <b>Usage Example:</b>
* <pre>
* Path file = ...
* DosFileAttributes attrs = Files.readAttributes(file, DosFileAttributes.class);
* </pre>
*
* @since 1.7
*/
public interface DosFileAttributes
extends BasicFileAttributes
{
/**
* Returns the value of the read-only attribute.
*
* <p> This attribute is often used as a simple access control mechanism
* to prevent files from being deleted or updated. Whether the file system
* or platform does any enforcement to prevent <em>read-only</em> files
* from being updated is implementation specific.
*
* @return the value of the read-only attribute
*/
boolean isReadOnly();
/**
* Returns the value of the hidden attribute.
*
* <p> This attribute is often used to indicate if the file is visible to
* users.
*
* @return the value of the hidden attribute
*/
boolean isHidden();
/**
* Returns the value of the archive attribute.
*
* <p> This attribute is typically used by backup programs.
*
* @return the value of the archive attribute
*/
boolean isArchive();
/**
* Returns the value of the system attribute.
*
* <p> This attribute is often used to indicate that the file is a component
* of the operating system.
*
* @return the value of the system attribute
*/
boolean isSystem();
}

54
src/java.base/share/classes/java/nio/file/attribute/FileAttribute.java Normal file
View file

@ -0,0 +1,54 @@
/*
* Copyright (c) 2007, 2013, 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;
/**
* An object that encapsulates the value of a file attribute that can be set
* atomically when creating a new file or directory by invoking the {@link
* java.nio.file.Files#createFile createFile} or {@link
* java.nio.file.Files#createDirectory createDirectory} methods.
*
* @param <T> The type of the file attribute value
*
* @since 1.7
* @see PosixFilePermissions#asFileAttribute
*/
public interface FileAttribute<T> {
/**
* Returns the attribute name.
*
* @return The attribute name
*/
String name();
/**
* Returns the attribute value.
*
* @return The attribute value
*/
T value();
}

42
src/java.base/share/classes/java/nio/file/attribute/FileAttributeView.java Normal file
View file

@ -0,0 +1,42 @@
/*
* 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;
/**
* An attribute view that is a read-only or updatable view of non-opaque
* values associated with a file in a filesystem. This interface is extended or
* implemented by specific file attribute views that define methods to read
* and/or update the attributes of a file.
*
* @since 1.7
*
* @see java.nio.file.Files#getFileAttributeView(Path,Class,java.nio.file.LinkOption[])
*/
public interface FileAttributeView
extends AttributeView
{
}

101
src/java.base/share/classes/java/nio/file/attribute/FileOwnerAttributeView.java Normal file
View file

@ -0,0 +1,101 @@
/*
* Copyright (c) 2007, 2016, 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.io.IOException;
/**
* A file attribute view that supports reading or updating the owner of a file.
* This file attribute view is intended for file system implementations that
* support a file attribute that represents an identity that is the owner of
* the file. Often the owner of a file is the identity of the entity that
* created the file.
*
* <p> The {@link #getOwner getOwner} or {@link #setOwner setOwner} methods may
* be used to read or update the owner of the file.
*
* <p> The {@link java.nio.file.Files#getAttribute getAttribute} and
* {@link java.nio.file.Files#setAttribute setAttribute} methods may also be
* used to read or update the owner. In that case, the owner attribute is
* identified by the name {@code "owner"}, and the value of the attribute is
* a {@link UserPrincipal}.
*
* @since 1.7
*/
public interface FileOwnerAttributeView
extends FileAttributeView
{
/**
* Returns the name of the attribute view. Attribute views of this type
* have the name {@code "owner"}.
*/
@Override
String name();
/**
* Read the file owner.
*
* <p> It is implementation specific if the file owner can be a {@link
* GroupPrincipal group}.
*
* @return the file owner
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}{@code ("accessUserInformation")} or its
* {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*/
UserPrincipal getOwner() throws IOException;
/**
* Updates the file owner.
*
* <p> It is implementation specific if the file owner can be a {@link
* GroupPrincipal group}. To ensure consistent and correct behavior
* across platforms it is recommended that this method should only be used
* to set the file owner to a user principal that is not a group.
*
* @param owner
* the new file owner
*
* @throws IOException
* if an I/O error occurs, or the {@code owner} parameter is a
* group and this implementation does not support setting the owner
* to a group
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}{@code ("accessUserInformation")} or its
* {@link SecurityManager#checkWrite(String) checkWrite} method
* denies write access to the file.
*/
void setOwner(UserPrincipal owner) throws IOException;
}

38
src/java.base/share/classes/java/nio/file/attribute/FileStoreAttributeView.java Normal file
View file

@ -0,0 +1,38 @@
/*
* Copyright (c) 2007, 2009, 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;
/**
* An attribute view that is a read-only or updatable view of the attributes of
* a {@link java.nio.file.FileStore}.
*
* @since 1.7
*/
public interface FileStoreAttributeView
extends AttributeView
{
}

475
src/java.base/share/classes/java/nio/file/attribute/FileTime.java Normal file
View file

@ -0,0 +1,475 @@
/*
* Copyright (c) 2009, 2013, 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.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
/**
* Represents the value of a file's time stamp attribute. For example, it may
* represent the time that the file was last
* {@link BasicFileAttributes#lastModifiedTime() modified},
* {@link BasicFileAttributes#lastAccessTime() accessed},
* or {@link BasicFileAttributes#creationTime() created}.
*
* <p> Instances of this class are immutable.
*
* @since 1.7
* @see java.nio.file.Files#setLastModifiedTime
* @see java.nio.file.Files#getLastModifiedTime
*/
public final class FileTime
implements Comparable<FileTime>
{
/**
* The unit of granularity to interpret the value. Null if
* this {@code FileTime} is converted from an {@code Instant},
* the {@code value} and {@code unit} pair will not be used
* in this scenario.
*/
private final TimeUnit unit;
/**
* The value since the epoch; can be negative.
*/
private final long value;
/**
* The value as Instant (created lazily, if not from an instant)
*/
private Instant instant;
/**
* The value return by toString (created lazily)
*/
private String valueAsString;
/**
* Initializes a new instance of this class.
*/
private FileTime(long value, TimeUnit unit, Instant instant) {
this.value = value;
this.unit = unit;
this.instant = instant;
}
/**
* Returns a {@code FileTime} representing a value at the given unit of
* granularity.
*
* @param value
* the value since the epoch (1970-01-01T00:00:00Z); can be
* negative
* @param unit
* the unit of granularity to interpret the value
*
* @return a {@code FileTime} representing the given value
*/
public static FileTime from(long value, TimeUnit unit) {
Objects.requireNonNull(unit, "unit");
return new FileTime(value, unit, null);
}
/**
* Returns a {@code FileTime} representing the given value in milliseconds.
*
* @param value
* the value, in milliseconds, since the epoch
* (1970-01-01T00:00:00Z); can be negative
*
* @return a {@code FileTime} representing the given value
*/
public static FileTime fromMillis(long value) {
return new FileTime(value, TimeUnit.MILLISECONDS, null);
}
/**
* Returns a {@code FileTime} representing the same point of time value
* on the time-line as the provided {@code Instant} object.
*
* @param instant
* the instant to convert
* @return a {@code FileTime} representing the same point on the time-line
* as the provided instant
* @since 1.8
*/
public static FileTime from(Instant instant) {
Objects.requireNonNull(instant, "instant");
return new FileTime(0, null, instant);
}
/**
* Returns the value at the given unit of granularity.
*
* <p> Conversion from a coarser granularity that would numerically overflow
* saturate to {@code Long.MIN_VALUE} if negative or {@code Long.MAX_VALUE}
* if positive.
*
* @param unit
* the unit of granularity for the return value
*
* @return value in the given unit of granularity, since the epoch
* since the epoch (1970-01-01T00:00:00Z); can be negative
*/
public long to(TimeUnit unit) {
Objects.requireNonNull(unit, "unit");
if (this.unit != null) {
return unit.convert(this.value, this.unit);
} else {
long secs = unit.convert(instant.getEpochSecond(), TimeUnit.SECONDS);
if (secs == Long.MIN_VALUE || secs == Long.MAX_VALUE) {
return secs;
}
long nanos = unit.convert(instant.getNano(), TimeUnit.NANOSECONDS);
long r = secs + nanos;
// Math.addExact() variant
if (((secs ^ r) & (nanos ^ r)) < 0) {
return (secs < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
}
return r;
}
}
/**
* Returns the value in milliseconds.
*
* <p> Conversion from a coarser granularity that would numerically overflow
* saturate to {@code Long.MIN_VALUE} if negative or {@code Long.MAX_VALUE}
* if positive.
*
* @return the value in milliseconds, since the epoch (1970-01-01T00:00:00Z)
*/
public long toMillis() {
if (unit != null) {
return unit.toMillis(value);
} else {
long secs = instant.getEpochSecond();
int nanos = instant.getNano();
// Math.multiplyExact() variant
long r = secs * 1000;
long ax = Math.abs(secs);
if (((ax | 1000) >>> 31 != 0)) {
if ((r / 1000) != secs) {
return (secs < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
}
}
return r + nanos / 1000_000;
}
}
/**
* Time unit constants for conversion.
*/
private static final long HOURS_PER_DAY = 24L;
private static final long MINUTES_PER_HOUR = 60L;
private static final long SECONDS_PER_MINUTE = 60L;
private static final long SECONDS_PER_HOUR = SECONDS_PER_MINUTE * MINUTES_PER_HOUR;
private static final long SECONDS_PER_DAY = SECONDS_PER_HOUR * HOURS_PER_DAY;
private static final long MILLIS_PER_SECOND = 1000L;
private static final long MICROS_PER_SECOND = 1000_000L;
private static final long NANOS_PER_SECOND = 1000_000_000L;
private static final int NANOS_PER_MILLI = 1000_000;
private static final int NANOS_PER_MICRO = 1000;
// The epoch second of Instant.MIN.
private static final long MIN_SECOND = -31557014167219200L;
// The epoch second of Instant.MAX.
private static final long MAX_SECOND = 31556889864403199L;
/*
* Scale d by m, checking for overflow.
*/
private static long scale(long d, long m, long over) {
if (d > over) return Long.MAX_VALUE;
if (d < -over) return Long.MIN_VALUE;
return d * m;
}
/**
* Converts this {@code FileTime} object to an {@code Instant}.
*
* <p> The conversion creates an {@code Instant} that represents the
* same point on the time-line as this {@code FileTime}.
*
* <p> {@code FileTime} can store points on the time-line further in the
* future and further in the past than {@code Instant}. Conversion
* from such further time points saturates to {@link Instant#MIN} if
* earlier than {@code Instant.MIN} or {@link Instant#MAX} if later
* than {@code Instant.MAX}.
*
* @return an instant representing the same point on the time-line as
* this {@code FileTime} object
* @since 1.8
*/
public Instant toInstant() {
if (instant == null) {
long secs = 0L;
int nanos = 0;
switch (unit) {
case DAYS:
secs = scale(value, SECONDS_PER_DAY,
Long.MAX_VALUE/SECONDS_PER_DAY);
break;
case HOURS:
secs = scale(value, SECONDS_PER_HOUR,
Long.MAX_VALUE/SECONDS_PER_HOUR);
break;
case MINUTES:
secs = scale(value, SECONDS_PER_MINUTE,
Long.MAX_VALUE/SECONDS_PER_MINUTE);
break;
case SECONDS:
secs = value;
break;
case MILLISECONDS:
secs = Math.floorDiv(value, MILLIS_PER_SECOND);
nanos = (int)Math.floorMod(value, MILLIS_PER_SECOND)
* NANOS_PER_MILLI;
break;
case MICROSECONDS:
secs = Math.floorDiv(value, MICROS_PER_SECOND);
nanos = (int)Math.floorMod(value, MICROS_PER_SECOND)
* NANOS_PER_MICRO;
break;
case NANOSECONDS:
secs = Math.floorDiv(value, NANOS_PER_SECOND);
nanos = (int)Math.floorMod(value, NANOS_PER_SECOND);
break;
default : throw new AssertionError("Unit not handled");
}
if (secs <= MIN_SECOND)
instant = Instant.MIN;
else if (secs >= MAX_SECOND)
instant = Instant.MAX;
else
instant = Instant.ofEpochSecond(secs, nanos);
}
return instant;
}
/**
* Tests this {@code FileTime} for equality with the given object.
*
* <p> The result is {@code true} if and only if the argument is not {@code
* null} and is a {@code FileTime} that represents the same time. This
* method satisfies the general contract of the {@code Object.equals} method.
*
* @param obj
* the object to compare with
*
* @return {@code true} if, and only if, the given object is a {@code
* FileTime} that represents the same time
*/
@Override
public boolean equals(Object obj) {
return (obj instanceof FileTime) ? compareTo((FileTime)obj) == 0 : false;
}
/**
* Computes a hash code for this file time.
*
* <p> The hash code is based upon the value represented, and satisfies the
* general contract of the {@link Object#hashCode} method.
*
* @return the hash-code value
*/
@Override
public int hashCode() {
// hashcode of instant representation to satisfy contract with equals
return toInstant().hashCode();
}
private long toDays() {
if (unit != null) {
return unit.toDays(value);
} else {
return TimeUnit.SECONDS.toDays(toInstant().getEpochSecond());
}
}
private long toExcessNanos(long days) {
if (unit != null) {
return unit.toNanos(value - unit.convert(days, TimeUnit.DAYS));
} else {
return TimeUnit.SECONDS.toNanos(toInstant().getEpochSecond()
- TimeUnit.DAYS.toSeconds(days));
}
}
/**
* Compares the value of two {@code FileTime} objects for order.
*
* @param other
* the other {@code FileTime} to be compared
*
* @return {@code 0} if this {@code FileTime} is equal to {@code other}, a
* value less than 0 if this {@code FileTime} represents a time
* that is before {@code other}, and a value greater than 0 if this
* {@code FileTime} represents a time that is after {@code other}
*/
@Override
public int compareTo(FileTime other) {
// same granularity
if (unit != null && unit == other.unit) {
return Long.compare(value, other.value);
} else {
// compare using instant representation when unit differs
long secs = toInstant().getEpochSecond();
long secsOther = other.toInstant().getEpochSecond();
int cmp = Long.compare(secs, secsOther);
if (cmp != 0) {
return cmp;
}
cmp = Long.compare(toInstant().getNano(), other.toInstant().getNano());
if (cmp != 0) {
return cmp;
}
if (secs != MAX_SECOND && secs != MIN_SECOND) {
return 0;
}
// if both this and other's Instant reps are MIN/MAX,
// use daysSinceEpoch and nanosOfDays, which will not
// saturate during calculation.
long days = toDays();
long daysOther = other.toDays();
if (days == daysOther) {
return Long.compare(toExcessNanos(days), other.toExcessNanos(daysOther));
}
return Long.compare(days, daysOther);
}
}
// days in a 400 year cycle = 146097
// days in a 10,000 year cycle = 146097 * 25
// seconds per day = 86400
private static final long DAYS_PER_10000_YEARS = 146097L * 25L;
private static final long SECONDS_PER_10000_YEARS = 146097L * 25L * 86400L;
private static final long SECONDS_0000_TO_1970 = ((146097L * 5L) - (30L * 365L + 7L)) * 86400L;
// append year/month/day/hour/minute/second/nano with width and 0 padding
private StringBuilder append(StringBuilder sb, int w, int d) {
while (w > 0) {
sb.append((char)(d/w + '0'));
d = d % w;
w /= 10;
}
return sb;
}
/**
* Returns the string representation of this {@code FileTime}. The string
* is returned in the <a
* href="http://www.w3.org/TR/NOTE-datetime">ISO&nbsp;8601</a> format:
* <pre>
* YYYY-MM-DDThh:mm:ss[.s+]Z
* </pre>
* where "{@code [.s+]}" represents a dot followed by one of more digits
* for the decimal fraction of a second. It is only present when the decimal
* fraction of a second is not zero. For example, {@code
* FileTime.fromMillis(1234567890000L).toString()} yields {@code
* "2009-02-13T23:31:30Z"}, and {@code FileTime.fromMillis(1234567890123L).toString()}
* yields {@code "2009-02-13T23:31:30.123Z"}.
*
* <p> A {@code FileTime} is primarily intended to represent the value of a
* file's time stamp. Where used to represent <i>extreme values</i>, where
* the year is less than "{@code 0001}" or greater than "{@code 9999}" then
* this method deviates from ISO 8601 in the same manner as the
* <a href="http://www.w3.org/TR/xmlschema-2/#deviantformats">XML Schema
* language</a>. That is, the year may be expanded to more than four digits
* and may be negative-signed. If more than four digits then leading zeros
* are not present. The year before "{@code 0001}" is "{@code -0001}".
*
* @return the string representation of this file time
*/
@Override
public String toString() {
if (valueAsString == null) {
long secs = 0L;
int nanos = 0;
if (instant == null && unit.compareTo(TimeUnit.SECONDS) >= 0) {
secs = unit.toSeconds(value);
} else {
secs = toInstant().getEpochSecond();
nanos = toInstant().getNano();
}
LocalDateTime ldt;
int year = 0;
if (secs >= -SECONDS_0000_TO_1970) {
// current era
long zeroSecs = secs - SECONDS_PER_10000_YEARS + SECONDS_0000_TO_1970;
long hi = Math.floorDiv(zeroSecs, SECONDS_PER_10000_YEARS) + 1;
long lo = Math.floorMod(zeroSecs, SECONDS_PER_10000_YEARS);
ldt = LocalDateTime.ofEpochSecond(lo - SECONDS_0000_TO_1970, nanos, ZoneOffset.UTC);
year = ldt.getYear() + (int)hi * 10000;
} else {
// before current era
long zeroSecs = secs + SECONDS_0000_TO_1970;
long hi = zeroSecs / SECONDS_PER_10000_YEARS;
long lo = zeroSecs % SECONDS_PER_10000_YEARS;
ldt = LocalDateTime.ofEpochSecond(lo - SECONDS_0000_TO_1970, nanos, ZoneOffset.UTC);
year = ldt.getYear() + (int)hi * 10000;
}
if (year <= 0) {
year = year - 1;
}
int fraction = ldt.getNano();
StringBuilder sb = new StringBuilder(64);
sb.append(year < 0 ? "-" : "");
year = Math.abs(year);
if (year < 10000) {
append(sb, 1000, Math.abs(year));
} else {
sb.append(String.valueOf(year));
}
sb.append('-');
append(sb, 10, ldt.getMonthValue());
sb.append('-');
append(sb, 10, ldt.getDayOfMonth());
sb.append('T');
append(sb, 10, ldt.getHour());
sb.append(':');
append(sb, 10, ldt.getMinute());
sb.append(':');
append(sb, 10, ldt.getSecond());
if (fraction != 0) {
sb.append('.');
// adding leading zeros and stripping any trailing zeros
int w = 100_000_000;
while (fraction % 10 == 0) {
fraction /= 10;
w /= 10;
}
append(sb, w, fraction);
}
sb.append('Z');
valueAsString = sb.toString();
}
return valueAsString;
}
}

42
src/java.base/share/classes/java/nio/file/attribute/GroupPrincipal.java Normal file
View file

@ -0,0 +1,42 @@
/*
* Copyright (c) 2007, 2009, 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;
/**
* A {@code UserPrincipal} representing a <em>group identity</em>, used to
* determine access rights to objects in a file system. The exact definition of
* a group is implementation specific, but typically, it represents an identity
* created for administrative purposes so as to determine the access rights for
* the members of the group. Whether an entity can be a member of multiple
* groups, and whether groups can be nested, are implementation specified and
* therefore not specified.
*
* @since 1.7
*
* @see UserPrincipalLookupService#lookupPrincipalByGroupName
*/
public interface GroupPrincipal extends UserPrincipal { }

201
src/java.base/share/classes/java/nio/file/attribute/PosixFileAttributeView.java Normal file
View file

@ -0,0 +1,201 @@
/*
* 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.nio.file.*;
import java.util.Set;
import java.io.IOException;
/**
* A file attribute view that provides a view of the file attributes commonly
* associated with files on file systems used by operating systems that implement
* the Portable Operating System Interface (POSIX) family of standards.
*
* <p> Operating systems that implement the <a href="http://www.opengroup.org">
* POSIX</a> family of standards commonly use file systems that have a
* file <em>owner</em>, <em>group-owner</em>, and related <em>access
* permissions</em>. This file attribute view provides read and write access
* to these attributes.
*
* <p> The {@link #readAttributes() readAttributes} method is used to read the
* file's attributes. The file {@link PosixFileAttributes#owner() owner} is
* represented by a {@link UserPrincipal} that is the identity of the file owner
* for the purposes of access control. The {@link PosixFileAttributes#group()
* group-owner}, represented by a {@link GroupPrincipal}, is the identity of the
* group owner, where a group is an identity created for administrative purposes
* so as to determine the access rights for the members of the group.
*
* <p> The {@link PosixFileAttributes#permissions() permissions} attribute is a
* set of access permissions. This file attribute view provides access to the nine
* permission defined by the {@link PosixFilePermission} class.
* These nine permission bits determine the <em>read</em>, <em>write</em>, and
* <em>execute</em> access for the file owner, group, and others (others
* meaning identities other than the owner and members of the group). Some
* operating systems and file systems may provide additional permission bits
* but access to these other bits is not defined by this class in this release.
*
* <p> <b>Usage Example:</b>
* Suppose we need to print out the owner and access permissions of a file:
* <pre>
* Path file = ...
* PosixFileAttributes attrs = Files.getFileAttributeView(file, PosixFileAttributeView.class)
* .readAttributes();
* System.out.format("%s %s%n",
* attrs.owner().getName(),
* PosixFilePermissions.toString(attrs.permissions()));
* </pre>
*
* <h2> Dynamic Access </h2>
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view are as defined by {@link
* BasicFileAttributeView} and {@link FileOwnerAttributeView}, and in addition,
* the following attributes are supported:
* <blockquote>
* <table class="striped">
* <caption style="display:none">Supported attributes</caption>
* <thead>
* <tr>
* <th scope="col"> Name </th>
* <th scope="col"> Type </th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"> "permissions" </th>
* <td> {@link Set}&lt;{@link PosixFilePermission}&gt; </td>
* </tr>
* <tr>
* <th scope="row"> "group" </th>
* <td> {@link GroupPrincipal} </td>
* </tr>
* </tbody>
* </table>
* </blockquote>
*
* <p> The {@link Files#getAttribute getAttribute} method may be used to read
* any of these attributes, or any of the attributes defined by {@link
* BasicFileAttributeView} as if by invoking the {@link #readAttributes
* readAttributes()} method.
*
* <p> The {@link Files#setAttribute setAttribute} method may be used to update
* the file's last modified time, last access time or create time attributes as
* defined by {@link BasicFileAttributeView}. It may also be used to update
* the permissions, owner, or group-owner as if by invoking the {@link
* #setPermissions setPermissions}, {@link #setOwner setOwner}, and {@link
* #setGroup setGroup} methods respectively.
*
* <h2> Setting Initial Permissions </h2>
* <p> Implementations supporting this attribute view may also support setting
* the initial permissions when creating a file or directory. The
* initial permissions are provided to the {@link Files#createFile createFile}
* or {@link Files#createDirectory createDirectory} methods as a {@link
* FileAttribute} with {@link FileAttribute#name name} {@code "posix:permissions"}
* and a {@link FileAttribute#value value} that is the set of permissions. The
* following example uses the {@link PosixFilePermissions#asFileAttribute
* asFileAttribute} method to construct a {@code FileAttribute} when creating a
* file:
*
* <pre>
* Path path = ...
* Set&lt;PosixFilePermission&gt; perms =
* EnumSet.of(OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ);
* Files.createFile(path, PosixFilePermissions.asFileAttribute(perms));
* </pre>
*
* <p> When the access permissions are set at file creation time then the actual
* value of the permissions may differ that the value of the attribute object.
* The reasons for this are implementation specific. On UNIX systems, for
* example, a process has a <em>umask</em> that impacts the permission bits
* of newly created files. Where an implementation supports the setting of
* the access permissions, and the underlying file system supports access
* permissions, then it is required that the value of the actual access
* permissions will be equal or less than the value of the attribute
* provided to the {@link Files#createFile createFile} or {@link
* Files#createDirectory createDirectory} methods. In other words, the file may
* be more secure than requested.
*
* @since 1.7
*/
public interface PosixFileAttributeView
extends BasicFileAttributeView, FileOwnerAttributeView
{
/**
* Returns the name of the attribute view. Attribute views of this type
* have the name {@code "posix"}.
*/
@Override
String name();
/**
* @throws IOException {@inheritDoc}
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies
* {@link RuntimePermission}{@code ("accessUserInformation")}
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*/
@Override
PosixFileAttributes readAttributes() throws IOException;
/**
* Updates the file permissions.
*
* @param perms
* the new set of permissions
*
* @throws ClassCastException
* if the sets contains elements that are not of type {@code
* PosixFilePermission}
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies
* {@link RuntimePermission}{@code ("accessUserInformation")}
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
void setPermissions(Set<PosixFilePermission> perms) throws IOException;
/**
* Updates the file group-owner.
*
* @param group
* the new file group-owner
*
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it denies
* {@link RuntimePermission}{@code ("accessUserInformation")}
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
void setGroup(GroupPrincipal group) throws IOException;
}

75
src/java.base/share/classes/java/nio/file/attribute/PosixFileAttributes.java Normal file
View file

@ -0,0 +1,75 @@
/*
* 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.Set;
/**
* File attributes associated with files on file systems used by operating systems
* that implement the Portable Operating System Interface (POSIX) family of
* standards.
*
* <p> The POSIX attributes of a file are retrieved using a {@link
* PosixFileAttributeView} by invoking its {@link
* PosixFileAttributeView#readAttributes readAttributes} method.
*
* @since 1.7
*/
public interface PosixFileAttributes
extends BasicFileAttributes
{
/**
* Returns the owner of the file.
*
* @return the file owner
*
* @see PosixFileAttributeView#setOwner
*/
UserPrincipal owner();
/**
* Returns the group owner of the file.
*
* @return the file group owner
*
* @see PosixFileAttributeView#setGroup
*/
GroupPrincipal group();
/**
* Returns the permissions of the file. The file permissions are returned
* as a set of {@link PosixFilePermission} elements. The returned set is a
* copy of the file permissions and is modifiable. This allows the result
* to be modified and passed to the {@link PosixFileAttributeView#setPermissions
* setPermissions} method to update the file's permissions.
*
* @return the file permissions
*
* @see PosixFileAttributeView#setPermissions
*/
Set<PosixFilePermission> permissions();
}

84
src/java.base/share/classes/java/nio/file/attribute/PosixFilePermission.java Normal file
View file

@ -0,0 +1,84 @@
/*
* 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;
/**
* Defines the bits for use with the {@link PosixFileAttributes#permissions()
* permissions} attribute.
*
* <p> The {@link PosixFilePermissions} class defines methods for manipulating
* set of permissions.
*
* @since 1.7
*/
public enum PosixFilePermission {
/**
* Read permission, owner.
*/
OWNER_READ,
/**
* Write permission, owner.
*/
OWNER_WRITE,
/**
* Execute/search permission, owner.
*/
OWNER_EXECUTE,
/**
* Read permission, group.
*/
GROUP_READ,
/**
* Write permission, group.
*/
GROUP_WRITE,
/**
* Execute/search permission, group.
*/
GROUP_EXECUTE,
/**
* Read permission, others.
*/
OTHERS_READ,
/**
* Write permission, others.
*/
OTHERS_WRITE,
/**
* Execute/search permission, others.
*/
OTHERS_EXECUTE;
}

180
src/java.base/share/classes/java/nio/file/attribute/PosixFilePermissions.java Normal file
View file

@ -0,0 +1,180 @@
/*
* 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 static java.nio.file.attribute.PosixFilePermission.*;
import java.util.*;
/**
* This class consists exclusively of static methods that operate on sets of
* {@link PosixFilePermission} objects.
*
* @since 1.7
*/
public final class PosixFilePermissions {
private PosixFilePermissions() { }
// Write string representation of permission bits to {@code sb}.
private static void writeBits(StringBuilder sb, boolean r, boolean w, boolean x) {
if (r) {
sb.append('r');
} else {
sb.append('-');
}
if (w) {
sb.append('w');
} else {
sb.append('-');
}
if (x) {
sb.append('x');
} else {
sb.append('-');
}
}
/**
* Returns the {@code String} representation of a set of permissions. It
* is guaranteed that the returned {@code String} can be parsed by the
* {@link #fromString} method.
*
* <p> If the set contains {@code null} or elements that are not of type
* {@code PosixFilePermission} then these elements are ignored.
*
* @param perms
* the set of permissions
*
* @return the string representation of the permission set
*/
public static String toString(Set<PosixFilePermission> perms) {
StringBuilder sb = new StringBuilder(9);
writeBits(sb, perms.contains(OWNER_READ), perms.contains(OWNER_WRITE),
perms.contains(OWNER_EXECUTE));
writeBits(sb, perms.contains(GROUP_READ), perms.contains(GROUP_WRITE),
perms.contains(GROUP_EXECUTE));
writeBits(sb, perms.contains(OTHERS_READ), perms.contains(OTHERS_WRITE),
perms.contains(OTHERS_EXECUTE));
return sb.toString();
}
private static boolean isSet(char c, char setValue) {
if (c == setValue)
return true;
if (c == '-')
return false;
throw new IllegalArgumentException("Invalid mode");
}
private static boolean isR(char c) { return isSet(c, 'r'); }
private static boolean isW(char c) { return isSet(c, 'w'); }
private static boolean isX(char c) { return isSet(c, 'x'); }
/**
* Returns the set of permissions corresponding to a given {@code String}
* representation.
*
* <p> The {@code perms} parameter is a {@code String} representing the
* permissions. It has 9 characters that are interpreted as three sets of
* three. The first set refers to the owner's permissions; the next to the
* group permissions and the last to others. Within each set, the first
* character is {@code 'r'} to indicate permission to read, the second
* character is {@code 'w'} to indicate permission to write, and the third
* character is {@code 'x'} for execute permission. Where a permission is
* not set then the corresponding character is set to {@code '-'}.
*
* <p> <b>Usage Example:</b>
* Suppose we require the set of permissions that indicate the owner has read,
* write, and execute permissions, the group has read and execute permissions
* and others have none.
* <pre>
* Set&lt;PosixFilePermission&gt; perms = PosixFilePermissions.fromString("rwxr-x---");
* </pre>
*
* @param perms
* string representing a set of permissions
*
* @return the resulting set of permissions
*
* @throws IllegalArgumentException
* if the string cannot be converted to a set of permissions
*
* @see #toString(Set)
*/
public static Set<PosixFilePermission> fromString(String perms) {
if (perms.length() != 9)
throw new IllegalArgumentException("Invalid mode");
Set<PosixFilePermission> result = EnumSet.noneOf(PosixFilePermission.class);
if (isR(perms.charAt(0))) result.add(OWNER_READ);
if (isW(perms.charAt(1))) result.add(OWNER_WRITE);
if (isX(perms.charAt(2))) result.add(OWNER_EXECUTE);
if (isR(perms.charAt(3))) result.add(GROUP_READ);
if (isW(perms.charAt(4))) result.add(GROUP_WRITE);
if (isX(perms.charAt(5))) result.add(GROUP_EXECUTE);
if (isR(perms.charAt(6))) result.add(OTHERS_READ);
if (isW(perms.charAt(7))) result.add(OTHERS_WRITE);
if (isX(perms.charAt(8))) result.add(OTHERS_EXECUTE);
return result;
}
/**
* Creates a {@link FileAttribute}, encapsulating a copy of the given file
* permissions, suitable for passing to the {@link java.nio.file.Files#createFile
* createFile} or {@link java.nio.file.Files#createDirectory createDirectory}
* methods.
*
* @param perms
* the set of permissions
*
* @return an attribute encapsulating the given file permissions with
* {@link FileAttribute#name name} {@code "posix:permissions"}
*
* @throws ClassCastException
* if the set contains elements that are not of type {@code
* PosixFilePermission}
*/
public static FileAttribute<Set<PosixFilePermission>>
asFileAttribute(Set<PosixFilePermission> perms)
{
// copy set and check for nulls (CCE will be thrown if an element is not
// a PosixFilePermission)
perms = new HashSet<>(perms);
for (PosixFilePermission p: perms) {
if (p == null)
throw new NullPointerException();
}
final Set<PosixFilePermission> value = perms;
return new FileAttribute<>() {
@Override
public String name() {
return "posix:permissions";
}
@Override
public Set<PosixFilePermission> value() {
return Collections.unmodifiableSet(value);
}
};
}
}

231
src/java.base/share/classes/java/nio/file/attribute/UserDefinedFileAttributeView.java Normal file
View file

@ -0,0 +1,231 @@
/*
* Copyright (c) 2007, 2013, 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.nio.ByteBuffer;
import java.util.List;
import java.io.IOException;
/**
* A file attribute view that provides a view of a file's user-defined
* attributes, sometimes known as <em>extended attributes</em>. User-defined
* file attributes are used to store metadata with a file that is not meaningful
* to the file system. It is primarily intended for file system implementations
* that support such a capability directly but may be emulated. The details of
* such emulation are highly implementation specific and therefore not specified.
*
* <p> This {@code FileAttributeView} provides a view of a file's user-defined
* attributes as a set of name/value pairs, where the attribute name is
* represented by a {@code String}. An implementation may require to encode and
* decode from the platform or file system representation when accessing the
* attribute. The value has opaque content. This attribute view defines the
* {@link #read read} and {@link #write write} methods to read the value into
* or write from a {@link ByteBuffer}. This {@code FileAttributeView} is not
* intended for use where the size of an attribute value is larger than {@link
* Integer#MAX_VALUE}.
*
* <p> User-defined attributes may be used in some implementations to store
* security related attributes so consequently, in the case of the default
* provider at least, all methods that access user-defined attributes require the
* {@code RuntimePermission("accessUserDefinedAttributes")} permission when a
* security manager is installed.
*
* <p> The {@link java.nio.file.FileStore#supportsFileAttributeView
* supportsFileAttributeView} method may be used to test if a specific {@link
* java.nio.file.FileStore FileStore} supports the storage of user-defined
* attributes.
*
* <p> Where dynamic access to file attributes is required, the {@link
* java.nio.file.Files#getAttribute getAttribute} method may be used to read
* the attribute value. The attribute value is returned as a byte array (byte[]).
* The {@link java.nio.file.Files#setAttribute setAttribute} method may be used
* to write the value of a user-defined attribute from a buffer (as if by
* invoking the {@link #write write} method), or byte array (byte[]).
*
* @since 1.7
*/
public interface UserDefinedFileAttributeView
extends FileAttributeView
{
/**
* Returns the name of this attribute view. Attribute views of this type
* have the name {@code "user"}.
*/
@Override
String name();
/**
* Returns a list containing the names of the user-defined attributes.
*
* @return An unmodifiable list containing the names of the file's
* user-defined
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}{@code ("accessUserDefinedAttributes")}
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*/
List<String> list() throws IOException;
/**
* Returns the size of the value of a user-defined attribute.
*
* @param name
* The attribute name
*
* @return The size of the attribute value, in bytes.
*
* @throws ArithmeticException
* If the size of the attribute is larger than {@link Integer#MAX_VALUE}
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}{@code ("accessUserDefinedAttributes")}
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*/
int size(String name) throws IOException;
/**
* Read the value of a user-defined attribute into a buffer.
*
* <p> This method reads the value of the attribute into the given buffer
* as a sequence of bytes, failing if the number of bytes remaining in
* the buffer is insufficient to read the complete attribute value. The
* number of bytes transferred into the buffer is {@code n}, where {@code n}
* is the size of the attribute value. The first byte in the sequence is at
* index {@code p} and the last byte is at index {@code p + n - 1}, where
* {@code p} is the buffer's position. Upon return the buffer's position
* will be equal to {@code p + n}; its limit will not have changed.
*
* <p> <b>Usage Example:</b>
* Suppose we want to read a file's MIME type that is stored as a user-defined
* attribute with the name "{@code user.mimetype}".
* <pre>
* UserDefinedFileAttributeView view =
* Files.getFileAttributeView(path, UserDefinedFileAttributeView.class);
* String name = "user.mimetype";
* ByteBuffer buf = ByteBuffer.allocate(view.size(name));
* view.read(name, buf);
* buf.flip();
* String value = Charset.defaultCharset().decode(buf).toString();
* </pre>
*
* @param name
* The attribute name
* @param dst
* The destination buffer
*
* @return The number of bytes read, possibly zero
*
* @throws IllegalArgumentException
* If the destination buffer is read-only
* @throws IOException
* If an I/O error occurs or there is insufficient space in the
* destination buffer for the attribute value
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}{@code ("accessUserDefinedAttributes")}
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*
* @see #size
*/
int read(String name, ByteBuffer dst) throws IOException;
/**
* Writes the value of a user-defined attribute from a buffer.
*
* <p> This method writes the value of the attribute from a given buffer as
* a sequence of bytes. The size of the value to transfer is {@code r},
* where {@code r} is the number of bytes remaining in the buffer, that is
* {@code src.remaining()}. The sequence of bytes is transferred from the
* buffer starting at index {@code p}, where {@code p} is the buffer's
* position. Upon return, the buffer's position will be equal to {@code
* p + n}, where {@code n} is the number of bytes transferred; its limit
* will not have changed.
*
* <p> If an attribute of the given name already exists then its value is
* replaced. If the attribute does not exist then it is created. If it
* implementation specific if a test to check for the existence of the
* attribute and the creation of attribute are atomic with respect to other
* file system activities.
*
* <p> Where there is insufficient space to store the attribute, or the
* attribute name or value exceed an implementation specific maximum size
* then an {@code IOException} is thrown.
*
* <p> <b>Usage Example:</b>
* Suppose we want to write a file's MIME type as a user-defined attribute:
* <pre>
* UserDefinedFileAttributeView view =
* FIles.getFileAttributeView(path, UserDefinedFileAttributeView.class);
* view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));
* </pre>
*
* @param name
* The attribute name
* @param src
* The buffer containing the attribute value
*
* @return The number of bytes written, possibly zero
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}{@code ("accessUserDefinedAttributes")}
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
int write(String name, ByteBuffer src) throws IOException;
/**
* Deletes a user-defined attribute.
*
* @param name
* The attribute name
*
* @throws IOException
* If an I/O error occurs or the attribute does not exist
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}{@code ("accessUserDefinedAttributes")}
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
void delete(String name) throws IOException;
}

54
src/java.base/share/classes/java/nio/file/attribute/UserPrincipal.java Normal file
View file

@ -0,0 +1,54 @@
/*
* Copyright (c) 2007, 2009, 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.security.Principal;
/**
* A {@code Principal} representing an identity used to determine access rights
* to objects in a file system.
*
* <p> On many platforms and file systems an entity requires appropriate access
* rights or permissions in order to access objects in a file system. The
* access rights are generally performed by checking the identity of the entity.
* For example, on implementations that use Access Control Lists (ACLs) to
* enforce privilege separation then a file in the file system may have an
* associated ACL that determines the access rights of identities specified in
* the ACL.
*
* <p> A {@code UserPrincipal} object is an abstract representation of an
* identity. It has a {@link #getName() name} that is typically the username or
* account name that it represents. User principal objects may be obtained using
* a {@link UserPrincipalLookupService}, or returned by {@link
* FileAttributeView} implementations that provide access to identity related
* attributes. For example, the {@link AclFileAttributeView} and {@link
* PosixFileAttributeView} provide access to a file's {@link
* PosixFileAttributes#owner owner}.
*
* @since 1.7
*/
public interface UserPrincipal extends Principal { }

106
src/java.base/share/classes/java/nio/file/attribute/UserPrincipalLookupService.java Normal file
View file

@ -0,0 +1,106 @@
/*
* Copyright (c) 2007, 2009, 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.io.IOException;
/**
* An object to lookup user and group principals by name. A {@link UserPrincipal}
* represents an identity that may be used to determine access rights to objects
* in a file system. A {@link GroupPrincipal} represents a <em>group identity</em>.
* A {@code UserPrincipalLookupService} defines methods to lookup identities by
* name or group name (which are typically user or account names). Whether names
* and group names are case sensitive or not depends on the implementation.
* The exact definition of a group is implementation specific but typically a
* group represents an identity created for administrative purposes so as to
* determine the access rights for the members of the group. In particular it is
* implementation specific if the <em>namespace</em> for names and groups is the
* same or is distinct. To ensure consistent and correct behavior across
* platforms it is recommended that this API be used as if the namespaces are
* distinct. In other words, the {@link #lookupPrincipalByName
* lookupPrincipalByName} should be used to lookup users, and {@link
* #lookupPrincipalByGroupName lookupPrincipalByGroupName} should be used to
* lookup groups.
*
* @since 1.7
*
* @see java.nio.file.FileSystem#getUserPrincipalLookupService
*/
public abstract class UserPrincipalLookupService {
/**
* Initializes a new instance of this class.
*/
protected UserPrincipalLookupService() {
}
/**
* Lookup a user principal by name.
*
* @param name
* the string representation of the user principal to lookup
*
* @return a user principal
*
* @throws UserPrincipalNotFoundException
* the principal does not exist
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it checks
* {@link RuntimePermission}{@code ("lookupUserInformation")}
*/
public abstract UserPrincipal lookupPrincipalByName(String name)
throws IOException;
/**
* Lookup a group principal by group name.
*
* <p> Where an implementation does not support any notion of group then
* this method always throws {@link UserPrincipalNotFoundException}. Where
* the namespace for user accounts and groups is the same, then this method
* is identical to invoking {@link #lookupPrincipalByName
* lookupPrincipalByName}.
*
* @param group
* the string representation of the group to lookup
*
* @return a group principal
*
* @throws UserPrincipalNotFoundException
* the principal does not exist or is not a group
* @throws IOException
* if an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it checks
* {@link RuntimePermission}{@code ("lookupUserInformation")}
*/
public abstract GroupPrincipal lookupPrincipalByGroupName(String group)
throws IOException;
}

64
src/java.base/share/classes/java/nio/file/attribute/UserPrincipalNotFoundException.java Normal file
View file

@ -0,0 +1,64 @@
/*
* Copyright (c) 2007, 2009, 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.io.IOException;
/**
* Checked exception thrown when a lookup of {@link UserPrincipal} fails because
* the principal does not exist.
*
* @since 1.7
*/
public class UserPrincipalNotFoundException
extends IOException
{
static final long serialVersionUID = -5369283889045833024L;
private final String name;
/**
* Constructs an instance of this class.
*
* @param name
* the principal name; may be {@code null}
*/
public UserPrincipalNotFoundException(String name) {
super();
this.name = name;
}
/**
* Returns the user principal name if this exception was created with the
* user principal name that was not found, otherwise {@code null}.
*
* @return the user principal name or {@code null}
*/
public String getName() {
return name;
}
}

130
src/java.base/share/classes/java/nio/file/attribute/package-info.java Normal file
View file

@ -0,0 +1,130 @@
/*
* 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.
*/
/**
* Interfaces and classes providing access to file and file system attributes.
*
* <table class="striped" style="padding-left:2em; text-align:left">
* <caption style="display:none">Attribute views</caption>
* <thead>
* <tr><th scope="col">Attribute views</th>
* <th scope="col">Description</th></tr>
* </thead>
* <tbody>
* <tr><th scope="row"><i>{@link java.nio.file.attribute.AttributeView}</i></th>
* <td>Can read or update non-opaque values associated with objects in a file system</td></tr>
* <tr><th scope="row">
* <span style="padding-left:1em"><i>{@link java.nio.file.attribute.FileAttributeView}</i></span></th>
* <td>Can read or update file attributes</td></tr>
* <tr><th scope="row">
* <span style="padding-left:2em">
* <i>{@link java.nio.file.attribute.BasicFileAttributeView}</i></span></th>
* <td>Can read or update a basic set of file attributes</td></tr>
* <tr><th scope="row">
* <span style="padding-left:3em">
* <i>{@link java.nio.file.attribute.PosixFileAttributeView}</i></span></th>
* <td>Can read or update POSIX defined file attributes</td></tr>
* <tr><th scope="row">
* <span style="padding-left:3em">
* <i>{@link java.nio.file.attribute.DosFileAttributeView}</i></span></th>
* <td>Can read or update FAT file attributes</td></tr>
* <tr><th scope="row">
* <span style="padding-left:2em">
* <i>{@link java.nio.file.attribute.FileOwnerAttributeView}</i></span></th>
* <td>Can read or update the owner of a file</td></tr>
* <tr><th scope="row">
* <span style="padding-left:3em">
* <i>{@link java.nio.file.attribute.AclFileAttributeView}</i></span></th>
* <td>Can read or update Access Control Lists</td></tr>
* <tr><th scope="row">
* <span style="padding-left:2em">
* <i>{@link java.nio.file.attribute.UserDefinedFileAttributeView}</i></span></th>
* <td>Can read or update user-defined file attributes</td></tr>
* <tr><th scope="row">
* <span style="padding-left:1em"><i>{@link java.nio.file.attribute.FileStoreAttributeView}</i></span></th>
* <td>Can read or update file system attributes</td></tr>
* </tbody>
* </table>
*
* <p> An attribute view provides a read-only or updatable view of the non-opaque
* values, or <em>metadata</em>, associated with objects in a file system.
* The {@link java.nio.file.attribute.FileAttributeView} interface is
* extended by several other interfaces that provide views to specific sets of file
* attributes. {@code FileAttributeViews} are selected by invoking the {@link
* java.nio.file.Files#getFileAttributeView} method with a
* <em>type-token</em> to identify the required view. Views can also be identified
* by name. The {@link java.nio.file.attribute.FileStoreAttributeView} interface
* provides access to file store attributes. A {@code FileStoreAttributeView} of
* a given type is obtained by invoking the {@link
* java.nio.file.FileStore#getFileStoreAttributeView} method.
*
* <p> The {@link java.nio.file.attribute.BasicFileAttributeView}
* class defines methods to read and update a <em>basic</em> set of file
* attributes that are common to many file systems.
*
* <p> The {@link java.nio.file.attribute.PosixFileAttributeView}
* interface extends {@code BasicFileAttributeView} by defining methods
* to access the file attributes commonly used by file systems and operating systems
* that implement the Portable Operating System Interface (POSIX) family of
* standards.
*
* <p> The {@link java.nio.file.attribute.DosFileAttributeView}
* class extends {@code BasicFileAttributeView} by defining methods to
* access the legacy "DOS" file attributes supported on file systems such as File
* Allocation Tabl (FAT), commonly used in consumer devices.
*
* <p> The {@link java.nio.file.attribute.AclFileAttributeView}
* class defines methods to read and write the Access Control List (ACL)
* file attribute. The ACL model used by this file attribute view is based
* on the model defined by <a href="http://www.ietf.org/rfc/rfc3530.txt">
* <i>RFC&nbsp;3530: Network File System (NFS) version 4 Protocol</i></a>.
*
* <p> In addition to attribute views, this package also defines classes and
* interfaces that are used when accessing attributes:
*
* <ul>
*
* <li> The {@link java.nio.file.attribute.UserPrincipal} and
* {@link java.nio.file.attribute.GroupPrincipal} interfaces represent an
* identity or group identity. </li>
*
* <li> The {@link java.nio.file.attribute.UserPrincipalLookupService}
* interface defines methods to lookup user or group principals. </li>
*
* <li> The {@link java.nio.file.attribute.FileAttribute} interface
* represents the value of an attribute for cases where the attribute value is
* required to be set atomically when creating an object in the file system. </li>
*
* </ul>
*
*
* <p> Unless otherwise noted, passing a {@code null} argument to a constructor
* or method in any class or interface in this package will cause a {@link
* java.lang.NullPointerException NullPointerException} to be thrown.
*
* @since 1.7
*/
package java.nio.file.attribute;