ナビゲーション・ヘッダーをスキップ
Oracle ADF UIX開発者ガイド 目次へ
目次
前のページへ戻る
前へ
次のページへ進む
次へ

17. ADF UIXの構成

このトピックでは、UIXアプリケーションのすべての部分の構成情報を管理するために使用する、Oracle ADF UIX Configuration APIについて説明します。 ここでは、次の項目について説明します。

Configuration API

UIX Configuration APIは、グローバル構成情報をUIXフレームワークのすべての部分に渡すためのUIXのメカニズムです。 構成情報は、URL、ファイル・システム・パスおよびその他多数のプロパティという3つのタイプの情報から構成されます。 URLとパスはどちらも、イメージやスタイルシートなどのUIXフレームワークで使用されるUIXリソースの場所を示すために使用されます。 すべての構成情報は、不変のベース・クラスであるConfigurationクラスのインスタンスを介してアクセスされます。 Configuration APIには、アプリケーションでデフォルトの構成値をオーバーライドする際に使用する、関連する不定のサブクラスConfigurationImplも用意されています。

ConfigurationオブジェクトはJavaから作成できますが、構成を作成するための単純なXML書式を提供する、WEB-INFディレクトリにあるuix-config.xmlファイルを使用した方がはるかに簡単です。

Configurationオブジェクトは、UIXサーブレットのBajaContext、ComponentsのRenderingContext、ImagesのImageContextなど、様々なプロジェクト固有のコンテキストを介して、UIXフレームワーク全体に渡されます。 1つのHTTPリクエストに対するサービスのために作成され、レスポンスの完了時に解放されるその他のコンテキスト・オブジェクトとは異なり、Configurationオブジェクトはアプリケーションの存続期間を通じて存在します。 このため、アプリケーションでは構成の初期化を一度実行した後、単一のConfigurationオブジェクト(または少数のConfigurationオブジェクト)を再利用し、すべてのリクエストにサービスを提供できます。

UIXリソース・ファイル

UIXフレームワークではイメージおよびスタイルシートなどの様々なリソース・ファイルを使用するため、UIXで生成されたWebページで使用するためには、これらのファイルをWebサーバーにインストールする必要があります。 多くの場合、Webアプリケーションでは、アプリケーション固有のリソースを特定の標準ディレクトリにインストールします。 たとえば、あるアプリケーションで、イメージを/imagesディレクトリにインストールする場合があります。 この方法の問題点は、異なるアプリケーション間でリソース・ファイル名が競合する可能性がある点です。 2つの異なるアプリケーションが/images/logo.gifまたはstyles.cssを参照すると仮定します。 この2つのアプリケーションは、1つのWebサーバー上では共存できません。 UIXフレームワークでは、このようなリソース・ファイル名の競合を、次の2つの方法で回避します。 第1に、UIXフレームワークでは、自分のリソースを/caboの下のデフォルト・リソース・ディレクトリに配置することでパーティション化します。 第2に、UIXフレームワークでは、Configuration APIを介してリソースのデフォルトの場所をオーバーライドできます。

次の表に、各UIXリソース・ディレクトリの名前、デフォルトの場所および内容を示します。 名前は、Configurationクラスで定義されたディレクトリ定数を使用して指定されています。 デフォルトの場所は、相対URLで指定されています。

Java名 XML要素 デフォルトの場所 内容
BASE_DIRECTORY <base-directory> /cabo/ その他のUIXリソース・ディレクトリすべてを含む。
IMAGES_DIRECTORY <images-directory> /cabo/images/ UIX Componentsで使用される静的イメージを含む。
STYLES_DIRECTORY <styles-directory> /cabo/styles/ UIXで使用されるXML Style Sheet文書を含む。
JSLIBS_DIRECTORY <jslibs-directory> /cabo/jsLibs/ UIXで内部的に使用されるJavaScriptライブラリ・ファイルを含む。
JSPS_DIRECTORY <jsps-directory> /cabo/jsps/ UIXで内部的に使用されるJSPファイルを含む。
IMAGES_CACHE_DIRECTORY <images-cache-directory> /cabo/images/cache/ UIXで動的に生成されるアプリケーション固有のイメージを含む。
STYLES_CACHE_DIRECTORY <styles-cache-directory> /cabo/styles/cache/ UIXで動的に生成されるCascading Style Sheetファイルを含む。

