| Oracle® Fusion Middleware Oracle TopLinkソリューション・ガイド 12c (12.1.2) E47993-02 |
|
 前 |
 次 |
この章では、RESTfulデータ・サービスを使用してJPA永続性ユニットを公開する方法を説明します。
この章の内容は次のとおりです。
ユース・ケース
HTML5/JavaScriptおよびモバイル・テクノロジを含む、Thinサーバー・アーキテクチャ(TSA)クライアントを開発するために、RESTを介して永続性データ・モデルおよびアプリケーション・ロジックを公開します。
解決方法
RESTfulデータ・サービスを使用すると、JAX-RSコードを記述する必要なく、RESTfulサービスを使用するエンティティを公開できます。
コンポーネント
次を含むJava EEアプリケーション・サーバー
TopLink 12cリリース1 (12.1.2)以上。
|
注意: TopLinkのコア機能は、オープン・ソースのEclipse Foundationの永続性フレームワークであるEclipseLinkによって提供されています。EclipseLinkでは、Java Persistence API (JPA)、Java Architecture for XML Binding (JAXB)、および標準に基づいたその他の永続性テクノロジと、それらの標準の拡張が実装されます。TopLinkには、EclipseLinkのすべてに加え、Oracleの追加機能が含まれています。 |
Jersey (http://jersey.java.net/を参照)などのJAX-RS参照の実装であるJava API for RESTful Web Services (JAX-RS) 1.0に対するサポート。
Oracle Database、Oracle ExpressまたはMySQLなどの対応するJava Database Connectivity (JDBC)データベース
REpresentational State Transfer (REST)は、Webサービスがリソースとみなされる分散システムのアーキテクチャの原則のセットを定義します。これらのリソースは、HTTPプロトコルを使用してアドレス指定および送信できるURIで指定します。RESTは、JPAなど、多数のテクノロジとともに使用できます。リソースにアクセスしたり操作を実行するには、HTTPメソッドを使用します。
Java API for RESTful Web Services (JAX-RS)は、RESTアーキテクチャを使用するJAVAアプリケーションの構築を容易にするために設計されたAPIです。JAX-RSでは、リソースおよびそれらのリソースに対して実行できるアクションを定義するために注釈を使用します。
RESTfulアプリケーションのJPA永続性ユニットと通信するためにJAX-RSを直接使用することも可能ですが、RESTfulデータ・サービスにはJPAの永続性にRESTを実装するのを容易にするAPIが用意されています。RESTを介して永続性ユニットを公開する単純な方法であるこのAPIを使用すると、JAX-RSコードを明示的に記述せずにJPA永続性ユニットと通信できます。
|
注意: RESTfulアプリケーションにJPAの永続性を実装するために直接JAX-RSを使用する例については、 |
RESTfulデータ・サービスは、Webアプリケーションの機能を拡張するWebフラグメントを介して有効にします。このREST機能は、WebアプリケーションのWEB-INF/libフォルダにRESTfulデータ・サービスのJARファイルを含めることによって有効になります。
実行しているアプリケーションにパッケージされたすべての永続性ユニットおよびその中にプロビジョニングされている動的なすべての永続性ユニットへのアクセスは、RESTfulデータ・サービスのランタイムにより提供されます。
この項では、RESTfulデータ・サービスを使用してJPAエンティティを公開する、次のタスクについて説明します。
RESTfulデータ・サービスを実装および使用するには、次が必要です。
Oracle WebLogic Server 12c (12.1.2)以上(次を含む)。
EclipseLink 2.4以上(永続性プロバイダとして構成される)
Java API for RESTful Web Services (JAX-RS) 1.0仕様の参照実装であるJersey。
toplink-dataservices-web.jarファイル。このファイルは、TOPLINK_HOME\oracle_common\modules\oracle.toplink_release_numの下のTopLink配布に含まれています(ここでTOPLINK_HOMEは、TopLinkをインストールした場所を指し、release_numはoracle.toplink_12.1.2などのTopLinkのリリース番号を指します)。
Oracle Database、Oracle Database Express Edition (Oracle Database XE)またはMySQLを含む対応するすべてのJava Database Connectivity (JDBC)データベース。ここで説明する手順は、Oracle Database XE 11gリリース2のものです。
保証マトリックスについては、http://www.oracle.com/technetwork/middleware/ias/index-099524.htmlを参照してください。
RESTfulデータ・サービスは、標準のJPAアプリケーションと機能するように設計されていますが、有効にするには、サービスを有効にするのみではなく、次で説明するいくつかの作業を行う必要があります。
1つ以上の標準のJPA永続性ユニットを使用してアプリケーションを開発し、Web ARchive (WAR)ファイルにパッケージして、普通にデプロイします。
|
注意: フラグメントはWebサービスを提供するのでWARに含める必要があります。WARはオプションでEnterprise Archive (EAR)ファイルにパッケージすることもできます。 |
|
注意: いくつかのRESTfulデータ・サービスの機能には、リレーションシップをリンクとして提供したり、リレーションシップを編集したり、多対1の遅延リレーションシップを処理するウィービンが必要です。したがって、これらの機能が必要な場合には、Java EEに対応のサーバーにデプロイするか、クラスを静的にウィーブする必要があります。 |
アプリケーションを含むWARにRESTfulデータ・サービス・サーブレットを含めます。(ダウンロード方法の詳細は、「手順1: 前提条件」を参照してください。)
|
注意: RESTfulデータ・サービスのJARファイルには、サーブレットを指定し、RESTfulサービスのルートURIを定義する |
toplink-dataservices-web.jarファイルを、WEB-INF/lib下のアプリケーションを含むWARに追加します。
RESTfulデータ・サービス用にREST呼び出しを行うURIは、次の標準のパターンに従っています。
アプリケーションのベースURIは、http://server:port/application-name/persistence/{version}です。
|
注意: TopLink 12.1.2のRESTfulデータ・サービスのバージョンは、 |
永続性ユニット上のベース操作には、永続性ユニット名を追加します。
/persistence/{version}/{unit-name}
特定の種類の操作については、次などのように操作の種類を追加します。
エンティティの操作: /persistence/{version}/{unit-name}/entity
問合せの操作: /persistence/{version}/{unit-name}/query
単一の結果の問合せ操作: /persistence/{version}/{unit-name}/singleResultQuery
永続性ユニット・レベルのメタデータ操作: /persistence/{version}/{unit-name}/metadata
ベース操作: /persistence/{version}
これらのURIの構成方法の詳細は、20.4項「RESTfulデータ・サービスのAPIリファレンス」を参照してください。
RESTfulデータ・サービス内のエンティティは、次の2つの方法で示します。
JPAエンティティとして: JPAエンティティをマッピングする場合、注釈を使用するかXMLファイルを使用するかの一般的なJPAの表現方法で示します。これらのマッピングは、データ・ソースとの通信に使用されます。
JAXB/JSONとして: JAXB/JSONを使用する場合には、特定のマッピング情報は不要です。RESTfulデータ・サービスでは、デフォルトでJAXBのデフォルト(JAXB仕様に定義)が使用され、JAXB/JSONにマッピングされます。オブジェクトのマッピング方法を変更するには、オプションでクラスにJAXB注釈を加えます。また、XML定義のJAXBマッピングを指定するには、永続性ユニットのpersistence.xmlに永続性ユニット・プロパティeclipselink.jpa-rs.oxmを指定します。
JSON/JAXBを使用し情報通信を行うには、一般的にJAXBのデフォルトのマッピングで十分です。ただし、リレーションシップを扱う場合には特殊なケースがいくつかあります。
双方向リレーションシップとサイクル
双方向リレーションシップは、JPAでは一般的であり、データベースで外部キーを使用して簡単に表現できます。これをXMLや標準のJAXBを使用するJSONドキュメントで表現することは、より困難です。ただし、EclipseLinkのJAXBの実装では逆の関係を定義する方法があります。逆の関係をXMLまたはJSONに直接記述せず、XMLまたはJSONがアンマーシャリングされる際に移入します。これは、次のように処理されます。
JPAの双方向の関係の定義には、所有者側と非所有者側があります。データベースの表に外部キーがあるエンティティは、所有者側のエンティティです。もう一方の表(ポイント対象)が、逆(非所有)エンティティです。JPAマッピングのmapped-by属性で、どちらがどちらであるかを定義します。mappedBy属性は、逆サイドにある必要があります。RESTfulデータ・サービスのデフォルトでは、所有者側が逆関係です。その結果、所有者関係のオブジェクトが読み書きされると、そのリレーションシップは無視されます。
次に疑似コードの場合を考えてみましょう。
@Entity
ClassA{
@Id
int id
@OneToOne
myB
}
@Entity
ClassB{
@Id
int id
@OneToOne(mappedby="myB")
myA
}
オブジェクトの定義が次である場合
A1 は id=1で、myB = B1
B1 は id=11 で、myA = A1
次のJSONでは、これらのオブジェクトに対応します。
A {
id:1
}
B {
id:11
myA: {
id: 1
}
}
値渡し対参照渡し
RESTfulデータ・サービスでは、RESTリクエストでリレーションシップ・オブジェクトを値または参照として渡すことができます。JSON属性は、リソース参照(「値渡し」を参照)を保持し、_relationshipはナビゲーション・リンク(「リファレンス渡し」を参照)を持ちます。
値渡し
オブジェクトを値で渡すには、オブジェクトを示す一般的なJSONまたはXMLを作成します。次のJSONではmyAを値で渡します。
B {
id:11
myA {
id: 1
}
}
参照渡し
オブジェクトを参照渡しするには、_linkを使用します。このリンクが、そのオブジェクトを取得するために必要なRESTfulデータ・サービス呼び出しを示します。次のJSONではmyAを参照で渡します。
B {
id:11
myA {
_link:{
href: "http://localhost:8080/app/persistence/v1.0/pu/entity/A/1"
method: "GET"
rel: "self"
}
}
}
linkは、href、methodおよびrel属性で構成されます。
href (ハイパーテキスト・リファレンス)とは、リンクされているエンティティのURIです。hrefは、リンクされているエンティティまたは属性を一意に識別します。
methodは、hrefが使用される操作を指定します。
relは、それを含むエンティティとそれにリンクされているエンティティ間の関係を指定します。
リストには、参照と値アイテムを混合できます。リクエストでアイテムが参照で指定されている場合、対応するエンティティが必要です(そうでない場合、RESTfulデータ・サービスによってエラーが返されます)。
次の例では、正規表現のような構文でリクエストとしてRESTfulデータ・サービスに送信できるJSONを示します。
{
"numericAttribute": 1
"stringAttribute": "auction1"
"dateAttribute": 12-09-16
"singleRelatedItem": RELATED_ITEM?
"listRelatedItem":
{
RELATED_ITEM*
}
}
RELATED_ITEM =
{
"numericAttribute": 11
"stringAttribute": "myName"
}
OR
"_link" {
"rel"="self",
"href" = "LINK_HREF",
"method"="GET"
}
次のJSONでは、Bidという直接マップされたいくつかのフィールドとエンティティの集合を持つAuctionというエンティティを示します。
{
"description": "Auction 1",
"endPrice": 0,
"id": 2,
"image": "auction1.jpg",
"name": "A1",
"sold": false,
"startPrice": 100,
"bids": [
{
"_link": {
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/auction/entity/Bid/5",
"method": "GET",
"rel": "self"
}
},
{
"_link": {
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/auction/entity/Bid/6",
"method": "GET",
"rel": "self"
}
}
]
}
XMLの表現は、JSONの表現を模倣しています。次のXMLの例では、Bidという直接マップされたいくつかの属性とエンティティのリストを持つAuctionというエンティティを示します。
<?xml version="1.0" encoding="UTF-8"?>
<Auction>
<description>Auction 1</description>
<endPrice>0.0</endPrice>
<id>2</id>
<image>auction1.jpg</image>
<name>A1</name>
<sold>false</sold>
<startPrice>100.0</startPrice>
<bids>
<_link href="http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/auction/entity/Bid/5" method="GET" rel="self" />
</bids>
<bids>
<_link href="http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/auction/entity/Bid/6" method="GET" rel="self" />
</bids>
</Auction>
クライアントは、デプロイしたアプリケーションの永続性ユニットで操作を行うためにHTTP呼び出しを使用します。この呼び出しを構成する要件およびオプションの詳細は、20.4項「RESTfulデータ・サービスのAPIリファレンス」を参照してください。
このRESTインタフェースでは、XMLおよびJSONの両方で表現されたデータを処理できます。コンテンツの形式は、呼び出し元でHTTPヘッダー値を使用して指定する必要があります。
Content-Type = application/jsonは、コンテンツがJSONに送られることを示します。
Content-Type = application/xmlは、コンテンツがXMLに送信されることを示します。
Accept = application/jsonは、結果としてJSON形式が期待されることを示します。
Accept = application/xmlは、結果としてXML形式が期待されることを示します。
ヘッダー値の指定がない場合、デフォルトでJSONが使用されます。Content-typeが指定され、Acceptが指定されない場合、返される形式は渡されたContent-typeと同じになります。
|
注意: 多くのRESTユーティリティでは、 |
RESTfulデータ・サービスの処理と関係するメッセージは、org.eclipse.persistence.jparsと呼ばれるロガーに記録されます。多くのメッセージは、FINEレベルで記録されます。例外スタックはFINERに記録されます。
EntityManager、EntityManagerFactoryおよびJAXBContext内の処理と関係するメッセージは、他のEclipseLinkのログと同様な方法で記録されます。
RESTfulデータ・サービスは、典型的なのRESTセキュリティ・メカニズムを使用してセキュリティを確保します。
RESTfulデータ・サービスのXMLまたはJSONの応答メッセージには次のカテゴリが含まれます。
int, double, String, Integer, Double, Booleanなどの基本データ型。
リレーションシップ(リンクおよびリレーションシップ)
次の項では、データの各カテゴリのセマンティクおよび構文について詳細に説明します。
XMLとJSONの応答には(形式以外に)他にもいくつかの違いがあります。JSONの応答には、XMLの応答には含まれる、エンティティのルート名は含まれません。次のXML応答のemployeeルート/グループ名を参照してください。ルート名は、それを示すエンティティ名に由来します。
JSON
{
"firstName":"John",
"lastName": "Smith",
…
}
XML
<?xml version="1.0" encoding="UTF-8"?> <employee> <firstName>John</firstName> <lastName>Smith</lastName> … </employee>
RESTfulデータ・サービスの応答では、基本データ型およびプリミティブは単純なJSONまたはXMLフィールドとして示されます。次に例を示します。
JSON
{
"firstName":"John",
"lastName": "Smith",
…
}
XML
<?xml version="1.0" encoding="UTF-8"?> <employee> <firstName>John</firstName> <lastName>Smith</lastName> … </employee>
RESTfulデータ・サービスの処理では、JPAへの組込みおよび要素コレクションを除き、すべてのリレーションシップは参照で返されます。
relationshipsとは、1対1および1対多などエンティティの(JPA)リレーションシップをポイントするリンクです。たとえば、従業員が複数の電話番号(1対多)を保有しているとします。従業員が読み取られると、応答には従業員と電話エンティティ間のリレーションシップをポイントするリレーションシップ・リンクに加え、リンクの一覧を含むようになり、各リンクは従業員が所有する(一意の)電話番号をポイントします。次に例を示します。
{
"firstName": "Jacob",
"gender": "Male",
"id": 743627,
"lastName": "Smith",
"version": 1,
"_relationships": [
{
"_link": {
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/hr/entity/Employee/743627/phoneNumbers",
"rel": "phoneNumbers"
}
}
],
"phoneNumbers": [
{
"_link": {
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/hr/entity/PhoneNumber/743627+cell",
"method": "GET",
"rel": "self"
}
},
{
"_link": {
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/hr/entity/PhoneNumber/743627+work",
"method": "GET",
"rel": "self"
}
}
]
}
組込みオブジェクトおよび要素のコレクションは完全に私有の(依存)オブジェクトです。IDは持たず、ElementCollectionにはカスケード・オプションはありません。ターゲット・オブジェクトは常に、その親と永続化、マージおよび削除されます。したがって、RESTfulデータ・サービスでは、リンクを提供するのではなく、これらのオブジェクトの応答を直接組込みます。たとえば、EmployeeオブジェクトでEmploymentPeriodがEmbeddedと定義されているとします。Employeeが読み取られると、応答にはEmploymentPeriodに対するリンクではなく、それを組込みオブジェクトとして含むようになります。リレーションシップは現在、組込み属性としてはサポートされていません。次の例を参照してください。
{
"firstName": "John",
"lastName": "Smith",
"employmentPeriod": {
"startDate": "2010-04-23T14:12:03.905-04:00",
"endDate": "2013-01-23T12:00:02.301-04:00",
"_relationships": []
},
...
}
同様に、要素のコレクションも、RESTfulデータ・サービスの応答にリンクとしてではなく直接含まれます。たとえば、EmployeeオブジェクトでCertificationオブジェクトのコレクションとして"certifications"属性が定義されているとします。Employeeが読み取られると、応答にはリンクではなくCertificationオブジェクトのリストが含まれます。
{
"firstName": "John",
"lastName": "Smith",
"certifications": [
{
"issueDate": "2013-04-23T15:02:23.071-04:00",
"name": "Java"
},
{
"issueDate": "2010-05-23T11:02:23.033-04:00",
"name": "Weblogic"
}
],
...
}
この章のソリューションが実装されているその他のテクノロジおよびツールの詳細は、次の参考資料を参照してください。
http://docs.oracle.com/javaee/6/tutorial/doc/giepu.htmlのJava EE 6チュートリアルのJAX-RSでのRESTful Webサービスの構築に関する項。
http://wiki.eclipse.org/EclipseLink/Examples/REST/GettingStartedのRESTfulサービスの例に関する項。
http://jcp.org/en/jsr/detail?id=311の「JSR 311: JAX-RS: The Java API for RESTful Web Services」。
http://jersey.java.net/のJerseyプロジェクト。
次の種類のRESTful処理は、RESTfulデータ・サービスを使用する際に、HTTPを使用してJPAで使用できます。
エンティティ操作とは、永続性ユニット内の特定の種類のエンティティに対して実行する操作です。
エンティティ操作の基本URIは次のとおりです。
/persistence/{version}/{unit-name}/entity/{type}/*
{type}値は、タイプ名(ディスクリプタ・エイリアス)を意味します。
サポートされるエンティティ操作は次のとおりです。
HTTPリクエストの構文
GET /persistence/{version}/{unit-name}/entity/{type}/{id}?{hints}
ここで、
{id}は文字列です。
hintsは、キーがEclipseLink問合せのヒント名であるHTTP問合せパラメータを使用して指定します。
使用例
GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1
次のものを生成
JSONまたはXML
応答
OKとエンティティを含むペイロード
エンティティが存在しない場合はNOT_FOUND
使用状況
コンポジット・キー
コンポジット・キーがサポートされています。+は予約文字で、キーを示すフィールドには使用できません。コンポジット・キーは、+文字を使用して分割され、Javaの属性名のデフォルトのソート順に従って指定される必要があります。
たとえば、Phoneエンティティに、extB=123およびextA=321という属性があるとします。このエンティティを探すURLは、次のとおりです。
http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Phone/321+123
Javaでソートされる場合、extAはextBの前になるので、321は123の前になります。
結果のキャッシュ
デフォルトのEclipseLinkおよびHTTPのキャッシュが有効になっており、標準の方法で構成されています。
リフレッシュ
Refreshの問合せのヒントにfindを使用してEntityManager.refresh操作を起動できます。
属性
エンティティの属性にナビゲート(たとえば、単一のRESTリクエストで従業員と関連付られているAddressエンティティを取得)する場合、次のように1レベルまでサポートされています。
/persistence/v1.0/{unit-name}/entity/{type}/{id}/{relationship}は機能します。
これに対し、
/persistence/v1.0/{unit-name}/entity/{type}/{id}/{relationship}/{index}/{relationship2}は機能しません。
HTTPリクエストの構文
PUT /persistence/{version}/{unit-name}/entity/{type}
使用例
PUT http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo
次のものを使用
JSONまたはXML
ペイロード
エンティティ
次のものを生成
JSONまたはXML
応答
永続性操作によって返されたエンティティを含むペイロード
使用状況
多重呼出し不変であるにはPUTが必要です。その結果、サーバーがIDフィールドの提供を期待するオブジェクトで呼び出されると失敗します。これは一般的に、メタデータが生成されたキーを指定し、そのキーを含むフィールドに値がない場合に発生します。
HTTPリクエストの構文
POST /persistence/{version}/{unit-name}/entity/{type}
使用例
POST http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo
次のものを使用
JSONまたはXML
ペイロード
エンティティ
次のものを生成
JSONまたはXML
応答
マージ操作によって返されたエンティティを含むペイロード
マージはオブジェクト・グラフを取り、比較を介して永続性コンテキストの一部とします。これは、オブジェクトと関係するすべてのオブジェクトをすでに存在するものと比較し、INSERT、UPDATE、DELETEを発行して、そのオブジェクトを永続性コンテキストに配置します。
HTTPリクエストの構文
DELETE /persistence/{version}/{unit-name}/entity/{type}{id}
ここで{id}は、文字列を使用して定義します。
使用例
DELETE http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1
応答
OK
リレーションシップ操作の基本URIは次のとおりです。
/persistence/{version}/{unit-name}/entity/{entity}/{id}/{relationship}
サポートされるリレーションシップ操作は次のとおりです。
この操作を使用すると、リレーションシップの値を取得できます。
HTTPリクエストの構文
GET /persistence/{version}/{unit-name}/entity/{type}/{id}/{relationship}
ここで、
{id}は文字列です。
{relationship}はリレーションシップのJPA名です。
使用例
GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1/myRelationship
次のものを生成
JSONまたはXML
応答
OK、エンティティまたはエンティティのリストを含むペイロード
エンティティが存在しない場合はNOT_FOUND
この操作を使用すると、多対1のリレーションシップのリストを追加したり、値を置換できます。
HTTPリクエストの構文
POST /persistence/{version}/{unit-name}/entity/{type}/{id}/{relationship}?{partner}
|
注意:
|
例
一方向のリレーションシップの場合、次のように{partner}は不要です。
POST http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1/myRelationship
双方向のリレーションシップの場合、リレーションシップの逆側を構成する属性名を入力する必要があります。たとえば、リレーションシップの逆側がBid.auctionであるとき、Auction.bidを更新する場合、次を使用します。
POST http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1/myRelationship?partner=bid
次のものを使用
JSONまたはXML
ペイロード
新しい値のエンティティ。
次のものを生成
JSONまたはXML
応答
要素が追加されたエンティティを含むペイロード
リストから特定のエンティティを削除したり、多対1のリレーションシップでnullを削除するにはこの操作を使用します。
HTTPリクエストの構文
DELETE /persistence/{version}/{unit-name}/entity/{type}/{id}/{relationship}?{relationshipListItemId}
ここで、relationshipListItemIdはオプションの問合せパラメータです。relationshipListItemIdは、リストから削除する{relationship}がリストの場合のみ意味があります。relationshipListItemIdは、リレーションシップ・リストのそのメンバーのみを削除する必要がある場合、リレーションシップ・リストのメンバーのidに設定します。relationshipListItemIdを指定しない場合は、{relationship}で指定されたリスト全体が削除されます。
使用例
DELETE http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1/myRelationship
次のものを使用
JSONまたはXML
次のものを生成
JSONまたはXML
応答
OK
要素が削除されたエンティティを含むペイロード
問合せ操作の基本URIは次のとおりです。
GET /persistence/{version}/{unit-name}/query/{name}{params}
次の問合せ操作がサポートされています。
JPAでは、読取りを実行する名前付きの問合せは2とおりの方法で実行できます。いずれもREST APIでサポートされています。これらは次のとおりです。
HTTPリクエストの構文
GET /persistence/{version}/{unit-name}/query/{name};{parameters}? {hints}
ここで、
parametersは、HTTPマトリックス・パラメータを使用して指定します。
hintsは、HTTPの問合せパラメータおよびEclipseLinkの問合せのヒント名であるキーを使用して指定します。
例
GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/query/Foo.findByName;name=myname
GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/query/Foo.findByName;name=myname?eclipselink.jdbc.max-results=500
次のものを生成
JSONまたはXML
応答
エンティティのリストを含むペイロード。XML応答には、アイテムのコレクションのグループ名としてListが含まれ、また返されたコレクションの各メンバーのグループ名としてitemが含まれます。JSONでは、角括弧[]を使用しコレクションをカプセル化し、波括弧{}を使用し、コレクションの各メンバーをカプセル化します。次に例を示します。
XMLの例
<?xml version="1.0" encoding="UTF-8"?>
<List>
<item>
<firstName>Miles</firstName>
<lastName>Davis</lastName>
<manager>
<firstName>Charlie</firstName>
<lastName>Parker</lastName>
<gender>Male</gender>
<id>26</id>
</manager>
</item>
<item>
<firstName>Charlie</firstName>
<lastName>Parker</lastName>
<manager>
<firstName>Louis</firstName>
<lastName>Armstrong</lastName>
<gender>Male</gender>
<id>27</id>
</manager>
</item>
</List>
JSONの例
[
{
"firstName": "Miles",
"lastName": "Davis",
"manager": {
"firstName": "Charlie",
"lastName": "Parker",
"gender": "Male",
"id": 26
}
},
{
"firstName": "Charlie",
"lastName": "Parker",
"manager": {
"firstName": "Louis",
"lastName": "Armstrong",
"gender": "Male",
"id": 27
}
}
]
HTTPリクエストの構文
POST /persistence/{version}/{unit-name}/query/{name};parameters?hints
ここで、
parametersは、HTTPマトリックス・パラメータを使用して指定します。
hintsは、HTTPの問合せパラメータおよびEclipseLinkの問合せのヒント名であるキーを使用して指定します。
例
POST http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/query/Foo.deleteAllByName;name=myname
POST http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/query/Foo.updateName;name=myname?eclipselink.jdbc.max-results=500
次のものを生成
JSONまたはXML
応答
更新または削除するエンティティの数を含むペイロード
HTTPリクエストの構文
GET /persistence/{version}/{unit-name}/singleResultQuery/{name};{parameters}?{hints}
ここで、
parametersは、HTTPマトリックス・パラメータを使用して指定します。
hintsは、HTTPの問合せパラメータおよびEclipseLinkの問合せのヒント名であるキーを使用して指定します。
使用例
GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/singleResultQuery/Foo.findByName;name=myname
次のものを生成
JSON、XMLまたはapplication/octet-stream
応答
エンティティを含むペイロード
次に基本操作を示します。
HTTPリクエストの構文
GET /persistence/{version}
使用例
GET http://localhost:8080/exampleApp/persistence/v1.0
次のものを生成
JSONまたはXML
応答
永続性ユニット名一覧およびそのメタデータへのリンクを含むペイロード。次に例を示します。
[
{
"_link": {
"href": "http://localhost:8080/exampleApp/persistence/v1.0/employee/metadata",
"method": "application/json",
"rel": "employee"
}
},
{
"_link": {
"href": "http://localhost:8080/exampleApp/persistence/v1.0/traveler/metadata",
"method": "application/json",
"rel": "traveler"
}
}
]
次のメタデータ操作がサポートされています。
HTTPリクエストの構文
GET /persistence/{version}/{unit-name}/metadata
使用例
GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/metadata
次のものを生成
JSON
応答
OKと次のように、より詳細なメタデータへのリンクを含むタイプ一覧を含むペイロード
{
"persistenceUnitName": "hr",
"types": [
{
"_link": {
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/metadata/entity/Employee",
"method": "application/json",
"rel": "Employee"
}
},
{
"_link": {
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/metadata/entity/PhoneNumber",
"method": "application/json",
"rel": "PhoneNumber"
}
}
]
}
永続性ユニットが見つからない場合はNOT_FOUND
HTTPリクエストの構文
GET /persistence/{version}/{unit-name}/metadata/query
使用例
GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/metadata/query
次のものを生成
JSON
応答
OKと次のように、利用可能な問合せをすべて含むリストのペイロード
[
{
"queryName": "Employee.count",
"returnTypes": [
"Long"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.count",
"rel": "execute"
},
"jpql": "SELECT count(e) FROM Employee e"
},
{
"queryName": "EmployeeAddress.getRegion",
"returnTypes": [
"String",
"String",
"String"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/EmployeeAddress.getRegion",
"rel": "execute"
},
"jpql": "SELECT u.postalCode, u.province, u.street FROM EmployeeAddress u"
},
{
"queryName": "Employee.getPhoneNumbers",
"returnTypes": [
"String",
"String",
"PhoneNumber"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.getPhoneNumbers",
"rel": "execute"
},
"jpql": "SELECT e.firstName, e.lastName, pn FROM Employee e JOIN e.phoneNumbers pn"
},
{
"queryName": "EmployeeAddress.getPicture",
"returnTypes": [
"byte[]"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/EmployeeAddress.getPicture;id={id}",
"rel": "execute"
},
"jpql": "SELECT u.areaPicture FROM EmployeeAddress u where u.id = :id"
},
{
"queryName": "EmployeeAddress.updatePostalCode",
"returnTypes": [
"EmployeeAddress"
],
"linkTemplate": {
"method": "post",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/EmployeeAddress.updatePostalCode;postalCode={postalCode};id={id}",
"rel": "execute"
},
"jpql": "UPDATE EmployeeAddress u SET u.postalCode = :postalCode where u.id = :id"
},
{
"queryName": "Employee.salaryMax",
"returnTypes": [
"int",
"Object"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.salaryMax",
"rel": "execute"
},
"jpql": "SELECT e.id, max(e.salary) AS max_salary from Employee e GROUP BY e.id, e.salary"
},
{
"queryName": "EmployeeAddress.getAll",
"returnTypes": [
"EmployeeAddress"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/EmployeeAddress.getAll",
"rel": "execute"
},
"jpql": "SELECT u FROM EmployeeAddress u"
},
{
"queryName": "EmployeeAddress.getById",
"returnTypes": [
"EmployeeAddress"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/EmployeeAddress.getById;id={id}",
"rel": "execute"
},
"jpql": "SELECT u FROM EmployeeAddress u where u.id = :id"
},
{
"queryName": "Employee.getManagerById",
"returnTypes": [
"String",
"String",
"Employee"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.getManagerById;id={id}",
"rel": "execute"
},
"jpql": "select u.firstName, u.lastName, u.manager from Employee u where u.id = :id"
},
{
"queryName": "Employee.findAll",
"returnTypes": [
"Employee"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.findAll",
"rel": "execute"
},
"jpql": "SELECT e FROM Employee e ORDER BY e.id"
},
{
"queryName": "Employee.getManager",
"returnTypes": [
"String",
"String",
"Employee"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.getManager",
"rel": "execute"
},
"jpql": "select u.firstName, u.lastName, u.manager from Employee u"
}
]
永続性ユニットが見つからない場合はNOT_FOUND
HTTPリクエストの構文
GET /persistence/{version}/{unit-name}/metadata/entity/ type
使用例
GET http://localhost:8080/CustomerApp/persistence/v1.0/Inventory/metadata/entity/Customer
次のものを生成
JSON
応答
OKと次のように、エンティティの詳細およびそれに対して実行可能な操作を含むペイロード
{
"name": "Employee",
"attributes": [
{
"name": "id",
"type": "int"
},
{
"name": "firstName",
"type": "String"
},
{
"name": "gender",
"type": "Gender"
},
{
"name": "lastName",
"type": "String"
},
{
"name": "salary",
"type": "double"
},
{
"name": "version",
"type": "Long"
},
{
"name": "period",
"type": "EmploymentPeriod"
},
{
"name": "manager",
"type": "Employee"
},
{
"name": "office",
"type": "Office"
},
{
"name": "address",
"type": "EmployeeAddress"
},
{
"name": "certifications",
"type": "List<Certification>"
},
{
"name": "responsibilities",
"type": "List<String>"
},
{
"name": "projects",
"type": "List<Project>"
},
{
"name": "expertiseAreas",
"type": "List<Expertise>"
},
{
"name": "managedEmployees",
"type": "List<Employee>"
},
{
"name": "phoneNumbers",
"type": "List<PhoneNumber>"
}
],
"linkTemplates": [
{
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/entity/Employee/{primaryKey}",
"rel": "find"
},
{
"method": "put",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/entity/Employee",
"rel": "persist"
},
{
"method": "post",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/entity/Employee",
"rel": "update"
},
{
"method": "delete",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/entity/Employee/{primaryKey}",
"rel": "delete"
}
],
"queries": [
{
"queryName": "Employee.count",
"returnTypes": [
"Long"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.count",
"rel": "execute"
},
"jpql": "SELECT count(e) FROM Employee e"
},
{
"queryName": "Employee.getPhoneNumbers",
"returnTypes": [
"String",
"String",
"PhoneNumber"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.getPhoneNumbers",
"rel": "execute"
},
"jpql": "SELECT e.firstName, e.lastName, pn FROM Employee e JOIN e.phoneNumbers pn"
},
{
"queryName": "Employee.salaryMax",
"returnTypes": [
"int",
"Object"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.salaryMax",
"rel": "execute"
},
"jpql": "SELECT e.id, max(e.salary) AS max_salary from Employee e GROUP BY e.id, e.salary"
},
{
"queryName": "Employee.getManagerById",
"returnTypes": [
"String",
"String",
"Employee"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.getManagerById;id={id}",
"rel": "execute"
},
"jpql": "select u.firstName, u.lastName, u.manager from Employee u where u.id = :id"
},
{
"queryName": "Employee.findAll",
"returnTypes": [
"Employee"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.findAll",
"rel": "execute"
},
"jpql": "SELECT e FROM Employee e ORDER BY e.id"
},
{
"queryName": "Employee.getManager",
"returnTypes": [
"String",
"String",
"Employee"
],
"linkTemplate": {
"method": "get",
"href": "http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/hr/query/Employee.getManager",
"rel": "execute"
},
"jpql": "select u.firstName, u.lastName, u.manager from Employee u"
}
]
}
永続性ユニットが見つからない場合はNOT_FOUND
