/*
 * Copyright 2002-2005 The Apache Software Foundation.
 * 
 * Licensed 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.vfs;

import org.apache.commons.vfs.util.RandomAccessMode;

import java.io.InputStream;
import java.io.OutputStream;
import java.security.cert.Certificate;
import java.util.Map;

/**
 * Represents the data content of a file.
 * <p/>
 * <p>To read from a file, use the <code>InputStream</code> returned by
 * {@link #getInputStream}.
 * <p/>
 * <p>To write to a file, use the <code>OutputStream</code> 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 sametime.
 * <p/>
 *
 * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
 * @version $Revision$ $Date$
 * @see FileObject#getContent
 */
public interface FileContent
{
    /**
     * Returns the file which 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;

    /**
     * Returns a read-only map of this file's attributes.
     *
     * @throws FileSystemException If the file does not exist, or does not support attributes.
     */
    Map 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;

    /**
     * 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/>
     * <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</code>.
     * @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/>
     * <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</code>.
     * @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/>
     * <p>There may only be a single input or output stream open for the
     * file at any time.
     *
     * @throws FileSystemException If the file is read-only, or is being read, or is being written,
     *                             or on error opening the stream.
     */
    public 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/>
     * <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
     * @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</code>.
     * @throws FileSystemException If the file is read-only, or is being read, or is being written,
     *                             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/>
     * <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.
     */
    void close() throws FileSystemException;


    /**
     * get the content info. e.g. type, encoding, ...
     */
    public FileContentInfo getContentInfo() throws FileSystemException;
}