TopLinkプロジェクトのビルディング・ブロックこの章では、オブジェクト・リレーショナルおよびObject-XMLマッピング・プロジェクトで使用できるアイテムについて説明します。この章の内容は次のとおりです。2.0準拠のJPA実装が用意されています。これは、すべての必須機能、多くのオプション機能および一部の追加機能に完全に準拠しています。Databaseサポートの拡張機能、高度なマッピング、オプティミスティック・ロック・オプションとペシミスティック・ロック・オプション、広範な注釈と問合せのヒントが含まれます。Guide』を参照してください。http://wiki.eclipse.org/EclipseLink/UserGuide/JPA次の各項で、これらの機能の多くについて説明します。オブジェクト・リレーショナル・エンティティ・アーキテクチャこのエンティティ・アーキテクチャは、エンティティ、永続性ユニット、永続性コンテキスト、エンティティ・マネージャ・ファクトリおよびエンティティ・マネージャで構成されています。図2-1に、これらの要素の関係を示します。永続性は、1つ以上のEntityManagerFactoryオブジェクトを作成します。各EntityManagerFactoryは、1つの永続性ユニットによって構成されます。EntityManagerFactoryは、1つ以上のEntityManagerオブジェクトを作成します。1つ以上のEntityManagerは、1つのPersistenceContextを管理します。エンティティエンティティは、アプリケーションで定義されたオブジェクトで、次の特性があります。永続化することが可能です。永続識別子を持ちます(永続識別子とは、エンティティ・インスタンスを一意に識別し、そのインスタンスを同じエンティティ・タイプの他のインスタンスから区別するキーです。エンティティは、データ・ストアにそのエンティティを表現するオブジェクトが存在する場合、永続識別子を持ちます)。エンティティの永続性ビューに関してトランザクション的であるという点で、トランザクション的です(エンティティは、トランザクション内で作成、更新および削除され、変更のデータベースへのコミット時にはトランザクションが必要です)。メモリー内エンティティは、変更を永続化することなく更新できます。プリミティブ・オブジェクト、プリミティブ・ラッパー・オブジェクトまたは組込みオブジェクトではありません。エンティティは、単一の場所(表の行など)に通常格納される集約された状態のセットを保持する粒度の細かいオブジェクトであり、他のエンティティに対するリレーションシップを持ちます。エンティティには、エンティティを記述するエンティティ・メタデータも含まれています。エンティティ・メタデータは、データベースに対して永続化されません。これは、エンティティがロードされてから実行時に起動されるまでの間、永続性レイヤーがエンティティを管理するために使用されます。メタデータは、Javaプログラミング要素またはXMLファイル(ディスクリプタ)の注釈として表現できます。現在のリリース以降では、マッピングを自動的に追加できる拡張可能なエンティティを定義および使用できます。この場合、エンティティには、静的属性ではなく、マップ内に拡張された属性が保存されます。次に、エンティティは、eclipselink-orm.xmlマッピング・ファイルを使用して、このマップの値をデータベースにマップする方法を定義します。TopLinkでは、動的にマッピングを定義できることに加えて、これらの拡張されたマッピングを保存して外部から管理することもできます。この外部保存によって、アプリケーションの実行中に、拡張されたマッピングを定義できるようになりました。詳細は、EclipseLinkドキュメントの『EclipseLink/Examples/JPA/Extensibility』を参照してください。永続性と永続性ユニット永続性は、エンティティの特性です。エンティティはデータ・ストアで表すことができ、後でアクセスできます。永続性ユニットは、永続化可能なユニットを識別し、それに関連するプロパティを定義します。永続化する必要があるオブジェクトも定義します。オブジェクトは、エンティティ・クラス、埋込み可能クラス、マップされたスーパークラスのいずれかです。永続性ユニットでは、エンティティ・マネージャ・ファクトリの構成が提供されます。エンティティ・マネージャ・ファクトリによって作成されたエンティティ・マネージャは、永続性ユニットに定義されたプロパティを継承します。エンティティ・マネージャエンティティ・マネージャは、エンティティに対して操作を実行するAPIコールを有効にします。エンティティ・マネージャを使用してエンティティの作成、読取り、書込みのいずれかを行うまで、エンティティは、非永続性Javaオブジェクトです。エンティティ・マネージャがエンティティへの参照を取得すると、そのエンティティはエンティティ・マネージャによって管理されるようになります。特定の時点でのエンティティ・マネージャ内の管理対象エンティティ・インスタンスのセットは、永続性コンテキストと呼ばれ、同じ永続性IDのJavaインスタンスは、永続性コンテキスト内に特定の時点で1つのみ存在できます。特定のデータベースを対象とする読取りまたは書込み、特定タイプのオブジェクトの永続化または管理、および特定の永続性プロバイダによる実装を行うようエンティティ・マネージャを構成できます。永続性プロバイダにより、EntityManagerインタフェース実装、Query実装、SQL生成などのJPAの実装が提供されます。エンティティ・マネージャはEntityManagerFactoryによって提供されます。エンティティ・マネージャの構成は、EntityManagerFactoryに依存しますが、永続性ユニットとして個別に定義されます。永続性ユニットに名前を付けることで、各EntityManagerFactoryオブジェクトを区別できます。この方法により、特定のエンティティの操作にどの構成を使用するかをアプリケーションで制御できます。永続性ユニットを記述する構成は、persistence.xmlファイルで定義します。特定の構成をEntityManagerFactoryにバインドするようにリクエストできるようにするために、永続性ユニットに名前を付けます。注釈を使用したメタデータの追加TopLinkには、Javaソース・コードに簡単にメタデータを追加できるように、一連の独自仕様の注釈が用意されています。メタデータは、対応するJavaクラス・ファイルにコンパイルされ、実行時にJPA永続性プロバイダによって解釈されて、永続性動作が管理されます。注釈は、クラス、メソッドおよびフィールドのレベルに適用できます。TopLinkの注釈では、JPAメタデータの使用を介して現在入手できないTopLinkの機能の一部が公開されています。デフォルトでは、TopLinkの永続性プロバイダは、単純型に対する基本マッピングを自動的に構成します。これらの注釈を使用して、フィールドまたはプロパティのエンティティの即時の状態を微調整します。TopLinkには、OneToOneやOneToManyなど、いくつかの関係がデフォルトで含まれます。他の関係は、明示的にマップする必要があります。注釈を使用して、エンティティ関係のタイプおよび特性を指定して、これらの関係をデータベースでどのように実装するかを微調整します。埋込みオブジェクトには、それ自体の永続識別子は存在せず、識別子に関しては、エンティティに依存しています。TopLink永続性プロバイダはデフォルトで、各エンティティがそれ自体の表にマップされていることを前提としています。それに続く注釈を使用すれば、他のエンティティが所有するエンティティに対して、この動作をオーバーライドできます。構成ファイル次の項では、TopLinkオブジェクト・リレーショナル・マッピング・プロジェクトの主な構成ファイルのいくつかについて説明します。2.0仕様に準拠しています。構成ファイルでは、仕様に定義されているプロパティのデフォルト値を変更できます。Annotations」に示されています。http://jcp.org/en/jsr/detail?id=317この構成は例外処理として行われます。構成ファイルのいずれかに値が指定されていない場合は、デフォルト値が使用されます。永続性ユニットを構成するには、JPA永続性ファイルpersistence.xmlを使用します。永続性ユニットでは、エンティティ・マネージャを取得する際に必要な詳細を定義します。ベンダー固有の拡張機能は、<properties>要素を使用して、このファイルに指定できます。このファイルは、永続性ユニットのJARファイルのMETA-INF/ディレクトリまたはクラスパスにあります。persistence.xml』を参照してください。eclipselink-orm.xmlを使用したTopLinkオブジェクト・リレーショナル・マッピングの指定メタデータを永続性ユニットに適用するには、標準のJPAのorm.xmlファイルを使用します。2.0マッピングをサポートしています。このファイルを注釈のかわりに使用するか、ソース・コードのJPA注釈をオーバーライドするために使用できます。2.0では定義されていないEclipseLink拡張機能のフル・セットもサポートしています。eclipselink-orm.xml』を参照してください。http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Configuration/JPA/eclipselink-orm.xmlEclipseLinkドキュメントの『EclipseLink/Examples/JPA/EclipseLink-ORM.XML』も参照してください。http://wiki.eclipse.org/EclipseLink/Examples/JPA/EclipseLink-ORM.XML注意:このマッピング・ファイルを使用すると、TopLinkの多くの高度な機能が有効になりますが、他のJPA実装に対する永続性ユニットの移植性がなくなる場合があります。データ・ソース永続性ユニットの定義で重要なのは、プロバイダが読み書きするデータを検出可能な場所です。これを、データ・ソースと呼びます。TopLinkでは、多くの場合、データ・ソースはデータベースです。データベースの場所は、サーバーのJNDIネームスペースのJDBCデータ・ソースの形式で指定します。通常、TopLinkを使用するアプリケーションは、JTAトランザクションのコンテキストで実行します。データ・ソースの名前は、persistence.xmlファイルのjta-data-source要素に指定します。アプリケーションがトランザクションのコンテキストで実行されない場合は、resource-localと見なされます。この場合は、non-jta-data-source要素に、データ・ソースの名前を指定します。TopLinkでは、XMLスキーマなどのリレーショナル・データベース以外のデータ・ソースも指定できます。SE)モードで実行できます。このモードでは、非JTA準拠のデータ・ソースとともに、非Oracleスタックにおいて、サーバーの外部でアプリケーションが実行されます。この場合、JDBCドライバ・クラス、データベースに接続するためにクライアントが使用するURL、データベースにアクセスするためのユーザー名とパスワードなどのドライバ固有の情報を指定する必要があります。詳細およびスタンドアロン・モードでのアプリケーションの実行例は、EclipseLinkドキュメントの『EclipseLink/Examples/JPA/OutsideContainer』を参照してください。Tutorial』も参照してください。TopLinkのキャッシュTopLinkのデフォルトでは、読み取られて永続性ユニットに対して永続化されたすべてのオブジェクトのサブセットがキャッシュされる、共有オブジェクト・キャッシュが使用されます。TopLinkの共有キャッシュは、ローカルのEntityManagerキャッシュとは異なります。共有キャッシュは、永続性ユニット(EntityManagerFactoryまたはサーバー)の期間存在し、永続性ユニットのすべてのEntityManagerおよびユーザーによって共有されます。ローカルのEntityManagerキャッシュは共有されず、EntityManagerまたはトランザクションの期間のみ存在します。共有キャッシュの利点は、オブジェクトを読み取ると、同じオブジェクトを再度読み取る際にデータベースにアクセスする必要がないことです。問合せを使用してオブジェクトを読み取る場合は、オブジェクトを再作成する必要はなく、オブジェクトの関係も再度フェッチする必要がありません。共有キャッシュの制限は、JDBC経由または別のアプリケーションやサーバーによってデータベースが直接変更されると、共有キャッシュのオブジェクトが失効することです。TopLinkには、失効データを扱うために、次のようなメカニズムが用意されています。リフレッシュ無効化オプティミスティック・ロックキャッシュ・コーディネーション共有キャッシュは無効にしたり、@Cacheまたは@Cacheable注釈を使用して、選択的に有効化または無効化することもできます。TopLinkには、キャッシュするオブジェクト数および使用するメモリー量を構成するためのキャッシュ戦略もいくつか用意されています。キャッシュが最新でないことをアプリケーションが検出した場合、アプリケーションはプログラムでキャッシュをクリア、リフレッシュまたは無効化できます。キャッシュされているオブジェクトのいずれかが使用中の場合にキャッシュをクリアすると、オブジェクトIDの問題が発生する場合があるので、無効化するほうが安全です。キャッシュされているオブジェクトのいずれも使用中でないことがわかっている場合は、キャッシュをクリアできます。詳細は、EclipseLinkドキュメントの『EclipseLink/Examples/JPA/Caching』を参照してください。キャッシュ動作の定義TopLinkには、キャッシュ・プロパティを定義できる@Cache注釈が用意されています。プロパティには、キャッシュのタイプ、サイズ、リフレッシュ・ルールなどが含まれます。Annotation』を参照してください。クラスタ環境でのキャッシングあるサーバーでの変更は他のサーバーにキャッシュされているオブジェクトには反映されないため、クラスタ環境でのキャッシングでは問題が発生する場合があります。これは、読取り専用オブジェクトでは問題になりませんが、頻繁に更新されるオブジェクトでは問題になります。TopLinkには、この問題に対する解決策がいくつか用意されています。頻繁に変更されるクラスに対してはキャッシュを無効にできます。キャッシュ・コーディネーションを使用して、クラスタ内のサーバー間で変更をブロードキャストして、変更されたオブジェクトを更新または無効化できます。存続時間または時刻に基づいてキャッシュを無効化できます。オプティミスティック・ロックを使用して、無効なオブジェクトへの更新を防ぎ、キャッシュ内でオブジェクトが無効化されるようにトリガーすることができます。データベース問合せTopLinkのオブジェクト・リレーショナル・コンポーネントは、様々な問合せをサポートしています。JPQLJPQLは、SQLに似た問合せ言語ですが、オブジェクト・モデルのパースペクティブから問合せを提示できること、およびエンティティと依存オブジェクトに対して定義されている関係のナビゲーションを可能にするパス式が含まれていることが異なります。TopLinkでは、JPQLを通常のJavaオブジェクトで使用できます。TopLinkでJPQLを使用すると、オブジェクト・モデルの各抽象エンティティの属性を使用して、問合せを宣言できます。JPQLの短所は、動的問合せで、Webフォームや動的コンテンツから文字列を動的に連結して問合せを作成する必要があることです。JPQLは実行時までチェックされないので、タイプミスが多くなります。これらの短所は、次の項で説明する問合せ基準APIを使用すればある程度補えます。EclipseLinkドキュメントの『JPQL』を参照してください。http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/JPQLEclipseLinkドキュメントの『EclipseLink/Release/2.1.0/JPAQueryEnhancements』も参照してください。2.0には、動的問合せの作成を簡素化するために問合せ基準APIが定義されています。基準問合せでは、パラメータを使用でき、名前付き問合せと同様に問合せヒントを使用できます。問合せ基準APIでは、任意のJQPL問合せを記述できます。このAPIには、すべてのJPQLキーワードが定義されています。基準APIでは、一連のJavaインタフェースを使用して、問合せを動的に作成できるようになっています。コンパイル時に正確さを確認して、実行時のタイプミスを減らすこともできます。Query』を参照してください。問合せヒントTopLinkの問合せヒントでは、JPA仕様で可能な範囲を超えてJPA問合せをカスタマイズまたは最適化できます。TopLinkのJPA問合せヒントを使用して、次のことを行えます。Hints』を参照してください。TopLinkの高度なネイティブ問合せサポートTopLinkには、式フレームワーク(TopLinkネイティブ問合せサポートとも呼ばれる)が用意されています。この機能では、JPQLでサポートされていない問合せを記述する際に、SQLのかわりにデータベースに中立な形で問合せを表現できます。データベースにアクセスする場合、TopLinkの式は次の点でSQLよりも優れています。データベースが抽象化されるため、式の方が管理が容易です。ディスクリプタまたはデータベース表に変更を加えても、アプリケーションの問合せ構造に影響を与えません。式では、Javaの通常のコール方法に似せてQueryインタフェースを標準化するため、読みやすさが向上します。式を使用すると、読取り問合せによって、同じリレーションシップを共有する2つのクラスの間で問合せを透過的に行うことができます。これらのクラスがデータベース内の複数の表に格納されている場合、適切な結合文が自動的に生成され、両方の表から情報が返されます。式は複雑な操作を単純化します。TopLinkでは、指定した式から適切なSQLが自動的に生成されます。式フレームワークでは、式、データベース問合せ、コール・オブジェクトおよびネイティブ問合せを操作できます。Queries』を参照してください。http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Querying/NativeEclipseLinkのDatabaseQueryを使用したJPA問合せTopLinkのDatabaseQueryは、オブジェクト・レベルおよびデータ・レベルでの読取りおよび書込みを含む、データベース問合せの様々な要件を処理するための強力なAPIが用意された問合せオブジェクトです。Callを定義できます。ネイティブ問合せの名前付きパラメータTopLinkでは、TopLinkの#表記規則を使用して、ネイティブ問合せに名前付きパラメータを指定できます。(JPQL)の位置パラメータの?n表記規則を使用して、番号別にパラメータを指定することによって、ネイティブ問合せに位置パラメータを指定できます。ネイティブ問合せのJDBCスタイル位置パラメータTopLinkでは、JDBCスタイル位置パラメータの?表記規則を使用して、ネイティブ問合せに位置パラメータを指定できます。Object-XMLコンポーネントでは、JavaクラスをXMLスキーマに効率的にバインドできます。Object-XMLではJAXBが実装されるので、注釈でマッピング情報を提供でき、マッピングをXML形式で保存できます。222)は、JavaのXMLバインディングの標準です。JAXBでは、XMLスキーマの概念が100%カバーされています。TopLinkでは、JAXBの実装が多くの拡張機能とともに提供されています。Object-XMLをJAXBプロバイダとして使用する際には、既存のオブジェクト・モデルをXMLに変換するためのメタデータは不要です。XML表記を微調整する必要がある場合は、(注釈またはXMLを使用して)メタデータを指定できます。Object-XMLには、Javaクラス・モデルでスキーマをミラーリングしなくても、複雑なXML構造を処理できる高度なマッピングが多数含まれています。Guide』を参照してください。http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy次の各項で、これらの機能の多くについて説明します。JAXBランタイムへのエントリ・ポイントを指定する必要があります。このエントリ・ポイントはJAXBContextFactoryクラスです。jaxb.propertiesというテキスト・ファイルを作成して、JAXBContextFactoryクラスへのパスをjavax.xml.bind.context.factoryコンテキスト・パラメータの値として、次のように入力します。jaxb.propertiesファイルは、ドメイン・クラスと同じパッケージに存在する必要があります。Object-XMLのアーキテクチャ図2-2に示されているObject-XMLのサンプル・アーキテクチャでは、開始点はXMLスキーマになっています。バインディング・コンパイラは、スキーマから導出されたプログラム・クラスおよびインタフェースのセットにソース・スキーマをバインドします。アプリケーション内のJAXBの注釈が付いたクラスは、スキーマ・コンパイラで生成されるか、開発者がJAXB注釈を既存のJavaクラスに追加した結果によって生成されます。アプリケーションは、データをXML文書にマーシャリングするか、データをコンテンツ・オブジェクトのツリーにアンマーシャリングできます。各コンテンツ・オブジェクトは、導出されたスキーマ、またはスキーマ・ジェネレータによってマップされた既存のプログラム要素のどちらかのインスタンスで、XML内のインスタンスに対応しています。JAXBランタイムへのエントリ・ポイントです。これは、必須のファクトリ・メソッドを提供し、JAXBContextオブジェクトの新しいインスタンスを作成できます。JAXBContextFactoryクラスでは、次のことが可能です。APIに対するクライアントのエントリ・ポイントを提供します。JAXBContextクラスは、メタデータの解釈、スキーマ・ファイルの生成、およびJAXBオブジェクト(Marshaller、Unmarshaller、Binder、IntrospectorおよびValidator)のインスタンスの作成を行います。Object-XMLには、JAXBContextオブジェクトを作成する際にいくつかのオプションが用意されています。次のいずれかから開始できます。Object-XMLには、MetadataSourceオブジェクトの概念が用意されています。このオブジェクトによって、マッピング情報をアプリケーションの外部に保存して、アプリケーションのJAXBContextオブジェクトが作成またはリフレッシュされるときにそれを取得できるようになります。MetadataSourceの実装の詳細は、EclipseLinkドキュメントの『MetadataSource』を参照してください。XMLバインディングTopLinkでは、すべての標準JAXB注釈を使用できます。XMLバインディング・ドキュメントという、メタデータを表現する別の方法も用意されています。XMLバインディングは、マッピング情報を実際のJavaクラスから分離できるだけでなく、次のような高度なメタデータ・タスクにも使用できます。追加のマッピング情報で、既存の注釈を拡張またはオーバーライドできます。Java注釈を使用せずに、すべてのマッピング情報を外部指定できます。複数のバインディング文書にまたがるマッピングを定義できます。具体的なJavaフィールドに対応しない仮想マッピングを指定できます。Bindings』を参照してください。Object-XMLマッピングの指定Java注釈を使用して、TopLinkプロジェクトにJAXBの機能を指定できます。TopLinkには、Java注釈に加えて、eclipselink-oxm.xmlというXMLマッピング構成ファイルが用意されています。このマッピング・ファイルには、標準のJAXBマッピングと、高度なマッピング・タイプ用の構成オプションが含まれています。eclipselink-oxm.xmlファイルを、ソース・コードのJAXB注釈のかわりに使用するか、JAXB注釈をオーバーライドするために使用できます。注意:このマッピング・ファイルを使用すると、多くのTopLinkの高度な機能が有効になりますが、他のJAXB実装に対するモデルの移植性がなくなる場合があります。Object-XMLでは、従来のJavaのアクセス・メソッドを使用してオブジェクトの値を取得および設定する方法に加えて、XPath文を使用して値にアクセスすることもできます。TopLinkのJAXBContextには、XPathで値を取得および設定できる特別なAPIがあります。XPath』を参照してください。reserved.法律上の注意点ライブラリ。