パッケージ jakarta.faces.component

クラス UIInput

  • 実装されたすべてのインターフェース:
    EditableValueHolder、PartialStateHolder、StateHolder、TransientStateHolder、ValueHolder、ComponentSystemEventListener、FacesListener、SystemEventListenerHolder、EventListenerSE
    既知の直属サブクラス
    HtmlInputFile、HtmlInputHidden、HtmlInputSecret、HtmlInputText、HtmlInputTextarea、UISelectBoolean、UISelectMany、UISelectOne、UIViewParameter
    public class UIInput
extends UIOutput
implements EditableValueHolder

    UIInput は UIComponent であり、ユーザーに出力を表示するコンポーネント（UIOutput コンポーネントのように）と、デコードする必要がある後続のリクエストでリクエストパラメーターを処理するコンポーネントの両方を表します。ローカル値のデータ型、または値バインディング式（存在する場合）によって参照されるオブジェクトに制限はありません。ただし、個々の Renderer は通常、表示方法がわかっているデータの型に制限を課します。

    リクエスト処理ライフサイクルのリクエスト値の適用フェーズ中に、このコンポーネントのデコードされた値は、通常は文字列である必要はありませんが、setSubmittedValue() を使用して保存する必要がありますが、まだ変換されていません。コンポーネントが特定の値が送信されなかったことを示す場合は、何も実行しないか、送信された値を null に設定できます。

    デフォルトでは、リクエスト処理ライフサイクルのプロセスバリデーターフェーズ中に、送信された値は型安全オブジェクトに変換され、検証が成功した場合、setValue() を使用してローカル値として保存されます。ただし、immediate プロパティが true に設定されている場合、この処理は代わりにリクエスト値の適用フェーズの最後に行われます。

    リクエスト処理ライフサイクルのレスポンスのレンダリングフェーズ中に、出力の変換が UIOutput の場合と同様に行われます。

    この UIInput の validate() メソッドは、値の変更が実際に発生し、すべての検証が正常に渡されたことを検出すると、ValueChangeEvent をキューに入れます。その後、broadcast() メソッドは、このイベントがすべての関係するリスナーに確実にブロードキャストされるようにします。このイベントは、デフォルトでプロセス検証プロセスで配信されますが、immediate プロパティが true に設定されている場合は、リクエスト値の適用中に代わりに配信できます。検証が失敗した場合、実装は FacesContext.validationFailed() を呼び出す必要があります。

    デフォルトでは、rendererType プロパティを "Text" に設定する必要があります。この値は、setRendererType() メソッドを呼び出すことで変更できます。

    • フィールドの詳細

      • COMPONENT_FAMILY

        public static final StringSE COMPONENT_FAMILY

        このコンポーネントの標準コンポーネントファミリ。

        関連事項:
        定数フィールド値

      • UPDATE_MESSAGE_ID

        public static final StringSE UPDATE_MESSAGE_ID

        モデル更新エラーが発生し、スローされた例外にメッセージがない場合に作成される FacesMessage のメッセージ識別子。

        関連事項:
        定数フィールド値

      • EMPTY_STRING_AS_NULL_PARAM_NAME

        public static final StringSE EMPTY_STRING_AS_NULL_PARAM_NAME

        空の文字列をどのように解釈する必要があるかを示すコンテキストパラメーターの名前。

        関連事項:
        定数フィールド値

      • ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE

        public static final StringSE ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE

        このパラメーターが設定されていて、その値のストリング表現で toLowerCase().equals（"true" ）を呼び出すと true が返される場合、受信リクエストにこのコンポーネントに対応する値がない場合でも検証を実行する必要があります。validate(jakarta.faces.context.FacesContext) を参照してください。

        関連事項:
        定数フィールド値

    • コンストラクターの詳細

      • UIInput

        public UIInput()

        デフォルトのプロパティ値で新しい UIInput インスタンスを作成します。

    • メソッドの詳細

      • getFamily

        public StringSE getFamily()
        クラスからコピーされた説明: UIComponent

        このコンポーネントが属するコンポーネントファミリの識別子を返します。この識別子は、rendererType プロパティの値と組み合わせて、このコンポーネントインスタンスに適切な Renderer を選択するために使用できます。このメソッドは null を返すべきではないことに注意してください

        オーバーライド:
        クラス UIOutput の getFamily 
        戻り値:
        コンポーネントファミリ（null 以外）。

      • getSubmittedValue

        public ObjectSE getSubmittedValue()

        この UIInput コンポーネントの submittedValue 値を返します。このメソッドは、このコンポーネントの decode() および validate() メソッド、または対応する Renderer でのみ使用する必要があります。

        次で指定:
        インターフェース EditableValueHolder の getSubmittedValue 
        戻り値:
        送信された値。

      • setSubmittedValue

        public void setSubmittedValue​(ObjectSE submittedValue)

        この UIInput コンポーネントの submittedValue 値を設定します。このメソッドは、このコンポーネントの decode() および validate() メソッド、または対応する Renderer でのみ使用する必要があります。

        次で指定:
        インターフェース EditableValueHolder の setSubmittedValue 
        パラメーター:
        submittedValue - 新しく送信された値

      • getValue

        public ObjectSE getValue()

        ローカル値がある場合はそれを返し、それ以外の場合は super.getVaue() の呼び出し結果を返します。

        次で指定:
        インターフェース ValueHolder の getValue 
        オーバーライド:
        クラス UIOutput の getValue 
        戻り値:
        値。
        導入:
        2.2

      • setValue

        public void setValue​(ObjectSE value)
        インターフェースからコピーされた説明: ValueHolder

        この UIComponent の値を設定します（ある場合）。

        次で指定:
        インターフェース ValueHolder の setValue 
        オーバーライド:
        クラス UIOutput の setValue 
        パラメーター:
        value - 新しいローカル値

      • resetValue

        public void resetValue()

        このコンポーネントの値を初期化されていない状態にリセットする簡易メソッド。このメソッドは次のことを行います。

        UIOutput.setValue(java.lang.Object) を呼び出します。

        null を渡して setSubmittedValue(java.lang.Object) を呼び出します。

        プロパティ localValueSet の状態をクリアします。

        プロパティ valid の状態をクリアします。

        この呼び出しから戻ったときに、インスタンスに "value" プロパティの ValueBinding が関連付けられている場合、このバインディングは UIOutput.getValue() が呼び出されたときに評価されます。それ以外の場合、getValue() から null が返されます。

        次で指定:
        インターフェース EditableValueHolder の resetValue 
        オーバーライド:
        クラス UIOutput の resetValue 

      • isLocalValueSet

        public boolean isLocalValueSet()
        このコンポーネントの「ローカル値セット」の状態を返します。setValue() を呼び出すと、このプロパティは true に自動的にリセットされます。
        次で指定:
        インターフェース EditableValueHolder の isLocalValueSet 
        戻り値:
        ローカル値が設定されている場合は true、それ以外の場合は false。

      • setLocalValueSet

        public void setLocalValueSet​(boolean localValueSet)
        このコンポーネントの「ローカル値セット」の状態を設定します。
        次で指定:
        インターフェース EditableValueHolder の setLocalValueSet 
        パラメーター:
        localValueSet - 「ローカル値セット」ブール値。

      • isRequired

        public boolean isRequired()

        このコンポーネントの「必須フィールド」の状態を返します。

        次で指定:
        インターフェース EditableValueHolder の isRequired 
        戻り値:
        必要な場合は true、それ以外の場合は false。

      • setRequiredMessage

        public void setRequiredMessage​(StringSE message)

        このメソッドに提供されたリテラル引数を使用して、"requiredMessage" に設定された ValueExpression を上書きします。getRequiredMessage() への後続の呼び出しでは、この値が返されます。

        パラメーター:
        message - ユーザーが値を指定しておらず、値が必要な場合に表示されるリテラルメッセージ値。

      • setConverterMessage

        public void setConverterMessage​(StringSE message)

        このメソッドに提供されたリテラル引数を使用して、"converterMessage" に設定された ValueExpression を上書きします。getConverterMessage() への後続の呼び出しでは、この値が返されます。

        パラメーター:
        message - イベント変換で表示されるリテラルメッセージ値は失敗します。

      • setValidatorMessage

        public void setValidatorMessage​(StringSE message)

        このメソッドに提供されたリテラル引数を使用して、"validatorMessage" に設定された ValueExpression を上書きします。getValidatorMessage() への後続の呼び出しでは、この値が返されます。

        パラメーター:
        message - イベント検証で表示されるリテラルメッセージ値は失敗します。

      • isValid

        public boolean isValid()
        インターフェースからコピーされた説明: EditableValueHolder

        このコンポーネントのローカル値が有効かどうかを示すフラグを返します（変換エラーは発生していません）。

        次で指定:
        インターフェース EditableValueHolder の isValid 
        戻り値:
        有効な場合は true、それ以外の場合は false。

      • setValid

        public void setValid​(boolean valid)
        インターフェースからコピーされた説明: EditableValueHolder

        このコンポーネントのローカル値が有効である（変換エラーが発生していない）かどうかを示すフラグを設定します。

        次で指定:
        インターフェース EditableValueHolder の setValid 
        パラメーター:
        valid - 新しい有効なフラグ

      • setRequired

        public void setRequired​(boolean required)

        このコンポーネントの「必須フィールド」の状態を設定します。

        次で指定:
        インターフェース EditableValueHolder の setRequired 
        パラメーター:
        required - 新しい「必須フィールド」状態

      • isImmediate

        public boolean isImmediate()
        インターフェースからコピーされた説明: EditableValueHolder

        このコンポーネントの「即時」状態を返します。

        次で指定:
        インターフェース EditableValueHolder の isImmediate 
        戻り値:
        が即時の場合は true、それ以外の場合は false。

      • setImmediate

        public void setImmediate​(boolean immediate)
        インターフェースからコピーされた説明: EditableValueHolder

        このコンポーネントの「即時」状態を設定します。true に設定すると、コンポーネントの値は、リクエスト値の適用フェーズですぐに変換および検証され、ValueChangeEvent もそのフェーズで配信されます。このプロパティのデフォルト値は false である必要があります。

        次で指定:
        インターフェース EditableValueHolder の setImmediate 
        パラメーター:
        immediate - 新しい「即時」状態

      • processDecodes

        public void processDecodes​(FacesContext context)

        スーパークラスによって提供されるものに加えて、特殊なデコード動作。UIComponentBase から継承された標準の processDecodes 動作に加えて、immediate プロパティが true の場合は validate() を呼び出します。その後、コンポーネントが無効になった場合、RuntimeException がスローされた場合は、FacesContext.renderResponse() を呼び出します。

        オーバーライド:
        クラス UIComponentBase の processDecodes 
        パラメーター:
        context - FacesContext（処理中のリクエスト）
        例外:
        NullPointerExceptionSE - context が null の場合

      • processValidators

        public void processValidators​(FacesContext context)

        immediate プロパティが（デフォルトで）false の場合 UIComponentBase から継承された標準 processValidators 動作に加えて、validate() を呼び出します。その後、コンポーネントが無効な場合は、FacesContext.renderResponse() を呼び出します。PostValidateEvent が適切なタイミングで公開されるようにするには、このコンポーネントを最初に検証してから、コンポーネントの子とファセットを検証する必要があります。検証処理中に RuntimeException がスローされた場合は、FacesContext.renderResponse() を呼び出して、例外を再スローします。

        オーバーライド:
        クラス UIComponentBase の processValidators 
        パラメーター:
        context - FacesContext（処理中のリクエスト）
        例外:
        NullPointerExceptionSE - context が null の場合
        関連事項:
        PreValidateEvent, PostValidateEvent

      • decode

        public void decode​(FacesContext context)
        クラスからコピーされた説明: UIComponent

        指定された FacesContext に含まれるリクエストからこの UIComponent の新しい状態をデコードし、必要に応じてこの状態を保存します。

        デコード中、queueEvent() を呼び出すことにより、（インタレストを登録したイベントリスナーによる）後の処理のためにイベントをキューに入れることができます。

        オーバーライド:
        クラス UIComponentBase の decode 
        パラメーター:
        context - FacesContext（処理中のリクエスト）
        例外:
        NullPointerExceptionSE - context が null の場合

      • updateModel

        public void updateModel​(FacesContext context)

        次のアルゴリズムを実行して、必要に応じて、この UIInput に関連付けられているモデルデータを更新します。

        • このコンポーネントの valid プロパティが false の場合、それ以上のアクションは実行しないでください。
        • このコンポーネントの localValueSet プロパティが false の場合、それ以上のアクションは実行しないでください。
        • value の ValueExpression が存在しない場合は、それ以上のアクションを実行しません。
        • ValueExpression の setValue() メソッドを呼び出して、ValueExpression が指す値を更新します。
        • setValue() メソッドが正常に戻った場合:
          • この UIInput のローカル値をクリアします。
          • この UIInput の localValueSet プロパティを false に設定します。
        • setValue() メソッドが例外をスローした場合:例外を再スローしてはなりません。これにより、他のすべてのライフサイクルフェーズと同様に、ツリートラバーサルをこのライフサイクルフェーズで続行できます。
        パラメーター:
        context - FacesContext（処理中のリクエスト）
        例外:
        NullPointerExceptionSE - context が null の場合

      • validate

        public void validate​(FacesContext context)

        次のアルゴリズムを実行して、この UIInput のローカル値を検証します。

        • getSubmittedValue() を使用して送信された値を取得します。これが null を返し、ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE context-param の値が true（大文字と小文字を区別しない）の場合は、"required" プロパティの値を調べます。"required" の値が true の場合は、以下のように続行します。"required" の値が false の場合、または required 属性が設定されていない場合は、それ以上処理せずに終了します。context-param が設定されていないか、false に設定されている（大文字と小文字を区別しない）場合は、それ以上処理せずに終了します。(これは、このコンポーネントに値が送信されなかったことを示します。)
        • jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL コンテキストパラメーター値が true （大文字と小文字を区別しない）であり、getSubmittedValue() が長さゼロの String 呼び出し setSubmittedValue(java.lang.Object) を返す場合、引数として null を渡し、現在送信される値として null を使用して処理を続行します。
        • getConvertedValue(jakarta.faces.context.FacesContext, java.lang.Object) を呼び出して、送信された値を適切なデータ型の「ローカル値」に変換します。
        • 変換に失敗した場合 :
          • FacesContext で addMessage() メソッドを呼び出して、適切なエラーメッセージをキューに入れます。
          • このコンポーネントの valid プロパティを false に設定します
        • validateValue(jakarta.faces.context.FacesContext, java.lang.Object) を呼び出して、プロパティを検証します。
        • このコンポーネントの valid プロパティがまだ true である場合は、コンポーネントの以前の値を取得し（getValue() を使用）、setValue() を使用して新しいローカル値を格納し、null を引数として渡す setSubmittedValue(java.lang.Object) を呼び出して、送信された値を null にリセットします。compareValues(java.lang.Object, java.lang.Object) の呼び出しによって決定されたように、ローカル値がこのコンポーネントの以前の値と異なる場合は、ValueChangeEvent を起動して、関心のあるすべてのリスナーにブロードキャストします。

        コンポーネントに埋め込まれたロジックを使用して検証を実行する UIInput を実装するアプリケーションコンポーネントは、独自の正当性チェックを実行してから、super.validate() メソッドを呼び出して上記の標準処理を実行する必要があります。

        パラメーター:
        context - 現在のリクエストの FacesContext
        例外:
        NullPointerExceptionSE - context が null の場合

      • getConvertedValue

        protected ObjectSE getConvertedValue​(FacesContext context,
                                   ObjectSE newSubmittedValue)
                            throws ConverterException

        必要に応じて、送信された値を適切なデータ型の「ローカル値」に変換します。これを行うには、次のアルゴリズムを使用します。

        • Renderer が存在する場合は、getConvertedValue() を呼び出して、送信された値を変換します。
        • Renderer が存在せず、送信された値が文字列である場合は、次のように Converter を見つけます。
          • getConverter() が null 以外の Converter を返す場合は、そのインスタンスを使用します。
          • それ以外の場合、value の値バインディングが存在する場合は、getType() を呼び出します。
            • この呼び出しが null を返す場合、出力型が String であると想定し、変換を実行しません。
            • それ以外の場合は、Application.createConverter(Class) を呼び出して、指定された型のデータ値を変換できる登録済み Converter を見つけます。
        • Converter インスタンスが見つかった場合は、その getAsObject() メソッドを呼び出して変換を実行します。変換が失敗した場合、Converter はこのメソッドでチェックされた例外として宣言された ConverterException をスローするため、呼び出し元が処理する必要があります。
        • それ以外の場合は、変換せずに送信された値を使用します

        このメソッドは、より具体的な動作のためにサブクラスによってオーバーライドできます。

        パラメーター:
        context - Faces コンテキスト。
        newSubmittedValue - 新しく提出された値。
        戻り値:
        変換された値。
        例外:
        ConverterException

      • validateValue

        protected void validateValue​(FacesContext context,
                             ObjectSE newValue)

        以下のアルゴリズムに従って「有効な」プロパティを設定します。

        • このコンポーネントの valid プロパティがまだ true であり、required プロパティも true である場合は、ローカル値が空でないことを確認してください（「空」は null または長さゼロの文字列として定義されます）。ローカル値が空の場合:

          • 現在のリクエストの FacesContext インスタンスで addMessage() メソッドを呼び出して、適切なエラーメッセージをキューに入れます。getRequiredMessage() が非 null を返す場合は、その値を FacesContext にエンキューされている FacesMessage の summary および detail として使用します。それ以外の場合は、REQUIRED_MESSAGE_ID のメッセージを使用します。

          • このコンポーネントの valid プロパティを false に設定します。

          • ValidatorException.getFacesMessages() を呼び出すと非 null が返される場合は、各メッセージを FacesContext に追加する必要があります。それ以外の場合は、ValidatorException.getFacesMessage() から返される単一のメッセージを追加する必要があります。

        • それ以外の場合、このコンポーネントの valid プロパティがまだ true である場合は、次のアクションを実行して、このコンポーネントの検証を続行するかどうかを決定します。

          • 値が空でない場合は、検証を続行する必要があります。

          • 値が空であるが、システムが空のフィールドを検証するように指示されている場合、検証を続行する必要があります。実装は、ExternalContext から初期化パラメーター Map を取得し、シンボリック定数 VALIDATE_EMPTY_FIELDS_PARAM_NAME の値によって指定されたキーの値をインスペクションする必要があります。そのキーに値がない場合は、同じキーを使用して、ExternalContext からアプリケーションマップを調べます。値が null または文字列 "auto" （引用符なし）と等しい場合は、適切なアクションを実行して、ランタイム環境に Bean 検証が存在するかどうかを判別します。そうでない場合、検証は続行されません。その場合、検証を続行する必要があります。値が "true" （引用符なし）と等しい（大文字と小文字を区別しない）場合は、検証を続行する必要があります。それ以外の場合、検証は続行されません。

          上記の決定により検証を続行する必要があることが示された場合は、この UIInput に登録されている各 Validator の validate() メソッドを呼び出してから、validatorBinding プロパティ（存在する場合）が指すメソッドを呼び出します。これらのバリデーターまたはメソッドのいずれかが ValidatorException をスローした場合は、例外をキャッチし、そのメッセージ（存在する場合）を FacesContext に追加し、このコンポーネントの valid プロパティを false に設定します。

        パラメーター:
        context - Faces コンテキスト。
        newValue - 新しい値。

      • compareValues

        protected boolean compareValues​(ObjectSE previous,
                                ObjectSE value)

        新しい値が前の値と異なる場合は、true を返します。最初に、前の引数の equals メソッドに値を渡して、2 つの値を比較します。そのメソッドが true を返す場合は、true を返します。そのメソッドが false を返し、両方の引数が java.lang.Comparable を実装している場合は、前の引数の compareTo メソッドに値を渡して 2 つの値を比較します。このメソッドが 0 を返す場合は true を返し、それ以外の場合は false を返します。

        パラメーター:
        previous - このコンポーネントの古い値 (もしあれば)
        value - このコンポーネントの新しい値 (もしあれば)
        戻り値:
        新しい値が前の値と異なる場合は true、それ以外の場合は false。

      • isEmpty

        public static boolean isEmpty​(ObjectSE value)

        空の値を示す値です。

        値が null の場合、true を返します。値が文字列であり、それが空の文字列である場合は、true を返します。値が配列で、配列の長さが 0 の場合、true を返します。値がリストで、リストが空の場合、true を返します。値がコレクションであり、コレクションが空の場合、true を返します。値がマップで、マップが空の場合、true を返します。それ以外の場合はすべて false を返します。

        パラメーター:
        value - チェックする値。
        戻り値:
        そうである場合は true、そうでない場合は false。

      • getValidators

        public Validator[] getValidators()

        この UIInput インスタンスに登録されている Validator のセットを返します。登録されたバリデーターがない場合は、長さがゼロの配列が返されます。

        次で指定:
        インターフェース EditableValueHolder の getValidators 
        戻り値:
        バリデーター、または長さゼロの配列。

      • removeValidator

        public void removeValidator​(Validator validator)

        以前に関連付けられていた場合は、この UIInput に関連付けられているセットから Validator インスタンスを削除します。それ以外の場合は、何もしません。

        次で指定:
        インターフェース EditableValueHolder の removeValidator 
        パラメーター:
        validator - 削除する Validator

      • getValueChangeListeners

        public ValueChangeListener[] getValueChangeListeners()

        この UIInput インスタンスに登録されている ValueChangeListener のセットを返します。登録済みのリスナーがない場合は、長さ 0 の配列が返されます。

        次で指定:
        インターフェース EditableValueHolder の getValueChangeListeners 
        戻り値:
        値変更リスナー、または長さがゼロの配列。

      • saveState

        public ObjectSE saveState​(FacesContext context)
        インターフェースからコピーされた説明: StateHolder

        インスタンスの状態を Serializable オブジェクトとして取得します。

        このインターフェースを実装するクラスが、StateHolder を実装するインスタンス（イベントハンドラー、バリデーターなどを含む UIComponent など）への参照を持っている場合、このメソッドはそれらすべてのインスタンスで StateHolder.saveState(jakarta.faces.context.FacesContext) メソッドも呼び出す必要があります。このメソッドは、子とファセットの状態を保存してはなりませんそれは StateManager を介して行われます

        このメソッドは、実装オブジェクトの状態を変更してはなりません。つまり、このコードを実行した後:

         
 Object state = component.saveState(facesContext);

        component は、実行前と同じでなければなりません。

        このメソッドからの戻り値は Serializable でなければなりません

        次で指定:
        インターフェース StateHolder の saveState 
        オーバーライド:
        クラス UIOutput の saveState 
        パラメーター:
        context - Faces コンテキスト。
        戻り値:
        保存された状態。

      • restoreState

        public void restoreState​(FacesContext context,
                         ObjectSE state)
        インターフェースからコピーされた説明: StateHolder

        state オブジェクトのエントリから状態を復元するために必要な処理を実行します。

        このインターフェースを実装するクラスが、StateHolder も実装するインスタンスへの参照を持っている場合（イベントハンドラー、バリデーターなどを備えた UIComponent など）、このメソッドはそれらすべてのインスタンスで StateHolder.restoreState(jakarta.faces.context.FacesContext, java.lang.Object) メソッドも呼び出す必要があります。

        state 引数が null の場合、アクションを実行せずに戻ります。

        次で指定:
        インターフェース StateHolder の restoreState 
        オーバーライド:
        クラス UIOutput の restoreState 
        パラメーター:
        context - Faces コンテキスト。
        state - 状態。