org.apache.commons.fileupload
クラス MultipartStream

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

public class MultipartStream
extends Object

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

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

ストリームは以下のような形式で定義されています:
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[])を参照)。

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

    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) {
          // 読み込みまたは書き出しにてエラーが発生
    }

 

バージョン:
$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()
          バッファ内の headtail で区切られた範囲内から 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バイト)。

関連項目:
定数フィールド値

DEFAULT_BUFSIZE

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

関連項目:
定数フィールド値

HEADER_SEPARATOR

protected static final byte[] HEADER_SEPARATOR
header-part の終わりを示すバイト列(CRLFCRLF)。


FIELD_SEPARATOR

protected static final byte[] FIELD_SEPARATOR
encapsulation の前に来る delimiter に続くバイト列(CRLF)。


STREAM_TERMINATOR

protected static final byte[] STREAM_TERMINATOR
ストリーム内の最後の encapsulation のdelimiter に続くバイト列(--)。


input

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


boundaryLength

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


keepRegion

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


boundary

private byte[] boundary
ストリームを仕切るバイト列。


bufSize

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


buffer

private byte[] buffer
リクエストを処理する際に使用するバッファ。


head

private int head
バッファ内の先頭の有効なキャラクタのインデックス。
0 <= head < bufSize


tail

private int tail
バッファ内の末尾の有効なキャラクタのインデックス + 1。
0 <= tail <= bufSize


headerEncoding

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

コンストラクタの詳細

MultipartStream

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

関連項目:
MultipartStream(InputStream, byte[], int), MultipartStream(InputStream, byte[])

MultipartStream

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

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

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

パラメータ:
input - データソースを出力する InputStream
boundary - ストリームを encapsulations に分割するために使用するトークン。
bufSize - 使用するバッファのサイズ(バイト単位)。
関連項目:
MultipartStream(), MultipartStream(InputStream, byte[])

MultipartStream

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

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

パラメータ:
input - データソースを出力する InputStream
boundary - ストリームを encapsulations に分割するために使用するトークン。
例外:
IOException - エラーが発生した場合。
関連項目:
MultipartStream(), MultipartStream(InputStream, byte[], int)
メソッドの詳細

getHeaderEncoding

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

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

setHeaderEncoding

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

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

readByte

public byte readByte()
              throws IOException
バッファからバイトを返し、必要な分だけ補充します。

戻り値:
入力ストリームから読み出した次のバイト。
例外:
IOException - もうこれ以上データがない場合。

readBoundary

public boolean readBoundary()
                     throws MultipartStream.MalformedStreamException
boundary トークンをスキップし、 ストリーム内にさらに encapsulations があるかどうかチェックします。

戻り値:
true ストリーム内にさらに encapsulations がある場合; false それ以外の場合。
例外:
MultipartStream.MalformedStreamException - ストリームが不意に終了した場合、 または文法の解釈に失敗した場合。

setBoundary

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

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

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

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

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

パラメータ:
boundary - 入れ子になったストリームのパースに使用するバウンダリ。
例外:
MultipartStream.IllegalBoundaryException - boundary の長さが現在使用されているものと違った場合。

readHeaders

public String readHeaders()
                   throws MultipartStream.MalformedStreamException

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

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

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

戻り値:
現在の encapsulationheader-part
例外:
MultipartStream.MalformedStreamException - ストリームが不意に終了した場合。

readBodyData

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

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

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

パラメータ:
output - データを書き出す対象となる Stream
戻り値:
書き出したデータの量。
例外:
MultipartStream.MalformedStreamException - ストリームが不意に終了した場合。
IOException - 入出力エラーが発生した場合。

discardBodyData

public int discardBodyData()
                    throws MultipartStream.MalformedStreamException,
                           IOException
現在の encapsulation から body-data を読み込み、これを破棄します。

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

戻り値:
破棄したデータの量。
例外:
MultipartStream.MalformedStreamException - ストリームが不意に終了した場合。
IOException - 入出力エラーが発生した場合。

skipPreamble

public boolean skipPreamble()
                     throws IOException
最初の encapsulation の始まりを捜し出します。

戻り値:
true ストリーム内に encapsulation が見つかった場合。
例外:
IOException - 入出力エラーが発生した場合。

arrayequals

public static boolean arrayequals(byte[] a,
                                  byte[] b,
                                  int count)
2つのバイト配列の先頭から指定されたインデックス分を比較します。

パラメータ:
a - 最初の比較対象となる配列。
b - 2番目の比較対象となる配列。
count - 比較対象となる(先頭からの)バイト数。
戻り値:
true 配列 ab の先頭から count 分のバイト配列が等しい場合。

findByte

protected int findByte(byte value,
                       int pos)
バッファ内の指定された位置から指定されたバイトの値を検索します。

パラメータ:
value - 検索する値。
pos - 検索開始位置。
戻り値:
見つかったバイトのバッファの先頭からの位置。 見つからなかった場合には -1

findSeparator

protected int findSeparator()
バッファ内の headtail で区切られた範囲内から boundary を検索します。

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

toString

public String toString()
このオブジェクトの文字列表現を返します。

戻り値:
このオブジェクトの文字列表現。


このドキュメントは、Ja-Jakartaにより訳されました。 コメントがある場合は report@jajakarta.orgまでお願いします。
Translated into Japanese by jajakarta.org. The original page is here.
Copyright (c) 2002-2003 - Apache Software Foundation