View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.vfs2;
18  
19  import java.io.Closeable;
20  import java.io.IOException;
21  import java.io.InputStream;
22  import java.io.OutputStream;
23  import java.nio.charset.Charset;
24  import java.security.cert.Certificate;
25  import java.util.Map;
26  
27  import org.apache.commons.vfs2.util.RandomAccessMode;
28  
29  /**
30   * Represents the data content of a file.
31   * <p>
32   * To read from a file, use the {@code InputStream} returned by {@link #getInputStream()}.
33   * </p>
34   * <p>
35   * To write to a file, use the {@code OutputStream} returned by {@link #getOutputStream()} method. This will create the
36   * file, and the parent folder, if necessary.
37   * </p>
38   * <p>
39   * A file may have multiple InputStreams open at the same time.
40   * </p>
41   *
42   * @see FileObject#getContent
43   */
44  public interface FileContent extends Closeable {
45  
46      /**
47       * Closes all resources used by the content, including any open stream. Commits pending changes to the file.
48       * <p>
49       * This method is a hint to the implementation that it can release resources. This object can continue to be used
50       * after calling this method.
51       * </p>
52       *
53       * @throws FileSystemException if an error occurs closing the file.
54       */
55      @Override
56      void close() throws FileSystemException;
57  
58      /**
59       * Gets the value of an attribute of the file's content.
60       *
61       * @param attrName The name of the attribute. Attribute names are case insensitive.
62       * @return The value of the attribute, or null if the attribute value is unknown.
63       * @throws FileSystemException If the file does not exist, or does not support attributes.
64       */
65      Object getAttribute(String attrName) throws FileSystemException;
66  
67      /**
68       * Lists the attributes of the file's content.
69       *
70       * @return The names of the attributes. Never returns null;
71       * @throws FileSystemException If the file does not exist, or does not support attributes.
72       */
73      String[] getAttributeNames() throws FileSystemException;
74  
75      /**
76       * Returns a read-only map of this file's attributes.
77       *
78       * @return The attribute Map.
79       * @throws FileSystemException If the file does not exist, or does not support attributes.
80       */
81      Map<String, Object> getAttributes() throws FileSystemException;
82  
83      /**
84       * Retrieves the certificates if any used to sign this file or folder.
85       *
86       * @return The certificates, or an empty array if there are no certificates or the file does not support signing.
87       * @throws FileSystemException If the file does not exist, or is being written.
88       */
89      Certificate[] getCertificates() throws FileSystemException;
90  
91      /**
92       * get the content info. e.g. type, encoding, ...
93       *
94       * @return the FileContentInfo
95       * @throws FileSystemException if an error occurs.
96       */
97      FileContentInfo getContentInfo() throws FileSystemException;
98  
99      /**
100      * Returns the file which this is the content of.
101      *
102      * @return The FileObject this is the content of.
103      */
104     FileObject getFile();
105 
106     /**
107      * Returns an input stream for reading the file's content.
108      * <p>
109      * There may only be a single input or output stream open for the file at any time.
110      * </p>
111      *
112      * @return An input stream to read the file's content from. The input stream is buffered, so there is no need to
113      *         wrap it in a {@code BufferedInputStream}.
114      * @throws FileSystemException If the file does not exist, or is being read, or is being written, or on error
115      *             opening the stream.
116      */
117     InputStream getInputStream() throws FileSystemException;
118 
119     /**
120      * Returns the content of a file as a byte array.
121      *
122      * @return The content as a byte array.
123      * @throws IOException if the file content cannot be accessed.
124      * @since 2.4
125      */
126     default byte[] getByteArray() throws IOException {
127         final long sizeL = getSize();
128         if (sizeL > Integer.MAX_VALUE) {
129             throw new IllegalStateException(String.format("File content is too large for a byte array: %,d", sizeL));
130         }
131         final int size = (int) sizeL;
132         final byte[] buf = new byte[size];
133         try (final InputStream in = getInputStream(size)) {
134             int read = 0;
135             for (int pos = 0; pos < size && read >= 0; pos += read) {
136                 read = in.read(buf, pos, size - pos);
137             }
138         }
139         return buf;
140     }
141 
142     /**
143      * Returns an input stream for reading the file's content.
144      * <p>
145      * There may only be a single input or output stream open for the file at any time.
146      * </p>
147      *
148      * @param bufferSize The buffer size to use.
149      * @return An input stream to read the file's content from. The input stream is buffered, so there is no need to
150      *         wrap it in a {@code BufferedInputStream}.
151      * @throws FileSystemException If the file does not exist, or is being read, or is being written, or on error
152      *             opening the stream.
153      * @since 2.4
154      */
155     default InputStream getInputStream(int bufferSize) throws FileSystemException {
156         return getInputStream();
157     }
158 
159     /**
160      * Determines the last-modified timestamp of the file.
161      *
162      * @return The last-modified timestamp.
163      * @throws FileSystemException If the file does not exist, or is being written to, or on error determining the
164      *             last-modified timestamp.
165      */
166     long getLastModifiedTime() throws FileSystemException;
167 
168     /**
169      * Returns an output stream for writing the file's content.
170      * <p>
171      * If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist,
172      * it is replaced with whatever is written to the output stream.
173      * </p>
174      * <p>
175      * There may only be a single input or output stream open for the file at any time.
176      * </p>
177      *
178      * @return An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it
179      *         in a {@code BufferedOutputStream}.
180      * @throws FileSystemException If the file is read-only, or is being read, or is being written, or on error opening
181      *             the stream.
182      */
183     OutputStream getOutputStream() throws FileSystemException;
184 
185     /**
186      * Returns an output stream for writing the file's content.
187      * <p>
188      * If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist,
189      * it is replaced with whatever is written to the output stream.
190      * </p>
191      * <p>
192      * There may only be a single input or output stream open for the file at any time.
193      * </p>
194      *
195      * @param bAppend true if you would like to append to the file. This may not be supported by all implementations.
196      * @return An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it
197      *         in a {@code BufferedOutputStream}.
198      * @throws FileSystemException If the file is read-only, or is being read, or is being written, or bAppend is true
199      *             and the implementation does not support it, or on error opening the stream.
200      */
201     OutputStream getOutputStream(boolean bAppend) throws FileSystemException;
202 
203     /**
204      * Returns an output stream for writing the file's content.
205      * <p>
206      * If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist,
207      * it is replaced with whatever is written to the output stream.
208      * </p>
209      * <p>
210      * There may only be a single input or output stream open for the file at any time.
211      * </p>
212      *
213      * @param bAppend true if you would like to append to the file. This may not be supported by all implementations.
214      * @param bufferSize The buffer size to use.
215      * @return An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it
216      *         in a {@code BufferedOutputStream}.
217      * @throws FileSystemException If the file is read-only, or is being read, or is being written, or bAppend is true
218      *             and the implementation does not support it, or on error opening the stream.
219      * @since 2.4
220      */
221     default OutputStream getOutputStream(boolean bAppend, int bufferSize) throws FileSystemException {
222         return getOutputStream(bAppend);
223     }
224 
225     /**
226      * Returns an output stream for writing the file's content.
227      * <p>
228      * If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist,
229      * it is replaced with whatever is written to the output stream.
230      * </p>
231      * <p>
232      * There may only be a single input or output stream open for the file at any time.
233      * </p>
234      *
235      * @param bufferSize The buffer size to use.
236      * @return An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it
237      *         in a {@code BufferedOutputStream}.
238      * @throws FileSystemException If the file is read-only, or is being read, or is being written, or bAppend is true
239      *             and the implementation does not support it, or on error opening the stream.
240      * @since 2.4
241      */
242     default OutputStream getOutputStream(int bufferSize) throws FileSystemException {
243         return getOutputStream();
244     }
245 
246     /**
247      * Returns an stream for reading/writing the file's content.
248      * <p>
249      * If the file does not exist, and you use one of the write* methods, this method creates it, and the parent folder,
250      * if necessary. If the file does exist, parts of the file are replaced with whatever is written at a given
251      * position.
252      * </p>
253      * <p>
254      * There may only be a single input or output stream open for the file at any time.
255      * </p>
256      *
257      * @param mode The mode to use to access the file.
258      * @return the stream for reading and writing the file's content.
259      * @throws FileSystemException If the file is read-only, or is being read, or is being written, or on error opening
260      *             the stream.
261      */
262     RandomAccessContent getRandomAccessContent(final RandomAccessMode mode) throws FileSystemException;
263 
264     /**
265      * Determines the size of the file, in bytes.
266      *
267      * @return The size of the file, in bytes.
268      * @throws FileSystemException If the file does not exist, or is being written to, or on error determining the size.
269      */
270     long getSize() throws FileSystemException;
271 
272     /**
273      * Returns the content of a file as a String.
274      *
275      * @param charset The file character set, may be null.
276      * @return The content as a byte array.
277      * @throws IOException if the file content cannot be accessed.
278      * @since 2.4
279      */
280     default String getString(final Charset charset) throws IOException {
281         return new String(getByteArray(), charset == null ? Charset.defaultCharset() : charset);
282     }
283 
284     /**
285      * Returns the content of a file as a String.
286      *
287      * @param charset The file character set, may be null.
288      * @return The content as a byte array.
289      * @throws IOException if the file content cannot be accessed.
290      * @since 2.4
291      */
292     default String getString(final String charset) throws IOException {
293         return new String(getByteArray(), charset == null ? Charset.defaultCharset().name() : charset);
294     }
295 
296     /**
297      * Checks if an attribute of the file's content exists.
298      *
299      * @param attrName The name of the attribute.
300      * @return true if the attribute exists, false otherwise.
301      * @throws FileSystemException If the file does not exist, or does not support attributes.
302      */
303     boolean hasAttribute(String attrName) throws FileSystemException;
304 
305     /**
306      * check if this file has open streams.
307      *
308      * @return true if the file is open, false otherwise.
309      */
310     boolean isOpen();
311 
312     /**
313      * Removes the value of an attribute of the file's content.
314      *
315      * @param attrName The name of the attribute.
316      * @throws FileSystemException If the file does not exist, or is read-only, or does not support attributes, or on
317      *             error removing the attribute.
318      */
319     void removeAttribute(String attrName) throws FileSystemException;
320 
321     /**
322      * Sets the value of an attribute of the file's content. Creates the file if it does not exist.
323      *
324      * @param attrName The name of the attribute.
325      * @param value The value of the attribute.
326      * @throws FileSystemException If the file does not exist, or is read-only, or does not support attributes, or on
327      *             error setting the attribute.
328      */
329     void setAttribute(String attrName, Object value) throws FileSystemException;
330 
331     /**
332      * Sets the last-modified timestamp of the file. Creates the file if it does not exist.
333      *
334      * @param modTime The time to set the last-modified timestamp to.
335      * @throws FileSystemException If the file is read-only, or is being written to, or on error setting the
336      *             last-modified timestamp.
337      */
338     void setLastModifiedTime(long modTime) throws FileSystemException;
339 
340     /**
341      * Writes this content to another FileContent.
342      *
343      * @param output The target OutputStream.
344      * @throws IOException if an error occurs writing the content.
345      * @return the total number of bytes written
346      * @since 2.1
347      */
348     long write(FileContent output) throws IOException;
349 
350     /**
351      * Writes this content to another FileObject.
352      *
353      * @param file The target FileObject.
354      * @throws IOException if an error occurs writing the content.
355      * @return the total number of bytes written
356      * @since 2.1
357      */
358     long write(FileObject file) throws IOException;
359 
360     /**
361      * Writes this content to an OutputStream.
362      *
363      * @param output The target OutputStream.
364      * @return the total number of bytes written
365      * @throws IOException if an error occurs writing the content.
366      * @since 2.1
367      */
368     long write(OutputStream output) throws IOException;
369 
370     /**
371      * Writes this content to an OutputStream.
372      *
373      * @param output The target OutputStream.
374      * @param bufferSize The buffer size to write data chunks.
375      * @return the total number of bytes written
376      * @throws IOException if an error occurs writing the file.
377      * @since 2.1
378      */
379     long write(OutputStream output, int bufferSize) throws IOException;
380 
381 }