UIXリソース・ディレクトリの構造は、階層構造です。 親ディレクトリの場所を変更すると、子ディレクトリの場所も移動します。 たとえば、IMAGES_DIRECTORYを変更するとIMAGES_CACHE_DIRECTORYも暗黙的に変更され、BASE_DIRECTORYを変更するとその他すべてのディレクトリも暗黙的に変更されます。

ここに定義したデフォルトの場所はすべて、アプリケーション固有の値で構成されているConfigurationImplインスタンスを使用して、またはWEB-INF/uix-config.xmlに要素を追加して変更できます。

uix-config.xmlの編集

UIXでは、1つのXMLファイルで簡単に構成オブジェクトを設定できます。 このファイルは、WEB-INFディレクトリのuix-config.xml内に格納されています。 これは、web.xmlがサーブレットやファイル・マッピングを列記する同じWEB-INFディレクトリです。 (このディレクトリはJava Servlet 2.1以上でのみ存在します。)

WEB-INF/uix-config.xmlファイルはいつも同じ要素、<configurations>で始まり(終わり)ます。 その要素内に、UIXを構成する一連の要素が含まれています。 次に例を示します。

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <configurations xmlns="http://xmlns.oracle.com/uix/config">

    <!-- A series of properties global to your application -->
    <application-configuration>
      <uix-path>c:\yourDirectory\uixFiles\</uix-path>
      <check-modified>true</check-modified>
      <ui-extensions>
        <template-library>templates/library.uit</template-library>
      </ui-extensions>
    </application-configuration>

    <!-- A set of default properties -->
    <default-configuration>
      <base-path>
        <context-uri>uixInst</context-uri>
      </base-path>

      <help-provider>
        <ohw-servlet-url>http://yourserver.com/ohw</ohw-servlet-url>
      </help-provider>
    </default-configuration>

    <!-- An alternate configuration that disables accessibility features  -->
    <configuration name="noAccessibility">
      <accessibility-mode>inaccessible</accessibility-mode>
    </configuration>

    <!-- And another configuration that maxes out accessibility features -->
    <configuration name="maxAccessibility">
      <accessibility-mode>screenReader</accessibility-mode>
      <style-sheet-name>myBigStyleSheet.xss</style-sheet-name>
    </configuration>

  </configurations>

構成ファイルで使用できるすべての要素についてはすぐ後述しますが、この例を一覧することによって概略がつかめるはずです。

uix-config.xmlファイルには次の3つのセクションがあり、各セクションはオプションです。

  1. 最初に、<application-configuration>セクションが、Webアプリケーション全体に対してグローバルなプロパティを定義します。
  2. 次に、<default-configuration>セクションが、デフォルトとして使用される(ただしオーバーライドは可能な)プロパティを定義します。
  3. 最後に、多数の<configuration>要素で、<default-configuration>の名前付きオーバーライドを定義します。

この例では、<application-configuration>がUIXに、c:\yourDirectory\uixFiles\ディレクトリで .uixファイルを検索するように指示しています。 (これによってUIXがイメージ、JavaScriptライブラリなどを検索する場所に影響はありません。UIXファイルのみです。) キャッシュされたバージョンを削除してファイルを再ロードできるように、UIXがファイルの変更時に注意を払うことも指示しています。これによってデバッグがはるかに容易になりますが、パフォーマンスへの影響はわずかです。 最後に、1つのテンプレート・ライブラリを登録しました。これによってUIXユーザーは各ページでライブラリを手動でインポートする必要がなくなります。

次に、<default-configuration>は2つのプロパティを設定します。 最初に、UIXのインストール可能ファイルがあるルート・ディレクトリの<base-path>を変更します。 次に、Oracle Help for the Web(OHW)サーブレットの示唆によりUIXを指し示します。これらの数行のみで、すべてのUIXページが状況依存ヘルプをサポートするようになります。 (Oracle Help for the Webは、オラクル社が無償で提供している強力なWebベースのヘルプです。 詳細は、Oracle Technology Networkを参照してください。)

