Oracle® Fusion Middleware

Oracle WebLogic Server JSPタグ拡張のプログラミング

11gリリース1 (10.3.6)

B55531-05(原本部品番号:E13722-06)

2015年4月

このマニュアルは、JavaServer Page (JSP)でカスタム・タグを作成および使用するソフトウェア開発者を対象としてまた、JSPでカスタム・タグを使用するWebページ作成者も対象としています。

Oracle Fusion Middleware Oracle WebLogic Server JSPタグ拡張のプログラミング, 11gリリース1 (10.3.6)

B55531-05

Copyright © 2007, 2015, Oracle and/or its affiliates.All rights reserved.

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。適用されるお客様とOracle Corporationとの間の契約に別段の定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。適用されるお客様とOracle Corporationとの間の契約に定めがある場合を除いて、Oracle Corporationおよびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

目次

タイトルおよび著作権情報

はじめに

- ドキュメントのアクセシビリティについて

- 表記規則

1 概要とロードマップ

- ドキュメントの内容と対象読者

- このドキュメントの手引き

- 関連ドキュメント

- このリリースでのJSPの新機能と変更点

2 カスタムJSPタグの理解と作成

- タグ・ハンドラのAPIおよび実装

- カスタム・タグ・ライブラリ

- カスタム・タグのフォーマット

- カスタム・タグの機能

- JSPタグ・ライブラリの作成と構成:手順の例

3 タグ・ライブラリ記述子の作成

- タグ・ライブラリ記述子の概要

- タグ・ライブラリ記述子の記述

- タグ・ライブラリ記述子のサンプル

- DynamicAttributesインタフェース

- タグ・ハンドラによる動的な属性のサポート

- 動的な属性の例

- 動的な属性の構文

4 タグ・ハンドラの実装

- シンプル・タグ・ハンドラのライフサイクル(SimpleTagインタフェース)

- シンプル・タグ・ハンドラのライフサイクルにおけるイベント

- JSPフラグメント

- タグ・ハンドラのライフサイクル(TagおよびBodyTagインタフェース)

- タグ本体の反復処理(IterationTagインタフェース)

- タグ本体内の例外処理

- タグ属性の使い方

- 新しいスクリプト変数の定義

- 動的名前付きスクリプト変数

- タグ・ライブラリ記述子の変数の定義

- 協調的ネスト・タグの記述

- タグ・ライブラリ・バリデータの使用

5 管理と構成

- JSPタグ・ライブラリの構成

- JSPタグ・ライブラリのJARファイルとしてのパッケージ化

はじめに

「はじめに」では、このガイド『Oracle WebLogic Server JSPタグ拡張のプログラミング』で使用されているドキュメント・アクセシビリティ機能および規則について説明します。

ドキュメントのアクセシビリティについて

Oracleのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイトhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=docaccを参照してください。

Oracleサポートへのアクセス

サポートをご購入のOracleのお客様は、My Oracle Supportにアクセスして電子サポートを受けることができます。詳細情報はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoか、聴覚に障害のあるお客様はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsを参照してください。

表記規則

このマニュアルでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するGraphical User Interface要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

斜体

イタリックは、ユーザーが特定の値を指定するプレースホルダー変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

1 概要とロードマップ

この章では、このマニュアル『Oracle Fusion Middleware Oracle WebLogic Server JSPタグ拡張のプログラミング』の内容と構成について説明します。

- ドキュメントの内容と対象読者

- このドキュメントの手引き

- 関連ドキュメント

- このリリースでのJSPの新機能と変更点

ドキュメントの内容と対象読者

JSP 2.1仕様により、Java Server Page (JSP)でカスタム・タグを作成および使用できます。カスタム・タグは、Webページ作成者が使いやすく管理しやすいように、Webページのプレゼンテーションからビジネス・ロジックの複雑さを分離するための優れた方法です。JSPページでカスタムJSPタグ拡張を使用すると、動的コンテンツを生成できます。また、様々なWeb開発ツールを使用して、プレゼンテーションを作成できるようになります。

WebLogic Serverは、http://java.sun.com/products/jsp/reference/api/index.htmlでJSP 2.0仕様に定義されているタグ拡張メカニズムを完全にサポートしています。

このマニュアルは、Java Server Page (JSP)でカスタム・タグを作成および使用するソフトウェア開発者を対象としています。また、JSPでカスタム・タグを使用するWebページ作成者も対象です。

このマニュアルでは、プロダクション段階での管理、モニター、パフォーマンス・チューニングについては扱いません。これらのトピックに関するWebLogic Serverのドキュメントとリソースへのリンクについては、「関連ドキュメント」を参照してください。

このマニュアルは、Java EEプラットフォームおよびJSPの概念に精通している読者を対象としています。

このドキュメントの手引き

- 第1章「概要とロードマップ」では、このガイドの構成を紹介します。

- 第2章「カスタムJSPタグの理解と作成」では、カスタムJSPタグの機能、フォーマットおよびコンポーネントの概要、ならびにタグ・ライブラリの作成と構成の手順について説明します。

- 第3章「タグ・ライブラリ記述子の作成」では、タグ・ライブラリ記述子(TLD)ファイルの作成方法を説明します。

- 第4章「タグ・ハンドラの実装」では、拡張タグの機能を実装するJavaクラスを記述する方法について説明します。

- 第5章「管理と構成」では、JSPタグ拡張を使用するための管理タスクと構成タスクの概要を示します。

関連ドキュメント

このマニュアルには、JSP拡張に固有の設計および開発上の情報が含まれています。

WebLogic Serverアプリケーションを開発、デプロイ、およびモニターするための包括的なガイドラインについては、以下のドキュメントを参照してください。

- 『Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発』は、WebLogic Serverアプリケーションの開発ガイドです。

- 『Oracle WebLogic Serverアプリケーションの開発』は、WebLogic Serverアプリケーションの開発ガイドです。

- 『Oracle WebLogic Serverへのアプリケーションのデプロイ』は、WebLogic Serverアプリケーションのデプロイメントについての情報のプライマリ・ソースです。

