| Oracle® Fusion Middleware Oracle ADF FacesによるWebユーザー・インタフェースの開発 12c (12.1.2) E48096-02 |
|
 前 |
 次 |
この章では、アプリケーションのADF Faces入力コンポーネントに変換と検証の機能を追加する方法について説明します。また、カスタムJSF変換および検証を追加する方法と、エラー(検証によって生じたもの以外も含む)の処理と表示の方法についても説明します。
この章では、次の項目について説明します。
ADF Facesの入力コンポーネントでは、変換機能がサポートされます。Webアプリケーションで、int、long、dateなどの様々な型をモデル・レイヤーに格納できます。ただし、クライアント・ブラウザで表示されるとき、ユーザー・インタフェースには、ユーザーが読取りまたは変更できるような形式でデータが表示される必要があります。たとえば、フォームの日付フィールドでは、java.util.Dateオブジェクトをmm/dd/yyyy形式のテキスト文字列で表します。ユーザーが「date」フィールドを編集してフォームを送信した場合、文字列は、アプリケーションで要求されるタイプに変換される必要があります。変換後のデータは、規則および条件に対して検証されます。逆に、String以外の型として格納したデータを表示および更新用にStringに変換することもできます。af:inputDateなどの多くのコンポーネントで、変換機能が自動的に提供されます。
ADF Facesの入力コンポーネントでは、検証機能もサポートされます。1つ以上のバリデータ・タグをコンポーネントに追加できます。また、ビジネス・ニーズに応じてカスタム・バリデータを作成することもできます。
バリデータとコンバータには、ユーザーが関連付けられているフィールドをクリックすると表示されるデフォルトのヒント・メッセージがあります。コンバータの場合、ヒントは、通常、入力値に使用する、指定されたパターンに基づいた適切な形式をユーザーに示します。バリデータの場合、ヒントを使用して、コンポーネントに構成されている検証に基づいた有効な値が示されます。変換または検証に失敗すると、関連付けられたエラー・メッセージがユーザーに表示されます。これらのメッセージはダイアログに表示することも、変換または検証に失敗したコンポーネントと並べてページ自体に表示することもできます。ADF Facesアプリケーションでのメッセージの表示の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。
ADF Facesコンバータは、標準JSFコンバータを拡張するコンバータのセットです。入力コンポーネントのADF Facesコンバータはクライアント側で動作するため、変換のエラーはクライアントで捕捉され、サーバーへのラウンドトリップが回避されます。ADF Facesコンバータは、入力コンポーネントに簡単にドラッグ・アンド・ドロップできます。
ADF Facesバリデータは、標準JSFバリデータも補強します。ADF Facesバリデータは、クライアント側とサーバー側の両方で動作できます。クライアント側バリデータはJavaScriptで記述され、クライアント側で捕捉された検証エラーはサーバーとの間をラウンドトリップしなくても処理できます。
ADF Facesコンバータを使用して、入力コンポーネントからモデルで要求される形式に入力を変換します。一般的なユースケースは、数値の入力のための入力コンポーネントの使用と、ユーザーが入力した文字列をモデルで処理するための数値に変換するためのコンバータの組込みです。たとえば、af:inputTextコンポーネントは製品ID属性に使用されます。af:convertNumberコンバータをaf:inputTextコンポーネントに追加して、StringをNumberに変換します。別の例は、製品のコストの属性用にinputTextコンポーネントがある場合です。af:convertNumberを使用して、入力文字列を適切な通貨形式に変換できます。
入力文字列を検証するのと同じ方法で、バリデータを入力コンポーネントに追加します。たとえば、バリデータをaf:inputTextコンポーネントに追加して、製品IDの桁数が適切な範囲内にあることを確認できます。af:validateLengthをaf:inputTextに追加し、minimumおよびmaximum属性を設定して有効な桁の長さを定義します。
コンバータおよびバリデータを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。次に、役に立つ可能性のある他のセクションへのリンクを示します。
JSFライフサイクルでの変換と検証の動作の詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。
ADF Facesでは、デフォルトのメッセージのかわりに変換エラー・メッセージの詳細部分をカスタマイズできます。メッセージの作成の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。
文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。
データを持つフォームが送信されると、編集可能なvalue属性がバインドされているUIコンポーネントごとに、リクエスト値がブラウザからサーバーに送信されます。リクエスト値は、JSFのリクエスト値の適用フェーズでデコードされ、デコードされた値はコンポーネントのsubmittedValue属性にローカルに保存されます。値に変換が必要な場合(Stringとして表示されるが、java.util.Dateオブジェクトとして格納されている場合など)、データは、UIコンポーネントごとに検証の処理フェーズで正しい型に変換されます。
検証または変換に失敗した場合、ライフサイクルはレスポンスのレンダリング・フェーズに進み、対応するエラー・メッセージがページに表示されます。変換および検証が正常に終了すると、モデルの更新フェーズが開始され、変換および検証された値がモデルの更新に使用されます。
検証または変換エラーが起きた場合、検証または変換に失敗したコンポーネントで、関連付けられたエラー・メッセージがキューに置かれ、コンポーネント自身は無効とされます。その後、現在のページがエラー・メッセージを使用して再表示されます。ADF Facesのコンポーネントには、これらのメッセージを宣言的に設定する方法が用意されています。
JSFライフサイクルでの変換と検証の動作の詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。
Webアプリケーションは、モデル・レイヤー内に多くのタイプのデータ(int、long、dateなど)を格納できます。ただし、クライアント・ブラウザで表示されるとき、ユーザー・インタフェースには、ユーザーが読取りまたは変更できるような形式でデータが表示される必要があります。たとえば、フォームの日付フィールドでは、java.util.Dateオブジェクトをmm/dd/yyyy形式のテキスト文字列で表します。ユーザーが「date」フィールドを編集してフォームを送信した場合、文字列は、アプリケーションで要求されるタイプに変換される必要があります。1つのUIコンポーネントには1つのコンバータのみを設定できます。
af:inputTextコンポーネントを作成し、コンバータを持つタイプの属性を設定すると、コンバータのタグが入力コンポーネントの子としてJDeveloperで自動的に追加されます。このタグでコンバータが起動され、ユーザーが入力したString型が、オブジェクトで規定された型に変換されます。
String型と単純なデータ型の間の変換を処理するJSFの標準コンバータでは、javax.faces.convert.Converterインタフェースが実装されます。用意されているJSF標準コンバータ・クラスは次のとおりです。
BigDecimalConverter
BigIntegerConverter
BooleanConverter
ByteConverter
CharacterConverter
DateTimeConverter
DoubleConverter
EnumConverter
FloatConverter
IntegerConverter
LongConverter
NumberConverter
ShortConverter
表7-1に、ADF Facesにより提供されるコンバータを示します。
表7-1 ADF Facesのコンバータ
| コンバータ | タグ名 | 説明 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
バリデータ同様、ADF Facesのコンバータはクライアント側でも実行されます。
コンバータが明示的に追加されていない場合、ADF Facesでデータ型に基づいたコンバータの作成が試行されます。このため、値が次の型にバインドされている場合、明示的にコンバータを追加する必要はありません。
java.util.Date
java.util.Color
java.awt.Color
java.lang.Number
java.lang.Integer
java.lang.Long
java.lang.Short
java.lang.Byte
java.lang.Float
java.lang.Double
表7-1にリストされているコンバータとは異なり、JavaScript対応のコンバータはtypeによって適用され、標準のコンバータのかわりに使用されてclassおよびid属性をオーバーライドします。これらのコンバータには、コンポーネント内にネストできるタグは関連付けられていません。
UIコンポーネントにコンバータを手動で挿入できます。
始める前に:
コンバータに関する知識が役立つ場合があります。詳細は、7.3項「変換の追加」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、7.1.2項「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。
タグを持つADF Facesコンバータを追加する手順:
「構造」ウィンドウで、コンバータを追加するコンポーネントを右クリックして「componentの中に挿入」を選択し、ADF Facesコンバータを挿入するために「ADF Faces」を選択します。
「JSF」→「コンバータ」を選択してJSFコンバータを挿入することもできます。
コンバータ・タグ(「日時の変換」など)を選択し、「OK」をクリックします。
JSFページでコンポーネントを選択し、「プロパティ」ウィンドウで、変換エラー用のメッセージなどの値を属性に設定します。ヘルプを参照するには、属性を右クリックし、「ヘルプ」を選択します。
複数のパターンを設定できるADF Facesコンバータもあります。詳細は、7.3.2項「複数のコンバータ・パターンを指定する方法」を参照してください。
ADF Facesでは、変換エラー・メッセージの詳細部分をカスタマイズできます。MessageDetailxyz属性(xyzはMessageDetailconvertDateなどの変換エラー・タイプ)に値を設定することにより、変換に失敗した場合、デフォルト・メッセージのかわりに、ADF Facesでカスタム・メッセージが表示されます。メッセージの作成の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。
一部のコンバータでは、複数のコンバータ・パターンがサポートされます。パターンでは、変換で受け入れられるデータの形式を指定します。複数のパターンが複数の形式に対応します。たとえば、ユーザーは、スラッシュ(/)またはハイフン(-)をセパレータとして使用して日付を入力できます。すべてのコンバータが複数のパターンをサポートするわけではありませんが、パターン一致は柔軟であり、複数のパターンが必要ではない場合もあります。
例7-1に、af:convertColorタグに対する複数パターンの使用を示します。「255-255-000」と「FFFF00」の両方の値が使用可能です。
例7-1 af:convertColorの複数パターン
<af:inputColor colorData="#{adfFacesContext.colorPalette.default49}" id="sic3"
label="Select a color" value="#{demoColor.colorValue4}" chooseId="chooseId">
<af:convertColor patterns="rrr-ggg-bbb RRGGBB #RRGGBB"
transparentAllowed="false"/>
</af:inputColor>
例7-2に、「6/9/2007」と「2007/9/6」の両方が使用可能なaf:convertDateTimeタグの使用を示します。
例7-2 af:convertDateTimeの複数パターン
<af:inputDate id="mdf5" value="2004/09/06" label="attached converter">
<af:convertDateTime pattern="yyyy/M/d" secondaryPattern="d/M/yyyy" />
</af:inputDate>
例7-3に、type属性がcurrencyに設定されており、$78.57と$078.57を変換の値として使用できるaf:convertNumberタグを示します。
ユーザーがコンバータを含むページを送信すると、ADF Facesのvalidate()メソッドでコンバータのgetAsObject()メソッドがコールされ、String値が必要なオブジェクト・タイプに変換されます。アタッチされているコンバータがなく、コンポーネントがモデルのBeanプロパティにバインドされている場合、ADFでモデルのデータ型を確認して適切なコンバータを見つけます。変換に失敗すると、コンポーネントのvalid属性がfalseに設定され、JSFでFacesContextによってメンテナンスされているキューにエラー・メッセージが追加されます。変換が正常終了し、コンポーネントにアタッチされているバリデータがある場合、変換された値がバリデータに渡されます。コンポーネントにアタッチされているバリデータがない場合、変換された値はローカル値として格納され、モデルの更新に後で使用されます。
日付コンバータでは、あいまいにならないように、4桁の年のパターンを使用する必要があります。パターンとして2桁の年の書式を使用すると、4桁の年の値がすべて2桁の年の値として表示されます。たとえば、パターンとして2桁の年の書式(MM-dd-yyなど)を使用している場合、日付値03-01-1910と03-01-2010は入力フィールドに03-01-10と表示されるので、サーバーに正しい年の値が格納されても、正確に解釈されないおそれがあります。
図7-1は、inputDateコンポーネントに表示されている日付値と、その下にあってサーバーに保存されている元の値を表示するoutputTextコンポーネントを示しています。
2桁の年の書式を使用すると、2桁の年を含むすべての文字列が、two-digit-year-startからtwo-digit-year-start + 100までの範囲内の日付に解決されます。たとえば、two-digit-year-startの値が1912で、文字列が01/01/50の場合、その日付は01/01/1950として解決されます。この範囲外の日付を入力するには、エンド・ユーザーは完全な(4桁の)年を使用して日付を入力する必要があります。two-digit-year-start要素とその構成方法の詳細は、第A.6.2項「trinidad-config.xmlの要素に関する必知事項」を参照してください。
|
注意: 2桁の年の書式を使用している間は、ユーザーが既存の値を編集しても、2桁の年は たとえば、 |
12時間形式(MM/dd/yyyy - hh:mmなど)をパターンとしてaf:convertDateTimeで使用する場合は、am/pmプレースホルダもパターンに含める必要があります(MM/dd/yyyy - hh:mm aなど)。含めないと、ピッカーでam/pmオプションが表示されず、am/pm情報を保存できません。図7-2に、inputDateコンポーネントのパターンにam/pmプレースホルダが含まれているケースと含まれていないケースを示します。
convertDateTimeパターンにタイムゾーン・プレースホルダ(z)を含めてタイムゾーン情報を表示する場合は(たとえばyyyy-MM-dd hh:mm:ss a zのように)、トリニダードのconvertDateTimeがタイムゾーン名の表示より優先される点に注意してください。コンバータをinputTextまたはoutputTextとともに使用すると、タイムゾーンはGMT + xという形式で表示されます。inputDateとともに使用すると、(UTC-08:00) ロサンゼルス - 太平洋標準時(PT)などの事前構成済の表示値の選択肢を使用してタイムゾーンが表示されます。
カスタムJSFコンバータは、Javaを使用してサーバー側で動作します。ADF FacesコンバータはJSFコンバータと同様に動作しますが、Javascriptを使用したクライアント側での変換と検証もサポートしています。
カスタムADF Facesコンバータを作成するには、変換用のビジネス・ロジックを作成し、カスタム・コンバータをアプリケーションに登録する必要があります。カスタムADF Facesコンバータを使用するには、f:converterタグを使用して、カスタムADF Facesコンバータをそのタグのプロパティとして設定します。または、入力コンポーネントのconverter属性を使用して、そのコンバータにバインドすることもできます。
ADF Facesコンバータは、サーバー側ではカスタムJSFコンバータと同様に実装されます。
javax.faces.converter.Converterインタフェースを実装するJavaクラスを作成します。Converterインタフェースを実装するには、実装にpublic no-argsコンストラクタ、属性に対するアクセッサ・メソッドのセットおよびgetAsObjectおよびgetAsStringメソッドを含める必要があります。
getAsObject()メソッドは、次の例のようにFacesContextインスタンス、UIコンポーネントおよび指定されたオブジェクトに変換されるString値を引数とします。
public Object getAsObject(FacesContext context,
UIComponent component,
java.lang.String value){
..
}
getAsString()メソッドは、FacesContextインスタンス、UIコンポーネントおよびString値に変換されるオブジェクトを引数とします。次に例を示します。
public String getAsString(FacesContext context,
UIComponent component,
Object value){
..
}
これらのクラスの詳細は、Javadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。
必要な変換ロジックを追加します。このロジックでは、javax.faces.convert.ConverterExceptionを使用して適切な例外をスローし、javax.faces.application.FacesMessageを使用して対応するエラー・メッセージを生成します。
ConverterインタフェースとFacesMessageエラー・ハンドラの詳細は、javax.faces.convert.ConverterExceptionおよびjavax.faces.application.FacesMessageのJavadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。
アプリケーションでクライアントに状態を保存する場合、カスタムADF FacesコンバータでSerializableインタフェースまたはStateHolderインタフェースと、StateHolderインタフェースのsaveState(FacesContext)およびrestoreState(FacesContext, Object)メソッドを実装する必要があります。詳細は、Javadocでjavax.faces.componentパッケージのStateHolderインタフェースを参照するか、http://docs.oracle.com/javaee/index.htmlを参照してください。
コンバータは、faces-config.xmlファイルに登録する必要があります。
faces-config.xmlファイルを開きます。
faces-config.xmlファイルは、JDeveloperの「アプリケーション」ウィンドウの、「View_Project」→WEB-INFノードにあります。
エディタ・ウィンドウで、「概要」タブをクリックします。
「コンバータ」を選択し、「追加」をクリックしてコンバータ情報を入力します。
「ヘルプ」をクリックするか、[F1]を押すと、コンバータの登録に関する追加のヘルプが表示されます。
ADFフレームワークでは、サーバーへのポストバックを最小限に抑えるために、クライアント側での変換と検証がサポートされています。クライアント側での実装は、通常はオプションです。クライアント側の実装を利用できない場合、フレームワークはJSFの場合と同様に、単にポストバック中にサーバー側のコンバータを呼び出します。
inputNumberSlider、inputNumberSpinboxおよびinputDateなどのように、ポストバックなしのクライアント相互作用をサポートする特定のコンポーネントとともにコンバータを使用する場合には、クライアント側の実装が必要です。あるコンポーネントにとってクライアント側のコンバータが必要かどうかを調べるには、そのコンポーネントのtagdocを参照します。
ADF Facesクライアント側コンバータは、クライアントでJavaScriptが使用されていることを除き、サーバー上の標準JSF変換と同じように動作します。JavaScriptコンバータ・オブジェクトはConverterException例外をスローでき、getAsObject()およびgetAsString()メソッドをサポートします。
例7-4に示すように、JavaScriptバージョンのコンバータを作成し、関連する情報をコンストラクタに渡します。
例7-4 コンバータ・インタフェース
function TrConverter()
{
}
/**
* Convert the specified model object value, into a String for display
* @param value Model object value to be converted
* @param label label to identify the editableValueHolder to the user
* @return the value as a string or undefined in case of no converter mechanism is
* available (see TrNumberConverter).
*/
TrConverter.prototype.getAsString = function(value, label){}
/**
* Convert the specified string value into a model data object
* which can be passed to validators
* @param value String value to be converted
* @param label label to identify the editableValueHolder to the user
* @return the converted value or undefined in case of no converter mechanism is
* available (see TrNumberConverter).
*/
TrConverter.prototype.getAsObject = function(value, label){}
エラーが発生した場合、クライアントはTrConverterException例外をスローしてTrFacesMessageエラー・メッセージを表示できます。
例7-5に、TrFacesMessageのシグネチャを示します。
例7-5 TrFacesMessageのシグネチャ
/**
* Message similar to javax.faces.application.FacesMessage
* @param summary - Localized summary message text
* @param detail - Localized detail message text
* @param severity - An optional severity for this message. Use constants
* SEVERITY_INFO, SEVERITY_WARN, SEVERITY_ERROR, and
* SEVERITY_FATAL from the FacesMessage class. Default is
* SEVERITY_INFO
*/
function TrFacesMessage(summary,detail,severity){
..
}
例7-6に、TrFacesExceptionのシグネチャを示します。
例7-6 TrFacesExceptionのシグネチャ
/**
* TrConverterException is an exception thrown by the getAsObject() or getAsString()
* method of a Converter, to indicate that the requested conversion cannot be performed.
* @param facesMessage the TrFacesMessage associated with this exception
* @param summary Localized summary message text, used to create only if facesMessage is null
* @param detail Localized detail message text, used only if facesMessage is null
*/
function TrConverterException(facesMessage, summary, detail){
..
}
サーバー側コンバータに変更を加えて、このクラスがクライアント側での変換をサポートすることを示すClientConverterインタフェースを実装します。インタフェース・メソッドの詳細は、http://myfaces.apache.orgにあるClientConverterのjavadocを参照してください。
例7-7に、社会保障番号用のカスタム・コンバータのJavaScript実装を示します。
例7-7 JavaScriptによるクライアント側カスタム・コンバータ
function ssnGetAsString(value)
{
return value.substring(0,3) + '-' +
value.substring(3,5) + '-' +
value.substring(5);
}
function ssnGetAsObject(value)
{
if (!value)
return (void 0);
var len=value.length;
var messageKey = SSNConverter.NOT;
if (len < 9 )
messageKey = SSNConverter.SHORT;
else if (len > 11)
messageKey = SSNConverter.LONG;
else if (len == 9)
{
if (!isNaN(value))
return value;
}
else if (len == 11 && value.charAt(3) == '-' && value.charAt(6) == '-')
{
var result = value.substring(0,3) +
value.substring(4,6) +
value.substring(7);
if (!isNaN(result))
return result;
}
if (messageKey!=void(0) && this._messages!=void(0))
return new ConverterException(this._messages[messageKey]);
return (void 0);
}
function SSNConverter(messages)
{
this._messages = messages;
}
SSNConverter.prototype = new Converter();
SSNConverter.prototype.getAsString = ssnGetAsString;
SSNConverter.prototype.getAsObject = ssnGetAsObject;
SSNConverter.SHORT = 'S';
SSNConverter.LONG = 'L';
SSNConverter.NOT = 'N';
例7-8に、社会保障番号用のサーバー側コンバータを実装するJavaクラスを示します。getAsObject()メソッドとgetAsString()メソッドでは、Javaコードの詳細が省略されています。
例7-8 Javaによるサーバー側カスタム・コンバータ
package oracle.adfdemo.view.faces.convertValidate;
import javax.faces.application.FacesMessage;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.convert.Converter;
import javax.faces.convert.ConverterException;
import oracle.adf.view.faces.converter.ClientConverter;
/**
* <p>Social Security number converter.</p>
*
*/
public class SSNConverter implements Converter, ClientConverter
{
public static final String CONVERTER_ID = "oracle.adfdemo.SSN";
public Object getAsObject(
FacesContext context,
UIComponent component,
String value)
{
// some Java code ...
}
public String getAsString(
FacesContext context,
UIComponent component,
Object value)
{
// some Java code ...
}
public String getClientConversion(
FacesContext context,
UIComponent component)
{
// in a real app the messages would be translated
return "new SSNConverter({" +
"S:'Value \"{0}\" in \"{1}\" is too short.'," +
"L:'Value \"{0}\" in \"{1}\" is too long.'," +
"N:'Value \"{0}\" in \"{1}\" " +
"is not a social security number.'})";
}
public String getClientScript(
FacesContext context,
UIComponent component)
{
// check if the script has already been returned this request
Object scriptReturned =
context.getExternalContext().getRequestMap().get(CONVERTER_ID);
// if scriptReturned is null the script hasn't been returned yet
if ( scriptReturned == null)
{
context.getExternalContext().getRequestMap().put(CONVERTER_ID,
Boolean.TRUE);
return _sSSNjs;
}
// if scriptReturned is not null, then script has already been returned,
// so don't return it again.
else
return null;
}
private static final String _sSSNjs =
"function ssnGetAsString(value)"+
"{return value.substring(0,3) + '-' " +
"+ value.substring(3,5) + '-' + value.substring(5);}" +
"function ssnGetAsObject(value)" +
"{if (!value)return (void 0);" +
"var len=value.length;"+
"var messageKey = SSNConverter.NOT;" +
"if (len < 9 )"+
"messageKey = SSNConverter.SHORT;" +
"else if (len > 11)"+
"messageKey = SSNConverter.LONG;" +
"else if (len == 9)" +
"{ if (!isNaN(value))" +
"return value;" +
"}" +
"else if (len == 11 && value.charAt(3) == '-' && " +
"value.charAt(6) == '-')" +
"{" +
"var result = value.substring(0,3) + value.substring(4,6) + " +
"value.substring(7);"+
"if (!isNaN(result))"+
"return result;" +
"}" +
"if (messageKey!=void(0) && this._messages!=void(0))" +
"return new ConverterException(this._messages[messageKey]);" +
"return void(0);}" +
"function SSNConverter(messages)" +
"{this._messages = messages;}" +
"SSNConverter.prototype = new Converter();" +
"SSNConverter.prototype.getAsString = ssnGetAsString;" +
"SSNConverter.prototype.getAsObject = ssnGetAsObject;" +
"SSNConverter.SHORT = 'S';" +
"SSNConverter.LONG = 'L';" +
"SSNConverter.NOT = 'N';";
}
カスタムADF Facesコンバータがアプリケーションで特定のデータ型のクラスの下に登録されると、カスタム・コンバータ・オブジェクトと同じ型の値バインディングがコンポーネント値で参照されるたびに、JSFでそのクラスのコンバータが値の変換に自動的に使用されます。この場合、次のコードに示すように、converter属性を使用してカスタム・コンバータをコンポーネントに登録する必要はありません。
<af:inputText value="#{myBean.myProperty}"/>
myPropertyのデータ型は、カスタム・コンバータと同じ型です。かわりに、コンバータ・クラスを入力コンポーネントのconverter属性にバインドすることもできます。
ユーザーがフィールド内のデータを編集または入力してフォームを送信したときに、設定した規則および条件に対してデータが検証されるように、検証を追加できます。検証に失敗すると、アプリケーションでエラー・メッセージが表示されます。たとえば、図7-3では、af:validateDateTimeRangeコンポーネントによってユーザー入力に対する特定の日付範囲がメッセージ・ヒントに設定されており、無効な値が入力されると、メッセージ・ポップアップ・ウィンドウにエラー・メッセージが表示されます。
クライアント側の検証が必要な場合、ビュー・レイヤーでADF Facesの検証を使用します。ADF Facesに用意されているすべてのバリデータは、クライアント側ピアを持ちます。多くのコンポーネントは、検証を提供する属性を持ちます。詳細は、7.5.1.2項「検証属性の使用」を参照してください。また、ADF Facesは、クライアントとサーバーの両方で実行できる独立した検証クラスを提供します。詳細は、7.5.1.3項「ADF Facesバリデータの使用」を参照してください。独自のバリデータも作成できます。カスタム・バリデータの詳細は、7.6.3項「カスタムJSFバリデータの作成方法」を参照してください。
デフォルトでは、ADF Facesの構文およびセマンティク検証は、クライアント側とサーバー側の両方で行われます。クライアント側の検証では、バリデータでデータを捕捉および表示し、サーバーへのラウンドトリップは不要です。
ADF Facesでは、次のタイプの検証が提供されます。
UIコンポーネント属性: ADF Faces入力コンポーネントには、データの検証に使用できる属性が備わっています。たとえば、値が必須かどうかを指定するには、ADF Facesの入力コンポーネントのrequired属性を使用して簡単な検証を指定できます。required属性をtrueに設定した場合、コンポーネントは値を持つ必要があります。コンポーネントが値を持たない場合、アプリケーションによりエラー・メッセージが表示されます。詳細は、7.5.1.2項「検証属性の使用」を参照してください。
デフォルトADF Facesバリデータ: JSFフレームワークで提供されるバリデータには、日付範囲の検証、入力されたデータの長さの検証などのよく使用される検証チェックが用意されています。詳細は、7.5.1.3項「ADF Facesバリデータの使用」を参照してください。
カスタムのADF Facesバリデータ: 独自のバリデータを作成して、UIコンポーネントに対して使用するように選択できます。詳細は、7.6項「カスタムJSF検証の作成」を参照してください。
検証が追加されると、検証エラーをページにインラインで、またはポップアップ・ウィンドウに表示できるようになります。検証エラーで作成されたメッセージの表示の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。
多くのADF FacesのUIコンポーネントには、簡単な検証を提供する属性が備わっています。たとえば、af:inputDateコンポーネントには、日付値に使用できる最大値と最小値を指定するmaxValue属性とminValue属性があります。
UIコンポーネントのヘルプを参照するには、「プロパティ」ウィンドウで属性の名前を右クリックし、「ヘルプ」を選択します。
ADF Facesバリデータは、サーバーまたはクライアントで実行できる個別のクラスです。表7-2に、バリデータとそのロジックを示します。
表7-2 ADF Facesのバリデータ
| バリデータ | タグ名 | 説明 |
|---|---|---|
|
|
|
エンコード時に文字列のバイト数が検証されます。 |
|
|
|
入力された日付が、指定された制限に対し有効かどうかが検証されます。 |
|
|
|
入力された日付が、指定された範囲内かどうかが検証されます。範囲はバリデータの属性として指定します。 |
|
|
|
コンポーネント値が指定された範囲内にあるかが検証されます。値は浮動小数点型に変換可能である必要があります。 |
|
|
|
コンポーネントの長さが指定された範囲内にあるかが検証されます。値は |
|
|
|
コンポーネント値が指定された範囲内にあるかが検証されます。値は数値型か、 |
|
|
|
Java正規表現構文を使用するデータを検証します。 |
|
注意: コンポーネントにカスタム・バリデータを登録する場合、標準JSFの |
ADF Facesバリデータを追加する手順:
「構造」ウィンドウで、バリデータを追加するコンポーネントを右クリックして「componentの中に挿入」を選択し、ADF Facesバリデータを挿入するために「ADF Faces」を選択します。
「JSF」→「バリデータ」を選択してJSF参照実装バリデータを挿入することもできます。
バリデータ・タグ(「日付時間範囲の検証」など)を選択し、「OK」をクリックします。
JSFページでコンポーネントを選択し、「プロパティ」ウィンドウで、検証エラー用のメッセージなどの値を属性に設定します。
ヘルプを参照するには、属性を右クリックし、「ヘルプ」を選択します。
ADF Facesでは、検証エラー・メッセージの詳細部分をカスタマイズできます。MessageDetailxyz属性(xyzはMessageDetailmaximumなどの検証エラー・タイプ)に値を設定することにより、検証に失敗した場合、デフォルト・メッセージのかわりに、ADF Facesでカスタム・メッセージが表示されます。
ユーザーがページを送信すると、ADF Facesで送信された値を確認し、null以外の値に対して変換を実行します。変換された値は、validate()メソッドに渡されます。値が空の場合、コンポーネントのrequired属性が確認され、指定されている場合はエラー・メッセージが生成されます。送信された値がnull以外の場合、検証プロセスが続けられ、コンポーネントのすべてのバリデータが宣言順にコールされます。
|
注意: ADF Facesでは、クライアント側サポートのある、JSFバリデータの拡張が提供されます。 |
ADF Faces検証が検証の処理フェーズで実行されます。エラーが発生した場合、コンポーネントが無効化され、関連付けられているメッセージがFacesContextインスタンスのキューに追加されます。モデルの更新フェーズは、変換または検証にエラーがない場合にのみ発生します。コンポーネントのすべての検証が終了すると、モデル・レイヤーに制御が移り、モデルの更新の検証フェーズが実行されます。検証の処理フェーズ同様、エラーが発生した場合、コンポーネントが無効化され、関連付けられているメッセージがFacesContextインスタンスのキューに追加されます。
ライフサイクルはレスポンスのレンダリング・フェーズに移り、現在のページが再表示されます。コンポーネントがエラーを生成した場合、ADF Facesはエラーを自動的にハイライト表示します。たとえば、ADF Facesは、検証エラーがある場合に図7-4に示すようにinputTextコンポーネントの周囲に赤いボックスをレンダリングします。
検証または変換エラーの発生時のエラー・メッセージの追加の詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。
UIコンポーネントには、バリデータを設定しないことも、複数設定することもできます。コンポーネントのrequired属性を設定し、バリデータを使用することができます。ただし、required属性をtrueに設定し、値がnullまたは長さがゼロの文字列の場合、コンポーネントは無効化され、コンポーネントに登録された他のバリデータはコールされません。
コンポーネントが空でも有効になるケースが存在する場合は、この組合せでは問題があることがあります。たとえば、ページに「Cancel」ボタンが含まれている場合、ユーザーはデータを入力しなくても、そのボタンをクリックすればページを閉じることができるようにする必要があります。このようなケースを処理するには、「Cancel」ボタンのコンポーネントのimmediate属性をtrueに設定します。この属性により、リクエスト値の適用フェーズ中にアクションを実行できます。次に、デフォルトのJSFアクション・リスナーはFacesContext.renderResponse()をコールして、アクション実行時に検証をバイパスします。詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。
ビジネス・ニーズに合せて独自の検証ロジックを追加できます。1つのページのコンポーネントにカスタム検証ロジックが必要な場合、ページのバッキングBeanに検証メソッドを作成します。
アプリケーション内の様々なページで再利用されるロジックを作成する場合、またはクライアント側で検証を実行できるようにする場合は、JSFバリデータ・クラスを作成します。その後、クライアント側でバリデータを実行できるADF Faces版を作成します。
1つのページのコンポーネントにカスタム検証が必要な場合、必要な検証を提供するメソッドをバッキングBeanに作成します。
始める前に:
カスタムJSF検証に関する知識が役立つ場合があります。詳細は、7.6項「カスタムJSF検証の作成」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、7.1.2項「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。
バッキングBeanの検証メソッドを追加する手順:
検証の必要なコンポーネントをJSFページに挿入します。
ビジュアル・エディタで、コンポーネントをダブルクリックします。
「バインド「バリデータ」プロパティ」ダイアログで検証メソッドを含めるマネージドBeanを入力または選択し、「新規」をクリックして新規のマネージドBeanを作成します。提供されているデフォルト・メソッド・シグネチャを使用するか、ロジックがすでにある場合は既存のメソッドを選択します。
ダイアログで「OK」をクリックすると、JDeveloperでスケルトン・メソッドをコードに追加し、ソース・エディタにBeanを開きます。
必要な検証ロジックを追加します。このロジックでは、javax.faces.validator.ValidatorException例外を使用して適切な例外をスローし、javax.faces.application.FacesMessageエラー・メッセージを使用して対応するエラー・メッセージを生成します。
ValidatorインタフェースとFacesMessageの詳細は、javax.faces.validator.ValidatorExceptionおよびjavax.faces.application.FacesMessageのJavadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。
検証メソッドを作成すると、選択したマネージドBeanにJDeveloperでスケルトン・メソッドが追加されます。例7-9に、JDeveloperにより生成されるコードを示します。
例7-9 検証メソッドのマネージドBeanコード
public void inputText_validator(FacesContext facesContext,
UIComponent uiComponent, Object object) {
// Add event code here...
}
入力コンポーネントを含むフォームが送信されると、validator属性がバインドされているメソッドが実行されます。
カスタム・バリデータを作成するには、インタフェースのValidator実装を作成してから、アプリケーションにカスタム・バリデータを登録することで、検証のビジネス・ロジックを作成する必要があります。バリデータのタグを作成するか、f:validatorタグを使用してカスタム・バリデータをそのタグの属性とすることもできます。
さらに、バリデータのクライアント側バージョンを作成できます。ADF Facesクライアント側検証は、クライアントでJavaScriptが使用されることを除き、サーバー上の標準検証と同じように動作します。JavaScriptバリデータ・オブジェクトはValidatorExceptions例外をスローでき、validate()メソッドをサポートします。
始める前に:
カスタムJSF検証に関する知識が役立つ場合があります。詳細は、7.6項「カスタムJSF検証の作成」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、7.1.2項「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。
カスタムJSFバリデータを作成する手順:
javax.faces.validator.Validatorインタフェースを実装するJavaクラスを作成します。Validatorインタフェースを実装するには、実装にpublic no-argsコンストラクタ、属性に対するアクセッサ・メソッドのセットおよびvalidateメソッドを含める必要があります。
public void validate(FacesContext facesContext,
UIComponent uiComponent,
Object object)
throws ValidatorException {
..
}
これらのクラスの詳細は、Javadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。
必要な検証ロジックを追加します。このロジックでは、javax.faces.validate.ValidatorException例外を使用して適切な例外をスローし、javax.faces.application.FacesMessageエラー・メッセージを使用して対応するエラー・メッセージを生成します。
ValidatorインタフェースとFacesMessageの詳細は、javax.faces.validator.ValidatorExceptionおよびjavax.faces.application.FacesMessageのJavadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。
アプリケーションでクライアントに状態を保存する場合、カスタム・バリデータでSerializableインタフェースまたはStateHolderインタフェースと、StateHolderインタフェースのsaveState(FacesContext)およびrestoreState(FacesContext, Object)メソッドを実装する必要があります。
詳細は、Javadocでjavax.faces.componentパッケージのStateHolderインタフェースを参照してください。
バリデータをfaces-config.xmlファイルに登録します。
faces-config.xmlファイルを開きます。
faces-config.xmlファイルは、JDeveloperの「アプリケーション」ウィンドウの、「View_Project」→WEB-INFノードにあります。
エディタ・ウィンドウで、「概要」タブをクリックします。
「バリデータ」を選択し、「追加」をクリックしてバリデータ情報を入力します。
「ヘルプ」をクリックするか、[F1]を押すと、バリデータの登録に関する追加のヘルプが表示されます。
バリデータのクライアント版を作成する手順:
JavaScript版のバリデータを記述し、関連する情報をコンストラクタに渡します。
2つのメソッドを持つorg.apache.myfaces.trinidad.validator.ClientValidatorインタフェースを実装します。1つ目のメソッドはgetClientScript()で、JavaScriptのValidatorオブジェクトの実装を返します。2つ目のメソッドはgetClientValidation()で、バリデータ・インスタンスのインスタンス化に使用されるJavaScriptコンストラクタを返します。
例7-10に、Javaのバリデータを示します。
例7-10 Javaバリデータ
public String getClientValidation(
FacesContext context,
UIComponent component)
{
return ("new SSNValidator('Invalid social security number.','Value \"{1}\"
must start with \"123\".')");
}
Javaバリデータは、例7-11に示すJavaScriptバリデータをコールします。
JSFページでカスタム・バリデータを使用する手順:
JSFページにタグを持つカスタム・バリデータを使用するには、これをコンポーネントのタグ内に手動でネストさせる必要があります。
例7-12に、inputTextコンポーネント内にネストするカスタム・バリデータ・タグを示します。faces-config.xmlファイル内に宣言されていたバリデータのプロパティの値を提供するためにタグ属性が使用されていることに注意してください。
例7-12 JSFページ上のカスタム・バリデータ・タグ
<h:inputText id="empnumber" required="true"> <hdemo:emValidator emPatterns="9999|9 9 9 9|9-9-9-9" /> </h:inputText>
カスタム・タグを使用せずにカスタム・バリデータを使用する手順:
カスタム・タグを使用せずにカスタム・バリデータを使用するには、f:validatorタグ内にバリデータのIDをネスト(faces-config.xmlファイルで構成されているとおりに)させる必要があります。バリデータのID属性は、使用するバリデータをアプリケーションが動的に決定できるEL式をサポートします。
「構造」ウィンドウから、検証を追加する入力コンポーネントを右クリックし、「componentの中に挿入」→「JSF」→「バリデータ」を選択します。
入力コンポーネントが選択された状態で、「プロパティ」ウィンドウでドロップダウン・リストからバリデータのIDを選択し、「OK」をクリックします。
バリデータのIDをf:validatorタグのプロパティにするコードが、JDeveloperでJSFページに挿入されます。
例7-13に、f:validatorタグを使用するバリデータのJSFページでのコードを示します。
