FileContent


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