1 /*

     2  * Copyright 2007-2009 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.nio.file;

    27 

    28 import java.nio.file.attribute.*;

    29 

    30 /**

    31  * Storage for files. A {@code FileStore} represents a storage pool, device,

    32  * partition, volume, concrete file system or other implementation specific means

    33  * of file storage. The {@code FileStore} for where a file is stored is obtained

    34  * by invoking the {@link FileRef#getFileStore getFileStore} method, or all file

    35  * stores can be enumerated by invoking the {@link FileSystem#getFileStores

    36  * getFileStores} method.

    37  *

    38  * <p> In addition to the methods defined by this class, a file store may support

    39  * one or more {@link FileStoreAttributeView FileStoreAttributeView} classes

    40  * that provide a read-only or updatable view of a set of file store attributes.

    41  * File stores associated with the default provider support the {@link

    42  * FileStoreSpaceAttributeView} to read the space related attributes of the

    43  * file store.

    44  *

    45  * @since 1.7

    46  */

    47 

    48 public abstract class FileStore {

    49 

    50     /**

    51      * Initializes a new instance of this class.

    52      */

    53     protected FileStore() {

    54     }

    55 

    56     /**

    57      * Returns the name of this file store. The format of the name is highly

    58      * implementation specific. It will typically be the name of the storage

    59      * pool or volume.

    60      *

    61      * <p> The string returned by this method may differ from the string

    62      * returned by the {@link Object#toString() toString} method.

    63      *

    64      * @return  The name of this file store

    65      */

    66     public abstract String name();

    67 

    68     /**

    69      * Returns the <em>type</em> of this file store. The format of the string

    70      * returned by this method is highly implementation specific. It may

    71      * indicate, for example, the format used or if the file store is local

    72      * or remote.

    73      *

    74      * @return  A string representing the type of this file store

    75      */

    76     public abstract String type();

    77 

    78     /**

    79      * Tells whether this file store is read-only. A file store is read-only if

    80      * it does not support write operations or other changes to files. Any

    81      * attempt to create a file, open an existing file for writing etc. causes

    82      * an {@code IOException} to be thrown.

    83      *

    84      * @return  {@code true} if, and only if, this file store is read-only

    85      */

    86     public abstract boolean isReadOnly();

    87 

    88     /**

    89      * Tells whether or not this file store supports the file attributes

    90      * identified by the given file attribute view.

    91      *

    92      * <p> Invoking this method to test if the file store supports {@link

    93      * BasicFileAttributeView} will always return {@code true}. In the case of

    94      * the default provider, this method cannot guarantee to give the correct

    95      * result when the file store is not a local storage device. The reasons for

    96      * this are implementation specific and therefore unspecified.

    97      *

    98      * @param   type

    99      *          The file attribute view type

   100      *

   101      * @return  {@code true} if, and only if, the file attribute view is

   102      *          supported

   103      */

   104     public abstract boolean supportsFileAttributeView(Class<? extends FileAttributeView> type);

   105 

   106     /**

   107      * Tells whether or not this file store supports the file attributes

   108      * identified by the given file attribute view.

   109      *

   110      * <p> Invoking this method to test if the file store supports {@link

   111      * BasicFileAttributeView}, identified by the name "{@code basic}" will

   112      * always return {@code true}. In the case of the default provider, this

   113      * method cannot guarantee to give the correct result when the file store is

   114      * not a local storage device. The reasons for this are implementation

   115      * specific and therefore unspecified.

   116      *

   117      * @param   name

   118      *          The {@link FileAttributeView#name name} of file attribute view

   119      *

   120      * @return  {@code true} if, and only if, the file attribute view is

   121      *          supported

   122      */

   123     public abstract boolean supportsFileAttributeView(String name);

   124 

   125     /**

   126      * Returns a {@code FileStoreAttributeView} of the given type.

   127      *

   128      * <p> This method is intended to be used where the file store attribute

   129      * view defines type-safe methods to read or update the file store attributes.

   130      * The {@code type} parameter is the type of the attribute view required and

   131      * the method returns an instance of that type if supported.

   132      *

   133      * <p> For {@code FileStore} objects created by the default provider, then

   134      * the file stores support the {@link FileStoreSpaceAttributeView} that

   135      * provides access to space attributes. In that case invoking this method

   136      * with a parameter value of {@code FileStoreSpaceAttributeView.class} will

   137      * always return an instance of that class.

   138      *

   139      * @param   type

   140      *          The {@code Class} object corresponding to the attribute view

   141      *

   142      * @return  A file store attribute view of the specified type or

   143      *          {@code null} if the attribute view is not available

   144      */

   145     public abstract <V extends FileStoreAttributeView> V

   146         getFileStoreAttributeView(Class<V> type);

   147 

   148     /**

   149      * Returns a {@code FileStoreAttributeView} of the given name.

   150      *

   151      * <p> This method is intended to be used where <em>dynamic access</em> to

   152      * file store attributes is required. The {@code name} parameter specifies

   153      * the {@link FileAttributeView#name name} of the file store attribute view

   154      * and this method returns an instance of that view if supported.

   155      *

   156      * <p> For {@code FileStore} objects created by the default provider, then

   157      * the file stores support the {@link FileStoreSpaceAttributeView} that

   158      * provides access to space attributes. In that case invoking this method

   159      * with a parameter value of {@code "space"} will always return an instance

   160      * of that class.

   161      *

   162      * @param   name

   163      *          The name of the attribute view

   164      *

   165      * @return  A file store attribute view of the given name, or {@code null}

   166      *          if the attribute view is not available

   167      */

   168     public abstract FileStoreAttributeView getFileStoreAttributeView(String name);

   169 }