<session>要素

<session>要素にはTopLinkセッションに対する構成情報が含まれています。この要素にはセッションのオプションを指定するいくつかのタグがあります。セッションXMLファイルには通常、少なくとも1つの<session>要素があり、アプリケーションで必要な場合は複数の要素指定も可能です。

<session>表B-1にリスト表示されている構成タグをサポートします。

表B-1 <session>要素内のタグ

タグ 説明
<name> セッションの名前を指定します。セッションXMLファイルの各セッションに一意の名前を割り当てて、SessionManagerがセッションを正しく取得できるようにします。<name>タグは必須です。
<project-class> TopLinkプロジェクト・メタデータを含むクラスの名前を指定します。エクスポートおよびコンパイルされたJavaコードを使用するプロジェクトをデプロイするには、(<project-xml>タグではなく)このタグを使用します。完全修飾Javaクラス名を指定しますが、.classまたは.java拡張子はクラス名に入れないでください。
<project-xml> TopLinkプロジェクト・メタデータを含むXMLファイルの名前を指定します。エクスポートされたXMLファイルを使用するプロジェクトをデプロイするには、(<project-class>タグではなく)このタグを使用します。.xml拡張子を含めて完全修飾ファイル名を指定します。

例B-2 プロジェクト・クラスの使用

<toplink-configuration>
    <session>
        <name>mysession</name>
        <project-class>com.mycompany.MyProject</project-class>
        ...
    </session>
</toplink-configuration>

例B-3 プロジェクトXMLの使用

<toplink-configuration>
    <session>
        <name>mysession</name>
        <project-xml>C:/myproject/myproject.xml</project-xml>
        ...
    </session>
</toplink-configuration>

これらのタグ以外に、<session>要素にはセッション構成情報を示すいくつかのタグがあります。リストには次のようなライブラリが含まれます。


関連項目

セッションXMLファイルのナビゲート
XMLヘッダー
<toplink-configuration>要素
<session-broker>要素
JTA構成

<session-type>要素

<session-type>要素は<session>要素の内側に示され、次のタグでセッション・タイプを指定します。

表B-2 <session-type>要素内のタグ

タグ 説明
<session-type> SessionManagerがインスタンス化するTopLinkセッションのタイプを指定します。有効なオプションには<server-session/>および<database-session/>があります。<session-type>タグは必須です。
<server-session/> project-type要素で使用され、SessionManagerが名前付きセッションをServerSession(サーバー)としてインスタンス化して返すことを示します。
<database-session/> project-type要素で使用され、SessionManagerが名前付きセッションをDatabaseSessionとしてインスタンス化して返すことを示します。

例B-4 ServerSessionの定義

<session>
    <name>myServerSession</name>
    <project-class>com.mycompany.MyProject</project-class>
    <session-type>
        <server-session/>
    </session-type>
    ...
</session>

例B-5 DatabaseSessionの定義

<session>
    <name>myDatabaseSession</name>
    <project-class>com.mycompany.MyProject</project-class>
    <session-type>
        <database-session/>
    </session-type>
    ...
</session>

<login>要素

<login>要素はセッションのオプションです。セッションXMLファイルに<login>要素を含めない場合は、TopLinkマッピング・エディタでデフォルトのログインを設定する必要があります。

表B-3 <login>要素内の基本構成タグ

タグ 説明
<driver-class> データベースにログインするためのJDBCドライバ・クラスを指定します。<driver-class>タグはオプションであり、<data-source>タグを実装する場合は不要です。
<connection-url> データベースに対するJDBC接続URLを指定します。このタグはオプションです。<data-source>タグを実装する場合は<connection-url>タグを使用しないでください。
<data-source> JNDIデータソースを使用している場合はデータソース名を指定します。このタグはオプションです。<connection-url>および<driver-class>タグを実装する場合は<data-source>タグを使用しないでください。
<platform-class> セッションに対するTopLinkプラットフォーム・クラスを指定します。このタグはオプションです。
<user-name> データベースにログインするためのユーザー名。<user-name>タグはオプションであり、データソースを使用する場合は不要です。
<password> データベースにログインするためのパスワード。<password>タグはオプションであり、データソースを使用する場合は不要です。

例B-6 JDBCを使用した基本構成

