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を作成するには、次の手順に従います。

テキスト・ファイルを作成して、適切な名前と拡張子.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>

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)を参照してください。