最後に、アクセシビリティ・サポートのレベルを調整するため、2つの名前付き<configuration>オプションを追加します。 1つのオプションはアクセシビリティ機能を使用不可にし、もう1つのオプションはアクセシビリティをデフォルトよりも拡張します。 これらの構成によって特定のユーザー向けに出力を調整できますが、ユーザーが(設定ページなどで)取得する環境は依然としてアプリケーションに依存します。 また、これらの<configuration>の選択肢は両方とも<default-configuration>で設定された値をそれぞれ継承するため、OHWサーバーまたはベース・パスを再指定する必要はありません。

<application-configuration>の編集

<application-configuration>要素はいくつかの子をサポートします。 これらの子の順序は意味を持っています。 これらは、ここで記述されるとおりに組み込まれる必要があります。

デバッグ機能の使用可能化

UIXでは、デバッグ時に有効にできるいくつかの機能が提供されていますが、これはアプリケーションのデプロイ時には使用しないでください(デプロイされたアプリケーションで問題をデバッグすることが必要な場合以外)。 UIXでデバッグ・モードを有効にするには、<application-configuration>のdebug属性をtrueに設定します。

   <application-configuration debug="true">
     <debug-indent-output>true</debug-indent-output>
   </application-configuration>

debug-で始まる名前の要素はすべてデバッグ・モードのみの設定とみなされ、デバッグが明示的に有効にされていないかぎり、無視されます。 これによって開発者は一連のデバッグ機能を選択でき、それを迅速に有効または無効にできます。

個別に有効または無効にできる機能の他に、UIXはデバッグ・モードになると自動的にある機能を使用可能にします。

<default-configuration>要素および<configuration>要素の編集

<default-configuration>要素および<configuration>要素はいくつかの子をサポートします。 これらの子の順序に意味はありませんが、<default-configuration>を組み込む場合は、すべての<configuration>要素の前に配置します。

リソース・ディレクトリ要素

構成ファイルは7つのUIXリソース・ディレクトリのいずれにも設定できます。これらのディレクトリは「UIXリソース・ファイル」で列記および説明しました。これらの要素の使用については「UIXリソースの場所の変更」で後述します。

デフォルト以外のConfigurationの使用方法

レンダリング時にConfigurationインスタンスを指定しない場合、アプリケーションではデフォルトの構成が使用されます。 または、すべてのページのレンダリングにアプリケーション固有の1つのConfigurationインスタンスが使用されるか、レンダリングごとに少数のインスタンスの中から選択されます。 たとえば、ターゲットのコンテンツ・タイプ(HTMLまたはWML)に応じて異なるConfigurationインスタンスが使用される場合や、ホストされるアプリケーション環境内の異なる顧客にカスタム構成が提供される場合などがあります。

UIXサーブレットを使用する場合、UIXPageBroker.getConfigurationNameメソッドをオーバーライドするリクエストごとにConfigurationを指定できます。


  protected String getConfigurationName(
    BajaContext context,
    Page page)
  {
    if (_doIWantMyOtherConfig(...))
      return "MyOtherConfig";
    return "MyConfig";
  }

UIX Servletを使用しない開発者の場合、(uix-config.xmlまたはJavaのどちらかで)Configurationインスタンスが構成され登録されていると、UIX ComponentsのRenderingContextsetConfiguration()をコールすることによってレンダリング時に使用できます。 UIX ComponentsのBaseRenderingContextには、setConfiguration()のオーバーロードが2つ用意されています。1つはConfigurationインスタンスを受け取り、もう1つはConfiguration名を受け取ります。

ConfigurationImplインスタンスの作成

アプリケーションでJavaのデフォルトの構成値をオーバーライドする必要がある場合、独自のConfigurationImplインスタンスを作成します。 構成を作成するには、次の3つの手順に従います。

  1. 新規ConfigurationImplインスタンスを作成します。
  2. このインスタンスに、アプリケーション固有のURL、パスおよびプロパティを設定します。
  3. インスタンスを登録します。

これらの手順は1回のみ実行されます。 次の例は、アプリケーション固有のConfigurationImplインスタンスを作成し、登録する方法を示しています。

// Create the ConfigurationImpl instance, specifying a unique name
ConfigurationImpl config = new ConfigurationImpl("iProductConfig");

// Configure the instance with application-specific values
config.putRelativeURI(Configuration.BASE_DIRECTORY, "/iProduct/cabo/");

