KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > net > jforum > util > legacy > commons > fileupload > FileItem


1 /*
2  * Copyright 2001-2004 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 net.jforum.util.legacy.commons.fileupload;
17
18 import java.io.File JavaDoc;
19 import java.io.IOException JavaDoc;
20 import java.io.InputStream JavaDoc;
21 import java.io.OutputStream JavaDoc;
22 import java.io.Serializable JavaDoc;
23 import java.io.UnsupportedEncodingException JavaDoc;
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,v 1.3 2005/07/26 03:05:01 rafaelsteil Exp $
51  */
52 public interface FileItem
53     extends Serializable JavaDoc {
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      * @exception IOException if an error occurs.
67      */
68     InputStream JavaDoc getInputStream()
69         throws IOException JavaDoc;
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 JavaDoc 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 JavaDoc 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      * @exception UnsupportedEncodingException if the requested character
132      * encoding is not available.
133      */
134     String JavaDoc getString(String JavaDoc encoding)
135         throws UnsupportedEncodingException JavaDoc;
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 JavaDoc 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      * @exception Exception if an error occurs.
163      */
164     void write(File JavaDoc file) throws Exception JavaDoc;
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 JavaDoc 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 JavaDoc 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      * @exception IOException if an error occurs.
222      */
223     OutputStream JavaDoc getOutputStream() throws IOException JavaDoc;
224
225 }
226
Popular Tags