blob: 8039e7800394651746ac8d63a23860869fab312d [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>Implementing the Solution | EclipseLink 2.7 Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
<meta name="date" content="2014-06-10T10:35:15Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Implementing the Solution" />
<meta name="relnum" content="Release 2.7" />
<link rel="stylesheet" type="text/css" href="../../dcommon/style.css" media="screen" />
<link rel="copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="start" href="../../index.htm" title="Home" type="text/html" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="prev" href="restful_jpa001.htm" title="Previous" type="text/html" />
<link rel="next" href="restful_jpa003.htm" title="Next" type="text/html" />
<!-- START: Disqus --><script type="text/javascript"> var disqus_developer = 0; </script><!-- END: Disqus --><!-- START: Sharethis --><script type="text/javascript">var switchTo5x=true;</script><script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script><script type="text/javascript" src="http://s.sharethis.com/loader.js"></script> <!-- END: Sharethis --></head>
<body bgcolor="#FFFFFF"><iframe id="docheader" frameborder="0" framemargin="0" scrolling="no" src="../../dcommon/header.html"></iframe><script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> google.load('search', '1', {language : 'en'}); google.setOnLoadCallback(function() { var customSearchOptions = {}; var googleAnalyticsOptions = {}; googleAnalyticsOptions['queryParameter'] = 'q'; googleAnalyticsOptions['categoryParameter'] = ''; customSearchOptions['googleAnalyticsOptions'] = googleAnalyticsOptions; var customSearchControl = new google.search.CustomSearchControl( '016171230611334810008:enkkfjmsqju', customSearchOptions); customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET); var options = new google.search.DrawOptions(); options.setSearchFormRoot('cse-search-form'); customSearchControl.draw('cse', options); }, true);</script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" /><div id="cse" style="width:100%;"></div>
<div class="header"><a id="top" name="top"></a>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><font face="helvetica, arial, sans-serif"><b>EclipseLink Solutions Guide for EclipseLink</b><br />
Release 2.7</div></td>
<td valign="bottom" align="right" width="144">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<tr>
<td align="center"><a href="restful_jpa001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="restful_jpa003.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
<td>&nbsp;</td>
</tr>
</table>
</div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="A1656101" name="A1656101"></a><a id="TLADG1157" name="TLADG1157"></a>
<div class="sect1">
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Implementing the Solution</font></h1>
<p>This section contains the following tasks for exposing JPA entities using RESTful Data Services:</p>
<ul>
<li>
<p><a href="#CHDCIBDG">Step 1: Prerequisites</a></p>
</li>
<li>
<p><a href="#CHDGGJJJ">Step 2: Create and Configure the Application</a></p>
</li>
<li>
<p><a href="#CHDBHBAC">Step 3: Understand RESTful Data Services URI Basics</a></p>
</li>
<li>
<p><a href="#CHDBIIFF">Step 4: Represent Entities Using JPA, JAXB, or JSON</a></p>
</li>
<li>
<p><a href="#CHDCIHEG">Step 5: Issue Client Calls for Operations on the Persistence Unit</a></p>
</li>
<li>
<p><a href="#CHDGJEDF">Step 6: Implement Security</a></p>
</li>
<li>
<p><a href="#CHDHGACD">Step 7: Understand the Structure of RESTful Data Services Responses</a></p>
</li>
</ul>
<a id="CHDCIBDG" name="CHDCIBDG"></a><a id="TLADG1158" name="TLADG1158"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Step 1: Prerequisites</font></h2>
<p>To implement and use RESTful Data Services, you need:</p>
<ul>
<li>
<p>Either of the following Java EE application servers:</p>
<ul>
<li>
<p>Oracle WebLogic Server Release 2.7 or later.</p>
</li>
<li>
<p>Glassfish Server 3.1.2 or later.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>With Glassfish Server 3.1.2, you must upgrade the EclipseLink version to use the version of the RESTful Data Services shipped in EclipseLink 2.4.2 (and must also include DBWS). See <code><a href="http://www.eclipse.org/eclipselink/downloads/">http://www.eclipse.org/eclipselink/downloads/</a></code> for EclipseLink downloads.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
</li>
</ul>
<p>Those servers include the following:</p>
<ul>
<li>
<p>EclipseLink 2.4 or later, configured as the persistence provider.</p>
</li>
<li>
<p>Jersey, the reference implementation of the Java API for RESTful Web Services (JAX-RS) 1.0 specification.</p>
</li>
</ul>
</li>
<li>
<p>The <code>org.eclipse.persistence.jpars_</code><em><code>version_num</code></em><code>.jar</code> file, where <em><code>version_num</code></em> is the version of the jpars file, for example, <code>org.eclipse.persistence.jpars_2.4.1.v20121003-ad44345.jar</code>. This file is included in the EclipseLink distributions from the Eclipse foundation, at <code><a href="http://www.eclipse.org/eclipselink/downloads/">http://www.eclipse.org/eclipselink/downloads/</a></code>:</p>
<ul>
<li>
<p>In the installer distribution, the file is located in <code>eclipselink\jlib\jpa\</code>.</p>
</li>
<li>
<p>In the bundles distribution, the file is located with the other bundles.</p>
</li>
</ul>
</li>
<li>
<p>Any compliant Java Database Connectivity (JDBC) database, including Oracle Database, Oracle Database Express Edition (Oracle Database XE), or MySQL. These instructions are based on Oracle Database XE 11g Release 2.</p>
<p>For the certification matrix, see</p>
</li>
</ul>
</div>
<!-- class="sect2" -->
<a id="CHDGGJJJ" name="CHDGGJJJ"></a><a id="TLADG1159" name="TLADG1159"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Step 2: Create and Configure the Application</font></h2>
<p>RESTful Data Services are designed to function with standard JPA applications, with little extra work required beyond enabling the service, as described below:</p>
<ol>
<li><a id="CHDIFBID" name="CHDIFBID"></a>
<p>Develop an application using one or more standard JPA persistence units, package it in a Web ARchive (WAR) file, and deploy it normally.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>The fragment must be placed inside a WAR, because it offers Web services. That WAR may optionally be packaged inside an Enterprise Archive (EAR) file.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>Weaving is required for several RESTful Data Services features to work: providing relationships as links, editing relationships, and dealing with lazy many-to-one relationships. Therefore, for those features, you must either deploy to a Java EE compliant server or statically weave your classes.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
</li>
<li><a id="CHDDHCHE" name="CHDDHCHE"></a>
<p>Include the RESTful Data Services servlet in the WAR containing the application. (For instructions on downloading, see.<a href="#CHDCIBDG">Step 1: Prerequisites</a>)</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>The RESTful Data Services JAR file includes a <code>web-fragment.xml</code> file that identifies the servlet and defines the root URI for the RESTful service.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p>Add the <code>org.eclipse.persistence.jpars_</code><em><code>version_num</code></em><code>.jar</code> file to the WAR containing the application, under <code>WEB-INF/lib</code>.</p>
</li>
</ol>
</div>
<!-- class="sect2" -->
<a id="CHDBHBAC" name="CHDBHBAC"></a><a id="TLADG1160" name="TLADG1160"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Step 3: Understand RESTful Data Services URI Basics</font></h2>
<p>URIs used for making REST calls for RESTful Data Services follow these standard patterns:</p>
<ul>
<li>
<p>The base URI for an application is: <code>http://server:port/application-name/persistence/{version}</code></p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>As of EclipseLink 2.4.2, support for using RESTful Data Services URIs without a version number is deprecated and will be removed in future releases. The version of RESTful Data Services in EclipseLink 2.4.2 is <code>v1.0</code>, and that version number should be used to make REST requests to RESTful Data Services.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
</li>
<li>
<p>For base operations on the persistence unit, add the persistence unit name:</p>
<p><code>/persistence/{version}/{unit-name}</code></p>
</li>
<li>
<p>For specific types of operations, add the type of operation, for example:</p>
<ul>
<li>
<p>Entity operations: <code>/persistence/{version}/{unit-name}/entity</code></p>
</li>
<li>
<p>Query operations: <code>/persistence/{version}/{unit-name}/query</code></p>
</li>
<li>
<p>Single result query operations: <code>/persistence/{version}/{unit-name}/singleResultQuery</code></p>
</li>
<li>
<p>Persistence unit level metadata operations: <code>/persistence/{version}/{unit-name}/metadata</code></p>
</li>
<li>
<p>Base operations: <code>/persistence/{version}</code></p>
</li>
</ul>
</li>
</ul>
<p>For complete documentation on how to construct these URIs, see <a href="restful_jpa004.htm#CHDEGJIG">RESTful Data Services API Reference.</a></p>
</div>
<!-- class="sect2" -->
<a id="CHDBIIFF" name="CHDBIIFF"></a><a id="TLADG1165" name="TLADG1165"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Step 4: Represent Entities Using JPA, JAXB, or JSON</font></h2>
<p>Entities in RESTful Data Services are represented in two ways:</p>
<ul>
<li>
<p><strong>As JPA Entities</strong> - The mappings of the JPA entities must be represented in the typical JPA fashion, using either annotations or XML files. These mappings are used to interact with the data source.</p>
</li>
<li>
<p><strong>As JAXB/JSON</strong> - No specific mapping information is required when using JAXB/JSON. By default, RESTful Data Services use the JAXB defaults (defined in the JAXB specification) to map to JAXB/JSON. You can optionally provide JAXB annotations on the classes to alter the way the objects are mapped. Additionally, the persistence unit property <code>eclipselink.jpa-rs.oxm</code> can be specified in a persistence unit's <code>persistence.xml</code> to specify XML-defined JAXB mappings.</p>
</li>
</ul>
<a id="TLADG1166" name="TLADG1166"></a>
<div class="sect3"><a id="sthref157" name="sthref157"></a>
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Relationships</font></h3>
<p>In general, JAXB default mappings are sufficient to allow information exchange using JSON/JAXB. There are, however, some special cases when dealing with relationships.</p>
<a id="TLADG1167" name="TLADG1167"></a>
<p><b><font face="arial, helvetica, sans-serif" color="#330099">Bidirectional Relationships and Cycles</font></b></p>
<p>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:</p>
<p>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 <em>owning</em> entity. The other table--the one pointed to--is the <em>inverse</em> (non-owning) entity. JPA mapping provides a mapped-by attribute that defines which is which. The <code>mappedBy</code> 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.</p>
<p>Consider the following pseudo-code:</p>
<pre xml:space="preserve" class="oac_no_warn">
@Entity
ClassA{
@Id
int id
@OneToOne
myB
}
@Entity
ClassB{
@Id
int id
@OneToOne(mappedby="myB")
myA
}
</pre>
<p>If the objects are identified as follows...</p>
<ul>
<li>
<p><code>A1</code> with <code>id=1</code> and <code>myB = B1</code></p>
</li>
<li>
<p><code>B1</code> with <code>id=11</code> and <code>myA = A1</code></p>
</li>
</ul>
<p>...the following JSON corresponds to those objects:</p>
<pre xml:space="preserve" class="oac_no_warn">
A {
id:1
}
B {
id:11
myA: {
id: 1
}
}
</pre>
<a id="CHDBDBHJ" name="CHDBDBHJ"></a><a id="TLADG1168" name="TLADG1168"></a>
<p><b><font face="arial, helvetica, sans-serif" color="#330099">Passing By Value vs. Passing By Reference</font></b></p>
<p>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 <a href="#CHDBADFD">"Pass By Value"</a>), while <code>_relationship</code>s have "navigation" links (see <a href="#CHDFJAII">"Pass By Reference"</a>).</p>
<a id="CHDBADFD" name="CHDBADFD"></a><a id="TLADG1206" name="TLADG1206"></a>
<p><b><font face="arial, helvetica, sans-serif" color="#330099">Pass By Value</font></b></p>
<p>To pass an object by value, create typical JSON or XML that represents the object. The following JSON passes <code>myA</code> by value:</p>
<pre xml:space="preserve" class="oac_no_warn">
B {
id:11
myA {
id: 1
}
}
</pre>
<a id="CHDFJAII" name="CHDFJAII"></a><a id="TLADG1207" name="TLADG1207"></a>
<p><b><font face="arial, helvetica, sans-serif" color="#330099">Pass By Reference</font></b></p>
<p>To pass an object by reference, use a <code>_link</code>. The link represents the RESTful Data Services call necessary to get that object. The following JSON passes <code>myA</code> by reference:</p>
<pre xml:space="preserve" class="oac_no_warn">
B {
id:11
myA {
_link:{
href: "http://localhost:8080/app/persistence/v1.0/pu/entity/A/1"
method: "GET"
rel: "self"
}
}
}
</pre>
<p>A <code>link</code> consists of <code>href</code>, <code>method</code> and <code>rel</code> attributes.</p>
<ul>
<li>
<p>The <code>href</code> (Hypertext REFerence) is the URI of the entity linked to. The <code>href</code> uniquely identifies the linked entity or attribute.</p>
</li>
<li>
<p>The <code>method</code> identifies the operation the <code>href</code> is to be used for.</p>
</li>
<li>
<p>The <code>rel</code> represents the relationship between the containing entity and the entity linked to.</p>
</li>
</ul>
<p>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.</p>
<p>The following example shows JSON that can be sent to RESTful Data Services as a request, in a regular-expression-like syntax:</p>
<pre xml:space="preserve" class="oac_no_warn">
{
"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"
}
</pre>
<p>The following JSON represents an entity called <code>Auction</code> with several directly mapped fields and a collection of an entity called <code>Bid</code>.</p>
<pre xml:space="preserve" class="oac_no_warn">
{
"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"
}
}
]
}
</pre>
<p>XML representation mimics the JSON representation. The following is sample XML for an entity called <code>Auction</code>, with several directly mapped attributes and a list of an entity called <code>Bid</code>.</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;Auction&gt;
&lt;description&gt;Auction 1&lt;/description&gt;
&lt;endPrice&gt;0.0&lt;/endPrice&gt;
&lt;id&gt;2&lt;/id&gt;
&lt;image&gt;auction1.jpg&lt;/image&gt;
&lt;name&gt;A1&lt;/name&gt;
&lt;sold&gt;false&lt;/sold&gt;
&lt;startPrice&gt;100.0&lt;/startPrice&gt;
&lt;bids&gt;
&lt;_link href="http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/auction/entity/Bid/5" method="GET" rel="self" /&gt;
&lt;/bids&gt;
&lt;bids&gt;
&lt;_link href="http://localhost:8080/eclipselink.jpars.test/persistence/v1.0/auction/entity/Bid/6" method="GET" rel="self" /&gt;
&lt;/bids&gt;
&lt;/Auction&gt;
</pre></div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDCIHEG" name="CHDCIHEG"></a><a id="TLADG1161" name="TLADG1161"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Step 5: Issue Client Calls for Operations on the Persistence Unit</font></h2>
<p>Clients use HTTP calls to perform operations on persistence units in a deployed application. The requirements and options for constructing the calls are described in <a href="restful_jpa004.htm#CHDEGJIG">RESTful Data Services API Reference.</a></p>
<a id="CHDCDFHG" name="CHDCDFHG"></a><a id="TLADG1162" name="TLADG1162"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Specify Media Format in the Header</font></h3>
<p>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:</p>
<ul>
<li>
<p><code>Content-Type = application/json</code> indicates that the content being sent is JSON</p>
</li>
<li>
<p><code>Content-Type = application/xml</code> indicates that the content being sent is XML</p>
</li>
<li>
<p><code>Accept = application/json</code> indicates that the expected&nbsp;format of the result is JSON</p>
</li>
<li>
<p><code>Accept = application/xml</code> indicates that the expected&nbsp;format of the result is XML</p>
</li>
</ul>
<p>If no header value is specified, JSON is used by default. If <code>Content-type</code> is specified and <code>Accept</code> is not specified, the returned format matches the <code>Content-type</code> passed in.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>In many REST utilities, the <code>Accept</code> value is defaulted to <code>application/xml</code>. In those cases, you must configure this value explicitly if you want JSON.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
</div>
<!-- class="sect3" -->
<a id="CHDGBJGH" name="CHDGBJGH"></a><a id="TLADG1164" name="TLADG1164"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">About Logging</font></h3>
<p>Messages related to RESTful Data Services operations are logged to a logger called <code>org.eclipse.persistence.jpars</code>. Most messages are logged at the <code>FINE</code> level. Exception stacks are logged at <code>FINER</code>.</p>
<p>Messages related to operations within <code>EntityManager</code>s, <code>EntityManagerFactory</code>s and <code>JAXBContext</code>s are logged in the same manner as other EclipseLink logging.</p>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDGJEDF" name="CHDGJEDF"></a><a id="TLADG1171" name="TLADG1171"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Step 6: Implement Security</font></h2>
<p>Secure RESTful Data Services through typical REST security mechanisms.</p>
</div>
<!-- class="sect2" -->
<a id="CHDHGACD" name="CHDHGACD"></a><a id="TLADG1208" name="TLADG1208"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Step 7: Understand the Structure of RESTful Data Services Responses</font></h2>
<p>The RESTful Data Services response messages, either in XML or in JSON, contain following categories:</p>
<ul>
<li>
<p>Basic data types, such as <code>int</code>, <code>double</code>, <code>String</code>, <code>Integer</code>, <code>Double</code>, <code>Boolean</code>, etc.</p>
</li>
<li>
<p>Relationships (links and relationships)</p>
</li>
</ul>
<p>The next sections explain the semantic and syntactic details of each category of data.</p>
<p>There is also a minor generic difference between the XML and JSON responses (other than format). The JSON responses do not include the root name of an entity, while XML responses do. See the <code>employee</code> root/grouping name in the XML response below. The root name is derived from the name of the entity it represents.</p>
<p><strong>JSON</strong></p>
<pre xml:space="preserve" class="oac_no_warn">
{
"firstName":"John",
"lastName": "Smith",
&hellip;
}
</pre>
<p><strong>XML</strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;employee&gt;
&lt;firstName&gt;John&lt;/firstName&gt;
&lt;lastName&gt;Smith&lt;/lastName&gt;
&hellip;
&lt;/employee&gt;
</pre>
<a id="TLADG1209" name="TLADG1209"></a>
<div class="sect3"><a id="sthref158" name="sthref158"></a>
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Basic Data Types</font></h3>
<p>In the RESTful Data Services responses, basic data types and primitives are presented as simple JSON or XML fields. For example:</p>
<p><strong>JSON</strong></p>
<pre xml:space="preserve" class="oac_no_warn">
{
"firstName":"John",
"lastName": "Smith",
&hellip;
}
</pre>
<p><strong>XML</strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;employee&gt;
&lt;firstName&gt;John&lt;/firstName&gt;
&lt;lastName&gt;Smith&lt;/lastName&gt;
&hellip;
&lt;/employee&gt;
</pre></div>
<!-- class="sect3" -->
<a id="TLADG1210" name="TLADG1210"></a>
<div class="sect3"><a id="sthref159" name="sthref159"></a>
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Links and Relationships</font></h3>
<p>RESTful Data Services operations return all relationships by reference, with the exception of JPA embeddables and element collections.</p>
<p>The <code>relationships</code> 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:</p>
<pre xml:space="preserve" class="oac_no_warn">
{
"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"
}
}
]
}
</pre>
<p>Embedded objects and element collections are strictly privately-owned (dependent) objects.They have no identity, and there is no cascade option on an <code>ElementCollection</code>. 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 <code>Employee</code> object has <code>EmploymentPeriod</code> defined as <code>Embedded</code>. When the <code>Employee</code> is read, the response will contain <code>EmploymentPeriod</code> as an embedded object, not a link to it. Relationships are currently not supported for embedded attributes. See the example below:</p>
<pre xml:space="preserve" class="oac_no_warn">
{
"firstName": "John",
"lastName": "Smith",
"employmentPeriod": {
"startDate": "2010-04-23T14:12:03.905-04:00",
"endDate": "2013-01-23T12:00:02.301-04:00",
"_relationships": []
},
...
}
</pre>
<p>Similarly, element collections are also directly contained in RESTful Data Services responses as collections, not as links. For example, assume the <code>Employee</code> object has a <code>"certifications"</code> attribute defined as a collection of <code>Certification</code> objects. When the <code>Employee</code> is read, the response will contain list of <code>Certification</code> objects, not links:</p>
<pre xml:space="preserve" class="oac_no_warn">
{
"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"
}
],
...
}
</pre></div>
<!-- class="sect3" --></div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="restful_jpa001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="restful_jpa003.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
</tr>
</table>
</td>
<td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
<font size="-2">Copyright&nbsp;&copy;&nbsp;2014,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</font> <a href="../../dcommon/html/cpyr.htm"><br />
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
<div id="copyright">Copyright &copy; 2014 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-1608008-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
</html>