    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.fileupload;
    018
    019import java.io.File;
    020import java.io.IOException;
    021import java.io.InputStream;
    022import java.io.OutputStream;
    023import java.io.UnsupportedEncodingException;
    024
    025/**
    026 * <p> This class represents a file or form item that was received within a
    027 * <code>multipart/form-data</code> POST request.
    028 *
    029 * <p> After retrieving an instance of this class from a {@link
    030 * org.apache.commons.fileupload.FileUpload FileUpload} instance (see
    031 * {@link org.apache.commons.fileupload.servlet.ServletFileUpload
    032 * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may
    033 * either request all contents of the file at once using {@link #get()} or
    034 * request an {@link java.io.InputStream InputStream} with
    035 * {@link #getInputStream()} and process the file without attempting to load
    036 * it into memory, which may come handy with large files.
    037 *
    038 * <p> While this interface does not extend
    039 * <code>javax.activation.DataSource</code> per se (to avoid a seldom used
    040 * dependency), several of the defined methods are specifically defined with
    041 * the same signatures as methods in that interface. This allows an
    042 * implementation of this interface to also implement
    043 * <code>javax.activation.DataSource</code> with minimal additional work.
    044 *
    045 * @since 1.3 additionally implements FileItemHeadersSupport
    046 */
    047public interface FileItem extends FileItemHeadersSupport {
    048
    049    // ------------------------------- Methods from javax.activation.DataSource
    050
    051    /**
    052     * Returns an {@link java.io.InputStream InputStream} that can be
    053     * used to retrieve the contents of the file.
    054     *
    055     * @return An {@link java.io.InputStream InputStream} that can be
    056     *         used to retrieve the contents of the file.
    057     *
    058     * @throws IOException if an error occurs.
    059     */
    060    InputStream getInputStream() throws IOException;
    061
    062    /**
    063     * Returns the content type passed by the browser or <code>null</code> if
    064     * not defined.
    065     *
    066     * @return The content type passed by the browser or <code>null</code> if
    067     *         not defined.
    068     */
    069    String getContentType();
    070
    071    /**
    072     * Returns the original filename in the client's filesystem, as provided by
    073     * the browser (or other client software). In most cases, this will be the
    074     * base file name, without path information. However, some clients, such as
    075     * the Opera browser, do include path information.
    076     *
    077     * @return The original filename in the client's filesystem.
    078     * @throws InvalidFileNameException The file name contains a NUL character,
    079     *   which might be an indicator of a security attack. If you intend to
    080     *   use the file name anyways, catch the exception and use
    081     *   InvalidFileNameException#getName().
    082     */
    083    String getName();
    084
    085    // ------------------------------------------------------- FileItem methods
    086
    087    /**
    088     * Provides a hint as to whether or not the file contents will be read
    089     * from memory.
    090     *
    091     * @return <code>true</code> if the file contents will be read from memory;
    092     *         <code>false</code> otherwise.
    093     */
    094    boolean isInMemory();
    095
    096    /**
    097     * Returns the size of the file item.
    098     *
    099     * @return The size of the file item, in bytes.
    100     */
    101    long getSize();
    102
    103    /**
    104     * Returns the contents of the file item as an array of bytes.
    105     *
    106     * @return The contents of the file item as an array of bytes.
    107     */
    108    byte[] get();
    109
    110    /**
    111     * Returns the contents of the file item as a String, using the specified
    112     * encoding.  This method uses {@link #get()} to retrieve the
    113     * contents of the item.
    114     *
    115     * @param encoding The character encoding to use.
    116     *
    117     * @return The contents of the item, as a string.
    118     *
    119     * @throws UnsupportedEncodingException if the requested character
    120     *                                      encoding is not available.
    121     */
    122    String getString(String encoding) throws UnsupportedEncodingException;
    123
    124    /**
    125     * Returns the contents of the file item as a String, using the default
    126     * character encoding.  This method uses {@link #get()} to retrieve the
    127     * contents of the item.
    128     *
    129     * @return The contents of the item, as a string.
    130     */
    131    String getString();
    132
    133    /**
    134     * A convenience method to write an uploaded item to disk. The client code
    135     * is not concerned with whether or not the item is stored in memory, or on
    136     * disk in a temporary location. They just want to write the uploaded item
    137     * to a file.
    138     * <p>
    139     * This method is not guaranteed to succeed if called more than once for
    140     * the same item. This allows a particular implementation to use, for
    141     * example, file renaming, where possible, rather than copying all of the
    142     * underlying data, thus gaining a significant performance benefit.
    143     *
    144     * @param file The <code>File</code> into which the uploaded item should
    145     *             be stored.
    146     *
    147     * @throws Exception if an error occurs.
    148     */
    149    void write(File file) throws Exception;
    150
    151    /**
    152     * Deletes the underlying storage for a file item, including deleting any
    153     * associated temporary disk file. Although this storage will be deleted
    154     * automatically when the <code>FileItem</code> instance is garbage
    155     * collected, this method can be used to ensure that this is done at an
    156     * earlier time, thus preserving system resources.
    157     */
    158    void delete();
    159
    160    /**
    161     * Returns the name of the field in the multipart form corresponding to
    162     * this file item.
    163     *
    164     * @return The name of the form field.
    165     */
    166    String getFieldName();
    167
    168    /**
    169     * Sets the field name used to reference this file item.
    170     *
    171     * @param name The name of the form field.
    172     */
    173    void setFieldName(String name);
    174
    175    /**
    176     * Determines whether or not a <code>FileItem</code> instance represents
    177     * a simple form field.
    178     *
    179     * @return <code>true</code> if the instance represents a simple form
    180     *         field; <code>false</code> if it represents an uploaded file.
    181     */
    182    boolean isFormField();
    183
    184    /**
    185     * Specifies whether or not a <code>FileItem</code> instance represents
    186     * a simple form field.
    187     *
    188     * @param state <code>true</code> if the instance represents a simple form
    189     *              field; <code>false</code> if it represents an uploaded file.
    190     */
    191    void setFormField(boolean state);
    192
    193    /**
    194     * Returns an {@link java.io.OutputStream OutputStream} that can
    195     * be used for storing the contents of the file.
    196     *
    197     * @return An {@link java.io.OutputStream OutputStream} that can be used
    198     *         for storing the contensts of the file.
    199     *
    200     * @throws IOException if an error occurs.
    201     */
    202    OutputStream getOutputStream() throws IOException;
    203
    204}