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 Path#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 * File stores associated with the default provider support the {@link
43 * FileStoreSpaceAttributeView} to read the space related attributes of the
44 * file store.
45 *
46 * @since 1.7
47 */
48
49 public abstract class FileStore {
50
51 /**
52 * Initializes a new instance of this class.
53 */
54 protected FileStore() {
55 }
56
57 /**
58 * Returns the name of this file store. The format of the name is highly
59 * implementation specific. It will typically be the name of the storage
60 * pool or volume.
61 *
62 * <p> The string returned by this method may differ from the string
63 * returned by the {@link Object#toString() toString} method.
64 *
70 * Returns the <em>type</em> of this file store. The format of the string
71 * returned by this method is highly implementation specific. It may
72 * indicate, for example, the format used or if the file store is local
73 * or remote.
74 *
75 * @return a string representing the type of this file store
76 */
77 public abstract String type();
78
79 /**
80 * Tells whether this file store is read-only. A file store is read-only if
81 * it does not support write operations or other changes to files. Any
82 * attempt to create a file, open an existing file for writing etc. causes
83 * an {@code IOException} to be thrown.
84 *
85 * @return {@code true} if, and only if, this file store is read-only
86 */
87 public abstract boolean isReadOnly();
88
89 /**
90 * Tells whether or not this file store supports the file attributes
91 * identified by the given file attribute view.
92 *
93 * <p> Invoking this method to test if the file store supports {@link
94 * BasicFileAttributeView} will always return {@code true}. In the case of
95 * the default provider, this method cannot guarantee to give the correct
96 * result when the file store is not a local storage device. The reasons for
97 * this are implementation specific and therefore unspecified.
98 *
99 * @param type
100 * the file attribute view type
101 *
102 * @return {@code true} if, and only if, the file attribute view is
103 * supported
104 */
105 public abstract boolean supportsFileAttributeView(Class<? extends FileAttributeView> type);
106
107 /**
108 * Tells whether or not this file store supports the file attributes
109 * identified by the given file attribute view.
114 * method cannot guarantee to give the correct result when the file store is
115 * not a local storage device. The reasons for this are implementation
116 * specific and therefore unspecified.
117 *
118 * @param name
119 * the {@link FileAttributeView#name name} of file attribute view
120 *
121 * @return {@code true} if, and only if, the file attribute view is
122 * supported
123 */
124 public abstract boolean supportsFileAttributeView(String name);
125
126 /**
127 * Returns a {@code FileStoreAttributeView} of the given type.
128 *
129 * <p> This method is intended to be used where the file store attribute
130 * view defines type-safe methods to read or update the file store attributes.
131 * The {@code type} parameter is the type of the attribute view required and
132 * the method returns an instance of that type if supported.
133 *
134 * <p> For {@code FileStore} objects created by the default provider, then
135 * the file stores support the {@link FileStoreSpaceAttributeView} that
136 * provides access to space attributes. In that case invoking this method
137 * with a parameter value of {@code FileStoreSpaceAttributeView.class} will
138 * always return an instance of that class.
139 *
140 * @param type
141 * the {@code Class} object corresponding to the attribute view
142 *
143 * @return a file store attribute view of the specified type or
144 * {@code null} if the attribute view is not available
145 */
146 public abstract <V extends FileStoreAttributeView> V
147 getFileStoreAttributeView(Class<V> type);
148
149 /**
150 * Reads the value of a file store attribute.
151 *
152 * <p> The {@code attribute} parameter identifies the attribute to be read
153 * and takes the form:
154 * <blockquote>
155 * <i>view-name</i><b>:</b><i>attribute-name</i>
156 * </blockquote>
157 * where the character {@code ':'} stands for itself.
158 *
159 * <p> <i>view-name</i> is the {@link FileStoreAttributeView#name name} of
160 * a {@link FileStore AttributeView} that identifies a set of file attributes.
161 * <i>attribute-name</i> is the name of the attribute.
162 *
163 * <p> For {@code FileStore} objects created by the default provider, then
164 * the file stores support the {@link FileStoreSpaceAttributeView} that
165 * provides access to space attributes.
166 *
167 * <p> <b>Usage Example:</b>
168 * Suppose we want to know if ZFS compression is enabled (assuming the "zfs"
169 * view is supported):
170 * <pre>
171 * boolean compression = (Boolean)fs.getAttribute("zfs:compression");
172 * </pre>
173 *
174 * @param attribute
175 * the attribute to read
176
177 * @return the attribute value; {@code null} may be a valid valid for some
178 * attributes
179 *
180 * @throws UnsupportedOperationException
181 * if the attribute view is not available or it does not support
182 * reading the attribute
183 * @throws IOException
184 * if an I/O error occurs
185 */
186 public abstract Object getAttribute(String attribute) throws IOException;
|
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 */
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 *
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.
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 type
177 * the {@code Class} object corresponding to the attribute view
178 *
179 * @return a file store attribute view of the specified type or
180 * {@code null} if the attribute view is not available
181 */
182 public abstract <V extends FileStoreAttributeView> V
183 getFileStoreAttributeView(Class<V> type);
184
185 /**
186 * Reads the value of a file store attribute.
187 *
188 * <p> The {@code attribute} parameter identifies the attribute to be read
189 * and takes the form:
190 * <blockquote>
191 * <i>view-name</i><b>:</b><i>attribute-name</i>
192 * </blockquote>
193 * where the character {@code ':'} stands for itself.
194 *
195 * <p> <i>view-name</i> is the {@link FileStoreAttributeView#name name} of
196 * a {@link FileStore AttributeView} that identifies a set of file attributes.
197 * <i>attribute-name</i> is the name of the attribute.
198 *
199 * <p> <b>Usage Example:</b>
200 * Suppose we want to know if ZFS compression is enabled (assuming the "zfs"
201 * view is supported):
202 * <pre>
203 * boolean compression = (Boolean)fs.getAttribute("zfs:compression");
204 * </pre>
205 *
206 * @param attribute
207 * the attribute to read
208
209 * @return the attribute value; {@code null} may be a valid valid for some
210 * attributes
211 *
212 * @throws UnsupportedOperationException
213 * if the attribute view is not available or it does not support
214 * reading the attribute
215 * @throws IOException
216 * if an I/O error occurs
217 */
218 public abstract Object getAttribute(String attribute) throws IOException;
|