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.wicket.util.upload;
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.UnsupportedEncodingException;
024:
025: import org.apache.wicket.IClusterable;
026:
027: /**
028: * <p>
029: * This class represents a file or form item that was received within a
030: * <code>multipart/form-data</code> POST request.
031: *
032: * <p>
033: * After retrieving an instance of this class from a {@link
034: * org.apache.wicket.util.upload.FileUpload FileUpload} instance, you may either request
035: * all contents of the file at once using {@link #get()} or request an
036: * {@link java.io.InputStream InputStream} with {@link #getInputStream()} and
037: * process the file without attempting to load it into memory, which may come
038: * handy with large files.
039: *
040: * <p>
041: * While this interface does not extend <code>javax.activation.DataSource</code>
042: * per se (to avoid a seldom used dependency), several of the defined methods
043: * are specifically defined with the same signatures as methods in that
044: * interface. This allows an 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: public interface FileItem extends IClusterable {
053:
054: // ------------------------------- Methods from javax.activation.DataSource
055:
056: /**
057: * Returns an {@link java.io.InputStream InputStream} that can be used to
058: * retrieve the contents of the file.
059: *
060: * @return An {@link java.io.InputStream InputStream} that can be used to
061: * retrieve the contents of the file.
062: *
063: * @exception IOException
064: * 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 from
091: * memory.
092: *
093: * @return <code>true</code> if the file contents will be read from
094: * memory; <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 contents of the
115: * item.
116: *
117: * @param encoding
118: * The character encoding to use.
119: *
120: * @return The contents of the item, as a string.
121: *
122: * @exception UnsupportedEncodingException
123: * if the requested character 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 the
144: * same item. This allows a particular implementation to use, for example,
145: * file renaming, where possible, rather than copying all of the underlying
146: * data, thus gaining a significant performance benefit.
147: *
148: * @param file
149: * The <code>File</code> into which the uploaded item should be
150: * stored.
151: *
152: * @exception Exception
153: * if an error occurs.
154: */
155: void write(File file) throws Exception;
156:
157: /**
158: * Deletes the underlying storage for a file item, including deleting any
159: * associated temporary disk file. Although this storage will be deleted
160: * automatically when the <code>FileItem</code> instance is garbage
161: * collected, this method can be used to ensure that this is done at an
162: * earlier time, thus preserving system resources.
163: */
164: void delete();
165:
166: /**
167: * Returns the name of the field in the multipart form corresponding to this
168: * file item.
169: *
170: * @return The name of the form field.
171: */
172: String getFieldName();
173:
174: /**
175: * Sets the field name used to reference this file item.
176: *
177: * @param name
178: * The name of the form field.
179: */
180: void setFieldName(String name);
181:
182: /**
183: * Determines whether or not a <code>FileItem</code> instance represents a
184: * simple form field.
185: *
186: * @return <code>true</code> if the instance represents a simple form
187: * field; <code>false</code> if it represents an uploaded file.
188: */
189: boolean isFormField();
190:
191: /**
192: * Specifies whether or not a <code>FileItem</code> instance represents a
193: * simple form field.
194: *
195: * @param state
196: * <code>true</code> if the instance represents a simple form
197: * field; <code>false</code> if it represents an uploaded file.
198: */
199: void setFormField(boolean state);
200:
201: /**
202: * Returns an {@link java.io.OutputStream OutputStream} that can be used for
203: * storing the contents of the file.
204: *
205: * @return An {@link java.io.OutputStream OutputStream} that can be used for
206: * storing the contensts of the file.
207: *
208: * @exception IOException
209: * if an error occurs.
210: */
211: OutputStream getOutputStream() throws IOException;
212:
213: }
|