<session>
  <name>myServerSession</name>
  <project-class>com.mycompany.MyProject</project-class>
  <session-type>
    <server-session/>
  </session-type>
  <login>
    <license-path>C:/myproject/license/</license-path>
    <driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
    <connection-url>jdbc:oracle:thin@dbserver:1521:dbname</connection-url>
    <platform-class>oracle.toplink.internal.databaseaccess.OraclePlatform</platform-class>
    <user-name>scott</user-name>
    <password>tiger</password>
  </login>
...
</session>

例B-7 データソースを使用した基本構成

<session>
  <name>myServerSession</name>
  <project-class>com.mycompany.MyProject</project-class>
  <session-type>
    <server-session/>
  </session-type>
  <login>
    <data-source>jdbc/MyApplicationDS</data-source>
    <platform-class>oracle.toplink.internal.databaseaccess.OraclePlatform</platform-class>
  </login>
...
</session>

オプションの<login>タグ

<login>要素には、セッション・ログインをカスタマイズできるオプションのタグがいくつかあります。オプションの<login>タグは通常、有効な値としてTRUEまたはFALSEを受け取ります。表B-4はこれらのタグを説明しています。

表B-4 <login>要素内のオプション・タグ

タグ 説明
<should-bind-all-parameters> すべてのパラメータに対するパラメータ・バインディングを使用可能にします。文キャッシングによるパラメータ・バインディングを使用します。デフォルト値はFALSEです。
<should-cache-all-statements> 文キャッシングを使用可能にします。デフォルト値はFALSEです。文キャッシングでは<should-bind-all-parameters>タグをTRUEに設定することが必要です。
<uses-byte-array-binding> TopLinkでバイト配列にバインディングを使用するかどうか指定します。デフォルト値はFALSEです。
<uses-string-binding> TopLinkで文オブジェクトにバインディングを使用するかどうか指定します。デフォルト値はFALSEです。
<uses-streams-for-binding> TopLinkでバイト配列パラメータのバインディングにストリームを使用するかどうか指定します。デフォルト値はFALSEです。
<should-force-field-names-to-uppercase> TopLinkでSQL生成時にフィールド名を大文字に変換するかどうか指定します。デフォルト値はFALSEです。
<should-optimize-data-conversion> セッションでドライバレベルのデータ変換を最適化するかどうか指定します。デフォルト値はTRUEです。
<should-trim-strings> TopLinkで文字列から末尾の空白を削除するかどうか指定します。デフォルト値はTRUEです。
<uses-batch-writing> セッションでデータベースへの書込みにバッチ書込みを使用するかどうか指定します。デフォルト値はFALSEです。
<uses-jdbc20-batch-writing> セッションのデータベース接続で、JDBC 2.0バッチ書込みまたはTopLinkバッチ書込みのどちらを使用するか指定します。デフォルト値はTRUEです。このオプションを使用可能にする場合は、<uses-batch-writing>オプションも使用可能にします。
<uses-external-connection-pool> セッションで外部接続プールを使用するかどうか指定します。デフォルト値はFALSEです。
<uses-native-sql> セッションでデータベース固有のSQL文法を使用するかどうか指定します。デフォルト値はFALSEです。
<uses-external-transaction-controller> セッションで外部トランザクション・コントローラを使用するかどうか指定します。デフォルト値はFALSEです。
<non-jts-connection-url 接続プールを順序付けするためのURLを指定します。<uses-sequence-connection-pool>タグをTRUEに設定する際に<non-jts-datasource>タグとともに使用されます。
<non-jts-datasource> 接続プールを順序付けするためのJTS以外のデータソースを指定します。<uses-sequence-connection-pool>タグをTRUEに設定する際に<non-jts-connection-url>タグとともに使用されます。
<uses-sequence-connection-pool> セッションで順序付けのため別の接続プールを作成し使用するかどうか指定します。デフォルト値はFALSEです。この要素をTRUEに設定した場合は、<non-jts-connection-url>および<non-jts-datasource>タグも構成する必要があります。

login要素にはこの他に2つのオプション・タグがあります。

順序付け要素

セッション・ログインの一部として順序付けを構成できます(必須ではありません)。セッションXMLファイルで順序付けを構成しない場合は、TopLinkマッピング・エディタで指定された構成がアプリケーションで使用されます。

