7 ネイティブTopLinkからの移行

この章では、TopLinkのネイティブなオブジェクト・リレーショナル・マッピング(ORM) APIを使用するアプリケーションを現在のEclipseLink APIを使用するアプリケーションに移行する方法を説明します。

TopLink 11gリリース1 (11.1.1)以降、EclipseLinkライブラリはOracle TopLinkのコア・ライブラリとなっています。

この章の内容は次のとおりです。

• ソリューションの概要

• ソリューションの実装

ユース・ケース

開発者は、以前のTopLinkにネイティブのORMを使用しているアプリケーションを、現在のEclipseLink ORM実装を使用するようにアップグレードしたいと考えています。

解決方法

この章の手順に従って、アプリケーションをアップグレードします。

コンポーネント

• TopLink 12c (12.1.2.0.0)以上。

  注意:

  TopLinkのコア機能は、オープン・ソースのEclipse Foundationの永続性フレームワークであるEclipseLinkによって提供されています。EclipseLinkでは、Java Persistence API (JPA)、Java Architecture for XML Binding (JAXB)、および標準に基づいたその他の永続性テクノロジと、それらの標準の拡張が実装されます。TopLinkには、EclipseLinkのすべてに加え、Oracleの追加機能が含まれています。

• EclipseLink 2.4以降。

• (オプション) EclipseLink Workbench。

ソリューションの概要

ネイティブTopLink ORMとは、Java Persistence API (JPA)がオブジェクト・リレーショナル・マッピングAPIを標準化する前に、TopLinkで展開された、API、構成ファイル、オブジェクト・リレーショナル・マッピング用のツールを指します。JPAは、TopLink EssentialsとしてOracle TopLink 10g (10.1.3.1.0)で完全にサポートされるようになりました。ただし、ネイティブTopLinkもサポートされ続けています。

TopLink 11g (11.1.1)リリースより前では、Oracleでは、Eclipse FoundationにTopLink JPAおよびネイティブTopLinkを含むTopLinkのソース・コードを提供し、これを基にして、オープンソースのEclipseLink永続性サービス・プロジェクトの基礎が形成されました。その後、TopLink 11gリリース1 (11.1.1)で、OracleはTopLinkにTopLinkのコア機能を提供するEclipseLinkを含めるようになりました。

TopLinkバージョン11.1.1.0.0から11.1.1.6.0を使用するTopLink開発者は、Oracle独自のtoplink.jarまたはEclipseLink eclipselink.jarのいずれかで、ネイティブTopLink ORMにアクセスできます。toplink.jarのクラスは、名前がoracle.toplink.*で開始するパッケージです。eclipselink.jarでは、これらのパッケージ名は、かわりにorg.eclipselink.persistenceで開始します。

注意:

toplink.jarファイルはTopLink 11gで非推奨となり、TopLink 12cでは出荷されなくなっています。TopLink 11gでは、oracle.toplink.*から移行することをお薦めします。

toplink.jarのoracle.toplink.*パッケージを使用するアプリケーションを、eclipselink.jarのorg.eclipselink.persistence.パッケージを使用するよう移行できます。アプリケーションの機能は同じですが、eclipselink.jarに移行することにより、最新のコード・ベースが得られます。移行すると、他のTopLink機能を利用できるようになり、アプリケーションでJPAまたは現在のTopLinkのバージョンの他の永続性サービスを使用する準備を整えることができます。

この章では、スタンドアロンのTopLinkにパッケージされている名前変更ツールを使用して、アプリケーションのパッケージ名を簡単に変更し、現在のコード・ベースに移行するために必要なその他のアクションを実行する方法を説明します。

注意:

この章の説明に従うと、アプリケーションが更新され、現在のEclipseLinkのコード・ベースを使用できるようになります。これを実行した場合、当初実装したアプリケーションの設計および機能が維持されます。ただし、これらの手順では、ネイティブTopLinkベース・アプリケーションでJPAまたは現在のTopLinkのバージョンのその他の任意の永続性サービスを使用するよう変換する方法は説明していません。この情報については、TopLinkのその他のドキュメントを参照してください。

ソリューションの実装

この項の内容は次のとおりです。

• タスク1: 前提条件

• タスク2: 非推奨および削除されたネイティブAPIの置換

• タスク3: パッケージの名前変更

• タスク4: XML構成ファイルの変換

• タスク5: Oracle TopLink Workbenchプロジェクトの変換(オプション)

