3 DataSourceリソース定義の使用

DataSourceリソースは、JDBC APIでデータベースを識別してアクセスするために必要な、一連のプロパティを設定するために使用されます。Java EE DataSourceリソース定義の作成方法と使用方法について説明します。

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

DataSourceリソースは、JDBC APIでデータベースを識別してアクセスするために必要な、一連のプロパティを設定するために使用されます。これらのプロパティには、データベース・サーバーのURL、データベースの名前、サーバーとの通信に使用するネットワーク・プロトコルなどの情報が含まれます。アノテーションまたはデプロイメント記述子を使用してデータ・ソース・リソースを作成することによって、データ・ソース定義を宣言できます。

DataSourceオブジェクトは、Java Naming and Directory Interface (JNDI)ネーミング・サービスに登録されます。これにより、アプリケーションがJNDI APIを使用してDataSourceオブジェクトにアクセスし、データベースに接続できるようになります。

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

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

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

次のいずれかの方法を使用して、データ・ソース定義をプログラミングで定義できます。

アノテーションを使用する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>
. . .

WebLogic構成属性の使用

Java EE 7定義アノテーション@DataSourceDefinitionでは、構成属性の基本的な標準セットが提供されます。property要素を使用する独自の属性をサポートすることで、WebLogic Serverの豊富な構成属性セットのサポートが拡張されます。

注意:

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

マルチ・データ・ソースの構成には使用できません。マルチ・データ・ソースをEARまたはWARファイルに組み込むことはできません。
@DataSourceDefinitionアノテーション要素とオーバーラップしません。
データ・ソース・レベルの属性nameとversionを含みません。

表3-1に、データ・ソース構成属性のWebLogic Serverの拡張サポートをまとめています。Weblogic.Attribute Nameプロパティ値とWebLogic構成要素をマッピングしています。WebLogic構成要素を使用するDataSourceリソース定義の例は、「Active GridLink DataSourceリソース定義の構成」を参照してください

表3-1 WebLogic構成属性

