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