1 /*
   2  * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.nio.file.attribute;
  27 
  28 /**
  29  * Basic attributes associated with a file in a file system.
  30  *
  31  * <p> Basic file attributes are attributes that are common to many file systems
  32  * and consist of mandatory and optional file attributes as defined by this
  33  * interface.
  34  *
  35  * <p> <b>Usage Example:</b>
  36  * <pre>
  37  *    Path file = ...
  38  *    BasicFileAttributes attrs = Files.readAttributes(file, BasicFileAttributes.class);
  39  * </pre>
  40  *
  41  * @since 1.7
  42  *
  43  * @see BasicFileAttributeView
  44  */
  45 
  46 public interface BasicFileAttributes {
  47 
  48     /**
  49      * Returns the time of last modification.
  50      *
  51      * <p> If the file system implementation does not support a time stamp
  52      * to indicate the time of last modification then this method returns an
  53      * implementation specific default value, typically a {@code FileTime}
  54      * representing the epoch (1970-01-01T00:00:00Z).
  55      *
  56      * @return  a {@code FileTime} representing the time the file was last
  57      *          modified
  58      */
  59     FileTime lastModifiedTime();
  60 
  61     /**
  62      * Returns the time of last access.
  63      *
  64      * <p> If the file system implementation does not support a time stamp
  65      * to indicate the time of last access then this method returns
  66      * an implementation specific default value, typically the {@link
  67      * #lastModifiedTime() last-modified-time} or a {@code FileTime}
  68      * representing the epoch (1970-01-01T00:00:00Z).
  69      *
  70      * @return  a {@code FileTime} representing the time of last access
  71      */
  72     FileTime lastAccessTime();
  73 
  74     /**
  75      * Returns the creation time. The creation time is the time that the file
  76      * was created.
  77      *
  78      * <p> If the file system implementation does not support a time stamp
  79      * to indicate the time when the file was created then this method returns
  80      * an implementation specific default value, typically the {@link
  81      * #lastModifiedTime() last-modified-time} or a {@code FileTime}
  82      * representing the epoch (1970-01-01T00:00:00Z).
  83      *
  84      * @return   a {@code FileTime} representing the time the file was created
  85      */
  86     FileTime creationTime();
  87 
  88     /**
  89      * Tells whether the file is a regular file with opaque content.
  90      */
  91     boolean isRegularFile();
  92 
  93     /**
  94      * Tells whether the file is a directory.
  95      */
  96     boolean isDirectory();
  97 
  98     /**
  99      * Tells whether the file is a symbolic link.
 100      */
 101     boolean isSymbolicLink();
 102 
 103     /**
 104      * Tells whether the file is something other than a regular file, directory,
 105      * or symbolic link.
 106      */
 107     boolean isOther();
 108 
 109     /**
 110      * Returns the size of the file (in bytes). The size may differ from the
 111      * actual size on the file system due to compression, support for sparse
 112      * files, or other reasons. The size of files that are not {@link
 113      * #isRegularFile regular} files is implementation specific and
 114      * therefore unspecified.
 115      *
 116      * @return  the file size, in bytes
 117      */
 118     long size();
 119 
 120     /**
 121      * Returns an object that uniquely identifies the given file, or {@code
 122      * null} if a file key is not available. On some platforms or file systems
 123      * it is possible to use an identifier, or a combination of identifiers to
 124      * uniquely identify a file. Such identifiers are important for operations
 125      * such as file tree traversal in file systems that support <a
 126      * href="../package-summary.html#links">symbolic links</a> or file systems
 127      * that allow a file to be an entry in more than one directory. On UNIX file
 128      * systems, for example, the <em>device ID</em> and <em>inode</em> are
 129      * commonly used for such purposes.
 130      *
 131      * <p> The file key returned by this method can only be guaranteed to be
 132      * unique if the file system and files remain static. Whether a file system
 133      * re-uses identifiers after a file is deleted is implementation dependent and
 134      * therefore unspecified.
 135      *
 136      * <p> File keys returned by this method can be compared for equality and are
 137      * suitable for use in collections. If the file system and files remain static,
 138      * and two files are the {@link java.nio.file.Files#isSameFile same} with
 139      * non-{@code null} file keys, then their file keys are equal.
 140      *
 141      * @see java.nio.file.Files#walkFileTree
 142      */
 143     Object fileKey();
 144 }