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.fileupload;
    18
    19  import java.io.File;
    20  import java.io.IOException;
    21  import java.io.InputStream;
    22  import java.io.OutputStream;
    23  import java.io.UnsupportedEncodingException;
    24
    25  /**
    26   * <p> This class represents a file or form item that was received within a
    27   * {@code multipart/form-data} POST request.
    28   *
    29   * <p> After retrieving an instance of this class from a {@link
    30   * org.apache.commons.fileupload.FileUpload FileUpload} instance (see
    31   * {@link org.apache.commons.fileupload.servlet.ServletFileUpload
    32   * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may
    33   * either request all contents of the file at once using {@link #get()} or
    34   * request an {@link java.io.InputStream InputStream} with
    35   * {@link #getInputStream()} and process the file without attempting to load
    36   * it into memory, which may come handy with large files.
    37   *
    38   * <p> While this interface does not extend
    39   * {@code javax.activation.DataSource} per se (to avoid a seldom used
    40   * dependency), several of the defined methods are specifically defined with
    41   * the same signatures as methods in that interface. This allows an
    42   * implementation of this interface to also implement
    43   * {@code javax.activation.DataSource} with minimal additional work.
    44   *
    45   * @since 1.3 additionally implements FileItemHeadersSupport
    46   */
    47  public interface FileItem extends FileItemHeadersSupport {
    48
    49      /**
    50       * Deletes the underlying storage for a file item, including deleting any
    51       * associated temporary disk file. Although this storage will be deleted
    52       * automatically when the {@code FileItem} instance is garbage
    53       * collected, this method can be used to ensure that this is done at an
    54       * earlier time, thus preserving system resources.
    55       */
    56      void delete();
    57
    58      /**
    59       * Returns the contents of the file item as an array of bytes.
    60       *
    61       * @return The contents of the file item as an array of bytes.
    62       */
    63      byte[] get();
    64
    65      /**
    66       * Returns the content type passed by the browser or {@code null} if
    67       * not defined.
    68       *
    69       * @return The content type passed by the browser or {@code null} if
    70       *         not defined.
    71       */
    72      String getContentType();
    73
    74      /**
    75       * Returns the name of the field in the multipart form corresponding to
    76       * this file item.
    77       *
    78       * @return The name of the form field.
    79       */
    80      String getFieldName();
    81
    82      /**
    83       * Returns an {@link java.io.InputStream InputStream} that can be
    84       * used to retrieve the contents of the file.
    85       *
    86       * @return An {@link java.io.InputStream InputStream} that can be
    87       *         used to retrieve the contents of the file.
    88       *
    89       * @throws IOException if an error occurs.
    90       */
    91      InputStream getInputStream() throws IOException;
    92
    93      /**
    94       * Returns the original file name in the client's file system, as provided by
    95       * the browser (or other client software). In most cases, this will be the
    96       * base file name, without path information. However, some clients, such as
    97       * the Opera browser, do include path information.
    98       *
    99       * @return The original file name in the client's file system.
    100      * @throws InvalidFileNameException The file name contains a NUL character,
    101      *   which might be an indicator of a security attack. If you intend to
    102      *   use the file name anyways, catch the exception and use
    103      *   InvalidFileNameException#getName().
    104      */
    105     String getName();
    106
    107     /**
    108      * Returns an {@link java.io.OutputStream OutputStream} that can
    109      * be used for storing the contents of the file.
    110      *
    111      * @return An {@link java.io.OutputStream OutputStream} that can be used
    112      *         for storing the contents of the file.
    113      *
    114      * @throws IOException if an error occurs.
    115      */
    116     OutputStream getOutputStream() throws IOException;
    117
    118     /**
    119      * Returns the size of the file item.
    120      *
    121      * @return The size of the file item, in bytes.
    122      */
    123     long getSize();
    124
    125     /**
    126      * Returns the contents of the file item as a String, using the default
    127      * character encoding.  This method uses {@link #get()} to retrieve the
    128      * contents of the item.
    129      *
    130      * @return The contents of the item, as a string.
    131      */
    132     String getString();
    133
    134     /**
    135      * Returns the contents of the file item as a String, using the specified
    136      * encoding.  This method uses {@link #get()} to retrieve the
    137      * contents of the item.
    138      *
    139      * @param encoding The character encoding to use.
    140      * @return The contents of the item, as a string.
    141      * @throws UnsupportedEncodingException if the requested character
    142      *                                      encoding is not available.
    143      */
    144     String getString(String encoding) throws UnsupportedEncodingException;
    145
    146     /**
    147      * Determines whether or not a {@code FileItem} instance represents
    148      * a simple form field.
    149      *
    150      * @return {@code true} if the instance represents a simple form
    151      *         field; {@code false} if it represents an uploaded file.
    152      */
    153     boolean isFormField();
    154
    155     /**
    156      * Provides a hint as to whether or not the file contents will be read
    157      * from memory.
    158      *
    159      * @return {@code true} if the file contents will be read from memory;
    160      *         {@code false} otherwise.
    161      */
    162     boolean isInMemory();
    163
    164     /**
    165      * Sets the field name used to reference this file item.
    166      *
    167      * @param name The name of the form field.
    168      */
    169     void setFieldName(String name);
    170
    171     /**
    172      * Specifies whether or not a {@code FileItem} instance represents
    173      * a simple form field.
    174      *
    175      * @param state {@code true} if the instance represents a simple form
    176      *              field; {@code false} if it represents an uploaded file.
    177      */
    178     void setFormField(boolean state);
    179
    180     /**
    181      * A convenience method to write an uploaded item to disk. The client code
    182      * is not concerned with whether or not the item is stored in memory, or on
    183      * disk in a temporary location. They just want to write the uploaded item
    184      * to a file.
    185      * <p>
    186      * This method is not guaranteed to succeed if called more than once for
    187      * the same item. This allows a particular implementation to use, for
    188      * example, file renaming, where possible, rather than copying all of the
    189      * underlying data, thus gaining a significant performance benefit.
    190      *
    191      * @param file The {@code File} into which the uploaded item should
    192      *             be stored.
    193      *
    194      * @throws Exception if an error occurs.
    195      */
    196     void write(File file) throws Exception;
    197
    198 }