このチュートリアルではJakarta-Taglibs ライブラリの基本的なタグがどのように作られたかを簡単に説明します。タグライブラリではカスタムアクションを作って機能をカプセル化することが出来ます。カスタムタグによって、プレゼンテーション層をビジネスロジックから明確に分けることが出来ます。 カスタムタグはJSP ページで使用できるすべてのオブジェクトにアクセスすることができる再利用可能なコンポーネントです。詳しくはJavaServer Page の仕様書(バージョン1.2) を見て下さい。

JSP のバージョン1.1以上をサポートしているサーバではタグライブラリが使用できます。 JavaServer ページ 業界動向 のページを見れば、現在どのサーバがどのレベルまでサポートしているかを知ることが出来ます。 Sun Microsystems 社のページには Java Web Service チュートリアル があり、その中には カスタムタグ について記述された章や、 JSP 標準タグライブラリ (JSTL) について書かれた章もあります。

タグハンドラ

JSP ページの実行時にアクションの実行を手助けするサーバサイドのオブジェクト

タグライブラリ記述子

タグの名称とその属性を定義する xml ファイル

JSP

JSP ページではtaglibディレクティブを用いることによって タグライブラリを使用できるようになります。

インストールと配置

既に存在するタグライブラリのインストール方法

例

タグライブラリを使用したコードの例です。

タグハンドラは JSP ページとその他のサーバサイドオブジェクトとの橋渡しをするのが役目です。タグハンドラはJSPページの実行中にカスタムタグが読み込まれると呼び出されます。 カスタムタグの開始タグと終了タグが読み込まれた時にはそれぞれ doStartTag() と doEndTag() が呼び出されます。タグハンドラが確保したリソースは release()メソッドで解放します。

タグハンドラには２つのインターフェースが備わっています。

タグハンドラは２つの大きなアクションメソッドを持っています。

doStartTag() は次の値を戻り値とします。

• EVAL_BODY_INCLUDE
  • タグのボディ部を処理しますが、新しい BodyContent を作ることはしません。 ボディ部を処理することなしにそのまま渡します。BodyTagインターフェースを実装していない時にのみ有効です。
• EVAL_BODY_TAG
  • タグのボディ部を処理し、新しい BodyContent を作ります。BodyTagインターフェースを実装している時にのみ有効です。
• SKIP_BODY
  • タグのボディ部を評価しません

doEndTag() は次の値を返します。

• EVAL_PAGE
  • JSP ページの残りの評価を続けます
• SKIP_PAGE
  • JSP ページの残りの評価を止めます

この戻り値はJSPページの残りをどのように評価するかを直接 JSP コンテナへ渡します。release()メソッドはタグハンドラが確保したリソースの開放をします。

TagSupport と BodyTagSupport はともに Tag のサブクラスで、新しいタグハンドラを作成する時のベースクラスとして使用することが出来ます。

Tag を実装している TagSupport はユーティリティクラスで、次のような便利なメソッドを持っています。

• Tag プロパティの取得メソッド

アクションの本体(タグのボディ部)を操作するようなタグハンドラならば、BodyTagインターフェースを 実装する必要があります。タグのボディ部が評価されるようにdoStartTag() は必ず EVAL_BODY_TAG を返さなければなりません。もしSKIP_BODYが返されたら開始タグから終了タグまでのボディ部は無視されて しまいます。タグのボディ部を取り扱うメソッドには次のようなものがあります。

BodyTagSupport クラスは BodyTag インターフェースを実装し、かつ便利なメソッドが追加されています。例えば次のようなメソッドです。：

• bodyContentプロパティの取得メソッド
• 以前使用された JSPWriter out の取得メソッド

Webアプリケーションではタグハンドラは次に示すように、Javaクラスの標準的な格納場所のどこかになければなりません。

• /WEB-INF/lib ディレクトリにある JAR ファイルの中
• /WEB-INF/classes ディレクトリの中