- 「JavaServer Pages Tutorial」(http://download.oracle.com/javaee/5/tutorial/doc/)

- JavaServer Pages (JSP)製品概要(http://www.oracle.com/technetwork/java/javaee/jsp/index.html)

- JSP 2.1仕様(http://java.sun.com/products/jsp/reference/api/index.html)

このリリースでのJSPの新機能と変更点

このリリースで導入されたWebLogic Serverの包括的な新機能一覧は、『Oracle WebLogic Serverの新機能』を参照してください。

2 カスタムJSPタグの理解と作成

この章では、カスタムJSPタグの機能、フォーマット、およびコンポーネントの概要、ならびにタグ・ライブラリの作成と構成の手順について説明します。

- タグ・ハンドラのAPIおよび実装

- カスタム・タグ・ライブラリ

- カスタム・タグのフォーマット

- カスタム・タグの機能

- JSPタグ・ライブラリの作成と構成:手順の例

タグ・ハンドラのAPIおよび実装

カスタムJSPタグを作成するには、タグ・ハンドラと呼ばれるJavaクラスを作成します。

JSP 2.1 APIには、JSP 2.1仕様での説明どおりhttp://java.sun.com/products/jsp/reference/api/index.htmlで、カスタム・タグ・ハンドラの作成に使用するクラスとインタフェースのセットが説明されます。

javax.servlet.jsp.tagext APIに関するドキュメントは、http://download.oracle.com/docs/cd/E17802_01/products/products/jsp/2.1/docs/jsp-2_1-pfd2/index.htmlにあります。

タグ・ハンドラは、次の2つのタイプのどちらかである必要があります。

- 以下の3つのインタフェースのいずれかを実装する従来のタグ・ハンドラ。
Tag - インタフェースにアクセスする必要のないカスタム・タグを作成している場合は、javax.servlet.jsp.tagext.Tagインタフェースを実装します。このAPIは、コンビニエンス・クラスTagSupportも提供します。このクラスは、Tagインタフェースを実装し、このインタフェース内で定義されているメソッド用のデフォルトの空メソッドを提供します。

BodyTag - カスタム・タグが本体を使用する必要がある場合、javax.servlet.jsp.tagext.BodyTagインタフェースを実装します。このAPIは、コンビニエンス・クラスBodyTagSupportも提供します。このクラスは、BodyTagインタフェースを実装し、このインタフェース内で定義されているメソッド用のデフォルトの空メソッドを提供します。BodyTagはTagを拡張したものであり、インタフェース・メソッドのスーパーセットです。

IterationTag - 本体の再評価を制御する追加のメソッドdoAfterBody()を定義して、tagを拡張する、javax.servlet.jsp.tagext.IterationTagインタフェースを実装します。

- シンプル・タグ・ハンドラ(SimpleTagインタフェース)。
大幅に簡素化された呼出しプロトコルを使用する場合は、javax.servlet.jsp.tagext.SimpleTagインタフェースを実装します。SimpleTagインタフェースでは、BodyTagインタフェースのようにjavax.servlet.jsp.tagext.Tagインタフェースを拡張しません。したがって、SimpleTagインタフェースはdoStartTag()およびdoEndTag()メソッドをサポートするのではなく、simple doTag()メソッドを提供します。このメソッドはタグ呼出しごとに一度だけ呼び出されます。

タグ・ハンドラは、以下のいずれかの方法で作成します。

- タグのライフサイクルの間に呼び出されるメソッドを定義するSimpleTag、TagまたはBodyTagインタフェースを実装します。

- SimpleTag、Tag、またはBodyTagインタフェースを実装する抽象ベース・クラスを拡張します。

抽象ベース・クラスを拡張すると、タグ・ハンドラ・クラスがそのインタフェース内のすべてのメソッドを実装する必要がなくなります。また、他の便利な機能を使用できるようになります。SimpleTagSupport、TagSupport、およびBodyTagSupportクラスが、SimpleTag、Tag、またはBodyTagインタフェースを実装し、APIに組み込まれます。

タグ・ライブラリには、1つ以上のカスタムJSPタグを格納することができます。タグ・ライブラリは、タグ・ライブラリ記述子(.tld)ファイルで定義します。TLDは各タグの構文を記述し、その機能を実行するJavaクラスにそのタグを関連付けます。

カスタム・タグ・ライブラリ

JSPタグ・ライブラリは、1つ以上のカスタムJSPタグを格納しており、タグ・ライブラリ記述子(.tld)ファイルで定義されます。JSPページからカスタム・タグ・ライブラリを使用するには、以下のように<%@ taglib %>ディレクティブを使用してそのタグ・ライブラリ記述子を参照します。例:

<%@ taglib uri="myTLD" prefix="mytaglib" %>

- uri
JSPエンジンは、Webアプリケーション・デプロイメント記述子(web.xml)の<taglib-uri>要素で定義したuriと、このuri属性を照合することによって、タグ・ライブラリ記述子ファイルを見つけようとします。

注意:
.tldファイルがデフォルトの場所(/WEB-INF/または/WEB-INF/tags/)にある場合、<%@ taglib uri='myTLD' prefix='mytaglib' %>であるuri値が.tldファイルで指定されているuriと同じであれば、web.xmlで<taglib>を記載する必要はありません。詳細は、JSP 2.1仕様を参照してください。

たとえば、上のtaglibディレクティブのmyTLDは、次のようにWebアプリケーション・デプロイメント記述子のタグ・ライブラリ記述子(library.tld)を参照します。

<taglib>
<taglib-uri>myTLD</taglib-uri>
<taglib-location>library.tld</taglib-location>
</taglib>

- prefix
prefix属性は、タグ・ライブラリにラベルを割り当てます。カスタムJSPタグを使用してページを作成する場合は、このラベルを使って関連するタグ・ライブラリを参照します。たとえば、上の例のライブラリ(mytaglib)がnewtagという新しいタグを定義した場合、このタグをJSPページで使用するには、以下のように記述します。

<mytaglib:newtag>

詳細は、第3章「タグ・ライブラリ記述子の作成」を参照してください。

カスタム・タグのフォーマット

カスタム・タグのフォーマットは、空タグと呼ばれる空のものか、本体付きタグと呼ばれる本体を含むものです。どちらのタイプのタグも、そのタグを実装するJavaクラスに渡される複数の属性を受け付けます。詳細は、「タグ本体内の例外処理」を参照してください。

空タグの形式は次のとおりです。

<mytaglib:newtag attr1="aaa" attr2="bbb" ... />

本体付きタグの形式は次のとおりです。

<mytaglib:newtag attr1="aaa" attr2="bbb" ... >
body
</mytaglib:newtag>

タグ本体には、多くのJSP構文、およびネストされた本体を持つ別のカスタムJSPタグを入れることができます。タグは、お互いの内部で任意のレベルにネストできます。例:

<mytaglib:tagA>
<h2>This is the body of tagA</h2>
You have seen this text <mytaglib:counter /> times!
<p>
<mytaglib:repeater repeat=4>
<p>Hello World!
</mytaglib:repeater>
</mytaglib:tagA>

上の例では、3つのカスタム・タグを使用して、本体付きタグの中にタグをネストする方法が示されています。これらのタグは、以下のように機能します。

- 本体付きタグ<mytaglib:tagA>は、その評価済み本体からのHTML出力しか認識しません。つまり、ネストされたJSPタグの<mytaglib:counter>と<mytaglib:repeater>がまず評価され、それらの出力が<mytaglib:tagA>タグの評価済み本体の一部になります。

- 本体付きタグの本体がまずJSPとして評価され、ネストされた本体付きタグも含め、その中に入っているすべてのタグが変換され、さらにそれらの本体が再帰的に評価されます。評価済み本体の結果が本体付きタグの出力として直接使用されるか、本体付きタグがその評価済み本体のコンテンツに基づいて出力を決定します。

- 本体付きタグのJSPから生成される出力は、通常のHTMLとして取り扱われます。つまり、出力はさらにJSPとして解釈されることはありません。

カスタム・タグの機能

カスタム・タグは、以下のタスクを実行できます。

- 出力を生成します。タグの出力はその親スコープに送られます。スコープは以下のいずれかです。

- そのタグがJSPページに直接含まれる場合には、そのJSPページの出力が親スコープとなります。

- そのタグが別の親タグ内でネストされている場合、その出力はその親タグの評価済み本体の一部になります。

- JSPページの中でスクリプト変数として参照および使用できる新しいオブジェクトを定義します。タグは、固定名前付きスクリプト変数を導入するか、id属性を備えた動的名前付きスクリプト変数を定義できます。

- 一定の条件が満たされるまで、そのタグ本体のコンテンツの処理を繰り返します。これは、出力を反復的に生成するため、またはサーバー側アクションを繰返し呼び出すために使用します。

- そのJSPページの残りの部分を要求の一部として処理するか、それともスキップするかを決定します。

- 空タグは、そのタグの属性に基づいてサーバー側の作業を実行できます。そのタグが実行するアクションによって、ページの残りの部分を解釈するか、それともリダイレクトなどの別のアクションを実行するかが決められます。この機能は、ユーザーがページにアクセスする前にログインしたかどうかをチェックし、ログインしていなければログイン・ページにリダイレクトする場合に役立ちます。

- 空タグは、その属性に基づいてページにコンテンツを挿入できます。このようなタグを使用すると、ページのヒット数を数える単純なカウンタや、その他のテンプレート・ベースの挿入を実装できます。

- 空タグは、その属性に基づいて、ページの残りの部分で使用可能なサーバー側オブジェクトを定義できます。このタグを使用すると、同じJSPページ内の他の場所でデータの問合せを受けることができるEJBへの参照を作成することができます。

- 本体付きタグは、ブラウザに送信されるHTMLページの一部となる前にその出力を処理し、その出力を評価して、ブラウザに送信するHTMLを決定できます。この機能は、「引用HTML」、つまり再フォーマットされたコンテンツを生成するために、またはSQL問合せなどの他の関数に渡すパラメータとして使用できます(SQL問合せの場合、タグの出力はフォーマットされた結果セットとなります)。

- 本体付きタグは、特定の条件が満たされるまで、その本体を繰返し処理できます。

JSPタグ・ライブラリの作成と構成:手順の例

カスタムJSPタグを作成および使用するには、以下の手順を実行します。

1. タグ・ハンドラ・クラスを記述します。JSPでカスタム・タグを使用する場合、このクラスはそのタグの機能を実行します。タグ・ハンドラ・クラスでは、次の3つのインタフェースのいずれかが実装されます。

javax.servlet.jsp.tagext.BodyTag
javax.servlet.jsp.tagext.Tag
javax.servlet.jsp.tagext.SimpleTag

タグ・ハンドラ・クラスは、タグ・ライブラリの一部として実装されます。詳細は、第4章「タグ・ハンドラの実装」を参照してください。

2. JSPソース内で、JSP <taglib>ディレクティブを使用してタグ・ライブラリを参照します。タグ・ライブラリは、JSPタグを集めたものです。このディレクティブをJSPソースの先頭に挿入します。詳細は、「JSPタグ・ライブラリの構成」を参照してください。

3. タグ・ライブラリ記述子(TLD)を記述します。TLDは、タグ・ライブラリを定義し、タグ・ハンドラ・クラス名、属性、タグに関するその他の情報など、各タグに関する追加情報を提供します。詳細は、第3章「タグ・ライブラリ記述子の作成」を参照してください。

4. TLDを、Webアプリケーション・デプロイメント記述子(web.xml)で参照してください。

5. JSPでカスタム・タグを使用します。詳細は、「JSPタグ・ライブラリの構成」を参照してください。

3 タグ・ライブラリ記述子の作成

この章では、タグ・ライブラリ記述子(TLD)の作成方法を説明します。

- タグ・ライブラリ記述子の概要

- タグ・ライブラリ記述子の記述

- タグ・ライブラリ記述子のサンプル

- DynamicAttributesインタフェース

- タグ・ハンドラによる動的な属性のサポート

タグ・ライブラリ記述子の概要

タグ・ライブラリを使用すると、開発者は関連する機能を持つタグを1つにまとめることができます。タグ・ライブラリには、タグ拡張を記述し、それらをJavaクラスに関連付けるタグ・ライブラリ記述子(TLD)ファイルが必要となります。TLDは、WebLogic Serverとオーサリング・ツールが拡張機能に関する情報を取得するために使用されます。TLDファイルのファイル拡張子は.tldで、このファイルはXML表記法で記述されます。

タグ・ライブラリ記述子の記述

タグ・ライブラリ記述子ファイル内の要素は、XSDに定義されている順序で並べます。この順序付けは、以下に示す手順で使用されます。TLD要素がこの順序どおりに並べられていない場合、XMLパーサーは例外を送出します。

TLDの本体は、<taglib> ... </taglib>要素の中にネストされた要素を含んでいます。これらのネストされた要素についても次の手順で説明します。このドキュメントでは、見やすくするためにネストされた要素はその親要素からインデントされていますが、TLDではインデント処理は必要ありません。

「タグ・ライブラリ記述子のサンプル」の例では、codeという新しいタグを宣言します。このタグの機能は、Javaクラスのweblogic.taglib.quote.CodeTagによって実装されます。

TLDを作成するには、次の手順に従います。

1. テキスト・ファイルを作成して、適切な名前と拡張子.tldを付け、JSPを持つWebアプリケーションのWEB-INFディレクトリに保存します。WEB-INFディレクトリの内容は非公開で、WebLogic ServerによってHTTPを介して提供されません。

2. 次のヘッダーを追加します。

<taglib version="2.0" xmlns="http://java.sun.com/xml/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd">

3. 手順4 - 7の指示に従い、TLDのコンテンツを、<taglib>要素の中に埋めこみます。コンテンツには、タグ・ライブラリに関する情報を含む要素と、各タグを定義する要素が含まれます。例:

<taglib>
... body of taglib descriptor ...
</taglib>

4. タグ・ライブラリを指定します。

<tlib-version>version_number</tlib-version>

(必須)タグ・ライブラリのバージョン番号。

<jsp-version>version_number</jsp-version>

(必須)このタグ・ライブラリが機能するために必要なJSP仕様のバージョン(番号)を記述します。デフォルトは2.0です。

<short-name>TagLibraryName</short-name>

(必須)タグ・ライブラリに短縮名を割り当てます。この要素は、WebLogic Serverでは使用されません。

<uri>unique_string</uri>

(必須)このバージョンのタグ・ライブラリをユニークに識別するパブリックなURIを定義します。

<display-name>display_name</display-name>

(オプション)ツールによって表示される短縮名を指定します。

<icon>

<small-icon>icon.jpg</small-icon>

(オプション)小さいアイコン(16 x 16)の画像が含まれるファイルの名前を指定します。ファイル名はタグ・ライブラリ内の相対パスです。画像はJPEGまたはGIF形式で、ファイル名はそれぞれ「.jpg」または「.gif」という接尾辞で終わる必要があります。アイコンはツールによって使用されます。

<large-icon>icon.jpg</large-icon>

(オプション)大きいアイコン(32 x 32)の画像が含まれるファイルの名前を指定します。ファイル名はタグ・ライブラリ内の相対パスです。画像はJPEGまたはGIF形式で、ファイル名はそれぞれ「.jpg」または「.gif」という接尾辞で終わる必要があります。アイコンはツールによって使用されます。

</icon>

<description>...text...</description>

(必須)タグ・ライブラリについて説明する任意のテキスト文字列を定義します。

<validator>unique_string</validator>

(オプション)このタグでスクリプト変数の情報を定義します。1つまたは複数の変数の下位要素を持つタグに、null以外のオブジェクトを返すTagExtraInfoクラスがある場合には、変換時エラーが発生します。

<listener>unique_string</listener>

(オプション)自動的にインスタンス化および登録される任意のイベント・リスナー・オブジェクトを定義します。

5. タグ・ライブラリ・バリデータを定義します(オプション)。

<validator>

バリデータの最上位要素。

<validator-class>my.validator</validator-class>

(必須)検証を実行するJavaクラス。

<init-param>

(オプション)バリデータ・クラスの初期化パラメータを定義します。

<param-name>param</param-name>

このパラメータの名前を定義します。

<param-value>value</param-value>

このパラメータの名前を定義します。

6. タグを定義します。
タグ・ライブラリに新しいタグを定義するには、それぞれ別個の<tag>要素を使用します。<tag>要素には、以下のネスト・タグを埋め込むことができます。

<name>tag_name</name>

(必須)タグの名前を指定します。JSPファイルのタグを参照するときに、次のように「:」という記号の後に使用します。

<mytaglib:tag_name>

詳細は、「このリリースでのJSPの新機能と変更点」を参照してください。

<tag-class>package.class.name</tag-class>

(必須)このタグの機能を実装するタグ・ハンドラ・クラスを宣言します。そのクラスの完全修飾パッケージ名を指定します。

クラス・ファイルは、 WEB-INF/classes ディレクトリの下に、パッケージ名を反映したディレクトリ構造に従って配置します。タグ・ライブラリjarファイルにクラスをパッケージ化することもできます。詳細は、「JSPタグ・ライブラリのJARファイルとしてのパッケージ化」を参照してください。

<tei-class>package.class.name</tei-class>

(オプション)このタグによって導入されるスクリプト変数を記述するTagExtraInfoのサブクラスを宣言します。タグが新しいスクリプト変数を定義しない場合、この要素は使われません。そのクラスの完全修飾パッケージ名を指定します。このクラスに含まれるタグの属性を検証できます。

クラス・ファイルは、Webアプリケーションの WEB-INF/classes ディレクトリの下に、パッケージ名を反映したディレクトリ構造に従って配置します。タグ・ライブラリjarファイルにクラスをパッケージ化することもできます。詳細は、「JSPタグ・ライブラリのJARファイルとしてのパッケージ化」を参照してください。

<body-content>empty | JSP | scriptless | tagdependent</body-content>

(オプション)タグ本体のコンテンツを定義します。

emptyを指定すると、タグはJSPページ内で空タグ・フォーマットで使用されます。例:

<taglib:tagname/>

JSPを指定すると、タグのコンテンツはJSPとして解釈され、タグは本体付きフォーマットで使用する必要があります。例:

<taglib:tagname>...</taglib:tagname>

scriptlessを指定すると、タグのコンテンツにはスクリプトやスクリプト記述要素が一切含まれません。

tagdependentを指定すると、タグは本体のコンテンツをJSP以外のもの(たとえばSQL文)であると解釈します。

<attribute>

(オプション) JSPページ内のタグ要素に指定できる属性の名前を定義します。例:

<taglib:mytag myAttribute="myAttributeValue">

タグに指定できる属性を定義するには、それぞれ別個の<attribute>要素を使用します。タグ属性を使用すると、JSP作成者はタグの動作を変更できます。

<name>myAttribute</name>
<required>true | false</required>

(オプション)この属性がJSPページの中でオプションとして使用されるかどうかを定義します。ここで定義しない場合、デフォルトはfalse、つまりその属性は省略可能となります。trueが指定され、その属性がJSPページの中で使用されない場合、変換時エラーが発生します。

<rtexprvalue>true | false</rtexprvalue>

(オプション)この属性の値としてスクリプトレット式を指定して、要求時にそれを動的に計算できるようにするかどうかを定義します。この要素を指定しない場合、デフォルトとしてfalseが使用されます。

</attribute>

7. スクリプト変数を定義します(オプション)。

<tag>要素内にスクリプト変数を定義できます。

<variable>

変数の宣言の最上位要素。

<name-given>someName</name-given>

変数の名前を定義します。使用する属性から名前を定義できます。

<name-from-attribute>attrName</name-from-attribute>

attrNameの値を使用して変数の名前を指定します。

<variable-class>some.java.type</variable-class>

この変数のJavaタイプ。

<declare>true</declare>

(オプション) trueに設定する場合、変数が定義されることを示します。

<scope>AT_BEGIN</scope>

スクリプト変数のスコープ。有効なオプションは以下のとおりです。

- NESTED (変数はタグ本体の内部でのみ使用できます)

- AT_BEGIN (変数は本体を実行する直前に定義されます)

- AT_END (変数は本体を実行した直後に定義されます)

</variable>

タグ・ライブラリ記述子のサンプル

以下にタグ・ライブラリ記述子のサンプルを示します。

例3-1 タグ・ライブラリ記述子(tld)のサンプル

<taglib version="2.0" xmlns="http://java.sun.com/xml/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd">
<taglib>
<tlib-version>2.0</tlib-version>
<jsp-version>2.0</jsp-version>
<short-name>quote</short-name>
<uri>tag lib version id</uri>
<description>
This tag library contains several tag extensions
useful for formatting content for HTML.
</description>

<tag>
<name>code</name>
<tag-class>weblogic.taglib.quote.CodeTag</tag-class>
<body-content>tagdependent</body-content>
<attribute>
<name>fontAttributes</name>
</attribute>
<attribute>
<name>commentColor</name>
</attribute>
<attribute>
<name>quoteColor</name>
</attribute>
</tag>
</taglib>

DynamicAttributesインタフェース

JSP 2.0コンテナでサポートされるDynamicAttributesインタフェースにより、開発の時点で名前が既知でなくても値が一貫性のある方法で処理されるタグを使用できます。たとえば、<table> HTMLタグのwidth部分を、実行時に値を決定してカスタマイズする場合は、DynamicAttributesインタフェースを利用して、<table>タグの他の部分(border、cellspacingなど)に指定を行うことなく、タグの変更する部分だけをカスタマイズできます。DynamicAttributesインタフェースを使用せずにwidthの値を実行時に動的に決定するには、タグ・ハンドラなどの複雑なコードを記述しなければなりません。

タグ・ハンドラによる動的な属性のサポート

タグ・ハンドラで動的な属性を受け付けるかどうかを最終的に決定するのはTLDです。タグ・ハンドラで、TLDにおいて動的な属性をサポートすると宣言しているにも関わらず、DynamicAttributesインタフェースがサポートされていない場合、タグ・ハンドラはコンテナによって無効と見なされます。

呼び出されるタグのdynamic-attributes要素(作成されているタグ・ライブラリのtag要素の子要素)に、値trueが含まれている場合、以下の要件が適用されます。

- TLD内に対応する属性要素のないタグ呼出しで指定された各属性について、属性のネームスペース(または、属性にネームスペースも接頭辞もない場合はnull)、ネームスペース接頭辞なしの属性名、および属性の最終的な値を渡すsetDynamicAttribute()を呼び出す必要があります。

- 動的な属性は、要求時の式の値を受け付けるものと見なされる必要があります。

- 動的な属性は、java.lang.Object型として扱われる必要があります。

- JSPコンテナは、<jsp:attribute>標準アクションを使用してタグ・ハンドラに渡される動的な属性を認識する必要があります。

- setDynamicAttribute()メソッドがJspExceptionを送出する場合、doStartTag()またはdoTag()メソッドはこのタグに対しては呼び出されず、例外は通常の属性セッター・メソッドから送出された場合と同様に扱われる必要があります。

- 標準構文またはXML構文のどちらのJSPドキュメントでも、動的な属性がネームスペースにマップされない接頭辞を持つ場合は、変換エラーが発生します。標準の構文では、taglibディレクティブで定義されたネームスペースだけが認識されます。

動的な属性の例

以下の例では、属性aおよびbが、TLDの属性要素で宣言されており、属性d1およびd2が宣言されておらず、dynamic-attributes要素がtrueに設定されています。各属性は次の呼出しを使用して設定します。

- setA( "1" ),

- setDynamicAttribute( null, "d1", "2" ),

- setDynamicAttribute( "http://www.foo.com/jsp/taglib/mytag.tld", "d2", "3" ),

- setB( "4" ),

- setDynamicAttribute( null, "d3", "5" ),および

- setDynamicAttribute( "http://www.foo.com/jsp/taglib/mytag.tld", "d4", "6" ).

例3-2 動的な属性の例

<jsp:root xmlns:mytag="http://www.foo.com/jsp/taglib/mytag.tld" version="2.0">
<mytag:invokeDynamic a="1" d1="2" mytag:d2="3">
<jsp:attribute name="b">4</jsp:attribute>
<jsp:attribute name="d3">5</jsp:attribute>
<jsp:attribute name="mytag:d4">6</jsp:attribute>
</mytag:invokeDynamic>
</jsp:root>

動的な属性の構文

タグにおいて動的な属性を受け付けると宣言するためには、DynamicAttributesインタフェースが実装されている必要があります。構文は以下のとおりです。

public interface DynamicAttributes

また、動的な属性が受け付けられていることを示すために、TLDのタグのエントリを構成する必要があります。このタグのTLDで宣言されていない属性については、変換時にエラーを受け取るのではなく、その属性の名前と値で、setDynamicAttribute()メソッドが呼び出されます。動的な属性の名前と値を記憶するようにタグを構成します。

setDynamicAttribute()メソッドは、動的な属性を受け付けるように宣言されたタグが、TLDで宣言されていない属性を渡したときに、呼び出されます。構文は以下のとおりです。

public void setDynamicAttribute(java.lang.String uri, java.lang.String localName, java.lang.Object value)

パラメータ値は次のとおりです。

- uri - 属性のネームスペース、またはデフォルトのネームスペース内であればnull。

- localName - 設定されている属性の名前。

- value - 属性の値。

タグ・ハンドラが、所定の属性を受け付けないことを示す場合は、JspExceptionが送出されます。このタグに対して、コンテナはdoStartTag()またはdoTag()を呼び出すことはできません。

これらのインタフェースの詳細は、DynamicAttributes API (http://download.oracle.com/javaee/5/api/javax/servlet/jsp/tagext/DynamicAttributes.html)を参照してください。

4 タグ・ハンドラの実装

この章では、拡張タグの機能を実装するJavaクラスを記述する方法について説明します。

- シンプル・タグ・ハンドラのライフサイクル(SimpleTagインタフェース)

- タグ・ハンドラのライフサイクル(TagおよびBodyTagインタフェース)

- タグ本体の反復処理(IterationTagインタフェース)

- タグ本体内の例外処理

- タグ属性の使い方

- 新しいスクリプト変数の定義

- 協調的ネスト・タグの記述

- タグ・ライブラリ・バリデータの使用

シンプル・タグ・ハンドラのライフサイクル(SimpleTagインタフェース)

シンプル・タグ・ハンドラでは、従来のタグ・ハンドラと比べて、大幅に簡素化された呼出しプロトコルが提示されます。タグ・ライブラリ記述子は、物理的な基底の実装に対して、タグ・ライブラリ宣言をマップします。シンプル・タグ・ハンドラは、SimpleTagインタフェースを実装するクラスによってJavaで表現されます。

シンプル・タグ・ハンドラのライフサイクルは簡単明瞭なものであり、キャッシングのセマンティクスによって複雑化されていません。一旦コンテナによってインスタンス化されたシンプル・タグ・ハンドラは、実行され、その後破棄されます。同じインスタンスをキャッシュして再利用することはできません。初期パフォーマンスのメトリックにより、タグ・ハンドラ・インスタンスをキャッシュしても、必ずしもパフォーマンスが向上するわけではないことがわかります。そのようなキャッシングに対応しようとすると、ポータブル・タグ・ハンドラの記述が困難になり、タグ・ハンドラでエラーが生じやすくなります。

扱いが簡単であることに加えて、シンプル・タグの拡張では、いかなるサーブレットAPIにも直接的な依存がないため、将来的な他の技術との統合の可能性にも対応できます。この機能は、Page-Contextによって拡張されたJspContextクラスで促進されています。JspContextは、JspWriterの格納やスコープ指定された属性の追跡など、一般的なサービスを提供します。一方、PageContextはサーブレットのコンテキストにおけるJSPの処理に特化した機能を備えています。TagインタフェースはPageContextに依存していますが、SimpleTagはJspContextのみに依存しています。SimpleTagの本体は、もしあれば、JSPフラグメントに変換され、setJspBodyメソッドに渡されます。タグはその後、必要な回数、そのフラグメントを実行できます。「JSPフラグメント」を参照してください。

従来のタグ・ハンドラとは異なり、SimpleTagインタフェースは、Tagを拡張したものではありません。doStartTag()およびdoEndTag()をサポートするのではなく、SimpleTagインタフェースは単純なdoTag()メソッドを提供します。このメソッドは任意のタグ呼出しごとに一度だけ呼び出されます。すべてのタグのロジック、反復、本体評価などが、この単一のメソッド内で実行されます。したがって、シンプル・タグ・ハンドラはBodyTagと同等の能力を持ちますが、そのライフサイクルとインタフェースはずっと単純です。

本体のコンテンツをサポートするために、setJspBody()メソッドが提供されています。コンテナは、JspFragmentオブジェクトがタグの本体をカプセル化している状態でsetJspBody()メソッドを呼び出します。タグ・ハンドラの実装は、そのフラグメントに対してinvoke()を呼び出し、本体を評価できます。SimpleTagSupportコンビニエンス・クラスでは、これをさらに容易に行うための、getJsp-Body()やその他の有用なメソッドが用意されています。

シンプル・タグ・ハンドラのライフサイクルにおけるイベント

以下では、作成から呼出しに至るまでのシンプル・タグ・ハンドラのライフサイクルを説明します。シンプル・タグ・ハンドラが呼び出されると、次のイベントが順番に発生します。

1. シンプル・タグ・ハンドラが、最初は対応する実装クラスに対して0の引数コンストラクタを使用して作成されます。従来のタグ・ハンドラとは異なり、シンプル・タグ・ハンドラ・インスタンスは、決してコンテナにプールされることがありません。タグ呼出しごとに、新しいインスタンスを作成する必要があります。

2. setJspContext()およびsetParent()メソッドが、タグ・ハンドラに対して呼び出されます。渡されている値がnullの場合には、setParent()メソッドを呼び出す必要はありません。タグ・ファイルの場合、JspContextラッパーが作成されるので、タグ・ファイルは独自のページ・スコープを備えていると認識されます。getJspContext()は、ラップされたJsp-Contextを返す必要があります。

3. 次に、以下のルールに従って、XML要素の属性として指定される属性(存在する場合)が宣言された順序で評価されます(これを後述の「XML要素の評価」と称します)。適切なBeanプロパティ・セッターが、各々に対して呼び出されます。指定された属性に対してセッターが定義されておらず、しかしタグでは動的な属性を受け付けている場合、setDynamicAttribute()メソッドがセッターとして呼び出されます。
属性がスクリプト記述式(たとえば、JSP構文の「<%= 1+1 %>」またはXML構文の「%= 1+1 %」)である場合、式は評価され、その結果が変換されてセッターに渡されます。

また、属性に何らかの式言語表現(たとえば、「Hello ${name}」)が含まれていると、式は評価され、その結果が変換されてセッターに渡されます。

それ以外の場合、属性値は逐語的に取得され、変換されてセッターに渡されます。

4. 各<jsp:attribute>要素の値が評価され、タグの本体に登場する順序に従って、対応するBeanプロパティ・セッター・メソッドが各々について呼び出されます。指定された属性に対してセッターが定義されておらず、しかしタグでは動的な属性を受け付けている場合、setDynamicAttribute()メソッドがセッターとして呼び出されます。
また、属性のタイプがJspFragmentではない場合、コンテナは<jsp:attribute>要素の本体を評価します。この評価は、コンテナ固有のものとして行うことができます。コンテナの実装者は、この本体評価プロセスにおいて、他のカスタム・アクションが呼び出される可能性があることに留意してください。

また、属性のタイプがJspFragmentである場合、Jsp-Fragmentオブジェクトのインスタンスが作成されて渡されます。

5. タグ本体の値が決定され、本体が存在する場合は、setJsp-Body()メソッドがタグ・ハンドラに対して呼び出されます。
本体のコンテンツ(body-content)が空である、本体が存在しない、またはこの呼出しに対して空の本体が渡されたとタグで宣言されている場合には、setJspBody()は呼び出されません。

また、<jsp:body>または<jsp:attribute>要素が存在しない場合は、タグの本体は<jsp:body>要素の本体であるか、カスタム・アクション呼出しの本体であるかのいずれかです。この場合、Jsp-Fragmentオブジェクトのインスタンスが作成され、セッターに渡されます。タグが、tagdependentという本体コンテンツ(body-content)を有すると宣言された場合、JspFragmentは本体のコンテンツを逐語的に返す必要があります。

また、タグが、scriptlessというタイプの本体コンテンツ(body-content)を有すると宣言された場合、JspFragmentは本体のコンテンツをJSPのスクリプトなし本体として評価する必要があります。

6. doTag()メソッドが呼び出されます。

7. doTag()の実装により、潜在的に(タグ・ハンドラがタグ・ファイルとして実装されている場合は)他のタグ・ハンドラを呼び出し、フラグメントを呼び出して、機能が実行されます。

8. doTag()メソッドが返り、タグ・ハンドラ・インスタンスが破棄されます。Skip-PageExceptionが送出されると、ページの残りの部分は評価されず、要求が完了します。この要求が別のページ(またはサーブレット)から転送されている、または組み込まれている場合、現在のページの評価だけが停止します。

9. AT_BEGINまたはAT_ENDのスコープで宣言されたタグ・スクリプト変数の各々について、クラシック・タグ・ハンドラの場合と同じく、適切なスクリプト変数とスコープ指定された属性が宣言されます。

JSPフラグメント

JSPフラグメントとは、必要に応じて何度でも呼び出せる、JSPコードのタグ・ハンドラに渡される部分です。フラグメントは、カスタマイズされたコンテンツを生成するためにタグ・ハンドラによって使用されるテンプレートであると考えることができます。したがって、コンテナによって評価される単純な属性とは異なり、フラグメント属性はタグ呼出し中にタグ・ハンドラによって評価されます。

JSPフラグメントは、フラグメントを構成するJSPコード内のJSP式言語(JSP EL)変数を使用して、パラメータ化できます。JSP EL変数はタグ・ハンドラによって設定されるため、ハンドラはフラグメントが呼び出される度に、そのフラグメントをカスタマイズできます。JSP式言語の詳細は、『Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発』のWebLogic JSPリファレンスに関する項を参照してください。

シンプル・タグ・ハンドラのライフサイクルの期間中、SimpleTagの本体は、もしあれば、JSPフラグメントに変換され、setJspBodyメソッドに渡されます。変換フェーズの期間中、ページの様々な部分が、タグ・ハンドラに渡される前にjavax.servlet.jsp.tagext.JspFragment抽象クラスの実装に変換されます。これは、タグ・ライブラリ記述子(TLD)内で、フラグメントとして宣言された、またはJspFragmentタイプである、名前付き属性の本体における任意のJSPコード(<jsp:attribute>で定義される)に対して自動的に行われます。また、シンプル・タグ・ハンドラによって処理されるどのタグの本体に対しても、自動的に行われます。一度渡されると、タグ・ハンドラはフラグメントを必要に応じて何度でも評価および再評価でき、タグ・ファイルの場合にはさらに他のタグ・ハンドラに渡すことさえできます。

JSPフラグメントは、フラグメントと関連付けられたJspContext内のページ・スコープ属性を設定することで、タグ・ハンドラによってパラメータ化できます。これらの属性にはその後、式言語を利用してアクセスできるようになります。

JSPフラグメントに変換されるはずのJSPコードの一部に、スクリプトレットまたはスクリプトレット式が含まれていた場合、変換エラーが発生します。

タグ・ハンドラのライフサイクル(TagおよびBodyTagインタフェース)

TagインタフェースまたはBodyTagインタフェースから継承され、そのタグ・ハンドラ・クラスによって実装されたメソッドは、JSPページの処理中の特定の時点でJSPエンジンによって呼び出されます。これらのメソッドは、タグのライフサイクルにおける様々なポイントを表し、以下の順序で実行されます。

1. JSPエンジンがJSPページの中でタグを見つけると、新しいタグ・ハンドラが初期化されます。javax.servlet.jsp.tagext.TagインタフェースのsetPageContext()メソッドとsetParent()メソッドが呼び出されて、そのタグ・ハンドラの環境コンテキストが設定されます。タグ開発者は、ベース・クラスTagSupportまたはBodyTagSupportを拡張する場合、これらのメソッドを実装する必要はありません。

2. タグ属性ごとにsetXXXX()というJavaBeanのようなメソッドが呼び出されます。詳細は、「タグ本体内の例外処理」を参照してください。

3. doStartTag()メソッドが呼び出されます。タグ・ハンドラでこのメソッドを定義すると、タグ・ハンドラを初期化したり、データベースなどの必要なあらゆるリソースへの接続を開くことができます。
doStartTag()メソッドの終わりには、タグ本体を評価すべきかどうかを、以下の値定数のうちの1つをタグ・ハンドラ・クラスから返すことで指定できます。

SKIP_BODY - タグの本体をスキップするようJSPエンジンに指示します。タグが本体のないタグ(空タグ)である場合、この値を返します。タグのライフサイクルのうち本体に関係のある部分はスキップされ、次に呼び出されるメソッドはdoEndTag()となります。

EVAL_BODY_INCLUDE - タグ本体のコンテンツを評価して組み込むようJSPエンジンに指示します。タグのライフサイクルのうち本体に関係のある部分はスキップされ、次に呼び出されるメソッドはdoEndTag()となります。

この値を返すことができるのは、Tagインタフェースを実装するタグの場合だけです。この値を使用すると、本体を組み込むかどうかは決定できるが、そのコンテンツには関知しないタグを記述できます。タグがBodyTagインタフェースを実装する(またはBodyTagSuportクラスを拡張する)場合、この値を返すことはできません。

EVAL_BODY_TAG - タグ本体を評価してからdoInitBody()メソッドを呼び出すようJSPエンジンに指示します。この値は、タグがBodyTagインタフェースを実装する(またはBodyTagSupportクラスを拡張する)場合にだけ返すことができます。

4. setBodyContent()メソッドが呼び出されます。この時点では、タグからの出力はBodyContentという特殊なJspWriterにリダイレクトされ、クライアントには送られません。本体を評価して得られるすべてのコンテンツはBodyContentバッファに追加されます。このメソッドにより、タグ・ハンドラはBodyContentバッファへの参照を格納してdoAfterBody()メソッドで評価後処理のために使えるようにすることができます。
タグが出力をJSPページ(ネスト・タグの場合はその親スコープ)に渡す場合、タグはタグ・ライフサイクルのこの時点からdoEndTag()メソッドが終わるまでに、そのタグの出力を親スコープのJspWriterに明示的に書き出さなければなりません。タグ・ハンドラは、getEnclosingWriter()メソッドを使用して、親スコープの出力にアクセスできます。

コンビニエンス・クラスのBodyTagSupportを使用している場合、このメソッドを実装する必要はありません。これは、タグがBodyContentへの参照を保持し、BodyContentメソッドを介してその参照を使用できるようにするからです。

5. doInitBody()メソッドが呼び出されます。このメソッドを使用すると、タグ本体が初めて評価される直前に何らかの処理を実行できます。ここでは、スクリプト変数を設定したり、タグ本体の前のBodyContentに何らかのコンテンツを挿入したりできます。ここで付加したコンテンツは、JSPページのタグ本体のコンテンツとは異なり、JSPとして評価されることはありません。

このメソッドで実行する処理とdoStartTag()メソッドの終わりに実行する処理との大きな違いは(EVAL_BODY_TAGを返そうとしていることがわかった場合)、このメソッドでは、タグの出力のスコープはネストされていて、JSPページ(または親タグ)には直接向けられないということです。すべての出力は、BodyContentという特殊なJspWriterに書き込まれます。

6. doAfterBody()メソッドが呼び出されます。このメソッドは、タグの本体が評価されBodyContentバッファに追加された後に呼び出されます。タグ・ハンドラは、評価済みタグ本体に基づいて何らかの処理を行うためにこのメソッドを実装する必要があります。ハンドラがコンビニエンス・クラスのBodyTagSupportを拡張する場合、getBodyContent()メソッドを使用して評価済みタグ本体にアクセスできます。単にBodyTagインタフェースを実装するだけであれば、setBodyContent()メソッドを定義して、そこにBodyContentインスタンスへの参照を格納しておく必要があります。
doAfterBody()メソッドの終わりには、タグのライフサイクルを、前と同じように以下の値定数のうちの1つを返すことで決定できます。

SKIP_BODY - 処理を続行し、本体を再び評価しないようJSPエンジンに指示します。タグのライフサイクルはdoEndTag()メソッドに進みます。

EVAL_BODY_TAG - 本体を再び評価するようJSPエンジンに指示します。評価済み本体がBodyContentに追加され、doAfterBody()メソッドが再び呼び出されます。

この時点で、タグ・ハンドラが親スコープに出力を書き出すよう指定できます。親スコープへのライターを取得するには、BodyTagSupport.getPreviousOut()メソッドまたはBodyContent.getEnclosingWriter()メソッドを使用します。どちらのメソッドでも、同じ親ライターが取得されます。

タグ・ハンドラは評価済み本体のコンテンツを親スコープに書き出すこともあれば、その評価済み本体をさらに処理して他の何らかの出力を書き出すこともあります。本体の反復処理ごとにBodyContentが既存のBodyContentに追加されるので、SKIP_BODYを返すよう決定した場合、反復処理された本体のコンテンツ全体だけを書き出します。そのようにしないと、後続の各反復処理のコンテンツが何度も出力に現れることになります。

7. pageContext内のoutライターが親のJspWriterに復元されます。このオブジェクトは実際にはスタックであり、pushBody()メソッドとpopBody()メソッドを使用してpageContext上のJSPエンジンによって処理されます。ただし、タグ・ハンドラの中でこれらのメソッドを使用してこのスタックを処理しようとしてはいけません。

8. doEndTag()メソッドが呼び出されます。タグ・ハンドラはこのメソッドを実装して、タグ処理後のサーバー側作業を実行し、出力を親スコープJspWriterに書き出し、データベース接続などのリソースをクローズできます。
タグ・ハンドラは、doEndTag()メソッド内でpageContext.getOut()を実行して得られるJspWriterを使用して、親スコープに出力を直接書き出します。なお、pageContext.outは、前の手順でpopBody()がpageContext上で呼び出されたときに親ライターに復元されています。

doEngTag()メソッドから以下の値のうちの1つを返すことで、JSPページの残りの部分の評価フローを制御できます。

EVAL_PAGE - JSPページの残りの部分の処理を続行するようJSPエンジンに指示します。

SKIP_PAGE - JSPページの残りの部分をスキップするようJSPエンジンに指示します。

9. release()メソッドが呼び出されます。この呼出しは、タグ・ハンドラ・インスタンスが逆参照され、ガベージ・コレクション用に使用できるようになる直前に行われます。

タグ本体の反復処理(IterationTagインタフェース)

javax.servlet.jsp.tagext.IterationTagインタフェースを実装するタグでは、タグの本体を条件付きで再評価できるdoAfterBody()というメソッドを使用できます。doAFterBody()がIterationTag.EVAL_BODY_AGAINを返す場合は、本体が再評価されます。doAFterBody()が Tag.SKIP_BODYを返す場合は、本体はスキップされてdoEndTag()メソッドが呼び出されます。詳細は、このインタフェースのJava EE Javadocを参照してください(Javadocs (http://www.oracle.com/technetwork/java/javaee/jsp/index.html)をダウンロードできます。)

タグ本体内の例外処理

javax.servlet.jsp.tagext.TryCatchFinallyインタフェースのdoCatch()およびdoFinally()メソッドを実装すると、タグ内から送出される例外を捕捉できます。詳細は、このインタフェースのJava EE Javadocを参照してください(Javadocs (http://www.oracle.com/technetwork/java/javaee/jsp/index.html)をダウンロードできます。)

タグ属性の使い方

カスタム・タグでは、JSPページから指定できる属性を何個でも定義できます。これらの属性は、タグ・ハンドラに情報を渡してその動作をカスタマイズするために使用できます。

各属性名は、TLDの中で<attribute>要素を使用して宣言します。この要素は、属性の名前とその他の属性プロパティを宣言します。

JavaBean規約と同じように、タグ・ハンドラは属性名に基づいてセッター・メソッドとゲッター・メソッドを実装する必要があります。たとえば、fooという属性名を宣言する場合、タグ・ハンドラは以下のパブリック・メソッドを定義しなければなりません。

public void setFoo(String f);
public String getFoo();

属性名の先頭の文字は、接頭辞のsetまたはgetの後では大文字になることに注意してください。

JSPエンジンは、タグ・ハンドラが初期化されてからdoStartTag()メソッドが呼び出されるまでの間に、各属性のセッター・メソッドを呼び出します。一般に、タグ・ハンドラの他のメソッドからアクセスできるメンバー変数に属性値を格納するには、セッター・メソッドを実装しなければなりません。

新しいスクリプト変数の定義

タグ・ハンドラは、様々なスコープでJSPページから参照できる新しいスクリプト変数を使用できます。スクリプト変数は、それらの定義済みスコープの内部で暗黙的なオブジェクトのように使用できます。

javax.servlet.jsp.tagext.TagExtraInfoを拡張するJavaクラスを識別するための新しいスクリプト変数は、<tei-class>要素を使用して定義します。例:

<tei-class>weblogic.taglib.session.ListTagExtraInfo</tei-class>

次に、TagExtraInfoクラスを作成します。例:

package weblogic.taglib.session;
import javax.servlet.jsp.tagext.*;
public class ListTagExtraInfo extends TagExtraInfo {

public VariableInfo[] getVariableInfo(TagData data) {
return new VariableInfo[] {
new VariableInfo("username","String",true,VariableInfo.NESTED)
new VariableInfo("dob","java.util.Date",true,VariableInfo.NESTED)
};
}
}

上の例では、VariableInfo要素の配列を返すgetVariableInfo()という1つのメソッドが定義されています。各要素は、新しいスクリプト変数を定義します。上記のサンプルでは、java.lang.String型のusernameとjava.util.Date型のdobという2つのスクリプト変数が定義されています。

VariableInfo()のコンストラクタは、以下の4つの引数を取ります。

- 新しい変数の名前を定義するString。

- その変数のJavaデータ型を定義するString。java.langパッケージ以外のパッケージに含まれる型の完全パッケージ名を指定します。

- その変数を使う前にインスタンス化しなければならないかどうかを宣言するboolean。タグ・ハンドラがJava以外の言語で書かれている場合を除き、この変数は「true」に設定します。

- その変数のスコープを宣言するint。以下に示すVariableInfoに定義されている静的フィールドを使用します。
VariableInfo.NESTED - タグの開始タグと終了タグの間でだけ使用できます。

VariableInfo.AT_BEGIN - 開始タグからページの最後までの間で使用できます。

VariableInfo.AT_END - 終了タグとページの最後の間で使用できます。

タグ・ハンドラは、ページのコンテキストを介してスクリプト変数の値を初期化しなければなりません。たとえば、上で定義したスクリプト変数の値を初期化するには、doStartTag()メソッドの中で以下のJavaソースを使用します。

pageContext.setAttribute("name", nameStr);
pageContext.setAttribute("dob", bday);

ここで、最初のパラメータはスクリプト変数の名前を指定し、2番目のパラメータは代入される値を示します。なお、ここではJava変数のnameStrはString型で、bdayはjava.util.Date型です。

また、TagExtraInfoクラスを使用して作成された変数にアクセスするには、useBeanを使用して作成されたJavaBeanにアクセスするときと同じようにそれを参照します。

動的名前付きスクリプト変数

タグの属性から、新しいスクリプト変数の名前を定義できます。このように定義することで、1つのスクリプト変数を定義するタグの複数のインスタンスを同じスコープで使用しつつ、タグのスクリプト変数名の衝突を避けることができます。TagExtraInfoを拡張するクラスからこれを実行するには、getVariableInfo()メソッドに渡されるTagDataからスクリプト変数の名前を取得しなければなりません。

TagDataからは、getAttributeString()メソッドを使用して、スクリプト変数の名前を指定する属性の値を検索できます。さらに、id属性の値を返すgetId()メソッドも存在します。これは、JSPタグからもたらされる新しい暗黙的オブジェクトに名前を付けるのによく使用されます。

タグ・ライブラリ記述子の変数の定義

タグ・ライブラリ記述子の変数を定義できます。詳細は、「スクリプト変数を定義します(オプション)」を参照してください。

協調的ネスト・タグの記述

ネストされているタグが、その親タグに定義されているプロパティを暗黙的に使用するよう設計できます。たとえば、サンプル・コードの「SQL Query」(WebLogic Serverのsamples/examples/jsp/tagext/sqlディレクトリを参照)では、<sql:query>タグが<sql:connection>タグの内部にネストされています。queryタグは親スコープのconnectionタグを検索して、そのタグによって確立されたJDBC接続を使用します。

親スコープのタグを見つけるために、ネスト・タグはTagSupportクラスの静的メソッドであるfindAncestorWithClass()を使用します。次に、QueryTagのサンプルから抜粋したコードを示します。

try {
ConnectionTag connTag = (ConnectionTag)
findAncestorWithClass(this,
Class.forName("weblogic.taglib.sql.ConnectionTag"));
} catch(ClassNotFoundException cnfe) {
throw new JspException("Query tag connection "+
"attribute not nested "+
"within connection tag");
}

この例では、与えられたクラスに一致するタグ・ハンドラ・クラスを持つ最も近い親タグ・クラスが返されます。直系の親タグがこのタイプでなければ、さらにその親が調べられます。一致するタグが見つかるまでこの処理が繰り返され、それでも見つからない場合はClassNotFoundExceptionが送出されます。

カスタム・タグでこの機能を使用すれば、JSPページでのタグの構文と使い方を簡素化できます。

タグ・ライブラリ・バリデータの使用

タグ・ライブラリ・バリデータはユーザーが記述するJavaクラスです。これを使用するとJSPページのXML表示の検証を実行できます。バリデータ・クラス上のvalidate(String, String, PageData)は、変換時(JSPがサーブレットに変換される時)にJSPコンパイラによって呼び出され、ページが検証された場合にはnull文字列を、検証が失敗した場合にはエラー情報を含む文字列を返します。

タグ・ライブラリ・バリデータを実装するには、次の手順に従います。

1. バリデータ・クラスを記述します。バリデータ・クラスはjavax.servlet.jsp.tagext.TagLibraryValidatorクラスを拡張します。

2. タグ・ライブラリ記述子内のバリデータを参照します。例:

<validator>
<validator-class>
myapp.tools.MyValidator
</validator-class>
</validator>

3. (オプション)初期化パラメータを定義します。バリデータ・クラスで初期化パラメータを取得および使用できます。例:

<validator>
<validator-class>
myapp.tools.MyValidator
</validator-class>
<init-param>
<param-name>myInitParam</param-name>
<param-value>foo</param-value>
</init-param>
</validator>

4. WebアプリケーションのWEB-INF/Classesディレクトリに、バリデータ・クラスをパッケージ化します。タグ・ライブラリjarファイルにクラスをパッケージ化することもできます。詳細は、「JSPタグ・ライブラリのJARファイルとしてのパッケージ化」を参照してください。

5 管理と構成

この章では、JSPタグ拡張を使用するための管理タスクと構成タスクの概要を示します。

- JSPタグ・ライブラリの構成

- JSPタグ・ライブラリのJARファイルとしてのパッケージ化

JSPタグ・ライブラリの構成

ここでは、JSPタグ・ライブラリを構成する手順について説明します。タグ・ライブラリはJARファイルにしてパッケージ化することもできます(「JSPタグ・ライブラリのJARファイルとしてのパッケージ化」を参照)。

1. タグ・ライブラリ記述子(TLD)を作成します。
詳細は、第3章「タグ・ライブラリ記述子の作成」を参照してください。

2. このTLDを、Webアプリケーション・デプロイメント記述子(web.xml)で参照します。例:

<taglib>
<taglib-uri>myTLD</taglib-uri>
<taglib-location>WEB-INF/library.tld</taglib-location>
</taglib>

この例では、タグ・ライブラリ記述子はlibrary.tldという名前のファイルです。tldの場所は、常にWebアプリケーションのルートを基準として相対的に指定します。

3. タグ・ライブラリ記述子ファイルを、WebアプリケーションのWEB-INFディレクトリに配置します。

4. JSPページでタグ・ライブラリを参照します。
JSPで、JSPディレクティブを使用してタグ・ライブラリを参照します。例:

<%@ taglib uri="myTLD" prefix="mytaglib" %>

5. タグ・ハンドラのJavaクラス・ファイルを、WebアプリケーションのWEB-INF/classesディレクトリに配置します。

6. WebアプリケーションをWebLogic Serverにデプロイします。詳細は、『Oracle WebLogic Serverアプリケーションの開発』の「分割開発ディレクトリからのデプロイとパッケージ化」を参照してください。

JSPタグ・ライブラリのJARファイルとしてのパッケージ化

前の節「JSPタグ・ライブラリの構成」で説明した手順に加えて、JSPタグ・ライブラリはJARファイルとしてパッケージ化することもできます。

1. TLD (タグ・ライブラリ記述子)ファイルをtaglib.tldという名前で作成します。

詳細は、第3章「タグ・ライブラリ記述子の作成」を参照してください。

2. タグ・ライブラリで使用されるコンパイル済みJavaタグ・ハンドラ・クラスのファイルを格納するディレクトリを作成します。

3. 手順2で作成したディレクトリのサブディレクトリを作成し、META-INFという名前を付けます。

4. 手順1で作成したtaglib.tldファイルを、手順3で作成したMETA-INFディレクトリにコピーします。

5. 手順2で作成したディレクトリから次のコマンドを実行して、コンパイルされたJavaクラス・ファイルをjarファイルとしてアーカイブします。

jar cv0f myTagLibrary.jar

(myTagLibrary.jarはユーザーが指定する名前です)

6. Jarファイルを、タグ・ライブラリを使用するWebアプリケーションのWEB-INF/libディレクトリにコピーします。

7. JSPでタグ・ライブラリを参照します。例:

<%@ taglib uri="taglib.tld" prefix="wl" %>

より柔軟性の高い方法は、手順1から6までを実行し、Webアプリケーション・デプロイメント記述子web.xmlでタグ・ライブラリ記述子を参照することです。例:

. . .
<taglib>
<taglib-uri>myjar.tld</taglib-uri>
<taglib-location>
/WEB-INF/lib/myTagLibrary.jar
</taglib-location>
</taglib>
. . .

その後、次のようにJSPタグ・ライブラリを参照できます。

<%@ taglib uri="myjar.tld" prefix="wl" %>

オラクル社の法律上の注意点について

コピーライトについて

Copyright © 1994-2015, Oracle and/or its affiliates.All rights reserved.

商標と登録商標について

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

ライセンス制約の保証と結果的に生じる損害の免責

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

保証免責

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

制限付権利

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

危険な用途への使用について

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション（人的傷害を発生させる可能性があるアプリケーションを含む）への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性（redundancy）、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

第三者のコンテンツ、製品、サービスに対する免責事項

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

ドラフトのアルファ版およびベータ版ドキュメントについて

このドキュメントが試作版の場合:

このドキュメントは試作版であり、デモおよび暫定使用のみを目的としたものです。このソフトウェアを使用するハードウェアに限定するものではありません。オラクル社およびその関連会社は、このドキュメントに関して一切の責任を負わず、いかなる保証もいたしません。また、このドキュメントを使用したことによって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。