Oracle® Fusion Middleware Oracle WebLogic Server JSP Tag Extensions プログラマーズ ガイド 11g リリース 1 (10.3.1) B55531-01 |
|
戻る |
次へ |
以下の節では、タグ ライブラリ記述子 (TLD) を作成する方法について説明します。
タグ ライブラリを使用すると、開発者は関連する機能を持つタグを 1 つにまとめることができます。タグ ライブラリには、タグ拡張を記述し、それらを Java クラスに関連付けるタグ ライブラリ記述子 (TLD) ファイルが必要となります。TLD は、WebLogic Server とオーサリング ツールが拡張機能に関する情報を取得するために使用されます。TLD ファイルのファイル拡張子は .tld で、このファイルは XML 表記法で記述されます。
タグ ライブラリ記述子ファイル内の要素は、XSD に定義されている順序で並べます。この順序付けは、以下に示す手順で使用されます。TLD 要素がこの順序どおりに並べられていない場合、XML パーサは例外を送出します。
TLD の本体は、<taglib> ... </taglib>
要素の中にネストされた要素を含んでいます。これらのネストされた要素についても次の手順で説明します。このドキュメントでは、見やすくするためにネストされた要素はその親要素からインデントされていますが、TLD ではインデント処理は必要ありません。
「タグ ライブラリ記述子のサンプル」の例では、code という新しいタグを宣言します。このタグの機能は、Java クラスの weblogic.taglib.quote.CodeTag
によって実装されます。
TLD を作成するには、次の手順に従います。
テキスト ファイルを作成して、適切な名前と拡張子 .tld を付け、JSP を持つ Web アプリケーションの WEB-INF ディレクトリに保存します。WEB-INF ディレクトリの内容は非公開で、WebLogic Server によって HTTP を介して提供されません。
次のヘッダを追加します。
<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">
手順 4 ~ 7 の指示に従い、TLD のコンテンツを、<taglib>
要素の中に埋めこみます。コンテンツには、タグ ライブラリに関する情報を含む要素と、各タグを定義する要素が含まれます。次に例を示します。
<taglib> ... body of taglib descriptor ... </taglib>
タグ ライブラリを指定します。
<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>
(省略可能) 自動的にインスタンス化および登録される任意のイベント リスナ オブジェクトを定義します。
タグ ライブラリ バリデータを定義します (省略可能)。
<validator>
バリデータの最上位要素。
<validator-class>my.validator</validator-class>
(必須) 検証を実行する Java クラス。
<init-param>
(省略可能) バリデータ クラスの初期化パラメータを定義します。
<param-name>param</param-name>
このパラメータの名前を定義します。
<param-value>value</param-value>
このパラメータの名前を定義します。
タグを定義します。
タグ ライブラリに新しいタグを定義するには、それぞれ別個の <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>
スクリプト変数を定義します (省略可能)。
<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>
JSP 2.0 コンテナでサポートされる DynamicAttributes インタフェースにより、開発の時点で名前が既知でなくても値が一貫性のある方法で処理されるタグを使用できます。たとえば、<table>
HTML タグの width
部分を、実行時に値を決定してカスタマイズする場合は、DynamicAttributes インタフェースを利用して、<table>
タグの他の部分 (border
、cellspacing
など) に指定を行うことなく、タグの変更する部分だけをカスタマイズできます。DynamicAttributes インタフェースを使用せずに width
の値を実行時に動的に決定するには、タグ ハンドラなどの複雑なコードを記述しなければなりません。
タグ ハンドラで動的な属性を受け付けるかどうかを最終的に決定するのは TLD です。タグ ハンドラで、TLD において動的な属性をサポートすると宣言しているにも関わらず、DynamicAttributes
インタフェースがサポートされていない場合、タグ ハンドラはコンテナによって無効と見なされます。
呼び出されるタグの dynamic-attributes
要素 (作成されているタグ
ライブラリのタグ要素の子要素) に、値 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()
を呼び出すことはできません。
これらのインタフェースの詳細については、(http://java.sun.com/javaee/5/docs/api/javax/servlet/jsp/tagext/DynamicAttributes.html
) で DynamicAttributes API を参照してください。