タグハンドラは JSP コンテナが設定メソッドで設定したプロパティにアクセス することができます。pageContext や parent などがそれです。 また、さらにタグハンドラは中に入っているサーバ側のオブジェクトとアクションにもアクセスできます。 タグがネストされているならば、タグを囲んでいる親タグのハンドラは以下のいずれかのメソッドでアクセスできます。

• TagSupport.getParent()
• TagSupport.findAncestorWithClass(from, class)

一度親オブジェクトの取得が出来たら、その親オブジェクトからは動的または静的に生成したオブジェクトに アクセスが出来るようになります。

タグライブラリ記述子(TLD)はJSPコンテナがタグライブラリを参照する taglibディレクティブ を含むページを解釈する時使用されます。 それ(TLD) はアクションタグとタグハンドラクラスを結びつける XML ドキュメントです． TLD の場所を記述するには，以下の 2つの方法があります．

• web.xml の taglib エレメントで
  • taglib-uri
    • タグライブラリを表すURI
  • taglib-location
    • リソースパス(訳注：Webアプリケーションルートからの相対パス)として表したTLD ファイルがある位置
• デフォルトの対応を利用する

web.xml の taglib エレメントの詳細につい てはServelet 2.2 と JSP 1.1 の仕様書に書いてあります。

最近の変更に対し妥当性検証パーサを呼ぶので、外部の DOCTYPE を明示的に参照する必要があります。：

                                        
  <!DOCTYPE taglib
    PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN"
    "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd">

TLD の中で taglibエレメントがルートとなります。その中には以下のようなサブエレメントがあります。

タグライブラリ中でアクションを定めるタグエレメント。次のようなサブエレメントを含みます。

もしそのタグがボディ部を持っているならば bodycontent を含みます。 ページ構成ツールがボディ部の構成に影響を与えないように使用します。 その値は次の３つのタイプのいずれかの１つを指定して下さい。：

• JSP (default)
  • JSP コンテナがタグのボディ部を評価する。ただしそのボディ部は空でもいい。
• tagdependent
  • タグのボディ部はタグ自身によって扱われます。（空でもいい）
• empty
  • タグのボディ部は空でないといけません。

teiclass はスクリプト変数を定義し、次の内容を含みます。

• 名前
• タイプ
• その変数は生成する必要があるのか否か
• スコープ

attributes は次のフィールドを含みます

• name (必須)
  • 属性名
• required
  • その属性が必須か否か
• rtexprvalue
  • 実行時に属性値をスクリプトレットとして動的に計算できるようにするかどうかを定義します。 注意: 初期値は "false" で、指定された属性値を静的な値として扱うことを意味します。 要求時に属性値を計算処理する場合は、"true" がセットされていることを確認してください。

すべての属性について、タグハンドラは JavaBeans と同じような取得メソッドと設定メソッドが必要です。もし属性が idという名前ならば、TagSupport クラスはsetId() と getId() を定義してくれます。

JavaServer Page は タグライブラリのアクションに囲まれている XML で書かれた内容を扱うことが出来ます。

  <%@ taglib uri="identifier" prefix="prefix" %>

タグライブラリを使うためには taglibディレクティブを使用して、どこにそのタグライブラリが存在するかを JSP コンテナに伝えなければなりません。このディレクトリはどのアクションより前に記述されていなければなりません。

• ここで指定される"identifier"はweb.xml ファイルの<taglib-uri> エレメントにあるもののどれかと一致しなければなりません。
• The "prefix" distinguishes which tag library will be used.
  "prefix"はどのタグライブラリが使用されるかを識別するためのものです。

a) 汎用タグライブラリの作成

タグライブラリをインストールするためには以下の手順を踏んでください。

