3 DataSourceリソース定義の使用

この章では、Java EE DataSourceリソース定義の作成方法と使用方法について説明します。

Java EE DataSourceリソース定義の使用
DataSourceリソース定義使用時の実装の考慮事項
クライアントでのデータ・ソースの使用
その他の情報源

Java EE DataSourceリソース定義の使用

DataSourceリソースは、JDBC APIでデータベースを識別してアクセスするために必要な、一連のプロパティを設定するために使用されます。これらのプロパティには、データベース・サーバーのURL、データベースの名前、サーバーとの通信に使用するネットワーク・プロトコルなどの情報が含まれます。DataSourceオブジェクトは、Java Naming and Directory Interface (JNDI)ネーミング・サービスに登録されます。これにより、アプリケーションがJNDI APIを使用してDataSourceオブジェクトにアクセスし、データベースに接続できるようになります。

Java EE 6よりも前は、『Oracle WebLogic Server JDBCデータ・ソースの構成と管理』のWebLogic JDBCリソースの構成に関する項で説明するように、DataSourceリソースは管理者によって作成されていました。Java EE 6では、データベース接続の柔軟性と移植性を向上するためにDataSourceリソースをプログラミングで定義するオプションが提供されます。

DataSourceを一意に識別するname要素がJNDIに登録されます。name要素に指定される値は、ネームスペース・スコープで開始します。Java EE 6には次のスコープがあります。

java:comp: このネームスペースの名前は各コンポーネントで表示されます。
java:module: このネームスペースの名前は、モジュールのすべてのコンポーネント(たとえば、ejb-jar.xmlファイルに定義されたEJBコンポーネント)で共有されます。
java:app: このネームスペースの名前は、アプリケーションのすべてのコンポーネントとモジュール(たとえば、.earファイルのapplication-client、WebおよびEJBコンポーネント)で共有されます。
java:global: このネームスペースの名前はサーバーのすべてのアプリケーションで共有されます。

DataSource定義をプログラミングで定義するには、次のいずれかの方法を使用します。

アノテーションを使用するDataSourceリソース定義の作成
デプロイメント記述子を使用するDataSourceリソース定義の作成

アノテーションを使用するDataSourceリソース定義の作成

javax.annotation.sqlパッケージでは、アプリケーション・クライアント、サーブレットまたはEnterprise JavaBeans (EJB)などのアプリケーション・コンポーネント・クラスにDataSourceリソース定義を定義するために、@DataSourceDefinitionと@DataSourceDefinitionsが提供されます。

DataSourceリソースがインジェクトされると、DataSourceオブジェクトが作成され、JNDIに登録されます。アノテーション要素を使用してDataSourceオブジェクトを構成します。その他のJava EE and WebLogic構成属性は、アノテーションのproperties要素に指定できます。「WebLogic構成属性の使用」を参照してください。

@DataSourceDefinitionを使用して1つのdatasource定義を作成します。例:

. . .

