1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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 }