特定のセッションにカスタム順序付けを使用する際はセッションXMLで順序付けを構成します。

表B-5には、セッションXMLファイルにおける順序付けの構成に使用する要素がリスト表示されています。これらの要素はすべてオプションです。

表B-5 <login>要素内のオプション順序付け構成タグ

タグ 説明
<uses-native-sequencing> セッションでネイティブ順序付けを使用するかどうか指定します。このタグは値としてTRUEまたはFALSEを受け取ります。デフォルトはFALSEです。一部のデータベース・プラットフォームではネイティブ順序付けをサポートしないので注意してください。
<sequence-preallocation-size> 順序の事前割当てサイズを指定します。ネイティブ順序付けを使用する場合、この値はデータベースで設定された順序の事前割当てサイズと一致する必要があります。デフォルト値は50です。
<sequence-table> 表の順序付けについて、順序表の名前を指定します。デフォルトの名前はSEQUENCEです。
<sequence-name-field> 表の順序付けについて、順序付けオブジェクトの名前を含む順序表内の列を指定します。デフォルトの名前はSEQ_NAMEです。
<sequence-counter-field> 表の順序付けについて、各順序付けオブジェクトに対する現在の順序カウントを格納する順序表内の列を指定します。デフォルトの名前はSEQ_COUNTです。

詳細は「順序付け」を参照してください。

例B-8 ネイティブ順序付けの構成

<session>
    <login>
...
        <uses-native-sequencing>true</uses-native-sequencing>
        <sequence-preallocation-size>50</sequence-preallocation-size>
    </login>
...
</session>

例B-9 表ベースの順序付けの構成

<session>
...
    <login>
        <uses-native-sequencing>false</uses-native-sequencing>
        <sequence-table>SEQUENCE</sequence-table>
        <sequence-name-field>SEQ_NAME</sequence-name-field>
        <sequence-counter-field>SEQ_COUNT</sequence-counter-field>
    </login>
...
</session>

<cache-synchronization-manager>要素

<login>の一部としてキャッシュ同期化を構成します。<cache-synchronization-manager>要素と表B-6にリスト表示されているタグを使用して、アプリケーションに対するキャッシュ同期化を構成します。

表B-6 キャッシュ同期化マネージャ構成タグ  

タグ 説明
<clustering-service> クラスタリング・サービスのクラス名を指定します。このタグはキャッシュ同期化に必要です。
<multicast-port> IPマルチキャスト経由の接続メッセージをリスニングするポートを指定します。必ず、TopLinkキャッシュ同期化グループのすべてのサーバーで同じマルチキャスト・ポートを使用してください。このタグは、<multicast-group-address>要素も使用する場合のみ必要です。デフォルト値は6018です。
<multicast-group-address> IPマルチキャスト経由の接続メッセージを送信するIPアドレスを指定します。必ず、TopLinkキャッシュ同期化グループのすべてのサーバーで同じマルチキャスト・アドレスを使用してください。このタグは、<multicast-port>要素も使用する場合のみ必要です。デフォルト値は226.18.6.18です。
<packet-time-to-live> キャッシュ同期化でパケット伝達を検出するネットワーク回数を指定します。このオプション・タグのデフォルトは2です。
<is-asynchronous> キャッシュ同期化を非同期(TRUE)または同期(FALSE)のどちらで実行するか指定します。このオプション・タグのデフォルトはTRUEです。
<should-remove-connection-on-error> 通信例外がリモート・サーバーで発生した場合に、TopLinkでリモート接続を削除するかどうか指定します。このオプション・タグのデフォルトはFALSEです。
<jndi-user-name> キャッシュ同期化マネージャのJNDIへのバインディングに使用するユーザー名を指定します。アプリケーション・サーバー以外のアプリケーションのJNDIをサポートするには、このタグを使用します。このオプション・タグには<jndi-password>タグが必要です。
<jndi-password> キャッシュ同期化マネージャのJNDIへのバインディングに使用するパスワードを指定します。アプリケーション・サーバー以外のアプリケーションのJNDIをサポートするには、このタグを使用します。このオプション・タグには<jndi-user-name>タグが必要です。
<jms-topic-connection-factory-name> JMSキャッシュ同期化に対するトピック・コネクション・ファクトリの名前を指定します。このタグはJMSキャッシュ同期化を使用する場合のみ必要です。
<jms-topic-name> JMSキャッシュ同期化に対するトピックの名前を指定します。このタグはJMSキャッシュ同期化を使用する場合のみ必要です。
<naming-service-initial-context-factory-name> JNDIにアクセスする初期コンテキスト・ファクトリを指定します。JNDIまたはJMSへの接続でTopLinkにエラーが発生する場合のみこのタグを使用します。
<naming-service-url> キャッシュ同期化をサポートするネーミング・サービスのURLを指定します。この要素の値は、キャッシュ同期化の実装方法によって異なります。
  • JNDIクラスタリング・サービスの場合、これはJNDIサービスのスキーム、ホストIPアドレスおよびポートになります。
  • RMIクラスタリング・サービスの場合、これはRMIレジストリのホストIPアドレスおよびポートになります。
このオプション・タグによって、JNDIクラスタリング・サービスでアプリケーション・サーバー内にキャッシュ同期化を実装する際に発生した問題が解決する場合があります。問題が発生しない場合はこのタグを使用しないでください。

例B-10 キャッシュ同期化マネージャの使用

<session>
...
  <login>
    <cache-synchronization-manager>
      <clustering-service>oracle.toplink.remote.rmi.RMIClusteringService</clustering-service>
      <multicast-port>6020</multicast-port>
      <multicast-group-address>226.18.6.18</multicast-group-address>
      <is-asynchronous>true</is-asynchronous>
      <should-remove-connection-on-error>true</should-remove-connection-on-error>
      <naming-service-url>localhost:1099</naming-service-url>
    </cache-synchronization-manager>
  </login>
...
</session>

<event-listener-class>要素

セッション・イベントの発生をアプリケーションに通知する場合は、イベント・リスナーを使用してイベント通知を登録します。セッションXMLファイルでイベント・リスナーを構成できます。

<event-listener-class>タグを使用すると、oracle.toplink.sessions.SessionEventListenerインタフェースを実装するリスナー・クラスか、oracle.toplink.sessions.SessionEventAdapterクラスを拡張するリスナー・クラスを構成できます。複数の<event-listener-class>タグを記述し、各タグについて実装クラス名を指定することで、複数のイベント・リスナー・クラスを構成できます。

例B-11 コードでのイベント・リスナー・クラスの設定

package examples;
import oracle.toplink.sessions.*;
public class MyEventListener extends SessionEventAdapter {
    public void preLogin(SessionEvent event) {
        Session session = event.getSession();
        /* custom code goes here */
    }
}

例B-12 セッションXMLでのイベント・リスナー・クラスの設定

<session>
    ...
    <event-listener-class>examples.MyEventListener</event-listener-class>
    ...
</session>

TopLinkではexamples.MyEventListenerクラスがセッションに対するSessionEventManagerに登録されます。preLoginイベントがセッションで発生すると、MyEventListenerクラスpreLoginメソッドが起動します。

<profiler-class>要素

TopLinkには、アプリケーションを最適化しパフォーマンス上のボトルネックを識別するために使用できる、プロファイラが用意されています。パフォーマンス・プロファイラを実装するには、<profiler-class>タグを使用してセッションにパフォーマンス・プロファイラを指定します。

例B-13 セッションXMLでのパフォーマンス・プロファイラの実装

<session>
    ...
    <profiler-class>oracle.toplink.tools.profiler.PerformanceProfiler</profiler-class>
    ...
</session>

<profiler-class>タグは、oracle.toplink.sessions.SessionProfilerインタフェースを実装するすべてのクラスをサポートします。このため、プロファイラがoracle.toplink.sessions.SessionProfilerインタフェースを実装していれば、独自のプロファイラをビルドしてセッションに追加することができます。


注意: セッションごとに1つのプロファイラしか実装できません。

<external-transaction-controller-class>要素

システムに外部トランザクション(たとえばJTAの下などに)が含まれる場合は、<external-transaction-controller-class>タグを使用してTopLink外部トランザクション・コントローラを指定します。

外部トランザクション・コントローラを使用するには、セッション・ログインで次の項目を指定します。

