FileItem


1   /*
2    * $Header: /home/cvs/jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/FileItem.java,v 1.15 2003/06/01 17:33:24 martinc Exp $
3    * $Revision: 1.15 $
4    * $Date: 2003/06/01 17:33:24 $
5    *
6    * ====================================================================
7    *
8    * The Apache Software License, Version 1.1
9    *
10   * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights
11   * reserved.
12   *
13   * Redistribution and use in source and binary forms, with or without
14   * modification, are permitted provided that the following conditions
15   * are met:
16   *
17   * 1. Redistributions of source code must retain the above copyright
18   *    notice, this list of conditions and the following disclaimer.
19   *
20   * 2. Redistributions in binary form must reproduce the above copyright
21   *    notice, this list of conditions and the following disclaimer in
22   *    the documentation and/or other materials provided with the
23   *    distribution.
24   *
25   * 3. The end-user documentation included with the redistribution, if
26   *    any, must include the following acknowlegement:
27   *       "This product includes software developed by the
28   *        Apache Software Foundation (http://www.apache.org/)."
29   *    Alternately, this acknowlegement may appear in the software itself,
30   *    if and wherever such third-party acknowlegements normally appear.
31   *
32   * 4. The names "The Jakarta Project", "Commons", and "Apache Software
33   *    Foundation" must not be used to endorse or promote products derived
34   *    from this software without prior written permission. For written
35   *    permission, please contact apache@apache.org.
36   *
37   * 5. Products derived from this software may not be called "Apache"
38   *    nor may "Apache" appear in their names without prior written
39   *    permission of the Apache Group.
40   *
41   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
42   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
43   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
45   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
47   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
48   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
49   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
50   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
51   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
52   * SUCH DAMAGE.
53   * ====================================================================
54   *
55   * This software consists of voluntary contributions made by many
56   * individuals on behalf of the Apache Software Foundation.  For more
57   * information on the Apache Software Foundation, please see
58   * <http://www.apache.org/>.
59   *
60   */
61  
62  
63  package org.apache.commons.fileupload;
64  
65  
66  import java.io.File  ;
67  import java.io.IOException  ;
68  import java.io.InputStream  ;
69  import java.io.OutputStream  ;
70  import java.io.Serializable  ;
71  import java.io.UnsupportedEncodingException  ;
72  
73  
74  /**
75   * <p> This class represents a file or form item that was received within a
76   * <code>multipart/form-data</code> POST request.
77   *
78   * <p> After retrieving an instance of this class from a {@link
79   * org.apache.commons.fileupload.FileUpload FileUpload} instance (see
80   * {@link org.apache.commons.fileupload.FileUpload
81   * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may
82   * either request all contents of the file at once using {@link #get()} or
83   * request an {@link java.io.InputStream InputStream} with
84   * {@link #getInputStream()} and process the file without attempting to load
85   * it into memory, which may come handy with large files.
86   *
87   * <p> While this interface does not extend
88   * <code>javax.activation.DataSource</code> per se (to avoid a seldom used
89   * dependency), several of the defined methods are specifically defined with
90   * the same signatures as methods in that interface. This allows an
91   * implementation of this interface to also implement
92   * <code>javax.activation.DataSource</code> with minimal additional work.
93   *
94   * @author <a HREF="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
95   * @author <a HREF="mailto:sean@informage.net">Sean Legassick</a>
96   * @author <a HREF="mailto:jvanzyl@apache.org">Jason van Zyl</a>
97   * @author <a HREF="mailto:martinc@apache.org">Martin Cooper</a>
98   *
99   * @version $Id: FileItem.java,v 1.15 2003/06/01 17:33:24 martinc Exp $
100  */
101 public interface FileItem
102     extends Serializable  
103 {
104 
105 
106     // ------------------------------- Methods from javax.activation.DataSource
107 
108 
109     /**
110      * Returns an {@link java.io.InputStream InputStream} that can be
111      * used to retrieve the contents of the file.
112      *
113      * @return An {@link java.io.InputStream InputStream} that can be
114      *         used to retrieve the contents of the file.
115      *
116      * @exception IOException if an error occurs.
117      */
118     InputStream   getInputStream()
119         throws IOException  ;
120 
121 
122     /**
123      * Returns the content type passed by the browser or <code>null</code> if
124      * not defined.
125      *
126      * @return The content type passed by the browser or <code>null</code> if
127      *         not defined.
128      */
129     String   getContentType();
130 
131 
132     /**
133      * Returns the original filename in the client's filesystem, as provided by
134      * the browser (or other client software). In most cases, this will be the
135      * base file name, without path information. However, some clients, such as
136      * the Opera browser, do include path information.
137      *
138      * @return The original filename in the client's filesystem.
139      */
140     String   getName();
141 
142 
143     // ------------------------------------------------------- FileItem methods
144 
145 
146     /**
147      * Provides a hint as to whether or not the file contents will be read
148      * from memory.
149      *
150      * @return <code>true</code> if the file contents will be read from memory;
151      *         <code>false</code> otherwise.
152      */
153     boolean isInMemory();
154 
155 
156     /**
157      * Returns the size of the file item.
158      *
159      * @return The size of the file item, in bytes.
160      */
161     long getSize();
162 
163 
164     /**
165      * Returns the contents of the file item as an array of bytes.
166      *
167      * @return The contents of the file item as an array of bytes.
168      */
169     byte[] get();
170 
171 
172     /**
173      * Returns the contents of the file item as a String, using the specified
174      * encoding.  This method uses {@link #get()} to retrieve the
175      * contents of the item.
176      *
177      * @param encoding The character encoding to use.
178      *
179      * @return The contents of the item, as a string.
180      *
181      * @exception UnsupportedEncodingException if the requested character
182      *                                         encoding is not available.
183      */
184     String   getString(String   encoding)
185         throws UnsupportedEncodingException  ;
186 
187 
188     /**
189      * Returns the contents of the file item as a String, using the default
190      * character encoding.  This method uses {@link #get()} to retrieve the
191      * contents of the item.
192      *
193      * @return The contents of the item, as a string.
194      */
195     String   getString();
196 
197 
198     /**
199      * A convenience method to write an uploaded item to disk. The client code
200      * is not concerned with whether or not the item is stored in memory, or on
201      * disk in a temporary location. They just want to write the uploaded item
202      * to a file.
203      * <p>
204      * This method is not guaranteed to succeed if called more than once for
205      * the same item. This allows a particular implementation to use, for
206      * example, file renaming, where possible, rather than copying all of the
207      * underlying data, thus gaining a significant performance benefit.
208      *
209      * @param file The <code>File</code> into which the uploaded item should
210      *             be stored.
211      *
212      * @exception Exception if an error occurs.
213      */
214     void write(File   file) throws Exception  ;
215 
216 
217     /**
218      * Deletes the underlying storage for a file item, including deleting any
219      * associated temporary disk file. Although this storage will be deleted
220      * automatically when the <code>FileItem</code> instance is garbage
221      * collected, this method can be used to ensure that this is done at an
222      * earlier time, thus preserving system resources.
223      */
224     void delete();
225 
226 
227     /**
228      * Returns the name of the field in the multipart form corresponding to
229      * this file item.
230      *
231      * @return The name of the form field.
232      */
233     String   getFieldName();
234 
235 
236     /**
237      * Sets the field name used to reference this file item.
238      *
239      * @param name The name of the form field.
240      */
241     void setFieldName(String   name);
242 
243 
244     /**
245      * Determines whether or not a <code>FileItem</code> instance represents
246      * a simple form field.
247      *
248      * @return <code>true</code> if the instance represents a simple form
249      *         field; <code>false</code> if it represents an uploaded file.
250      */
251     boolean isFormField();
252 
253 
254     /**
255      * Specifies whether or not a <code>FileItem</code> instance represents
256      * a simple form field.
257      *
258      * @param state <code>true</code> if the instance represents a simple form
259      *              field; <code>false</code> if it represents an uploaded file.
260      */
261     void setFormField(boolean state);
262 
263 
264     /**
265      * Returns an {@link java.io.OutputStream OutputStream} that can
266      * be used for storing the contents of the file.
267      *
268      * @return An {@link java.io.OutputStream OutputStream} that can be used
269      *         for storing the contensts of the file.
270      *
271      * @exception IOException if an error occurs.
272      */
273     OutputStream   getOutputStream() throws IOException  ;
274 
275 }
276
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags