1/*
2 * Copyright (c) 2007, 2013, 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
26package java.nio.file;
27
28import java.nio.file.attribute.*;
29import java.io.IOException;
30
31/**
32 * Storage for files. A {@code FileStore} represents a storage pool, device,
33 * partition, volume, concrete file system or other implementation specific means
34 * of file storage. The {@code FileStore} for where a file is stored is obtained
35 * by invoking the {@link Files#getFileStore getFileStore} method, or all file
36 * stores can be enumerated by invoking the {@link FileSystem#getFileStores
37 * getFileStores} method.
38 *
39 * <p> In addition to the methods defined by this class, a file store may support
40 * one or more {@link FileStoreAttributeView FileStoreAttributeView} classes
41 * that provide a read-only or updatable view of a set of file store attributes.
42 *
43 * @since 1.7
44 */
45
46public abstract class FileStore {
47
48    /**
49     * Initializes a new instance of this class.
50     */
51    protected FileStore() {
52    }
53
54    /**
55     * Returns the name of this file store. The format of the name is highly
56     * implementation specific. It will typically be the name of the storage
57     * pool or volume.
58     *
59     * <p> The string returned by this method may differ from the string
60     * returned by the {@link Object#toString() toString} method.
61     *
62     * @return  the name of this file store
63     */
64    public abstract String name();
65
66    /**
67     * Returns the <em>type</em> of this file store. The format of the string
68     * returned by this method is highly implementation specific. It may
69     * indicate, for example, the format used or if the file store is local
70     * or remote.
71     *
72     * @return  a string representing the type of this file store
73     */
74    public abstract String type();
75
76    /**
77     * Tells whether this file store is read-only. A file store is read-only if
78     * it does not support write operations or other changes to files. Any
79     * attempt to create a file, open an existing file for writing etc. causes
80     * an {@code IOException} to be thrown.
81     *
82     * @return  {@code true} if, and only if, this file store is read-only
83     */
84    public abstract boolean isReadOnly();
85
86    /**
87     * Returns the size, in bytes, of the file store.
88     *
89     * @return  the size of the file store, in bytes
90     *
91     * @throws  IOException
92     *          if an I/O error occurs
93     */
94    public abstract long getTotalSpace() throws IOException;
95
96    /**
97     * Returns the number of bytes available to this Java virtual machine on the
98     * file store.
99     *
100     * <p> The returned number of available bytes is a hint, but not a
101     * guarantee, that it is possible to use most or any of these bytes.  The
102     * number of usable bytes is most likely to be accurate immediately
103     * after the space attributes are obtained. It is likely to be made inaccurate
104     * by any external I/O operations including those made on the system outside
105     * of this Java virtual machine.
106     *
107     * @return  the number of bytes available
108     *
109     * @throws  IOException
110     *          if an I/O error occurs
111     */
112    public abstract long getUsableSpace() throws IOException;
113
114    /**
115     * Returns the number of unallocated bytes in the file store.
116     *
117     * <p> The returned number of unallocated bytes is a hint, but not a
118     * guarantee, that it is possible to use most or any of these bytes.  The
119     * number of unallocated bytes is most likely to be accurate immediately
120     * after the space attributes are obtained. It is likely to be
121     * made inaccurate by any external I/O operations including those made on
122     * the system outside of this virtual machine.
123     *
124     * @return  the number of unallocated bytes
125     *
126     * @throws  IOException
127     *          if an I/O error occurs
128     */
129    public abstract long getUnallocatedSpace() throws IOException;
130
131    /**
132     * Tells whether or not this file store supports the file attributes
133     * identified by the given file attribute view.
134     *
135     * <p> Invoking this method to test if the file store supports {@link
136     * BasicFileAttributeView} will always return {@code true}. In the case of
137     * the default provider, this method cannot guarantee to give the correct
138     * result when the file store is not a local storage device. The reasons for
139     * this are implementation specific and therefore unspecified.
140     *
141     * @param   type
142     *          the file attribute view type
143     *
144     * @return  {@code true} if, and only if, the file attribute view is
145     *          supported
146     */
147    public abstract boolean supportsFileAttributeView(Class<? extends FileAttributeView> type);
148
149    /**
150     * Tells whether or not this file store supports the file attributes
151     * identified by the given file attribute view.
152     *
153     * <p> Invoking this method to test if the file store supports {@link
154     * BasicFileAttributeView}, identified by the name "{@code basic}" will
155     * always return {@code true}. In the case of the default provider, this
156     * method cannot guarantee to give the correct result when the file store is
157     * not a local storage device. The reasons for this are implementation
158     * specific and therefore unspecified.
159     *
160     * @param   name
161     *          the {@link FileAttributeView#name name} of file attribute view
162     *
163     * @return  {@code true} if, and only if, the file attribute view is
164     *          supported
165     */
166    public abstract boolean supportsFileAttributeView(String name);
167
168    /**
169     * Returns a {@code FileStoreAttributeView} of the given type.
170     *
171     * <p> This method is intended to be used where the file store attribute
172     * view defines type-safe methods to read or update the file store attributes.
173     * The {@code type} parameter is the type of the attribute view required and
174     * the method returns an instance of that type if supported.
175     *
176     * @param   <V>
177     *          The {@code FileStoreAttributeView} type
178     * @param   type
179     *          the {@code Class} object corresponding to the attribute view
180     *
181     * @return  a file store attribute view of the specified type or
182     *          {@code null} if the attribute view is not available
183     */
184    public abstract <V extends FileStoreAttributeView> V
185        getFileStoreAttributeView(Class<V> type);
186
187    /**
188     * Reads the value of a file store attribute.
189     *
190     * <p> The {@code attribute} parameter identifies the attribute to be read
191     * and takes the form:
192     * <blockquote>
193     * <i>view-name</i><b>:</b><i>attribute-name</i>
194     * </blockquote>
195     * where the character {@code ':'} stands for itself.
196     *
197     * <p> <i>view-name</i> is the {@link FileStoreAttributeView#name name} of
198     * a {@link FileStore AttributeView} that identifies a set of file attributes.
199     * <i>attribute-name</i> is the name of the attribute.
200     *
201     * <p> <b>Usage Example:</b>
202     * Suppose we want to know if ZFS compression is enabled (assuming the "zfs"
203     * view is supported):
204     * <pre>
205     *    boolean compression = (Boolean)fs.getAttribute("zfs:compression");
206     * </pre>
207     *
208     * @param   attribute
209     *          the attribute to read
210
211     * @return  the attribute value; {@code null} may be a valid valid for some
212     *          attributes
213     *
214     * @throws  UnsupportedOperationException
215     *          if the attribute view is not available or it does not support
216     *          reading the attribute
217     * @throws  IOException
218     *          if an I/O error occurs
219     */
220    public abstract Object getAttribute(String attribute) throws IOException;
221}
222