Seasar DI Container with AOP

S2Click - Click Framework with Seasar2

S2Clickとは、Seasar2とClick Frameworkを組み合わせて利用するためのアダプタです。 以下のような機能を提供します。

  • ClickのページクラスをS2Containerで管理することができます
  • ClickのページクラスのHOT deployに対応します
  • Seasar2が推奨するpublicフィールドをClickで扱いやすくするための機能を提供します
  • Clickの設定をSeasar2のdiconファイルに集約します
  • Java 5のアノテーションを活用した機能を提供します
  • Ajax、ファイルダウンロードをサポートする機能を提供します
  • Click標準では提供されていない便利なコントロールやユーティリティを提供します
  • 携帯向けのWebアプリケーションを開発するために便利な機能を提供します
  • ClickIDEのS2Click向け拡張プラグインを提供します

なお、S2Clickの動作にはJava 5以降が必須です。

ダウンロード

各バージョンごとの更新履歴はこちらを参照してください。 また、S2Clickに同梱されているライブラリについてはこちらを参照してください。

S2ClickではClickプロジェクトにて開発されているClick Framework向けのEclipseプラグイン「ClickIDE」に 以下のプラグインを追加インストールすることで、S2ClickのプロジェクトでもClickIDEの機能を利用できるようになります。 ClickIDEをインストール後、以下のリンクからダウンロードしたJARファイルをEclipseのpluginsフォルダにコピーしてください。

サンプルを動かしてみる

リリースアーカイブを展開するとs2click-example.warというwarファイルがあります。 これはS2Clickのサンプルアプリケーションです。 Tomcatなどにデプロイし、Webブラウザからhttp://localhost:8080/s2click-exampleにアクセスすると動作を確認することができます。

スタートアップ

リリースアーカイブには以下のzipファイルが含まれています。これらはS2Clickによる開発をはじめるためのブランクプロジェクトです。 そのままEclipseにインポートしてご利用ください。

  • s2click-blank.zip (S2Clickのみ)
  • s2click-s2jdbc-blank.zip (S2Click + S2JDBC)

なお、ブランクプロジェクトは以下の環境が前提となっています。

  • Eclipse 3.3以上
  • WTP 2.0以上
  • Java 5.0以上
  • Apache Tomcat 6.0がServersビューに登録されていること

プロジェクトをインポートしたらWebContent/index.htmを右クリックし、 コンテキストメニューから[Run As] > [Run on Server]を選択してください。 Tomcatが起動し、足し算アプリが表示されるはずです。

なお、S2ClickのHOT deploy機能を利用する場合、Tomcat側でコンテキストのリロードが実行されないようにしておくと便利です。 WTPでは以下の手順でコンテキストのリロードを無効にすることができます。

  1. Serversビューで登録されているTomcatをダブルクリックする
  2. Tomcatの設定を行うためのエディタが表示されるので、[Modules]タブを選択する
  3. S2Clickのプロジェクトを選択して[Edit]ボタンをクリック
  4. [Auto reloading enabled]のチェックボックスのチェックを外す
Tomcatの設定変更

S2Clickの設定

s2click.diconでS2Clickの設定を行います。 org.seasar.s2click.S2ClickConfigのプロパティをセットすることで、 Clickの設定ファイルとほとんど同じ設定を行うことができます。 Clickの設定ファイルであるclick.xmlは作成する必要はありません(作成しても無視されます)。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR//DTD S2Container 2.4//EN"
  "http://www.seasar.org/dtd/components24.dtd">
<components>
  <component class="org.seasar.s2click.S2ClickConfig">
    <property name="formatClass">
      @org.seasar.s2click.example.util.S2ClickFormat@class
    </property>
  </component>
</components> 

S2ClickConfigには以下のプロパティを設定可能です。

プロパティ 説明 設定例
charset 文字コードを指定します。デフォルトはUTF-8です。
<property name="charset">
  "Windows-31J"
</property>
formatClass Velocityテンプレートで使用可能なFormatオブジェクトを指定します。 デフォルトはnet.sf.click.util.Formatです。
<property name="formatClass">
  @example.util.S2ClickFormat@class
</property>
mode Clickの動作モード。production、profile、development、debug、traceのいずれかを指定します。デフォルトはdevelopmentです。
モードによってClickの動作(HTMLテンプレートのリロードを行うかどうか等)やログに出力される内容が変化します。 詳細についてはClickのドキュメントを参照してください。
<property name="mode">
  "development"
