KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tomcat > util > http > fileupload > FileItem


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