7 入力の検証および変換
この章の内容は次のとおりです。
ADF Facesの変換および検証について
ADF Facesには、ユーザー指定のデータを変換および検証してデータの整合性を保証する機能があります。ADFフォーム上の値をアプリケーションで許可されるタイプに変換するにはコンバータを使用し、入力コンポーネントに対する検証を実行するにはバリデータを使用します。
ADF Facesの入力コンポーネントでは、変換機能がサポートされます。Webアプリケーションで、int、long、dateなどの様々な型をモデル・レイヤーに格納できます。ただし、クライアント・ブラウザで表示されるとき、ユーザー・インタフェースには、ユーザーが読取りまたは変更できるような形式でデータが表示される必要があります。たとえば、フォームの日付フィールドでは、java.util.Dateオブジェクトをmm/dd/yyyy形式のテキスト文字列で表します。ユーザーが「date」フィールドを編集してフォームを送信した場合、文字列は、アプリケーションで要求されるタイプに変換される必要があります。変換後のデータは、規則および条件に対して検証されます。逆に、String以外の型として格納したデータを表示および更新用にStringに変換することもできます。af:inputDateなどの多くのコンポーネントで、変換機能が自動的に提供されます。
ADF Facesの入力コンポーネントでは、検証機能もサポートされます。1つ以上のバリデータ・タグをコンポーネントに追加できます。また、ビジネス・ニーズに応じてカスタム・バリデータを作成することもできます。
バリデータとコンバータには、ユーザーが関連付けられているフィールドをクリックすると表示されるデフォルトのヒント・メッセージがあります。コンバータの場合、ヒントは、通常、入力値に使用する、指定されたパターンに基づいた適切な形式をユーザーに示します。バリデータの場合、ヒントを使用して、コンポーネントに構成されている検証に基づいた有効な値が示されます。変換または検証に失敗すると、関連付けられたエラー・メッセージがユーザーに表示されます。これらのメッセージはダイアログに表示することも、変換または検証に失敗したコンポーネントと並べてページ自体に表示することもできます。ADF Facesアプリケーションでのメッセージの表示の詳細は、「ヒント、メッセージおよびヘルプの表示」を参照してください。
ADF Facesコンバータは、標準JSFコンバータを拡張するコンバータのセットです。入力コンポーネントのADF Facesコンバータはクライアント側で動作するため、変換のエラーはクライアントで捕捉され、サーバーへのラウンドトリップが回避されます。ADF Facesコンバータは、入力コンポーネントに簡単にドラッグ・アンド・ドロップできます。
ADF Facesバリデータは、標準JSFバリデータも補強します。ADF Facesバリデータは、クライアント側とサーバー側の両方で動作できます。クライアント側バリデータはJavaScriptで記述され、クライアント側で捕捉された検証エラーはサーバーとの間をラウンドトリップしなくても処理できます。
ADF Facesコンバータおよびバリデータのユースケースと例
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コンバータおよびバリデータの追加機能
コンバータおよびバリデータを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。次に、役に立つ可能性のある他のセクションへのリンクを示します。
-
JSFライフサイクルでの変換と検証の動作の詳細は、「ADF FacesでのJSFライフサイクルの使用」を参照してください。
-
ADF Facesでは、デフォルトのメッセージのかわりに変換エラー・メッセージの詳細部分をカスタマイズできます。メッセージの作成の詳細は、「ヒント、メッセージおよびヘルプの表示」を参照してください。
-
文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。「ページの国際化およびローカライズ」を参照してください。
変換、検証とJSFライフサイクル
ADF Facesでサポートされる変換と検証の機能は、基本的にJSFライフサイクルの別々のフェーズで実行されます。JSFライフサイクルで変換と検証が実行されるフェーズと、変換および検証が失敗したときの動作について説明します。
データを持つフォームが送信されると、編集可能なvalue属性がバインドされているUIコンポーネントごとに、リクエスト値がブラウザからサーバーに送信されます。リクエスト値は、JSFのリクエスト値の適用フェーズでデコードされ、デコードされた値はコンポーネントのsubmittedValue属性にローカルに保存されます。値に変換が必要な場合(Stringとして表示されるが、java.util.Dateオブジェクトとして格納されている場合など)、データは、UIコンポーネントごとに検証の処理フェーズで正しい型に変換されます。
検証または変換に失敗した場合、ライフサイクルはレスポンスのレンダリング・フェーズに進み、対応するエラー・メッセージがページに表示されます。変換および検証が正常に終了すると、モデルの更新フェーズが開始され、変換および検証された値がモデルの更新に使用されます。
検証または変換エラーが起きた場合、検証または変換に失敗したコンポーネントで、関連付けられたエラー・メッセージがキューに置かれ、コンポーネント自身は無効とされます。その後、現在のページがエラー・メッセージを使用して再表示されます。ADF Facesのコンポーネントには、これらのメッセージを宣言的に設定する方法が用意されています。
JSFライフサイクルでの変換と検証の動作の詳細は、「ADF FacesでのJSFライフサイクルの使用」を参照してください。
変換の追加
ADF Facesコンバータは、入力コンポーネントからモデルで要求される形式に入力を変換する際に使用します。UIコンポーネントにコンバータを自動的に挿入するJDeveloperを使用するか、手動でUIコンポーネントにコンバータを挿入します。
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コンポーネントにコンバータを手動で挿入できます。
始める前に:
コンバータに関する知識が役立つ場合があります。「変換の追加」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。
タグを持つADF Facesコンバータを追加する手順:
複数のコンバータ・パターンを指定する方法
一部のコンバータでは、複数のコンバータ・パターンがサポートされます。パターンでは、変換で受け入れられるデータの形式を指定します。複数のパターンが複数の形式に対応します。たとえば、ユーザーは、スラッシュ(/)またはハイフン(-)をセパレータとして使用して日付を入力できます。すべてのコンバータが複数のパターンをサポートするわけではありませんが、パターン一致は柔軟であり、複数のパターンが必要ではない場合もあります。
次の例に、af:convertColorタグに対する複数パターンの使用を示します。「255-255-000」と「FFFF00」の両方の値が使用可能です。
<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>
次の例に、「6/9/2007」と「2007/9/6」の両方が使用可能な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>
次の例に、type属性がcurrencyに設定されており、$78.57と$078.57を変換の値として使用できるaf:convertNumberタグを示します。
<af:inputText label="type=currency" value="#{validate.currency}" id="it1">
<af:convertNumber type="currency"/>
</af:inputText>
コンバータに負数を指定する方法
負数は、財務アプリケーションで使用され、指定された接頭辞および接尾辞文字を使用して負の値を書式化することによりnegativePrefixおよびnegativeSuffix属性でaf:convertNumberタグを使用したクライアント側の変換での属性レベルをサポートしています。たとえば、財務アプリケーションでは、負数をカッコを使用して書式化することがよくあります。この場合、(99.00)は99.00の負の値を表します。
これらの属性は、#;(#)のような、数値コンバータでコンバータ・パターンを指定するのと同じことを実行します。パターンの";"に続く文字は、負のパターンを表し、式の開きカッコおよび閉じカッコはそれぞれ負数の接頭辞および接尾辞を表します。しかし、コンバータ・パターンはクライアント側では処理されず、出力を書式化するにはサーバーのラウンドトリップが必要です。
af:convertNumberタグを使用すれば、変換を実行するサーバーのラウンドトリップは必要なくなります。このクライアント側での変換では、任意の負の接頭辞/接尾辞をコンバータ・パターンを使用してオーバーライドします。
次の例に、negativePrefixおよびnegativeSuffix属性が"("および")"に設定されており、それぞれユーザーが入力する"-99.00"などの値を受け入れ、"(99.00)"に変換する、af:convertNumberタグを示します。この設定では、ユーザーがテキスト入力からタブで移動するとすぐに、変換がクライアントで処理されます。
<af:inputText label="type=number" id="it3">
<af:convertNumber negativePrefix="(" negativeSuffix=")" type="number"/>
</af:inputText>
実行時の処理: コンバータの機能の仕方
ユーザーがコンバータを含むページを送信すると、ADF Facesのvalidate()メソッドでコンバータのgetAsObject()メソッドがコールされ、String値が必要なオブジェクト・タイプに変換されます。アタッチされているコンバータがなく、コンポーネントがモデルのBeanプロパティにバインドされている場合、ADFでモデルのデータ型を確認して適切なコンバータを見つけます。変換に失敗すると、コンポーネントのvalid属性がfalseに設定され、JSFでFacesContextによってメンテナンスされているキューにエラー・メッセージが追加されます。変換が正常終了し、コンポーネントにアタッチされているバリデータがある場合、変換された値がバリデータに渡されます。コンポーネントにアタッチされているバリデータがない場合、変換された値はローカル値として格納され、モデルの更新に後で使用されます。
数値コンバータに関する必知事項
af:convertNumberは、サーバー側またはクライアント側の変換のどちらかをサポートします。コンバータは、数字の書式設定、解析および変換をまずブラウザ内で直接実行してみることにより、入力数値の書式設定のためにサーバーへの往復処理を実行しないようにしています。しかし、次の場合には、クライアント変換がスキップされます。
-
pattern属性が指定されている場合。コンバータはサーバーのみで実行されます。 -
入力文字列が、JavaScriptの数値でサポートされる最大精度である15桁を超える場合。コンバータはサーバーのみで実行されます。
af:convertNumberでmaxFractionDigitsによって指定されるよりも多くの小数の桁数がある入力値を表示する場合、デフォルトで、JavaのHALF_EVENメソッドを使用して値を四捨五入します。
af:convertNumberでHALF_EVEN(HALF_UPまたはFLOORなど)以外のメソッドを使用する場合、次のヒントに従います。
-
af:convertNumberの特定のインスタンスを構成するには、roundingMode属性を必要な値に設定します。次に例を示します。
<af:convertNumber roundingMode="FLOOR" ... />
-
アプリケーションで、
af:convertNumberのすべてのインスタンスを構成するには、trinidad-config.xmlにrounding-mode属性を追加し、適切にこれを設定します。次に例を示します。
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config"> ... <rounding-mode>FLOOR</rounding-mode> </trinidad-config>
roundingModeの値はJavaのRoundingModeによってサポートされている必要があります。値は、.jspxまたは構成ファイルの文字列として、あるいはRoundingModeタイプ値を返すメソッドにバインドされたEL式として、指定できます。
注意:
roundingModeがhalf-upに設定されていないかぎり、クライアント側で入力値を丸めることはできません。roundingModeがhalf-upに設定されている場合、サーバー側で実際の丸めを実行する後続のポストバックのために、入力値はクライアント側では変更されないままになります。
RoundingModeの詳細は、Java APIのドキュメントを参照してください。
日時コンバータに関する必知事項
日付コンバータでは、あいまいにならないように、4桁の年のパターンを使用する必要があります。パターンとして2桁の年の書式を使用すると、4桁の年の値がすべて2桁の年の値として表示されます。たとえば、パターンとして2桁の年の書式(MM-dd-yyなど)を使用している場合、日付値03-01-1910と03-01-2010は入力フィールドに03-01-10と表示されるので、サーバーに正しい年の値が格納されても、正確に解釈されないおそれがあります。
図7-1は、inputDateコンポーネントに表示されている日付値と、その下にあってサーバーに保存されている元の値を表示するoutputTextコンポーネントを示しています。
図7-1 年の書式が2桁の日付コンバータ
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要素とその構成方法の詳細は、「trinidad-config.xmlの要素に関する必知事項」を参照してください。
注意:
2桁の年の書式を使用している間は、ユーザーが既存の値を編集しても、2桁の年はtwo-digit-year-startによって決定される範囲内の年になります。
たとえば、two-digit-year-startが1950 (年の値は1950年から2050年の範囲で解決される)で、inputDateコンポーネントの値が03/01/1776 (03/01/76と表示される)であるとします。ユーザーがこの値を03/01/77に変更すると、新しい日付は期待する03/01/1777ではなく、03/01/1977になります。
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プレースホルダが含まれているケースと含まれていないケースを示します。
図7-2 af:convertDateTimeでのAM/PMプレースホルダの使用
convertDateTimeパターンにタイムゾーン・プレースホルダ(z)を含めてタイムゾーン情報を表示する場合は(たとえばyyyy-MM-dd hh:mm:ss a zのように)、トリニダードのconvertDateTimeがタイムゾーン名の表示より優先される点に注意してください。コンバータをinputTextまたはoutputTextとともに使用すると、タイムゾーンはGMT + xという形式で表示されます。inputDateとともに使用すると、「(UTC-08:00) ロサンゼルス - 太平洋標準時(PT)」などの事前構成済の表示値の選択肢を使用してタイムゾーンが表示されます。
カスタムADF Facesコンバータの作成
特定のビジネス・ニーズに合せて、独自のコンバータを作成できます。カスタムADF Facesのサーバー側コンバータまたはクライアント側のコンバータを作成する際には、別々の手順があります。
カスタムJSFコンバータは、Javaを使用してサーバー側で動作します。ADF FacesコンバータはJSFコンバータと同様に動作しますが、Javascriptを使用したクライアント側での変換と検証もサポートしています。
カスタムADF Facesコンバータの作成方法
カスタムADF Facesコンバータを作成するには、変換用のビジネス・ロジックを作成し、カスタム・コンバータをアプリケーションに登録する必要があります。カスタムADF Facesコンバータを使用するには、f:converterタグを使用して、カスタムADF Facesコンバータをそのタグのプロパティとして設定します。または、入力コンポーネントのconverter属性を使用して、そのコンバータにバインドすることもできます。
サーバー側のコンバータを作成するには、次を実行する必要があります。
ADFフレームワークでは、サーバーへのポストバックを最小限に抑えるために、クライアント側での変換と検証がサポートされています。クライアント側での実装は、通常はオプションです。クライアント側の実装を利用できない場合、フレームワークはJSFの場合と同様に、単にポストバック中にサーバー側のコンバータを呼び出します。
inputNumberSlider、inputNumberSpinboxおよびinputDateなどのように、ポストバックなしのクライアント相互作用をサポートする特定のコンポーネントとともにコンバータを使用する場合には、クライアント側の実装が必要です。あるコンポーネントにとってクライアント側のコンバータが必要かどうかを調べるには、そのコンポーネントのtagdocを参照します。
ADF Facesクライアント側コンバータは、クライアントでJavaScriptが使用されていることを除き、サーバー上の標準JSF変換と同じように動作します。JavaScriptコンバータ・オブジェクトはConverterException例外をスローでき、getAsObject()およびgetAsString()メソッドをサポートします。
クライアント側のコンバータを作成するには、次を実行する必要があります。
サーバー側(Java)での変換の実装
ADF Facesコンバータは、サーバー側ではカスタムJSFコンバータと同様に実装されます。
アプリケーションでクライアントに状態を保存する場合、カスタムADF FacesコンバータでSerializableインタフェースまたはStateHolderインタフェースと、StateHolderインタフェースのsaveState(FacesContext)およびrestoreState(FacesContext, Object)メソッドを実装する必要があります。Javadocでjavax.faces.componentパッケージのStateHolderインタフェースを参照するか、http://docs.oracle.com/javaee/index.htmlを参照してください。
ADF Facesコンバータのfaces-config.xmlファイルへの登録
コンバータは、faces-config.xmlファイルに登録する必要があります。
「ヘルプ」をクリックするか、[F1]を押すと、コンバータの登録に関する追加のヘルプが表示されます。
クライアント側バージョンのコンバータの作成
次の例に示すように、JavaScriptバージョンのコンバータを作成し、関連する情報をコンストラクタに渡します。
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エラー・メッセージを表示できます。
次の例に、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){
..
}
次の例に、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を参照してください。
次の例に、社会保障番号用のカスタム・コンバータの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';
次の例に、社会保障番号用のサーバー側コンバータを実装するJavaクラスを示します。getAsObject()メソッドとgetAsString()メソッドでは、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';";
}JSFページでのカスタムADF Facesコンバータの使用
カスタムADF Facesコンバータがアプリケーションで特定のデータ型のクラスの下に登録されると、カスタム・コンバータ・オブジェクトと同じ型の値バインディングがコンポーネント値で参照されるたびに、JSFでそのクラスのコンバータが値の変換に自動的に使用されます。この場合、次のコードに示すように、converter属性を使用してカスタム・コンバータをコンポーネントに登録する必要はありません。
<af:inputText value="#{myBean.myProperty}"/>
myPropertyのデータ型は、カスタム・コンバータと同じ型です。かわりに、コンバータ・クラスを入力コンポーネントのconverter属性にバインドすることもできます。
カスタムADF Facesコンバータに関する必知事項
表またはチャートの値の書式設定を定義すると、その値の書式設定は非アクティブ・イベントにのみ適用され、ADSイベントには適用されません。応答データのフォーマット設定を担当するコンバータは、ADS応答では機能しません。ADSデータをフォーマットするために、oracle.adf.view.rich.ads.USE_COMPONENT_FORMATTERパラメータをweb.xmlファイルで使用できます。このパラメータには、次の値を設定できます。
-
NEVER: コンポーネント・コンバータを使用しないようにするには、このオプションを適用します。
-
IF_MODEL_DID_NOT_FORMAT: 新しい値とアクティブ・モデルのフォーマットされた値が同じ場合にのみコンポーネント・コンバータを使用するには、このオプションを適用します。
-
ALWAYS:
formatterFactoryを実装し、null以外のフォーマットされた値を返す場合にコンポーネント・コンバータを使用するには、このオプションを適用します。
クライアント側のみのコンバータ・スクリプトを宣言によって登録する方法
af:clientConverterタグは、クライアント側のみのカスタム・コンバータ・スクリプトを登録するための宣言の代替方法をUI開発者に提供します。事前にプログラミングされたメソッドの使用も引き続き許可されます。
protected属性によって識別されます。 af:clientConverterタグは、保護されたデータをフォーマットしても安全であるページのレンダリングの時点までデータ・フォーマットの要件を遅延する必要がある状況で役に立ちます。
getAsString属性およびgetAsObject属性を使用して、インラインのJavaScriptの式を受け入れます。タグではかわりにJavaScriptのメソッドを呼び出すためのgetAsStringMethod属性およびgetAsObjectMethod属性も提供されています。
af:clientConverterタグを使用するには:
検証の追加
ADF Facesの入力コンポーネントでは、検証機能がサポートされます。UIコンポーネント属性、デフォルトADF Facesバリデータ、カスタムADF Facesバリデータを使用すると、入力コンポーネントの検証を追加できます。
ユーザーがフィールド内のデータを編集または入力してフォームを送信したときに、設定した規則および条件に対してデータが検証されるように、検証を追加できます。検証が失敗すると、アプリケーションによりエラー・メッセージが表示されます。たとえば、図7-3では、af:validateDateTimeRangeコンポーネントによってユーザー入力に対する特定の日付範囲がメッセージ・ヒントに設定されており、無効な値が入力されると、メッセージ・ポップアップ・ウィンドウにエラー・メッセージが表示されます。
図7-3 エラー・メッセージ付き日付範囲バリデータ
クライアント側の検証が必要な場合、ビュー・レイヤーでADF Facesの検証を使用します。ADF Facesに用意されているすべてのバリデータは、クライアント側ピアを持ちます。多くのコンポーネントは、検証を提供する属性を持ちます。「検証属性の使用」を参照してください。さらに、ADF Facesには、クライアント側とサーバー側のどちらでも実行できる個別の検証クラスが用意されています。詳細は、「ADF Facesバリデータの使用」を参照してください。また、独自のバリデータを作成することもできます。カスタム・バリデータの詳細は、「カスタムJSFバリデータの作成方法」を参照してください。
検証の追加方法
デフォルトでは、ADF Facesの構文およびセマンティク検証は、クライアント側とサーバー側の両方で行われます。クライアント側の検証では、バリデータでデータを捕捉および表示し、サーバーへのラウンドトリップは不要です。
ADF Facesでは、次のタイプの検証が提供されます。
-
UIコンポーネント属性: ADF Faces入力コンポーネントには、データの検証に使用できる属性が備わっています。たとえば、値が必須かどうかを指定するには、ADF Facesの入力コンポーネントの
required属性を使用して簡単な検証を指定できます。required属性をtrueに設定した場合、コンポーネントは値を持つ必要があります。そうでない場合、アプリケーションによりエラー・メッセージが表示されます。「検証属性の使用」を参照してください。 -
デフォルトADF Facesバリデータ: JSFフレームワークで提供されるバリデータには、日付範囲の検証、入力されたデータの長さの検証などのよく使用される検証チェックが用意されています。「ADF Facesバリデータの使用」を参照してください。
-
カスタムのADF Facesバリデータ: 独自のバリデータを作成して、UIコンポーネントに対して使用するように選択できます。「カスタムJSF検証の作成」を参照してください。
検証が追加されると、検証エラーをページにインラインで、またはポップアップ・ウィンドウに表示できるようになります。検証エラーで作成されたメッセージの表示の詳細は、「ヒント、メッセージおよびヘルプの表示」を参照してください。
検証属性の使用
多くのADF FacesのUIコンポーネントには、簡単な検証を提供する属性が備わっています。たとえば、af:inputDateコンポーネントには、日付値に使用できる最大値と最小値を指定するmaxValue属性とminValue属性があります。
UIコンポーネントのヘルプを参照するには、「プロパティ」ウィンドウで属性の名前を右クリックし、「ヘルプ」を選択します。
ADF Facesバリデータの使用
ADF Facesバリデータは、サーバーまたはクライアントで実行できる個別のクラスです。表7-2に、バリデータとそのロジックを示します。
表7-2 ADF Facesのバリデータ
| バリデータ | タグ名 | 説明 |
|---|---|---|
|
|
|
エンコード時に文字列のバイト数が検証されます。 |
|
|
|
入力された日付が、指定された制限に対し有効かどうかが検証されます。 |
|
|
|
入力された日付が、指定された範囲内かどうかが検証されます。範囲はバリデータの属性として指定します。 |
|
|
|
コンポーネント値が指定された範囲内にあるかが検証されます。値は浮動小数点型に変換可能である必要があります。 |
|
|
|
コンポーネントの長さが指定された範囲内にあるかが検証されます。値は |
|
|
|
コンポーネント値が指定された範囲内にあるかが検証されます。値は数値型か、 |
|
|
|
Java正規表現構文を使用するデータを検証します。 |
注意:
コンポーネントにカスタム・バリデータを登録する場合、標準JSFのf:validatorタグを使用します。カスタム・バリデータの使用の詳細は、「カスタムJSF検証の作成」を参照してください。
ADF Facesバリデータを追加する手順:
実行時の処理: バリデータの機能の仕方
ユーザーがページを送信すると、ADF Facesで送信された値を確認し、null以外の値に対して変換を実行します。変換された値は、validate()メソッドに渡されます。値が空の場合、コンポーネントのrequired属性が確認され、指定されている場合はエラー・メッセージが生成されます。送信された値がnull以外の場合、検証プロセスが続けられ、コンポーネントのすべてのバリデータが宣言順にコールされます。
注意:
ADF Facesでは、クライアント側サポートのある、JSFバリデータの拡張が提供されます。
ADF Faces検証が検証の処理フェーズで実行されます。エラーが発生した場合、コンポーネントが無効化され、関連付けられているメッセージがFacesContextインスタンスのキューに追加されます。モデルの更新フェーズは、変換または検証にエラーがない場合にのみ発生します。コンポーネントのすべての検証が終了すると、モデル・レイヤーに制御が移り、モデルの更新の検証フェーズが実行されます。検証の処理フェーズ同様、エラーが発生した場合、コンポーネントが無効化され、関連付けられているメッセージがFacesContextインスタンスのキューに追加されます。
ライフサイクルはレスポンスのレンダリング・フェーズに移り、現在のページが再表示されます。コンポーネントがエラーを生成した場合、ADF Facesはエラーを自動的にハイライト表示します。たとえば、ADF Facesは、検証エラーがある場合に図7-4に示すようにinputTextコンポーネントの周囲に赤いボックスをレンダリングします。
検証または変換エラーの発生時のエラー・メッセージの追加の詳細は、「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。
複数バリデータに関する必知事項
UIコンポーネントには、バリデータを設定しないことも、複数設定することもできます。コンポーネントのrequired属性を設定し、バリデータを使用することができます。ただし、required属性をtrueに設定し、値がnullまたは長さがゼロの文字列の場合、コンポーネントは無効化され、コンポーネントに登録された他のバリデータはコールされません。
コンポーネントが空でも有効になるケースが存在する場合は、この組合せでは問題があることがあります。たとえば、ページに「Cancel」ボタンが含まれている場合、ユーザーはデータを入力しなくても、そのボタンをクリックすればページを閉じることができるようにする必要があります。このようなケースを処理するには、「Cancel」ボタンのコンポーネントのimmediate属性をtrueに設定します。この属性により、リクエスト値の適用フェーズ中にアクションを実行できます。次に、デフォルトのJSFアクション・リスナーはFacesContext.renderResponse()をコールして、アクション実行時に検証をバイパスします。「ADF FacesでのJSFライフサイクルの使用」を参照してください。
カスタムJSF検証の作成
ADF Facesで、ビジネス・ニーズに合せて独自の検証ロジックを追加できます。バッキングBeanに対して必要な検証を提供するメソッドを追加するか、JSFバリデータを使用すると、カスタム検証を作成できます。
1つのページのコンポーネントにカスタム検証ロジックが必要な場合、ページのバッキングBeanに検証メソッドを作成します。
アプリケーション内の様々なページで再利用されるロジックを作成する場合、またはクライアント側で検証を実行できるようにする場合は、JSFバリデータ・クラスを作成します。その後、クライアント側でバリデータを実行できるADF Faces版を作成します。
バッキングBeanの検証メソッドの作成方法
1つのページのコンポーネントにカスタム検証が必要な場合、必要な検証を提供するメソッドをバッキングBeanに作成します。
始める前に:
カスタムJSF検証に関する知識が役立つ場合があります。「カスタムJSF検証の作成」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。
バッキングBeanの検証メソッドを追加する手順:
バッキングBeanの検証メソッドを作成するときに行われる処理
検証メソッドを作成すると、選択したマネージドBeanにJDeveloperでスケルトン・メソッドが追加されます。次の例は、JDeveloperが生成するコードを示します。
public void inputText_validator(FacesContext facesContext,
UIComponent uiComponent, Object object) {
// Add event code here...
}
入力コンポーネントを含むフォームが送信されると、validator属性がバインドされているメソッドが実行されます。
カスタムJSFバリデータの作成方法
カスタム・バリデータを作成するには、インタフェースのValidator実装を作成してから、アプリケーションにカスタム・バリデータを登録することで、検証のビジネス・ロジックを作成する必要があります。バリデータのタグを作成するか、f:validatorタグを使用してカスタム・バリデータをそのタグの属性とすることもできます。
さらに、バリデータのクライアント側バージョンを作成できます。ADF Facesクライアント側検証は、クライアントでJavaScriptが使用されることを除き、サーバー上の標準検証と同じように動作します。JavaScriptバリデータ・オブジェクトはValidatorExceptions例外をスローでき、validate()メソッドをサポートします。
始める前に:
カスタムJSF検証に関する知識が役立つ場合があります。「カスタムJSF検証の作成」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。
カスタムJSFバリデータを作成する手順:
-
javax.faces.validator.Validatorインタフェースを実装するJavaクラスを作成します。Validatorインタフェースを実装するには、実装にpublicno-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コンストラクタを返します。次の例に、Javaでのバリデータを示します。
public String getClientValidation( FacesContext context, UIComponent component) { return ("new SSNValidator('Invalid social security number.','Value \"{1}\" must start with \"123\".')"); }Javaバリデータは、次の例に示すJavaScriptバリデータをコールします。
function SSNValidator(summary, detail) { this._detail = detail; this._summary = summary; }
JSFページでカスタム・バリデータを使用する手順:
-
JSFページにタグを持つカスタム・バリデータを使用するには、これをコンポーネントのタグ内に手動でネストさせる必要があります。
次の例に、
inputTextコンポーネント内にネストするカスタム・バリデータ・タグを示します。faces-config.xmlファイル内に宣言されていたバリデータのプロパティの値を提供するためにタグ属性が使用されていることに注意してください。
<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式をサポートします。
-
「構造」ウィンドウから、検証を追加する入力コンポーネントを右クリックし、「コンポーネントの中に挿入」→「JSF」→「バリデータ」を選択します。
-
入力コンポーネントが選択された状態で、「プロパティ」ウィンドウでドロップダウン・リストからバリデータのIDを選択し、「OK」をクリックします。
バリデータのIDを
f:validatorタグのプロパティにするコードが、JDeveloperでJSFページに挿入されます。
次の例に、f:validatorタグを使用するバリデータのJSFページでのコードを示します。
<af:inputText id="empnumber" required="true"> <f:validator validatorID="emValidator"/> </af:inputText>