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.vfs;
18  
19  import org.apache.commons.vfs.util.RandomAccessMode;
20  
21  import java.io.InputStream;
22  import java.io.OutputStream;
23  import java.security.cert.Certificate;
24  import java.util.Map;
25  
26  /***
27   * Represents the data content of a file.
28   * <p/>
29   * <p>To read from a file, use the <code>InputStream</code> returned by
30   * {@link #getInputStream}.
31   * <p/>
32   * <p>To write to a file, use the <code>OutputStream</code> returned by
33   * {@link #getOutputStream} method.  This will create the file, and the parent
34   * folder, if necessary.
35   * <p/>
36   * <p>A file may have multiple InputStreams open at the sametime.
37   * <p/>
38   *
39   * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
40   * @version $Revision: 480428 $ $Date: 2006-11-29 07:15:24 +0100 (Mi, 29 Nov 2006) $
41   * @see FileObject#getContent
42   */
43  public interface FileContent
44  {
45      /***
46       * Returns the file which this is the content of.
47       */
48      FileObject getFile();
49  
50      /***
51       * Determines the size of the file, in bytes.
52       *
53       * @return The size of the file, in bytes.
54       * @throws FileSystemException If the file does not exist, or is being written to, or on error
55       *                             determining the size.
56       */
57      long getSize() throws FileSystemException;
58  
59      /***
60       * Determines the last-modified timestamp of the file.
61       *
62       * @return The last-modified timestamp.
63       * @throws FileSystemException If the file does not exist, or is being written to, or on error
64       *                             determining the last-modified timestamp.
65       */
66      long getLastModifiedTime() throws FileSystemException;
67  
68      /***
69       * Sets the last-modified timestamp of the file.  Creates the file if
70       * it does not exist.
71       *
72       * @param modTime The time to set the last-modified timestamp to.
73       * @throws FileSystemException If the file is read-only, or is being written to, or on error
74       *                             setting the last-modified timestamp.
75       */
76      void setLastModifiedTime(long modTime) throws FileSystemException;
77  
78      /***
79       * Returns a read-only map of this file's attributes.
80       *
81       * @throws FileSystemException If the file does not exist, or does not support attributes.
82       */
83      Map getAttributes() throws FileSystemException;
84  
85      /***
86       * Lists the attributes of the file's content.
87       *
88       * @return The names of the attributes.  Never returns null;
89       * @throws FileSystemException If the file does not exist, or does not support attributes.
90       */
91      String[] getAttributeNames() throws FileSystemException;
92  
93      /***
94       * Gets the value of an attribute of the file's content.
95       *
96       * @param attrName The name of the attribute.  Attribute names are case insensitive.
97       * @return The value of the attribute, or null if the attribute value is
98       *         unknown.
99       * @throws FileSystemException If the file does not exist, or does not support attributes.
100      */
101     Object getAttribute(String attrName) throws FileSystemException;
102 
103     /***
104      * Sets the value of an attribute of the file's content.  Creates the
105      * file if it does not exist.
106      *
107      * @param attrName The name of the attribute.
108      * @param value    The value of the attribute.
109      * @throws FileSystemException If the file does not exist, or is read-only, or does not support
110      *                             attributes, or on error setting the attribute.
111      */
112     void setAttribute(String attrName, Object value)
113         throws FileSystemException;
114 
115     /***
116      * Retrieves the certificates if any used to sign this file or folder.
117      *
118      * @return The certificates, or an empty array if there are no certificates or
119      *         the file does not support signing.
120      * @throws FileSystemException If the file does not exist, or is being written.
121      */
122     Certificate[] getCertificates() throws FileSystemException;
123 
124     /***
125      * Returns an input stream for reading the file's content.
126      * <p/>
127      * <p>There may only be a single input or output stream open for the
128      * file at any time.
129      *
130      * @return An input stream to read the file's content from.  The input
131      *         stream is buffered, so there is no need to wrap it in a
132      *         <code>BufferedInputStream</code>.
133      * @throws FileSystemException If the file does not exist, or is being read, or is being written,
134      *                             or on error opening the stream.
135      */
136     InputStream getInputStream() throws FileSystemException;
137 
138     /***
139      * Returns an output stream for writing the file's content.
140      * <p/>
141      * If the file does not exist, this method creates it, and the parent
142      * folder, if necessary.  If the file does exist, it is replaced with
143      * whatever is written to the output stream.
144      * <p/>
145      * <p>There may only be a single input or output stream open for the
146      * file at any time.
147      *
148      * @return An output stream to write the file's content to.  The stream is
149      *         buffered, so there is no need to wrap it in a
150      *         <code>BufferedOutputStream</code>.
151      * @throws FileSystemException If the file is read-only, or is being read, or is being written,
152      *                             or on error opening the stream.
153      */
154     OutputStream getOutputStream() throws FileSystemException;
155 
156     /***
157      * Returns an stream for reading/writing the file's content.
158      * <p/>
159      * If the file does not exist, and you use one of the write* methods,
160      * this method creates it, and the parent folder, if necessary.
161      * If the file does exist, parts of the file are replaced with whatever is written
162      * at a given position.
163      * <p/>
164      * <p>There may only be a single input or output stream open for the
165      * file at any time.
166      *
167      * @throws FileSystemException If the file is read-only, or is being read, or is being written,
168      *                             or on error opening the stream.
169      */
170     public RandomAccessContent getRandomAccessContent(final RandomAccessMode mode) throws FileSystemException;
171 
172     /***
173      * Returns an output stream for writing the file's content.
174      * <p/>
175      * If the file does not exist, this method creates it, and the parent
176      * folder, if necessary.  If the file does exist, it is replaced with
177      * whatever is written to the output stream.
178      * <p/>
179      * <p>There may only be a single input or output stream open for the
180      * file at any time.
181      *
182      * @param bAppend true if you would like to append to the file
183      * @return An output stream to write the file's content to.  The stream is
184      *         buffered, so there is no need to wrap it in a
185      *         <code>BufferedOutputStream</code>.
186      * @throws FileSystemException If the file is read-only, or is being read, or is being written,
187      *                             or on error opening the stream.
188      */
189     OutputStream getOutputStream(boolean bAppend) throws FileSystemException;
190 
191     /***
192      * Closes all resources used by the content, including any open stream.
193      * Commits pending changes to the file.
194      * <p/>
195      * <p>This method is a hint to the implementation that it can release
196      * resources.  This object can continue to be used after calling this
197      * method.
198      */
199     void close() throws FileSystemException;
200 
201     /***
202      * get the content info. e.g. type, encoding, ...
203      */
204     public FileContentInfo getContentInfo() throws FileSystemException;
205 
206     /***
207      * check if this file has open streams
208      */
209     public boolean isOpen();
210 }