</property>
headers 共通ヘッダ  
locale ロケール  
controlSets コントロールセットを定義した設定ファイル群のパスを指定します。  
controls デプロイ(ファイルの展開)が必要なコントロールクラス群を指定します。  
fileItemFactory ClickのFileFieldコントロールが使用するCommons FileUploadのFileItemFactoryのインスタンス  

S2Clickではページの自動マッピングは常に有効です。 また、ページクラスを配置するパッケージはSeasar2の規約に従ってconvension.diconの設定を使用します。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR//DTD S2Container 2.4//EN"
  "http://www.seasar.org/dtd/components24.dtd">
<components>
  <component class="org.seasar.framework.convention.impl.NamingConventionImpl">
    <initMethod name="addRootPackageName">
      <arg>"org.seasar.s2click.example"</arg>
    </initMethod>
  </component>
</components> 

この場合、ルートパッケージに.pageをつけたorg.seasar.s2click.example.pageパッケージにXxxxPageというクラス名(末尾がPageで終わるようにする) でページクラスを作成しておくと、自動的にS2Containerに登録されます。

publicフィールドの活用

Seasar2ではJavaBeanに無用なアクセサを設けず、publicフィールドを活用することが推奨されています(もちろんカプセル化の観点からアクセサメソッドを用意したほうがよいケースもあります)。 しかし、ClickはJavaBean規約に従いアクセサメソッドを持ったJavaBeanの利用が想定されています。 そこで、S2ClickではClickでもpublicフィールドを活用するための機能を提供します。

Velocityテンプレート
Clickではビュー技術としてVelocityを使用します(JSPを利用することも可能です)。 Velocityは標準ではpublicフィールドの利用をサポートしていませんが、 S2Clickではプロパティアクセスの構文でpublicフィールドにもアクセスすることができます。
Tableコントロール
ClickのTableコントロールはJavaBeanのリストを表形式で表示することができますが、 ゲッターメソッドを持ったJavaBeanの利用しかサポートされていません。 Clickが標準で提供しているnet.sf.click.control.Columnの代わりに org.seasar.s2click.control.PublicFieldColumnを利用することでTableコントロールでpublicフィールドを使用することが可能になります。
フォームとオブジェクトの相互変換
S2Clickが提供するorg.seasar.s2click.control.S2ClickFormクラスのcopyTo()メソッド、およびcopyFrom()メソッドはpublicフィールドに対応しています。 また、S2ClickUtilsクラスのcopyFormToObject()メソッド、およびcopyObjectToForm()メソッドも同様にpublicフィールドに対応しています。

リクエストパラメータのバインド

Click Frameworkは標準でページクラスのpublicフィールドに同じ名前のリクエストパラメータをバインドする機能を備えています。 しかし、S2ClickのページにはDI用のpublicフィールドも存在するため、リクエストパラメータによるDI用フィールドの上書きを防ぐため、 リクエストパラメータの自動バインド機能は利用できません。

代替手段として、@Requestアノテーションを付与したpublicフィールドにリクエストパラメータをバインドすることができます。 デフォルトではフィールド名と同じ名前のリクエストパラメータがバインドされますが、 @Requestアノテーションのパラメータによって別の名前のリクエストパラメータをバインドすることもできます。

また、@Requestアノテーションにrequired=trueの指定を追加することで、パラメータの必須チェックを自動的に行うことができます (必須パラメータが設定されなかった場合にはRuntimeExceptionが発生します)。

public class HelloPage extends Page {

  /** idというリクエストパラメータをバインド */
  @Request
  public String id;

  /** articleというリクエストパラメータをバインド(必須) */
  @Request(name="article", required=true)
  public String articleId;

}

ページクラスの基底クラス

S2ClickPage

S2ClickはAjaxやファイルダウンロードでの利用を想定し、ページクラスの抽象基底クラスを提供しています。 Ajaxやファイルダウンロード機能を使用するページクラスはorg.seasar.s2click.S2ClickPageを継承して実装します。 S2ClickPageには以下のようなメソッドが用意されており、サブクラスではこれらのメソッドを呼び出すことでJSONやHTML、ファイルなどを返却することができます。

