001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.commons.vfs;
018:
019: import org.apache.commons.vfs.util.RandomAccessMode;
020:
021: import java.io.InputStream;
022: import java.io.OutputStream;
023: import java.security.cert.Certificate;
024: import java.util.Map;
025:
026: /**
027: * Represents the data content of a file.
028: * <p/>
029: * <p>To read from a file, use the <code>InputStream</code> returned by
030: * {@link #getInputStream}.
031: * <p/>
032: * <p>To write to a file, use the <code>OutputStream</code> returned by
033: * {@link #getOutputStream} method. This will create the file, and the parent
034: * folder, if necessary.
035: * <p/>
036: * <p>A file may have multiple InputStreams open at the sametime.
037: * <p/>
038: *
039: * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
040: * @version $Revision: 537943 $ $Date: 2007-05-14 11:37:14 -0700 (Mon, 14 May 2007) $
041: * @see FileObject#getContent
042: */
043: public interface FileContent {
044: /**
045: * Returns the file which this is the content of.
046: */
047: FileObject getFile();
048:
049: /**
050: * Determines the size of the file, in bytes.
051: *
052: * @return The size of the file, in bytes.
053: * @throws FileSystemException If the file does not exist, or is being written to, or on error
054: * determining the size.
055: */
056: long getSize() throws FileSystemException;
057:
058: /**
059: * Determines the last-modified timestamp of the file.
060: *
061: * @return The last-modified timestamp.
062: * @throws FileSystemException If the file does not exist, or is being written to, or on error
063: * determining the last-modified timestamp.
064: */
065: long getLastModifiedTime() throws FileSystemException;
066:
067: /**
068: * Sets the last-modified timestamp of the file. Creates the file if
069: * it does not exist.
070: *
071: * @param modTime The time to set the last-modified timestamp to.
072: * @throws FileSystemException If the file is read-only, or is being written to, or on error
073: * setting the last-modified timestamp.
074: */
075: void setLastModifiedTime(long modTime) throws FileSystemException;
076:
077: /**
078: * Checks if an attribute of the file's content exists.
079: *
080: * @param attrName The name of the attribute.
081: * @throws FileSystemException If the file does not exist, or does not support
082: * attributes.
083: */
084: boolean hasAttribute(String attrName) throws FileSystemException;
085:
086: /**
087: * Returns a read-only map of this file's attributes.
088: *
089: * @throws FileSystemException If the file does not exist, or does not support attributes.
090: */
091: Map getAttributes() throws FileSystemException;
092:
093: /**
094: * Lists the attributes of the file's content.
095: *
096: * @return The names of the attributes. Never returns null;
097: * @throws FileSystemException If the file does not exist, or does not support attributes.
098: */
099: String[] getAttributeNames() throws FileSystemException;
100:
101: /**
102: * Gets the value of an attribute of the file's content.
103: *
104: * @param attrName The name of the attribute. Attribute names are case insensitive.
105: * @return The value of the attribute, or null if the attribute value is
106: * unknown.
107: * @throws FileSystemException If the file does not exist, or does not support attributes.
108: */
109: Object getAttribute(String attrName) throws FileSystemException;
110:
111: /**
112: * Sets the value of an attribute of the file's content. Creates the
113: * file if it does not exist.
114: *
115: * @param attrName The name of the attribute.
116: * @param value The value of the attribute.
117: * @throws FileSystemException If the file does not exist, or is read-only, or does not support
118: * attributes, or on error setting the attribute.
119: */
120: void setAttribute(String attrName, Object value)
121: throws FileSystemException;
122:
123: /**
124: * Removes the value of an attribute of the file's content.
125: *
126: * @param attrName The name of the attribute.
127: * @throws FileSystemException If the file does not exist, or is read-only, or does not support
128: * attributes, or on error removing the attribute.
129: */
130: void removeAttribute(String attrName) throws FileSystemException;
131:
132: /**
133: * Retrieves the certificates if any used to sign this file or folder.
134: *
135: * @return The certificates, or an empty array if there are no certificates or
136: * the file does not support signing.
137: * @throws FileSystemException If the file does not exist, or is being written.
138: */
139: Certificate[] getCertificates() throws FileSystemException;
140:
141: /**
142: * Returns an input stream for reading the file's content.
143: * <p/>
144: * <p>There may only be a single input or output stream open for the
145: * file at any time.
146: *
147: * @return An input stream to read the file's content from. The input
148: * stream is buffered, so there is no need to wrap it in a
149: * <code>BufferedInputStream</code>.
150: * @throws FileSystemException If the file does not exist, or is being read, or is being written,
151: * or on error opening the stream.
152: */
153: InputStream getInputStream() throws FileSystemException;
154:
155: /**
156: * Returns an output stream for writing the file's content.
157: * <p/>
158: * If the file does not exist, this method creates it, and the parent
159: * folder, if necessary. If the file does exist, it is replaced with
160: * whatever is written to the output stream.
161: * <p/>
162: * <p>There may only be a single input or output stream open for the
163: * file at any time.
164: *
165: * @return An output stream to write the file's content to. The stream is
166: * buffered, so there is no need to wrap it in a
167: * <code>BufferedOutputStream</code>.
168: * @throws FileSystemException If the file is read-only, or is being read, or is being written,
169: * or on error opening the stream.
170: */
171: OutputStream getOutputStream() throws FileSystemException;
172:
173: /**
174: * Returns an stream for reading/writing the file's content.
175: * <p/>
176: * If the file does not exist, and you use one of the write* methods,
177: * this method creates it, and the parent folder, if necessary.
178: * If the file does exist, parts of the file are replaced with whatever is written
179: * at a given position.
180: * <p/>
181: * <p>There may only be a single input or output stream open for the
182: * file at any time.
183: *
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: public RandomAccessContent getRandomAccessContent(
188: final RandomAccessMode mode) throws FileSystemException;
189:
190: /**
191: * Returns an output stream for writing the file's content.
192: * <p/>
193: * If the file does not exist, this method creates it, and the parent
194: * folder, if necessary. If the file does exist, it is replaced with
195: * whatever is written to the output stream.
196: * <p/>
197: * <p>There may only be a single input or output stream open for the
198: * file at any time.
199: *
200: * @param bAppend true if you would like to append to the file
201: * @return An output stream to write the file's content to. The stream is
202: * buffered, so there is no need to wrap it in a
203: * <code>BufferedOutputStream</code>.
204: * @throws FileSystemException If the file is read-only, or is being read, or is being written,
205: * or on error opening the stream.
206: */
207: OutputStream getOutputStream(boolean bAppend)
208: throws FileSystemException;
209:
210: /**
211: * Closes all resources used by the content, including any open stream.
212: * Commits pending changes to the file.
213: * <p/>
214: * <p>This method is a hint to the implementation that it can release
215: * resources. This object can continue to be used after calling this
216: * method.
217: */
218: void close() throws FileSystemException;
219:
220: /**
221: * get the content info. e.g. type, encoding, ...
222: */
223: public FileContentInfo getContentInfo() throws FileSystemException;
224:
225: /**
226: * check if this file has open streams
227: */
228: public boolean isOpen();
229: }
|