1. タグライブラリに必要なクラスをjarファイルにまとめます。タグライブラリの {library}.tldファイルが/WEB-INFディレクトリにあることを確認してください。
2. タグライブラリのjarファイル{library}.jarをCLASSPATHに追加します。
3. {library}.jar ファイルを /WEB-INF/lib にコピーします。
4. 次のように /WEB-INF/web.xml ファイルの taglib エレメントを定義します。

     <taglib>
       <taglib-uri>http://jakarta.apache.org/taglibs/{library}</taglib-uri>
       <taglib-location>/WEB-INF/{library}.tld</taglib-location>
     </taglib>
       

5. タグ拡張をjsp ページに定義します。 <taglib-uri> エレメントと taglib ディレクティブの uri属性とは一致しなければなりません。 prefix はタグを jsp ページの中で識別するために使用されます。 taglib ディレクティブは次のようになります。

  <%@ taglib uri="http://jakarta.apache.org/taglibs/{library}" prefix="x" %>
    

b) Jakarta-Taglibs ライブラリの追加

Jakarta-Taglibs プロジェクトへの新しいタグライブラリの追加をするためには次のようなことを する必要があります。

1. プロジェクト用にトップレベルのディレクトリを作成します。
2. すでに存在するサブプロジェクトから以下のファイルを作成したディレクトリの トップにコピーします。
   • build.sh
   • build.bat
   • build.xml
3. taglib.nameプロパティを新規に作成するタグライブラリのサブプロジェクト名 に変更します。
4. すでに存在するサブプロジェクトのディレクトリ構造をそのまま新しいサブプロジェクトの ディレクトリにコピーします。
5. 最上位の階層にある Jakarta-Taglibs の build.xml ファイルを変更し、新しいライブラリを追加します。

c) タグライブラリの配置

jakarta-taglibsプロジェクトのビルド用スクリプトで war ファイルを作成します。 そのwarファイルが出来たらそのファイルを $TOMCAT_HOME/webappsディレクトリに 配置します。 Tomcat サーバは新しいクラスをロードし、新しいコンテキストを作ります。

war ファイルは以下の構造をしています。

  META-INF/
  META-INF/MANIFEST.MF
  WEB-INF/
  WEB-INF/classes/
  WEB-INF/lib/
  WEB-INF/lib/{tagLibrary}.jar
  WEB-INF/web.xml
  WEB-INF/{tagLibrary}.tld

もし jarファイルを使いたくなければ、個別のクラスファイルすべてを /WEB-INF/classes ディレクトリに配置することも出来ます。

war ファイルについては Java Servlet v2.2 の仕様を参照して下さい。

いくつかの例が含まれています。

• 簡単なタグ
• 単純な入れ子のタグ
• UtilityTags ライブラリのドキュメント

簡単なタグの例は"Hello world"です。タグが出現したら "Hello world" という文字が出力されます。

• タグハンドラ
• タグライブラリ記述子
• web.xml ファイル
• JSP

Hello World タグハンドラ

Hello World タグは基本パッケージの一部なので、 /WEB-INF/classes/basic ディレクトリに入っています。

  package basic;

jspとタグクラスをインポートします：

  import javax.servlet.jsp.*;
  import javax.servlet.jsp.tagext.*;

Hello World タグハンドラは 開始タグが現れたときに呼び出される doStartTag() を実装しています。

    public int doStartTag() throws JspException {
        try {
            pageContext.getOut().print("Hello World");
        } catch (Exception ex) {
            throw new JspException("IO problems");
        }
        return SKIP_BODY;
    }

メンバ変数 pageContext は JSP コンテナによって設定され、タグハンドラが使用できます。 戻り値 SKIP_BODY はタグの内容の評価が行われないようにするという意味です。

Hello World タグライブラリ記述子

  <?xml version="1.0" encoding="ISO-8859-1" ?>

デプロイメント記述子のDOCTYPE を説明しているXMLヘッダです。デプロイメントデスクリプタはWebアプリケーションの設定情報を持つエレメントが含まれます。

  <!DOCTYPE taglib
            PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN" 
            "http://java.sun.com/j2ee/dtds/web-jsptaglib_1_1.dtd">

