Configuration

Clickの設定

このセクションではClickを使用したWebアプリケーションの設定方法を解説します。以下のトピックをカバーしています。

• サーブレットの設定 - ClickServletの設定方法
• アプリケーションの設定 - Clickの設定ファイルの記述方法
• 自動デプロイされるファイル - Clickが自動的に展開するファイルについて

Clickの設定ファイルは以下の通りです。

• WEB-INF/click.xml - Clickアプリケーションの設定（必須）
• WEB-INF/web.xml - サーブレットの設定（必須）

 サーブレットの設定

まずはweb.xmlでClickServletを設定する必要があります。*.htmへのリクエストをClickServletにマッピングする場合の例を以下に示します。

<web-app> <servlet> <servlet-name>ClickServlet</servlet-name> <servlet-class>org.apache.click.ClickServlet</servlet-class> <load-on-startup>0</load-on-startup> </servlet> <servlet-mapping> <servlet-name>ClickServlet</servlet-name> <url-pattern>*.htm</url-pattern> </servlet-mapping> </web-app>

デフォルトではClickServletはアプリケーション設定ファイルとして/WEB-INF/click.xmlを読み込みます。

（1.4-RC2から）このclick.xmlがWEB-INF以下に無い場合、ClickServletは、クラスパスの中からロードを試みます。

サーブレットマッピング

Clickのページテンプレートは*.htmという拡張子にし、ClickServletは*.htmというリクエストにマッピングすることが推奨されます。この規約によって、例えば*.htmlという拡張子を持つ静的なHTMLページについてはClickServletに処理させないようにすることができます。

Load On Startup

常にload-on-startup要素に0を指定すべきであるという点に注意してください。これによってサーブレットはサーブレットの開始時に初期化され、アプリケーションの初回利用時の遅延を防ぎます。

ClickServletは実行中の性能を向上させるため、起動時にできるだけ多くの処理を行います。Clickの起動およびキャッシュの振る舞いはclick.xmlのmode要素で指定することができます。

 アプリケーションの設定

Clickの心臓部がclick.xmlという設定ファイルです。このファイルはアプリケーションのページ、ヘッダー、フォーマットオブジェクト、アプリケーションのモードを指定します。

XMLの定義についてはClick DTDを参照してください。

click.xmlの簡単な例を以下に示します:

<click-app> <pages package="com.mycorp.page"/> <mode value="profile"/> </click-app>

以下は全てのオプションを指定した場合の例です:

<click-app charset="UTF-8" locale="de"> <pages package="com.mycorp.banking.page"> <page path="index.htm" classname="Home"/> </pages> <pages package="com.mycorp.common.page"/> <format classname="com.mycorp.util.Format"/> <mode value="profile"/> <log-service classname="org.apache.click.extras.service.Log4JLogService"/> </click-app>

この後のチャプターではClick設定の詳細を記述します。

Click App

ルートのclick-app要素はcharsetとlocaleという2つのローカライゼーションに関する属性を持っています。

<!ELEMENT click-app (pages*, headers?, format?, mode?, controls?, file-upload-service?, log-service?, template-service?)> <!ATTLIST click-app charset CDATA #IMPLIED> <!ATTLIST click-app locale CDATA #IMPLIED>

charset属性には以下で使用される文字コードを一括指定します。

• Velocityテンプレート
• HttpServletRequestのリクエストパラメータのデコードに使用する文字コード
• ページが出力するContent-Typeヘッダのcharset（getContentType()メソッドを参照してください）

locale属性にはアプリケーションのデフォルトロケールを指定します。もしこの属性が記述されていた場合、リクエストが返却するロケールをオーバーライドします。ContextのgetLocale()メソッドを参照してください。

以下は文字コードをUTF-8に、ロケールをドイツ（de）に指定する場合の例です:

<click-app charset="UTF-8" locale="de"> .. </click-app>

Pages

click-appの最初の要素はClickのページの一覧を定義するためのpages要素です。

<!ELEMENT pages (page*)> <!ATTLIST pages package CDATA #IMPLIED> <!ATTLIST pages automapping (true|false) "true"> <!ATTLIST pages autobinding (true|false) "true">

page要素はpage要素で指定したページクラスのクラス名の先頭に付与するパッケージ名をpackage属性で指定することができます。

