KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > vfs > 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 JavaDoc;
21 import java.io.OutputStream JavaDoc;
22 import java.security.cert.Certificate JavaDoc;
23 import java.util.Map JavaDoc;
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 JavaDoc 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 JavaDoc[] 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 JavaDoc getAttribute(String JavaDoc 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 JavaDoc attrName, Object JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags