You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ma...@apache.org on 2002/07/19 05:56:51 UTC
cvs commit: jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload DefaultFileItem.java FileItem.java FileUpload.java MultipartStream.java
martinc 2002/07/18 20:56:51
Modified: fileupload/src/java/org/apache/commons/fileupload
DefaultFileItem.java FileItem.java FileUpload.java
MultipartStream.java
Log:
Various cleanup changes:
- Javadoc corrections for accuracy and to remove Turbine references.
- Minor stylistic changes to keep Checkstyle happy.
- Moved some stuff around for grouping and clarity.
Revision Changes Path
1.9 +300 -198 jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload/DefaultFileItem.java
Index: DefaultFileItem.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload/DefaultFileItem.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- DefaultFileItem.java 17 Jul 2002 05:14:14 -0000 1.8
+++ DefaultFileItem.java 19 Jul 2002 03:56:51 -0000 1.9
@@ -70,64 +70,91 @@
import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
-import java.io.FileWriter;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.io.OutputStream;
-import javax.activation.DataSource;
/**
- * <p> The implementation of
+ * <p> The default mplementation of the
* {@link org.apache.commons.fileupload.FileItem FileItem} interface.
*
- * <p> After retrieving an instance of this class from the {@link
- * org.apache.commons.fileupload.FileUpload FileUpload} (see
+ * <p> After retrieving an instance of this class from a {@link
+ * org.apache.commons.fileupload.FileUpload FileUpload} instance (see
* {@link org.apache.commons.fileupload.FileUpload
- * #parseRequest(javax.servlet.http.HttpServletRequest, String)
- * You may either request all
- * contents of file at once using {@link #get()} or request an {@link
- * java.io.InputStream InputStream} with {@link #getStream()} and
- * process the file without attempting to load it into memory, which
+ * #parseRequest(javax.servlet.http.HttpServletRequest, String)), you may
+ * either request all contents of file at once using {@link #get()} or
+ * request an {@link java.io.InputStream InputStream} with {@link #getStream()}
+ * and process the file without attempting to load it into memory, which
* may come handy with large files.
*
- * Implements the javax.activation.DataSource interface (which allows
- * for example the adding of a FileItem as an attachment to a multipart
- * email).
- *
* @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
* @author <a href="mailto:sean@informage.net">Sean Legassick</a>
* @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
* @author <a href="mailto:jmcnally@apache.org">John McNally</a>
+ * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
+ *
* @version $Id$
*/
public class DefaultFileItem
implements FileItem
{
- protected static int counter = 0;
- /** The original filename in the user's filesystem. */
- protected String fileName;
+ // ----------------------------------------------------------- Data members
+
/**
- * The content type passed by the browser or <code>null</code> if
+ * Counter used in unique identifier generation.
+ */
+ private static int counter = 0;
+
+
+ /**
+ * The original filename in the user's filesystem.
+ */
+ private String fileName;
+
+
+ /**
+ * The content type passed by the browser, or <code>null</code> if
* not defined.
*/
- protected String contentType;
+ private String contentType;
- /** Cached contents of the file. */
- protected byte[] content;
- /** Temporary storage location. */
- protected File storeLocation;
+ /**
+ * Cached contents of the file.
+ */
+ private byte[] content;
- /** Temporary storage for in-memory files. */
- protected ByteArrayOutputStream byteStream;
- protected String fieldName;
+ /**
+ * Temporary storage location on disk.
+ */
+ private File storeLocation;
+
+
+ /**
+ * Temporary storage for in-memory files.
+ */
+ private ByteArrayOutputStream byteStream;
+
+
+ /**
+ * The name of the form field as provided by the browser.
+ */
+ private String fieldName;
+
+
+ /**
+ * Whether or not this item is a simple form field.
+ */
+ private boolean isFormField;
+
+
+ // ----------------------------------------------------------- Constructors
- protected boolean isFormField;
/**
* Default constructor.
@@ -136,79 +163,107 @@
{
}
- public void setFieldName(String fieldName)
- {
- this.fieldName = fieldName;
- }
-
- public String getFieldName()
- {
- return fieldName;
- }
/**
- * Constructs a new <code>DefaultFileItem</code>.
+ * Constructs a new <code>DefaultFileItem</code> instance.
*
* <p>Use {@link #newInstance(String,String,String,int,int)} to
- * instantiate <code>DefaultFileItems</code>.
+ * instantiate <code>DefaultFileItem</code>s.
*
* @param fileName The original filename in the user's filesystem.
* @param contentType The content type passed by the browser or
* <code>null</code> if not defined.
*/
- protected DefaultFileItem( String fileName, String contentType )
+ protected DefaultFileItem(String fileName, String contentType)
{
this.fileName = fileName;
this.contentType = contentType;
}
+
+ // ------------------------------- Methods from javax.activation.DataSource
+
+
/**
- * Returns the original filename in the user's filesystem.
- * (implements DataSource method)
+ * Returns an {@link java.io.InputStream InputStream} that can be
+ * used to retrieve the contents of the file.
+ *
+ * @return An {@link java.io.InputStream InputStream} that can be
+ * used to retrieve the contents of the file.
*
- * @return The original filename in the user's filesystem.
+ * @exception IOException if an error occurs.
*/
- public String getName()
+ public InputStream getInputStream()
+ throws IOException
{
- return fileName;
+ if (content == null)
+ {
+ if (storeLocation != null)
+ {
+ return new FileInputStream(storeLocation);
+ }
+ else
+ {
+ content = byteStream.toByteArray();
+ byteStream = null;
+ }
+ }
+ return new ByteArrayInputStream(content);
}
+
/**
- * Returns the content type passed by the browser or
- * <code>null</code> if not defined. (implements
- * DataSource method).
- *
- * @return The content type passed by the browser or
- * <code>null</code> if not defined.
- */
+ * Returns the content type passed by the browser or <code>null</code> if
+ * not defined.
+ *
+ * @return The content type passed by the browser or <code>null</code> if
+ * not defined.
+ */
public String getContentType()
{
return contentType;
}
+
/**
- * Provides a hint if the file contents will be read from memory.
+ * Returns the original filename in the client's filesystem.
*
- * @return <code>True</code> if the file contents will be read
+ * @return The original filename in the client's filesystem.
+ */
+ public String getName()
+ {
+ return fileName;
+ }
+
+
+ // ------------------------------------------------------- FileItem methods
+
+
+ /**
+ * Provides a hint as to whether or not the file contents will be read
* from memory.
+ *
+ * @return <code>true</code> if the file contents will be read
+ * from memory.
*/
- public boolean inMemory()
+ public boolean isInMemory()
{
return (content != null || byteStream != null);
}
+
/**
* Returns the size of the file.
*
- * @return The size of the file.
+ * @return The size of the file, in bytes.
*/
public long getSize()
{
- if(storeLocation != null)
+ if (storeLocation != null)
{
return storeLocation.length();
}
- else if(byteStream != null)
+ else if (byteStream != null)
{
return byteStream.size();
}
@@ -218,20 +273,21 @@
}
}
+
/**
* Returns the contents of the file as an array of bytes. If the
- * contents of the file were not yet cached int the memory, they
- * will be loaded from the disk storage and chached.
+ * contents of the file were not yet cached in memory, they will be
+ * loaded from the disk storage and cached.
*
* @return The contents of the file as an array of bytes.
*/
public byte[] get()
{
- if(content == null)
+ if (content == null)
{
- if(storeLocation != null)
+ if (storeLocation != null)
{
- content = new byte[(int)getSize()];
+ content = new byte[(int) getSize()];
try
{
FileInputStream fis = new FileInputStream(storeLocation);
@@ -252,156 +308,72 @@
return content;
}
+
/**
- * Returns the contents of the file as a String, using specified
- * encoding. This method uses {@link #get()} to retireve the
- * contents of the file.<br>
- *
- * @param encoding The encoding to use.
- * @return The contents of the file.
- * @exception UnsupportedEncodingException.
+ * Returns the contents of the file as a String, using the specified
+ * encoding. This method uses {@link #get()} to retrieve the
+ * contents of the file.
+ *
+ * @param encoding The character encoding to use.
+ *
+ * @return The contents of the file, as a string.
+ *
+ * @exception UnsupportedEncodingException if the requested character
+ * encoding is not available.
*/
- public String getString( String encoding )
+ public String getString(String encoding)
throws UnsupportedEncodingException
{
return new String(get(), encoding);
}
- public String getString()
- {
- return new String(get());
- }
/**
- * Returns an {@link java.io.InputStream InputStream} that can be
- * used to retrieve the contents of the file. (implements DataSource
- * method)
+ * Returns the contents of the file as a String, using the default
+ * character encoding. This method uses {@link #get()} to retrieve the
+ * contents of the file.
*
- * @return An {@link java.io.InputStream InputStream} that can be
- * used to retrieve the contents of the file.
- * @exception Exception, a generic exception.
+ * @return The contents of the file, as a string.
*/
- public InputStream getInputStream()
- throws IOException
+ public String getString()
{
- if(content == null)
- {
- if(storeLocation != null)
- {
- return new FileInputStream(storeLocation);
- }
- else
- {
- content = byteStream.toByteArray();
- byteStream = null;
- }
- }
- return new ByteArrayInputStream(content);
+ return new String(get());
}
+
/**
- * Returns the {@link java.io.File} objects for the DefaultFileItems's
- * data temporary location on the disk. Note that for
- * <code>DefaultFileItems</code> that have their data stored in memory
- * this method will return <code>null</code>. When handling large
+ * Returns the {@link java.io.File} object for the <code>FileItem</code>'s
+ * data's temporary location on the disk. Note that for
+ * <code>FileItem</code>s that have their data stored in memory,
+ * this method will return <code>null</code>. When handling large
* files, you can use {@link java.io.File#renameTo(File)} to
* move the file to new location without copying the data, if the
* source and destination locations reside within the same logical
* volume.
*
- * @return A File.
+ * @return The data file, or <code>null</code> if the data is stored in
+ * memory.
*/
public File getStoreLocation()
{
return storeLocation;
}
- /**
- * Removes the file contents from the temporary storage.
- */
- protected void finalize()
- {
- if(storeLocation != null && storeLocation.exists())
- {
- storeLocation.delete();
- }
- }
/**
- * Returns an {@link java.io.OutputStream OutputStream} that can
- * be used for storing the contents of the file.
- * (implements DataSource method)
+ * A convenience method to write an uploaded file to disk. The client code
+ * is not concerned whether or not the file is stored in memory, or on disk
+ * in a temporary location. They just want to write the uploaded file to
+ * disk.
*
- * @return an {@link java.io.OutputStream OutputStream} that can be
- * used for storing the contensts of the file.
- * @exception IOException.
- */
- public OutputStream getOutputStream()
- throws IOException
- {
- if(storeLocation == null)
- {
- return byteStream;
- }
- else
- {
- return new FileOutputStream(storeLocation);
- }
- }
-
- /**
- * Instantiates a DefaultFileItem. It uses <code>requestSize</code> to
- * decide what temporary storage approach the new item should
- * take. The largest request that will have its items cached in
- * memory can be configured in
- * <code>TurbineResources.properties</code> in the entry named
- * <code>file.upload.size.threshold</code>
+ * @param file The full path to location where the uploaded file should
+ * be stored.
*
- * @param path A String.
- * @param name The original filename in the user's filesystem.
- * @param contentType The content type passed by the browser or
- * <code>null</code> if not defined.
- * @param requestSize The total size of the POST request this item
- * belongs to.
- * @param threshold The maximum size to store in memory.
- * @return A DefaultFileItem.
- */
- public static FileItem newInstance(String path,
- String name,
- String contentType,
- int requestSize,
- int threshold)
- {
- DefaultFileItem item = new DefaultFileItem(name, contentType);
- if(requestSize > threshold)
- {
- String fileName = getUniqueId();
- fileName = "upload_" + fileName + ".tmp";
- fileName = path + "/" + fileName;
- File f = new File(fileName);
- f.deleteOnExit();
- item.storeLocation = f;
- }
- else
- {
- item.byteStream = new ByteArrayOutputStream();
- }
- return item;
- }
-
- /**
- * A convenience method to write an uploaded
- * file to disk. The client code is not concerned
- * whether or not the file is stored in memory,
- * or on disk in a temporary location. They just
- * want to write the uploaded file to disk.
- *
- * @param String full path to location where uploaded
- * should be stored.
+ * @exception Exception if an error occurs.
*/
public void write(String file) throws Exception
{
- if (inMemory())
+ if (isInMemory())
{
FileOutputStream fout = null;
try
@@ -435,9 +407,9 @@
out = new BufferedOutputStream(new FileOutputStream(file));
byte[] bytes = new byte[2048];
int s = 0;
- while ( (s = in.read(bytes)) != -1 )
+ while ((s = in.read(bytes)) != -1)
{
- out.write(bytes,0,s);
+ out.write(bytes, 0, s);
}
}
finally
@@ -472,35 +444,164 @@
}
}
- public void setIsFormField(boolean state)
+
+ /**
+ * Deletes the underlying storage for a file item, including deleting any
+ * associated temporary disk file. Although this storage will be deleted
+ * automatically when the <code>FileItem</code> instance is garbage
+ * collected, this method can be used to ensure that this is done at an
+ * earlier time, thus preserving system resources.
+ */
+ public void delete()
{
- isFormField = state;
+ byteStream = null;
+ content = null;
+ if (storeLocation != null && storeLocation.exists())
+ {
+ storeLocation.delete();
+ }
+ }
+
+
+ /**
+ * Returns the name of the field in the multipart form corresponding to
+ * this file item.
+ *
+ * @return The name of the form field.
+ */
+ public String getFieldName()
+ {
+ return fieldName;
+ }
+
+
+ /**
+ * Sets the field name used to reference this file item.
+ *
+ * @param fieldName The name of the form field.
+ */
+ public void setFieldName(String fieldName)
+ {
+ this.fieldName = fieldName;
}
+
+ /**
+ * Determines whether or not a <code>FileItem</code> instance represents
+ * a simple form field.
+ *
+ * @return <code>true</code> if the instance represents a simple form
+ * field; <code>false</code> if it represents an uploaded file.
+ */
public boolean isFormField()
{
return isFormField;
}
- public void delete() {
- byteStream = null;
- content = null;
- if (storeLocation != null && storeLocation.exists()) {
+
+ /**
+ * Specifies whether or not a <code>FileItem</code> instance represents
+ * a simple form field.
+ *
+ * @param state <code>true</code> if the instance represents a simple form
+ * field; <code>false</code> if it represents an uploaded file.
+ */
+ public void setIsFormField(boolean state)
+ {
+ isFormField = state;
+ }
+
+
+ // --------------------------------------------------------- Public methods
+
+
+ /**
+ * Removes the file contents from the temporary storage.
+ */
+ protected void finalize()
+ {
+ if (storeLocation != null && storeLocation.exists())
+ {
storeLocation.delete();
}
}
+
/**
- * <p> Returns an identifier that is unique within this turbine
- * instance, but does not have random-like apearance.
+ * Returns an {@link java.io.OutputStream OutputStream} that can
+ * be used for storing the contents of the file.
*
- * @return A String with the non-random looking instance
- * identifier.
+ * @return An {@link java.io.OutputStream OutputStream} that can be used
+ * for storing the contensts of the file.
+ *
+ * @exception IOException if an error occurs.
+ */
+ public OutputStream getOutputStream()
+ throws IOException
+ {
+ if (storeLocation == null)
+ {
+ return byteStream;
+ }
+ else
+ {
+ return new FileOutputStream(storeLocation);
+ }
+ }
+
+
+ /**
+ * Instantiates a DefaultFileItem. It uses <code>requestSize</code> to
+ * decide what temporary storage approach the new item should take.
+ *
+ * @param path The path under which temporary files should be
+ * created.
+ * @param name The original filename in the client's filesystem.
+ * @param contentType The content type passed by the browser, or
+ * <code>null</code> if not defined.
+ * @param requestSize The total size of the POST request this item
+ * belongs to.
+ * @param threshold The maximum size to store in memory.
+ *
+ * @return A <code>DefaultFileItem</code> instance.
+ */
+ public static FileItem newInstance(String path,
+ String name,
+ String contentType,
+ int requestSize,
+ int threshold)
+ {
+ DefaultFileItem item = new DefaultFileItem(name, contentType);
+ if (requestSize > threshold)
+ {
+ String fileName = getUniqueId();
+ fileName = "upload_" + fileName + ".tmp";
+ fileName = path + "/" + fileName;
+ File f = new File(fileName);
+ f.deleteOnExit();
+ item.storeLocation = f;
+ }
+ else
+ {
+ item.byteStream = new ByteArrayOutputStream();
+ }
+ return item;
+ }
+
+
+ // -------------------------------------------------------- Private methods
+
+
+ /**
+ * Returns an identifier that is unique within the class loader used to
+ * load this class, but does not have random-like apearance.
+ *
+ * @return A String with the non-random looking instance identifier.
*/
private static String getUniqueId()
{
int current;
- synchronized(DefaultFileItem.class)
+ synchronized (DefaultFileItem.class)
{
current = counter++;
}
@@ -508,10 +609,11 @@
// If you manage to get more than 100 million of ids, you'll
// start getting ids longer than 8 characters.
- if(current < 100000000)
+ if (current < 100000000)
{
- id = ("00000000"+id).substring(id.length());
+ id = ("00000000" + id).substring(id.length());
}
return id;
}
+
}
1.5 +149 -77 jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload/FileItem.java
Index: FileItem.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload/FileItem.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- FileItem.java 17 Jul 2002 05:14:14 -0000 1.4
+++ FileItem.java 19 Jul 2002 03:56:51 -0000 1.5
@@ -67,142 +67,214 @@
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
-import java.io.OutputStream;
-import javax.activation.DataSource;
/**
- * <p> This class represents a file that was received by Turbine using
+ * <p> This class represents a file or form item that was received within a
* <code>multipart/form-data</code> POST request.
*
- * <p> After retrieving an instance of this class from the {@link
- * org.apache.commons.fileupload.FileUpload FileUpload} (see
+ * <p> After retrieving an instance of this class from a {@link
+ * org.apache.commons.fileupload.FileUpload FileUpload} instance (see
* {@link org.apache.commons.fileupload.FileUpload
- * #parseRequest(javax.servlet.http.HttpServletRequest, String)
- * You may either request all
- * contents of file at once using {@link #get()} or request an {@link
- * java.io.InputStream InputStream} with {@link #getStream()} and
- * process the file without attempting to load it into memory, which
+ * #parseRequest(javax.servlet.http.HttpServletRequest, String)), you may
+ * either request all contents of file at once using {@link #get()} or
+ * request an {@link java.io.InputStream InputStream} with {@link #getStream()}
+ * and process the file without attempting to load it into memory, which
* may come handy with large files.
*
- * Implements the javax.activation.DataSource interface (which allows
- * for example the adding of a FileItem as an attachment to a multipart
- * email).
+ * <p> While this interface does not extend
+ * <code>javax.activation.DataSource</code> per se (to avoid a seldom used
+ * dependency), several of the defined methods are specifically defined with
+ * the same signatures as methods in that interface. This allows an
+ * implementation of this interface to also implement
+ * <code>javax.activation.DataSource</code> with minimal additional work.
*
* @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
* @author <a href="mailto:sean@informage.net">Sean Legassick</a>
* @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
+ * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
+ *
* @version $Id$
*/
public interface FileItem
- extends DataSource
{
+
+
+ // ------------------------------- Methods from javax.activation.DataSource
+
+
/**
- * The maximal size of request that will have it's elements stored
- * in memory.
+ * Returns an {@link java.io.InputStream InputStream} that can be
+ * used to retrieve the contents of the file.
+ *
+ * @return An {@link java.io.InputStream InputStream} that can be
+ * used to retrieve the contents of the file.
+ *
+ * @exception IOException if an error occurs.
*/
- public static final int DEFAULT_UPLOAD_SIZE_THRESHOLD = 10240;
+ InputStream getInputStream()
+ throws IOException;
+
/**
- * Returns the original filename in the user's filesystem.
- * (implements DataSource method)
+ * Returns the content type passed by the browser or <code>null</code> if
+ * not defined.
*
- * @return The original filename in the user's filesystem.
+ * @return The content type passed by the browser or <code>null</code> if
+ * not defined.
*/
- public String getName();
+ String getContentType();
- /**
- * Returns the content type passed by the browser or
- * <code>null</code> if not defined. (implements
- * DataSource method).
- *
- * @return The content type passed by the browser or
- * <code>null</code> if not defined.
- */
- public String getContentType();
/**
- * Provides a hint if the file contents will be read from memory.
+ * Returns the original filename in the client's filesystem.
*
- * @return <code>True</code> if the file contents will be read
+ * @return The original filename in the client's filesystem.
+ */
+ String getName();
+
+
+ // ----------------------------------------------------- Manifest constants
+
+
+ /**
+ * The maximal size of request that will have it's elements stored
+ * in memory.
+ */
+ public static final int DEFAULT_UPLOAD_SIZE_THRESHOLD = 10240;
+
+
+ // ------------------------------------------------------- FileItem methods
+
+
+ /**
+ * Provides a hint as to whether or not the file contents will be read
* from memory.
+ *
+ * @return <code>true</code> if the file contents will be read
+ * from memory.
*/
- public boolean inMemory();
+ boolean isInMemory();
+
/**
* Returns the size of the file.
*
- * @return The size of the file.
+ * @return The size of the file, in bytes.
*/
- public long getSize();
+ long getSize();
+
/**
* Returns the contents of the file as an array of bytes. If the
- * contents of the file were not yet cached int the memory, they
- * will be loaded from the disk storage and chached.
+ * contents of the file were not yet cached in memory, they will be
+ * loaded from the disk storage and cached.
*
* @return The contents of the file as an array of bytes.
*/
- public byte[] get();
+ byte[] get();
+
/**
- * Returns the contents of the file as a String, using specified
- * encoding. This method uses {@link #get()} to retireve the
- * contents of the file.<br>
+ * Returns the contents of the file as a String, using the specified
+ * encoding. This method uses {@link #get()} to retrieve the
+ * contents of the file.
+ *
+ * @param encoding The character encoding to use.
+ *
+ * @return The contents of the file, as a string.
*
- * @param encoding The encoding to use.
- * @return The contents of the file.
- * @exception UnsupportedEncodingException.
+ * @exception UnsupportedEncodingException if the requested character
+ * encoding is not available.
*/
- public String getString( String encoding )
+ String getString(String encoding)
throws UnsupportedEncodingException;
- public String getString();
/**
- * Returns an {@link java.io.InputStream InputStream} that can be
- * used to retrieve the contents of the file. (implements DataSource
- * method)
+ * Returns the contents of the file as a String, using the default
+ * character encoding. This method uses {@link #get()} to retrieve the
+ * contents of the file.
*
- * @return An {@link java.io.InputStream InputStream} that can be
- * used to retrieve the contents of the file.
- * @exception Exception, a generic exception.
+ * @return The contents of the file, as a string.
*/
- public InputStream getInputStream()
- throws IOException;
+ String getString();
+
/**
- * Returns the {@link java.io.File} objects for the DefaultFileItems's
- * data temporary location on the disk. Note that for
- * <code>DefaultFileItems</code> that have their data stored in memory
- * this method will return <code>null</code>. When handling large
+ * Returns the {@link java.io.File} object for the <code>FileItem</code>'s
+ * data's temporary location on the disk. Note that for
+ * <code>FileItem</code>s that have their data stored in memory,
+ * this method will return <code>null</code>. When handling large
* files, you can use {@link java.io.File#renameTo(File)} to
* move the file to new location without copying the data, if the
* source and destination locations reside within the same logical
* volume.
*
- * @return A File.
+ * @return The data file, or <code>null</code> if the data is stored in
+ * memory.
+ */
+ File getStoreLocation();
+
+
+ /**
+ * A convenience method to write an uploaded file to disk. The client code
+ * is not concerned whether or not the file is stored in memory, or on disk
+ * in a temporary location. They just want to write the uploaded file to
+ * disk.
+ *
+ * @param file The full path to location where the uploaded file should
+ * be stored.
+ *
+ * @exception Exception if an error occurs.
+ */
+ void write(String file) throws Exception;
+
+
+ /**
+ * Deletes the underlying storage for a file item, including deleting any
+ * associated temporary disk file. Although this storage will be deleted
+ * automatically when the <code>FileItem</code> instance is garbage
+ * collected, this method can be used to ensure that this is done at an
+ * earlier time, thus preserving system resources.
+ */
+ void delete();
+
+
+ /**
+ * Returns the name of the field in the multipart form corresponding to
+ * this file item.
+ *
+ * @return The name of the form field.
*/
- public File getStoreLocation();
+ String getFieldName();
+
/**
- * A convenience method to write an uploaded
- * file to disk. The client code is not concerned
- * whether or not the file is stored in memory,
- * or on disk in a temporary location. They just
- * want to write the uploaded file to disk.
+ * Sets the field name used to reference this file item.
*
- * @param String full path to location where uploaded
- * should be stored.
+ * @param name The name of the form field.
*/
- public void write(String file) throws Exception;
+ void setFieldName(String name);
+
- public String getFieldName();
+ /**
+ * Determines whether or not a <code>FileItem</code> instance represents
+ * a simple form field.
+ *
+ * @return <code>true</code> if the instance represents a simple form
+ * field; <code>false</code> if it represents an uploaded file.
+ */
+ boolean isFormField();
- public void setFieldName(String name);
- public boolean isFormField();
- public void setIsFormField(boolean state);
+ /**
+ * Specifies whether or not a <code>FileItem</code> instance represents
+ * a simple form field.
+ *
+ * @param state <code>true</code> if the instance represents a simple form
+ * field; <code>false</code> if it represents an uploaded file.
+ */
+ void setIsFormField(boolean state);
- public void delete();
}
1.6 +221 -152 jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload/FileUpload.java
Index: FileUpload.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload/FileUpload.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- FileUpload.java 17 Jul 2002 01:17:06 -0000 1.5
+++ FileUpload.java 19 Jul 2002 03:56:51 -0000 1.6
@@ -70,25 +70,20 @@
import java.util.List;
import java.util.ArrayList;
import java.util.HashMap;
-import java.util.Properties;
-import javax.servlet.ServletContext;
-import javax.servlet.ServletInputStream;
-import javax.servlet.ServletRequest;
import javax.servlet.http.HttpServletRequest;
+
/**
- * <p>High level api for processing file uploads.
+ * <p>High level API for processing file uploads.
*
- * <p>This class handles multiple
- * files per single html widget, sent using multipar/mixed encoding
- * type, as specified by
+ * <p>This class handles multiple files per single HTML widget, sent using
+ * <code>multipar/mixed</code> encoding type, as specified by
* <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>. Use {@link
- * #parseRequest(HttpServletRequest, String)} to
- * acquire a list of {@link
- * org.apache.commons.fileupload.FileItem}s associated with given
- * html widget.
+ * #parseRequest(HttpServletRequest, String)} to acquire a list of {@link
+ * org.apache.commons.fileupload.FileItem}s associated with a given HTML
+ * widget.
*
- * <p> Files will be stored in temporary disk storage on in memory,
+ * <p> Files will be stored in temporary disk storage or in memory,
* depending on request size, and will be available as {@link
* org.apache.commons.fileupload.FileItem}s.
*
@@ -96,106 +91,219 @@
* @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
* @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
* @author <a href="mailto:jmcnally@collab.net">John McNally</a>
+ * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
+ *
* @version $Id$
*/
public class FileUpload
{
+
+ // ----------------------------------------------------- Manifest constants
+
+
/**
- * HTTP header.
+ * HTTP content type header name.
*/
public static final String CONTENT_TYPE = "Content-type";
+
/**
- * HTTP header.
+ * HTTP content disposition header name.
*/
public static final String CONTENT_DISPOSITION = "Content-disposition";
+
/**
- * Content-disposition value.
+ * Content-disposition value for form data.
*/
public static final String FORM_DATA = "form-data";
+
/**
- * Content-disposition value.
+ * Content-disposition value for file attachment.
*/
public static final String ATTACHMENT = "attachment";
+
/**
- * Part of HTTP header.
+ * Part of HTTP content type header.
*/
- private static final String MULTIPART =
- "multipart/";
+ private static final String MULTIPART = "multipart/";
+
/**
- * HTTP header.
+ * HTTP content type header for multipart forms.
*/
- public static final String MULTIPART_FORM_DATA =
- "multipart/form-data";
+ public static final String MULTIPART_FORM_DATA = "multipart/form-data";
+
/**
- * HTTP header.
+ * HTTP content type header for multiple uploads.
*/
public static final String MULTIPART_MIXED = "multipart/mixed";
+
/**
- * A maximum lenght of a single header line that will be
- * parsed. (1024 bytes).
+ * The maximum length of a single header line that will be parsed.
+ * (1024 bytes).
*/
public static final int MAX_HEADER_SIZE = 1024;
- private int sizeMax;
+
+ // ----------------------------------------------------------- Data members
+
+
+ /**
+ * The maximum size permitted for an uploaded file.
+ */
+ private int sizeMax;
+
+
+ /**
+ * The threshold above which uploads will be stored on disk.
+ */
private int sizeThreshold;
+
+
+ /**
+ * The path to which uploaded files will be stored, if stored on disk.
+ */
private String repositoryPath;
+ // ----------------------------------------------------- Property accessors
+
+
+ /**
+ * Returns the maximum allowed upload size.
+ *
+ * @return The maximum allowed size, in bytes.
+ */
+ public int getSizeMax()
+ {
+ return sizeMax;
+ }
+
+
+ /**
+ * Sets the maximum allowed upload size. If negative, there is no maximum.
+ *
+ * @param sizeMax The maximum allowed size, in bytes, or -1 for no maximum.
+ */
+ public void setSizeMax(int sizeMax)
+ {
+ this.sizeMax = sizeMax;
+ }
+
+
+ /**
+ * Returns the size threshold beyond which files are written directly to
+ * disk. The default value is 1024 bytes.
+ *
+ * @return The size threshold, in bytes.
+ */
+ public int getSizeThreshold()
+ {
+ return sizeThreshold;
+ }
+
+
+ /**
+ * Sets the size threshold beyond which files are written directly to disk.
+ *
+ * @param sizeThreshold The size threshold, in bytes.
+ */
+ public void setSizeThreshold(int sizeThreshold)
+ {
+ this.sizeThreshold = sizeThreshold;
+ }
+
+
+ /**
+ * Returns the location used to temporarily store files that are larger
+ * than the configured size threshold.
+ *
+ * @return The path to the temporary file location.
+ */
+ public String getRepositoryPath()
+ {
+ return repositoryPath;
+ }
+
/**
- * <p> Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
- * compliant <code>multipart/form-data</code> stream. if files are
- * stored on disk, the path is given by getRepository()
+ * Sets the location used to temporarily store files that are larger
+ * than the configured size threshold.
+ *
+ * @param repositoryPath The path to the temporary file location.
+ */
+ public void setRepositoryPath(String repositoryPath)
+ {
+ this.repositoryPath = repositoryPath;
+ }
+
+
+ // --------------------------------------------------------- Public methods
+
+
+ /**
+ * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
+ * compliant <code>multipart/form-data</code> stream. If files are stored
+ * on disk, the path is given by <code>getRepositoryPath()</code>.
*
* @param req The servlet request to be parsed.
- * @exception FileUploadException If there are problems reading/parsing
- * the request or storing files.
+ *
+ * @return A list of <code>FileItem</code> instances parsed from the
+ * request, in the order that they were transmitted.
+ *
+ * @exception FileUploadException if there are problems reading/parsing
+ * the request or storing files.
*/
- public List parseRequest(HttpServletRequest req)
+ public List /* FileItem */ parseRequest(HttpServletRequest req)
throws FileUploadException
{
return parseRequest(req, getSizeThreshold(), getSizeMax(),
getRepositoryPath());
}
+
/**
- * <p> Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
- * compliant <code>multipart/form-data</code> stream.
+ * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
+ * compliant <code>multipart/form-data</code> stream. If files are stored
+ * on disk, the path is given by <code>getRepositoryPath()</code>.
*
- * @param req The servlet request to be parsed.
- * @param sizeThreshold the max size in bytes to be stored in memory
- * @param sizeMax the maximum allowed upload size in bytes
- * @param path The location where the files should be stored.
- * @exception FileUploadException If there are problems reading/parsing
- * the request or storing files.
+ * @param req The servlet request to be parsed.
+ * @param sizeThreshold The max size in bytes to be stored in memory.
+ * @param sizeMax The maximum allowed upload size, in bytes.
+ * @param path The location where the files should be stored.
+ *
+ * @return A list of <code>FileItem</code> instances parsed from the
+ * request, in the order that they were transmitted.
+ *
+ * @exception FileUploadException if there are problems reading/parsing
+ * the request or storing files.
*/
- public List parseRequest(HttpServletRequest req, int sizeThreshold,
- int sizeMax, String path)
+ public List /* FileItem */ parseRequest(HttpServletRequest req,
+ int sizeThreshold,
+ int sizeMax, String path)
throws FileUploadException
{
ArrayList items = new ArrayList();
String contentType = req.getHeader(CONTENT_TYPE);
- if(!contentType.startsWith(MULTIPART))
+ if (!contentType.startsWith(MULTIPART))
{
throw new FileUploadException("the request doesn't contain a " +
MULTIPART_FORM_DATA + " or " + MULTIPART_MIXED + " stream");
}
int requestSize = req.getContentLength();
- if(requestSize == -1)
+ if (requestSize == -1)
{
throw new FileUploadException("the request was rejected because " +
"it's size is unknown");
}
- if(sizeMax >= 0 && requestSize > sizeMax)
+ if (sizeMax >= 0 && requestSize > sizeMax)
{
throw new FileUploadException("the request was rejected because " +
"it's size exceeds allowed range");
@@ -204,13 +312,13 @@
try
{
byte[] boundary = contentType.substring(
- contentType.indexOf("boundary=")+9).getBytes();
+ contentType.indexOf("boundary=") + 9).getBytes();
- InputStream input = (InputStream)req.getInputStream();
+ InputStream input = (InputStream) req.getInputStream();
MultipartStream multi = new MultipartStream(input, boundary);
boolean nextPart = multi.skipPreamble();
- while(nextPart)
+ while (nextPart)
{
Map headers = parseHeaders(multi.readHeaders());
String fieldName = getFieldName(headers);
@@ -224,7 +332,7 @@
byte[] subBoundary =
subContentType.substring(
subContentType
- .indexOf("boundary=")+9).getBytes();
+ .indexOf("boundary=") + 9).getBytes();
multi.setBoundary(subBoundary);
boolean nextSubPart = multi.skipPreamble();
while (nextSubPart)
@@ -236,7 +344,7 @@
createItem(sizeThreshold, path,
headers, requestSize);
OutputStream os =
- ((DefaultFileItem)item).getOutputStream();
+ ((DefaultFileItem) item).getOutputStream();
try
{
multi.readBodyData(os);
@@ -267,7 +375,7 @@
path, headers,
requestSize);
OutputStream os =
- ((DefaultFileItem)item).getOutputStream();
+ ((DefaultFileItem) item).getOutputStream();
try
{
multi.readBodyData(os);
@@ -286,7 +394,7 @@
path, headers,
requestSize);
OutputStream os =
- ((DefaultFileItem)item).getOutputStream();
+ ((DefaultFileItem) item).getOutputStream();
try
{
multi.readBodyData(os);
@@ -309,31 +417,37 @@
nextPart = multi.readBoundary();
}
}
- catch(IOException e)
+ catch (IOException e)
{
throw new FileUploadException(
"Processing of " + MULTIPART_FORM_DATA +
- " request failed. " + e.getMessage() );
+ " request failed. " + e.getMessage());
}
return items;
}
+
+ // ------------------------------------------------------ Protected methods
+
+
/**
- * <p> Retrieves file name from <code>Content-disposition</code> header.
+ * Retrieves the file name from the <code>Content-disposition</code>
+ * header.
+ *
+ * @param headers A <code>Map</code> containing the HTTP request headers.
*
- * @param headers The HTTP request headers.
- * @return A the file name for the current <code>encapsulation</code>.
+ * @return The file name for the current <code>encapsulation</code>.
*/
- protected String getFileName(Map headers)
+ protected String getFileName(Map /* String, String */ headers)
{
String fileName = null;
String cd = getHeader(headers, CONTENT_DISPOSITION);
- if(cd.startsWith(FORM_DATA) || cd.startsWith(ATTACHMENT))
+ if (cd.startsWith(FORM_DATA) || cd.startsWith(ATTACHMENT))
{
int start = cd.indexOf("filename=\"");
int end = cd.indexOf('"', start + 10);
- if(start != -1 && end != -1 && (start + 10) != end)
+ if (start != -1 && end != -1 && (start + 10) != end)
{
String str = cd.substring(start + 10, end).trim();
if (str.length() > 0)
@@ -345,21 +459,24 @@
return fileName;
}
+
/**
- * <p> Retrieves field name from <code>Content-disposition</code> header.
+ * Retrieves the field name from the <code>Content-disposition</code>
+ * header.
+ *
+ * @param headers A <code>Map</code> containing the HTTP request headers.
*
- * @param headers The HTTP request headers.
* @return The field name for the current <code>encapsulation</code>.
*/
- protected String getFieldName(Map headers)
+ protected String getFieldName(Map /* String, String */ headers)
{
String fieldName = null;
String cd = getHeader(headers, CONTENT_DISPOSITION);
- if(cd != null && cd.startsWith(FORM_DATA))
+ if (cd != null && cd.startsWith(FORM_DATA))
{
int start = cd.indexOf("name=\"");
int end = cd.indexOf('"', start + 6);
- if(start != -1 && end != -1)
+ if (start != -1 && end != -1)
{
fieldName = cd.substring(start + 6, end);
}
@@ -367,24 +484,28 @@
return fieldName;
}
+
/**
- * <p> Creates a new instance of {@link
- * org.apache.commons.fileupload.FileItem}.
+ * Creates a new {@link org.apache.commons.fileupload.FileItem} instance.
+ *
+ * @param sizeThreshold The max size in bytes to be stored in memory.
+ * @param path The path for the FileItem.
+ * @param headers A <code>Map</code> containing the HTTP request
+ * headers.
+ * @param requestSize The total size of the request, in bytes.
*
- * @param path The path for the FileItem.
- * @param headers The HTTP request headers.
- * @param requestSize The size of the request.
- * @return A newly created <code>FileItem</code>.
- */
- protected FileItem createItem( int sizeThreshold,
- String path,
- Map headers,
- int requestSize )
+ * @return A newly created <code>FileItem</code> instance.
+ */
+ protected FileItem createItem(int sizeThreshold,
+ String path,
+ Map /* String, String */ headers,
+ int requestSize)
{
return DefaultFileItem.newInstance(path, getFileName(headers),
getHeader(headers, CONTENT_TYPE), requestSize, sizeThreshold);
}
+
/**
* <p> Parses the <code>header-part</code> and returns as key/value
* pairs.
@@ -393,10 +514,11 @@
* will map to a comma-separated list containing the values.
*
* @param headerPart The <code>header-part</code> of the current
- * <code>encapsulation</code>.
- * @return The parsed HTTP request headers.
+ * <code>encapsulation</code>.
+ *
+ * @return A <code>Map</code> containing the parsed HTTP request headers.
*/
- protected Map parseHeaders( String headerPart )
+ protected Map /* String, String */ parseHeaders(String headerPart)
{
Map headers = new HashMap();
char buffer[] = new char[MAX_HEADER_SIZE];
@@ -408,14 +530,14 @@
{
while (!done)
{
- i=0;
+ i = 0;
// Copy a single line of characters into the buffer,
// omitting trailing CRLF.
- while (i<2 || buffer[i-2] != '\r' || buffer[i-1] != '\n')
+ while (i < 2 || buffer[i - 2] != '\r' || buffer[i - 1] != '\n')
{
buffer[i++] = headerPart.charAt(j++);
}
- header = new String(buffer, 0, i-2);
+ header = new String(buffer, 0, i - 2);
if (header.equals(""))
{
done = true;
@@ -446,7 +568,7 @@
}
}
}
- catch(IndexOutOfBoundsException e)
+ catch (IndexOutOfBoundsException e)
{
// Headers were malformed. continue with all that was
// parsed.
@@ -454,74 +576,21 @@
return headers;
}
- /**
- * <p> Returns a header with specified name.
- *
- * @param headers The HTTP request headers.
- * @param name The name of the header to fetch.
- * @return The value of specified header, or a comma-separated
- * list if there were multiple headers of that name.
- */
- protected final String getHeader( Map headers, String name )
- {
- return (String)headers.get(name.toLowerCase());
- }
-
- // -------------------------------------------------------------------
- // properties
-
- /**
- * The maximum allowed upload size
- */
- public int getSizeMax()
- {
- return sizeMax;
- }
-
- /**
- * The maximum allowed upload size. If negative there is no
- * maximum.
- */
- public void setSizeMax(int v)
- {
- this.sizeMax = v;
- }
-
/**
- * The threshold beyond which files are written directly to disk.
- * Default is 1024 bytes.
+ * Returns the header with the specified name from the supplied map. The
+ * header lookup is case-insensitive.
+ *
+ * @param headers A <code>Map</code> containing the HTTP request headers.
+ * @param name The name of the header to return.
+ *
+ * @return The value of specified header, or a comma-separated list if
+ * there were multiple headers of that name.
*/
- public int getSizeThreshold()
+ protected final String getHeader(Map /* String, String */ headers,
+ String name)
{
- return sizeThreshold;
+ return (String) headers.get(name.toLowerCase());
}
-
- /**
- * The threshold beyond which files are written directly to disk.
- * Default is 1024 bytes.
- */
- public void setSizeThreshold(int v)
- {
- this.sizeThreshold = v;
- }
-
- /**
- * The location used to temporarily store files that are larger
- * than the size threshold.
- */
- public String getRepositoryPath()
- {
- return repositoryPath;
- }
-
- /**
- * The location used to temporarily store files that are larger
- * than the size threshold.
- */
- public void setRepositoryPath(String v)
- {
- this.repositoryPath = v;
- }
}
1.4 +259 -188 jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload/MultipartStream.java
Index: MultipartStream.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/fileupload/src/java/org/apache/commons/fileupload/MultipartStream.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- MultipartStream.java 17 Jul 2002 01:17:06 -0000 1.3
+++ MultipartStream.java 19 Jul 2002 03:56:51 -0000 1.4
@@ -67,16 +67,17 @@
import java.io.InputStream;
import java.io.OutputStream;
+
/**
- * <p>Low level api for processing file uploads.
+ * <p> Low level API for processing file uploads.
*
- * This class can be used to process data streams conforming to MIME
+ * <p> This class can be used to process data streams conforming to MIME
* 'multipart' format as defined in
- * <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>. Arbitrary
- * large amouns of data in the stream can be processed under constant
+ * <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>. Arbitrarily
+ * large amounts of data in the stream can be processed under constant
* memory usage.
*
- * <p>The format of the stream is defined in the following way:<br>
+ * <p> The format of the stream is defined in the following way:<br>
*
* <code>
* multipart-body := preamble 1*encapsulation close-delimiter epilogue<br>
@@ -123,55 +124,28 @@
* </pre>
*
* @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
+ * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
+ *
* @version $Id$
*/
public class MultipartStream
{
- /**
- * The maximum lenght of <code>header-part</code> that will be
- * processed (10 kilobytes = 10240 bytes.
- )*/
- public static final int HEADER_PART_SIZE_MAX = 10240;
- /** The stream were data is read from. */
- protected InputStream input;
+ // ----------------------------------------------------- Manifest constants
- /**
- * The lenght of boundary token plus leading <code>CRLF--</code>.
- */
- protected int boundaryLength;
/**
- * The amount of data that must be kept in the buffer in order to
- * detect delimiters reliably.
+ * The maximum length of <code>header-part</code> that will be
+ * processed. (10 kilobytes = 10240 bytes.)
*/
- protected int keepRegion;
-
- /** A byte sequence that partitions the stream. */
- protected byte[] boundary;
-
- /** The lenght of the buffer used for processing. */
- protected int bufSize;
-
- /** The default lenght of the buffer used for processing. */
- protected static final int DEFAULT_BUFSIZE = 4096;
+ public static final int HEADER_PART_SIZE_MAX = 10240;
- /** The buffer used for processing. */
- protected byte[] buffer;
/**
- * The index of first valid character in the buffer.
- *
- * 0 <= head < bufSize
+ * The default length of the buffer used for processing a request.
*/
- protected int head;
+ protected static final int DEFAULT_BUFSIZE = 4096;
- /**
- * The index of last valid characer in the buffer + 1.
- *
- * 0 <= tail <= bufSize
- */
- protected int tail;
/**
* A byte sequence that marks the end of <code>header-part</code>
@@ -179,46 +153,104 @@
*/
protected static final byte[] HEADER_SEPARATOR = {0x0D, 0x0A, 0x0D, 0x0A};
+
/**
* A byte sequence that that follows a delimiter that will be
* followed by an encapsulation (<code>CRLF</code>).
*/
protected static final byte[] FIELD_SEPARATOR = { 0x0D, 0x0A };
+
/**
* A byte sequence that that follows a delimiter of the last
* encapsulation in the stream (<code>--</code>).
*/
protected static final byte[] STREAM_TERMINATOR = { 0x2D, 0x2D };
+
+ // ----------------------------------------------------------- Data members
+
+
+ /**
+ * The input stream from which data is read.
+ */
+ private InputStream input;
+
+
+ /**
+ * The length of the boundary token plus the leading <code>CRLF--</code>.
+ */
+ private int boundaryLength;
+
+
+ /**
+ * The amount of data, in bytes, that must be kept in the buffer in order
+ * to detect delimiters reliably.
+ */
+ private int keepRegion;
+
+
+ /**
+ * The byte sequence that partitions the stream.
+ */
+ private byte[] boundary;
+
+
/**
- * Required by the proxy.
+ * The length of the buffer used for processing the request.
+ */
+ private int bufSize;
+
+
+ /**
+ * The buffer used for processing the request.
+ */
+ private byte[] buffer;
+
+
+ /**
+ * The index of first valid character in the buffer.
+ * <br>
+ * 0 <= head < bufSize
+ */
+ private int head;
+
+
+ /**
+ * The index of last valid characer in the buffer + 1.
+ * <br>
+ * 0 <= tail <= bufSize
+ */
+ private int tail;
+
+
+ // ----------------------------------------------------------- Constructors
+
+
+ /**
+ * Default constructor.
*/
public MultipartStream()
{
}
+
/**
- * Constructs a MultipartStream with a custom size buffer.
+ * <p> Constructs a <code>MultipartStream</code> with a custom size buffer.
*
- * <p>Note that the buffer must be at least big enough to contain
- * the boundary string, plus 4 characters for CR/LF and double
- * dash, plus at least one byte of data. Too small buffer size
- * setting will degrade performance.
+ * <p> Note that the buffer must be at least big enough to contain the
+ * boundary string, plus 4 characters for CR/LF and double dash, plus at
+ * least one byte of data. Too small a buffer size setting will degrade
+ * performance.
*
- * @param input The <code>InputStream</code> to serve as a data
- * source.
+ * @param input The <code>InputStream</code> to serve as a data source.
* @param boundary The token used for dividing the stream into
- * <code>encapsulations</code>.
- * @param bufSize The size of the buffer to be used in bytes.
- * @exception MalformedStreamException.
- * @exception IOException.
- */
- public MultipartStream( InputStream input,
- byte[] boundary,
- int bufSize )
- throws MalformedStreamException,
- IOException
+ * <code>encapsulations</code>.
+ * @param bufSize The size of the buffer to be used, in bytes.
+ */
+ public MultipartStream(InputStream input,
+ byte[] boundary,
+ int bufSize)
{
this.input = input;
this.bufSize = bufSize;
@@ -226,9 +258,9 @@
// We prepend CR/LF to the boundary to chop trailng CR/LF from
// body-data tokens.
- this.boundary = new byte[boundary.length+4];
- this.boundaryLength = boundary.length+4;
- this.keepRegion = boundary.length+3;
+ this.boundary = new byte[boundary.length + 4];
+ this.boundaryLength = boundary.length + 4;
+ this.keepRegion = boundary.length + 3;
this.boundary[0] = 0x0D;
this.boundary[1] = 0x0A;
this.boundary[2] = 0x2D;
@@ -239,39 +271,45 @@
tail = 0;
}
+
/**
- * Constructs a MultipartStream with a defalut size buffer.
+ * <p> Constructs a <code>MultipartStream</code> with a default size buffer.
*
- * @param input The <code>InputStream</code> to serve as a data
- * source.
+ * @param input The <code>InputStream</code> to serve as a data source.
* @param boundary The token used for dividing the stream into
- * <code>encapsulations</code>.
- * @exception IOException.
+ * <code>encapsulations</code>.
+ *
+ * @exception IOException when an error occurs.
*/
- public MultipartStream( InputStream input,
- byte[] boundary )
+ public MultipartStream(InputStream input,
+ byte[] boundary)
throws IOException
{
this(input, boundary, DEFAULT_BUFSIZE);
}
+
+ // --------------------------------------------------------- Public methods
+
+
/**
* Reads a byte from the <code>buffer</code>, and refills it as
- * neccessary.
+ * necessary.
*
- * @return Next byte from the input stream.
- * @exception IOException, if there isn't any more data available.
+ * @return The next byte from the input stream.
+ *
+ * @exception IOException if there is no more data available.
*/
public byte readByte()
throws IOException
{
// Buffer depleted ?
- if(head == tail)
+ if (head == tail)
{
head = 0;
// Refill.
tail = input.read(buffer, head, bufSize);
- if(tail == -1)
+ if (tail == -1)
{
// No more data available.
throw new IOException("No more data is available");
@@ -280,14 +318,16 @@
return buffer[head++];
}
+
/**
- * Skips a <code>boundary</code> token, and checks wether more
+ * Skips a <code>boundary</code> token, and checks whether more
* <code>encapsulations</code> are contained in the stream.
*
- * @return <code>True</code> if there are more encapsulations in
- * this stream.
- * @exception MalformedStreamException if the stream ends
- * unexpecetedly or fails to follow required syntax.
+ * @return <code>true</code> if there are more encapsulations in
+ * this stream; <code>false</code> otherwise.
+ *
+ * @exception MalformedStreamException if the stream ends unexpecetedly or
+ * fails to follow required syntax.
*/
public boolean readBoundary()
throws MalformedStreamException
@@ -304,64 +344,69 @@
{
nextChunk = false;
}
- else if(arrayequals(marker, FIELD_SEPARATOR, 2))
+ else if (arrayequals(marker, FIELD_SEPARATOR, 2))
{
nextChunk = true;
}
else
{
- throw new MalformedStreamException("Unexpected characters follow a boundary");
+ throw new MalformedStreamException(
+ "Unexpected characters follow a boundary");
}
}
- catch(IOException e)
+ catch (IOException e)
{
throw new MalformedStreamException("Stream ended unexpectedly");
}
return nextChunk;
}
+
/**
- * Changes the boundary token used for partitioning the stream.
+ * <p>Changes the boundary token used for partitioning the stream.
+ *
+ * <p>This method allows single pass processing of nested multipart
+ * streams.
*
- * <p>This method allows single pass processing of nested
- * multipart streams.
+ * <p>The boundary token of the nested stream is <code>required</code>
+ * to be of the same length as the boundary token in parent stream.
*
- * <p>The boundary token of the nested stream is
- * <code>required</code> to be of the same length as the boundary
- * token in parent stream.
+ * <p>Restoring the parent stream boundary token after processing of a
+ * nested stream is left to the application.
*
- * <p>Restoring parent stream boundary token after processing of a
- * nested stream is left ot the application. <br>
+ * @param boundary The boundary to be used for parsing of the nested
+ * stream.
*
- * @param boundary A boundary to be used for parsing of the nested
- * stream.
- * @exception IllegalBoundaryException, if <code>boundary</code>
- * has diffrent lenght than the one being currently in use.
+ * @exception IllegalBoundaryException if the <code>boundary</code>
+ * has a different length than the one
+ * being currently parsed.
*/
- public void setBoundary( byte[] boundary )
+ public void setBoundary(byte[] boundary)
throws IllegalBoundaryException
{
- if (boundary.length != boundaryLength-4)
+ if (boundary.length != boundaryLength - 4)
{
- throw new IllegalBoundaryException("The length of a boundary token can not be changed");
+ throw new IllegalBoundaryException(
+ "The length of a boundary token can not be changed");
}
System.arraycopy(boundary, 0, this.boundary, 4, boundary.length);
}
+
/**
- * <p>Reads <code>header-part</code> of the current
- * <code>encapsulation</code>
+ * <p>Reads the <code>header-part</code> of the current
+ * <code>encapsulation</code>.
*
- * <p>Headers are returned verbatim to the input stream, including
- * traling <code>CRLF</code> marker. Parsing is left to the
+ * <p>Headers are returned verbatim to the input stream, including the
+ * trailing <code>CRLF</code> marker. Parsing is left to the
* application.
*
* <p><strong>TODO</strong> allow limiting maximum header size to
- * protect against abuse.<br>
+ * protect against abuse.
*
- * @return <code>header-part</code> of the current encapsulation.
- * @exception MalformedStreamException, if the stream ends
- * unexpecetedly.
+ * @return The <code>header-part</code> of the current encapsulation.
+ *
+ * @exception MalformedStreamException if the stream ends unexpecetedly.
*/
public String readHeaders()
throws MalformedStreamException
@@ -371,18 +416,18 @@
StringBuffer buf = new StringBuffer();
int sizeMax = HEADER_PART_SIZE_MAX;
int size = 0;
- while(i<4)
+ while (i < 4)
{
try
{
b[0] = readByte();
}
- catch(IOException e)
+ catch (IOException e)
{
throw new MalformedStreamException("Stream ended unexpectedly");
}
size++;
- if(b[0] == HEADER_SEPARATOR[i])
+ if (b[0] == HEADER_SEPARATOR[i])
{
i++;
}
@@ -390,7 +435,7 @@
{
i = 0;
}
- if(size <= sizeMax)
+ if (size <= sizeMax)
{
buf.append(new String(b));
}
@@ -398,21 +443,24 @@
return buf.toString();
}
+
/**
- * Reads <code>body-data</code> from the current
+ * <p>Reads <code>body-data</code> from the current
* <code>encapsulation</code> and writes its contents into the
* output <code>Stream</code>.
*
- * <p>Arbitrary large amouts of data can be processed by this
+ * <p>Arbitrary large amounts of data can be processed by this
* method using a constant size buffer. (see {@link
* #MultipartStream(InputStream,byte[],int) constructor}).
*
* @param output The <code>Stream</code> to write data into.
+ *
* @return the amount of data written.
- * @exception MalformedStreamException
- * @exception IOException
+ *
+ * @exception MalformedStreamException if the stream ends unexpectedly.
+ * @exception IOException if an i/o error occurs.
*/
- public int readBodyData( OutputStream output )
+ public int readBodyData(OutputStream output)
throws MalformedStreamException,
IOException
{
@@ -421,15 +469,15 @@
int pos;
int bytesRead;
int total = 0;
- while(!done)
+ while (!done)
{
// Is boundary token present somewere in the buffer?
pos = findSeparator();
- if(pos != -1)
+ if (pos != -1)
{
// Write the rest of the data before the boundary.
- output.write(buffer, head, pos-head);
- total += pos-head;
+ output.write(buffer, head, pos - head);
+ total += pos - head;
head = pos;
done = true;
}
@@ -437,39 +485,40 @@
{
// Determine how much data should be kept in the
// buffer.
- if(tail-head>keepRegion)
+ if (tail - head > keepRegion)
{
pad = keepRegion;
}
else
{
- pad = tail-head;
+ pad = tail - head;
}
// Write out the data belonging to the body-data.
- output.write(buffer, head, tail-head-pad);
+ output.write(buffer, head, tail - head - pad);
// Move the data to the beging of the buffer.
- total += tail-head-pad;
- System.arraycopy(buffer, tail-pad, buffer, 0, pad);
+ total += tail - head - pad;
+ System.arraycopy(buffer, tail - pad, buffer, 0, pad);
// Refill buffer with new data.
head = 0;
- bytesRead = input.read(buffer, pad, bufSize-pad);
+ bytesRead = input.read(buffer, pad, bufSize - pad);
// [pprrrrrrr]
- if(bytesRead != -1)
+ if (bytesRead != -1)
{
- tail = pad+bytesRead;
+ tail = pad + bytesRead;
}
else
{
// The last pad amount is left in the buffer.
// Boundary can't be in there so write out the
// data you have and signal an error condition.
- output.write(buffer,0,pad);
+ output.write(buffer, 0, pad);
output.flush();
total += pad;
- throw new MalformedStreamException("Stream ended unexpectedly");
+ throw new MalformedStreamException(
+ "Stream ended unexpectedly");
}
}
}
@@ -477,16 +526,18 @@
return total;
}
+
/**
- * Reads <code>body-data</code> from the current
+ * <p> Reads <code>body-data</code> from the current
* <code>encapsulation</code> and discards it.
*
- * <p>Use this method to skip encapsulations you don't need or
- * don't understand.
+ * <p>Use this method to skip encapsulations you don't need or don't
+ * understand.
*
* @return The amount of data discarded.
- * @exception MalformedStreamException
- * @exception IOException
+ *
+ * @exception MalformedStreamException if the stream ends unexpectedly.
+ * @exception IOException if an i/o error occurs.
*/
public int discardBodyData()
throws MalformedStreamException,
@@ -497,14 +548,14 @@
int pos;
int bytesRead;
int total = 0;
- while(!done)
+ while (!done)
{
// Is boundary token present somewere in the buffer?
pos = findSeparator();
- if(pos != -1)
+ if (pos != -1)
{
// Write the rest of the data before the boundary.
- total += pos-head;
+ total += pos - head;
head = pos;
done = true;
}
@@ -512,27 +563,27 @@
{
// Determine how much data should be kept in the
// buffer.
- if(tail-head>keepRegion)
+ if (tail - head > keepRegion)
{
pad = keepRegion;
}
else
{
- pad = tail-head;
+ pad = tail - head;
}
- total += tail-head-pad;
+ total += tail - head - pad;
// Move the data to the beging of the buffer.
- System.arraycopy(buffer, tail-pad, buffer, 0, pad);
+ System.arraycopy(buffer, tail - pad, buffer, 0, pad);
// Refill buffer with new data.
head = 0;
- bytesRead = input.read(buffer, pad, bufSize-pad);
+ bytesRead = input.read(buffer, pad, bufSize - pad);
// [pprrrrrrr]
- if(bytesRead != -1)
+ if (bytesRead != -1)
{
- tail = pad+bytesRead;
+ tail = pad + bytesRead;
}
else
{
@@ -540,26 +591,29 @@
// Boundary can't be in there so signal an error
// condition.
total += pad;
- throw new MalformedStreamException("Stream ended unexpectedly");
+ throw new MalformedStreamException(
+ "Stream ended unexpectedly");
}
}
}
return total;
}
+
/**
* Finds the beginning of the first <code>encapsulation</code>.
*
- * @return <code>True</code> if an <code>encapsulation</code> was
- * found in the stream.
- * @exception IOException
+ * @return <code>true</code> if an <code>encapsulation</code> was found in
+ * the stream.
+ *
+ * @exception IOException if an i/o error occurs.
*/
public boolean skipPreamble()
throws IOException
{
// First delimiter may be not preceeded with a CRLF.
- System.arraycopy(boundary, 2, boundary, 0, boundary.length-2);
- boundaryLength = boundary.length-2;
+ System.arraycopy(boundary, 2, boundary, 0, boundary.length - 2);
+ boundaryLength = boundary.length - 2;
try
{
// Discard all data up to the delimiter.
@@ -569,37 +623,39 @@
// encapsulation.
return readBoundary();
}
- catch(MalformedStreamException e)
+ catch (MalformedStreamException e)
{
return false;
}
finally
{
// Restore delimiter.
- System.arraycopy(boundary,0, boundary, 2, boundary.length-2);
+ System.arraycopy(boundary, 0, boundary, 2, boundary.length - 2);
boundaryLength = boundary.length;
boundary[0] = 0x0D;
boundary[1] = 0x0A;
}
}
+
/**
* Compares <code>count</code> first bytes in the arrays
* <code>a</code> and <code>b</code>.
*
- * @param a The first array to compare.
- * @param b The second array to compare.
+ * @param a The first array to compare.
+ * @param b The second array to compare.
* @param count How many bytes should be compared.
- * @return <code>true</code> if <code>count</code> first bytes in
- * arrays <code>a</code> and <code>b</code> are equal.
+ *
+ * @return <code>true</code> if <code>count</code> first bytes in arrays
+ * <code>a</code> and <code>b</code> are equal.
*/
- public static boolean arrayequals( byte[] a,
- byte[] b,
- int count )
+ public static boolean arrayequals(byte[] a,
+ byte[] b,
+ int count)
{
- for(int i=0; i<count; i++)
+ for (int i = 0; i < count; i++)
{
- if(a[i] != b[i])
+ if (a[i] != b[i])
{
return false;
}
@@ -607,54 +663,65 @@
return true;
}
+
/**
- * Searches a byte of specified value in the <code>buffer</code>
- * starting at specified <code>position</code>.
+ * Searches for a byte of specified value in the <code>buffer</code>,
+ * starting at the specified <code>position</code>.
+ *
+ * @param value The value to find.
+ * @param pos The starting position for searching.
*
- * @param value the value to find.
- * @param pos The starting position for searching.
- * @return The position of byte found, counting from beginning of
- * the <code>buffer</code>, or <code>-1</code> if not found.
+ * @return The position of byte found, counting from beginning of the
+ * <code>buffer</code>, or <code>-1</code> if not found.
*/
protected int findByte(byte value,
int pos)
{
for (int i = pos; i < tail; i++)
- if(buffer[i] == value)
+ {
+ if (buffer[i] == value)
+ {
return i;
+ }
+ }
- return -1;
+ return -1;
}
+
/**
- * Searches the <code>boundary</code> in <code>buffer</code>
+ * Searches for the <code>boundary</code> in the <code>buffer</code>
* region delimited by <code>head</code> and <code>tail</code>.
*
- * @return The position of the boundary found, counting from
- * beginning of the <code>buffer</code>, or <code>-1</code> if not
- * found.
+ * @return The position of the boundary found, counting from the
+ * beginning of the <code>buffer</code>, or <code>-1</code> if
+ * not found.
*/
protected int findSeparator()
{
int first;
int match = 0;
int maxpos = tail - boundaryLength;
- for(first = head;
- (first <= maxpos) && (match != boundaryLength);
- first++)
+ for (first = head;
+ (first <= maxpos) && (match != boundaryLength);
+ first++)
{
first = findByte(boundary[0], first);
- if(first == -1 || (first > maxpos))
+ if (first == -1 || (first > maxpos))
+ {
return -1;
- for(match = 1; match<boundaryLength; match++)
+ }
+ for (match = 1; match < boundaryLength; match++)
{
- if(buffer[first+match] != boundary[match])
+ if (buffer[first + match] != boundary[match])
+ {
break;
+ }
}
}
- if(match == boundaryLength)
+ if (match == boundaryLength)
{
- return first-1;
+ return first - 1;
}
return -1;
}
@@ -688,6 +755,7 @@
}
}
+
/**
* Thrown upon attempt of setting an invalid boundary token.
*/
@@ -715,9 +783,12 @@
}
}
- /*-------------------------------------------------------------
+
+ // ------------------------------------------------------ Debugging methods
+
// These are the methods that were used to debug this stuff.
+ /*
// Dump data.
protected void dump()
@@ -726,7 +797,7 @@
byte[] temp = new byte[buffer.length];
for(int i=0; i<buffer.length; i++)
{
- if(buffer[i] == 0x0D || buffer[i] == 0x0A)
+ if (buffer[i] == 0x0D || buffer[i] == 0x0A)
{
temp[i] = 0x21;
}
@@ -737,10 +808,10 @@
}
System.out.println(new String(temp));
int i;
- for(i=0; i<head; i++)
+ for (i=0; i<head; i++)
System.out.print(" ");
System.out.println("h");
- for(i=0; i<tail; i++)
+ for (i=0; i<tail; i++)
System.out.print(" ");
System.out.println("t");
System.out.flush();
@@ -766,7 +837,7 @@
String header;
OutputStream output;
boolean nextChunk = chunks.skipPreamble();
- while(nextChunk)
+ while (nextChunk)
{
header = chunks.readHeaders();
System.out.println("!"+header+"!");
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>