Implementing the Solution

Relationships

In general, JAXB default mappings are sufficient to allow information exchange using JSON/JAXB. There are, however, some special cases when dealing with relationships.

Bidirectional Relationships and Cycles

Bidirectional relationships are typical in JPA and are easy to represent in a database using foreign keys. They are more difficult to represent in an XML or JSON document using standard JAXB. However, the EclipseLink JAXB implementation provides a way to define an inverse relationship. Inverse relationships are not directly written to XML or JSON but are populated when the XML or JSON is unmarshalled. The way this is handled is as follows:

JPA bidirectional relationships are defined to have an owning side and a non-owning side. The entity that has the table with a foreign key in the database is the owning entity. The other table--the one pointed to--is the inverse (non-owning) entity. JPA mapping provides a mapped-by attribute that defines which is which. The mappedBy attribute must be on the inverse side. RESTful Data Services default the owning side to be an inverse relationship. As a result, when an object with an owned relationship is read or written, that relationship is ignored.

Consider the following pseudo-code:

  @Entity
  ClassA{
 
  @Id
  int id
 
  @OneToOne
  myB
 
}
 
 
  @Entity
  ClassB{
 
  @Id
  int id
 
  @OneToOne(mappedby="myB")
  myA
 
}

If the objects are identified as follows...

• A1 with id=1 and myB = B1

• B1 with id=11 and myA = A1

...the following JSON corresponds to those objects:

  A {
    id:1
  }
 
  B {
    id:11
    myA: {
      id: 1
    }
  }

Passing By Value vs. Passing By Reference

RESTful Data Services allow relationship objects to be passed either by value or by reference in the REST request. JSON attributes hold resource references (see "Pass By Value"), while _relationships have "navigation" links (see "Pass By Reference").

Pass By Value

To pass an object by value, create typical JSON or XML that represents the object. The following JSON passes myA by value:

  B {
    id:11
    myA {
      id: 1
    }
  }

Pass By Reference

To pass an object by reference, use a _link. The link represents the RESTful Data Services call necessary to get that object. The following JSON passes myA by reference:

  B {
    id:11
    myA {
      _link:{
          href: "http://localhost:8080/app/persistence/v1.0/pu/entity/A/1"
          method: "GET"
          rel: "self"
      }
    }
  }

A link consists of href, method and rel attributes.

• The href (Hypertext REFerence) is the URI of the entity linked to. The href uniquely identifies the linked entity or attribute.

• The method identifies the operation the href is to be used for.

• The rel represents the relationship between the containing entity and the entity linked to.

Lists can mix and match items represented by reference and by value. The corresponding entity must exist if an item is represented by reference in a request; otherwise RESTful Data Services returns an error.

The following example shows JSON that can be sent to RESTful Data Services as a request, in a regular-expression-like syntax:

{
    "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"
     }

The following JSON represents an entity called Auction with several directly mapped fields and a collection of an entity called Bid.

  {
    "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 representation mimics the JSON representation. The following is sample XML for an entity called Auction, with several directly mapped attributes and a list of an entity called Bid.

<?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> 

Specify Media Format in the Header

This REST interface can handle both XML and JSON representations of data. The caller is responsible for using HTTP header values to indicate the format of the content:

• Content-Type = application/json indicates that the content being sent is JSON

• Content-Type = application/xml indicates that the content being sent is XML

• Accept = application/json indicates that the expected format of the result is JSON

• Accept = application/xml indicates that the expected format of the result is XML

If no header value is specified, JSON is used by default. If Content-type is specified and Accept is not specified, the returned format matches the Content-type passed in.

About Logging

Messages related to RESTful Data Services operations are logged to a logger called org.eclipse.persistence.jpars. Most messages are logged at the FINE level. Exception stacks are logged at FINER.

Messages related to operations within EntityManagers, EntityManagerFactorys and JAXBContexts are logged in the same manner as other EclipseLink logging.

Basic Data Types

In the RESTful Data Services responses, basic data types and primitives are presented as simple JSON or XML fields. For example:

JSON

{
   "firstName":"John",
   "lastName": "Smith",
   …
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<employee>
   <firstName>John</firstName>
   <lastName>Smith</lastName>
   …
</employee>

Links and Relationships

RESTful Data Services operations return all relationships by reference, with the exception of JPA embeddables and element collections.

The relationships are links pointing to the (JPA) relationships of an entity, such as one-to-one and one-to-many. For example, assume that an employee has multiple phone numbers (one-to-many). When the employee is read, the response will contain a relationship link pointing to the relationship between the employee and the phone entities, plus a list of the links, with each link pointing to a (unique) phone number that the employee owns. For example:

{
   "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"
         }
      }
   ]
}

Embedded objects and element collections are strictly privately-owned (dependent) objects.They have no identity, and there is no cascade option on an ElementCollection. The target objects are always persisted, merged, and removed with their parent. Therefore, RESTful Data Services embeds these objects directly in responses, rather than providing links to them. For example, assume the Employee object has EmploymentPeriod defined as Embedded. When the Employee is read, the response will contain EmploymentPeriod as an embedded object, not a link to it. Relationships are currently not supported for embedded attributes. See the example below:

{
   "firstName": "John",
   "lastName": "Smith",
 
   "employmentPeriod": {
      "startDate": "2010-04-23T14:12:03.905-04:00",
      "endDate": "2013-01-23T12:00:02.301-04:00",
      "_relationships": []
   },
   ...
}

Similarly, element collections are also directly contained in RESTful Data Services responses as collections, not as links. For example, assume the Employee object has a "certifications" attribute defined as a collection of Certification objects. When the Employee is read, the response will contain list of Certification objects, not links:

{
   "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"
      }
   ],
   ...
}