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 479262 2006-11-26 03:09:24Z niallp $
052: */
053: public interface FileItem extends Serializable {
054:
055: // ------------------------------- Methods from javax.activation.DataSource
056:
057: /**
058: * Returns an {@link java.io.InputStream InputStream} that can be
059: * used to retrieve the contents of the file.
060: *
061: * @return An {@link java.io.InputStream InputStream} that can be
062: * used to retrieve the contents of the file.
063: *
064: * @throws IOException if an error occurs.
065: */
066: InputStream getInputStream() throws IOException;
067:
068: /**
069: * Returns the content type passed by the browser or <code>null</code> if
070: * not defined.
071: *
072: * @return The content type passed by the browser or <code>null</code> if
073: * not defined.
074: */
075: String getContentType();
076:
077: /**
078: * Returns the original filename in the client's filesystem, as provided by
079: * the browser (or other client software). In most cases, this will be the
080: * base file name, without path information. However, some clients, such as
081: * the Opera browser, do include path information.
082: *
083: * @return The original filename in the client's filesystem.
084: */
085: String getName();
086:
087: // ------------------------------------------------------- FileItem methods
088:
089: /**
090: * Provides a hint as to whether or not the file contents will be read
091: * from memory.
092: *
093: * @return <code>true</code> if the file contents will be read from memory;
094: * <code>false</code> otherwise.
095: */
096: boolean isInMemory();
097:
098: /**
099: * Returns the size of the file item.
100: *
101: * @return The size of the file item, in bytes.
102: */
103: long getSize();
104:
105: /**
106: * Returns the contents of the file item as an array of bytes.
107: *
108: * @return The contents of the file item as an array of bytes.
109: */
110: byte[] get();
111:
112: /**
113: * Returns the contents of the file item as a String, using the specified
114: * encoding. This method uses {@link #get()} to retrieve the
115: * contents of the item.
116: *
117: * @param encoding The character encoding to use.
118: *
119: * @return The contents of the item, as a string.
120: *
121: * @throws UnsupportedEncodingException if the requested character
122: * encoding is not available.
123: */
124: String getString(String encoding)
125: throws UnsupportedEncodingException;
126:
127: /**
128: * Returns the contents of the file item as a String, using the default
129: * character encoding. This method uses {@link #get()} to retrieve the
130: * contents of the item.
131: *
132: * @return The contents of the item, as a string.
133: */
134: String getString();
135:
136: /**
137: * A convenience method to write an uploaded item to disk. The client code
138: * is not concerned with whether or not the item is stored in memory, or on
139: * disk in a temporary location. They just want to write the uploaded item
140: * to a file.
141: * <p>
142: * This method is not guaranteed to succeed if called more than once for
143: * the same item. This allows a particular implementation to use, for
144: * example, file renaming, where possible, rather than copying all of the
145: * underlying data, thus gaining a significant performance benefit.
146: *
147: * @param file The <code>File</code> into which the uploaded item should
148: * be stored.
149: *
150: * @throws Exception if an error occurs.
151: */
152: void write(File file) throws Exception;
153:
154: /**
155: * Deletes the underlying storage for a file item, including deleting any
156: * associated temporary disk file. Although this storage will be deleted
157: * automatically when the <code>FileItem</code> instance is garbage
158: * collected, this method can be used to ensure that this is done at an
159: * earlier time, thus preserving system resources.
160: */
161: void delete();
162:
163: /**
164: * Returns the name of the field in the multipart form corresponding to
165: * this file item.
166: *
167: * @return The name of the form field.
168: */
169: String getFieldName();
170:
171: /**
172: * Sets the field name used to reference this file item.
173: *
174: * @param name The name of the form field.
175: */
176: void setFieldName(String name);
177:
178: /**
179: * Determines whether or not a <code>FileItem</code> instance represents
180: * a simple form field.
181: *
182: * @return <code>true</code> if the instance represents a simple form
183: * field; <code>false</code> if it represents an uploaded file.
184: */
185: boolean isFormField();
186:
187: /**
188: * Specifies whether or not a <code>FileItem</code> instance represents
189: * a simple form field.
190: *
191: * @param state <code>true</code> if the instance represents a simple form
192: * field; <code>false</code> if it represents an uploaded file.
193: */
194: void setFormField(boolean state);
195:
196: /**
197: * Returns an {@link java.io.OutputStream OutputStream} that can
198: * be used for storing the contents of the file.
199: *
200: * @return An {@link java.io.OutputStream OutputStream} that can be used
201: * for storing the contensts of the file.
202: *
203: * @throws IOException if an error occurs.
204: */
205: OutputStream getOutputStream() throws IOException;
206:
207: }
|