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 */ 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 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 */ getUnallocatedSpace()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 */ supportsFileAttributeView(Class<? extends FileAttributeView> type)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 */ supportsFileAttributeView(String name)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 getFileStoreAttributeView(Class<V> type)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 */ getAttribute(String attribute)220 public abstract Object getAttribute(String attribute) throws IOException; 221 } 222