Oracle® Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド 11g リリース2(11.1.2.4.0) B66719-05 |
|
![]() 前 |
![]() 次 |
この章では、アプリケーションのADF Faces入力コンポーネントに変換と検証の機能を追加する方法について説明します。エラー(検証によって生じたもの以外も)の処理および表示方法についても説明します。
この章では、次の項目について説明します。
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章「ヒント、メッセージおよびヘルプの表示」を参照してください。
文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第29章「ページの国際化およびローカライズ」を参照してください。
データを持つフォームが送信されると、編集可能な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コンバータを追加する手順:
構造ウィンドウで、コンバータを追加するコンポーネントを右クリックします。
ポップアップ・メニューで「<UIコンポーネント>の中に挿入」を選択し、ADF Facesコンバータを挿入する場合は「ADF Faces」を、JSFコンバータを挿入する場合は「JSF Core」を選択します。
コンバータ・タグ(ConvertDateTimeなど)を選択します。
プロパティ・インスペクタで、変換エラー用のメッセージなどの値を属性に設定します。ヘルプを参照するには、属性を右クリックし、「ヘルプ」を選択します。
複数のパターンを設定できる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>
注意: 12時間フォーマット( |
例7-3に、type
属性がcurrency
に設定されており、$78.57と$078.57を変換の値として使用できるaf:convertNumber
タグを示します。
ユーザーがコンバータを含むページを送信すると、ADF Facesのvalidate()
メソッドでコンバータのgetAsObject()
メソッドがコールされ、String
値が必要なオブジェクト・タイプに変換されます。アタッチされているコンバータがなく、コンポーネントがモデルのBeanプロパティにバインドされている場合、ADFでモデルのデータ型を確認して適切なコンバータを見つけます。変換に失敗すると、コンポーネントのvalid
属性がfalse
に設定され、JSFでFacesContext
によってメンテナンスされているキューにエラー・メッセージが追加されます。変換が正常終了し、コンポーネントにアタッチされているバリデータがある場合、変換された値がバリデータに渡されます。コンポーネントにアタッチされているバリデータがない場合、変換された値はローカル値として格納され、モデルの更新に後で使用されます。
特定のビジネス・ニーズに合せて、独自のコンバータを作成できます。サーバー側で実Javaを使用して実行されるカスタムJSFコンバータを作成してから、クライアント側で実行できるJavaScriptバージョンも作成できます。ただし、カスタム・バリデータとは異なり、1つのコンポーネントに1つのコンバータのみアタッチできます。変換を提供するためにメソッドをバッキングBeanに追加することはできません。
カスタム・コンバータを作成するには、getAsObject()
およびgetAsString()
メソッドを含むConverter
インタフェースの実装を作成してから、アプリケーションにカスタム・コンバータを登録することで、変換のビジネス・ロジックを作成する必要があります。次にf:converter
タグを使用し、カスタム・コンバータをそのタグのプロパティとして設定するか、入力コンポーネントでconverter
属性を使用して、そのコンバータにバインドできます。
コンバータのクライアント側バージョンを作成することもできます。ADF Facesクライアント側コンバータは、クライアントでJavaScriptが使用されていることを除き、サーバー上の標準JSF変換と同じように動作します。JavaScriptコンバータ・オブジェクトはConverterException
例外をスローでき、getAsObject()
およびgetAsString()
メソッドをサポートします。
始める前に:
カスタムJSFコンバータに関する知識が役立つ場合があります。詳細は、7.4項「カスタムJSFコンバータの作成」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、7.1.2項「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
にアクセスしてください。
アプリケーションでクライアントに状態を保存する場合、カスタム・コンバータで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バージョンのコンバータを作成し、関連する情報をコンストラクタに渡します。例7-4に、2つのメソッドを持つorg.apache.myfaces.trinidad.convert.ClientConverter
インタフェースを実装するコードを示します。1つ目のメソッドはgetClientScript()
で、JavaScriptのConverter
オブジェクトの実装を返します。2つ目のメソッドはgetClientConversion()
で、コンバータ・インスタンスのインスタンス化に使用される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){}
TrConverter
インタフェースは、TrConverterException
例外をスローできます。この例外にはTrFacesMessage
エラー・メッセージが含まれている必要があります。例7-5にTrFacesMessage
のシグネチャを示し、例7-6にTrFacesException
のシグネチャを示します。
例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のシグネチャ
/** * 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
例7-7に、サーバーで実行される、Javaで作成されたカスタム・コンバータSimpleNumberConverterの例を示します。カスタム・コンバータでは、ClientConverter
インタフェースを実装する必要があります。
例7-7 Javaでのカスタム・コンバータSimpleNumberConverter
public class SimpleNumberConverter implements javax.faces.convert.Converter, org.apache.myfaces.trinidad.convert.ClientConverter { public SimpleNumberConverter(boolean isInteger) { _isInteger = isInteger; } // CONVERTER INTERFACE public Object getAsObject(FacesContext context, UIComponent component, String value) { // convert to object } String getAsString(FacesContext context, UIComponent component, Object value) { // convert to string } // CLIENTCONVERTER INTERFACE /** * Called to retrieve the appropriate client * conversion code for the node and context. * For HTML, this will be javascript that will be embedded in a * script tag. For HTML this method is expected to return a * constructor of the javascript Converter object * returned by getClientScript(). */ public String getClientConversion(FacesContext context, UIComponent component) { return "new SimpleNumberConverter(" + Boolean.toString(_isInteger) + ")"; } public Collection<String> getClientImportNames() { // return empty collection } public String getClientLibrarySource(FacesContext context) { return null; } public String getClientScript(FacesContext context, UIComponent component) { return null; } private boolean _isInteger; }
例7-8に示すように、クライアントのカスタム・コンバータのJavaScript実装も作成する必要があります。
例7-8 JavaScriptでのSimpleNumberConverterのクライアント側実装
/** * constructor of client side SimpleNumberConverter class */ function SimpleNumberConverter(isInteger) { this._isInteger = isInteger; } // Inherit object properties from base class if desired. SimpleNumberConverter.prototype = new SimpleConverter(); SimpleNumberConverter.prototype.getAsString = function(number,label){ // convert to string } SimpleNumberConverter.prototype.getAsObject = function(numberString,label) { // convert to object }
JSFページでカスタム・コンバータを使用する手順:
コンバータ・クラスを入力コンポーネントのconverter
属性にバインドします。
注意: カスタム・コンバータがアプリケーションで特定のデータ型のクラスの下に登録されると、カスタム・コンバータ・オブジェクトと同じ型の値バインディングがコンポーネント値で参照されるたびに、JSFでそのクラスのコンバータが値の変換に自動的に使用されます。この場合、次のコードに示すように、 <af:inputText value="#{myBean.myProperty}"/>
|
ユーザーがフィールド内のデータを編集または入力してフォームを送信したときに、設定した規則および条件に対してデータが検証されるように、検証を追加できます。検証に失敗すると、アプリケーションでエラー・メッセージが表示されます。たとえば、図7-1では、af:validateDateTimeRange
コンポーネントによってユーザー入力に対する特定の日付範囲がメッセージ・ヒントに設定されており、無効な値が入力されると、メッセージ・ポップアップ・ウィンドウにエラー・メッセージが表示されます。
クライアント側の検証が必要な場合、ビュー・レイヤーでADF Facesの検証を使用します。ADF Facesに用意されているすべてのバリデータは、クライアント側ピアを持ちます。多くのコンポーネントは、検証を提供する属性を持ちます。詳細は、7.5.1.2項「検証属性の使用」を参照してください。また、ADF Facesは、クライアントとサーバーの両方で実行できる独立した検証クラスを提供します。詳細は、7.5.1.3項「ADF Facesバリデータの使用」を参照してください。独自のバリデータも作成できます。カスタム・バリデータの詳細は、7.6.3項「カスタムJSFバリデータの作成方法」を参照してください。
入力コンポーネントにADF Faces検証を設定すると、エラー・メッセージがページにインラインで、またはポップアップ・ウィンドウに表示されます。検証エラーで作成されたメッセージの表示の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。
始める前に:
ADF検証に関する知識が役立つ場合があります。詳細は、7.5項「検証の追加」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、7.1.2項「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。
デフォルトでは、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検証の作成」を参照してください。
多くのADF FacesのUIコンポーネントには、簡単な検証を提供する属性が備わっています。たとえば、af:inputDate
コンポーネントには、日付値に使用できる最大値と最小値を指定するmaxValue
属性とminValue
属性があります。
UIコンポーネントのヘルプを参照するには、プロパティ・インスペクタで属性の名前を右クリックし、「ヘルプ」を選択します。
ADF Facesバリデータは、サーバーまたはクライアントで実行できる個別のクラスです。表7-2に、バリデータとそのロジックを示します。
表7-2 ADF Facesのバリデータ
バリデータ | タグ名 | 説明 |
---|---|---|
|
|
エンコード時に文字列のバイト数が検証されます。 |
|
|
入力された日付が、指定された制限に対し有効かどうかが検証されます。 |
|
|
入力された日付が、指定された範囲内かどうかが検証されます。範囲はバリデータの属性として指定します。 |
|
|
コンポーネント値が指定された範囲内にあるかが検証されます。値は浮動小数点型に変換可能である必要があります。 |
|
|
コンポーネントの長さが指定された範囲内にあるかが検証されます。値は |
|
|
コンポーネント値が指定された範囲内にあるかが検証されます。値は数値型か、 |
|
|
Java正規表現構文を使用するデータを検証します。 |
注意: コンポーネントにカスタム・バリデータを登録する場合、標準JSFの |
ADF Facesバリデータを追加する手順:
構造ウィンドウで、バリデータを追加するコンポーネントを右クリックします。
ポップアップ・メニューで「<UIコンポーネント>の中に挿入」を選択し、ADF Facesバリデータを挿入する場合は「ADF Faces」を、JSF参照実装バリデータを挿入する場合は「JSF Core」を選択します。
バリデータ・タグ(ValidateDateTimeRangeなど)を選択します。
プロパティ・インスペクタで、検証エラー用のメッセージなどの値を属性に設定します。ヘルプを参照するには、属性を右クリックし、「ヘルプ」を選択します。
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-2に示すように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
は、<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の中に挿入」→「ADF Facesコア」→「バリデータ」を選択します。
ドロップダウン・リストからバリデータのIDを選択し、「OK」をクリックします。
バリデータのIDをf:validator
タグのプロパティにするコードが、JDeveloperでJSFページに挿入されます。
例7-13に、f:validator
タグを使用するバリデータのJSFページでのコードを示します。