また、pages要素はページの自動マッピングを行うためのautomapping属性を持っています。これに関しては後述します。

Multiple Pages Packages

Clickは複数のpackageによるautomappingを可能にするために複数のpages要素指定ができます。

<click-app> <pages package="com.mycorp.banking.page"/> <pages package="com.mycorp.common.page"/> </click-app>

複数のpages要素がある場合、ページはpage要素の順にロードされマニュアル指定のページ要素がautomappingされたページよりも先にロードされます。一度Pageクラスにページテンプレートがマップされると後続に一致するものが存在しても置き換わりません。そのため上にあるpages要素は下にあるpages要素より優先度が高くなります。

Page

page要素ではClickアプリケーションのページを定義します。

<!ELEMENT page (header*)> <!ATTLIST page path CDATA #REQUIRED> <!ATTLIST page classname CDATA #REQUIRED>

ClickはHTTPリクエストをページのパスにマッピングするため、path属性は一意でなければなりません。

Clickはリクエストごとにclassname属性に指定されたページクラスのインスタンスを生成します。すべてのページクラスはPageクラスのサブクラスでなくてはならず、引数を取らないpublicコンストラクタを用意しておく必要があります。

また、page要素には次のトピックで触れるheader要素を含めることができます。

Clickは起動時にすべてのページ定義をチェックし、もし致命的な設定エラーがあった場合、ClickServletはエラーメッセージをログに出力すると共にUnavailableExceptionをスローします。この場合、エラーを修正し、アプリケーションを再起動するまでClickアプリケーションは動作しません。

ページの自動マッピング

pages要素のautomappingオプションは簡単なルールに従ってアプリケーションのページを設定します。これによって自動マッピングのルールにあてはまらない場合だけ設定ファイルを記述すればよくなるので、設定ファイルが非常に効率化されます。

自動マッピングはWEB-INFディレクトリとclickディレクトリ以外の*.htmファイルおよびJSPファイルをページクラスにマッピングしようとします。自動マッピングされたページは手動で定義されたページのあとでロードされ、手動で定義したページが優先されます。自動マッピングが有効になっており、モードがdebugまたはtraceの場合、Clickアプリケーションはページのマッピング状況をログ出力します。

index.htm                     =>  com.mycorp.page.Home
search.htm                    =>  com.mycorp.page.Search
contacts/contacts.htm         =>  com.mycorp.page.contacts.Contacts
security/login.htm            =>  com.mycorp.page.security.Login
security/logout.htm           =>  com.mycorp.page.security.Logout
security/change-password.htm  =>  com.mycorp.page.security.ChangePassword

上記のログは以下のようにpackageプレフィックスを使用して手動で設定された場合の例です。

<click-app> <pages package="com.mycorp.page" automapping="false"> <page path="index.htm" classname="Home"/> <page path="search.htm" classname="Search"/> <page path="contacts/contacts.htm" classname="contacts.Contacts"/> <page path="security/login.htm" classname="security.Login"/> <page path="security/logout.htm" classname="security.Logout"/> <page path="security/change-password.htm" classname="security.ChangePassword"/> </pages> </click-app>

自動マッピングを使うと、自動マッピング機能でマッピングされないHomeクラスとindex.htmのマッピングを記述するだけで済みます。

<click-app> <pages package="com.mycorp.page" automapping="true"> <page path="index.htm" classname="Home"/> </pages> </click-app>

ページテンプレート名からページクラスへのマッピングの規約は以下の通りです。

change-password.htm  =>  ChangePassword
change_password.htm  =>  ChangePassword
changePassword.htm   =>  ChangePassword
ChangePassword.htm   =>  ChangePassword

ページを自動マッピングする際にクラスが見つからない場合、Clickはクラス名にPageというサフィックスをつけてクラスを検索します。

customer.htm         =>  CustomerPage
change-password.htm  =>  ChangePasswordPage

自動マッピングの除外

ページの自動マッピングでは、自動マッピングを適用して欲しくないリソースが存在する場合にも対応しています。たとえば大量の*.htmファイルを持つJavaScriptライブラリを使用する場合、あなたはこれらのファイル群に対して自動マッピングを行って欲しくないと考えることでしょう。

このようなシチュエーションでは、pages要素の子要素としてexcludes要素を使用することができます。

