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 */
017package org.apache.commons.vfs2;
018
019import java.io.Closeable;
020import java.io.IOException;
021import java.io.InputStream;
022import java.io.OutputStream;
023import java.security.cert.Certificate;
024import java.util.Map;
025
026import org.apache.commons.vfs2.util.RandomAccessMode;
027
028/**
029 * Represents the data content of a file.
030 * <p>
031 * To read from a file, use the {@code InputStream} returned by {@link #getInputStream()}.
032 * </p>
033 * <p>
034 * To write to a file, use the {@code OutputStream} returned by {@link #getOutputStream()} method. This will create the
035 * file, and the parent folder, if necessary.
036 * </p>
037 * <p>
038 * A file may have multiple InputStreams open at the same time.
039 * </p>
040 *
041 * @see FileObject#getContent
042 */
043public interface FileContent extends Closeable {
044    /**
045     * Returns the file which this is the content of.
046     *
047     * @return The FileObject this is the content of.
048     */
049    FileObject getFile();
050
051    /**
052     * Determines the size of the file, in bytes.
053     *
054     * @return The size of the file, in bytes.
055     * @throws FileSystemException If the file does not exist, or is being written to, or on error determining the size.
056     */
057    long getSize() throws FileSystemException;
058
059    /**
060     * Determines the last-modified timestamp of the file.
061     *
062     * @return The last-modified timestamp.
063     * @throws FileSystemException If the file does not exist, or is being written to, or on error determining the
064     *             last-modified timestamp.
065     */
066    long getLastModifiedTime() throws FileSystemException;
067
068    /**
069     * Sets the last-modified timestamp of the file. Creates the file if 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 setting the
073     *             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     * @return true if the attribute exists, false otherwise.
082     * @throws FileSystemException If the file does not exist, or does not support attributes.
083     */
084    boolean hasAttribute(String attrName) throws FileSystemException;
085
086    /**
087     * Returns a read-only map of this file's attributes.
088     *
089     * @return The attribute Map.
090     * @throws FileSystemException If the file does not exist, or does not support attributes.
091     */
092    Map<String, Object> getAttributes() throws FileSystemException;
093
094    /**
095     * Lists the attributes of the file's content.
096     *
097     * @return The names of the attributes. Never returns null;
098     * @throws FileSystemException If the file does not exist, or does not support attributes.
099     */
100    String[] getAttributeNames() throws FileSystemException;
101
102    /**
103     * Gets the value of an attribute of the file's content.
104     *
105     * @param attrName The name of the attribute. Attribute names are case insensitive.
106     * @return The value of the attribute, or null if the attribute value is 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 file if it does not exist.
113     *
114     * @param attrName The name of the attribute.
115     * @param value The value of the attribute.
116     * @throws FileSystemException If the file does not exist, or is read-only, or does not support attributes, or on
117     *             error setting the attribute.
118     */
119    void setAttribute(String attrName, Object value) throws FileSystemException;
120
121    /**
122     * Removes the value of an attribute of the file's content.
123     *
124     * @param attrName The name of the attribute.
125     * @throws FileSystemException If the file does not exist, or is read-only, or does not support attributes, or on
126     *             error removing the attribute.
127     */
128    void removeAttribute(String attrName) throws FileSystemException;
129
130    /**
131     * Retrieves the certificates if any used to sign this file or folder.
132     *
133     * @return The certificates, or an empty array if there are no certificates or the file does not support signing.
134     * @throws FileSystemException If the file does not exist, or is being written.
135     */
136    Certificate[] getCertificates() throws FileSystemException;
137
138    /**
139     * Returns an input stream for reading the file's content.
140     * <p>
141     * There may only be a single input or output stream open for the file at any time.
142     *
143     * @return An input stream to read the file's content from. The input stream is buffered, so there is no need to
144     *         wrap it in a {@code BufferedInputStream}.
145     * @throws FileSystemException If the file does not exist, or is being read, or is being written, or on error
146     *             opening the stream.
147     */
148    InputStream getInputStream() throws FileSystemException;
149
150    /**
151     * Returns an output stream for writing the file's content.
152     * <p>
153     * If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist,
154     * it is replaced with whatever is written to the output stream.
155     * <p>
156     * There may only be a single input or output stream open for the file at any time.
157     *
158     * @return An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it
159     *         in a {@code BufferedOutputStream}.
160     * @throws FileSystemException If the file is read-only, or is being read, or is being written, or on error opening
161     *             the stream.
162     */
163    OutputStream getOutputStream() throws FileSystemException;
164
165    /**
166     * Returns an stream for reading/writing the file's content.
167     * <p>
168     * If the file does not exist, and you use one of the write* methods, this method creates it, and the parent folder,
169     * if necessary. If the file does exist, parts of the file are replaced with whatever is written at a given
170     * position.
171     * <p>
172     * There may only be a single input or output stream open for the file at any time.
173     *
174     * @param mode The mode to use to access the file.
175     * @return the stream for reading and writing the file's content.
176     * @throws FileSystemException If the file is read-only, or is being read, or is being written, or on error opening
177     *             the stream.
178     */
179    RandomAccessContent getRandomAccessContent(final RandomAccessMode mode) throws FileSystemException;
180
181    /**
182     * Returns an output stream for writing the file's content.
183     * <p>
184     * If the file does not exist, this method creates it, and the parent folder, if necessary. If the file does exist,
185     * it is replaced with whatever is written to the output stream.
186     * <p>
187     * There may only be a single input or output stream open for the file at any time.
188     *
189     * @param bAppend true if you would like to append to the file. This may not be supported by all implementations.
190     * @return An output stream to write the file's content to. The stream is buffered, so there is no need to wrap it
191     *         in a {@code BufferedOutputStream}.
192     * @throws FileSystemException If the file is read-only, or is being read, or is being written, or bAppend is true
193     *             and the implementation does not support it, or on error opening the stream.
194     */
195    OutputStream getOutputStream(boolean bAppend) throws FileSystemException;
196
197    /**
198     * Closes all resources used by the content, including any open stream. Commits pending changes to the file.
199     * <p>
200     * This method is a hint to the implementation that it can release resources. This object can continue to be used
201     * after calling this method.
202     *
203     * @throws FileSystemException if an error occurs closing the file.
204     */
205    @Override
206    void close() throws FileSystemException;
207
208    /**
209     * get the content info. e.g. type, encoding, ...
210     *
211     * @return the FileContentInfo
212     * @throws FileSystemException if an error occurs.
213     */
214    FileContentInfo getContentInfo() throws FileSystemException;
215
216    /**
217     * check if this file has open streams.
218     *
219     * @return true if the file is open, false otherwise.
220     */
221    boolean isOpen();
222
223    /**
224     * Writes this content to another FileContent.
225     *
226     * @param output The target OutputStream.
227     * @throws IOException if an error occurs writing the content.
228     * @return the total number of bytes written
229     * @since 2.1
230     */
231    long write(FileContent output) throws IOException;
232
233    /**
234     * Writes this content to another FileObject.
235     *
236     * @param file The target FileObject.
237     * @throws IOException if an error occurs writing the content.
238     * @return the total number of bytes written
239     * @since 2.1
240     */
241    long write(FileObject file) throws IOException;
242
243    /**
244     * Writes this content to an OutputStream.
245     *
246     * @param output The target OutputStream.
247     * @return the total number of bytes written
248     * @throws IOException if an error occurs writing the content.
249     * @since 2.1
250     */
251    long write(OutputStream output) throws IOException;
252
253    /**
254     * Writes this content to an OutputStream.
255     *
256     * @param output The target OutputStream.
257     * @param bufferSize The buffer size to write data chunks.
258     * @return the total number of bytes written
259     * @throws IOException if an error occurs writing the file.
260     * @since 2.1
261     */
262    long write(OutputStream output, int bufferSize) throws IOException;
263
264}