20 RESTfulデータ・サービスからのJPAエンティティの公開
この章の内容は次のとおりです。
ユース・ケース
HTML5/JavaScriptおよびモバイル・テクノロジを含む、Thinサーバー・アーキテクチャ(TSA)クライアントを開発するために、RESTを介して永続性データ・モデルおよびアプリケーション・ロジックを公開します。
解決方法
RESTfulデータ・サービスを使用すると、JAX-RSコードを記述する必要なく、RESTfulサービスを使用するエンティティを公開できます。
コンポーネント
-
次を含むJava EEアプリケーション・サーバー
-
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以降。
-
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を使用する例については、http://wiki.eclipse.org/EclipseLink/Examples/REST/GettingStarted
のRESTfulサービスの例に関する項を参照してください。RESTfulデータ・サービスを使用してこの手順を単純化する方法の詳細は、この章を続けて読んでください。
RESTfulデータ・サービスは、Webアプリケーションの機能を拡張するWebフラグメントを介して有効にします。このREST機能は、WebアプリケーションのWEB-INF/lib
フォルダにRESTfulデータ・サービスのJARファイルを含めることによって有効になります。
実行しているアプリケーションにパッケージされたすべての永続性ユニットおよびその中にプロビジョニングされている動的なすべての永続性ユニットへのアクセスは、RESTfulデータ・サービスのランタイムにより提供されます。
ソリューションの実装
この項では、RESTfulデータ・サービスを使用してJPAエンティティを公開する、次のタスクについて説明します。
ステップ1: 前提条件
RESTfulデータ・サービスを実装および使用するには、次が必要です。
-
Oracle WebLogic Server 12c (12.1.3)以上(次を含む)。
-
EclipseLink 2.4以上(永続性プロバイダとして構成)。
-
Java API for RESTful Web Services (JAX-RS) 1.0仕様の参照実装であるJersey。
-
-
次のいずれかのJava EEアプリケーション・サーバー:
-
Oracle WebLogic Server 12c (12.1.3)以上。
-
Glassfish Server 3.1.2以上。
注意:
Glassfish Server 3.1.2では、EclipseLink 2.4.2で出荷されたRESTfulデータ・サービスのバージョンを使用するには、EclipseLinkのバージョンをアップグレードする必要があります(DBWSも含める必要があります)。EclipseLinkのダウンロードについては、
http://www.eclipse.org/eclipselink/downloads/
を参照してください。
これらのサーバーには次が含まれます。
-
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のリリース番号を指します)。 -
org.eclipse.persistence.jpars_
version_num
.jar
ファイル(version_num
は、org.eclipse.persistence.jpars_2.4.1.v20121003-ad44345.jar
など、jparsファイルのバージョンです)。このファイルは、Eclipse FoundationのEclipseLinkディストリビューション(http://www.eclipse.org/eclipselink/downloads/
)に含まれています。-
インストーラの配布では、ファイルは
eclipselink\jlib\jpa\
にあります。 -
バンドル配布では、ファイルは他のバンドルと一緒に置かれています。
-
-
Oracle Database、Oracle Database Express Edition (Oracle Database XE)またはMySQLを含む対応するすべてのJava Database Connectivity (JDBC)データベース。ここで説明する手順は、Oracle Database XE 11gリリース2のものです。
動作保証マトリックスについては、
https://www.oracle.com/technetwork/middleware/toplink/overview/index.html
を参照してください
ステップ2: アプリケーションの作成および構成
RESTfulデータ・サービスは、標準のJPAアプリケーションと機能するように設計されていますが、有効にするには、サービスを有効にするのみではなく、次で説明するいくつかの作業を行う必要があります。
ステップ3: RESTfulデータ・サービスのURIの基本の理解
RESTfulデータ・サービス用にREST呼び出しを行うURIは、次の標準のパターンに従っています。
-
アプリケーションのベースURIは、
http://server:port/application-name/persistence/{version}
です。注意:
TopLink 12.1.2のRESTfulデータ・サービスのバージョンは、
v1.0
で、このバージョン番号を使用してRESTfulデータ・サービスに対してRESTリクエストを行う必要があります。たとえば、現在のバージョンのRESTfulデータ・サービスを使用するアプリケーションのRESTfulデータ・サービスのベースURIは、http://localhost:8080/exampleApp/persistence/v1.0
などになります。注意:
EclipseLink 2.4.2以降では、バージョン番号なしでRESTfulデータ・サービスURIを使用するためのサポートは非推奨となり、今後のリリースでは削除される予定です。EclipseLink2.4.2のRESTfulデータ・サービスのバージョンは、
v1.0
で、このバージョン番号を使用してRESTfulデータ・サービスに対してRESTリクエストを行う必要があります。 -
永続性ユニット上のベース操作には、永続性ユニット名を追加します。
/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の構成方法の詳細は、「RESTfulデータ・サービスのAPIリファレンス」を参照してください。
ステップ4: JPA、JAXBまたはJSONを使用したエンティティの表現
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>
ステップ5: 永続性ユニットに対する操作用のクライアント呼び出しの発行
クライアントは、デプロイしたアプリケーションの永続性ユニットで操作を行うためにHTTP呼び出しを使用します。この呼び出しを構成する要件およびオプションの詳細は、「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ユーティリティでは、Accept
値のデフォルト値はapplication/xml
です。このとき、JSONを希望する場合はこの値を明示的に構成する必要があります。
ステップ7: RESTfulデータ・サービスの応答の構造の理解
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プロジェクト。
エンティティ操作
エンティティ操作とは、永続性ユニット内の特定の種類のエンティティに対して実行する操作です。
エンティティ操作の基本URIは次のとおりです。
/persistence/{version}/{unit-name}/entity/{type}/*
{type}
値は、タイプ名(ディスクリプタ・エイリアス)を意味します。
サポートされるエンティティ操作は次のとおりです。
FIND
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
}は機能しません。
PERSIST
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フィールドの提供を期待するオブジェクトで呼び出されると失敗します。これは一般的に、メタデータが生成されたキーを指定し、そのキーを含むフィールドに値がない場合に発生します。
MERGE
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
を発行して、そのオブジェクトを永続性コンテキストに配置します。
リレーションシップに対するエンティティ操作
リレーションシップ操作の基本URIは次のとおりです。
/persistence/{version}/{unit-name}/entity/{entity}/{id}/{relationship}
サポートされるリレーションシップ操作は次のとおりです。
READ
この操作を使用すると、リレーションシップの値を取得できます。
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
ADD
この操作を使用すると、多対1のリレーションシップのリストを追加したり、値を置換できます。
HTTPリクエストの構文
POST /persistence/{version}/{unit-name}/entity/{type}/{id}/{relationship}?{partner}
注意:
partner
は問合せのパラメータとして指定する必要があります。partner
はマトリックス・パラメータとしては指定しないでください。
注意:
EclipseLink 2.4.2からは、partner
を問合せパラメータとして指定する必要があります。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
応答
要素が追加されたエンティティを含むペイロード
REMOVE
リストから特定のエンティティを削除したり、多対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
応答
-
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