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.security.cert.Certificate;
24  import java.util.Map;
25  
26  import org.apache.commons.vfs2.util.RandomAccessMode;
27  
28  /**
29   * Represents the data content of a file.
30   * <p>
31   * To read from a file, use the {@code InputStream} returned by {@link #getInputStream()}.
32   * </p>
33   * <p>
34   * To write to a file, use the {@code OutputStream} returned by {@link #getOutputStream()} method. This will create
35   * the file, and the parent folder, if necessary.
36   * </p>
37   * <p>
38   * A file may have multiple InputStreams open at the same time.
39   * </p>
40   *
41   * @see FileObject#getContent
42   */
43  public interface FileContent extends Closeable
44  {
45      /**
46       * Returns the file which this is the content of.
47       * @return The FileObject this is the content of.
48       */
49      FileObject getFile();
50  
51      /**
52       * Determines the size of the file, in bytes.
53       *
54       * @return The size of the file, in bytes.
55       * @throws FileSystemException If the file does not exist, or is being written to, or on error
56       *                             determining the size.
57       */
58      long getSize() throws FileSystemException;
59  
60      /**
61       * Determines the last-modified timestamp of the file.
62       *
63       * @return The last-modified timestamp.
64       * @throws FileSystemException If the file does not exist, or is being written to, or on error
65       *                             determining the last-modified timestamp.
66       */
67      long getLastModifiedTime() throws FileSystemException;
68  
69      /**
70       * Sets the last-modified timestamp of the file.  Creates the file if
71       * it does not exist.
72       *
73       * @param modTime The time to set the last-modified timestamp to.
74       * @throws FileSystemException If the file is read-only, or is being written to, or on error
75       *                             setting the last-modified timestamp.
76       */
77      void setLastModifiedTime(long modTime) throws FileSystemException;
78  
79      /**
80       * Checks if an attribute of the file's content exists.
81       *
82       * @param attrName The name of the attribute.
83       * @return true if the attribute exists, false otherwise.
84       * @throws FileSystemException If the file does not exist, or does not support
85       *                             attributes.
86       */
87      boolean hasAttribute(String attrName)
88          throws FileSystemException;
89  
90      /**
91       * Returns a read-only map of this file's attributes.
92       * @return The attribute Map.
93       * @throws FileSystemException If the file does not exist, or does not support attributes.
94       */
95      Map<String, Object> getAttributes() throws FileSystemException;
96  
97      /**
98       * Lists the attributes of the file's content.
99       *
100      * @return The names of the attributes.  Never returns null;
101      * @throws FileSystemException If the file does not exist, or does not support attributes.
102      */
103     String[] getAttributeNames() throws FileSystemException;
104 
105     /**
106      * Gets the value of an attribute of the file's content.
107      *
108      * @param attrName The name of the attribute.  Attribute names are case insensitive.
109      * @return The value of the attribute, or null if the attribute value is
110      *         unknown.
111      * @throws FileSystemException If the file does not exist, or does not support attributes.
112      */
113     Object getAttribute(String attrName) throws FileSystemException;
114 
115     /**
116      * Sets the value of an attribute of the file's content.  Creates the
117      * file if it does not exist.
118      *
119      * @param attrName The name of the attribute.
120      * @param value    The value of the attribute.
121      * @throws FileSystemException If the file does not exist, or is read-only, or does not support
122      *                             attributes, or on error setting the attribute.
123      */
124     void setAttribute(String attrName, Object value)
125         throws FileSystemException;
126 
127     /**
128      * Removes the value of an attribute of the file's content.
129      *
130      * @param attrName The name of the attribute.
131      * @throws FileSystemException If the file does not exist, or is read-only, or does not support
132      *                             attributes, or on error removing the attribute.
133      */
134     void removeAttribute(String attrName)
135         throws FileSystemException;
136 
137     /**
138      * Retrieves the certificates if any used to sign this file or folder.
139      *
140      * @return The certificates, or an empty array if there are no certificates or
141      *         the file does not support signing.
142      * @throws FileSystemException If the file does not exist, or is being written.
143      */
144     Certificate[] getCertificates() throws FileSystemException;
145 
146     /**
147      * Returns an input stream for reading the file's content.
148      * <p>
149      * There may only be a single input or output stream open for the
150      * file at any time.
151      *
152      * @return An input stream to read the file's content from.  The input
153      *         stream is buffered, so there is no need to wrap it in a
154      *         {@code BufferedInputStream}.
155      * @throws FileSystemException If the file does not exist, or is being read, or is being written,
156      *                             or on error opening the stream.
157      */
158     InputStream getInputStream() throws FileSystemException;
159 
160     /**
161      * Returns an output stream for writing the file's content.
162      * <p>
163      * If the file does not exist, this method creates it, and the parent
164      * folder, if necessary.  If the file does exist, it is replaced with
165      * whatever is written to the output stream.
166      * <p>
167      * There may only be a single input or output stream open for the
168      * file at any time.
169      *
170      * @return An output stream to write the file's content to.  The stream is
171      *         buffered, so there is no need to wrap it in a
172      *         {@code BufferedOutputStream}.
173      * @throws FileSystemException If the file is read-only, or is being read, or is being written,
174      *                             or on error opening the stream.
175      */
176     OutputStream getOutputStream() throws FileSystemException;
177 
178     /**
179      * Returns an stream for reading/writing the file's content.
180      * <p>
181      * If the file does not exist, and you use one of the write* methods,
182      * this method creates it, and the parent folder, if necessary.
183      * If the file does exist, parts of the file are replaced with whatever is written
184      * at a given position.
185      * <p>
186      * There may only be a single input or output stream open for the
187      * file at any time.
188      *
189      * @param mode The mode to use to access the file.
190      * @return the stream for reading and writing the file's content.
191      * @throws FileSystemException If the file is read-only, or is being read, or is being written,
192      *                             or on error opening the stream.
193      */
194     RandomAccessContent getRandomAccessContent(final RandomAccessMode mode) throws FileSystemException;
195 
196     /**
197      * Returns an output stream for writing the file's content.
198      * <p>
199      * If the file does not exist, this method creates it, and the parent
200      * folder, if necessary.  If the file does exist, it is replaced with
201      * whatever is written to the output stream.
202      * <p>
203      * There may only be a single input or output stream open for the
204      * file at any time.
205      *
206      * @param bAppend true if you would like to append to the file.
207      *        This may not be supported by all implementations.
208      * @return An output stream to write the file's content to.  The stream is
209      *         buffered, so there is no need to wrap it in a
210      *         {@code BufferedOutputStream}.
211      * @throws FileSystemException If the file is read-only, or is being read, or is being written,
212      *                             or bAppend is true and the implementation does not support it,
213      *                             or on error opening the stream.
214      */
215     OutputStream getOutputStream(boolean bAppend) throws FileSystemException;
216 
217     /**
218      * Closes all resources used by the content, including any open stream.
219      * Commits pending changes to the file.
220      * <p>
221      * This method is a hint to the implementation that it can release
222      * resources.  This object can continue to be used after calling this
223      * method.
224      *
225      * @throws FileSystemException if an error occurs closing the file.
226      */
227     @Override
228     void close() throws FileSystemException;
229 
230     /**
231      * get the content info. e.g. type, encoding, ...
232      * @return the FileContentInfo
233      * @throws FileSystemException if an error occurs.
234      */
235     FileContentInfo getContentInfo() throws FileSystemException;
236 
237     /**
238      * check if this file has open streams.
239      * @return true if the file is open, false otherwise.
240      */
241     boolean isOpen();
242 
243     /**
244      * Writes this content to another FileContent.
245      *
246      * @param output
247      *            The target OutputStream.
248      * @throws IOException
249      *             if an error occurs writing the content.
250      * @return the total number of bytes written
251      * @since 2.1
252      */
253     long write(FileContent output) throws IOException;
254 
255     /**
256      * Writes this content to another FileObject.
257      *
258      * @param file
259      *            The target FileObject.
260      * @throws IOException
261      *             if an error occurs writing the content.
262      * @return the total number of bytes written
263      * @since 2.1
264      */
265     long write(FileObject file) throws IOException;
266 
267     /**
268      * Writes this content to an OutputStream.
269      *
270      * @param output
271      *            The target OutputStream.
272      * @return the total number of bytes written
273      * @throws IOException
274      *             if an error occurs writing the content.
275      * @since 2.1
276      */
277     long write(OutputStream output) throws IOException;
278 
279     /**
280      * Writes this content to an OutputStream.
281      *
282      * @param output
283      *            The target OutputStream.
284      * @param bufferSize
285      *            The buffer size to write data chunks.
286      * @return the total number of bytes written
287      * @throws IOException
288      *             if an error occurs writing the file.
289      * @since 2.1
290      */
291     long write(OutputStream output, int bufferSize) throws IOException;
292 
293 }