タスク1: 前提条件

• TopLink 12c (12.1.2.0.0)以上。

  11g以上のTopLinkのすべてのダウンロードには、この章で説明している名前変更ツールが含まれています。

  注意:

  この名前変更ツールは、Oracle WebLogic ServerまたはOracle Glassfishに組み込まれているバージョンのTopLinkには含まれません。スタンドアロンのTopLinkインストーラをダウンロードする必要があります。

  http://www.oracle.com/technetwork/middleware/toplink/downloads/index.htmlからTopLinkをダウンロードします。インストール手順については、「Oracle TopLinkのインストール」を参照してください。

• EclipseLink 2.4以降。

  http://www.eclipse.org/eclipselink/downloads/からEclipseLinkをダウンロードします。

• (オプション) EclipseLink Workbench。EclipseLink WorkbenchはEclipseLinkのダウンロードに含まれています。http://www.eclipse.org/eclipselink/downloads/のEclipseLinkのダウンロード・ページを参照してください。

タスク2: 非推奨および削除されたネイティブAPIの置換

TopLink 11gリリース1 (11.1.1)以前のリリースで非推奨であったAPIは、EclipseLinkでは削除されているので、現在のバージョンのTopLinkには含まれていません。アプリケーションでこれらの非推奨のAPIやすでにTopLinkで置換または削除されているAPIを使用している場合、アプリケーションで現在のAPIを使用するよう更新する必要があります。

TopLink 11gリリース1 (11.1.1)より前のリリースで非推奨であったAPIは、EclipseLinkでは削除されています。アプリケーションでこれらの非推奨のAPIやすでにTopLinkで置換または削除されているAPIを使用している場合、アプリケーションで現在のAPIを使用するよう更新する必要があります。

次の項では、推奨される代替とともに、置換および削除されたAPIを示します。

• 置換されたAPI、

• 非推奨となったAPI、

• 削除されたAPI、

注意:

推奨される代替がoracle.toplink.*パッケージに含まれる場合、「タスク3: パッケージの名前変更」の説明に従って、パッケージ名も変更する必要があります。

置換されたAPI

次の表に、TopLink 11gリリース1 (11.1.1.1.)以上で削除されたAPIを示します。この表に示す代替のAPIを使用するようにしてください。

• 表7-1

• 表7-2

• 表7-3

• 表7-4

• 表7-5

• 表7-6

• 表7-7

• 表7-8

• 表7-9

• 表7-10

• 表7-11

• 表7-12

• 表7-13

• 表7-14

• 表7-15

• 表7-16

表7-1 changetracking (oracle.toplink.descriptors.*)

クラス名	メソッド名	代替のAPI
ChangeTracker	getTopLinkPropertyChangeListener	._persistence_getPropertyChangeListener
ChangeTracker	setTopLinkPropertyChangeListener(PropertyChangeListener)	_persistence_setPropertyChangeListener(PropertyChangeListener)

表7-2 databaseaccess (oracle.toplink.internal*)

クラス名	メソッド名	代替のAPI
.*Platform	完全なクラス名	oracle.toplink.platform.database.*Platform

