View Javadoc

1   /*
2    * Copyright 2001-2005 The Apache Software Foundation
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.fileupload;
17  
18  import java.io.File;
19  import java.io.IOException;
20  import java.io.InputStream;
21  import java.io.OutputStream;
22  import java.io.Serializable;
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</code> 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.FileUpload
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</code> 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</code> with minimal additional work.
44   *
45   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
46   * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
47   * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
48   * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
49   *
50   * @version $Id: FileItem.java 349366 2005-11-28 04:44:57Z martinc $
51   */
52  public interface FileItem
53      extends Serializable {
54  
55  
56      // ------------------------------- Methods from javax.activation.DataSource
57  
58  
59      /***
60       * Returns an {@link java.io.InputStream InputStream} that can be
61       * used to retrieve the contents of the file.
62       *
63       * @return An {@link java.io.InputStream InputStream} that can be
64       *         used to retrieve the contents of the file.
65       *
66       * @throws IOException if an error occurs.
67       */
68      InputStream getInputStream()
69          throws IOException;
70  
71  
72      /***
73       * Returns the content type passed by the browser or <code>null</code> if
74       * not defined.
75       *
76       * @return The content type passed by the browser or <code>null</code> if
77       *         not defined.
78       */
79      String getContentType();
80  
81  
82      /***
83       * Returns the original filename in the client's filesystem, as provided by
84       * the browser (or other client software). In most cases, this will be the
85       * base file name, without path information. However, some clients, such as
86       * the Opera browser, do include path information.
87       *
88       * @return The original filename in the client's filesystem.
89       */
90      String getName();
91  
92  
93      // ------------------------------------------------------- FileItem methods
94  
95  
96      /***
97       * Provides a hint as to whether or not the file contents will be read
98       * from memory.
99       *
100      * @return <code>true</code> if the file contents will be read from memory;
101      *         <code>false</code> otherwise.
102      */
103     boolean isInMemory();
104 
105 
106     /***
107      * Returns the size of the file item.
108      *
109      * @return The size of the file item, in bytes.
110      */
111     long getSize();
112 
113 
114     /***
115      * Returns the contents of the file item as an array of bytes.
116      *
117      * @return The contents of the file item as an array of bytes.
118      */
119     byte[] get();
120 
121 
122     /***
123      * Returns the contents of the file item as a String, using the specified
124      * encoding.  This method uses {@link #get()} to retrieve the
125      * contents of the item.
126      *
127      * @param encoding The character encoding to use.
128      *
129      * @return The contents of the item, as a string.
130      *
131      * @throws UnsupportedEncodingException if the requested character
132      *                                      encoding is not available.
133      */
134     String getString(String encoding)
135         throws UnsupportedEncodingException;
136 
137 
138     /***
139      * Returns the contents of the file item as a String, using the default
140      * character encoding.  This method uses {@link #get()} to retrieve the
141      * contents of the item.
142      *
143      * @return The contents of the item, as a string.
144      */
145     String getString();
146 
147 
148     /***
149      * A convenience method to write an uploaded item to disk. The client code
150      * is not concerned with whether or not the item is stored in memory, or on
151      * disk in a temporary location. They just want to write the uploaded item
152      * to a file.
153      * <p>
154      * This method is not guaranteed to succeed if called more than once for
155      * the same item. This allows a particular implementation to use, for
156      * example, file renaming, where possible, rather than copying all of the
157      * underlying data, thus gaining a significant performance benefit.
158      *
159      * @param file The <code>File</code> into which the uploaded item should
160      *             be stored.
161      *
162      * @throws Exception if an error occurs.
163      */
164     void write(File file) throws Exception;
165 
166 
167     /***
168      * Deletes the underlying storage for a file item, including deleting any
169      * associated temporary disk file. Although this storage will be deleted
170      * automatically when the <code>FileItem</code> instance is garbage
171      * collected, this method can be used to ensure that this is done at an
172      * earlier time, thus preserving system resources.
173      */
174     void delete();
175 
176 
177     /***
178      * Returns the name of the field in the multipart form corresponding to
179      * this file item.
180      *
181      * @return The name of the form field.
182      */
183     String getFieldName();
184 
185 
186     /***
187      * Sets the field name used to reference this file item.
188      *
189      * @param name The name of the form field.
190      */
191     void setFieldName(String name);
192 
193 
194     /***
195      * Determines whether or not a <code>FileItem</code> instance represents
196      * a simple form field.
197      *
198      * @return <code>true</code> if the instance represents a simple form
199      *         field; <code>false</code> if it represents an uploaded file.
200      */
201     boolean isFormField();
202 
203 
204     /***
205      * Specifies whether or not a <code>FileItem</code> instance represents
206      * a simple form field.
207      *
208      * @param state <code>true</code> if the instance represents a simple form
209      *              field; <code>false</code> if it represents an uploaded file.
210      */
211     void setFormField(boolean state);
212 
213 
214     /***
215      * Returns an {@link java.io.OutputStream OutputStream} that can
216      * be used for storing the contents of the file.
217      *
218      * @return An {@link java.io.OutputStream OutputStream} that can be used
219      *         for storing the contensts of the file.
220      *
221      * @throws IOException if an error occurs.
222      */
223     OutputStream getOutputStream() throws IOException;
224 
225 }