パッケージ jakarta.faces.application

クラス ResourceHandler

  • 既知の直属サブクラス
    ResourceHandlerWrapper
    public abstract class ResourceHandler
extends ObjectSE

    ResourceHandler は、UIComponent および Renderer インスタンス、および ViewDeclarationLanguage が Resource インスタンスを参照できるランタイム API です。このクラスの実装はスレッドセーフでなければなりません。

    パッケージングリソース

    ResourceHandler は、リソースのパスベースのパッケージ化規則を定義します。ResourceHandler のデフォルトの実装は、クラスパスまたは Web アプリケーションルートでのリソースのパッケージ化をサポートする必要があります。パッケージングリソースの規範的な仕様については、Jakarta Faces Specification Document のセクション 2.6.1「パッケージングリソース」を参照してください。

    簡単に言えば、デフォルトの実装は、パスの Web アプリケーションルートでパッケージ化リソースをサポートする必要があります

    resources/<resourceIdentifier>

    Web アプリのルートに対して相対的です。「リソース」はデフォルトの場所ですが、この場所は WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME <context-param> の値によって変更できます。

    デフォルトの実装では、クラスパスにパッケージ化されたリソースは JAR エントリ名に存在する必要があります

    META-INF/resources/<resourceIdentifier>

    jar ファイル内にパッケージ化された Faces Flow の場合、クラスパスにパッケージ化されたリソースは jar エントリ名に存在する必要があります

    META-INF/flows/<resourceIdentifier>

    <resourceIdentifier> は、次のように指定されたいくつかのセグメントで構成されています。

    [localePrefix/][libraryName/][libraryVersion/]resourceName[/resourceVersion]

    resourceIdentifier 内のセグメントはいずれも、"../otherLibraryName" などの相対パスであってはなりません。実装では、JAR パッケージ化の場合、libraryVersion および resourceVersion セグメントをサポートする必要はありません。

    必須のセグメントは resourceName のみであることに注意してください。

    エンコーディングリソース

    ビューリクエストの処理中に、Jakarta Server Face ランタイムが呼び出されて、後続のリソースリクエストを行うようにユーザーエージェントに指示するような方法でリソースをエンコードすることができます。この動作は、リソースレンダラーの 1 つ（ScriptRenderer、StylesheetRenderer、ImageRenderer）によって調整されます。ScriptRenderer、StylesheetRenderer、ImageRenderer はすべて Resource.getRequestPath() を呼び出して、リソースのエンコードされた URI を取得します。完全な仕様については、Resource.getRequestPath() および標準 HTML RenderKit 仕様を参照してください。

    このリソースの使用は、VDL リソースに対応するリソースには適用されません。

    リソースのデコード

    リソースリクエストの処理中に、Jakarta Faces ランタイムが呼び出され、リソースのバイトをユーザーエージェントに提供するようにリソースをデコードします。この動作は、Resource.getInputStream() を呼び出してリソースのバイトを取得する handleResourceRequest(jakarta.faces.context.FacesContext) によって調整されます。完全な仕様については、handleResourceRequest(jakarta.faces.context.FacesContext) を参照してください。

    このリソースの使用は、VDL リソースに対応するリソースには適用されません。

    導入:
    2.0

    • フィールドの詳細

      • FACES_SCRIPT_RESOURCE_NAME

        public static final StringSE FACES_SCRIPT_RESOURCE_NAME

        Jakarta Faces スクリプトリソースのリソース名。

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

      • FACES_SCRIPT_LIBRARY_NAME

        public static final StringSE FACES_SCRIPT_LIBRARY_NAME

        Jakarta Faces スクリプトリソースのライブラリ名。

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

      • RESOURCE_CONTRACT_XML

        public static final StringSE RESOURCE_CONTRACT_XML

        このファイルは、リソースライブラリ契約を含む jar ファイルの META-INF/contracts/<contractName>/ に配置する必要があります。<contractName> は契約の名前です。jar ファイルに複数の契約が含まれている場合は、マーカーファイルがそれぞれに存在する必要があります。その場所に配置する必要のあるファイルの名前については、「定数フィールド値」を参照してください。

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

      • WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME

        public static final StringSE WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME

        WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME の値と等しいパラメーター名を持つ <context-param> が存在する場合、ランタイムはその値を、リソースが配置される Web アプリルートを基準としたパスとして解釈する必要があります。このパラメーター値は "/" で始まることはできませんが、"/" 文字が含まれている場合があります。そのような <context-param> が存在しない場合、またはその値が無効な場合は、引用符なしの値 "resources" をランタイムで値として使用する必要があります。

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

      • WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME

        public static final StringSE WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME

        WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME の値と等しいパラメーター名を持つ <context-param> が存在する場合、ランタイムはその値を、リソースライブラリ契約が配置される Web アプリルートを基準としたパスとして解釈する必要があります。このパラメーター値は "/" で始まることはできませんが、"/" 文字が含まれている場合があります。そのような <context-param> が存在しない場合、またはその値が無効である場合、値 "contracts" は、引用符なしで、ランタイムによって値として使用される必要があります。

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

      • RESOURCE_EXCLUDES_PARAM_NAME

        public static final StringSE RESOURCE_EXCLUDES_PARAM_NAME

        handleResourceRequest(jakarta.faces.context.FacesContext) が参照する ServletContext init パラメーターは、リソースリクエストにレスポンスして決して提供されてはならないリソースの種類を示します。このパラメーターの値は、先頭の "." を含む、ファイル拡張子の単一のスペースで区切られたリストです。文字（引用符なし）。指定しない場合、RESOURCE_EXCLUDES_DEFAULT_VALUE 定数の値で指定されたデフォルト値が使用されます。手動で指定した場合、指定された値はデフォルトの値を完全に上書きし、補足しません。

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

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

      • ResourceHandler

        public ResourceHandler()

    • メソッドの詳細

      • createResource

        public abstract Resource createResource​(StringSE resourceName)

        引数 resourceName を指定して ViewResource のインスタンスを作成します。リソースのコンテンツ型は、resourceName を ExternalContext.getMimeType(java.lang.String) に渡すことによって導出されます。

        Jakarta Faces Specification Document のセクション 2.6.1.4「ローカライズおよびバージョン管理されたリソースの ライブラリ」で指定されたアルゴリズムを実行して、Resource を作成する必要があります。新しい要件は、仕様のバージョン 2.2 で導入されました。歴史的な理由から、このメソッドは、引数 resourceName が libraryName/resourceName の形式の場合、resourceName に "/" 文字が含まれている場合でも正しく動作します。

        パラメーター:
        resourceName - リソースの名前。
        戻り値:
        新しく作成された Resource インスタンス。指定されたリソースのエンコードまたはデコードでの使用に適しています。
        例外:
        NullPointerExceptionSE - resourceName が null の場合。

      • createViewResource

        public ViewResource createViewResource​(FacesContext context,
                                       StringSE resourceName)

        引数 resourceName を指定して Resource のインスタンスを作成します。これには、"/" 文字を含めることができます。ViewDeclarationLanguage は、ファイルシステムなどの永続ストアからビューをロードする必要がある場合にこのメソッドを呼び出します。このメソッドは createResource(java.lang.String) と同等の機能ですが、VDL ビューをロードする必要があるすべてのコールサイトはこのメソッドを使用する必要があります。これにより、ビューのロードのみに影響を与えるために ResourceHandler を装飾するクラスは、他の種類の処理に影響を与えることなくそうすることができます。スクリプトやスタイルシートなどのリソース。このメソッドを呼び出す前に、FacesContext が存在している必要があります。仕様の以前のリビジョンとの互換性を維持するには、createResource(java.lang.String) を呼び出すデフォルトの実装を提供する必要があります。

        デフォルトの実装では、次の場所でこの順序でリソースを検索する必要があります。

        • リソースライブラリ契約の検討 (Jakarta Faces Specification Document セクション 2.7 " リソースライブラリ契約 " で指定された場所)。

        • Web アプリのルートを検討します。

        • Faces フローを考慮します (Jakarta Faces Specification Document セクション 11.3.3 "Faces Flows" で指定された場所で)。

        FacesContext.getResourceLibraryContracts() を呼び出します。結果が非 null で空でない場合は、リスト内の各値について、その値をリソースライブラリ契約の名前として扱います。引数 resoureName がリソースライブラリ契約のリソースとして存在する場合は、それを返します。それ以外の場合は、見つかった場合は、リソース（リソースライブラリ契約にない）を返します。それ以外の場合は、null を返します。

        パラメーター:
        context - このリクエストの FacesContext
        resourceName - ViewDeclarationLanguage によってビューとして解釈されるリソースの名前。
        戻り値:
        新しく作成された ViewResource インスタンス。ViewDeclarationLanguage での使用に適しています。
        例外:
        NullPointerExceptionSE - resourceName が null の場合。
        導入:
        2.2

      • getViewResources

        public StreamSE<StringSE> getViewResources​(FacesContext facesContext,
                                       StringSE path,
                                       int maxDepth,
                                       ResourceVisitOption... options)

        指定された初期パスをルートとするリソースツリーをウォークすることにより、おそらく遅延して入力された Stream を返します。リソースツリーは幅優先でトラバースされます。ストリーム内の要素は、resourceName パラメーターとして createViewResource(jakarta.faces.context.FacesContext, java.lang.String) に渡されたときに ViewResource を生成するビューリソース名です。

        maxDepth パラメーターは、常にアクセスされる初期パスを超えてアクセスするディレクトリレベルの最大深度です。値は、指定された初期パスではなく、ルート（/）を基準にしています。たとえば、maxDepth = 3 および初期パス /foo/ が与えられた場合、訪問は /foo/bar/ まで進みます。ここで、/ は深さ 1 としてカウントされ、/foo/ は深さ 2 としてカウントされ、/foo/bar/ は深さ 3 としてカウントされます。初期パスの深さ以下の値は、初期パスのみが訪問されることを意味します。MAX_VALUESE の値を使用して、すべてのレベルにアクセスする必要があることを示すことができます。

        パラメーター:
        facesContext - このリクエストの FacesContext。
        path - ビューリソースの検索を開始する最初のパス
        maxDepth - ルート（/）から数えた、アクセスするネストされたディレクトリの絶対最大深度。
        options - トラバーサルに影響を与えるオプション。これらの詳細については、ResourceVisitOption を参照してください。
        戻り値:
        ビューリソース名の StreamSE
        導入:
        2.3

      • getViewResources

        public StreamSE<StringSE> getViewResources​(FacesContext facesContext,
                                       StringSE path,
                                       ResourceVisitOption... options)

        指定された初期パスをルートとするリソースツリーをウォークすることにより、おそらく遅延して入力された Stream を返します。リソースツリーは幅優先でトラバースされます。ストリーム内の要素は、resourceName パラメーターとして createViewResource(jakarta.faces.context.FacesContext, java.lang.String) に渡されたときに ViewResource を生成するビューリソース名です。

        このメソッドは、それを呼び出すことは式を評価することと同等であるかのように機能します。

         getViewResources(facesContext, start, Integer.MAX_VALUE, options)
        言い換えると、リソースツリーのすべてのレベルにアクセスします。
        パラメーター:
        facesContext - このリクエストの FacesContext。
        path - ビューリソースの検索を開始する最初のパス
        options - トラバーサルに影響を与えるオプション。これらの詳細については、ResourceVisitOption を参照してください。
        戻り値:
        ビューリソース名の StreamSE
        導入:
        2.3

      • createResourceFromId

        public Resource createResourceFromId​(StringSE resourceId)

        引数 resourceId を指定して Resource のインスタンスを作成します。リソースのコンテンツ型は、resourceName を ExternalContext.getMimeType(java.lang.String) に渡すことによって導出されます。

        リソースは、Jakarta Faces Specification Document のセクション 2.6.1.3「リソース識別子」の仕様に従って識別する必要があります。仕様のバージョン 2.2 で新しい要件が導入されました。

        パラメーター:
        resourceId - リソースのリソース識別子。
        戻り値:
        新しく作成された Resource インスタンス。指定されたリソースのエンコードまたはデコードでの使用に適しています。
        例外:
        NullPointerExceptionSE - resourceId が null の場合。
        導入:
        2.2

      • createResource

        public abstract Resource createResource​(StringSE resourceName,
                                        StringSE libraryOrContractName)

        引数 libraryName で指定されたライブラリのメンバーである引数 resourceName の値によって指定された resourceName を使用して、Resource のインスタンスを作成します。リソースのコンテンツ型は、resourceName を ExternalContext.getMimeType(java.lang.String) に渡すことによって導出されます。

        Jakarta Faces Specification Document のセクション 2.6.1.4「ローカライズおよびバージョン管理されたリソースの ライブラリ」で指定されたアルゴリズムを実行して、Resource. 新しい要件は、仕様のバージョン 2.2 で導入されましたを作成する必要があります。

        パラメーター:
        resourceName - リソースの名前。
        libraryOrContractName - このリソースが存在するライブラリ (または契約) の名前は null の場合があります。リソースライブラリの名前とリソースライブラリ契約が競合する場合は、リソースライブラリが優先されます。"../" などの相対パスを含めることはできません。
        戻り値:
        新しく作成された Resource インスタンス。指定されたリソースのエンコードまたはデコードでの使用に適しています。
        例外:
        NullPointerExceptionSE - resourceName が null の場合

      • createResource

        public abstract Resource createResource​(StringSE resourceName,
                                        StringSE libraryName,
                                        StringSE contentType)

        引数 content-type によって指定されたコンテンツ型を持つと主張する引数 libraryName によって指定されたライブラリのメンバーである引数 resourceName の値によって指定された resourceName を使用して、Resource のインスタンスを作成します。

        Jakarta Faces Specification Document のセクション 2.6.1.4「ローカライズおよびバージョン管理されたリソースの ライブラリ」で指定されたアルゴリズムを実行して、Resource. 新しい要件は、仕様のバージョン 2.2 で導入されましたを作成する必要があります。

        パラメーター:
        resourceName - リソースの名前。
        libraryName - このリソースが存在するライブラリの名前。null の場合があります。 "../" などの相対パスを含めることはできません。
        contentType - この Resource インスタンスが Resource.getContentType() から返す MIME コンテンツ。値が null の場合、リソースのコンテンツ型は resourceName を ExternalContext.getMimeType(java.lang.String) に渡すことによって導出されます。
        戻り値:
        新しく作成された Resource インスタンス。指定されたリソースのエンコードまたはデコードでの使用に適しています。
        例外:
        NullPointerExceptionSE - resourceName が null の場合。

      • libraryExists

        public abstract boolean libraryExists​(StringSE libraryName)

        引数 libraryName で指定されたリソースライブラリが見つかった場合は、true を返します。LOCALE_PREFIX で定義されているように、このアプリケーションに localePrefix がある場合は、最初にプレフィックス付きのライブラリを検索します。そのようなライブラリが見つからない場合は、プレフィックスなしのライブラリを検索します。これにより、開発者はファイルの重複を回避できます。例: 開発者が、ローカライズされたイメージリソースとローカライズされていないスクリプトリソースを含むリソースライブラリを必要とする場合を考えてみましょう。ライブラリの存在について両方の場所をチェックし、Jakarta Faces Specification Document のセクション 2.6.1.4「ローカライズおよびバージョン管理されたリソースの ライブラリ」のその他の仕様変更を行うことで、このシナリオが有効になります。

        パラメーター:
        libraryName - ライブラリ名。
        戻り値:
        ライブラリが存在する場合は true、それ以外の場合は false。
        導入:
        2.0

      • isResourceRequest

        public abstract boolean isResourceRequest​(FacesContext context)

        現在のリクエストがリソースリクエストの場合は、true を返します。このメソッドは FacesServlet.service(jakarta.servlet.ServletRequest, jakarta.servlet.ServletResponse) によって呼び出され、このリクエストがビューリクエストであるかリソースリクエストであるかを判別します。

        パラメーター:
        context - このリクエストの FacesContext
        戻り値:
        現在のリクエストがリソースリクエストの場合は true、それ以外の場合は false。

      • isResourceURL

        public boolean isResourceURL​(StringSE url)

        引数 url に定数 RESOURCE_IDENTIFIER の値で指定された文字列が含まれている場合は、true を返します。それ以外の場合は、false を返します。

        パラメーター:
        url - RESOURCE_IDENTIFIER の存在をインスペクションする URL。
        戻り値:
        これがリソース URL の場合は true、それ以外の場合は false。
        例外:
        NullPointerExceptionSE - 引数の URL が null の場合。

      • getRendererTypeForResourceName

        public abstract StringSE getRendererTypeForResourceName​(StringSE resourceName)

        このリソースをレンダリングできる Renderer の renderer-type を返します。デフォルトの実装は、次の表に従って値を返す必要があります。renderer-type を判別できない場合は、null を返却する必要があります。

        レンダラー型のマッピングへのリソース名
        リソース名の例 renderer-type
        mycomponent.jsjakarta.faces.resource.Script
        mystyle.cssjakarta.faces.resource.Stylesheet
        パラメーター:
        resourceName - リソース名。
        戻り値:
        レンダラーの型。

      • markResourceRendered

        public void markResourceRendered​(FacesContext context,
                                 StringSE resourceName,
                                 StringSE libraryName)

        指定されたリソースとライブラリ名で識別されるリソースをレンダリング済みとしてマークします。デフォルトの実装では、現在のビューのレンダリングレスポンスフェーズ中にリソースがすでにレンダリングされている場合に、isResourceRendered(FacesContext, String, String) が true を返すようにする必要があります。

        パラメーター:
        context - このリクエストの FacesContext。
        resourceName - リソースの名前。
        libraryName - リソースが存在するライブラリの名前は、null の場合があります。
        導入:
        2.3

      • isResourceRendered

        public boolean isResourceRendered​(FacesContext context,
                                  StringSE resourceName,
                                  StringSE libraryName)

        指定されたリソースとライブラリ名で識別されるリソースがレンダリングされているかどうかを返します。デフォルトの実装では、リソースが markResourceRendered(FacesContext, String, String) を介してレンダリングされたとマークされている場合、現在のビューのレンダリングレスポンスフェーズで true を返す必要があります。

        パラメーター:
        context - このリクエストの FacesContext。
        resourceName - リソースの名前。
        libraryName - このリソースが存在するライブラリの名前は、null の場合があります。
        戻り値:
        指定されたリソースとライブラリ名で識別されるリソースがレンダリングされているかどうか。
        導入:
        2.3