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:
018: package org.apache.tomcat.util.http.fileupload;
019:
020: import java.io.File;
021: import java.io.IOException;
022: import java.io.InputStream;
023: import java.io.OutputStream;
024: import java.io.Serializable;
025: import java.io.UnsupportedEncodingException;
026:
027: /**
028: * <p> This class represents a file or form item that was received within a
029: * <code>multipart/form-data</code> POST request.
030: *
031: * <p> After retrieving an instance of this class from a {@link
032: * org.apache.tomcat.util.http.fileupload.FileUpload FileUpload} instance (see
033: * {@link org.apache.tomcat.util.http.fileupload.FileUpload
034: * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may
035: * either request all contents of the file at once using {@link #get()} or
036: * request an {@link java.io.InputStream InputStream} with
037: * {@link #getInputStream()} and process the file without attempting to load
038: * it into memory, which may come handy with large files.
039: *
040: * <p> While this interface does not extend
041: * <code>javax.activation.DataSource</code> per se (to avoid a seldom used
042: * dependency), several of the defined methods are specifically defined with
043: * the same signatures as methods in that interface. This allows an
044: * implementation of this interface to also implement
045: * <code>javax.activation.DataSource</code> with minimal additional work.
046: *
047: * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
048: * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
049: * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
050: * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
051: *
052: * @version $Id: FileItem.java 467222 2006-10-24 03:17:11Z markt $
053: */
054: public interface FileItem extends Serializable {
055:
056: // ------------------------------- Methods from javax.activation.DataSource
057:
058: /**
059: * Returns an {@link java.io.InputStream InputStream} that can be
060: * used to retrieve the contents of the file.
061: *
062: * @return An {@link java.io.InputStream InputStream} that can be
063: * used to retrieve the contents of the file.
064: *
065: * @exception IOException if an error occurs.
066: */
067: InputStream getInputStream() throws IOException;
068:
069: /**
070: * Returns the content type passed by the browser or <code>null</code> if
071: * not defined.
072: *
073: * @return The content type passed by the browser or <code>null</code> if
074: * not defined.
075: */
076: String getContentType();
077:
078: /**
079: * Returns the original filename in the client's filesystem, as provided by
080: * the browser (or other client software). In most cases, this will be the
081: * base file name, without path information. However, some clients, such as
082: * the Opera browser, do include path information.
083: *
084: * @return The original filename in the client's filesystem.
085: */
086: String getName();
087:
088: // ------------------------------------------------------- FileItem methods
089:
090: /**
091: * Provides a hint as to whether or not the file contents will be read
092: * from memory.
093: *
094: * @return <code>true</code> if the file contents will be read from memory;
095: * <code>false</code> otherwise.
096: */
097: boolean isInMemory();
098:
099: /**
100: * Returns the size of the file item.
101: *
102: * @return The size of the file item, in bytes.
103: */
104: long getSize();
105:
106: /**
107: * Returns the contents of the file item as an array of bytes.
108: *
109: * @return The contents of the file item as an array of bytes.
110: */
111: byte[] get();
112:
113: /**
114: * Returns the contents of the file item as a String, using the specified
115: * encoding. This method uses {@link #get()} to retrieve the
116: * contents of the item.
117: *
118: * @param encoding The character encoding to use.
119: *
120: * @return The contents of the item, as a string.
121: *
122: * @exception UnsupportedEncodingException if the requested character
123: * encoding is not available.
124: */
125: String getString(String encoding)
126: throws UnsupportedEncodingException;
127:
128: /**
129: * Returns the contents of the file item as a String, using the default
130: * character encoding. This method uses {@link #get()} to retrieve the
131: * contents of the item.
132: *
133: * @return The contents of the item, as a string.
134: */
135: String getString();
136:
137: /**
138: * A convenience method to write an uploaded item to disk. The client code
139: * is not concerned with whether or not the item is stored in memory, or on
140: * disk in a temporary location. They just want to write the uploaded item
141: * to a file.
142: * <p>
143: * This method is not guaranteed to succeed if called more than once for
144: * the same item. This allows a particular implementation to use, for
145: * example, file renaming, where possible, rather than copying all of the
146: * underlying data, thus gaining a significant performance benefit.
147: *
148: * @param file The <code>File</code> into which the uploaded item should
149: * be stored.
150: *
151: * @exception Exception if an error occurs.
152: */
153: void write(File file) throws Exception;
154:
155: /**
156: * Deletes the underlying storage for a file item, including deleting any
157: * associated temporary disk file. Although this storage will be deleted
158: * automatically when the <code>FileItem</code> instance is garbage
159: * collected, this method can be used to ensure that this is done at an
160: * earlier time, thus preserving system resources.
161: */
162: void delete();
163:
164: /**
165: * Returns the name of the field in the multipart form corresponding to
166: * this file item.
167: *
168: * @return The name of the form field.
169: */
170: String getFieldName();
171:
172: /**
173: * Sets the field name used to reference this file item.
174: *
175: * @param name The name of the form field.
176: */
177: void setFieldName(String name);
178:
179: /**
180: * Determines whether or not a <code>FileItem</code> instance represents
181: * a simple form field.
182: *
183: * @return <code>true</code> if the instance represents a simple form
184: * field; <code>false</code> if it represents an uploaded file.
185: */
186: boolean isFormField();
187:
188: /**
189: * Specifies whether or not a <code>FileItem</code> instance represents
190: * a simple form field.
191: *
192: * @param state <code>true</code> if the instance represents a simple form
193: * field; <code>false</code> if it represents an uploaded file.
194: */
195: void setFormField(boolean state);
196:
197: /**
198: * Returns an {@link java.io.OutputStream OutputStream} that can
199: * be used for storing the contents of the file.
200: *
201: * @return An {@link java.io.OutputStream OutputStream} that can be used
202: * for storing the contensts of the file.
203: *
204: * @exception IOException if an error occurs.
205: */
206: OutputStream getOutputStream() throws IOException;
207:
208: }
|