タグライブラリ初期化について

  <taglib>
    <!-- タグライブラリのバージョン番号 -->
    <tlibversion>1.0</tlibversion>

    <!-- 動作させるのに必要な最低限のJSP仕様のバージョン -->
    <jspversion>1.1</jspversion>

    <!-- タグライブラリの短縮名 -->
    <shortname>utility</shortname>

    <!-- このタグライブラリのバージョンをユニークに識別するための公式なURI -->
    <uri>http://jakarta.apache.org/taglibs/utilitytags</uri>

    <!-- このタグライブラリの概略 -->
    <info>
          例題のためのタグライブラリ
    </info>

Hello World タグの説明

• tagclass要素はHello World タグとタグハンドラとを関連づける
• bodycontent タグはこのタグがボディ部の文書を含まないことを表しています。

  <!-- Hello tag -->
    <tag>
      <name>Hello</name>
      <tagclass>basic.Hello</tagclass>
      <bodycontent>empty</bodycontent>
      <info>
        Print Hello World
      </info>
    </tag>

web.xml ファイル

  <web-app>
    <taglib>
       <taglib-uri>
         http://jakarta.apache.org/taglibs/utilitytags
       </taglib-uri>
       <taglib-location>
         /WEB-INF/tld/utilitytags.tld
       </taglib-location>
    </taglib>
  </web-app>

Hello World jsp

次のディレクティブは web.xmlファイルの中でuri エレメントがJSP コンテナに"http://jakarta.apache.org/taglibs/utilitytags" というタグライブラリを使用するように伝えています。jLibが、そのタグの接頭辞として定義されています。

  <%@ taglib uri="http://jakarta.apache.org/taglibs/utilitytags" prefix="jLib" %>

Hello World タグが呼び出されます。タグ"Hello"がタグライブラリ記述子の中で定義されています。

  <jLib:Hello/>

If 条件タグ は ネストされたタグのいい例です。その属性の値に従ってタグの内側に含まれたスクリプトレット(scriptlet)が評価されたり、無視されたりします。

• タグハンドラ
• タグライブラリ記述子
• web.xml ファイル
• JSP

If タグハンドラ

