View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    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 }