メソッド名 説明
renderJSON(Object obj) 引数で渡したオブジェクトをJSONとしてレスポンスにレンダリングします。
renderHTML(String html) 引数で渡した文字列をHTMLとしてレスポンスにレンダリングします。
renderFile(String fileName, InputStream in) 引数で渡したファイル名と入力ストリームの内容をレスポンスにレンダリングします。
renderResponse(String contentType, InputStream in) コンテンツタイプを指定して入力ストリームの内容をレスポンスにレンダリングします。

アノテーションによるパスの指定

@Pathアノテーションで任意のパスにページクラスをマッピングすることができます。 対応するVelocityテンプレートが存在しないページクラスのパスを指定する場合に使用します。

@Path("/controls.htm")
public class ControlsPage extends LayoutPage {
  ...
} 

@UrlPatternアノテーションをページクラスに付与すると、ページに任意のエイリアスを指定することができます。 これはApacheのmod_rewriteのように動作します。URLパターンで指定したパスの一部をリクエストパラメータにマッピングすることもできます。

@UrlPattern("/user/select/{userId}")
public class UrlPatternPage extends LayoutPage {

  // リクエストパスの{userId}に一致した部分がセットされます
  @Request
  public String userId;

} 

Ajaxの実装例

JSONによるAjaxを実現するページクラスの実装例を以下に示します。

public class AjaxPage extends S2ClickPage {

  public AjaxPage(){
    AjaxButton button = new AjaxButton("button", "書籍情報を取得", this, "getAllBooks");
    button.addAjaxHandler(AjaxRequestButton.ON_COMPLETE, "displayResult");
    addControl(button);
  }

  public boolean getAllBooks(){
    List<Book> books = bookService.getAllBooks();
    renderJSON(books);
    return false;
  }
}

上記の例ではボタンをクリックするとprototype.jsのAjax.Requestによってページクラスの getAllBooks()メソッドが呼び出され、JSONが返却されます。 JSONが返却されるとHTML側ではJavaScriptのdisplayResult()関数が呼び出されます。

ファイルダウンロードの実装例

ファイルダウンロードを実現するページクラスの実装例を以下に示します。

public class FileDonwloadPage extends S2ClickPage {

  public FileDonwloadPage(){
    ActionLink link = new ActionLink("link", "ダウンロード", this, "onClick");
    addControl(link);
  }

  public boolean onClick(){
    String fileName = "sample.txt";
    InputStream in = getClass().getResourceAsStream("sample.txt");
    renderFile(fileName, in);
    return false;
  }
}

上記の例ではリンクをクリックするとページクラスのonClick()メソッドが呼び出され、 ファイルのダウンロードが行われます。

コントロール

S2Clickでは以下のような拡張コントロールを提供しています。 各コントロールの詳細についてはダウンロードしたアーカイブに含まれるJavadocやサンプルを参照してください。

クラス名 説明
org.seasar.s2click.control.S2ClickForm 入力フォームを作成する際に便利な機能を備えた抽象基底クラスです。
org.seasar.s2click.control.DateFieldYYYYMMDD 日付をYYYY/MM/DD形式で表示するDateFieldコントロールです。
org.seasar.s2click.control.ToolTip overLIBを使用してツールチップを表示するコントロールです。
org.seasar.s2click.control.CodePrettify プログラムのソースコードを強調表示するためのコントロールです。
org.seasar.s2click.control.AjaxLink Ajaxでページクラスのイベントハンドラメソッドを呼び出すActionLinkコントロールです。
org.seasar.s2click.control.AjaxButton Ajaxでページクラスのイベントハンドラメソッドを呼び出すActionButtonコントロールです。
org.seasar.s2click.control.AjaxSubmit フォームの内容をAjaxで送信するためのSubmitコントロールです。
org.seasar.s2click.control.FCKEditor FCKeditorを使用してHTMLを編集するためのコントロールです。 S2ClickのexamplesにはFCKeditorのファイルブラウザを動作させるためのページクラスの実装も含まれています。
org.seasar.s2click.control.HiddenList 同じパラメータ名で複数のhiddenフィールドを出力するためのコントロールです。
org.seasar.s2click.control.GreyboxButton GreyBoxを使用してモーダルダイアログを表示するためのボタンです。
org.seasar.s2click.control.GreyboxLink GreyBoxを使用してモーダルダイアログを表示するためのリンクです。
org.seasar.s2click.control.MobileForm 携帯向けの入力フォームを作成するためのS2ClickFormの拡張です。 JavaScriptやテーブルによるレイアウト、CSSのための記述などを一切行わず、シンプルかつ軽量なレンダリングを行います。
org.seasar.s2click.control.PaginateList リスト内のオブジェクトをVelocityテンプレートを指定してレンダリングします。 ページング機能を備えています。

