Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.vfs2; import java.io.Closeable; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.security.cert.Certificate; import java.util.Map; import org.apache.commons.vfs2.util.RandomAccessMode; /** * Represents the data content of a file. * <p> * To read from a file, use the {@code InputStream} returned by {@link #getInputStream()}. * </p> * <p> * To write to a file, use the {@code OutputStream} returned by {@link #getOutputStream()} method. This will create * the file, and the parent folder, if necessary. * </p> * <p> * A file may have multiple InputStreams open at the same time. * </p> * * @see FileObject#getContent */ public interface FileContent extends Closeable { /** * Returns the file which this is the content of. * @return The FileObject this is the content of. */ FileObject getFile(); /** * Determines the size of the file, in bytes. * * @return The size of the file, in bytes. * @throws FileSystemException If the file does not exist, or is being written to, or on error * determining the size. */ long getSize() throws FileSystemException; /** * Determines the last-modified timestamp of the file. * * @return The last-modified timestamp. * @throws FileSystemException If the file does not exist, or is being written to, or on error * determining the last-modified timestamp. */ long getLastModifiedTime() throws FileSystemException; /** * Sets the last-modified timestamp of the file. Creates the file if * it does not exist. * * @param modTime The time to set the last-modified timestamp to. * @throws FileSystemException If the file is read-only, or is being written to, or on error * setting the last-modified timestamp. */ void setLastModifiedTime(long modTime) throws FileSystemException; /** * Checks if an attribute of the file's content exists. * * @param attrName The name of the attribute. * @return true if the attribute exists, false otherwise. * @throws FileSystemException If the file does not exist, or does not support * attributes. */ boolean hasAttribute(String attrName) throws FileSystemException; /** * Returns a read-only map of this file's attributes. * @return The attribute Map. * @throws FileSystemException If the file does not exist, or does not support attributes. */ Map<String, Object> getAttributes() throws FileSystemException; /** * Lists the attributes of the file's content. * * @return The names of the attributes. Never returns null; * @throws FileSystemException If the file does not exist, or does not support attributes. */ String[] getAttributeNames() throws FileSystemException; /** * Gets the value of an attribute of the file's content. * * @param attrName The name of the attribute. Attribute names are case insensitive. * @return The value of the attribute, or null if the attribute value is * unknown. * @throws FileSystemException If the file does not exist, or does not support attributes. */ Object getAttribute(String attrName) throws FileSystemException; /** * Sets the value of an attribute of the file's content. Creates the * file if it does not exist. * * @param attrName The name of the attribute. * @param value The value of the attribute. * @throws FileSystemException If the file does not exist, or is read-only, or does not support * attributes, or on error setting the attribute. */ void setAttribute(String attrName, Object value) throws FileSystemException; /** * Removes the value of an attribute of the file's content. * * @param attrName The name of the attribute. * @throws FileSystemException If the file does not exist, or is read-only, or does not support * attributes, or on error removing the attribute. */ void removeAttribute(String attrName) throws FileSystemException; /** * Retrieves the certificates if any used to sign this file or folder. * * @return The certificates, or an empty array if there are no certificates or * the file does not support signing. * @throws FileSystemException If the file does not exist, or is being written. */ Certificate[] getCertificates() throws FileSystemException; /** * Returns an input stream for reading the file's content. * <p> * There may only be a single input or output stream open for the * file at any time. * * @return An input stream to read the file's content from. The input * stream is buffered, so there is no need to wrap it in a * {@code BufferedInputStream}. * @throws FileSystemException If the file does not exist, or is being read, or is being written, * or on error opening the stream. */ InputStream getInputStream() throws FileSystemException; /** * Returns an output stream for writing the file's content. * <p> * If the file does not exist, this method creates it, and the parent * folder, if necessary. If the file does exist, it is replaced with * whatever is written to the output stream. * <p> * There may only be a single input or output stream open for the * file at any time. * * @return An output stream to write the file's content to. The stream is * buffered, so there is no need to wrap it in a * {@code BufferedOutputStream}. * @throws FileSystemException If the file is read-only, or is being read, or is being written, * or on error opening the stream. */ OutputStream getOutputStream() throws FileSystemException; /** * Returns an stream for reading/writing the file's content. * <p> * If the file does not exist, and you use one of the write* methods, * this method creates it, and the parent folder, if necessary. * If the file does exist, parts of the file are replaced with whatever is written * at a given position. * <p> * There may only be a single input or output stream open for the * file at any time. * * @param mode The mode to use to access the file. * @return the stream for reading and writing the file's content. * @throws FileSystemException If the file is read-only, or is being read, or is being written, * or on error opening the stream. */ RandomAccessContent getRandomAccessContent(final RandomAccessMode mode) throws FileSystemException; /** * Returns an output stream for writing the file's content. * <p> * If the file does not exist, this method creates it, and the parent * folder, if necessary. If the file does exist, it is replaced with * whatever is written to the output stream. * <p> * There may only be a single input or output stream open for the * file at any time. * * @param bAppend true if you would like to append to the file. * This may not be supported by all implementations. * @return An output stream to write the file's content to. The stream is * buffered, so there is no need to wrap it in a * {@code BufferedOutputStream}. * @throws FileSystemException If the file is read-only, or is being read, or is being written, * or bAppend is true and the implementation does not support it, * or on error opening the stream. */ OutputStream getOutputStream(boolean bAppend) throws FileSystemException; /** * Closes all resources used by the content, including any open stream. * Commits pending changes to the file. * <p> * This method is a hint to the implementation that it can release * resources. This object can continue to be used after calling this * method. * * @throws FileSystemException if an error occurs closing the file. */ @Override void close() throws FileSystemException; /** * get the content info. e.g. type, encoding, ... * @return the FileContentInfo * @throws FileSystemException if an error occurs. */ FileContentInfo getContentInfo() throws FileSystemException; /** * check if this file has open streams. * @return true if the file is open, false otherwise. */ boolean isOpen(); /** * Writes this content to another FileContent. * * @param output * The target OutputStream. * @throws IOException * if an error occurs writing the content. * @return the total number of bytes written * @since 2.1 */ long write(FileContent output) throws IOException; /** * Writes this content to another FileObject. * * @param file * The target FileObject. * @throws IOException * if an error occurs writing the content. * @return the total number of bytes written * @since 2.1 */ long write(FileObject file) throws IOException; /** * Writes this content to an OutputStream. * * @param output * The target OutputStream. * @return the total number of bytes written * @throws IOException * if an error occurs writing the content. * @since 2.1 */ long write(OutputStream output) throws IOException; /** * Writes this content to an OutputStream. * * @param output * The target OutputStream. * @param bufferSize * The buffer size to write data chunks. * @return the total number of bytes written * @throws IOException * if an error occurs writing the file. * @since 2.1 */ long write(OutputStream output, int bufferSize) throws IOException; }