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} 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} 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} with minimal additional work.
044 *
045 * @since 1.3 additionally implements FileItemHeadersSupport
046 */
047public interface FileItem extends FileItemHeadersSupport {
048
049    /**
050     * Deletes the underlying storage for a file item, including deleting any
051     * associated temporary disk file. Although this storage will be deleted
052     * automatically when the {@code FileItem} instance is garbage
053     * collected, this method can be used to ensure that this is done at an
054     * earlier time, thus preserving system resources.
055     */
056    void delete();
057
058    /**
059     * Returns the contents of the file item as an array of bytes.
060     *
061     * @return The contents of the file item as an array of bytes.
062     */
063    byte[] get();
064
065    /**
066     * Returns the content type passed by the browser or {@code null} if
067     * not defined.
068     *
069     * @return The content type passed by the browser or {@code null} if
070     *         not defined.
071     */
072    String getContentType();
073
074    /**
075     * Returns the name of the field in the multipart form corresponding to
076     * this file item.
077     *
078     * @return The name of the form field.
079     */
080    String getFieldName();
081
082    /**
083     * Returns an {@link java.io.InputStream InputStream} that can be
084     * used to retrieve the contents of the file.
085     *
086     * @return An {@link java.io.InputStream InputStream} that can be
087     *         used to retrieve the contents of the file.
088     *
089     * @throws IOException if an error occurs.
090     */
091    InputStream getInputStream() throws IOException;
092
093    /**
094     * Returns the original file name in the client's file system, as provided by
095     * the browser (or other client software). In most cases, this will be the
096     * base file name, without path information. However, some clients, such as
097     * the Opera browser, do include path information.
098     *
099     * @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}