/*
 * 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;

import java.nio.file.attribute.*;
import java.io.IOException;

Storage for files. A FileStore represents a storage pool, device, partition, volume, concrete file system or other implementation specific means of file storage. The FileStore for where a file is stored is obtained by invoking the getFileStore method, or all file stores can be enumerated by invoking the 
getFileStores method. 
 In addition to the methods defined by this class, a file store may support one or more FileStoreAttributeView classes that provide a read-only or updatable view of a set of file store attributes. 
Since:
1.7/**
 * Storage for files. A {@code FileStore} represents a storage pool, device,
 * partition, volume, concrete file system or other implementation specific means
 * of file storage. The {@code FileStore} for where a file is stored is obtained
 * by invoking the {@link Files#getFileStore getFileStore} method, or all file
 * stores can be enumerated by invoking the {@link FileSystem#getFileStores
 * getFileStores} method.
 *
 * <p> In addition to the methods defined by this class, a file store may support
 * one or more {@link FileStoreAttributeView FileStoreAttributeView} classes
 * that provide a read-only or updatable view of a set of file store attributes.
 *
 * @since 1.7
 */

public abstract class FileStore {

    
Initializes a new instance of this class.
/**
     * Initializes a new instance of this class.
     */
    protected FileStore() {
    }

    
Returns the name of this file store. The format of the name is highly
implementation specific. It will typically be the name of the storage
pool or volume.
 The string returned by this method may differ from the string returned by the toString method. 
Returns:
 the name of this file store/**
     * Returns the name of this file store. The format of the name is highly
     * implementation specific. It will typically be the name of the storage
     * pool or volume.
     *
     * <p> The string returned by this method may differ from the string
     * returned by the {@link Object#toString() toString} method.
     *
     * @return  the name of this file store
     */
    public abstract String name();

    
Returns the type of this file store. The format of the string
returned by this method is highly implementation specific. It may
indicate, for example, the format used or if the file store is local
or remote.
Returns:
 a string representing the type of this file store/**
     * Returns the <em>type</em> of this file store. The format of the string
     * returned by this method is highly implementation specific. It may
     * indicate, for example, the format used or if the file store is local
     * or remote.
     *
     * @return  a string representing the type of this file store
     */
    public abstract String type();

    
Tells whether this file store is read-only. A file store is read-only if it does not support write operations or other changes to files. Any attempt to create a file, open an existing file for writing etc. causes an IOException to be thrown. 
Returns:
 true if, and only if, this file store is read-only/**
     * Tells whether this file store is read-only. A file store is read-only if
     * it does not support write operations or other changes to files. Any
     * attempt to create a file, open an existing file for writing etc. causes
     * an {@code IOException} to be thrown.
     *
     * @return  {@code true} if, and only if, this file store is read-only
     */
    public abstract boolean isReadOnly();

    
Returns the size, in bytes, of the file store.
Throws:
IOException – 
         if an I/O error occurs
Returns:
 the size of the file store, in bytes/**
     * Returns the size, in bytes, of the file store.
     *
     * @return  the size of the file store, in bytes
     *
     * @throws  IOException
     *          if an I/O error occurs
     */
    public abstract long getTotalSpace() throws IOException;

    
Returns the number of bytes available to this Java virtual machine on the
file store.
 The returned number of available bytes is a hint, but not a
guarantee, that it is possible to use most or any of these bytes.  The
number of usable bytes is most likely to be accurate immediately
after the space attributes are obtained. It is likely to be made inaccurate
by any external I/O operations including those made on the system outside
of this Java virtual machine.
Throws:
IOException – 
         if an I/O error occurs
Returns:
 the number of bytes available/**
     * Returns the number of bytes available to this Java virtual machine on the
     * file store.
     *
     * <p> The returned number of available bytes is a hint, but not a
     * guarantee, that it is possible to use most or any of these bytes.  The
     * number of usable bytes is most likely to be accurate immediately
     * after the space attributes are obtained. It is likely to be made inaccurate
     * by any external I/O operations including those made on the system outside
     * of this Java virtual machine.
     *
     * @return  the number of bytes available
     *
     * @throws  IOException
     *          if an I/O error occurs
     */
    public abstract long getUsableSpace() throws IOException;

    
Returns the number of bytes per block in this file store.
 File storage is typically organized into discrete sequences of bytes
called blocks. A block is the smallest storage unit of a file store.
Every read and write operation is performed on a multiple of blocks.
Throws:
IOException – 
         if an I/O error occurs
UnsupportedOperationException – 
         if the operation is not supported
Implementation Requirements:
The implementation in this class throws an UnsupportedOperationException.
Returns:
 a positive value representing the block size of this file store,
         in bytes
Since:
10/**
     * Returns the number of bytes per block in this file store.
     *
     * <p> File storage is typically organized into discrete sequences of bytes
     * called <i>blocks</i>. A block is the smallest storage unit of a file store.
     * Every read and write operation is performed on a multiple of blocks.
     *
     * @implSpec The implementation in this class throws an
     *         {@code UnsupportedOperationException}.
     *
     * @return  a positive value representing the block size of this file store,
     *          in bytes
     *
     * @throws  IOException
     *          if an I/O error occurs
     *
     * @throws  UnsupportedOperationException
     *          if the operation is not supported
     *
     * @since 10
     */
    public long getBlockSize() throws IOException {
        throw new UnsupportedOperationException();
    }

    
Returns the number of unallocated bytes in the file store.
 The returned number of unallocated bytes is a hint, but not a
guarantee, that it is possible to use most or any of these bytes.  The
number of unallocated bytes is most likely to be accurate immediately
after the space attributes are obtained. It is likely to be
made inaccurate by any external I/O operations including those made on
the system outside of this virtual machine.
Throws:
IOException – 
         if an I/O error occurs
Returns:
 the number of unallocated bytes/**
     * Returns the number of unallocated bytes in the file store.
     *
     * <p> The returned number of unallocated bytes is a hint, but not a
     * guarantee, that it is possible to use most or any of these bytes.  The
     * number of unallocated bytes is most likely to be accurate immediately
     * after the space attributes are obtained. It is likely to be
     * made inaccurate by any external I/O operations including those made on
     * the system outside of this virtual machine.
     *
     * @return  the number of unallocated bytes
     *
     * @throws  IOException
     *          if an I/O error occurs
     */
    public abstract long getUnallocatedSpace() throws IOException;

    
Tells whether or not this file store supports the file attributes
identified by the given file attribute view.
 Invoking this method to test if the file store supports BasicFileAttributeView will always return true. In the case of the default provider, this method cannot guarantee to give the correct result when the file store is not a local storage device. The reasons for this are implementation specific and therefore unspecified. 
Params:
type – 
         the file attribute view type
Returns:
 true if, and only if, the file attribute view is supported/**
     * Tells whether or not this file store supports the file attributes
     * identified by the given file attribute view.
     *
     * <p> Invoking this method to test if the file store supports {@link
     * BasicFileAttributeView} will always return {@code true}. In the case of
     * the default provider, this method cannot guarantee to give the correct
     * result when the file store is not a local storage device. The reasons for
     * this are implementation specific and therefore unspecified.
     *
     * @param   type
     *          the file attribute view type
     *
     * @return  {@code true} if, and only if, the file attribute view is
     *          supported
     */
    public abstract boolean supportsFileAttributeView(Class<? extends FileAttributeView> type);

    
Tells whether or not this file store supports the file attributes
identified by the given file attribute view.
 Invoking this method to test if the file store supports BasicFileAttributeView, identified by the name "basic" will always return true. In the case of the default provider, this method cannot guarantee to give the correct result when the file store is not a local storage device. The reasons for this are implementation specific and therefore unspecified. 
Params:
name –  the name of file attribute view
Returns:
 true if, and only if, the file attribute view is supported/**
     * Tells whether or not this file store supports the file attributes
     * identified by the given file attribute view.
     *
     * <p> Invoking this method to test if the file store supports {@link
     * BasicFileAttributeView}, identified by the name "{@code basic}" will
     * always return {@code true}. In the case of the default provider, this
     * method cannot guarantee to give the correct result when the file store is
     * not a local storage device. The reasons for this are implementation
     * specific and therefore unspecified.
     *
     * @param   name
     *          the {@link FileAttributeView#name name} of file attribute view
     *
     * @return  {@code true} if, and only if, the file attribute view is
     *          supported
     */
    public abstract boolean supportsFileAttributeView(String name);

    
Returns a FileStoreAttributeView of the given type. 
 This method is intended to be used where the file store attribute view defines type-safe methods to read or update the file store attributes. The type parameter is the type of the attribute view required and the method returns an instance of that type if supported. 
Params:
type –  the Class object corresponding to the attribute view
Type parameters:
<V> –  The FileStoreAttributeView type
Returns:
 a file store attribute view of the specified type or null if the attribute view is not available/**
     * Returns a {@code FileStoreAttributeView} of the given type.
     *
     * <p> This method is intended to be used where the file store attribute
     * view defines type-safe methods to read or update the file store attributes.
     * The {@code type} parameter is the type of the attribute view required and
     * the method returns an instance of that type if supported.
     *
     * @param   <V>
     *          The {@code FileStoreAttributeView} type
     * @param   type
     *          the {@code Class} object corresponding to the attribute view
     *
     * @return  a file store attribute view of the specified type or
     *          {@code null} if the attribute view is not available
     */
    public abstract <V extends FileStoreAttributeView> V
        getFileStoreAttributeView(Class<V> type);

    
Reads the value of a file store attribute.
 The attribute parameter identifies the attribute to be read and takes the form: 

view-name:attribute-name
 where the character ':' stands for itself. 
 view-name is the name of a AttributeView that identifies a set of file attributes. attribute-name is the name of the attribute.
 Usage Example:
Suppose we want to know if ZFS compression is enabled (assuming the "zfs"
view is supported):
   boolean compression = (Boolean)fs.getAttribute("zfs:compression");

Params:
attribute – 
         the attribute to read
Throws:
UnsupportedOperationException – 
         if the attribute view is not available or it does not support
         reading the attribute
IOException – 
         if an I/O error occurs
Returns:
 the attribute value; null may be valid for some attributes/**
     * Reads the value of a file store attribute.
     *
     * <p> The {@code attribute} parameter identifies the attribute to be read
     * and takes the form:
     * <blockquote>
     * <i>view-name</i><b>:</b><i>attribute-name</i>
     * </blockquote>
     * where the character {@code ':'} stands for itself.
     *
     * <p> <i>view-name</i> is the {@link FileStoreAttributeView#name name} of
     * a {@link FileStore AttributeView} that identifies a set of file attributes.
     * <i>attribute-name</i> is the name of the attribute.
     *
     * <p> <b>Usage Example:</b>
     * Suppose we want to know if ZFS compression is enabled (assuming the "zfs"
     * view is supported):
     * <pre>
     *    boolean compression = (Boolean)fs.getAttribute("zfs:compression");
     * </pre>
     *
     * @param   attribute
     *          the attribute to read

     * @return  the attribute value; {@code null} may be valid for some
     *          attributes
     *
     * @throws  UnsupportedOperationException
     *          if the attribute view is not available or it does not support
     *          reading the attribute
     * @throws  IOException
     *          if an I/O error occurs
     */
    public abstract Object getAttribute(String attribute) throws IOException;
}