org.apache.commons.fileupload
クラス MultipartStream

java.lang.Object
  org.apache.commons.fileupload.MultipartStream

public class MultipartStream

extends Object

ファイルアップロードを処理するための低レベルAPIです。

Low level API for processing file uploads.

このクラスは RFC 1867 に規定されている MIME 'multipart' フォーマットに従うデータストリームを処理するために使用されます。 ストリーム内の(任意の)大量のデータを一定のメモリの使用量で処理することができます。

This class can be used to process data streams conforming to MIME 'multipart' format as defined in RFC 1867. Arbitrarily large amounts of data in the stream can be processed under constant memory usage.

ストリームは以下のような形式で定義されています:

The format of the stream is defined in the following way:

multipart-body := preamble 1*encapsulation close-delimiter epilogue
encapsulation := delimiter body CRLF
delimiter := "--" boundary CRLF
close-delimiter := "--" boudary "--"
preamble := <ignore>
epilogue := <ignore>
body := header-part CRLF body-part
header-part := 1*header CRLF
header := header-name ":" header-value
header-name := <printable ascii characters except ":">
header-value := <any ascii characters except CR & LF>
body-data := <arbitrary data>


body-data が他の multipart エンティティを持つことができることに注意して下さい。 このような入れ子になったストリームの単独パスでの処理を制限つきでサポートします。 入れ子になったストリームは必ず親のストリームと同じ長さのバウンダリトークンを 持っていなくてはなりません(setBoundary(byte[])を参照)。

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 required to have a boundary token of the same length as the parent stream (see {@link #setBoundary(byte[])}).

以下にこのクラスに使用例を示します。

Here is an exaple of usage of this class.

    try {
        MultipartStream multipartStream = new MultipartStream(input,
                                                              boundary);
        boolean nextPart = malitPartStream.skipPreamble();
        OutputStream output;
        while(nextPart) {
            header = chunks.readHeader();
            // ヘッダを処理
            // 出力ストリームを生成
            multipartStream.readBodyPart(output);
            nextPart = multipartStream.readBoundary();
        }
    } catch(MultipartStream.MalformedStreamException e) {
          // ストリームが必要とする文法に従っていない
    } catch(IOException) {
          // 読み込みまたは書き出しにてエラーが発生
    }

 

    try {
        MultipartStream multipartStream = new MultipartStream(input,
                                                              boundary);
        boolean nextPart = malitPartStream.skipPreamble();
        OutputStream output;
        while(nextPart) {
            header = chunks.readHeader();
            // process headers
            // create some output stream
            multipartStream.readBodyPart(output);
            nextPart = multipartStream.readBoundary();
        }
    } catch(MultipartStream.MalformedStreamException e) {
          // the stream failed to follow required syntax
    } catch(IOException) {
          // a read or write error occurred
    }

 

バージョン:

$Id: MultipartStream.java,v 1.4 2004/04/15 11:15:10 hioki Exp $

作成者:

Rafal Krzewski, Martin Cooper, Sean C. Sullivan

翻訳者:

日置 聡

校正者:

入江 弘憲

翻訳状況:

校了

入れ子クラスの概要

class	MultipartStream.IllegalBoundaryException 不正なバウンダリトークンを設定しようとした場合に投げられます。
class	MultipartStream.MalformedStreamException 入力ストリームが必要な文法に従っていない場合に投げられます。

フィールドの概要

private byte[]	boundary ストリームを仕切るバイト列。
private int	boundaryLength バウンダリトークンと CRLF-- を加えた長さ。
private byte[]	buffer リクエストを処理する際に使用するバッファ。
private int	bufSize リクエストを処理する際に使用するバッファの長さ。
protected static int	DEFAULT_BUFSIZE リクエストを処理する際に使用されるバッファのデフォルトの長さ。
protected static byte[]	FIELD_SEPARATOR encapsulation の前に来る delimiter に続くバイト列(CRLF)。
private int	head バッファ内の先頭の有効なキャラクタのインデックス。
static int	HEADER_PART_SIZE_MAX 処理される header-part の最大の長さ(10キロバイト = 10240バイト)。
protected static byte[]	HEADER_SEPARATOR header-part の終わりを示すバイト列(CRLFCRLF)。
private String	headerEncoding ヘッダを読み込む際に使用するコンテントエンコーディング。
private InputStream	input データの読み込み対象となる入力ストリーム。
private int	keepRegion データの量(バイト単位)。
protected static byte[]	STREAM_TERMINATOR ストリーム内の最後の encapsulation のdelimiter に続くバイト列(--)。
private int	tail バッファ内の末尾の有効なキャラクタのインデックス + 1。

コンストラクタの概要

MultipartStream()
デフォルトコンストラクタ。

MultipartStream(InputStream input, byte[] boundary)
デフォルトのバッファサイズを使用する MultipartStream を生成します。

MultipartStream(InputStream input, byte[] boundary, int bufSize)
バッファのサイズを指定して MultipartStream を生成します。

メソッドの概要

static boolean	arrayequals(byte[] a, byte[] b, int count) 2つのバイト配列の先頭から指定されたインデックス分を比較します。
int	discardBodyData() 現在の encapsulation から body-data を読み込み、これを破棄します。
protected int	findByte(byte value, int pos) バッファ内の指定された位置から指定されたバイトの値を検索します。
protected int	findSeparator() バッファ内の head と tail で区切られた範囲内から boundary を検索します。
String	getHeaderEncoding() 個々のパーツのヘッダを読み込む際に使用するキャラクタエンコーディングを返します。
int	readBodyData(OutputStream output) 現在の encapsulation から body-data を読み込み、その内容を 出力ストリームに書き出します。
boolean	readBoundary() boundary トークンをスキップし、 ストリーム内にさらに encapsulations があるかどうかチェックします。
byte	readByte() バッファからバイトを返し、必要な分だけ補充します。
String	readHeaders() 現在の encapsulation から header-part を読み込みます。
void	setBoundary(byte[] boundary) ストリームを分割する際に使用するバウンダリトークンを変更します。
void	setHeaderEncoding(String encoding) 個々のパーツのヘッダを読み込む際に使用するキャラクタエンコーディングを設定します。
boolean	skipPreamble() 最初の encapsulation の始まりを捜し出します。
String	toString() このオブジェクトの文字列表現を返します。

クラス java.lang.Object から継承したメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

フィールドの詳細

HEADER_PART_SIZE_MAX

public static final int HEADER_PART_SIZE_MAX

処理される header-part の最大の長さ(10キロバイト = 10240バイト)。

The maximum length of header-part that will be processed (10 kilobytes = 10240 bytes.).

関連項目:

定数フィールド値

DEFAULT_BUFSIZE

protected static final int DEFAULT_BUFSIZE

リクエストを処理する際に使用されるバッファのデフォルトの長さ。

The default length of the buffer used for processing a request.

関連項目:

定数フィールド値

HEADER_SEPARATOR

protected static final byte[] HEADER_SEPARATOR

header-part の終わりを示すバイト列(CRLFCRLF)。

A byte sequence that marks the end of header-part (CRLFCRLF).

FIELD_SEPARATOR

protected static final byte[] FIELD_SEPARATOR

encapsulation の前に来る delimiter に続くバイト列(CRLF)。

A byte sequence that that follows a delimiter that will be followed by an encapsulation (CRLF).

STREAM_TERMINATOR

protected static final byte[] STREAM_TERMINATOR

ストリーム内の最後の encapsulation のdelimiter に続くバイト列(--)。

A byte sequence that that follows a delimiter of the last encapsulation in the stream (--).

input

private InputStream input

データの読み込み対象となる入力ストリーム。

The input stream from which data is read.

boundaryLength

private int boundaryLength

バウンダリトークンと CRLF-- を加えた長さ。

The length of the boundary token plus the leading CRLF--.

keepRegion

private int keepRegion

データの量(バイト単位)。 これはデリミタを正しく検出するためにバッファ内に順番に保持されなくてはならない。

The amount of data, in bytes, that must be kept in the buffer in order to detect delimiters reliably.

boundary

private byte[] boundary

ストリームを仕切るバイト列。

The byte sequence that partitions the stream.

bufSize

private int bufSize

リクエストを処理する際に使用するバッファの長さ。

The length of the buffer used for processing the request.

buffer

private byte[] buffer

リクエストを処理する際に使用するバッファ。

The buffer used for processing the request.

head

private int head

バッファ内の先頭の有効なキャラクタのインデックス。

The index of first valid character in the buffer.

0 <= head < bufSize

tail

private int tail

バッファ内の末尾の有効なキャラクタのインデックス + 1。

The index of last valid characer in the buffer + 1.

0 <= tail <= bufSize

headerEncoding

private String headerEncoding

ヘッダを読み込む際に使用するコンテントエンコーディング。

The content encoding to use when reading headers.

コンストラクタの詳細

MultipartStream

public MultipartStream()

デフォルトコンストラクタ。

Default constructor.

関連項目:

MultipartStream(InputStream, byte[], int), MultipartStream(InputStream, byte[])

MultipartStream

public MultipartStream(InputStream input,
                       byte[] boundary,
                       int bufSize)

バッファのサイズを指定して MultipartStream を生成します。

Constructs a MultipartStream with a custom size buffer.

バッファはバウンダリ文字列 + "CR/LF--"の4文字 + 少なくとも1バイトのデータを 保持できる大きさがなくてはならないことに注意してください。 小さすぎるバッファサイズの設定はパフォーマンスを低下させます。

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.

パラメータ:

input - データソースを出力する InputStream 。

The InputStream to serve as a data source.

boundary - ストリームを encapsulations に分割するために使用するトークン。

The token used for dividing the stream into encapsulations.

bufSize - 使用するバッファのサイズ(バイト単位)。

The size of the buffer to be used, in bytes.

関連項目:

MultipartStream(), MultipartStream(InputStream, byte[])

MultipartStream

public MultipartStream(InputStream input,
                       byte[] boundary)
                throws IOException

デフォルトのバッファサイズを使用する MultipartStream を生成します。

Constructs a MultipartStream with a default size buffer.

パラメータ:

input - データソースを出力する InputStream 。

The InputStream to serve as a data source.

boundary - ストリームを encapsulations に分割するために使用するトークン。

The token used for dividing the stream into encapsulations.

例外:

IOException - エラーが発生した場合。

when an error occurs.

関連項目:

MultipartStream(), MultipartStream(InputStream, byte[], int)

メソッドの詳細

getHeaderEncoding

public String getHeaderEncoding()

個々のパーツのヘッダを読み込む際に使用するキャラクタエンコーディングを返します。 設定されていないまたは null の場合にはプラットフォームのデフォルトエンコーディングを使用します。

Retrieves the character encoding used when reading the headers of an individual part. When not specified, or null, the platform default encoding is used.

戻り値:

パーツのヘッダを読み込む際に使用するエンコーディング。

The encoding used to read part headers.

setHeaderEncoding

public void setHeaderEncoding(String encoding)

個々のパーツのヘッダを読み込む際に使用するキャラクタエンコーディングを設定します。 設定されていないまたは null の場合にはプラットフォームのデフォルトエンコーディングを使用します。

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.

パラメータ:

encoding - パーツのヘッダを読み込む際に使用するエンコーディング。

The encoding used to read part headers.

readByte

public byte readByte()
              throws IOException

バッファからバイトを返し、必要な分だけ補充します。

Reads a byte from the buffer, and refills it as necessary.

戻り値:

入力ストリームから読み出した次のバイト。

The next byte from the input stream.

例外:

IOException - もうこれ以上データがない場合。

if there is no more data available.

readBoundary

public boolean readBoundary()
                     throws MultipartStream.MalformedStreamException

boundary トークンをスキップし、 ストリーム内にさらに encapsulations があるかどうかチェックします。

Skips a boundary token, and checks whether more encapsulations are contained in the stream.

戻り値:

true ストリーム内にさらに encapsulations がある場合; false それ以外の場合。

true if there are more encapsulations in this stream; false otherwise.

例外:

MultipartStream.MalformedStreamException - ストリームが不意に終了した場合、 または文法の解釈に失敗した場合。

if the stream ends unexpectedly or fails to follow required syntax.

setBoundary

public void setBoundary(byte[] boundary)
                 throws MultipartStream.IllegalBoundaryException

ストリームを分割する際に使用するバウンダリトークンを変更します。

Changes the boundary token used for partitioning the stream.

このメソッドは入れ子になったストリームの単独パスでの処理を可能にします。

This method allows single pass processing of nested multipart streams.

入れ子になったストリームのバウンダリトークンは 必ず 親のストリームのバウンダリトークンと同じ長さでなくてはなりません。

The boundary token of the nested stream is required to be of the same length as the boundary token in parent stream.

入れ子になったストリームのの処理の後、親のストリームのバウンダリに戻す処理は アプリケーションに委ねられます(手動で設定しなおす必要があります)。

Restoring the parent stream boundary token after processing of a nested stream is left to the application.

パラメータ:

boundary - 入れ子になったストリームのパースに使用するバウンダリ。

The boundary to be used for parsing of the nested stream.

例外:

MultipartStream.IllegalBoundaryException - boundary の長さが現在使用されているものと違った場合。

if the boundary has a different length than the one being currently parsed.

readHeaders

public String readHeaders()
                   throws MultipartStream.MalformedStreamException

現在の encapsulation から header-part を読み込みます。

Reads the header-part of the current encapsulation.

ヘッダは末尾の CRLF マーカーを含む入力ストリームから読み出したままの状態で返されます。 パースの処理はアプリケーションに委ねられます。

Headers are returned verbatim to the input stream, including the trailing CRLF marker. Parsing is left to the application.

TODO 悪意あるアクセスから保護するために、 ヘッダサイズには上限を設けられています。

TODO allow limiting maximum header size to protect against abuse.

戻り値:

現在の encapsulation の header-part。

The header-part of the current encapsulation.

例外:

MultipartStream.MalformedStreamException - ストリームが不意に終了した場合。

if the stream ends unexpecetedly.

readBodyData

public int readBodyData(OutputStream output)
                 throws MultipartStream.MalformedStreamException,
                        IOException

現在の encapsulation から body-data を読み込み、その内容を 出力ストリームに書き出します。

Reads body-data from the current encapsulation and writes its contents into the output Stream.

このメソッドによって(任意の)大量のデータを 一定のサイズのバッファを使用して処理を行うことができます (コンストラクタ を参照)。

Arbitrary large amounts of data can be processed by this method using a constant size buffer. (see {@link #MultipartStream(InputStream,byte[],int) constructor}).

パラメータ:

output - データを書き出す対象となる Stream。

The Stream to write data into.

戻り値:

書き出したデータの量。

the amount of data written.

例外:

MultipartStream.MalformedStreamException - ストリームが不意に終了した場合。

if the stream ends unexpectedly.

IOException - 入出力エラーが発生した場合。

if an i/o error occurs.

discardBodyData

public int discardBodyData()
                    throws MultipartStream.MalformedStreamException,
                           IOException

現在の encapsulation から body-data を読み込み、これを破棄します。

Reads body-data from the current encapsulation and discards it.

このメソッドは必要のない、もしくは解釈できない encapsulations をスキップする際に使用してください。

Use this method to skip encapsulations you don't need or don't understand.

戻り値:

破棄したデータの量。

The amount of data discarded.

例外:

MultipartStream.MalformedStreamException - ストリームが不意に終了した場合。

if the stream ends unexpectedly.

IOException - 入出力エラーが発生した場合。

if an i/o error occurs.

skipPreamble

public boolean skipPreamble()
                     throws IOException

最初の encapsulation の始まりを捜し出します。

Finds the beginning of the first encapsulation.

戻り値:

true ストリーム内に encapsulation が見つかった場合。

true if an encapsulation was found in the stream.

例外:

IOException - 入出力エラーが発生した場合。

if an i/o error occurs.

arrayequals

public static boolean arrayequals(byte[] a,
                                  byte[] b,
                                  int count)

2つのバイト配列の先頭から指定されたインデックス分を比較します。

Compares count first bytes in the arrays a and b.

パラメータ:

a - 最初の比較対象となる配列。

The first array to compare.

b - 2番目の比較対象となる配列。

The second array to compare.

count - 比較対象となる(先頭からの)バイト数。

How many bytes should be compared.

戻り値:

true 配列 a と b の先頭から count 分のバイト配列が等しい場合。

true if count first bytes in arrays a and b are equal.

findByte

protected int findByte(byte value,
                       int pos)

バッファ内の指定された位置から指定されたバイトの値を検索します。

Searches for a byte of specified value in the buffer, starting at the specified position.

パラメータ:

value - 検索する値。

The value to find.

pos - 検索開始位置。

The starting position for searching.

戻り値:

見つかったバイトのバッファの先頭からの位置。 見つからなかった場合には -1 。

The position of byte found, counting from beginning of the buffer, or -1 if not found.

findSeparator

protected int findSeparator()

バッファ内の head と tail で区切られた範囲内から boundary を検索します。

Searches for the boundary in the buffer region delimited by head and tail.

戻り値:

見つかったバウンダリのバッファの先頭からの位置。 見つからなかった場合には -1 。

The position of the boundary found, counting from the beginning of the buffer, or -1 if not found.

toString

public String toString()

このオブジェクトの文字列表現を返します。

Returns a string representation of this object.

戻り値:

このオブジェクトの文字列表現。

The string representation of this object.