このクラスはクライアントから受け取る multipart/form-data
* のPOSTリクエスト内のファイルまたはアイテムを表現したものです。
* {@primary This class represents a file or form item that was received within a
* multipart/form-data POST request.}
*
*
{@link org.apache.commons.fileupload.FileUpload FileUpload} * からこのクラスインスタンスを取得した後 * ( {@link org.apache.commons.fileupload.FileUpload * #parseRequest(javax.servlet.http.HttpServletRequest)} を参照) 、 * {@link #get()} メソッドを使ってすべてのファイルの内容を(メモリ上に)取得するか、 * {@link #getInputStream()} メソッドを使って {@link java.io.InputStream InputStream} * を取得し、メモリ上に展開することなくファイルを処理する * (大きなファイルを扱う場合に有用)かを選択することができます。 * {@primary After retrieving an instance of this class from a {@link * org.apache.commons.fileupload.FileUpload FileUpload} instance (see * {@link org.apache.commons.fileupload.FileUpload * #parseRequest(javax.servlet.http.HttpServletRequest)}), 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.} * *
このインターフェイスは(めったに使われない依存関係を避けるため)
* javax.activation.DataSource を継承していませんが、
* 定義されたいくつかのメソッドはこのインターフェイスとまったく同じ名称で定義されています。
* そのため、このインターフェイスの実装クラスに最低限の修正を加えることで
* javax.activation.DataSource も実装することができます。
* {@primary While this interface does not extend
* 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
* javax.activation.DataSource with minimal additional work.}
*
* @author Rafal Krzewski
* @author Sean Legassick
* @author Jason van Zyl
* @author Martin Cooper
* @translator 日置 聡
* @editor 入江 弘憲
* @status completion
* @update 2003/04/13
*
* @version $Id: FileItem.java,v 1.5 2004/04/13 09:29:57 hioki Exp $
*/
public interface FileItem
extends Serializable
{
// ------------------------------- Methods from javax.activation.DataSource
/**
* ファイルの内容を取得するための {@link java.io.InputStream InputStream}
* を返します。
* {@primary Returns an {@link java.io.InputStream InputStream} that can be
* used to retrieve the contents of the file.}
*
* @return ファイルの内容を取得するための {@link java.io.InputStream InputStream} 。
* {@primary An {@link java.io.InputStream InputStream} that can be
* used to retrieve the contents of the file.}
*
* @exception IOException エラーが発生した場合。
* {@primary if an error occurs.}
*/
InputStream getInputStream()
throws IOException;
/**
* ブラウザによって付加されたコンテントタイプを返します。
* 定義されていない場合には null を返します。
* {@primary Returns the content type passed by the browser or null if
* not defined.}
*
* @return ブラウザによって付加されたコンテントタイプ。
* 定義されていない場合には null。
* {@primary The content type passed by the browser or null if
* not defined.}
*/
String getContentType();
/**
* ブラウザ(または他のクライアントソフトウェア)によって渡された
* クライアントのファイルシステム上でのオリジナルのファイル名を返します。
* 大体の場合、これはパス情報を除いた元のファイル名になります。
* しかし、Operaブラウザ等のいくつかのクライアントではパス情報が含まれます。
* {@primary Returns the original filename in the client's filesystem, 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 クライアントのファイルシステム上でのオリジナルのファイル名。
* {@primary The original filename in the client's filesystem.}
*/
String getName();
// ------------------------------------------------------- FileItem methods
/**
* ファイルの内容をメモリ上から読み込むことができるかどうかを示します。
* {@primary Provides a hint as to whether or not the file contents will be read
* from memory.}
*
* @return true ファイルの内容をメモリ上から読み込むことができる場合;
* false その他の場合。
* {@primary true if the file contents will be read from memory;
* false otherwise.}
*/
boolean isInMemory();
/**
* ファイルアイテムのサイズを返します。
* {@primary Returns the size of the file item.}
*
* @return ファイルアイテムのバイト単位のサイズ 。
* {@primary The size of the file item, in bytes.}
*/
long getSize();
/**
* ファイルアイテムの内容をバイト配列で返します。
* {@primary Returns the contents of the file item as an array of bytes.}
*
* @return ファイルアイテムの内容を示すバイト配列。
* {@primary The contents of the file item as an array of bytes.}
*/
byte[] get();
/**
* 指定されたエンコーディングを使用してファイルアイテムの内容の文字列表現を返します。
* このメソッドはアイテムの内容を取得するために {@link #get()} メソッドを使用します。
* {@primary 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.}
*
* @param encoding 使用するキャラクタエンコーディング。
* {@primary The character encoding to use.}
*
* @return アイテムの内容の文字列表現。
* {@primary The contents of the item, as a string.}
*
* @exception UnsupportedEncodingException 指定されたエンコーディングが利用できなかった場合。
* {@primary if the requested character encoding is not available.}
*/
String getString(String encoding)
throws UnsupportedEncodingException;
/**
* デフォルトのキャラクタエンコーディングを使用してファイルアイテムの内容の文字列表現を返します。
* このメソッドはアイテムの内容を取得するために {@link #get()} メソッドを使用します。
* {@primary 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.}
*
* @return アイテムの内容の文字列表現。
* {@primary The contents of the item, as a string.}
*/
String getString();
/**
* アップロードアイテムをディスクに書き出すための簡易メソッドです。
* クライアントコードはアイテムがメモリに保持されているか、ディスクの一時領域に保持されているかを考慮しません。
* アップロードアイテムをファイルに書き出すことだけを考えます。
* {@primary 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.}
*
*
* このメソッドは同じアイテムに対して複数回コールされた場合、処理を保証しません。
* この事は特別な実装を可能とします。
* たとえばファイル名の変更はファイルのデータをすべてコピーするよりも
* 非常に大きなパフォーマンスのメリットをもたらします。
* {@primary
* 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 アップロードアイテムの出力先となる File 。
* {@primary The File into which the uploaded item should
* be stored.}
*
* @exception Exception エラーが発生した場合。
* {@primary if an error occurs.}
*/
void write(File file) throws Exception;
/**
* 関係する一時ディスク領域も含むストレージ上のファイルアイテムを削除します。
* FileItem インスタンスがガベージコレクションにかかった時にこのストレージは削除されますが、
* このメソッドは早く確実に削除を実施し、システムリソースを保護します。
* {@primary Deletes the underlying storage for a file item, including deleting any
* associated temporary disk file. Although this storage will be deleted
* automatically when the 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();
/**
* ファイルアイテムに対応したマルチパートフォームフィールド名を返します。
* {@primary Returns the name of the field in the multipart form corresponding to
* this file item.}
*
* @return フォームフィールド名。
* {@primary The name of the form field.}
*/
String getFieldName();
/**
* このファイルアイテムを参照するためのフィールド名を設定します。
* {@primary Sets the field name used to reference this file item.}
*
* @param name フォームフィールド名。
* {@primary The name of the form field.}
*/
void setFieldName(String name);
/**
* FileItem インスタンスが単純なフォームフィールドを示すかどうかを判断します。
* {@primary Determines whether or not a FileItem instance represents
* a simple form field.}
*
* @return true インスタンスが単純なフォームフィールドを示す場合;
* false インスタンスがアップロードされたファイルを示す場合。
* {@primary true if the instance represents a simple form
* field; false if it represents an uploaded file.}
*/
boolean isFormField();
/**
* FileItem インスタンスが単純なフォームフィールドを示すかどうかを設定します。
* {@primary Specifies whether or not a FileItem instance represents
* a simple form field.}
*
* @param state true インスタンスが単純なフォームフィールドを示す場合;
* false インスタンスがアップロードされたファイルを示す場合。
* {@primary true if the instance represents a simple form
* field; false if it represents an uploaded file.}
*/
void setFormField(boolean state);
/**
* ファイルの内容を保持するための {@link java.io.OutputStream OutputStream} を返します。
* {@primary Returns an {@link java.io.OutputStream OutputStream} that can
* be used for storing the contents of the file.}
*
* @return ファイルの内容を保持するための {@link java.io.OutputStream OutputStream} 。
* {@primary An {@link java.io.OutputStream OutputStream} that can be used
* for storing the contensts of the file.}
*
* @exception IOException エラーが発生した場合。
* {@primary if an error occurs.}
*/
OutputStream getOutputStream() throws IOException;
}