ServletContext context = _getAServletContext();
// Register the instance
config.register(context);

ConfigurationImplインスタンスに一意の名前を指定し、Configuration.register(ServletContext)メソッドをコールして登録します。 (UIXではregister()メソッドによるグローバルな構成の登録もサポートされていますが、これはお薦めしません。) これは、UIXのプライベートJSPが使用された場合に、ブラウザとのラウンドトリップによって構成設定が消失することを防ぐために必要です。

UIXリソースの場所の変更

UIXリソース・ファイルのデフォルトの場所では、他のアプリケーションのリソース・ファイル名との競合が回避されますが、UIXのリソースをまとめて別の場所に移動することが有効な場合があります。 たとえば、複数のUIXアプリケーションがインストールされている環境では、アプリケーションごとにUIXリソースのコピーを保持することが有益です。 こうすれば、1つのアプリケーションでUIXの新規バージョンにアップグレードしても、他のアプリケーションで使用されているUIXリソース・ファイルに影響を与えません。 (独自のサーブレット・コンテキストにインストールされていないアプリケーションなど、別の方法でパーティション化されていないアプリケーションの場合、これは特に重要です。)

UIXリソース・ディレクトリを変更する最も簡単な方法は、ConfigurationImpl.putRelativeURI()メソッドまたは<context-uri> XML要素を使用することです。 このメソッドでは、移動するディレクトリのキー定数、およびディレクトリの新規の相対URLを受け取ります。 次のコードは、1つのリソース・ディレクトリを移動する方法を示しています。


<!-- in UIX XML -->
<jsps-directory>
  <context-uri>/iProduct/cabo/jsps/</context-uri>
<jsps-directory>

// In Java:
config.putRelativeURI(Configuration.JSPS_DIRECTORY, "/iProduct/cabo/jsps/");

この変更の結果、UIX Componentsでは、JSPファイルの参照時にURLが<context path>/iProduct/cabo/jsps/という形式で生成されます。 アプリケーションでは、UIX ComponentsのJSPが、ファイル・システムの対応するディレクトリにインストールされている必要があります。

UIXリソース・ディレクトリの構造は、階層構造です。 親ディレクトリの場所を変更すると、子ディレクトリの場所も移動します。 たとえば、次のコードでは、IMAGES_DIRECTORYと、子のIMAGES_CACHE_DIRECTORYの両方が変更されます。


<!-- in UIX XML: -->
<images-directory>
  <context-uri>/iProduct/images/</context-uri>
</images-directory>

// In Java:
config.putRelativeURI(Configuration.IMAGES_DIRECTORY, "/iProduct/images/");

その結果、UIX Componentsのイメージは、/iProduct/images/の対応するディレクトリにインストールされます。 IMAGES_CACHE_DIRECTORYが明示的に指定されていない場合、UIX Dynamic Imagesで生成されるイメージは、/iProduct/images/cacheの対応するサブディレクトリに作成されます。

同様に、すべてのUIXリソース・ディレクトリは、putRelativeURI()を1回コールして、BASE_DIRECTORYの値を変更すること(または<base-directory>要素を使用すること)で移動できます。

フルパスの使用

これまでに示した例ではすべて、サーブレットのコンテキスト・パスと相対的に解決される相対URLを使用しました。 この他に、ConfigurationImpl.putFullURIAndPath()か、<full-uri>および<full-path>要素の両方を使用して、絶対位置を指定する方法があります。 絶対位置は、マシン間でUIXリソースを共有する場合、または他のWebサーバーに処理をオフロードする場合に便利です。 たとえば、次の例は、イメージがセカンダリWebサーバーで処理されるようUIXを構成する方法を示しています。


<!-- in UIX XML -->
<images-directory>
  <full-path>/net/images/private/httpd/htdocs/cabo/images/</full-path>
  <full-uri>http://images.example.com/cabo/images/</full-uri>
</images-directory>

// In Java:
// The full URI to the images directory on the image server
String fullURI = "http://images.example.com/cabo/images/";

// The full file system path to the auto-mounted images directory
String fullPath = "/net/images/private/httpd/htdocs/cabo/images/";

config.putFullURIAndPath(config.IMAGES_DIRECTORY, fullURI, fullPath);

