javax.servlet.jsp.tagext
インタフェース Tag

既知のサブインタフェースの一覧:

BodyTag, IterationTag

既知の実装クラスの一覧:

BodyTagSupport, TagSupport

public interface Tag

ボディの操作をしない簡単なタグハンドラのインターフェースです。 TagインターフェースはタグハンドラとJSPページ実装クラスとの間に基本的なプロトコルを定義します。 Tagインターフェースはライフサイクル、つまりタグの開始時と終了時に呼ばれるメソッドを定義します。

プロパティ

Tagインターフェースは、コアpageContextと親プロパティの設定と取得メソッドを定義しています。

JSPページ実装オブジェクトは、doStartTag()またはdoEndTag()の呼び出しより前に、setPageContextとsetParentを呼び出します。

メソッド

doStartTagとdoEndTagの2つのメインアクションがあります: 全ての特有なプロパティは一度だけ初期化され、doStartTagとdoEndTagメソッドはタグハンドラ上で呼び出されます。 これらの呼び出しの間で、タグハンドラは保護されなければならない状態を保持すると仮定されます。doEndTagの呼び出しの後、タグハンドラは以降の呼び出しで利用可能になります。(プロパティは保持されていると予想されます)

ライフサイクル ライフサイクルの詳細は、以下の状態遷移図とコメントで述べられます。

• [1] この遷移は長い期間、データを開放することを意図しています。 プロパティが保持されているかどうかについては保証されません。
• [2] この遷移は、例外を上げないでタグが正常終了した場合に限り起ります。
• [3] プロパティの状態は保証されていません。そのため、オプショナルなプロパティの値を設定したタグハンドラがあった場合、タグハンドラを再利用できるのは、（既知の）新しい値でそれらのプロパティを設定したときだけであることに注意してください。これは、タグハンドラは同じ"AttSet"(設定済みの属性セット)内で再利用されるだけであることを意味します。
• 追加情報は例外ハンドリングとリソース管理に関連するため、TryCatchFinallyインターフェースをチェックして下さい。

一度、タグハンドラからの全ての呼び出しが完成すると、releaseメソッドはその上で呼び出されます。 一度、releaseメソッドが呼び出されると、親とpageContextを含む全てのプロパティは、未定義の値にリセットされたものとみなされます。 ページコンパイラは、ハンドラがGCへリリースされる前にタグハンドラでrelease()が起動されることを保証します。

エンプティとノンエンプティアクション

TagLibraryDescriptorファイルで、"空"の<body-content>エントリーによって、アクションが常にエンプティアクションをもたなければならない指定した場合、doStartTag()メソッドはSKIP_BODYを返さなければなりません。 それ以外は、doStartTag()メソッドはSKIP_BODYまたはEVAL_BODY_INCLUDEを返すかもしれません。

もし、SKIP_BODYがボディから返された場合、評価されません。

もし、EVAL_BODY_INCLUDEが返された場合、ボディは評価され、現在の出力へ"流されます"。

フィールドの概要

static int	EVAL_BODY_INCLUDE 存在する出力ストリームを通してボディを評価します。
static int	EVAL_PAGE ページの評価を続けます。
static int	SKIP_BODY ボディ評価をスキップします。
static int	SKIP_PAGE ページの残り部分をスキップします。

メソッドの概要

int	doEndTag() このインスタンスの終了タグを処理します。
int	doStartTag() このインスタンスの開始タグを処理します。
Tag	getParent() このタグハンドラの親(最も近くを囲んでいるタグハンドラ)を取得します。
void	release() 状態を開放するためにTagハンドラで呼ばれます。
void	setPageContext(PageContext pc) 現在のページコンテキストを設定します。
void	setParent(Tag t) このタグハンドラの親(最も近くを囲んでいるタグハンドラ)を設定します。

フィールドの詳細

SKIP_BODY

public static final int SKIP_BODY

ボディ評価をスキップします。 doStartTagとdoAfterBodyの有効な戻り値です。

関連項目:

定数フィールド値

EVAL_BODY_INCLUDE

public static final int EVAL_BODY_INCLUDE

存在する出力ストリームを通してボディを評価します。 doStartTagの有効な戻り値です。

関連項目:

定数フィールド値

SKIP_PAGE

public static final int SKIP_PAGE

ページの残り部分をスキップします。 doEndTagの有効な戻り値です。

関連項目:

定数フィールド値

EVAL_PAGE

