001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.vfs2; 018 019import java.io.Closeable; 020import java.io.IOException; 021import java.io.InputStream; 022import java.io.OutputStream; 023import java.security.cert.Certificate; 024import java.util.Map; 025 026import org.apache.commons.vfs2.util.RandomAccessMode; 027 028/** 029 * Represents the data content of a file. 030 * <p> 031 * To read from a file, use the {@code InputStream} returned by {@link #getInputStream()}. 032 * </p> 033 * <p> 034 * To write to a file, use the {@code OutputStream} returned by {@link #getOutputStream()} method. This will create the 035 * file, and the parent folder, if necessary. 036 * </p> 037 * <p> 038 * A file may have multiple InputStreams open at the same time. 039 * </p> 040 * 041 * @see FileObject#getContent 042 */ 043public interface FileContent extends Closeable { 044 /** 045 * Returns the file which this is the content of. 046 * 047 * @return The FileObject this is the content of. 048 */ 049 FileObject getFile(); 050 051 /** 052 * Determines the size of the file, in bytes. 053 * 054 * @return The size of the file, in bytes. 055 * @throws FileSystemException If the file does not exist, or is being written to, or on error determining the size. 056 */ 057 long getSize() throws FileSystemException; 058 059 /** 060 * Determines the last-modified timestamp of the file. 061 * 062 * @return The last-modified timestamp. 063 * @throws FileSystemException If the file does not exist, or is being written to, or on error determining the 064 * last-modified timestamp. 065 */ 066 long getLastModifiedTime() throws FileSystemException; 067 068 /** 069 * Sets the last-modified timestamp of the file. Creates the file if it does not exist. 070 * 071 * @param modTime The time to set the last-modified timestamp to. 072 * @throws FileSystemException If the file is read-only, or is being written to, or on error setting the 073 * last-modified timestamp. 074 */ 075 void setLastModifiedTime(long modTime) throws FileSystemException; 076 077 /** 078 * Checks if an attribute of the file's content exists. 079 * 080 * @param attrName The name of the attribute. 081 * @return true if the attribute exists, false otherwise. 082 * @throws FileSystemException If the file does not exist, or does not support attributes. 083 */ 084 boolean hasAttribute(String attrName) throws FileSystemException; 085 086 /** 087 * Returns a read-only map of this file's attributes. 088 * 089 * @return The attribute Map. 090 * @throws FileSystemException If the file does not exist, or does not support attributes. 091 */ 092 Map<String, Object> getAttributes() throws FileSystemException; 093 094 /** 095 * Lists the attributes of the file's content. 096 * 097 * @return The names of the attributes. Never returns null; 098 * @throws FileSystemException If the file does not exist, or does not support attributes. 099 */ 100 String[] getAttributeNames() throws FileSystemException; 101 102 /** 103 * Gets the value of an attribute of the file's content. 104 * 105 * @param attrName The name of the attribute. Attribute names are case insensitive. 106 * @return The value of the attribute, or null if the attribute value is unknown. 107 * @throws FileSystemException If the file does not exist, or does not support attributes. 108 */ 109 Object getAttribute(String attrName) throws FileSystemException; 110 111 /** 112 * Sets the value of an attribute of the file's content. Creates the file if it does not exist. 113 * 114 * @param attrName The name of the attribute. 115 * @param value The value of the attribute. 116 * @throws FileSystemException If the file does not exist, or is read-only, or does not support attributes, or on 117 * error setting the attribute. 118 */ 119 void setAttribute(String attrName, Object value) throws FileSystemException; 120 121 /** 122 * Removes the value of an attribute of the file's content. 123 * 124 * @param attrName The name of the attribute. 125 * @throws FileSystemException If the file does not exist, or is read-only, or does not support attributes, or on 126 * error removing the attribute. 127 */ 128 void removeAttribute(String attrName) throws FileSystemException; 129 130 /** 131 * Retrieves the certificates if any used to sign this file or folder. 132 * 133 * @return The certificates, or an empty array if there are no certificates or the file does not support signing. 134 * @throws FileSystemException If the file does not exist, or is being written. 135 */ 136 Certificate[] getCertificates() throws FileSystemException; 137 138 /** 139 * Returns an input stream for reading the file's content. 140 * <p> 141 * There may only be a single input or output stream open for the file at any time. 142 * 143 * @return An input stream to read the file's content from. The input stream is buffered, so there is no need to 144 * wrap it in a {@code BufferedInputStream}. 145 * @throws FileSystemException If the file does not exist, or is being read, or is being written, or on error 146 * opening the stream. 147 */ 148 InputStream getInputStream() throws FileSystemException; 149 150 /** 151 * Returns an output stream for writing the file's content. 152 * <p> 153 * If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist, 154 * it is replaced with whatever is written to the output stream. 155 * <p> 156 * There may only be a single input or output stream open for the file at any time. 157 * 158 * @return An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it 159 * in a {@code BufferedOutputStream}. 160 * @throws FileSystemException If the file is read-only, or is being read, or is being written, or on error opening 161 * the stream. 162 */ 163 OutputStream getOutputStream() throws FileSystemException; 164 165 /** 166 * Returns an stream for reading/writing the file's content. 167 * <p> 168 * If the file does not exist, and you use one of the write* methods, this method creates it, and the parent folder, 169 * if necessary. If the file does exist, parts of the file are replaced with whatever is written at a given 170 * position. 171 * <p> 172 * There may only be a single input or output stream open for the file at any time. 173 * 174 * @param mode The mode to use to access the file. 175 * @return the stream for reading and writing the file's content. 176 * @throws FileSystemException If the file is read-only, or is being read, or is being written, or on error opening 177 * the stream. 178 */ 179 RandomAccessContent getRandomAccessContent(final RandomAccessMode mode) throws FileSystemException; 180 181 /** 182 * Returns an output stream for writing the file's content. 183 * <p> 184 * If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist, 185 * it is replaced with whatever is written to the output stream. 186 * <p> 187 * There may only be a single input or output stream open for the file at any time. 188 * 189 * @param bAppend true if you would like to append to the file. This may not be supported by all implementations. 190 * @return An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it 191 * in a {@code BufferedOutputStream}. 192 * @throws FileSystemException If the file is read-only, or is being read, or is being written, or bAppend is true 193 * and the implementation does not support it, or on error opening the stream. 194 */ 195 OutputStream getOutputStream(boolean bAppend) throws FileSystemException; 196 197 /** 198 * Closes all resources used by the content, including any open stream. Commits pending changes to the file. 199 * <p> 200 * This method is a hint to the implementation that it can release resources. This object can continue to be used 201 * after calling this method. 202 * 203 * @throws FileSystemException if an error occurs closing the file. 204 */ 205 @Override 206 void close() throws FileSystemException; 207 208 /** 209 * get the content info. e.g. type, encoding, ... 210 * 211 * @return the FileContentInfo 212 * @throws FileSystemException if an error occurs. 213 */ 214 FileContentInfo getContentInfo() throws FileSystemException; 215 216 /** 217 * check if this file has open streams. 218 * 219 * @return true if the file is open, false otherwise. 220 */ 221 boolean isOpen(); 222 223 /** 224 * Writes this content to another FileContent. 225 * 226 * @param output The target OutputStream. 227 * @throws IOException if an error occurs writing the content. 228 * @return the total number of bytes written 229 * @since 2.1 230 */ 231 long write(FileContent output) throws IOException; 232 233 /** 234 * Writes this content to another FileObject. 235 * 236 * @param file The target FileObject. 237 * @throws IOException if an error occurs writing the content. 238 * @return the total number of bytes written 239 * @since 2.1 240 */ 241 long write(FileObject file) throws IOException; 242 243 /** 244 * Writes this content to an OutputStream. 245 * 246 * @param output The target OutputStream. 247 * @return the total number of bytes written 248 * @throws IOException if an error occurs writing the content. 249 * @since 2.1 250 */ 251 long write(OutputStream output) throws IOException; 252 253 /** 254 * Writes this content to an OutputStream. 255 * 256 * @param output The target OutputStream. 257 * @param bufferSize The buffer size to write data chunks. 258 * @return the total number of bytes written 259 * @throws IOException if an error occurs writing the file. 260 * @since 2.1 261 */ 262 long write(OutputStream output, int bufferSize) throws IOException; 263 264}