This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-fileupload.git
commit e40a6e2dba3a102a48bfb9790fad191e35f55e0b Author: Gary Gregory <[email protected]> AuthorDate: Mon Apr 3 08:02:25 2023 -0400 Javadoc --- .../org/apache/commons/fileupload2/FileItem.java | 127 ++++++++------------- .../commons/fileupload2/FileItemFactory.java | 23 ++-- .../commons/fileupload2/FileItemHeaders.java | 42 +++---- .../fileupload2/FileItemHeadersSupport.java | 8 +- .../commons/fileupload2/FileItemIterator.java | 21 +++- .../apache/commons/fileupload2/FileItemStream.java | 22 ++-- .../org/apache/commons/fileupload2/FileUpload.java | 5 +- .../apache/commons/fileupload2/FileUploadBase.java | 83 ++++++-------- .../fileupload2/InvalidFileNameException.java | 6 +- .../commons/fileupload2/MultipartStream.java | 61 ++++------ .../commons/fileupload2/ParameterParser.java | 17 +-- .../commons/fileupload2/ProgressListener.java | 2 +- .../apache/commons/fileupload2/RequestContext.java | 8 +- .../apache/commons/fileupload2/UploadContext.java | 2 +- .../commons/fileupload2/disk/DiskFileItem.java | 43 +++---- 15 files changed, 192 insertions(+), 278 deletions(-) diff --git a/src/main/java/org/apache/commons/fileupload2/FileItem.java b/src/main/java/org/apache/commons/fileupload2/FileItem.java index 997316f..ad8d28d 100644 --- a/src/main/java/org/apache/commons/fileupload2/FileItem.java +++ b/src/main/java/org/apache/commons/fileupload2/FileItem.java @@ -24,35 +24,28 @@ import java.io.UncheckedIOException; import java.io.UnsupportedEncodingException; /** - * <p> This class represents a file or form item that was received within a - * {@code multipart/form-data} POST request. - * - * <p> After retrieving an instance of this class from a {@link - * org.apache.commons.fileupload2.FileUpload FileUpload} instance (see - * {@link org.apache.commons.fileupload2.servlet.ServletFileUpload - * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may - * either request all contents of the file at once using {@link #get()} or - * request an {@link java.io.InputStream InputStream} with - * {@link #getInputStream()} and process the file without attempting to load - * it into memory, which may come handy with large files. - * - * <p> While this interface does not extend - * {@code javax.activation.DataSource} 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 + * <p> + * This class represents a file or form item that was received within a {@code multipart/form-data} POST request. + * </p> + * <p> + * After retrieving an instance of this class from a {@link org.apache.commons.fileupload2.FileUpload FileUpload} instance (see + * {@link org.apache.commons.fileupload2.servlet.ServletFileUpload #parseRequest(javax.servlet.http.HttpServletRequest)}), you may either request all contents + * of the file at once using {@link #get()} or request an {@link java.io.InputStream InputStream} with {@link #getInputStream()} and process the file without + * attempting to load it into memory, which may come handy with large files. + * </p> + * <p> + * While this interface does not extend {@code javax.activation.DataSource} 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} with minimal additional work. - * + * </p> * @since 1.3 additionally implements FileItemHeadersSupport */ public interface FileItem extends FileItemHeadersSupport { /** - * 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} instance is garbage - * collected, this method can be used to ensure that this is done at an - * earlier time, thus preserving system resources. + * 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} 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(); @@ -66,104 +59,85 @@ public interface FileItem extends FileItemHeadersSupport { byte[] get() throws UncheckedIOException; /** - * Returns the content type passed by the browser or {@code null} if - * not defined. + * Gets the content type passed by the browser or {@code null} if not defined. * - * @return The content type passed by the browser or {@code null} if - * not defined. + * @return The content type passed by the browser or {@code null} if not defined. */ String getContentType(); /** - * Returns the name of the field in the multipart form corresponding to - * this file item. + * Gets the name of the field in the multipart form corresponding to this file item. * * @return The name of the form field. */ String getFieldName(); /** - * Returns an {@link java.io.InputStream InputStream} that can be - * used to retrieve the contents of the file. + * Gets 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 An {@link java.io.InputStream InputStream} that can be used to retrieve the contents of the file. * * @throws IOException if an error occurs. */ InputStream getInputStream() throws IOException; /** - * Returns the original file name in the client's file system, as provided by - * the browser (or other client software). In most cases, this will be the - * base file name, without path information. However, some clients, such as - * the Opera browser, do include path information. + * Gets the original file name in the client's file system, as provided by the browser (or other client software). In most cases, this will be the base file + * name, without path information. However, some clients, such as the Opera browser, do include path information. * * @return The original file name in the client's file system. - * @throws InvalidFileNameException The file name contains a NUL character, - * which might be an indicator of a security attack. If you intend to - * use the file name anyways, catch the exception and use - * InvalidFileNameException#getName(). + * @throws InvalidFileNameException The file name contains a NUL character, which might be an indicator of a security attack. If you intend to use the file + * name anyways, catch the exception and use InvalidFileNameException#getName(). */ String getName(); /** - * Returns an {@link java.io.OutputStream OutputStream} that can - * be used for storing the contents of the file. + * Gets an {@link java.io.OutputStream OutputStream} that can be used for storing the contents of the file. * - * @return An {@link java.io.OutputStream OutputStream} that can be used - * for storing the contents of the file. + * @return An {@link java.io.OutputStream OutputStream} that can be used for storing the contents of the file. * * @throws IOException if an error occurs. */ OutputStream getOutputStream() throws IOException; /** - * Returns the size of the file item. + * Gets the size of the file item. * * @return The size of the file item, in bytes. */ long getSize(); /** - * Returns the contents of the file item as a String, using the default - * character encoding. This method uses {@link #get()} to retrieve the - * contents of the item. + * Gets the contents of the file item as a String, using the default character encoding. This method uses {@link #get()} to retrieve the contents of the + * item. * * @return The contents of the item, as a string. */ String getString(); /** - * Returns the contents of the file item as a String, using the specified - * encoding. This method uses {@link #get()} to retrieve the - * contents of the item. + * Gets the contents of the file item as a String, using the specified encoding. This method uses {@link #get()} to retrieve the contents of the item. * * @param encoding The character encoding to use. * * @return The contents of the item, as a string. * - * @throws UnsupportedEncodingException if the requested character - * encoding is not available. - * @throws IOException if an I/O error occurs + * @throws UnsupportedEncodingException if the requested character encoding is not available. + * @throws IOException if an I/O error occurs */ String getString(String encoding) throws UnsupportedEncodingException, IOException; /** - * Determines whether or not a {@code FileItem} instance represents - * a simple form field. + * Tests whether or not a {@code FileItem} instance represents a simple form field. * - * @return {@code true} if the instance represents a simple form - * field; {@code false} if it represents an uploaded file. + * @return {@code true} if the instance represents a simple form field; {@code false} if it represents an uploaded file. */ boolean isFormField(); /** - * Provides a hint as to whether or not the file contents will be read - * from memory. + * Tests a hint as to whether or not the file contents will be read from memory. * - * @return {@code true} if the file contents will be read from memory; - * {@code false} otherwise. + * @return {@code true} if the file contents will be read from memory; {@code false} otherwise. */ boolean isInMemory(); @@ -175,28 +149,23 @@ public interface FileItem extends FileItemHeadersSupport { void setFieldName(String name); /** - * Specifies whether or not a {@code FileItem} instance represents - * a simple form field. + * Sets whether or not a {@code FileItem} instance represents a simple form field. * - * @param state {@code true} if the instance represents a simple form - * field; {@code false} if it represents an uploaded file. + * @param state {@code true} if the instance represents a simple form field; {@code false} if it represents an uploaded file. */ void setFormField(boolean state); /** - * A convenience method to write an uploaded item to disk. The client code - * is not concerned with whether or not the item is stored in memory, or on - * disk in a temporary location. They just want to write the uploaded item - * to a file. + * Writes an uploaded item to disk. * <p> - * This method is not guaranteed to succeed if called more than once for - * the same item. This allows a particular implementation to use, for - * example, file renaming, where possible, rather than copying all of the - * underlying data, thus gaining a significant performance benefit. - * - * @param file The {@code File} into which the uploaded item should - * be stored. - * + * The client code is not concerned with whether or not the item is stored in memory, or on disk in a temporary location. They just want to write the + * uploaded item to a file. + * </p> + * <p> + * This method is not guaranteed to succeed if called more than once for the same item. This allows a particular implementation to use, for example, file + * renaming, where possible, rather than copying all of the underlying data, thus gaining a significant performance benefit. + * </p> + * @param file The {@code File} into which the uploaded item should be stored. * @throws IOException if an error occurs. */ void write(File file) throws IOException; diff --git a/src/main/java/org/apache/commons/fileupload2/FileItemFactory.java b/src/main/java/org/apache/commons/fileupload2/FileItemFactory.java index 1ea59cd..40a249f 100644 --- a/src/main/java/org/apache/commons/fileupload2/FileItemFactory.java +++ b/src/main/java/org/apache/commons/fileupload2/FileItemFactory.java @@ -17,30 +17,23 @@ package org.apache.commons.fileupload2; /** - * <p>A factory interface for creating {@link FileItem} instances. Factories - * can provide their own custom configuration, over and above that provided - * by the default file upload implementation.</p> + * Creates {@link FileItem} instances. + * <p> + * Factories can provide their own custom configuration, over and above that provided by the default file upload implementation. + * </p> */ public interface FileItemFactory { /** - * Create a new {@link FileItem} instance from the supplied parameters and - * any local factory configuration. + * Creates a new {@link FileItem} instance from the supplied parameters and any local factory configuration. * * @param fieldName The name of the form field. * @param contentType The content type of the form field. - * @param isFormField {@code true} if this is a plain form field; - * {@code false} otherwise. - * @param fileName The name of the uploaded file, if any, as supplied - * by the browser or other client. + * @param isFormField {@code true} if this is a plain form field; {@code false} otherwise. + * @param fileName The name of the uploaded file, if any, as supplied by the browser or other client. * * @return The newly created file item. */ - FileItem createItem( - String fieldName, - String contentType, - boolean isFormField, - String fileName - ); + FileItem createItem(String fieldName, String contentType, boolean isFormField, String fileName); } diff --git a/src/main/java/org/apache/commons/fileupload2/FileItemHeaders.java b/src/main/java/org/apache/commons/fileupload2/FileItemHeaders.java index d41b7fc..ab258da 100644 --- a/src/main/java/org/apache/commons/fileupload2/FileItemHeaders.java +++ b/src/main/java/org/apache/commons/fileupload2/FileItemHeaders.java @@ -19,55 +19,41 @@ package org.apache.commons.fileupload2; import java.util.Iterator; /** - * <p> This class provides support for accessing the headers for a file or form - * item that was received within a {@code multipart/form-data} POST - * request.</p> + * This class provides support for accessing the headers for a file or form item that was received within a {@code multipart/form-data} POST request. * * @since 1.2.1 */ public interface FileItemHeaders { /** - * Returns the value of the specified part header as a {@code String}. - * - * If the part did not include a header of the specified name, this method - * return {@code null}. If there are multiple headers with the same - * name, this method returns the first header in the item. The header - * name is case insensitive. + * Gets the value of the specified part header as a {@code String}. + * <p> + * If the part did not include a header of the specified name, this method return {@code null}. If there are multiple headers with the same name, this + * method returns the first header in the item. The header name is case insensitive. + * </p> * * @param name a {@code String} specifying the header name - * @return a {@code String} containing the value of the requested - * header, or {@code null} if the item does not have a header - * of that name + * @return a {@code String} containing the value of the requested header, or {@code null} if the item does not have a header of that name */ String getHeader(String name); /** - * <p> - * Returns an {@code Iterator} of all the header names. - * </p> + * Gets an {@code Iterator} of all the header names. * - * @return an {@code Iterator} containing all of the names of - * headers provided with this file item. If the item does not have - * any headers return an empty {@code Iterator} + * @return an {@code Iterator} containing all of the names of headers provided with this file item. If the item does not have any headers return an empty + * {@code Iterator} */ Iterator<String> getHeaderNames(); /** + * Gets all the values of the specified item header as an {@code Iterator} of {@code String} objects. * <p> - * Returns all the values of the specified item header as an - * {@code Iterator} of {@code String} objects. - * </p> - * <p> - * If the item did not include any headers of the specified name, this - * method returns an empty {@code Iterator}. The header name is - * case insensitive. + * If the item did not include any headers of the specified name, this method returns an empty {@code Iterator}. The header name is case insensitive. * </p> * * @param name a {@code String} specifying the header name - * @return an {@code Iterator} containing the values of the - * requested header. If the item does not have any headers of - * that name, return an empty {@code Iterator} + * @return an {@code Iterator} containing the values of the requested header. If the item does not have any headers of that name, return an empty + * {@code Iterator} */ Iterator<String> getHeaders(String name); diff --git a/src/main/java/org/apache/commons/fileupload2/FileItemHeadersSupport.java b/src/main/java/org/apache/commons/fileupload2/FileItemHeadersSupport.java index 8e7d649..a71553a 100644 --- a/src/main/java/org/apache/commons/fileupload2/FileItemHeadersSupport.java +++ b/src/main/java/org/apache/commons/fileupload2/FileItemHeadersSupport.java @@ -17,18 +17,16 @@ package org.apache.commons.fileupload2; /** - * Interface that will indicate that {@link FileItem} or {@link FileItemStream} - * implementations will accept the headers read for the item. - * - * @since 1.2.1 + * Accepts headers for an item type. * * @see FileItem * @see FileItemStream + * @since 1.2.1 */ public interface FileItemHeadersSupport { /** - * Returns the collection of headers defined locally within this item. + * Gets the collection of headers defined locally within this item. * * @return the {@link FileItemHeaders} present for this item. */ diff --git a/src/main/java/org/apache/commons/fileupload2/FileItemIterator.java b/src/main/java/org/apache/commons/fileupload2/FileItemIterator.java index 1fa5f5d..5ac94eb 100644 --- a/src/main/java/org/apache/commons/fileupload2/FileItemIterator.java +++ b/src/main/java/org/apache/commons/fileupload2/FileItemIterator.java @@ -28,9 +28,11 @@ import org.apache.commons.fileupload2.pub.FileUploadByteCountLimitException; * {@link FileUploadBase#getItemIterator(RequestContext)}. */ public interface FileItemIterator { + List<FileItem> getFileItems() throws FileUploadException, IOException; - /** Returns the maximum size of a single file. An {@link FileUploadByteCountLimitException} + /** + * Gets the maximum size of a single file. An {@link FileUploadByteCountLimitException} * will be thrown, if there is an uploaded file, which is exceeding this value. * By default, this value will be copied from the {@link FileUploadBase#getFileSizeMax() * FileUploadBase} object, however, the user may replace the default value with a @@ -39,7 +41,8 @@ public interface FileItemIterator { */ long getFileSizeMax(); - /** Returns the maximum size of the complete HTTP request. A {@link SizeLimitExceededException} + /** + * Gets the maximum size of the complete HTTP request. A {@link SizeLimitExceededException} * will be thrown, if the HTTP request will exceed this value. * By default, this value will be copied from the {@link FileUploadBase#getSizeMax() * FileUploadBase} object, however, the user may replace the default value with a @@ -49,7 +52,7 @@ public interface FileItemIterator { long getSizeMax(); /** - * Returns, whether another instance of {@link FileItemStream} + * Tests whether another instance of {@link FileItemStream} * is available. * * @throws FileUploadException Parsing or processing the @@ -73,25 +76,31 @@ public interface FileItemIterator { */ FileItemStream next() throws FileUploadException, IOException; - /** Sets the maximum size of a single file. An {@link FileUploadByteCountLimitException} + /** + * Sets the maximum size of a single file. An {@link FileUploadByteCountLimitException} * will be thrown, if there is an uploaded file, which is exceeding this value. * By default, this value will be copied from the {@link FileUploadBase#getFileSizeMax() * FileUploadBase} object, however, the user may replace the default value with a * request specific value by invoking {@link #setFileSizeMax(long)} on this object, so * there is no need to configure it here. - * <em>Note:</em>Changing this value doesn't affect files, that have already been uploaded. + * <p> + * <em>Note:</em> Changing this value doesn't affect files, that have already been uploaded. + * </p> * @param pFileSizeMax The maximum size of a single, uploaded file. The value -1 indicates "unlimited". */ void setFileSizeMax(long pFileSizeMax); - /** Returns the maximum size of the complete HTTP request. A {@link SizeLimitExceededException} + /** + * Sets the maximum size of the complete HTTP request. A {@link SizeLimitExceededException} * will be thrown, if the HTTP request will exceed this value. * By default, this value will be copied from the {@link FileUploadBase#getSizeMax() * FileUploadBase} object, however, the user may replace the default value with a * request specific value by invoking {@link #setSizeMax(long)} on this object. + * <p> * <em>Note:</em> Setting the maximum size on this object will work only, if the iterator is not * yet initialized. In other words: If the methods {@link #hasNext()}, {@link #next()} have not * yet been invoked. + * </p> * @param pSizeMax The maximum size of the complete HTTP request. The value -1 indicates "unlimited". */ void setSizeMax(long pSizeMax); diff --git a/src/main/java/org/apache/commons/fileupload2/FileItemStream.java b/src/main/java/org/apache/commons/fileupload2/FileItemStream.java index 02b9bd6..c936f84 100644 --- a/src/main/java/org/apache/commons/fileupload2/FileItemStream.java +++ b/src/main/java/org/apache/commons/fileupload2/FileItemStream.java @@ -20,16 +20,20 @@ import java.io.IOException; import java.io.InputStream; /** - * <p> This interface provides access to a file or form item that was + * Provides access to a file or form item that was * received within a {@code multipart/form-data} POST request. - * The items contents are retrieved by calling {@link #openStream()}.</p> + * <p> + * The items contents are retrieved by calling {@link #openStream()}. + * </p> * <p>Instances of this class are created by accessing the * iterator, returned by - * {@link FileUploadBase#getItemIterator(RequestContext)}.</p> + * {@link FileUploadBase#getItemIterator(RequestContext)}. + * </p> * <p><em>Note</em>: There is an interaction between the iterator and * its associated instances of {@link FileItemStream}: By invoking * {@link java.util.Iterator#hasNext()} on the iterator, you discard all data, - * which hasn't been read so far from the previous data.</p> + * which hasn't been read so far from the previous data. + * </p> */ public interface FileItemStream extends FileItemHeadersSupport { @@ -51,7 +55,7 @@ public interface FileItemStream extends FileItemHeadersSupport { } /** - * Returns the content type passed by the browser or {@code null} if + * Gets the content type passed by the browser or {@code null} if * not defined. * * @return The content type passed by the browser or {@code null} if @@ -60,7 +64,7 @@ public interface FileItemStream extends FileItemHeadersSupport { String getContentType(); /** - * Returns the name of the field in the multipart form corresponding to + * Gets the name of the field in the multipart form corresponding to * this file item. * * @return The name of the form field. @@ -68,7 +72,7 @@ public interface FileItemStream extends FileItemHeadersSupport { String getFieldName(); /** - * Returns the original file name in the client's file system, as provided by + * Gets the original file name in the client's file system, as provided by * the browser (or other client software). In most cases, this will be the * base file name, without path information. However, some clients, such as * the Opera browser, do include path information. @@ -78,7 +82,7 @@ public interface FileItemStream extends FileItemHeadersSupport { String getName(); /** - * Determines whether or not a {@code FileItem} instance represents + * Tests whether or not a {@code FileItem} instance represents * a simple form field. * * @return {@code true} if the instance represents a simple form @@ -87,7 +91,7 @@ public interface FileItemStream extends FileItemHeadersSupport { boolean isFormField(); /** - * Creates an {@link InputStream}, which allows to read the + * Opens an {@link InputStream}, which allows to read the * items contents. * * @return The input stream, from which the items data may diff --git a/src/main/java/org/apache/commons/fileupload2/FileUpload.java b/src/main/java/org/apache/commons/fileupload2/FileUpload.java index 1c8bf28..95c53e8 100644 --- a/src/main/java/org/apache/commons/fileupload2/FileUpload.java +++ b/src/main/java/org/apache/commons/fileupload2/FileUpload.java @@ -30,8 +30,7 @@ package org.apache.commons.fileupload2; * used to create them; a given part may be in memory, on disk, or somewhere * else.</p> */ -public class FileUpload - extends FileUploadBase { +public class FileUpload extends FileUploadBase { /** * The factory to use to create new form items. @@ -62,7 +61,7 @@ public class FileUpload } /** - * Returns the factory class used when creating file items. + * Gets the factory class used when creating file items. * * @return The factory class for new file items. */ diff --git a/src/main/java/org/apache/commons/fileupload2/FileUploadBase.java b/src/main/java/org/apache/commons/fileupload2/FileUploadBase.java index 6e90d4f..5f35d1d 100644 --- a/src/main/java/org/apache/commons/fileupload2/FileUploadBase.java +++ b/src/main/java/org/apache/commons/fileupload2/FileUploadBase.java @@ -35,18 +35,20 @@ import org.apache.commons.fileupload2.util.FileItemHeadersImpl; import org.apache.commons.io.IOUtils; /** - * <p>High level API for processing file uploads.</p> - * - * <p>This class handles multiple files per single HTML widget, sent using + * High level API for processing file uploads. + * <p> + * This class handles multiple files per single HTML widget, sent using * {@code multipart/mixed} encoding type, as specified by * <a href="http://www.ietf.org/rfc/rfc1867.txt";>RFC 1867</a>. Use {@link * #parseRequest(RequestContext)} to acquire a list of {@link * org.apache.commons.fileupload2.FileItem}s associated with a given HTML - * widget.</p> - * - * <p>How the data for individual parts is stored is determined by the factory + * widget. + * </p> + * <p> + * How the data for individual parts is stored is determined by the factory * used to create them; a given part may be in memory, on disk, or somewhere - * else.</p> + * else. + * </p> */ public abstract class FileUploadBase { @@ -91,16 +93,15 @@ public abstract class FileUploadBase { public static final String MULTIPART_MIXED = "multipart/mixed"; /** - * <p>Utility method that determines whether the request contains multipart - * content.</p> - * - * <p><strong>NOTE:</strong>This method will be moved to the + * Utility method that determines whether the request contains multipart + * content. + * <p> + * <strong>NOTE:</strong> This method will be moved to the * {@code ServletFileUpload} class after the FileUpload 1.1 release. * Unfortunately, since this method is static, it is not possible to - * provide its replacement until this method is removed.</p> - * + * provide its replacement until this method is removed. + * </p> * @param ctx The request context to be evaluated. Must be non-null. - * * @return {@code true} if the request is multipart; * {@code false} otherwise. */ @@ -141,11 +142,10 @@ public abstract class FileUploadBase { private ProgressListener listener; /** - * Retrieves the boundary from the {@code Content-type} header. + * Gets the boundary from the {@code Content-type} header. * * @param contentType The value of the content type header from which to * extract the boundary value. - * * @return The boundary, as a byte array. */ public byte[] getBoundary(final String contentType) { @@ -164,11 +164,10 @@ public abstract class FileUploadBase { } /** - * Retrieves the field name from the {@code Content-disposition} + * Gets the field name from the {@code Content-disposition} * header. * * @param headers A {@code Map} containing the HTTP request headers. - * * @return The field name for the current {@code encapsulation}. */ public String getFieldName(final FileItemHeaders headers) { @@ -176,8 +175,9 @@ public abstract class FileUploadBase { } /** - * Returns the field name, which is given by the content-disposition + * Gets the field name, which is given by the content-disposition * header. + * * @param pContentDisposition The content-dispositions header value. * @return The field jake */ @@ -198,7 +198,7 @@ public abstract class FileUploadBase { } /** - * Returns the maximum number of files allowed in a single request. + * Gets the maximum number of files allowed in a single request. * * @return The maximum number of files allowed in a single request. */ @@ -207,14 +207,14 @@ public abstract class FileUploadBase { } /** - * Returns the factory class used when creating file items. + * Gets the factory class used when creating file items. * * @return The factory class for new file items. */ public abstract FileItemFactory getFileItemFactory(); /** - * Retrieves the file name from the {@code Content-disposition} + * Gets the file name from the {@code Content-disposition} * header. * * @param headers The HTTP headers object. @@ -226,7 +226,7 @@ public abstract class FileUploadBase { } /** - * Returns the given content-disposition headers file name. + * Gets the given content-disposition headers file name. * @param pContentDisposition The content-disposition headers value. * @return The file name */ @@ -256,7 +256,7 @@ public abstract class FileUploadBase { } /** - * Returns the maximum allowed size of a single uploaded file, + * Gets the maximum allowed size of a single uploaded file, * as opposed to {@link #getSizeMax()}. * * @see #setFileSizeMax(long) @@ -267,7 +267,7 @@ public abstract class FileUploadBase { } /** - * Retrieves the character encoding used when reading the headers of an + * Gets the character encoding used when reading the headers of an * individual part. When not specified, or {@code null}, the request * encoding is used. If that is also not specified, or {@code null}, * the platform default encoding is used. @@ -279,15 +279,13 @@ public abstract class FileUploadBase { } /** - * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt";>RFC 1867</a> + * Gets an <a href="http://www.ietf.org/rfc/rfc1867.txt";>RFC 1867</a> * compliant {@code multipart/form-data} stream. * * @param ctx The context for the request to be parsed. - * * @return An iterator to instances of {@code FileItemStream} * parsed from the request, in the order that they were * transmitted. - * * @throws FileUploadException if there are problems reading/parsing * the request or storing files. * @throws IOException An I/O error occurred. This may be a network @@ -299,15 +297,14 @@ public abstract class FileUploadBase { } /** - * <p> Parses the {@code header-part} and returns as key/value + * Parses the {@code header-part} and returns as key/value * pairs. - * - * <p> If there are multiple headers of the same names, the name + * <p> + * If there are multiple headers of the same names, the name * will map to a comma-separated list containing the values. - * + * </p> * @param headerPart The {@code header-part} of the current * {@code encapsulation}. - * * @return A {@code Map} containing the parsed HTTP request headers. */ public FileItemHeaders getParsedHeaders(final String headerPart) { @@ -344,7 +341,7 @@ public abstract class FileUploadBase { } /** - * Returns the progress listener. + * Gets the progress listener. * * @return The progress listener, if any, or null. */ @@ -353,12 +350,11 @@ public abstract class FileUploadBase { } /** - * Returns the maximum allowed size of a complete request, as opposed + * Gets the maximum allowed size of a complete request, as opposed * to {@link #getFileSizeMax()}. * * @return The maximum allowed size, in bytes. The default value of * -1 indicates, that there is no limit. - * * @see #setSizeMax(long) * */ @@ -376,6 +372,7 @@ public abstract class FileUploadBase { /** * Skips bytes until the end of the current line. + * * @param headerPart The headers, which are being parsed. * @param end Index of the last byte, which has yet been * processed. @@ -398,7 +395,8 @@ public abstract class FileUploadBase { } /** - * Reads the next header line. + * Parses the next header line. + * * @param headers String with all headers. * @param header Map where to store the current header. */ @@ -415,16 +413,13 @@ public abstract class FileUploadBase { } /** - * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt";>RFC 1867</a> + * Parses an <a href="http://www.ietf.org/rfc/rfc1867.txt";>RFC 1867</a> * compliant {@code multipart/form-data} stream. * * @param ctx The context for the request to be parsed. - * * @return A map of {@code FileItem} instances parsed from the request. - * * @throws FileUploadException if there are problems reading/parsing * the request or storing files. - * * @since 1.3 */ public Map<String, List<FileItem>> parseParameterMap(final RequestContext ctx) @@ -443,14 +438,12 @@ public abstract class FileUploadBase { } /** - * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt";>RFC 1867</a> + * Parses an <a href="http://www.ietf.org/rfc/rfc1867.txt";>RFC 1867</a> * compliant {@code multipart/form-data} stream. * * @param ctx The context for the request to be parsed. - * * @return A list of {@code FileItem} instances parsed from the * request, in the order that they were transmitted. - * * @throws FileUploadException if there are problems reading/parsing * the request or storing files. */ @@ -555,9 +548,7 @@ public abstract class FileUploadBase { * * @param sizeMax The maximum allowed size, in bytes. The default value of * -1 indicates, that there is no limit. - * * @see #getSizeMax() - * */ public void setSizeMax(final long sizeMax) { this.sizeMax = sizeMax; diff --git a/src/main/java/org/apache/commons/fileupload2/InvalidFileNameException.java b/src/main/java/org/apache/commons/fileupload2/InvalidFileNameException.java index 51eeda0..f6bb11e 100644 --- a/src/main/java/org/apache/commons/fileupload2/InvalidFileNameException.java +++ b/src/main/java/org/apache/commons/fileupload2/InvalidFileNameException.java @@ -17,7 +17,7 @@ package org.apache.commons.fileupload2; /** - * This exception is thrown in case of an invalid file name. + * Signals an invalid file name. * A file name is invalid, if it contains a NUL character. * Attackers might use this to circumvent security checks: * For example, a malicious user might upload a file with the name @@ -40,7 +40,7 @@ public class InvalidFileNameException extends RuntimeException { private final String name; /** - * Creates a new instance. + * Constructs a new instance. * * @param pName The file name causing the exception. * @param pMessage A human readable error message. @@ -51,7 +51,7 @@ public class InvalidFileNameException extends RuntimeException { } /** - * Returns the invalid file name. + * Gets the invalid file name. * * @return the invalid file name. */ diff --git a/src/main/java/org/apache/commons/fileupload2/MultipartStream.java b/src/main/java/org/apache/commons/fileupload2/MultipartStream.java index 9acea9f..9ce56a7 100644 --- a/src/main/java/org/apache/commons/fileupload2/MultipartStream.java +++ b/src/main/java/org/apache/commons/fileupload2/MultipartStream.java @@ -29,16 +29,15 @@ import org.apache.commons.io.IOUtils; import org.apache.commons.io.output.NullOutputStream; /** - * <p> - * Signals low-level API for processing file uploads. + * Low-level API for processing file uploads. * * <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>. Arbitrarily large amounts of data in the stream can be processed under constant memory usage. - * + * </p> * <p> - * The format of the stream is defined in the following way:<br> - * + * The format of the stream is defined in the following way: + * </p> * <code> * multipart-body := preamble 1*encapsulation close-delimiter epilogue<br> * encapsulation := delimiter body CRLF<br> @@ -57,10 +56,10 @@ import org.apache.commons.io.output.NullOutputStream; * <p> * Note that body-data can contain another mulipart entity. There is limited support for single pass processing of such nested streams. The nested stream is * <strong>required</strong> to have a boundary token of the same length as the parent stream (see {@link #setBoundary(byte[])}). - * + * </p> * <p> - * Here is an example of usage of this class.<br> - * + * Here is an example of usage of this class: + * </p> * <pre> * try { * MultipartStream multipartStream = new MultipartStream(input, boundary); @@ -207,7 +206,7 @@ public class MultipartStream { } /** - * Returns the number of bytes, which have been read by the stream. + * Gets the number of bytes, which have been read by the stream. * * @return Number of bytes, which have been read so far. */ @@ -262,7 +261,7 @@ public class MultipartStream { } /** - * Returns the next byte in the stream. + * Reads the next byte in the stream. * * @return The next byte in the stream, as a non-negative integer, or -1 for EOF. * @throws IOException An I/O error occurred. @@ -491,7 +490,6 @@ public class MultipartStream { * @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} if {@code count} first bytes in arrays {@code a} and {@code b} are equal. */ public static boolean arrayEquals(final byte[] a, final byte[] b, final int count) { @@ -563,13 +561,11 @@ public class MultipartStream { /** - * <p> * Constructs a {@code MultipartStream} 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 a buffer size setting will degrade performance. - * + * </p> * @param input The {@code InputStream} to serve as a data source. * @param boundary The token used for dividing the stream into {@code encapsulations}. * @param bufferSize The size of the buffer to be used, in bytes. @@ -607,7 +603,6 @@ public class MultipartStream { } /** - * <p> * Constructs a {@code MultipartStream} with a default size buffer. * * @param input The {@code InputStream} to serve as a data source. @@ -620,7 +615,7 @@ public class MultipartStream { } /** - * Compute the table used for Knuth-Morris-Pratt search algorithm. + * Computes the table used for Knuth-Morris-Pratt search algorithm. */ private void computeBoundaryTable() { int position = 2; @@ -644,14 +639,11 @@ public class MultipartStream { } /** - * <p> * Reads {@code body-data} from the current {@code encapsulation} and discards it. - * * <p> * Use this method to skip encapsulations you don't need or don't understand. - * + * </p> * @return The amount of data discarded. - * * @throws MalformedStreamException if the stream ends unexpectedly. * @throws IOException if an i/o error occurs. */ @@ -701,7 +693,7 @@ public class MultipartStream { } /** - * Retrieves the character encoding used when reading the headers of an individual part. When not specified, or {@code null}, the platform default encoding + * Gets the character encoding used when reading the headers of an individual part. When not specified, or {@code null}, the platform default encoding * is used. * * @return The encoding used to read part headers. @@ -720,17 +712,13 @@ public class MultipartStream { } /** - * <p> * Reads {@code body-data} from the current {@code encapsulation} and writes its contents into the output {@code Stream}. - * * <p> * Arbitrary large amounts of data can be processed by this method using a constant size buffer. (see * {@link #MultipartStream(InputStream,byte[],int, MultipartStream.ProgressNotifier) constructor}). - * + * </p> * @param output The {@code Stream} to write data into. May be null, in which case this method is equivalent to {@link #discardBodyData()}. - * * @return the amount of data written. - * * @throws MalformedStreamException if the stream ends unexpectedly. * @throws IOException if an i/o error occurs. */ @@ -744,7 +732,6 @@ public class MultipartStream { * Skips a {@code boundary} token, and checks whether more {@code encapsulations} are contained in the stream. * * @return {@code true} if there are more encapsulations in this stream; {@code false} otherwise. - * * @throws FileUploadSizeException if the bytes read from the stream exceeded the size limits * @throws MalformedStreamException if the stream ends unexpectedly or fails to follow required syntax. */ @@ -785,7 +772,6 @@ public class MultipartStream { * Reads a byte from the {@code buffer}, and refills it as necessary. * * @return The next byte from the input stream. - * * @throws IOException if there is no more data available. */ public byte readByte() throws IOException { @@ -806,17 +792,14 @@ public class MultipartStream { } /** - * <p> * Reads the {@code header-part} of the current {@code encapsulation}. - * * <p> * Headers are returned verbatim to the input stream, including the trailing {@code CRLF} marker. Parsing is left to the application. - * + * </p> * <p> * <strong>TODO</strong> allow limiting maximum header size to protect against abuse. - * + * </p> * @return The {@code header-part} of the current encapsulation. - * * @throws FileUploadSizeException if the bytes read from the stream exceeded the size limits. * @throws MalformedStreamException if the stream ends unexpectedly. */ @@ -863,20 +846,17 @@ public class MultipartStream { } /** - * <p> * Changes the boundary token used for partitioning the stream. - * * <p> * This method allows single pass processing of nested multipart streams. - * + * </p> * <p> * The boundary token of the nested stream is {@code required} to be of the same length as the boundary token in parent stream. - * + * </p> * <p> * Restoring the parent stream boundary token after processing of a nested stream is left to the application. - * + * </p> * @param boundary The boundary to be used for parsing of the nested stream. - * * @throws FileUploadBoundaryException if the {@code boundary} has a different length than the one being currently parsed. */ public void setBoundary(final byte[] boundary) throws FileUploadBoundaryException { @@ -888,7 +868,7 @@ public class MultipartStream { } /** - * Specifies the character encoding to be used when reading the headers of individual parts. When not specified, or {@code null}, the platform default + * Sets the character encoding to be used when reading the headers of individual parts. When not specified, or {@code null}, the platform default * encoding is used. * * @param encoding The encoding used to read part headers. @@ -901,7 +881,6 @@ public class MultipartStream { * Finds the beginning of the first {@code encapsulation}. * * @return {@code true} if an {@code encapsulation} was found in the stream. - * * @throws IOException if an i/o error occurs. */ public boolean skipPreamble() throws IOException { diff --git a/src/main/java/org/apache/commons/fileupload2/ParameterParser.java b/src/main/java/org/apache/commons/fileupload2/ParameterParser.java index 4eba2f1..cf7e848 100644 --- a/src/main/java/org/apache/commons/fileupload2/ParameterParser.java +++ b/src/main/java/org/apache/commons/fileupload2/ParameterParser.java @@ -26,13 +26,13 @@ import org.apache.commons.fileupload2.util.mime.RFC2231Utility; /** * A simple parser intended to parse sequences of name/value pairs. - * + * <p> * Parameter values are expected to be enclosed in quotes if they * contain unsafe characters, such as '=' characters or separators. * Parameter values are optional and can be omitted. - * + * </p> * <p> - * {@code param1 = value; param2 = "anything goes; really"; param3} + * {@code param1 = value; param2 = "anything goes; really"; param3} * </p> */ public class ParameterParser { @@ -107,7 +107,7 @@ public class ParameterParser { } /** - * Are there any characters left to parse? + * Tests if there any characters left to parse. * * @return {@code true} if there are unparsed characters, * {@code false} otherwise. @@ -117,7 +117,7 @@ public class ParameterParser { } /** - * Returns {@code true} if parameter names are to be converted to lower + * Tests {@code true} if parameter names are to be converted to lower * case when name/value pairs are parsed. * * @return {@code true} if parameter names are to be @@ -133,7 +133,6 @@ public class ParameterParser { * * @param ch the character to test for presence in the array of characters * @param charray the array of characters to test against - * * @return {@code true} if the character is present in the array of * characters, {@code false} otherwise. */ @@ -155,7 +154,6 @@ public class ParameterParser { * @param charArray the array of characters that contains a sequence of * name/value pairs * @param separator the name/value pairs separator - * * @return a map of name/value pairs */ public Map<String, String> parse(final char[] charArray, final char separator) { @@ -174,7 +172,6 @@ public class ParameterParser { * @param offset - the initial offset. * @param length - the length. * @param separator the name/value pairs separator - * * @return a map of name/value pairs */ public Map<String, String> parse( @@ -231,7 +228,6 @@ public class ParameterParser { * * @param str the string that contains a sequence of name/value pairs * @param separator the name/value pairs separator - * * @return a map of name/value pairs */ public Map<String, String> parse(final String str, final char separator) { @@ -248,7 +244,6 @@ public class ParameterParser { * * @param str the string that contains a sequence of name/value pairs * @param separators the name/value pairs separators - * * @return a map of name/value pairs */ public Map<String, String> parse(final String str, final char[] separators) { @@ -276,7 +271,6 @@ public class ParameterParser { * @param terminators the array of terminating characters. Any of these * characters when encountered outside the quotation marks signify the end * of the token - * * @return the token */ private String parseQuotedToken(final char[] terminators) { @@ -307,7 +301,6 @@ public class ParameterParser { * * @param terminators the array of terminating characters. Any of these * characters when encountered signify the end of the token - * * @return the token */ private String parseToken(final char[] terminators) { diff --git a/src/main/java/org/apache/commons/fileupload2/ProgressListener.java b/src/main/java/org/apache/commons/fileupload2/ProgressListener.java index 5acc770..d426871 100644 --- a/src/main/java/org/apache/commons/fileupload2/ProgressListener.java +++ b/src/main/java/org/apache/commons/fileupload2/ProgressListener.java @@ -17,7 +17,7 @@ package org.apache.commons.fileupload2; /** - * The {@link ProgressListener} may be used to display a progress bar. + * Receives progress information. May be used to display a progress bar. */ public interface ProgressListener { diff --git a/src/main/java/org/apache/commons/fileupload2/RequestContext.java b/src/main/java/org/apache/commons/fileupload2/RequestContext.java index fa7bed1..46094ca 100644 --- a/src/main/java/org/apache/commons/fileupload2/RequestContext.java +++ b/src/main/java/org/apache/commons/fileupload2/RequestContext.java @@ -20,10 +20,10 @@ import java.io.IOException; import java.io.InputStream; /** - * <p>Abstracts access to the request information needed for file uploads. This - * interface should be implemented for each type of request that may be - * handled by FileUpload, such as servlets and portlets.</p> - * + * Abstracts access to the request information needed for file uploads. + * <p> + * This interface should be implemented for each type of request that may be handled by FileUpload, such as servlets and portlets. + * </p> * @since 1.1 */ public interface RequestContext { diff --git a/src/main/java/org/apache/commons/fileupload2/UploadContext.java b/src/main/java/org/apache/commons/fileupload2/UploadContext.java index d710987..08e9cde 100644 --- a/src/main/java/org/apache/commons/fileupload2/UploadContext.java +++ b/src/main/java/org/apache/commons/fileupload2/UploadContext.java @@ -29,7 +29,7 @@ package org.apache.commons.fileupload2; public interface UploadContext extends RequestContext { /** - * Retrieve the content length of the request. + * Gets the content length of the request. * * @return The content length of the request. * @since 1.3 diff --git a/src/main/java/org/apache/commons/fileupload2/disk/DiskFileItem.java b/src/main/java/org/apache/commons/fileupload2/disk/DiskFileItem.java index fd2f62a..66ff34d 100644 --- a/src/main/java/org/apache/commons/fileupload2/disk/DiskFileItem.java +++ b/src/main/java/org/apache/commons/fileupload2/disk/DiskFileItem.java @@ -41,10 +41,11 @@ import org.apache.commons.io.IOUtils; import org.apache.commons.io.output.DeferredFileOutputStream; /** - * <p> The default implementation of the + * The default implementation of the * {@link org.apache.commons.fileupload2.FileItem FileItem} interface. * - * <p> After retrieving an instance of this class from a {@link + * <p> + * After retrieving an instance of this class from a {@link * DiskFileItemFactory} instance (see * {@link org.apache.commons.fileupload2.servlet.ServletFileUpload * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may @@ -52,8 +53,9 @@ import org.apache.commons.io.output.DeferredFileOutputStream; * request an {@link java.io.InputStream InputStream} with * {@link #getInputStream()} and process the file without attempting to load * it into memory, which may come handy with large files. - * - * <p>Temporary files, which are created for file items, should be + * </p> + * <p> + * Temporary files, which are created for file items, should be * deleted later on. The best way to do this is using a * {@link org.apache.commons.io.FileCleaningTracker}, which you can set on the * {@link DiskFileItemFactory}. However, if you do use such a tracker, @@ -65,7 +67,8 @@ import org.apache.commons.io.output.DeferredFileOutputStream; * there are files to be tracked. * It might make sense to terminate that thread, for example, if * your web application ends. See the section on "Resource cleanup" - * in the users guide of commons-fileupload.</p> + * in the users guide of commons-fileupload. + * </p> * * @since 1.1 */ @@ -82,8 +85,7 @@ public class DiskFileItem implements FileItem { /** * UID used in unique file name generation. */ - private static final String UID = - UUID.randomUUID().toString().replace('-', '_'); + private static final String UID = UUID.randomUUID().toString().replace('-', '_'); /** * Counter used in unique identifier generation. @@ -224,7 +226,6 @@ public class DiskFileItem implements FileItem { * * @return The contents of the file as an array of bytes * or {@code null} if the data cannot be read - * * @throws UncheckedIOException if an I/O error occurs */ @Override @@ -276,6 +277,7 @@ public class DiskFileItem implements FileItem { /** * Returns the default charset for use when no explicit charset * parameter is provided by the sender. + * * @return the default charset */ public String getDefaultCharset() { @@ -287,9 +289,7 @@ public class DiskFileItem implements FileItem { * this file item. * * @return The name of the form field. - * * @see #setFieldName(String) - * */ @Override public String getFieldName() { @@ -298,6 +298,7 @@ public class DiskFileItem implements FileItem { /** * Returns the file item headers. + * * @return The file items headers. */ @Override @@ -311,7 +312,6 @@ public class DiskFileItem implements FileItem { * * @return An {@link java.io.InputStream InputStream} that can be * used to retrieve the contents of the file. - * * @throws IOException if an error occurs. */ @Override @@ -347,7 +347,6 @@ public class DiskFileItem implements FileItem { * * @return An {@link java.io.OutputStream OutputStream} that can be used * for storing the contents of the file. - * */ @Override public OutputStream getOutputStream() { @@ -404,9 +403,9 @@ public class DiskFileItem implements FileItem { * 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. - * + * <p> * <b>TODO</b> Consider making this method throw UnsupportedEncodingException. - * + * </p> * @return The contents of the file, as a string. */ @Override @@ -449,7 +448,7 @@ public class DiskFileItem implements FileItem { * <p> * <b>Note: Subclasses that override this method must ensure that they return the * same File each time.</b> - * + * </p> * @return The {@link java.io.File File} to be used for temporary storage. */ protected File getTempFile() { @@ -472,9 +471,7 @@ public class DiskFileItem implements FileItem { * * @return {@code true} if the instance represents a simple form * field; {@code false} if it represents an uploaded file. - * * @see #setFormField(boolean) - * */ @Override public boolean isFormField() { @@ -499,6 +496,7 @@ public class DiskFileItem implements FileItem { /** * Sets the default charset for use when no explicit charset * parameter is provided by the sender. + * * @param charset the default charset */ public void setDefaultCharset(final String charset) { @@ -509,9 +507,7 @@ public class DiskFileItem implements FileItem { * Sets the field name used to reference this file item. * * @param fieldName The name of the form field. - * * @see #getFieldName() - * */ @Override public void setFieldName(final String fieldName) { @@ -524,9 +520,7 @@ public class DiskFileItem implements FileItem { * * @param state {@code true} if the instance represents a simple form * field; {@code false} if it represents an uploaded file. - * * @see #isFormField() - * */ @Override public void setFormField(final boolean state) { @@ -535,6 +529,7 @@ public class DiskFileItem implements FileItem { /** * Sets the file item headers. + * * @param pHeaders The file items headers. */ @Override @@ -568,9 +563,7 @@ public class DiskFileItem implements FileItem { * This method is only guaranteed to work <em>once</em>, the first time it is invoked for a particular item. This is because, in the event that the method * renames a temporary file, that file will no longer be available to copy or rename again at a later time. * </p> - * * @param file The {@code File} into which the uploaded item should be stored. - * * @throws IOException if an error occurs. */ @Override @@ -587,7 +580,7 @@ public class DiskFileItem implements FileItem { /* * For whatever reason we cannot write the file to disk. */ - throw new FileUploadException("Cannot write uploaded file to disk!"); + throw new FileUploadException("Cannot write uploaded file to disk."); } // Save the length of the file size = outputFile.length(); @@ -595,7 +588,7 @@ public class DiskFileItem implements FileItem { * The uploaded file is being stored on disk in a temporary location so move it to the desired file. */ if (file.exists() && !file.delete()) { - throw new FileUploadException("Cannot write uploaded file to disk!"); + throw new FileUploadException("Cannot write uploaded file to disk."); } FileUtils.moveFile(outputFile, file); }
