ファイルアップロードを処理するための高レベルAPIです。 * {@primary High level API for processing file uploads.}
* *このクラスは RFC 1867
* によって規定された multipart/mixed エンコーディングタイプを使用して
* HTMLウィジェットから送信された複数のファイルを処理します。
* {@link #parseRequest(HttpServletRequest)} を使用して、HTMLウィジェットから送られるデータを示す
* {@link org.apache.commons.fileupload.FileItem} のリストを取得します。
* {@primary This class handles multiple files per single HTML widget, sent using
* multipart/mixed encoding type, as specified by
* RFC 1867. Use {@link
* #parseRequest(HttpServletRequest)} to acquire a list of {@link
* org.apache.commons.fileupload.FileItem}s associated with a given HTML
* widget.}
個々のパーツが持つデータを保持する方法は、使用されるファクトリによって、 * メモリ上やディスク上などになります。 * {@primary 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.}
* * @author Rafal Krzewski * @author Daniel Rall * @author Jason van Zyl * @author John McNally * @author Martin Cooper * @author Sean C. Sullivan * @translator 日置 聡 * @editor 入江 弘憲 * @status completion * @update 2003/04/21 * * @version $Id: FileUploadBase.java,v 1.5 2004/04/20 15:10:02 hioki Exp $ */ public abstract class FileUploadBase { // ---------------------------------------------------------- Class methods /** * リクエストが multipart content を含むかどうかを判断するユーティリティメソッドです。 * {@primary Utility method that determines whether the request contains multipart * content.} * * @param req 評価対象となるサーブレットリクエスト。null は受け付けません。
* {@primary req The servlet request to be evaluated. Must be non-null.}
*
* @return true リクエストが multipart だった場合;
* false それ以外の場合。
* {@primary true if the request is multipart;
* false otherwise.}
*/
public static final boolean isMultipartContent(HttpServletRequest req)
{
String contentType = req.getHeader(CONTENT_TYPE);
if (contentType == null)
{
return false;
}
if (contentType.startsWith(MULTIPART))
{
return true;
}
return false;
}
// ----------------------------------------------------- Manifest constants
/**
* HTTP content type のヘッダ名。
* {@primary HTTP content type header name.}
*/
public static final String CONTENT_TYPE = "Content-type";
/**
* HTTP content disposition のヘッダ名。
* {@primary HTTP content disposition header name.}
*/
public static final String CONTENT_DISPOSITION = "Content-disposition";
/**
* フォームデータの場合の Content-disposition の値。
* {@primary Content-disposition value for form data.}
*/
public static final String FORM_DATA = "form-data";
/**
* ファイルアタッチメントの場合の Content-disposition の値。
* {@primary Content-disposition value for file attachment.}
*/
public static final String ATTACHMENT = "attachment";
/**
* HTTP content type ヘッダの一部。
* {@primary Part of HTTP content type header.}
*/
public static final String MULTIPART = "multipart/";
/**
* multipart forms の場合の HTTP content type ヘッダ(の値)。
* {@primary HTTP content type header for multipart forms.}
*/
public static final String MULTIPART_FORM_DATA = "multipart/form-data";
/**
* 複数アップロードの場合の HTTP content type ヘッダ(の値)。
* {@primary HTTP content type header for multiple uploads.}
*/
public static final String MULTIPART_MIXED = "multipart/mixed";
/**
* ヘッダのパースの際に読み込む最大長(1024バイト)。
* {@primary The maximum length of a single header line that will be parsed
* (1024 bytes).}
*/
public static final int MAX_HEADER_SIZE = 1024;
// ----------------------------------------------------------- Data members
/**
* アップロードされるファイルに許可する最大サイズ。
* -1 は上限が無いことを示します。
* {@primary The maximum size permitted for an uploaded file. A value of -1 indicates
* no maximum.}
*/
private long sizeMax = -1;
/**
* パーツのヘッダを読み込む際に使用されるエンコーディング。
* {@primary The content encoding to use when reading part headers.}
*/
private String headerEncoding;
// ----------------------------------------------------- Property accessors
/**
* ファイルアイテムを生成する際に使用するファクトリクラスを返します。
* {@primary Returns the factory class used when creating file items.}
*
* @return ファイルアイテムを生成するファクトリクラス。
* {@primary The factory class for new file items.}
*/
public abstract FileItemFactory getFileItemFactory();
/**
* ファイルアイテムを生成する際に使用するファクトリクラスを設定します。
* {@primary Sets the factory class to use when creating file items.}
*
* @param factory ファイルアイテムを生成するファクトリクラス。
* {@primary factory The factory class for new file items.}
*/
public abstract void setFileItemFactory(FileItemFactory factory);
/**
* アップロードが許可される最大サイズを返します。
* {@primary Returns the maximum allowed upload size.}
*
* @return 許可されるバイト単位の最大サイズ。
* {@primary The maximum allowed size, in bytes.}
*
* @see #setSizeMax(long)
*
*/
public long getSizeMax()
{
return sizeMax;
}
/**
* アップロードが許可される最大サイズを設定します。
* 負の数の場合、アップロードサイズの上限はありません。
* {@primary Sets the maximum allowed upload size. If negative, there is no maximum.}
*
* @param sizeMax 許可されるバイト単位の最大サイズ。-1 の場合には上限なし。
* {@primary sizeMax The maximum allowed size, in bytes, or -1 for no maximum.}
*
* @see #getSizeMax()
*
*/
public void setSizeMax(long sizeMax)
{
this.sizeMax = sizeMax;
}
/**
* 個々のパーツのヘッダを読み込む際に使用されるキャラクタエンコーディングを取得します。
* 設定されていない、もしくは null の場合、プラットフォームの デフォルトエンコーディングを使用します。
* {@primary Retrieves the character encoding used when reading the headers of an
* individual part. When not specified, or null, the platform
* default encoding is used.}
*
* @return パーツのヘッダを読み込む際に使用されるエンコーディング。
* {@primary The encoding used to read part headers.}
*/
public String getHeaderEncoding()
{
return headerEncoding;
}
/**
* 個々のパーツのヘッダを読み込む際に使用されるキャラクタエンコーディングを設定します。
* 設定されていない、もしくは null の場合、プラットフォームの デフォルトエンコーディングを使用します。
* {@primary Specifies the character encoding to be used when reading the headers of
* individual parts. When not specified, or null, the platform
* default encoding is used.}
*
* @param encoding パーツのヘッダを読み込む際に使用されるエンコーディング。
* {@primary encoding The encoding used to read part headers.}
*/
public void setHeaderEncoding(String encoding)
{
headerEncoding = encoding;
}
// --------------------------------------------------------- Public methods
/**
* RFC 1867 の仕様に従って
* multipart/form-data のストリームを処理します。
* ファイルがディスク上に保持される場合には getRepository()
* によってそのパスを取得することができます。
* {@primary Processes an RFC 1867
* compliant multipart/form-data stream. If files are stored
* on disk, the path is given by getRepository().}
*
* @param req 処理対象となるサーブレットリクエスト。
* {@primary The servlet request to be parsed.}
*
* @return このリクエストを処理して生成された FileItem インスタンスのリスト。
* 送信された順番に並びます。
* {@primary A list of FileItem instances parsed from the
* request, in the order that they were transmitted.}
*
* @exception FileUploadException リクエストの読み込み、処理またはファイルの保持にて 問題が発生した場合。
* {@primary if there are problems reading/parsing the request or storing files.}
*/
public List /* FileItem */ parseRequest(HttpServletRequest req)
throws FileUploadException
{
if (null == req)
{
throw new NullPointerException("req parameter");
}
ArrayList items = new ArrayList();
String contentType = req.getHeader(CONTENT_TYPE);
if ((null == contentType) || (!contentType.startsWith(MULTIPART)))
{
throw new InvalidContentTypeException(
"the request doesn't contain a "
+ MULTIPART_FORM_DATA
+ " or "
+ MULTIPART_MIXED
+ " stream, content type header is "
+ contentType);
}
int requestSize = req.getContentLength();
if (requestSize == -1)
{
throw new UnknownSizeException(
"the request was rejected because it's size is unknown");
}
if (sizeMax >= 0 && requestSize > sizeMax)
{
throw new SizeLimitExceededException(
"the request was rejected because "
+ "it's size exceeds allowed range");
}
try
{
int boundaryIndex = contentType.indexOf("boundary=");
if (boundaryIndex < 0)
{
throw new FileUploadException(
"the request was rejected because "
+ "no multipart boundary was found");
}
byte[] boundary = contentType.substring(
boundaryIndex + 9).getBytes();
InputStream input = req.getInputStream();
MultipartStream multi = new MultipartStream(input, boundary);
multi.setHeaderEncoding(headerEncoding);
boolean nextPart = multi.skipPreamble();
while (nextPart)
{
Map headers = parseHeaders(multi.readHeaders());
String fieldName = getFieldName(headers);
if (fieldName != null)
{
String subContentType = getHeader(headers, CONTENT_TYPE);
if (subContentType != null && subContentType
.startsWith(MULTIPART_MIXED))
{
// Multiple files.
byte[] subBoundary =
subContentType.substring(
subContentType
.indexOf("boundary=") + 9).getBytes();
multi.setBoundary(subBoundary);
boolean nextSubPart = multi.skipPreamble();
while (nextSubPart)
{
headers = parseHeaders(multi.readHeaders());
if (getFileName(headers) != null)
{
FileItem item =
createItem(headers, false);
OutputStream os = item.getOutputStream();
try
{
multi.readBodyData(os);
}
finally
{
os.close();
}
items.add(item);
}
else
{
// Ignore anything but files inside
// multipart/mixed.
multi.discardBodyData();
}
nextSubPart = multi.readBoundary();
}
multi.setBoundary(boundary);
}
else
{
if (getFileName(headers) != null)
{
// A single file.
FileItem item = createItem(headers, false);
OutputStream os = item.getOutputStream();
try
{
multi.readBodyData(os);
}
finally
{
os.close();
}
items.add(item);
}
else
{
// A form field.
FileItem item = createItem(headers, true);
OutputStream os = item.getOutputStream();
try
{
multi.readBodyData(os);
}
finally
{
os.close();
}
items.add(item);
}
}
}
else
{
// Skip this part.
multi.discardBodyData();
}
nextPart = multi.readBoundary();
}
}
catch (IOException e)
{
throw new FileUploadException(
"Processing of " + MULTIPART_FORM_DATA
+ " request failed. " + e.getMessage());
}
return items;
}
// ------------------------------------------------------ Protected methods
/**
* Content-disposition ヘッダからファイル名を取得します。
* {@primary Retrieves the file name from the Content-disposition
* header.}
*
* @param headers HTTPリクエストヘッダの情報を内部に持つ Map 。
* {@primary A Map containing the HTTP request headers.}
*
* @return 現在の encapsulation のファイル名。
* {@primary The file name for the current encapsulation.}
*/
protected String getFileName(Map /* String, String */ headers)
{
String fileName = null;
String cd = getHeader(headers, CONTENT_DISPOSITION);
if (cd.startsWith(FORM_DATA) || cd.startsWith(ATTACHMENT))
{
int start = cd.indexOf("filename=\"");
int end = cd.indexOf('"', start + 10);
if (start != -1 && end != -1)
{
fileName = cd.substring(start + 10, end).trim();
}
}
return fileName;
}
/**
* Content-disposition ヘッダからフィールド名を取得します。
* {@primary Retrieves the field name from the Content-disposition
* header.}
*
* @param headers HTTPリクエストヘッダの情報を内部に持つ Map 。
* {@primary A Map containing the HTTP request headers.}
*
* @return 現在の encapsulation のフィールド名。
* {@primary The field name for the current encapsulation.}
*/
protected String getFieldName(Map /* String, String */ headers)
{
String fieldName = null;
String cd = getHeader(headers, CONTENT_DISPOSITION);
if (cd != null && cd.startsWith(FORM_DATA))
{
int start = cd.indexOf("name=\"");
int end = cd.indexOf('"', start + 6);
if (start != -1 && end != -1)
{
fieldName = cd.substring(start + 6, end);
}
}
return fieldName;
}
/**
* 新規 {@link FileItem} インスタンスを生成します。
* {@primary Creates a new {@link FileItem} instance.}
*
* @param headers HTTPリクエストヘッダの情報を内部に持つ Map 。
* {@primary A Map containing the HTTP request
* headers.}
* @param isFormField このアイテムがファイルではなくフォームフィールドかどうか。
* {@primary Whether or not this item is a form field, as opposed to a file.}
*
* @return 新規に作成された FileItem インスタンス。
* {@primary A newly created FileItem instance.}
*
* @exception FileUploadException エラーが発生した場合。
* {@primary if an error occurs.}
*/
protected FileItem createItem(Map /* String, String */ headers,
boolean isFormField)
throws FileUploadException
{
return getFileItemFactory().createItem(getFieldName(headers),
getHeader(headers, CONTENT_TYPE),
isFormField,
getFileName(headers));
}
/**
* header-part をパースし、キー/値 のペアを返します。
* {@primary Parses the header-part and returns as key/value
* pairs.}
*
*
同名のヘッダが複数あった場合、
* その値はカンマで区切られたリストで格納されます。
* {@primary If there are multiple headers of the same names, the name
* will map to a comma-separated list containing the values.}
*
* @param headerPart 現在の encapsulationの header-part 。
* {@primary The header-part of the current
* encapsulation.}
*
* @return HTTPリクエストヘッダの情報を内部に持つ Map 。
* {@primary A Map containing the parsed HTTP request headers.}
*/
protected Map /* String, String */ parseHeaders(String headerPart)
{
Map headers = new HashMap();
char buffer[] = new char[MAX_HEADER_SIZE];
boolean done = false;
int j = 0;
int i;
String header, headerName, headerValue;
try
{
while (!done)
{
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')
{
buffer[i++] = headerPart.charAt(j++);
}
header = new String(buffer, 0, i - 2);
if (header.equals(""))
{
done = true;
}
else
{
if (header.indexOf(':') == -1)
{
// This header line is malformed, skip it.
continue;
}
headerName = header.substring(0, header.indexOf(':'))
.trim().toLowerCase();
headerValue =
header.substring(header.indexOf(':') + 1).trim();
if (getHeader(headers, headerName) != null)
{
// More that one heder of that name exists,
// append to the list.
headers.put(headerName,
getHeader(headers, headerName) + ','
+ headerValue);
}
else
{
headers.put(headerName, headerValue);
}
}
}
}
catch (IndexOutOfBoundsException e)
{
// Headers were malformed. continue with all that was
// parsed.
}
return headers;
}
/**
* 渡されたマップの中から指定された名称のヘッダの値を取得します。
* ヘッダの参照時に大文字小文字は区別されません(case-insensitive)。
* {@primary Returns the header with the specified name from the supplied map. The
* header lookup is case-insensitive.}
*
* @param headers HTTPリクエストヘッダの情報を内部に持つ Map 。
* {@primary A Map containing the HTTP request headers.}
* @param name データの取得対象となるヘッダの名称。
* {@primary The name of the header to return.}
*
* @return 指定されたヘッダの値。
* 同じ名前のヘッダが複数あった場合にはカンマで区切られたリスト。
* {@primary The value of specified header, or a comma-separated list if
* there were multiple headers of that name.}
*/
protected final String getHeader(Map /* String, String */ headers,
String name)
{
return (String) headers.get(name.toLowerCase());
}
/**
* リクエストが multipart リクエストでない場合に投げられます。
* {@primary Thrown to indicate that the request is not a multipart request.}
*/
public static class InvalidContentTypeException
extends FileUploadException
{
/**
* 詳細メッセージなしで InvalidContentTypeException を生成します。
* {@primary Constructs a InvalidContentTypeException with no
* detail message.}
*/
public InvalidContentTypeException()
{
super();
}
/**
* 詳細メッセージを設定して InvalidContentTypeException を生成します。
* {@primary Constructs an InvalidContentTypeException with
* the specified detail message.}
*
* @param message 詳細メッセージ。
* {@primary The detail message.}
*/
public InvalidContentTypeException(String message)
{
super(message);
}
}
/**
* リクエストのサイズが明示されていない場合に投げられます。
* {@primary Thrown to indicate that the request size is not specified.}
*/
public static class UnknownSizeException
extends FileUploadException
{
/**
* 詳細メッセージなしで UnknownSizeException を生成します。
* {@primary Constructs a UnknownSizeException with no
* detail message.}
*/
public UnknownSizeException()
{
super();
}
/**
* 詳細メッセージを設定して UnknownSizeException を生成します。
* {@primary Constructs an UnknownSizeException with
* the specified detail message.}
*
* @param message 詳細メッセージ。
* {@primary The detail message.}
*/
public UnknownSizeException(String message)
{
super(message);
}
}
/**
* リクエストのサイズが設定された最大サイズを超えた場合に投げられます。
* {@primary Thrown to indicate that the request size exceeds the configured maximum.}
*/
public static class SizeLimitExceededException
extends FileUploadException
{
/**
* 詳細メッセージなしで SizeExceededException を生成します。
* {@primary Constructs a SizeExceededException with no
* detail message.}
*/
public SizeLimitExceededException()
{
super();
}
/**
* 詳細メッセージを設定して SizeExceededException を生成します。
* {@primary Constructs an SizeExceededException with
* the specified detail message.}
*
* @param message 詳細メッセージ。
* {@primary The detail message.}
*/
public SizeLimitExceededException(String message)
{
super(message);
}
}
}