public static final int EVAL_PAGE

ページの評価を続けます。 doEndTag()の有効な戻り値です。

関連項目:

定数フィールド値

メソッドの詳細

setPageContext

public void setPageContext(PageContext pc)

現在のページコンテキストを設定します。 このメソッドはJSPページ実装オブジェクトによって、doStartTag()より前に呼び出されます。

この値はdoEndTag()によってリセット*されません*。もし doStartTag() の呼び出しの間に変更するなら、ページ実装によって明示的にリセットされなければいけません。

パラメータ:

pc - このタグハンドラのページコンテキスト。

setParent

public void setParent(Tag t)

このタグハンドラの親(最も近くを囲んでいるタグハンドラ)を設定します。 JSPページ実装オブジェクトによって、doStartTag()より前に呼び出されます。

この値は、doEndTag()によってリセット*されずに*、ページ実装によって明示的にリセットされなければなりません。

パラメータ:

t - 親タグまたはnull

getParent

public Tag getParent()

このタグハンドラの親(最も近くを囲んでいるタグハンドラ)を取得します。

getParent()メソッドは、カスタムアクション間の協調のために、ランタイム時にネストしたタグハンドラ構造をナビゲートするために使用できます。 たとえば、TagSupportのfindAncestorWithClass()メソッドは、このやり方の便利な方法を提供します。

仕様の現バージョンでは、タグハンドラの観測タイプを指示するたった一つの正式な方法しか提供していません: タグエレメントのタグクラス、サブエレメント内で述べられているタグハンドラ実装クラス。 これは、記述サブエレメント観測タイプで指示するタグライブラリー著者の許可によって非公式マナーとして展開されています。 タイプはタグハンドラ実装クラスまたはvoidのサブタイプであるべきです。 これに追加される制限は、独自タグライブラリーを認識している特別なコンテナによって開発可能です。

戻り値:

現在の親、または、もしないならばnull

関連項目:

TagSupport.findAncestorWithClass(javax.servlet.jsp.tagext.Tag, java.lang.Class)

doStartTag

public int doStartTag()
               throws JspException

このインスタンスの開始タグを処理します。 このメソッドはJSPページ実装オブジェクトによって起動されます。

doStartTagメソッドは、pageContextと親のプロパティが設定されていることを仮定します。 それはまた、属性として公開されたプロパティも設定されていると仮定します。 このメソッドが起動された時、ボディはまだ評価されていません。

このメソッドは、アクションのボディは評価されるべき、または他でSKIP_BODYを指定することと、指定するTag.EVAL_BODY_INCLUDEまたはBodyTag.EVAL_BODY_BUFFEREDを返します。

TagがEVAL_BODY_INCLUDEを返すとき、(もしあるなら)ボディの評価結果は現在の"出力"JspWriterに含まれます。 そして、doEndTag()が起動されます。

タグハンドラがBodyTagを実装している場合、BodyTag.EVAL_BODY_BUFFEREDは、単に有効です。

JSPコンテナは、doStartTag()の起動後、TagExtraInfo内で指示される変数と再同期します。

戻り値:

タグがボディを処理したい場合、EVAL_BODY_INCLUDE。処理したくない場合、SKIP_BODY

例外:

JspException.

JspException

関連項目:

BodyTag

doEndTag

public int doEndTag()
             throws JspException

このインスタンスの終了タグを処理します。 このメソッドは、全てのTagハンドラでJSPページ実装オブジェクトによって起動されます。

このメソッドは、doStartTagから実行された後に呼ばれます。 アクションのボディは評価されているかもしれないし、されているかもしれません。 それはdoStartTagの戻り値に依存します。

このメソッドがEVAL_PAGEを返した場合、ページの残り部分は評価され続けます。 このメソッドがSKIP_PAGEを返した場合、ページの残り部分は評価されず、リクエストは完了します。 このリクエストが転送された、または、他のページ(またはServlet)からインクルードされた場合、現ページ評価は完了します。

JSPコンテナは、doEndTag()起動後、TagExtraInfo内で指示する変数を再同期します。

戻り値:

JSPページの評価を続けるかどうかの指示

例外:

JspException.

JspException

release

public void release()

状態を開放するためにTagハンドラで呼ばれます。 ページコンパイラーはJSPページ実装オブジェクトがこのメソッドを全てのタグハンドラで呼び出すことを保証していますが、 間でdoStartTagやdoEndTagの起動を操作されるかもしれません。