<!ELEMENT excludes (#PCDATA)> <!ATTLIST excludes pattern CDATA #REQUIRED>

たとえば私たちのアプリケーションがTinyMCE JavaScriptライブラリを使用していたとしましょう。この場合、/tiny_mceディレクトリ配下の*.htmファイルを自動マッピングから除外するよう設定することができます。

<click-app> <pages package="com.mycorp.page"> <excludes pattern="/tiny_mce/*"/> </pages> </click-app>

excludes要素のpattern属性はカンマで区切って複数のディレクトリ、ファイルを指定することができます。

<click-app> <pages package="com.mycorp.page"> <excludes pattern="/dhtml/*, /tiny_mce/*, banner.htm, about.htm"/> </pages> </click-app>

なお、ヘッダーのキャッシュが有効になっている場合、自動マッピングから除外されたページは内部的なページクラスで処理されます。

ページの自動バインディング

デフォルトでは、全てのページで自動バインディングが有効になっています。 自動バインディングが有効な場合、ClickServletは以下のことを自動で実施します。

• ページのコンストラクタが実行された後、publicなコントロールをページに追加します。
• publicなコントロールの名前が定義されていない場合、そのフィールド名をコントロールの名前として設定します。
• ページのコンストラクタが実行された後、リクエストのパラメータをpublicフィールドにセットします。ClickServlet.processPageRequestParams(Page)に詳しい説明があります。
• ページを出力する前に、ページのpublicなフィールドをページのモデルに追加します。

例

public class EmployeePage extends Page { public Form employeeForm = new Form(); public Table myTable = new Table(); }

この例でemployeeFormとmyTableの２つのコントロールはPageに追加されません。注意すべき点はFormとTableに名前が定義されていないことです。

自動バインディング可能な場合、ClickServletは新しいPageを作成しpublicなコントロールを追加します。この例ではemployeeFormとmyTableがPageに追加されます。addControl(employeeForm) と addControl(myTable)を実行した場合と同じです。

コントロールに名前が定義されていない場合、ClickServletはコントロールの名前としてそれらのフィールド名を設定します。この例ではFormの名前にはemployeeForm、Tableの名前にはmyTableが設定されます。

上の例は以下の記述の省略形になります。

public class EmployeePage extends Page { private Form employeeForm = new Form(); private Table myTable = new Table(); public void onInit() { employeeForm.setName("employeeForm"); addControl(employeeForm); myTable.setName("myTable"); addControl(myTable); } }

autobinding属性をfalseにすることで、この挙動を無効にすることが可能です。

<click-app> <pages package="com.mycorp.page" autobinding="false"/> </click-app>

Headers

headers要素は任意の要素であり、header要素のリストを含みます。ここで定義されたheader要素はすべてのページクラスに適用されます。

<!ELEMENT headers (header*)>

header要素はHttpServletResponseに適用されるヘッダー名と値の組を指定します。

<!ELEMENT header (#PCDATA)> <!ATTLIST header name CDATA #REQUIRED> <!ATTLIST header value CDATA #REQUIRED> <!ATTLIST header type (String|Integer|Date) "String">

ヘッダー情報はページが生成され、onInit()メソッドが呼び出される前にセットされます。ページクラスではsetHeader()メソッドを使用してheadersプロパティを変更することは可能です。

ブラウザのキャッシュ

通常、ヘッダはブラウザをキャッシュを無効にするために使用されます。header要素をアプリケーションで定義していなければ、既定でClickは以下のキャッシュを使わない設定を使用します。

<click-app> <pages> .. </pages> <headers> <header name="Pragma" value="no-cache"/> <header name="Cache-Control" value="no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/> <header name="Expires" value="1" type="Date"/> </headers> </click-app>

これを各ページごとに行うこともできますし、アプリケーション内のすべてのページに対して行うこともできます。例えば、ログインページでキャッシュを無効にする場合の例を以下に示します。Dateヘッダのvalue属性にはlong型の数値を指定することに注意してください。

<page path="login.htm" classname="com.mycorp.page.Login"/> <header name="Pragma" value="no-cache"/> <header name="Expires" value="1" type="Date"/> </page>

もし、キャッシュを特定のページで有効化にしたい場合には、以下のCache-Controlを設定してください。これは、このページのキャッシュがリロード後１時間の間は有効であることを示します。

<page path="home.htm" classname="com.mycorp.page.Home"/> <header name="Cache-Control" value="max-age=3600, public, must-revalidate"/> </page>

すべてのページに適用するには以下のようにheaders要素の配下に定義します。

<click-app> <pages> .. </pages> <headers> <header name="Pragma" value="no-cache"/> <header name="Cache-Control" value="no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/> <header name="Expires" value="1" type="Date"/> </headers> </click-app>

Format

format要素は任意の要素であり、はすべてのページに適用されるフォーマットオブジェクトのクラス名を指定します。

<!ELEMENT format (#PCDATA)> <ATTLIST format classname CDATA #FIXED "org.apache.click.util.Format">

デフォルトではすべてのページでorg .apache.click.util.Formatオブジェクトが使用されます。フォーマットオブジェクトはVelocityテンプレート内で$formatという名前で利用することができます。

独自のフォーマットクラスを使用する場合、format要素をclick-app要素の配下に記述します。

<click-app> .. <format classname="com.mycorp.util.CustomFormat"/> </click-app>

Mode

mode要素は任意の要素であり、アプリケーションのロギングとキャッシュのモードを指定します。

<!ELEMENT mode (#PCDATA)> <ATTLIST mode value (production|profile|development|debug|trace) "development">

デフォルトではClickアプリケーションはdevelopmentモード（ページテンプレートのキャッシュは無効、ログレベルはINFO）で実行されます。

アプリケーションのモードを指定するにはclick-app要素の配下にmode要素を記述します。以下はproductionモードで実行する場合の例です。

<click-app> .. <mode value="production"> </click-app>

アプリケーションのモードの設定は、システムプロパティである"click.mode"を指定することで上書き可能です。これは実際のシステムでデバッグするような場合に利用できます。その場合は、以下のシステムプロパティを設定してモードを変更し、アプリケーションを再起動することでトレースできるようになります。

-Dclick.mode=trace

アプリケーションのモードと、モードごとの振る舞いは以下の通りです。

モード	ページの自動ロード	テンプレートのキャッシュ	Clickのログレベル	Velocityのログレベル
production	No	Yes	WARN	ERROR
profile	No	Yes	INFO	ERROR
development	Yes	No	INFO	ERROR
debug	Yes	No	DEBUG	ERROR
trace	Yes	No	TRACE	WARN

ページの自動ロード

ページの自動ロードが有効になっている場合、ページテンプレートとページクラスは実行時に自動的にロードされます。これらのページは自動マッピングのルールにしたがってロードされます。

ページの自動ロードは、新しいページを追加した際にアプリケーションを再起動する必要がないため、高速な開発ではとても便利な機能です。

ClickとVelocityのロギング

ClickおよびVelocityのランタイムはログを出力するためにLogServiceを使用します。デフォルトのLogService実装はConsoleLogServiceで実行時のログはコンソール（System.out）に送られます。例えば、以下の出力はモードがtrace時のHemePageへのリクエストに対するものです。

[Click] [debug] GET http://localhost:8080/quickstart/home.htm
[Click] [trace]    invoked: HomePage.<<init>>
[Click] [trace]    invoked: HomePage.onSecurityCheck() : true
[Click] [trace]    invoked: HomePage.onInit()
[Click] [trace]    invoked: HomePage.onGet()
[Click] [trace]    invoked: HomePage.onRender()
[Click] [info ]    renderTemplate: /home.htm - 6 ms
[Click] [trace]    invoked: HomePage.onDestroy()
[Click] [info ] handleRequest:  /home.htm - 24 ms  

すべての未処理の例外はClickServletによってログに出力されます。

Click ExtraにLog4JとJDK Logging API用のログアダプターが提供されています。

アプリケーションがproductionモードで動作していない場合、エラーページは詳細なデバッグ情報を表示します。アプリケーションのモードがproductionの場合は、機密情報がの漏洩を防ぐため、なにも表示しません。この振る舞いはデプロイされたclick/error.htmというページテンプレートを修正することで変更することが可能です。

Controls

controls要素は任意の要素であり、アプリケーションの起動時にデプロイされるcontrol要素のリストを定義します、

<!ELEMENT controls (control*)>

control要素でonDeploy()メソッド（Clickアプリケーションの起動時に呼び出されます）を持つControlクラスを登録します。

<!ELEMENT control (#PCDATA)> <!ATTLIST control classname CDATA #REQUIRED>

例えば、CustomFieldクラスを登録する場合、click.xmlには以下の内容を加えます。

<click-app> .. <controls> <control classname="com.mycorp.control.CustomField"/> </controls> </click-app>

 自動デプロイされるファイル

予め用意されたリソース（テンプレート、スタイルシート等）をWebアプリケーションで利用可能にするために、Clickは起動時にクラスパス内のリソースを自動的に/clickディレクトリにデプロイします（存在しない場合のみ）。

あなたはこれらのファイルを変更することができます。その場合、Clickは上書きしません。これらのファイルには以下のものがあります。

• click/error.htm - エラー処理用のテンプレート。
• click/control.css - コントロールのスタイルシート。
• click/control.js - コントロールが使用するJavaScriptライブラリ。
• click/not-found.htm - ページが存在しない場合のテンプレート。

例えば、control.cssの変更用コピー（もしくはまったく新しいバージョン）でコントロールのスタイルを変更したい場合、それをWebプロジェクトの/clickフォルダにおきます。

/webapp/click/control.css

Clickの起動時、control.cssはそのデフォルトバージョンでは置き換えられません。

別のコントロールは別のスタイルシートやJavaScript、画像ファイルをデプロイすることができます。ただし、その場合でも同様のルールが適用されます。スタイルシートやJavaScript、画像ファイルの変更用コピーを/clickフォルダの下に置く場合、元のリソースを上書きします。

注意：いくつかの複雑なコントロール（チェックリスト、カラーピッカー、ツリー）は/clickのサブフォルダー、例えば/click/checklist/*にリソースをデプロイします。

コントロールのJavadocでは普通このコントロールで何のリソースがデプロイされるかが示されています。

大抵のServletコンテナでは解凍されてWARによる実行は簡単でただ置くだけです。けれどもWeblogic（少なくともVersion10）のようないくつかのコンテナでは動作しません。Weblogicで解凍されたWARを実行するためにはAdmin Console > server node > Web Applications タブをクリックし、Archived Real Path Enabled Parameter にチェックを入れます。

ファイルシステムのパーミッションによる制限のためClickがこれらのファイルをデプロイできなかった場合、その旨がログに出力されます。

もしアプリケーションサーバがWAR/EARを解凍できない、もしくは、パーミッションが制限されている場合、これらの自動デプロイされるファイルをWARファイルでパッケージングする必要があります。これを行うためには、まずパーミッション制限のない開発マシンでアプリケーションを実行し、デプロイされたファイル群をWAR/EARにパッケージ化するべきです。

 カスタムリソースのデプロイ

Clickは事前設定されたリソース（テンプレート、スタイルシート、JavaScriptなど）のJarからWebアプリケーションへの配備方法を２つ用意しています。

1. コントロールのonDeploy()イベントハンドラーを通して。上記Controlsを参照
2. リソース（スタイルシート、JavaScript、画像など）を特別なフォルダであるMETA-INF/webにパッケージングすることで

１つめの選択肢はすでにControlsで説明しました。2つめの選択肢を見てみましょう。

Clickが開始されるとき、クラスパス中のそれぞれのJarに'META-INF/web/'で始まるエントリーがあるか検索します。（注意してほしいのは、Clickは全体のクラスパスであっても検索するので、JarファイルはWEB-INF/libのようなWARファイルのlibフォルダの中に入れることを強く推奨します。クラスパス上の共有Jarではクラスロード問題が発生する可能性があります）

Clickは'META-INF/web/'配下のすべてのファイルを見つけwebアプリケーションフォルダにコピーします。

例えば、Jarファイルに以下のエントリーがある場合

• META-INF/web/mycorp/edit_customer.js
• META-INF/web/mycorp/edit_customer.css
• mycorp/pages/EditCustomerPage.class

Clickは'mycorp/edit_customer.js'と'/mycorp/edit_customer.css'をwebアプリケーションフォルダにコピーします。

従ってwebアプリケーションのコンテキストルートが'webapp'の場合、ファイルは'webapp/mycorp/edit_customer.js'と'webapp/mycorp/edit_customer.css'として配備されます。

２つめの選択肢はJarから大量のリソースを配備する場合に特に有効です。注）Jarは配備の際、'WEB-INF/lib'の配下にのみ置かれていること。