Weblogic属性名	WebLogic要素
AffinityPolicy	JDBCOracleParams.setAffinityPolicy()
AlgorithmType	JDBCDataSourceParams.setAlgorithmType()
CapacityIncrement	JDBCConnectionPoolParams.setCapacityIncrement()
ConnectionCreationRetryFrequencySeconds	JDBCConnectionPoolParams.setConnectionCreationRetryFrequencySeconds()
ConnectionPoolFailoverCallbackHandler	JDBCDataSourceParams.setConnectionPoolFailoverCallbackHandler()
ConnectionReserveTimeoutSeconds	JDBCConnectionPoolParams.setConnectionReserveTimeoutSeconds()
CredentialMappingEnable	JDBCConnectionPoolParams.setCredentialMappingEnabled()
DataSourceList	JDBCDataSourceParams.setDataSourceList()
DriverInterceptor	JDBCConnectionPoolParams.setDriverInterceptor()
FailoverRequestIfBusy	JDBCDataSourceParams.setFailoverRequestIfBusy()
FanEnabled	JDBCOracleParams.setFanEnabled()
GlobalTransactionsProtocol	JDBCDataSourceParams.setGlobalTransactionsProtocol()
HighestNumWaiters	JDBCConnectionPoolParams.setHighestNumWaiters()
IdentityBasedConnectionPoolingEnabled	JDBCConnectionPoolParams.setIdentityBasedConnectionPoolingEnabled()
IgnoreInUseConnectionsEnabled	JDBCConnectionPoolParams.setIgnoreInUseConnectionsEnabled()
InactiveConnectionTimeoutSeconds	JDBCConnectionPoolParams.setInactiveConnectionTimeoutSeconds()
InitSql	JDBCConnectionPoolParams.setInitSql()
JDBCXADebugLevel	JDBCConnectionPoolParams.setJDBCXADebugLevel()
KeepConnAfterLocalTx	JDBCDataSourceParams.setKeepConnAfterLocalTx()
KeepLogicalConnOpenOnRelease	JDBCXAParams.setKeepLogicalConnOpenOnRelease()
KeepXaConnTillTxComplete	JDBCXAParams.setKeepXaConnTillTxComplete()
LoginDelaySeconds	JDBCConnectionPoolParams.setLoginDelaySeconds()
NeedTxCtxOnClose	JDBCXAParams.setNeedTxCtxOnClose()
NewXaConnForCommit	JDBCXAParams.setNewXaConnForCommit()
OnsNodeList	JDBCOracleParams.setOnsNodeList()
OnsWalletFile	JDBCOracleParams.setOnsWalletFile()
OnsWalletPassword	JDBCOracleParams.setOnsWalletPassword()
OracleOptimizeUtf8Conversion	JDBCOracleParams.setOracleOptimizeUtf8Conversion()
PasswordEncrypted	JDBCDriverParams.setPassword
PinnedToThread	JDBCConnectionPoolParams.setPinnedToThread()
ProfileHarvestFrequencySeconds	JDBCConnectionPoolParams.setProfileHarvestFrequencySeconds()
ProfileType	JDBCConnectionPoolParams.setProfileType()
RecoverOnlyOnce	JDBCXAParams.setRecoverOnlyOnce()
RemoveInfectedConnections	JDBCConnectionPoolParams.setRemoveInfectedConnections()
ResourceHealthMonitoring	JDBCXAParams.setResourceHealthMonitoring()
RollbackLocalTxUponConnClose	JDBCXAParams.setRollbackLocalTxUponConnClose()
RowPrefetch	JDBCDataSourceParams.setRowPrefetch()
RowPrefetchSize	JDBCDataSourceParams.setRowPrefetchSize()
SecondsToTrustAnIdlePoolConnection	JDBCConnectionPoolParams.setSecondsToTrustAnIdlePoolConnection()
ShrinkFrequencySeconds	JDBCConnectionPoolParams.setShrinkFrequencySeconds()
StatementCacheSize	JDBCConnectionPoolParams.setStatementCacheSize()
StatementCacheType	JDBCConnectionPoolParams.setStatementCacheType()
StatementTimeout	JDBCConnectionPoolParams.setStatementTimeout()
StreamChunkSize	JDBCDataSourceParams.setStreamChunkSize()
TestConnectionsOnReserve	JDBCConnectionPoolParams.setTestConnectionsOnReserve()
TestFrequencySeconds	JDBCConnectionPoolParams.setTestFrequencySeconds()
TestTableName	JDBCConnectionPoolParams.setTestTableName()
UsePasswordIndirection	JDBCDriverParams.setUsePasswordIndirection()
UseXaDataSourceInterface	JDBCDriverParams.setUseXaDataSourceInterface()
WrapTypes	JDBCConnectionPoolParams.setWrapTypes()
XaEndOnlyOnce	JDBCXAParams.setXaEndOnlyOnce()
XaRetryDurationSeconds	JDBCXAParams.setXaRetryDurationSeconds()
XaRetryIntervalSeconds	JDBCXAParams.setXaRetryIntervalSeconds()
XaSetTransactionTimeout	JDBCXAParams.setXaSetTransactionTimeout()
XaTransactionTimeout	JDBCXAParams.setXaTransactionTimeout()

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

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

命名規則

ここでは、データ・ソースの命名規則について説明します。

注意:

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

WebLogicデータ・ソースの命名規則

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