この構成を使用することにより、UIX Componentsのイメージを参照するすべてのURLはhttp://images.example.com/cabo/images/で始まり、images.example.comのWebサーバーで処理されます。 イメージ・ファイルの処理をセカンダリWebサーバーにオフロードすると、プライマリ・サーバーで必要な処理量が軽減されるため、応答時間を改善できます。 ただし、URLを長くすると、UIX Componentsで参照されるイメージごとに完全なURLが生成されるため、ページ・サイズが大きくなるので注意してください。

実際のパスはマシンによって異なるため、ハードコードされた絶対ファイル・システム・パスをアプリケーションで使用しないでください。 ファイル・システム・パスは、デプロイメント時に構成可能である必要があります。 これは、パスをインストール・プロセスの中で指定できるようにすることで、可能になります。 もしくはフルパスを、(uix-config.xmlなどの)構成ファイルから、またはサーブレットの初期化パラメータを介して取得します。

別名が付けられたApacheのディレクトリ

完全なURLまたはフルパスを使用したカスタム構成が必要なもう1つのケースは、アプリケーションのJSPファイルおよびUIXリソースが、Apache Webサーバー上の別名が付けられたディレクトリにある場合です。 Apacheでは、Webサーバーのドキュメント・ルート外にあるディレクトリに、URLの別名を付けることができます。 たとえば、Apacheのhttpd.conf構成ファイルの次のエントリにより、/HTML/というURLの別名が作成されます。

Alias /HTML/ "/private/html/"

この別名によって、/HTML/で始まるすべてのURLは、/private/html/ディレクトリ下のパスに変換されます。 /private/html/cabo下の別名が付けられたディレクトリにUIXリソースを移動するには、次の構成で十分機能するはずです。


<!-- In XML: -->
<base-directory>
  <context-uri>/HTML/cabo/</context-uri>
</base-directory>

// In Java:
config.putRelativeURI(Configuration.BASE_DIRECTORY, "/HTML/cabo/");

/HTML/に別名が付けられていない場合、この構成は正常に機能します。 ただし、/HTML/に前述のような別名が付けられている場合、この構成では目的とする結果は得られません。 Apacheの別名指定メカニズムは、サーブレット・エンジンによるファイル・システム・パスのレポートに影響します。 そのため、UIX Componentsにより生成されるすべてのHTMLに/HTML/cabo/で始まる正しいURLが含まれていても、UIXにより動的に生成されるイメージおよびスタイルシートは、ファイル・システムの正しい場所に作成されません。 たとえば、このケースでは、本来/private/html/cabo/images/cacheに作成されるIMAGES_CACHE_DIRECTORYが、実際には/private/html/HTML/cabo/images/cacheに作成されます。 最終的には、生成されたイメージおよびスタイルシートのURLが別名の付けられたディレクトリ内の場所と一致せず、イメージは損なわれ、スタイルは欠落することになります。

この問題は、UIXリソースの別名の付けられた場所のフルパスを使用してUIXを構成することにより、回避できます。 次のputFullURIAndPath()へのコールは、このケースで必要な構成を示しています。


<!-- in UIX XML -->
<base-directory>
  <full-uri>/HTML/cabo/>/full-uri>
  <full-path>/private/html/cabo/</full-path>
</base-directory>

// In Java:
config.putFullURIAndPath(Configuration.BASE_DIRECTORY,
                       "/HTML/cabo/",
                       "/private/html/cabo/");

前述の相対URL構成のかわりにこの完全URL構成を使用した場合、UIXでは、動的に生成されたリソースを/private/html/cabo/の下の別名の付けられたディレクトリに正しく配置します。 当然のことながら、マシンによって実際のパスは異なるため、フルパスの/private/html/cabo/はハードコードしないでください。 かわりに、サーブレットAPIのServletContext.getRealPath()を使用し、別名の付けられたディレクトリのフルパスを動的に導出できます。getRealPath()はURLをファイル・システム・パスに変換します。 別名が付けられた/private/html/ディレクトリ内のJSPから次のコードがコールされた場合、正しい構成が作成されます。

// The call to getRealPath("/") will return the root directory of the
// alias, which is "/private/html".
String realPath = servletContext.getRealPath("/");

