Introduction to the Solution

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 JPA-RS 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.

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 a 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 handles is as follows:

JPA bidirectional relationships are defined to have an owning side and a non-owning side. JPA mapping provides a mapped-by attribute that defines which is which. JPA-RS defaults 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
    }
  }

Cycles can be difficult to detect, and JPA-RS requires that you provide JAXB mappings. That allows EclipseLink to resolve cycles in the cases where they can cause problems. In general, issues arise only when you try to create a group of new objects that include a cycle. To avoid problems in such cases, choose one of the mappings in the cycle and map it as XMLTransient.

Pass By Reference, Pass By Value

JPA-RS allows relationship objects to be passed either by value or by reference.

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

To pass an object by reference, use a link. The link represents the JPA-RS call necessary to get that object. The following JSON passes myA by reference:

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

Lists can mix and match items represented by reference and by value.

JPA-RS read operations currently return all relationships by reference.

Sample JSON

The following example shows JSON that can be sent to JPA-RS in a regular-expression-like syntax:

  <code>
  {
    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 StaticAuction 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,
    "_relationships": [
      {
        "_link": {
        "href": "http://localhost:8080/eclipselink.jpars.test/persistence/auction-static/entity/StaticAuction/2/bids",
        "rel": "bids"
        }
      }
      ],
    "bids": [
      {
        "_link": {
       "href": "http://localhost:8080/eclipselink.jpars.test/persistence/auction-static/entity/StaticBid/5",
        "method": "GET",
        "rel": "self"
      }
    },
    {
      "_link": {
        "href": "http://localhost:8080/eclipselink.jpars.test/persistence/auction-static/entity/StaticBid/6",
        "method": "GET",
        "rel": "self"
      }
    }
  ]
  }

  <staticAuction xmlns:atom="http://www.w3.org/2005/Atom">
    <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>
    <_relationships>
      <_link href="http://localhost:8080/eclipselink.jpars.test/persistence/auction-static/entity/StaticAuction/2/bids" rel="bids" />
    </_relationships>
    <bids>
      <_link href="http://localhost:8080/eclipselink.jpars.test/persistence/auction-static/entity/StaticBid/5" method="GET" rel="self" />
    </bids>
    <bids>
      <_link href="http://localhost:8080/eclipselink.jpars.test/persistence/auction-static/entity/StaticBid/6" method="GET" rel="self" />
    </bids>
  </staticAuction>