1 /*
2  * Copyright (c) 2007, 2017, 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;
27 
28 import java.nio.file.attribute.*;
29 import 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 
46 public abstract class FileStore {
47 
48     /**
49      * Initializes a new instance of this class.
50      */
FileStore()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      */
name()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      */
type()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      */
isReadOnly()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      */
getTotalSpace()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      */
getUsableSpace()112     public abstract long getUsableSpace() throws IOException;
113 
114     /**
115      * Returns the number of bytes per block in this file store.
116      *
117      * <p> File storage is typically organized into discrete sequences of bytes
118      * called <i>blocks</i>. A block is the smallest storage unit of a file store.
119      * Every read and write operation is performed on a multiple of blocks.
120      *
121      * @implSpec The implementation in this class throws an
122      *         {@code UnsupportedOperationException}.
123      *
124      * @return  a positive value representing the block size of this file store,
125      *          in bytes
126      *
127      * @throws  IOException
128      *          if an I/O error occurs
129      *
130      * @throws  UnsupportedOperationException
131      *          if the operation is not supported
132      *
133      * @since 10
134      */
getBlockSize()135     public long getBlockSize() throws IOException {
136         throw new UnsupportedOperationException();
137     }
138 
139     /**
140      * Returns the number of unallocated bytes in the file store.
141      *
142      * <p> The returned number of unallocated bytes is a hint, but not a
143      * guarantee, that it is possible to use most or any of these bytes.  The
144      * number of unallocated bytes is most likely to be accurate immediately
145      * after the space attributes are obtained. It is likely to be
146      * made inaccurate by any external I/O operations including those made on
147      * the system outside of this virtual machine.
148      *
149      * @return  the number of unallocated bytes
150      *
151      * @throws  IOException
152      *          if an I/O error occurs
153      */
getUnallocatedSpace()154     public abstract long getUnallocatedSpace() throws IOException;
155 
156     /**
157      * Tells whether or not this file store supports the file attributes
158      * identified by the given file attribute view.
159      *
160      * <p> Invoking this method to test if the file store supports {@link
161      * BasicFileAttributeView} will always return {@code true}. In the case of
162      * the default provider, this method cannot guarantee to give the correct
163      * result when the file store is not a local storage device. The reasons for
164      * this are implementation specific and therefore unspecified.
165      *
166      * @param   type
167      *          the file attribute view type
168      *
169      * @return  {@code true} if, and only if, the file attribute view is
170      *          supported
171      */
supportsFileAttributeView(Class<? extends FileAttributeView> type)172     public abstract boolean supportsFileAttributeView(Class<? extends FileAttributeView> type);
173 
174     /**
175      * Tells whether or not this file store supports the file attributes
176      * identified by the given file attribute view.
177      *
178      * <p> Invoking this method to test if the file store supports {@link
179      * BasicFileAttributeView}, identified by the name "{@code basic}" will
180      * always return {@code true}. In the case of the default provider, this
181      * method cannot guarantee to give the correct result when the file store is
182      * not a local storage device. The reasons for this are implementation
183      * specific and therefore unspecified.
184      *
185      * @param   name
186      *          the {@link FileAttributeView#name name} of file attribute view
187      *
188      * @return  {@code true} if, and only if, the file attribute view is
189      *          supported
190      */
supportsFileAttributeView(String name)191     public abstract boolean supportsFileAttributeView(String name);
192 
193     /**
194      * Returns a {@code FileStoreAttributeView} of the given type.
195      *
196      * <p> This method is intended to be used where the file store attribute
197      * view defines type-safe methods to read or update the file store attributes.
198      * The {@code type} parameter is the type of the attribute view required and
199      * the method returns an instance of that type if supported.
200      *
201      * @param   <V>
202      *          The {@code FileStoreAttributeView} type
203      * @param   type
204      *          the {@code Class} object corresponding to the attribute view
205      *
206      * @return  a file store attribute view of the specified type or
207      *          {@code null} if the attribute view is not available
208      */
209     public abstract <V extends FileStoreAttributeView> V
getFileStoreAttributeView(Class<V> type)210         getFileStoreAttributeView(Class<V> type);
211 
212     /**
213      * Reads the value of a file store attribute.
214      *
215      * <p> The {@code attribute} parameter identifies the attribute to be read
216      * and takes the form:
217      * <blockquote>
218      * <i>view-name</i><b>:</b><i>attribute-name</i>
219      * </blockquote>
220      * where the character {@code ':'} stands for itself.
221      *
222      * <p> <i>view-name</i> is the {@link FileStoreAttributeView#name name} of
223      * a {@link FileStore AttributeView} that identifies a set of file attributes.
224      * <i>attribute-name</i> is the name of the attribute.
225      *
226      * <p> <b>Usage Example:</b>
227      * Suppose we want to know if ZFS compression is enabled (assuming the "zfs"
228      * view is supported):
229      * <pre>
230      *    boolean compression = (Boolean)fs.getAttribute("zfs:compression");
231      * </pre>
232      *
233      * @param   attribute
234      *          the attribute to read
235 
236      * @return  the attribute value; {@code null} may be valid for some
237      *          attributes
238      *
239      * @throws  UnsupportedOperationException
240      *          if the attribute view is not available or it does not support
241      *          reading the attribute
242      * @throws  IOException
243      *          if an I/O error occurs
244      */
getAttribute(String attribute)245     public abstract Object getAttribute(String attribute) throws IOException;
246 }
247