@DataSourceDefinition(
name = "java:module/ExampleDS",
     className = "org.apache.derby.jdbc.ClientDataSource",
     portNumber = 1527,
     serverName = "localhost",
     databaseName = "exampleDB",
     user = "examples",
     password = "examples",
     properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"})

@WebServlet("/dataSourceServlet")
public class DataSourceServlet extends HttpServlet {
 
 . . .
 
  @Resource(lookup = "java:module/ExampleDS")

. . .

@DataSourceDefinitionsを使用して複数のdatasource定義を作成します。例:

. . .

@DataSourceDefinitions(
      value = {
 
        @DataSourceDefinition(name = "java:app/env/DS1",
           minPoolSize = 0,
           initialPoolSize = 0,
           className = "org.apache.derby.jdbc.ClientXADataSource",
           portNumber = 1527,
           serverName = "localhost",
           user = "examples",
           password = "examples",
           databaseName = "exampleDB",
           properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"}
                   ),
 
        @DataSourceDefinition(name = "java:comp/env/DS2",
           minPoolSize = 0,
           initialPoolSize = 0,
           className = "org.apache.derby.jdbc.ClientDataSource",
           portNumber = 1527,
           serverName = "localhost",
           user = "examples",
           password = "examples",
           databaseName = "examplesDB",
           properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"}
        )
      }
   )

. . .

サンプル全体は、WebLogic Serverコード例の@DataSourceDefinitionアノテーションを使用するDataSourceの作成に関する項を参照してください。

デプロイメント記述子を使用するDataSourceリソース定義の作成

application.xml、application-client.xml、web.xmlおよびejb-jar.xmlファイルでデプロイメント記述子を使用して、DataSourceリソース定義を作成できます。例:

. . .

 <data-source>
     <name>java:module/ExampleDS</name>
     <class-name>org.apache.derby.jdbc.ClientDataSource</class-name>
     <server-name>localhost</server-name>
     <port-number>1527</port-number>
     <database-name>exampleDB</database-name>
     <user>examples</user>
     <password>examples</password>
     <property>
       <name>create</name>
       <value>true</value>
     </property>
     <property>
       <name>weblogic.TestTableName</name>
       <value>SQL SELECT 1 FROM SYS.SYSTABLES</value>
     </property>
   </data-source>
. . .

DataSourceリソース定義使用時の実装の考慮事項

次の項では、DataSourceリソース定義を作成および使用するときに考慮する必要がある実装の詳細について説明します。

ネーミング・ルール
Java EE DataSourceリソース定義とWebLogicデータ・ソース・リソースのマッピング
WebLogic構成属性の使用
GridLink DataSourceリソース定義の構成
追加の考慮事項

ネーミング・ルール

ここでは、データ・ソースのネーミング・ルールについて説明します。

注意:

WebLogic Server 12.1.1よりも前のバージョンとJava EE データ・ソースのネーミング・ルールには互換性があります。既存のアプリケーションは、以前のリリースからアップグレードするためにネーミング・ルールを変更する必要はありません。

WebLogicデータ・ソースのネーミング・ルール

WebLogic Server 12.1.1よりも前のリリースでのデータ・ソースの名前には次のルールが使用されます。

dsname: システム・リソースのJDBC記述子(config/jdbc/*-jdbc.xml)
module@dsname: スタンドアロン・アプリケーション・スコープのJDBC記述子
application@module@dsname: EAR内のアプリケーション・スコープのJDBC記述子

Java EEデータ・ソースのネーミング・ルール

Java EEデータ・ソースの名前には次のルールが使用されます。

appname@modulename@componentname@dsname: コンポーネント・レベル
appname@modulename@dsname: モジュール・レベル
appname@dsname: アプリケーション・レベル
dsname: グローバル

Java EE DataSourceリソース定義とWebLogicデータ・ソース・リソースのマッピング

表3-1は、Java EE DataSourceリソース定義の要素とWebLogic Serverリソースをどのようにマッピングするかを示します。

表3-1 DataSourceリソース定義とWebLogic Serverリソースのマッピング

DataSourceBean	デフォルト値	WebLogicリソース
String name()	必須	JDBCDataSourceParamsBean.setJndiName
String className()	必須	JDBCDriverParamsBean.setDriverName
String description()	""	不使用
String url()	""	JDBCDriverParamsBean.setUrl
String user()	""	JDBCDriverParamsBean.getProperties()に追加
String password()	""	JDBCDriverParamsBean.setPassword
String databaseName()	""	URLの生成に使用(`properties`に追加)
int portNumber()	-1	URLの生成に使用(`properties`に追加)
String serverName()	"localhost"	URLの生成に使用(`properties`に追加)
int isolationLevel()	-1	WebLogic Serverが`Connection.setTransactionIsolation()`を呼び出すために使用する`desiredtxisolevel`プロパティを設定
boolean transactional()	true	URLの生成に使用
int initialPoolSize()	-1	JDBCConnectionPoolParamsBean.setInitialCapacity
int maxPoolSize()	-1	JDBCConnectionPoolParamsBean.setMaxCapacity
int minPoolSize()	-1	JDBCConnectionPoolParamsBean.setMinCapacity (新規)
int maxIdleTime()	-1	JDBCConnectionPoolParamsBean.setShrinkFrequencySeconds
int maxStatements()	-1	JDBCConnectionPoolParamsBean.setStatementCacheSize
String[] properties()	{}	JDBCPropertiesBean
int loginTimeout()	0	不使用

WebLogic構成属性の使用

Java EE 6 @DataSourceDefinitionでは、構成属性の基本的な標準セットが提供されます。Weblogic. Attributeプロパティ値をWebLogic構成要素にマッピングしてWebLogic Server独自の属性をすべてサポートすることで、WebLogic Serverの豊富な構成属性セットのサポートが拡張されます。WebLogic構成要素を使用するDataSourceリソース定義の例は、「GridLink DataSourceリソース定義の構成」を参照してください。

注意:

WebLogic Server独自の属性をproperty要素で使用するときには、次の制限事項に注意してください。WebLogic Server独自の属性の特徴は次のとおりです。

複数データ・ソースではサポートされません。
@DataSourceDefinitionアノテーション要素とオーバーラップしません。「Java EE DataSourceリソース定義とWebLogicデータ・ソース・リソースのマッピング」を参照してください。
データ・ソース・レベルの属性nameとversionを含みません。

GridLink DataSourceリソース定義の構成

GridLinkデータ・ソースは、DataSourceリソース定義で次の名前/値ペアを使用して定義されます。

FanEnabledはtrueに設定されます。
OnsNodeListはnull以外の値です。ONSベースのFANイベントを受信するためのONSデーモン・リスニング・アドレスおよびポートのカンマ区切りのリストです。『Oracle WebLogic Server JDBCデータ・ソースの構成と管理』のONSクライアントの構成に関する項を参照してください。

デプロイメント記述子を使用したGridLinkデータ・ソースのためのDataSourceリソース定義の例を次に示します。

. . .

 <data-source>
    <name>java:global/DSD2</name>
    <class-name>oracle.jdbc.OracleDriver</class-name>
    <url>jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=lcr01155-r)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=mydb)))</url>
    <user>lefty123</user>
    <password>welcome1</password>
    <property><name>weblogic.CapacityIncrement</name><value>2</value></property>
 <property><name>weblogic.HighestNumWaiters</name><value>2147483647</value></property>
    <property><name>weblogic.ConnectionCreationRetryFrequencySeconds</name><value>0</value></property>
    <property><name>weblogic.ConnectionReserveTimeoutSeconds</name><value>10</value></property>
    <property><name>weblogic.TestFrequencySeconds</name><value>120</value></property>
    <property><name>weblogic.TestConnectionsOnReserve</name><value>false</value></property>
    <property><name>weblogic.ProfileHarvestFrequencySeconds</name><value>300</value></property>
    <property><name>weblogic.IgnoreInUseConnectionsEnabled</name><value>true</value></property>
    <property><name>weblogic.InactiveConnectionTimeoutSeconds</name><value>0</value></property>
    <property><name>weblogic.TestTableName</name><value></value></property>
    <property><name>weblogic.LoginDelaySeconds</name><value>0</value></property>
    <property><name>weblogic.InitSql</name><value></value></property>
    <property><name>weblogic.StatementCacheType</name><value>LRU</value></property>
    <property><name>weblogic.RemoveInfectedConnections</name><value>true</value></property>
    <property><name>weblogic.SecondsToTrustAnIdlePoolConnection</name><value>10</value></property>
    <property><name>weblogic.StatementTimeout</name><value>-1</value></property>
    <property><name>weblogic.ProfileType</name><value>0</value></property>
    <property><name>weblogic.JDBCXADebugLevel</name><value>10</value></property>
    <property><name>weblogic.CredentialMappingEnabled</name><value>false</value></property>
    <property><name>weblogic.DriverInterceptor</name><value></value></property>
    <property><name>weblogic.PinnedToThread</name><value>false</value></property>
    <property><name>weblogic.IdentityBasedConnectionPoolingEnabled</name><value>false</value></property>
    <property><name>weblogic.WrapTypes</name><value>true</value></property>
    <property><name>weblogic.ConnectionLabelingCallback</name><value></value></property>
    <property><name>weblogic.FatalErrorCodes</name><value></value></property>
    <property><name>weblogic.Scope</name><value>Global</value></property>
    <property><name>weblogic.RowPrefetch</name><value>false</value></property>
    <property><name>weblogic.RowPrefetchSize</name><value>48</value></property>
    <property><name>weblogic.StreamChunkSize</name><value>256</value></property>
    <property><name>weblogic.AlgorithmType</name><value>Failover</value></property>
    <property><name>weblogic.ConnectionPoolFailoverCallbackHandler</name><value></value></property>
    <property><name>weblogic.FailoverRequestIfBusy</name><value>false</value></property>
    <property><name>weblogic.GlobalTransactionsProtocol</name><value>OnePhaseCommit</value></property>
    <property><name>weblogic.KeepConnAfterLocalTx</name><value>true</value></property>
    <property><name>weblogic.KeepConnAfterGlobalTx</name><value>false</value></property>
    <property><name>weblogic.UseXaDataSourceInterface</name><value>true</value></property>
    <property><name>weblogic.UsePasswordIndirection</name><value>false</value></property>
    <property><name>weblogic.FanEnabled</name><value>true</value></property>
    <property><name>weblogic.OnsNodeList</name><value>lcr01155-r:6200</value></property>
    <property><name>weblogic.OnsWalletFile</name><value></value></property>
    <property><name>weblogic.OnsWalletPassword</name><value></value></property>
    <property><name>weblogic.OracleEnableJavaNetFastPath</name><value>false</value></property>
    <property><name>weblogic.OracleOptimizeUtf8Conversion</name><value>false</value></property>
    <property><name>weblogic.ConnectionInitializationCallback</name><value></value></property>
    <property><name>weblogic.AffinityPolicy</name><value>Session</value></property>
    <property><name>weblogic.OracleProxySession</name><value>false</value></property>
    <property><name>weblogic.KeepXaConnTillTxComplete</name><value>true</value></property>
    <property><name>weblogic.NeedTxCtxOnClose</name><value>false</value></property>
    <property><name>weblogic.XaEndOnlyOnce</name><value>false</value></property>
    <property><name>weblogic.NewXaConnForCommit</name><value>false</value></property>
    <property><name>weblogic.KeepLogicalConnOpenOnRelease</name><value>false</value></property>
    <property><name>weblogic.ResourceHealthMonitoring</name><value>true</value></property>
    <property><name>weblogic.RecoverOnlyOnce</name><value>false</value></property>
    <property><name>weblogic.XaSetTransactionTimeout</name><value>false</value></property>
    <property><name>weblogic.XaTransactionTimeout</name><value>0</value></property>
    <property><name>weblogic.RollbackLocalTxUponConnClose</name><value>false</value></property>
    <property><name>weblogic.XaRetryDurationSeconds</name><value>0</value></property>
    <property><name>weblogic.XaRetryIntervalSeconds</name><value>60</value></property>
  </data-source>
. . .

詳細は、『Oracle WebLogic Server JDBCデータ・ソースの構成と管理』のGridLinkデータ・ソースの使用に関する項を参照してください。

追加の考慮事項

Java EE DataSourceリソース定義をWebLogic Serverで使用する際には次の点を考慮してください。

アノテーションと記述子の同じDataSource名が同じスコープにある場合、属性はデプロイメント記述子に指定された値とマージされます。デプロイメント記述子の値は、アノテーションに指定された値よりも優先されます。
DataSourceはモジュールではありません。モジュールの一部として作成されるリソースです。
DataSourceは、ドメインに関連付けられたJDBCSystemResourcesオブジェクトではありません。また、WebLogic Server構成beanツリーにはありません。
JSR88 APIを使用して、Java EE 6データ・ソースを含むアプリケーションを表示できます。

クライアントでのデータ・ソースの使用

Java EEデータ・ソースをJava EEクライアントに実装できます。ただし、以下の例外があります。

Transactional=trueはサポートされません。トランザクション・プロトコルはNONEに設定されます。
スコープがグローバルまたはアプリケーションのデータ・ソースは、クライアントとサーバーの両方で表示されます(作成されます)。使用する接続数が多い場合には好ましくない影響があります。
データ・ソースに対する権限のチェックは実行されません。reserveやshrinkなどの処理をローカル・データ・ソースに対して使用できます。

その他の情報源

ここでは、DataSourceリソース定義を実装するときに参照する資料を示します。

『Java EE 6 Specification』の項EE.5.17「DataSource Resource Definition」(http://jcp.org/en/jsr/detail?id=316)
『Java EE 6 Tutorial』(http://docs.oracle.com/javaee/6/tutorial/doc/)
WebLogic Serverコード例。