dsname: システム・リソースのJDBC記述子(config/jdbc/*-jdbc.xml)
application@null@dsname - 非推奨 (9.x以前)、EARのアプリケーション・スコープのJDBC記述子
application@module@dsname - EARのアプリケーションスコープのパッケージ化JDBC記述子

Java EEデータ・ソースの命名規則

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

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

Java EEの名前はjava:で始まるため、これらの名前には以前の名前との互換性があります。

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

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

表3-2 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	不使用

Active GridLink DataSourceリソース定義の構成

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

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

次の例は、デプロイメント記述子を使用したActive 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>password</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.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データ・ソースの管理のActive GridLinkデータ・ソースの使用を参照してください。

DataSourceDefinitionでの暗号化パスワードの使用

DataSourceDefinitionで暗号化パスワードを提供できます。そのためには、次の例で示すようにパスワードを生成し、DataSourceDefinitionにコピーする必要があります。

# needs to be run in the domain home directory
java weblogic.security.Encrypt
Password:  mypassword
{AES}OQ1CnXWsgTVQsxrHqpxMT7iZwt7wBBIrkLP5NWeAvNk="
# This value needs to be pasted into the DataSourceDefinition

暗号化パスワードはドメインごとに異なります。ドメインと一致しない暗号化パスワードを使用すると、次のようなエラーが発生します。

weblogic.application.ModuleException: com.rsa.jsafe.JSAFE_PaddingException:
 Invalid padding.:com.rsa.jsafe.JSAFE_PaddingException:Invalid padding

次のコードは、Javaサーブレッドのアノテーションで暗号化パスワードを使用してデータ・ソースを定義します。

@DataSourceDefinition(
name="java:comp/ds",
className="oracle.jdbc.OracleDriver",
portNumber=1521,
serverName="myhost",
user="myuser",
databaseName="mydbname",
initialPoolSize = 0,
minPoolSize = 0,
maxPoolSize = 15,
maxStatements = 0,
transactional=false,
properties = {"weblogic.TestTableName=SQL ISVALID",
 "weblogic.PasswordEncrypted={AES}OQ1CnXWsgTVQsxrHqpxMT7iZwt7wBBIrkLP5NWeAvNk="}
)
@WebServlet(urlPatterns = "/GetVersion")
public class GetVersion extends javax.servlet.http.HttpServlet
  implements javax.servlet.Servlet {
  @Resource(lookup = "java:comp/ds")
  private DataSource ds;

追加の考慮事項

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

アノテーションと記述子の同じDataSource名が同じスコープにある場合、属性はデプロイメント記述子に指定された値とマージされます。デプロイメント記述子の値は、アノテーションに指定された値よりも優先されます。
DataSourceはモジュールではありません。モジュールの一部として作成されるリソースです。
DataSourceは、ドメインに関連付けられたJDBCSystemResourcesオブジェクトではありません。また、WebLogic Server構成beanツリーにはありません。
JSR88 APIを使用して、Java EE 7データ・ソースを含むアプリケーションを表示できます。
各データ・ソース定義にはランタイムMBeanが1つ作成されます。このMBeanには修飾された名前が使用されます。
WLSでURLを生成できる既知のクラス名は限られています。非XAの場合、JDBCドライバや非データソースのクラスがよく知られています。databaseName、portNumber、またはserverNameに不明なクラス名を指定するとエラーが発生します。この場合は、databaseName、portNumber、またはserverNameを削除してURLを指定します。
AGLデータ・ソースに対するURLの生成はサポートされていません。
URLの生成は一般に、そのサービス、データベースおよびOracle RACインスタンスの形式に起因して、すべてのOracleドライバで問題になります。OracleドライバのURLを指定することが最善の方法です。

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

WebLogic Serverを使用して、Java EEクライアントにJava EEデータ・ソースを実装できます(いくつかの制限事項あり)。

制限事項は次のとおりです。

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

その他の情報源

データ・ソース・リソース定義を実装するときに参照するその他の情報源について説明します。

『Java EE 7 Specification』の項EE.5.17「DataSource Resource Definition」(http://jcp.org/en/jsr/detail?id=316)
『Java EE 7 Tutorial』(http://docs.oracle.com/javaee/6/tutorial/doc/)
JDBC(tm) 4.1 Specification (http://download.oracle.com/otn-pub/jcp/jdbc-4_1-mrel-spec/jdbc4.1-fr-spec.pdf)
WebLogic Serverコード例。