BodyTagSupport クラスは BodyTag インターフェースを 実装して、bodyContent プロパティの取得メソッドを持っています。

  public class IfTag extends BodyTagSupport {

開始タグを読み込んだら doStartTag() メソッドが呼び出され、 さらにローカルな getPredicate() メソッドが呼び出されます。 getPredicate() の戻り値が真ならば、タグの本体の残りの部分が評価され、偽ならば無視されます。

  public int doStartTag() {
    if (getPredicate()) return EVAL_BODY_TAG;
    else return SKIP_BODY;
  }

doAfterBody() はタグ本体が評価された後に呼び出されます。 タグ本体が空であったり、doStartTag() が SKIP_BODY を返したら呼び出されません。

  public int doAfterBody() throws JspException {
    try {
      bodyContent.writeOut(bodyContent.getEnclosingWriter());
      return SKIP_BODY;
    } catch (IOException ex) {
      throw new JspTagException(ex.toString());
    }
  }

If タグライブラリ記述子

  <!-- IF tag -->
    <tag>
      <name>If</name>
      <tagclass>lang.IfTag</tagclass>

If タグは一つの必須属性を持っています。rtexprvalue が真に設定されているのでその属性はスクリプトレット(scriptlet)を持つことが出来ます。そのスクリプトレット(scriptlet)の値は要求時に動的に計算されます。

      <attribute>
        <name>predicate</name>
        <required>true</required>
        <rtexprvalue>true</rtexprvalue>
      </attribute>
      <info>
        Conditional Tag.
      </info>
    </tag>  

web.xml ファイル

If JSP

If タグには１つの属性が必要です。属性の述部には実行時に評価されるスクリプトを含んでいます。 その述部の値に従ってjLib:Helloタグは評価されるか、無視されるかが決まります。

  <jlib:if predicate="<%= x==5 %>">
    <jLib:Hello/>   
  </jlib:if>

1. はじめに

utilitytagsカスタムタグライブラリにはいくつかの基本的なタグの例が含まれます。 そこでは単純なカスタムタグライブラリを作る上で必要なテクニックがわかります。

2. 前提ソフトウェア

このカスタムタグライブラリでは JavaServer Page バージョン 1.1 の仕様 をサポートしたサーブレットコンテナ以外のソフトウェアは必要ありません。

3. 設定情報

タグライブラリを含んだWebアプリケーションを設定するためには次の作業が必要です。

• タグライブラリ記述子(utilitytags/utilitytags.tld) をWebアプリケーションの/WEB-INF サブディレクトリにコピーします。
• タグライブラリ JAR ファイル (utilitytags/utilitytags.jar) をWebアプリケーションの /WEB-INF/lib サブディレクトリにコピーします。
• Webアプリケーションのデプロイメント記述子 に次のように <taglib> エレメントを追加します。

      <taglib>
          <taglib-uri>http://jakarta.apache.org/taglibs/utilitytags</taglib-uri>
          <taglib-location>/WEB-INF/utilitytags.tld</taglib-location>
      </taglib>
      

JSP ページで新しく追加されたタグを使用するためには次のようなディレクティブをページの先頭に追加します。

    <%@ taglib uri="http://jakarta.apache.org/taglibs/utilitytags" prefix="x" %>

ここで "x" はタグを使用する際に付ける接頭辞を表します。この接頭辞の文字は何でもかまいません。

4. タグのドキュメント

utilitytags タグライブラリは次のようなタグを含みます。

1. Hello Tag

   Hello タグは "Hello World" という文字を出力します。このタグには属性はありません。
   

   属性	説明	任意性
   -	-	-

2. Copy Tag

   MacroCopy タグは属性の文字列をWriterにコピーします。
   

   属性	説明	任意性
   name	出力するためのテキストを保持するための名前。任意の文字列	必須

3. Paste Tag

   MacroPaste タグは Writer にて指定されたテキストを貼り付けます
   

   属性	説明	任意性
   name	貼り付けられる文字列に付けられた名前	必須

4. ShowSource Tag

   jspFile を受け取り、その内容を Writer に複写します。
   

   属性	説明	任意性
   jspFile	jsp ファイルの相対的なパスで指定したファイル名。任意の文字列	必須

5. Include Tag

   Include タグはＵＲＬで指定した内容をそのまま出力するタグです。
   

   属性	説明	任意性
   url	有効なURL	必須

6. If Tag

   Ifタグは基本的な条件タグです。
   

   属性	説明	任意性
   predicate	任意の文字列	必須

7. For Tag

   Forタグは基本的なループ用タグです。
   

   属性	説明	任意性
   iterations	何回ループを回すか。任意の整数値	必須
   varName	For ループに関連付けられる変数名。任意の文字列	オプション
   begin	ループの開始値。任意の整数値	オプション

8. useBean Tag

   useBean タグはJava のオブジェクトのインスタンスと与えられた識別子を対応付けるタグです。
   

   属性	説明	任意性
   id	JSPコンテナとページ中のbean用の一意な識別子。任意の文字列が指定できます。	必須
   scope	page|request|session|application	オプション
   classname	そのオブジェクトの実装を定義するクラスの名前	オプション
   type	定義されるスクリプト変数のタイプ（型）	必須
   beanName	java.beans.Beans クラスの instantiate() メソッドに期待されているbeanの名前	必須
   processRequest	true|false JSP 0.92 の下位互換性を維持するために残してある。	オプション

9. Validate Tag

   Validate タグは HTML フォームの正当性を検査する Javascript を生成します。
   

   属性	説明	任意性
   name	フォームの名称。任意の文字列	必須
   method	生成されるJavascript関数の名前。任意の文字列	必須
   reqdFields	カンマで区切られた必須フィールドのリスト。任意の文字列	必須