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 578253 2007-09-21 20:13:14Z 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         */
089        String getName();
090    
091    
092        // ------------------------------------------------------- FileItem methods
093    
094    
095        /**
096         * Provides a hint as to whether or not the file contents will be read
097         * from memory.
098         *
099         * @return <code>true</code> if the file contents will be read from memory;
100         *         <code>false</code> otherwise.
101         */
102        boolean isInMemory();
103    
104    
105        /**
106         * Returns the size of the file item.
107         *
108         * @return The size of the file item, in bytes.
109         */
110        long getSize();
111    
112    
113        /**
114         * Returns the contents of the file item as an array of bytes.
115         *
116         * @return The contents of the file item as an array of bytes.
117         */
118        byte[] get();
119    
120    
121        /**
122         * Returns the contents of the file item as a String, using the specified
123         * encoding.  This method uses {@link #get()} to retrieve the
124         * contents of the item.
125         *
126         * @param encoding The character encoding to use.
127         *
128         * @return The contents of the item, as a string.
129         *
130         * @throws UnsupportedEncodingException if the requested character
131         *                                      encoding is not available.
132         */
133        String getString(String encoding) throws UnsupportedEncodingException;
134    
135    
136        /**
137         * Returns the contents of the file item as a String, using the default
138         * character encoding.  This method uses {@link #get()} to retrieve the
139         * contents of the item.
140         *
141         * @return The contents of the item, as a string.
142         */
143        String getString();
144    
145    
146        /**
147         * A convenience method to write an uploaded item to disk. The client code
148         * is not concerned with whether or not the item is stored in memory, or on
149         * disk in a temporary location. They just want to write the uploaded item
150         * to a file.
151         * <p>
152         * This method is not guaranteed to succeed if called more than once for
153         * the same item. This allows a particular implementation to use, for
154         * example, file renaming, where possible, rather than copying all of the
155         * underlying data, thus gaining a significant performance benefit.
156         *
157         * @param file The <code>File</code> into which the uploaded item should
158         *             be stored.
159         *
160         * @throws Exception if an error occurs.
161         */
162        void write(File file) throws Exception;
163    
164    
165        /**
166         * Deletes the underlying storage for a file item, including deleting any
167         * associated temporary disk file. Although this storage will be deleted
168         * automatically when the <code>FileItem</code> instance is garbage
169         * collected, this method can be used to ensure that this is done at an
170         * earlier time, thus preserving system resources.
171         */
172        void delete();
173    
174    
175        /**
176         * Returns the name of the field in the multipart form corresponding to
177         * this file item.
178         *
179         * @return The name of the form field.
180         */
181        String getFieldName();
182    
183    
184        /**
185         * Sets the field name used to reference this file item.
186         *
187         * @param name The name of the form field.
188         */
189        void setFieldName(String name);
190    
191    
192        /**
193         * Determines whether or not a <code>FileItem</code> instance represents
194         * a simple form field.
195         *
196         * @return <code>true</code> if the instance represents a simple form
197         *         field; <code>false</code> if it represents an uploaded file.
198         */
199        boolean isFormField();
200    
201    
202        /**
203         * Specifies whether or not a <code>FileItem</code> instance represents
204         * a simple form field.
205         *
206         * @param state <code>true</code> if the instance represents a simple form
207         *              field; <code>false</code> if it represents an uploaded file.
208         */
209        void setFormField(boolean state);
210    
211    
212        /**
213         * Returns an {@link java.io.OutputStream OutputStream} that can
214         * be used for storing the contents of the file.
215         *
216         * @return An {@link java.io.OutputStream OutputStream} that can be used
217         *         for storing the contensts of the file.
218         *
219         * @throws IOException if an error occurs.
220         */
221        OutputStream getOutputStream() throws IOException;
222    
223    }