<exception-handler-class>要素

<exception-handler-class>タグは、セッションの例外を扱うクラスを指定します。このタグは、oracle.toplink.exceptions.ExceptionHandlerを実装するすべてのクラスをサポートします。

例B-15 コードでの例外ハンドラの構成

package examples;
import oracle.toplink.exceptions.*;
public class MyExceptionHandler implements ExceptionHandler {
   public Object handleException(RuntimeException exception) {
      /*custom code goes here */
   }
}

例B-16 セッションXMLファイルでの例外ハンドラの構成

<session>
  ...
  <exception-handler-class>examples.MyExceptionHandler</exception-handler-class>
  ...
</session>

<connection-pool>要素

セッションXMLファイルの<connection-pool>要素によって、TopLinkアプリケーションに対する1つの接続プールまたは複数の接続プールを明示的に構成できます。セッションの接続プールを構成しない場合、セッションではプロジェクトで定義したデフォルトの接続プールが使用されます。

プロジェクトに対する接続プールの構成の詳細は、「接続プールの使用」を参照してください。

手動で定義した各<connection-pool>についてはログインを定義する必要があります。ログインの構成の詳細は、「<login>要素」を参照してください。

表B-7 <connection-pool>要素タグ

タグ 説明
<is-read-connection-pool> 接続プールで読取り接続(TRUE)-(非トランザクション)または書込み接続(FALSE)-(トランザクション)のどちらを使用するか指定します。<is-read-connection-pool>タグは必須であり、値としてTRUEまたはFALSEを受け取ります。
<name> 接続プールの名前を指定します。名前が既存のTopLink接続プール(デフォルトのTopLink読取りプールなど)と同じ場合は、既存の接続プールが新規の接続プールに置き換えられます。<name>タグは必須です。
<max-connections> 接続プールで使用できるデータベース接続の最大数を指定します。このオプション・タグは整数値を受け取り、デフォルトは10です。
<min-connections> 接続プールで起動時に使用するデータベース接続の最小数を指定します。このオプション・タグは整数値を受け取り、デフォルトは5です。

例B-17 接続プール要素の構成

<session>
...
    <connection-pool>
        <is-read-connection-pool>true</is-read-connection-pool>
        <name>additionalReadPool</name>
        <max-connections>20</max-connections>
        <min-connections>10</min-connections>
        <login>
        ...
        </login>
    </connection-pool>
...
</session>

<enable-logging>要素

セッションのロギングは、明示的に指定しないかぎりTopLinkでは自動的に有効になりません。セッションのロギングを有効にするには、セッションXMLファイルでセッション定義の一部として<enable-logging>要素を指定します。

ロギングを有効にするには、<enable-logging>要素を指定してそれをTRUEに設定します。ロギングを有効にした後、セッションXMLファイルで1つ以上のロギング・オプションを指定することでセッションにおけるロギング動作をカスタマイズできます。使用可能なロギング・オプションは表B-8に示されており、引数としてTRUEまたはFALSEを受け取ります。

表B-8 <enable-logging>オプション・タグ

タグ 説明
<log-debug> セッションで標準ログ・エントリ以外にデバッグ情報を記録するかどうか指定します。
<log-exceptions> セッションで未検出の例外メッセージを記録するかどうか指定します。
<log-exception-stacktrace> セッションで例外スタック・トレースを記録するかどうか指定します。
<print-session> セッションでセッション識別子を記録するかどうか指定します。
<print-thread> セッションでスレッド識別子を記録するかどうか指定します。
<print-connection> セッションで接続識別子を記録するかどうか指定します。
<print-date> セッションで各ログ・エントリの日時を記録するかどうか指定します。

例B-18 ロギングおよびロギング・オプションの構成

<session>
    ...
    <enable-logging>true</enable-logging>
    <logging-options>
        <log-debug>false</log-debug>
        <log-exceptions>true</log-exceptions>
        <log-exception-stacktrace>true</log-exception-stacktrace>
        <print-session>true</print-session>
        <print-thread>false</print-thread>
        <print-connection>true</print-connection>
        <print-date>true</print-date>
    </logging-options>
    ...
</session>

 

Copyright © 1997, 2004, Oracle. All rights reserved.