表7-3 jdo (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
.jdo	完全なパッケージ	なし

表7-4 mappings (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
TypeConversionMapping	完全なクラス名	.mappings.converters.TypeConversionConverter
ObjectTypeMapping	完全なクラス名	.mappings.converters.ObjectTypeConverter
SerializedObjectMapping	完全なクラス名	.mappings.converters.SerializedObjectConverter

表7-5 objectrelational (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
Oracle8Platform	完全なクラス名	oracle.toplink.platform.database.oracle.Oracle8Platform

表7-6 oraclespecific (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
.oraclespecific.NCharacter	完全なクラス名	.platform.database.oracle.NCharacter
.oraclespecific.NClob	完全なクラス名	.platform.database.oracle.NClob
.oraclespecific.NClob	完全なクラス名	.platform.database.oracle.NClob
.oraclespecific.Oracle8Platform	完全なクラス名	.platform.database.oracle.Oracle8Platform
.oraclespecific.Oracle9Specific脚注1	完全なクラス名	.platform.database.oracle.Oracle9Specific
.oraclesSpecific.TopLinkXMLType脚注2	完全なクラス名	なし

^脚注1

oracle.toplink.oraclespecific.Oracle9Specificは内部のパッケージに移動され、oracle.toplink.internal.platform.database.oracle.Oracle9Specificに名前変更されています。oracle.toplink.oraclespecific.Oracle9Specificの代替のパブリックAPIは、oracle.toplink.platform.database.oracle.Oracle9Specificです。

^脚注2

oracle.toplink.oraclespecific.TopLinkXMLTypeはその他のもののクラスで代替APIがありません。

表7-7 publicinterface (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
DatabaseRow	完全なクラス名	.sessions.DatabaseRecord
DatabaseSession脚注3	完全なクラス名	.sessions.DatabaseSession
Descriptor	完全なクラス名	.descriptors: ClassDescriptor、RelationalDescriptor
DescriptorEvent	完全なクラス名	.descriptors.DescriptorEvent
DescriptorEventListener	完全なクラス名	.descriptors: 新しいインタフェースでは、古いインタフェースを拡張しません
DescriptorEventManager	完全なクラス名	.descriptors
DescriptorQueryManager	完全なクラス名	.descriptors
InheritancePolicy	完全なクラス名	.descriptors
Session脚注4	完全なクラス名	.sessions.Session
UnitOfWork脚注5	完全なクラス名	.sessions.UnitOfWork

^脚注3

oracle.toplink.publicinterface.DatabaseSessionは内部のパッケージに移動され、oracle.toplink.internal.sessions.DatabaseSessionImplに名前変更されています。oracle.toplink.publicinterface.DatabaseSessionの代替のパブリックAPIは、oracle.toplink.sessions.DatabaseSessionです。

^脚注4

oracle.toplink.publicinterface.Sessionは内部のパッケージに移動され、oracle.toplink.internal.sessions.AbstractSessionImplに名前変更されています。oracle.toplink.publicinterface.Sessionの代替のパブリックAPIは、oracle.toplink.sessions.Sessionです。

^脚注5

oracle.toplink.publicinterface.UnitOfWorkは内部のパッケージに移動され、oracle.toplink.internal.sessionl.UnitOfWorkImplに名前変更されています。oracle.toplink.publicinterface.UnitOfWorkの代替のパブリックAPIはoracle.toplink.sessions.UnitOfWorkです。

表7-8 sdk (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
.sdk	完全なパッケージ	.eis

表7-9 entitymanager (oracle.toplink.sessions.*)

クラス名	メソッド名	代替のAPI
すべてのクラス	すべてのメソッド	JPA: 「JPA永続性プロバイダの実装」を参照

表7-10 sessionconfiguration (oracle.toplink.tools.*)

クラス名	メソッド名	代替のAPI
WASXMLLoader	すべてのメソッド	なし

表7-11 xml (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
.xml	完全なパッケージ	.ox
.xmlstream	完全なパッケージ	.ox
.xml.tools	完全なパッケージ	.ox
.xml.xerces	完全なパッケージ	.ox
.xml.zip	完全なパッケージ	.ox

表7-12 XMLCommandConverter (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
.remotecommand.XMLCommandConverter	完全なクラス名	なし
.transform.xml.XMLSource	完全なクラス名	なし
.transform.xml.XMLResult	完全なクラス名	なし
.internal.localization.i18n.ExceptionLocalizationResource	error_loading_resources	なし
.internal.localization.i18n.ExceptionLocalizationResource	error_parsing_resources	なし
.internal.localization.i18n.ExceptionLocalizationResource	unexpect_argument	なし

表7-13 Remoteプロトコル(oracle.toplink.*)

クラス名	メソッド名	代替のAPI
.remote.corba.orbix	完全なパッケージ	なし
.remote.corba.visibroker	完全なパッケージ	なし
.remote.ejb	完全なパッケージ	なし
.tools.sessionconfiguration.TopLinkSessionsFactory	orbix、visibrokerおよびejbパッケージ内の任意のJNDIClusteringServiceに対する参照。	なし
.tools.sessionconfiguration.DTD2SessionConfigLoader	orbix、visibrokerおよびejbパッケージ内の任意のJNDIClusteringServiceに対する参照。	なし
.tools.sessionconfiguration.model.clustering.VisibrokerCORBAJNDIClusteringConfig	完全なクラス名	なし
.tools.sessionconfiguration.model.clustering.OrbixCORBAJNDIClusteringConfig	完全なクラス名	なし
.tools.sessionconfiguration.model.clustering.EJBJNDIClusteringConfig	完全なクラス名	なし
.tools.sessionconfiguration.XMLSessionConfigProject	orbix、visibrokerおよびejbパッケージ内の任意のJNDIClusteringServiceに対する参照。	なし

表7-14 BEA WebLogic 6.1に対するEJBマッピング

クラス名	メソッド名	代替のAPI
toplink-cmp-bean_name.xml	なし	internal.ejb.cmp.wls11.CMPDeployer.readTypeSpecificData()の先頭に警告が追加されます

非推奨のAPI

次の表にTopLink 11gリリース1 (11.1.1)リリースより前に非推奨となり、したがって現在のリリースではEclipseLinkライブラリに置き換えられたために削除されたAPIを示します。かわりに示した代替のAPIを使用してください。

注意:

非推奨となったクラスと移動したクラスの名前は同じなので、古いパッケージと新しいパッケージの両方からimport *を使用してクラスをインポートすると、コンパイル・エラーが発生します。これらのエラーを回避するには、完全修飾されたパッケージ名でimportを使用します。

• 表7-15

• 表7-16

表7-15 mappings (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
OneToOneMapping	useJoining	ForeignReferenceMapping.setJoinFetch(int)

表7-16 descriptors (oracle.toplink.*)

クラス名	メソッド名	代替のAPI
ClassDescriptor	addMultipleTableForeignKeyField	addForeignKeyFieldForMultipleTable
ClassDescriptor	addMultipleTablePrimaryKeyField	addForeignKeyFieldForMultipleTable
ClassDescriptor	addMultipleTablePrimaryKeyFieldName	addForeignKeyFieldNameForMultipleTable
ClassDescriptor	addMultipleTableForeignKeyFieldName	addForeignKeyFieldNameForMultipleTable

削除されたAPI

次のクラスは、TopLink 11gリリース1 (11.1.1)より前のリリースで削除されています。

• OTSTransactionController

• OTSSynchronizationListener

• OracleSequenceDefinition(かわりにSequenceObjectDefinitionを使用)

• TimeTenSequenceDefinition(かわりにSequenceObjectDefinitionを使用)

その他のAPIの変更

APIに対するその他の変更は次のとおりです。

• JPA永続性プロバイダの実装。

• セッション・ファイナライザのデフォルトでの無効化。

• 戻し型VectorおよびHashtableのListまたはMapへの変更。

JPA永続性プロバイダの実装

TopLink 11g (11.1.1)以上のリリースでは、永続性プロバイダは、eclipselink.jarのパッケージに実装されています。たとえば次など、それまでのすべての実装で置き換わっています。

• toplink.jar

• toplink-essentials.jar

セッション・ファイナライザのデフォルトでの無効化

TopLink 11g (11.1.1) Technology Preview 3では、パフォーマンス向上のため、デフォルトではセッション・ファイナライザは無効になっていました。セッション・ファイナライザを有効にするには、SessionメソッドのsetIsFinalizersEnabled(true)を使用します。

戻し型VectorおよびHashtableのListまたはMapへの変更

VectorまたはHashtableを返すすべてのSessionまたはClassDescriptorメソッドは、それぞれListまたはMapを返すよう変更されます。この変更に備えるには、VectorおよびHashtableの戻り型をそれぞれListまたはMapにキャストします。たとえば、Javadocでは、ClassDescriptorメソッドのgetMappingsはjava.util.Vectorですが、戻り値はListにキャストされるようにする必要があります。

List mappings = (List) descriptor.getMappings();

現在、変更されMapを戻すようになっているものは次のとおりです。

• ClassDescriptor.getQueryKeys()

• ClassDescriptor.getProperties()

• DescriptorQueryManager.getQueries()

• EISInteraction.getProperties()

• Session.getProperties()

• Session.getQueries()

• getAttributesToAlwaysInclude()

• getSpecialOperations()

• getValuesToExclude()s

タスク3: パッケージの名前変更

TopLinkには、TopLink 11g,リリース1 (11.1.1)以上で、EclipseLinkのすべてのライブラリが含まれるようになりました。EclipseLinkは、TopLinkのコア機能を提供するもので、現在では、JPA 2.x、JAXBおよびその他の標準に基づく永続性サービスやそれらの標準の拡張をサポートしています。また、TopLinkではTopLinkのネイティブAPIもサポートされ続けています(ただし、oracle.toplink.*パッケージは現在すべてorg.eclipse.persistence.*に名前変更となっています)。

EclipseLinkではTopLinkのネイティブAPIもサポートされ続けています(ただし、oracle.toplink.*パッケージは現在すべてorg.eclipse.persistence.*に名前変更となっています)。

新しいコード・ベースを使用するようアプリケーションを移行するには、コードでパッケージ名を変更する必要があります。TopLinkのインストールには、これらをスムーズに行うパッケージの名前変更ツールが含まれています。これらのツールを、次のすべてに対して使用します。

• プロジェクトのソース・コード

• project.xmlファイル

• persistence.xmlファイル

• sessions.xmlファイル

パッケージの名前変更ツールは、toplink_install_directory\toplink\utils\renameディレクトリにあります。WindowsおよびUNIX/LINUX用のスクリプトが含まれています。

このスクリプトを使用し、パッケージの名前変更ツールを実行するには、次を実行します。

1. toplink_install_directory\toplink\utils\renameディレクトリでpackageRename.cmd (Windows)およびpackageRename.sh (UNIX/LINUX)スクリプトを探します。
2. 次の引数を使用し、packageRename.cmdまたはpackageRename.shを実行します。

   • sourceLocation: 名前変更するファイルを含むディレクトリ。

   • targetLocation: 名前変更したファイルの宛先ディレクトリ。パッケージの名前変更ツールは、JavaおよびXMLファイルが存在する場合、それをすべてを削除してしまうので、空のディレクトリを指定することをお薦めします。

   次に例を示します。

   packageRename c:/mySourceLocation c:/myDestinationLocation
   

   パッケージの名前変更ツールでは、名前変更するJavaおよびXMLファイルをディレクトリから再帰的に検索します。各ファイルの名前変更されたバージョンは、宛先の場所の対応するディレクトリに保存されます。

タスク4: XML構成ファイルの変換

パッケージの名前変更ツールでは、TopLinkのXML構成ファイルを変換できますが、ファイルの種類によっては他にも変更を行う必要があります。

セッションXML

sessions.xmlファイルは現状のまま、使用を継続できます。上位との互換性を高めるには、sessions.xmlファイルに対して名前変更ツールを実行します。

デプロイメントXML

TopLink 10.1.3以上のデプロイメントXMLファイルは、TopLink 11.1.1以上で読取りが可能です。これらのファイルは使用し続けることができますが、上位との互換性をより向上させるには、これらのファイルに対し名前変更ツールを実行し、XML Headerのバージョンの文字列を次と置き換えます。

Eclipse Persistence Services

永続性XML

TopLinkを永続性プロバイダとして使用するには、persistence.xmlファイルに対して名前変更ツールを実行する必要があります。名前変更ツールにより、永続性プロバイダがEclipseLinkとなるよう更新され、またTopLinkに固有なネイティブなすべてのプロパティもEclipseLinkの対応するものに更新されます。

ORM XML

オブジェクト・リレーショナル(ORM) XML構成ファイル(orm.xml)は、TopLinkには依存しないので、更新の必要はありません。

タスク5: Oracle TopLink Workbenchプロジェクトの変換(オプション)

TopLink 11gリリース1 (11.1.1)より前のリリースでは、Oracle TopLink Workbenchというグラフィカルな編集ツールが識別子の構成とプロジェクトのマッピング用に用意されていました。このツールはOracleでは提供しなくなりましたが、対応するEclipseLink WorkbenchというツールがEclipse Foundationから入手できます。古いTopLink Workbenchのプロジェクトは、EclipseLink Workbenchのプロジェクトに変換出力し、それを現在のOracle TopLinkアプリケーションで使用できます。WorkbenchプロジェクトはOracle JDeveloperにインポートすることも可能です。

注意:

EclipseLink Workbenchは、オープンソースのソフトウェアなので、Oracleではサポートされていません。

Oracle TopLink Workbench (.mwp)プロジェクトをEclipseLink Workbenchプロジェクトに変換するには、次の手順を実行します。

1. (前述の)パッケージの名前変更ツールを使用し、Oracle TopLink Workbenchプロジェクト・ソースを移行します。
2. EclipseLink WorkbenchでOracle TopLink Workbenchのプロジェクトを開きます。
3. EclipseLink Workbenchによってプロジェクトが検出され、現在のWorkbenchのバージョンで保存するか質問するメッセージが表示されます。
4. 「すぐに保存」をクリックして、プロジェクトを保存する新しいディレクトリを選択します。