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