ユーティリティ

org.seasar.s2click.util.S2ClickFormat

Click標準のnet.sf.click.util.Formatを拡張し、便利なメソッドを追加しています。 HTMLテンプレートでは$formatで参照することができます。

メソッド 説明
String date(Date date) 引数に渡された日付をyyyy/MM/dd形式にフォーマットします。
String datetime(Date date) 引数に渡された日付をyyyy/MM/dd HH:mm:ss形式にフォーマットします。
String url(String value) 引数に渡された文字列をs2click.diconで指定された文字コードでURLエンコードします。
String json(Object obj) JavaオブジェクトをJSONに変換します。
String nbsp(String value) 連続する半角スペースの2つめ以降を&nbsp;に変換します。
Object ognl(String expression) 引数のOGNL式として評価し、結果を返却します。
String mask(String value) 引数の文字列と同じ長さのアスタリスクからなる文字列を返却します。

トランザクションの制御

Clickは1リクエストでページクラスのメソッドを複数回呼び出します。 そのため、ページクラスのメソッドに対してトランザクション制御のためのインターセプタを適用しようとするとメソッドごとにトランザクションが完結してしまいます。 S2Clickでは1リクエスト=1トランザクションでトランザクション制御を行うためのS2ClickServletTxが付属しています。

S2ClickServletTxを使用するにはweb.xmlでS2ClickServletの代わりにS2ClickServletTxを使うよう設定してください。

<servlet>
  <servlet-name>ClickServlet</servlet-name>
  <servlet-class>net.sf.click.S2ClickServletTx</servlet-class>
  <load-on-startup>2</load-on-startup>
</servlet> 

リソースをクラスパス内に格納する

S2Clickにはクラスパス内に格納したイメージやJavaScriptなどをHTMLから参照するためのResourceServletが付属しています。 ResourceServletを使用するにはweb.xmlに以下のような設定を追加します。

<servlet>
  <servlet-name>ResourceServlet</servlet-name>
  <servlet-class>org.seasar.s2click.servlet.ResourceServlet</servlet-class>
  <init-param>
    <param-name>rootPackage</param-name>
    <param-value>org.seasar.s2click.example.resource</param-value>
  </init-param>
  <load-on-startup>3</load-on-startup>
</servlet>
...
<servlet-mapping>
  <servlet-name>ResourceServlet</servlet-name>
  <url-pattern>/resources/*</url-pattern>
</servlet-mapping> 

ResourceServletには初期化パラメータとしてrootPackageを指定する必要があります。 このパラメータにはリソースを格納するパッケージ名を指定してください。 パッケージ名はカンマで区切って複数指定することもできます。

上記の設定の場合、org.seasar.s2click.example.resourceパッケージ配下に配置したリソースに対し、 http://localhost:8080/s2click/resources/sample.gifというURLでアクセスすることができます(ホスト名、ポートやコンテキストは環境にあわせて読み替えてください)。

また、/resources/subpackage/sample.gifのようにパスをネストさせることでサブパッケージのリソースを参照することも可能です。

情報源

Click Framework
本家Click FrameworkのWebサイトです。英語ですが、非常に充実したドキュメントが提供されています。
Click Wiki
Clickの日本語Wikiサイトです。本家のドキュメントの翻訳などを行っています。
Click Framework探訪
オブジェクトの広場のClickに関する記事です。
シンプルかつ強力なコンポーネント指向フレームワーク「Click Framework」
ITProのClickに関する記事です。
新・たけぞう瀕死の日記
Clickのコミッタであり、S2Clickの開発者でもあるたけぞうの日記です。
Click Blog(英語)
Clickの開発チームのブログです。リリース情報などが掲載されています。
Clickのメーリングリスト(英語)
Clickのメーリングリストです。ユーザ向けと開発者向けが用意されています。過去ログは以下のURLでも参照することができます。
S2ClickのJavadoc
S2ClickのJavadocです。
S2ClickのSubversionリポジトリ
S2ClickのSubversionリポジトリブラウザです。ソースコードはhttps://www.seasar.org/svn/sandbox/s2click/からチェックアウトできます。
S2ClickのJIRA
フィードバックやバグレポートはこちらにどうぞ。