| Oracle® Fusion Middleware Oracle TopLinkデータベースWebサービスによる永続性アーキテクチャの開発 12c (12.1.3) E57541-01 |
|
 前 |
 次 |
この章では、リレーショナル・データベース・アーティファクトへのJava EEに準拠したクライアントニュートラルなアクセスをWebサービスを介して提供するEclipseLink DBWSを紹介および説明します。EclipseLink DBWSでは、既存のORMおよびOXMコンポーネントを利用しながら、EclipseLinkのコア機能を拡張しています。
EclipseLink DBWSには次の2つのコンポーネントがあります。
デザインタイム・コンポーネント: DBWSBuilderのコマンドライン・ユーティリティで、必要なデプロイメント・アーティファクトを生成します。
ランタイム・プロバイダ・コンポーネント: サービス・ディスクリプタを(関連するデプロイメント・アーティファクトとともに)使用して、JAX-WS 2.0 Webサービスとして実現します。ランタイム・プロバイダはEclipseLinkを使用して、Webサービス・クライアントが使用するXML SOAPメッセージとデータベースの間の橋渡しをします。
EclipseLink DBWSサービスには、次のような処理を任意の回数だけ追加することができます。
insert – XMLドキュメントで記述されたデータベース永続エンティティを挿入します。
update – XMLドキュメントで記述されたデータベース永続エンティティを更新します。
delete – XMLドキュメントで記述されたデータベース永続エンティティから削除します。
query – XMLドキュメントで記述されたデータベース永続エンティティから問い合わせます。
問合せ操作への選択条件は、次のものを使用して指定することができます。
カスタムSQL SELECT文
ストアド・プロシージャの起動
EclipseLink Named Query (EclipseLink ORM Expression Framework APIの全範囲を使用可能)
JP-QL
操作で使用されるXMLドキュメントはXMLスキーマ定義(.xsdファイル)に準拠しています。
この章の内容は、次のとおりです。
EclipseLinkのORM機能とOXM機能は、データベースのリレーショナル構造とXMLの階層構造とのギャップを埋める強力な基盤になります。
通常、EclipseLink DBWSサービスはMETA-INFディレクトリ(.warファイルにパッケージされている場合はWEB-INF/classes/META-INF)のサービス・ディスクリプタ・ファイルeclipselink-dbws.xmlとともにアーカイブ(.jarまたは.warファイル)にパッケージされています。 リレーショナル・データベースの世界とXMLの世界を橋渡しするため、EclipseLinkのsessions.xml (eclipselink-dbws-sessions.xml)は、2つのEclipseプロジェクト(1つはORM側、もう1つはOXM側)を指しています。サービスにはXMLスキーマ定義ファイルeclipselink-dbws-schema.xsd(OXMプロジェクトと組み合わせてデータベースからの情報がどのようにXMLドキュメントの形になるかという情報を指定する)も必要です。
|
注意: すべてのファイルが示されているわけではありません。 |
EclipseLink DBWSサービス・ディスクリプタ・ファイルeclipselink-dbws.xmlは、必要最小限の情報と省略されるフィールドの単純なデフォルトのみが記述された読みやすいものです。このため、ユーティリティによる自動生成も手動での編集も可能です。例1-1にDBWSサービス・ディスクリプタ・ファイルの例を示します。
例1-1 DBWSサービス・ディスクリプタ・ファイルの例
<?xml version="1.0" encoding="UTF-8"?> <dbws xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" > <name>example</name> <sessions-file>example-dbws-sessions.xml</sessions-file> <query> <name>countEmployees <result> <type>xsd:int</type> </result> <sql><!--[CDATA[select count(*) from EMP]]--></sql> </query> </dbws>
表1-1に、EclipseLink DBWSサービス・ディスクリプタ・ファイルの要素を示します。
EclipseLink DBWSサービス・スキーマ・ファイルeclipselink-dbws-schema.xsdは手動で作成するか、または設計時にデータベース・メタデータ(列名、型、NULLABLEなど)からXML要素タグ名を導出するDBWSBuilderユーティリティで自動生成することができます。
DBWSBuilderユーティリティでは、問合せ操作によって返される情報に事前定義された構造がない場合はXMLスキーマ定義が生成されません。次に例を示します。
カスタムSQL問合せ操作のresultSet
ストアド・プロシージャの問合せ処理の結果
update操作の行数
このような場合、EclipseLink DBWSランタイム・プロバイダでは、問合せ実行時に利用可能な情報のみを使用してXMLドキュメントを作成します。
例1-2 Simple XML Format (SXF)ドキュメントの例
要素のタグ名は表の列名がそのままコピーされます。
<?xml version = '1.0' encoding = 'UTF-8'?>
<simple-xml-format>
<simple-xml>
<EMPNO>7788</EMPNO>
<ENAME>SCOTT</ENAME>
<JOB>ANALYST</JOB>
<MGR>7566</MGR>
<HIREDATE>1987-04-19T00:00:00.000-0400</HIREDATE>
<SAL>3000</SAL>
<DEPTNO>20</DEPTNO>
</simple-xml>
<simple-xml>
<EMPNO>7369</EMPNO>
<ENAME>SMITH</ENAME>
<JOB>CLERK</JOB>
<MGR>7902</MGR>
<HIREDATE>1980-12-17T00:00:00.000-0400</HIREDATE>
<SAL>800</SAL>
<DEPTNO>20</DEPTNO>
</simple-xml>
</simple-xml-format>
このようなXMLドキュメントは、事前定義されたスキーマに対する検証ができないため処理不能ですが、厳密には次のような非常に許容性のある順不同のスキーマのみがそのようなドキュメントを検証できます。
例1-3 Simple XML Formatスキーマ
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
>
<xsd:complexType name="simple-xml-format">
<xsd:sequence>
<xsd:any minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
要素タグsimple-xml-format とsimple-xmlは、操作時に適切なプロパティを設定することでカスタマイズできます。
例1-4に示すように、DBWS Builder XMLファイルの<property>要素を使用して必要なサーバー・プロパティを定義します。
例1-4 DBWS Builder XMLファイルの例
<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<properties>
<property name="projectName">procedure_test</property>
<property name="logLevel">off</property>
<property name="username">myName</property>
...
</properties>
...
DBWS Builder XMLファイルのその他の例については、例1-5および例1-6を参照してください。
表1-2に有効な<property>値を示します。
表1-2 DBWS Builderファイルのプロパティ
| プロパティ | 説明 |
|---|---|
|
|
DBWSプロジェクトの名前。 デフォルト = |
|
|
TopLinkからログへの書込みの量と詳細。有効な値: 詳細は、『Oracle TopLink Java Persistence API (JPA)拡張機能リファレンス』の「logging.level」を参照してください。 |
|
|
データベースへのログインに使用されるユーザー名。 |
|
|
データベースへのログインに使用される |
|
|
データベースのURL。 |
|
|
データベース・ドライバ。 |
|
|
データベースのプラットフォームを指定します。 デフォルト = |
|
|
生成した型に適用されるターゲットのネームスペースの値。 デフォルト = |
|
|
ORMセッションに適用されるセッション・カスタマイザの名前。 詳細は、『Oracle TopLink Java Persistence API (JPA)拡張機能リファレンス』の「session.customizer」を参照してください。 |
|
|
OXMセッションに適用されるセッション・カスタマイザの名前。 詳細は、『Oracle TopLink Java Persistence API (JPA)拡張機能リファレンス』の「session.customizer」を参照してください。 |
|
|
ターゲットのアプリケーション・サーバーに定義されるデータ・ソースのJNDI名。 |
|
|
生成されたWSDLに設定されるLocation URIの値。 デフォルト = |
WARファイルを生成し、EclipseLink DBWSサービス・ディスクリプタとともに、JAX-WS 2.0 Webサービス(WSDL、XMLスキーマ、web.xml、EclipseLinkオブジェクト・リレーショナル・マッピング(ORM)およびオブジェクトXMLマッピング(OXM)のネイティブ・プロジェクトXMLファイルなど)に必要なすべてのデプロイメント・アーティファクトを含めることができます。
表1-3 EclipseLink DBWSサービスの.warファイルの内容
| ファイル | 説明 |
|---|---|
|
|
Webアプリケーションのデプロイメント・ファイルで、JAX-WS Webサービスとしてデプロイするために必要です。 詳細はJSR-109を参照してください。 |
|
|
EclipseLink DBWSサービス・ディスクリプタ・ファイル(表1-1を参照)。 |
|
|
EclipseLink ORMプロジェクトXMLファイル。 |
|
|
EclipseLink OXMプロジェクトXMLファイル。 |
|
|
EclipseLink DBWSサービスのEclipseLink |
|
|
処理の引数と戻り型のXML型定義を含みます。
|
|
|
EclipseLink DBWSサービスのすべての操作のエントリを含み、JAX-WS Webサービスのデプロイメントに必要とされます。 詳細はJSR-109( |
|
|
SOAP添付ファイルのXML型定義を含みます(オプション)。 |
swaref.xsdとweb.xmlの名前と内容はWebデプロイメントにおける役割で決まるため、修正することはできません。
デプロイ可能な.warファイルは、Oracle WebLogic Server 10.3 JavaEEコンテナで動作することが検証されています。 詳細は、http://www.oracle.com/technology/software/products/ias/htdocs/wls_main.html?rssid=rss_otn_softを参照してください。
代替のデプロイ可能なJARファイルは、JavaSE 6のコンテナレスEndPointとして動作することが検証されています。詳細はhttp://java.sun.com/javase/6/docs/api/javax/xml/ws/Endpoint.htmlおよびhttp://wiki.eclipse.org/EclipseLink/Examples/DBWS/AdvancedJavase6Containerlessを参照してください。
この項では、DBWSBuilderユーティリティを使用してEclipseLink DBWSサービスを作成する方法について説明します。
EclipseLink DBWSのデザインタイム・ユーティリティDBWSBuilderを使用すると、デプロイメント・ファイルを作成することができます。DBWSBuilderは、EclipseLink DBWS BuilderのXMLファイルに記述された操作を処理して、必要なすべてのデプロイメント・アーティファクトを作成するJavaアプリケーションです。
DBWSBuilderを起動する前に<ECLIPSELINK_HOME>\bin\setenv.cmd(またはsetenv.shファイル)で次の環境変数を設定してください。
JAVA_HOME
DRIVER_CLASSPATH
DBWSBuilderを起動するために用意されているスクリプト・ファイルがあります。これらは<ECLIPSELINK_HOME>\utils\dbwsディレクトリにあります。スクリプトはWindows用がdbwsbuilder.cmd、その他のオペレーティング・システム用がdbwsbuilder.shです。ヘルプ情報を表示するには、dbwsbuilder.cmdスクリプト(またはdbwsbuilder.sh)スクリプトを引数なしで実行します。
DBWSBuilderを使用すると、次のソースからEclipseLink DBWSサービスを生成することができます。
既存のリレーショナル・データベース表
1つ以上のSQL SELECT文
ストアド・プロシージャ
EclipseLink DBWSBuilderのXMLファイルは、<table>問合せ操作を次のように使用して作成できます。
例1-5 DBWSBuilder XMLファイルの例
<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<properties>
<property name="projectName">table_test</property>
... database properties ...
</properties>
<table
schemaPattern="%"
tableNamePattern="dbws_crud"
/>
</dbws-builder>
詳細は、「データベース表からのEclipseLink DBWSサービスの作成」を参照してください。
EclipseLink DBWSBuilderのXMLファイルは、<sql>問合せ操作を次のように使用して作成できます。
例1-6 DBWS Builder XMLファイルの例
<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<properties>
<property name="projectName">sql_test</property>
... database properties ...
</properties>
<sql name="employeeInfo" simpleXMLFormatTag="employee-info" xmlTag="aggregate-counts">
<text>
<![CDATA[select count(*) as "COUNT", max(SAL) as "MAX-Salary" from EMP]]>
</text>
</sql>
</dbws-builder>
<sql>操作のSQL SELECT文に、eclipselink-dbws-schema.xsdのデータ型またはなんらかの基本XSDデータ型にバインドする必要があるパラメータを指定する場合があります。SQL SELECTの文字列では、JDBC-style ? マーカーを使用して引数の位置を指定します。<sql>操作では、ネストした<binding>要素を使用してデータ型とパラメータを照合します。<binding>要素が定義された順番とSQL文字列での ? マーカーの順序は一致している必要があります。
<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<properties>
<property name="projectName">sql_binding_test</property>
... database properties ...
</properties>
<sql name="findEmpByName" isCollection="true" isSimpleXMLFormat="true">
<text>
<![CDATA[select * from EMP where EMPNO = ? and LAST_NAME = ?]]>
</text>
<binding name="EMPNO" type="xsd:int"/>
<binding name="LAST_NAME" type="xsd:string"/>
</sql>
</dbws-builder>
EMPNOという引数がinteger型にバインドされ、LAST_NAMEという引数がstring型にバインドされています。
詳細は、「SQL文からのDBWSサービスの作成」を参照してください。
EclipseLink DBWSBuilderのXMLファイルは、<procedure>問合せ操作を例1-7のように使用して作成できます。
例1-7 <procedure>問合せの使用
<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<properties>
<property name="projectName">procedure_test</property>
... database properties ...
</properties>
<procedure
returnType="empType"
catalogPattern="SOME_PKG"
schemaPattern="SCOTT"
procedurePattern="GetEmployeeByEMPNO_DEPTNO"/>
</procedure>
</dbws-builder>
詳細は、「ストアド・プロシージャからの作成」を参照してください。
EclipseLink DBWSサービスをカスタマイズして使用する例は多数あります。事例は次のカテゴリに分類されます。
簡単 – <element-tag>を"attribute"に変更
中程度 – EclipseLinkのORMプロジェクトまたはOXMプロジェクトのカスタマイズ
高度 – 必要なすべてのデプロイメント・アーティファクトを手動で作成
デフォルトでは、DBWSBuilderで生成されたeclipselink-dbws-schema.xsdファイルは、例1-8に示すように、データベース表のメタデータから<element-tag>名を導出します。
例1-8 DBWSBuilderで生成されたeclipselink-dbws-schema.xsdファイル
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
>
<xsd:complexType name="empType">
<xsd:sequence>
<xsd:element name="empno" type="xsd:int" xsi:nil="false"/>
<xsd:element name="ename" type="xsd:string" xsi:nil="true"/>
<xsd:element name="job" type="xsd:string" xsi:nil="true"/>
<xsd:element name="mgr" type="xsd:int" minOccurs="0" xsi:nil="true"/>
<xsd:element name="hiredate" type="xsd:dateTime" xsi:nil="true"/>
<xsd:element name="sal" type="xsd:decimal" xsi:nil="true"/>
<xsd:element name="comm" type="xsd:int" minOccurs="0" xsi:nil="true"/>
<xsd:element name="deptno" type="xsd:int" xsi:nil="true"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<element>タグを属性に変更するには、例1-9に示すようにNamingConventionTransformerを使用します。
EclipseLinkのSessionCustomizerを使用する大きな理由は、EclipseLink APIにプログラム上のアクセスが可能になるためです。このAPIを使用することで、セッションからオブジェクトリレーショナルまたはオブジェクトXMLのマッピング・ディスクリプタを取得することができるため、これらのディスクリプタを使用してマッピングへの追加、変更および削除を行います。セッション・キャッシュをオフにするか、またはデータベース接続のトランザクションの分離レベルを変更することも検討します。
次の例は、org.eclipse.persistence.config.SessionCustomizerの実装方法を示しています。
package some.java.package;
import org.eclipse.persistence.config.SessionCustomizer;
import org.eclipse.persistence.sessions.Session;
import org.eclipse.persistence.sessions.DatabaseLogin;
public class MySessionCustomizer implements SessionCustomizer {
public MySessionCustomizer() {
}
public void customize(Sesssion session) {
DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin();
login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED);
}
}
DBWSBuilderのXMLファイルで、そのカスタマイズをORMプロジェクトに適用するかOXMプロジェクトに適用するかを、次の例に示すように指定します。
<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<properties>
<property name="projectName">customize_test</property>
...
<property name="orSessionCustomizerClassName">some.java.package.MyORSessionCustomizer</property>
または
<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<properties>
<property name="projectName">customize_test</property>
...
<property name="oxSessionCustomizerClassName">some.java.package.MyOXSessionCustomizer</property>
詳細は、『Oracle TopLinkの理解』の「セッション」を参照してください。
project.xmlファイルとsessions.xmlファイルを作成することで、EclipseLink DBWSサービスをカスタマイズできます。任意のユーティリティを使用して、次の操作を実行します。
オブジェクトをEclipseLinkリレーショナル・プロジェクトのリレーショナル・データベースにマップします
オブジェクトをEclipseLink XMLプロジェクトのXMLスキーマにマップします
両方のプロジェクトを参照するEclipseLink sessions.xmlファイルを作成します。
この方法では、リレーショナル・マッピングとXMLマッピングのすべての側面を制御することができます。この方法は、多くのまたはすべての詳細をカスタマイズしたいときに最良です。詳細は、「既存のEclipseLink ORMマッピングとOXMマッピング」を参照してください。
EclipseLink DBWSデザインタイム・ユーティリティDBWSBuilderは、EclipseLink DBWSファイルを生成し、これらをデプロイ可能なアーカイブにアセンブルするJavaアプリケーションです。
通常はコマンドラインから主なメソッドを使用して起動します。
prompt > dbwsbuilder.cmd -builderFile {path_to_builder.xml} -stageDir {path_to_stageDir} -packageAs {packager}
指定されたBuilderのXMLファイル(例1-10)は、プロパティと<table>操作を表すモデル・オブジェクトを生成するOXMプロジェクトorg.eclipse.persistence.tools.dbws.DBWSBuilderModelProjectで解析されます。そのためパブリック・クラスorg.eclipse.persistence.tools.dbws.DBWSBuilderはプロパティ・セッター(setDriver()、setUrl()など)の表でaddSqlOperation()を介したSQL操作によってプログラム的に移入されます。
例1-10 BuilderのXMLファイルの例
<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<properties>
<property name="projectName">test</property>
<property name="driver">oracle.jdbc.OracleDriver</property>
<property name="password">tiger</property>
<property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property>
<property name="username">scott</property>
</properties>
<table
catalogPattern="%"
schemaPattern="SCOTT"
tableNamePattern="EMP"
/>
</dbws-builder>
コマンドラインで指定されたパッケージャはorg.eclipse.persistence.tools.dbws.DBWSPackagerインタフェースを実装するクラスで表現されます。このインタフェースには、図1-4に示すような具象実装の階層があります。
DBWSPackagerの主な役割は、DBWSBuilderで生成された出力に対してjava.io.OutputStreamを提供することです。
例1-11 DBWSPackagerの例
// call-backs for stream management public OutputStream getSchemaStream() throws FileNotFoundException; public void closeSchemaStream(OutputStream schemaStream); public OutputStream getSessionsStream(String sessionsFileName) throws FileNotFoundException; public void closeSessionsStream(OutputStream sessionsStream); public OutputStream getServiceStream() throws FileNotFoundException; public void closeServiceStream(OutputStream serviceStream); public OutputStream getOrStream() throws FileNotFoundException; public void closeOrStream(OutputStream orStream); public OutputStream getOxStream() throws FileNotFoundException; public void closeOxStream(OutputStream oxStream); public OutputStream getWSDLStream() throws FileNotFoundException; public void closeWSDLStream(OutputStream wsdlStream); public OutputStream getSWARefStream() throws FileNotFoundException; public void closeSWARefStream(OutputStream swarefStream); public OutputStream getWebXmlStream() throws FileNotFoundException; public void closeWebXmlStream(OutputStream webXmlStream); public OutputStream getProviderClassStream() throws FileNotFoundException; public void closeProviderClassStream(OutputStream codeGenProviderStream); public OutputStream getProviderSourceStream() throws FileNotFoundException; public void closeProviderSourceStream(OutputStream sourceProviderStream);
すべてのモデル・オブジェクトが組み込まれると、start()メソッドまたはbuild(...)メソッドからBuilderが起動され、DBWSPackagerからストリームをオーバーライドしてPackagerの外部でストリームを管理できるようになります。
public void start() ...
public void build(OutputStream dbwsSchemaStream, OutputStream dbwsSessionsStream,
OutputStream dbwsServiceStream, OutputStream dbwsOrStream, OutputStream dbwsOxStream,
OutputStream swarefStream, OutputStream webXmlStream, OutputStream wsdlStream,
OutputStream codeGenProviderStream, OutputStream sourceProviderStream, Logger logger) ...
EclipseLink DBWSのデザインタイム・ユーティリティDBWSBuilderを使用すると、デプロイメント・ファイルを作成することができます。DBWSBuilderは、EclipseLink DBWS BuilderのXMLファイルに記述された操作を処理して、必要なすべてのデプロイメント・アーティファクトを作成するJavaアプリケーションです。
DBWSBuilderを起動する前に、次の環境変数を<ECLIPSELINK_HOME>\utils\dbws\setenv.cmd(またはsetenv.shファイル)に設定します。
JAVA_HOME
DRIVER_CLASSPATH
DBWSBuilderを起動するために用意されているスクリプト・ファイルがあります。これらは<ECLIPSELINK_HOME>\utils\dbwsディレクトリにあります。スクリプトはWindows用がdbwsbuilder.cmd、その他のオペレーティング・システム用がdbwsbuilder.shです。
例1-12 DBWSBuilderの使用
prompt > dbwsbuilder.cmd -builderFile {path_to_dbws_builder.xml} -stageDir {path_to_stageDir}
-packageAs[:archive_flag - archive, noArchive, ignore] {packager} [additional args]
Available packagers:
-packageAs:[default=not supported] jdev
-packageAs:[default=archive] javase [jarFilename]
-packageAs:[default=archive] wls [warFilename]
-packageAs:[default=archive] glassfish [warFilename]
-packageAs:[default=archive] jboss [warFilename]
-packageAs:[default=archive] war [warFilename]
-packageAs:[default=archive] was [warFilename]
-packageAs:[default=not supported] eclipse
DBWSBuilderを使用して、次のソースからEclipseLink DBWSサービスを生成することができます。
既存のリレーショナル・データベース表。「データベース表からのEclipseLink DBWSサービスの作成」を参照してください。
1つ以上のSQL SELECT文。「SQL文からのEclipseLink DBWSサービスの作成」を参照してください。
ストアド・プロシージャ。「ストアド・プロシージャからのEclipseLink DBWSサービスの作成」を参照してください。
ストアド・ファンクション。「ストアド・ファンクションからの作成」を参照してください。