config.putFullURIAndPath(Configuration.BASE_DIRECTORY,
                       "/HTML/cabo/",
                       realPath + "/cabo/");

UIX Cookieの使用

UIXでは、UIXに影響するユーザーのプロファイルを保持するCookieの使用がサポートされています。 オラクル社は、プライバシおよびセキュリティを重要視しています。Cookieは、サイズが小さく、元のサーバーにのみ限定して送信され、暗号化が必要な情報は含まれません。 現在、Cookieには次の2つの情報のみが含まれます。

Cookieを設定してCookieからプロパティを取得する必要があるクライアントは、oracle.cabo.share.config.UIXCookie Javaクラスを使用して、これらの操作を行います。 Cookieを取得するには、HttpServletRequestおよびHttpServletResponseが必要です。


  HttpServletRequest request = ...;
  HttpServletResponse response = ...;

  // Get the UIX cookie, creating it if it hasn't been set already
  UIXCookie cookie = UIXCookie.getUIXCookie(request, response);
  cookie.setAccessibilityMode(AccessibilityMode.SCREEN_READER_MODE);
  cookie.setTimeZone(TimeZone.getTimeZone("America/Los_Angeles"));

UIXでは、Cookieに設定された値に基づいて、アクセシビリティ・モードおよびタイムゾーンが自動的にデフォルトに設定されます。 必要に応じて(ConfigurationおよびLocaleContextで)これらの値を明示的に設定することもできます。 ただし、UIX Cookieを使用すると、別のページのコードを変更したり、(UIX Cookieは存続期間が非常に長いため)ログインするたびに作業環境を保持することなく、はるかに簡単な方法で、アプリケーションのログイン画面にUIXの基本的な作業環境を追加できます。 たとえば、ログイン・ページに次のコンポーネントを追加すると、アプリケーションのアクセシビリティ・レベルの設定を完全にサポートできます。



   <messageChoice name="access" prompt="Accessibility: ">
     <contents>
       <option text="(None)" value=""/>
       <option text="Default" value="D"/>
       <option text="Disabled" value="I"/>
       <option text="Enhanced" value="S"/>
     </contents>
   </messageChoice>


... ログイン・イベント・ハンドラに次のコードを追加します。



  ...
    AccessibilityMode mode = _decodeAccessibilityMode(
                                       event.getParameter("access"));
    UIXCookie cookie = UIXCookie.getUIXCookie(context.getServletRequest(),
                                              context.getServletResponse());
    cookie.setAccessibilityMode(mode);
  ...


  //
  // Utility for decoding a string value into an AccessibilityMode
  //
  static private AccessibilityMode _decodeAccessibilityMode(String value)
  {
    if ("".equals(value))
      return null;
    else if ("D".equals(value))
      return AccessibilityMode.DEFAULT_MODE;
    else if ("I".equals(value))
      return AccessibilityMode.INACCESSIBLE_MODE;
    else if ("S".equals(value))
      return AccessibilityMode.SCREEN_READER_MODE;

    return null;
  }
}

<messageChoice>"selectedValue"をデータ・バインドし、最後に選択されたアクセシビリティ・モードの値がデフォルトで使用されるようにすることもできます。)

さらに、UIXには、Javaアクセスに対して、ブラウザでJavaScriptを使用するクライアントのタイムゾーンをデフォルト値にリセットするための自動サポートが組み込まれています。これによって、目立たないながらも重要な問題を解決できます。 HTTPプロトコルは、ユーザーの言語やブラウザ・タイプなど、ユーザーに関する多くの情報を提供するヘッダーを送信します。 これにはユーザーのタイムゾーンは含まれていません。 ただし、この情報にはJavaScriptを使用してアクセスできます。 UIXはこれを利用して、(タイムゾーンが明示的に指定されている場合を除き)JavaScriptを使用してアクセス可能な情報を、UIX Cookieに挿入します。 次回のリクエスト時にCookieがサーバーに送信され、これによってサーバーは正しい時刻をユーザーに報告できます。 (Cookieには2回目のリクエスト時までタイムゾーンが設定されません。そのため、ユーザーに対して最初に表示されるタイムゾーンは正しくありません。) このようなサポートが不要な場合、前述のようにWEB-INF/uix-config.xml<disable-uix-cookie>要素を使用することによって使用不可にすることができます。