1. Oracle TopLinkソリューション・ガイド
  2. RESTfulデータ・サービスからのJPAエンティティの公開

20 RESTfulデータ・サービスからのJPAエンティティの公開

この章では、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アプリケーションと機能するように設計されていますが、有効にするには、サービスを有効にするのみではなく、次で説明するいくつかの作業を行う必要があります。

  1. 1つ以上の標準のJPA永続性ユニットを使用してアプリケーションを開発し、Web ARchive (WAR)ファイルにパッケージして、普通にデプロイします。

    注意:

    フラグメントはWebサービスを提供するのでWARに含める必要があります。WARはオプションでEnterprise Archive (EAR)ファイルにパッケージすることもできます。

    注意:

    いくつかのRESTfulデータ・サービスの機能には、リレーションシップをリンクとして提供したり、リレーションシップを編集したり、多対1の遅延リレーションシップを処理するウィービンが必要です。したがって、これらの機能が必要な場合には、Java EEに対応のサーバーにデプロイするか、クラスを静的にウィーブする必要があります。

  2. アプリケーションを含むWARにRESTfulデータ・サービス・サーブレットを含めます。(ダウンロード方法の詳細は、「ステップ1: 前提条件」を参照してください。)

    注意:

    RESTfulデータ・サービスのJARファイルには、サーブレットを指定し、RESTfulサービスのルートURIを定義するweb-fragment.xmlファイルが含まれます。

    toplink-dataservices-web.jarファイルを、WEB-INF/lib下のアプリケーションを含むWARに追加します。

    org.eclipse.persistence.jpars_version_num.jarファイルを、アプリケーションが含まれているWAR (WEB-INF/libの下)に追加します。

ステップ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を希望する場合はこの値を明示的に構成する必要があります。

ロギングについて

RESTfulデータ・サービスの処理と関係するメッセージは、org.eclipse.persistence.jparsと呼ばれるロガーに記録されます。多くのメッセージは、FINEレベルで記録されます。例外スタックはFINERに記録されます。

EntityManager、EntityManagerFactoryおよびJAXBContext内の処理と関係するメッセージは、他のEclipseLinkのログと同様な方法で記録されます。

ステップ6: セキュリティの実装

RESTfulデータ・サービスは、典型的なのRESTセキュリティ・メカニズムを使用してセキュリティを確保します。

ステップ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"
      }
   ],
   ...
}

その他の参考資料

この章のソリューションが実装されているその他のテクノロジおよびツールの詳細は、次の参考資料を参照してください。

RESTfulデータ・サービスのAPIリファレンス

次の種類のRESTful処理は、RESTfulデータ・サービスを使用する際に、HTTPを使用してJPAで使用できます。

エンティティ操作

エンティティ操作とは、永続性ユニット内の特定の種類のエンティティに対して実行する操作です。

エンティティ操作の基本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を発行して、そのオブジェクトを永続性コンテキストに配置します。

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}

サポートされるリレーションシップ操作は次のとおりです。

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

注意:

リレーションシップ・オブジェクトは値または参照として渡すことができます。「値渡し対参照渡し」を参照してください。

次のものを生成

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 
                              
    
                           
    •