Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/batchClientApi.html ============================================================================== --- websites/staging/olingo/trunk/content/doc/odata4/tutorials/batchClientApi.html (added) +++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/batchClientApi.html Tue Sep 16 12:34:18 2014 @@ -0,0 +1,179 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html lang="en"> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="description" content="Apache Olingo provides libraries which enable developers to implement OData producers and OData consumers. The available OData Java library implements OData version 2.0. In future on goal is to provide an OData 4.0 compliant library once the OData standard is published at OASIS. The focus within the community is currently on the Java technology but it is up to the community to discuss if other environments find interest."> + <meta name="author" content=""> + <link rel="icon" href="/favicon.ico"> + <title> + Apache Olingo + </title><!-- Bootstrap core CSS --> + <link href="/css/bootstrap.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link href="/css/navbar.css" rel="stylesheet" type="text/css"><!-- Just for debugging purposes. Don't actually copy these 2 lines! --> + <link href="/css/offcanvas.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link rel="stylesheet" href="/css/main.css"> + <!--[if lt IE 9]><script src="/js/ie8-responsive-file-warning.js"></script><![endif]--> + + <script src="/js/ie-emulation-modes-warning.js" type="text/javascript"> +</script><!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> + + <script src="/js/ie10-viewport-bug-workaround.js" type="text/javascript"> +</script><!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> + </head> + + <body> + <div class="container"> + <!-- Static navbar --> + <div class="navbar navbar-default" role="navigation"> + <div class="container-fluid"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <img class="navbar-brand" src="/img/OlingoOrangeTM.png" style="width:62px;" > + <a class="navbar-brand" href="#">Apache Olingoâ¢</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + + <li><a href="/">Home</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="http://www.apache.org/foundation/";>ASF Home</a></li> + <li><a href="http://projects.apache.org/";>Projects</a></li> + <li><a href="http://people.apache.org/";>People</a></li> + <li><a href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a></li> + <li><a href="http://www.apache.org/dyn/closer.cgi";>Download</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Support Apache</a></li> + </ul> + </li> + + <li><a href="http://www.apache.org/licenses/";>License</a></li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/download.html">Download OData 2.0 Java</a></li> + <li><a href="/doc/javascript/download.html">Download OData 4.0 JavaScript</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/index.html">Documentation OData 2.0 Java</a></li> + <li><a href="/doc/javascript/index.html">Documentation OData 4.0 JavaScript</a></li> + </ul> + </li> + <li><a href="/support.html">Support</a></li> + + </ul> + + <img class="navbar-right" height="50px" src="/img/asf-logo.gif"> + + </div><!--/.nav-collapse --> + </div><!--/.container-fluid --> + </div><!-- Main component for a primary marketing message or call to action --><h2 id="batch-request-construction">Batch Request construction</h2> +<p><strong>Query Request construction</strong></p> +<p>A BatchQueryPart is a representation of a single retrieve request. You can use the following methods in order to fill out a request:</p> +<ul> +<li>method(String) </li> +<li>uri(String) </li> +<li>contentId(String) </li> +<li>headers(List<String>)</li> +</ul> +<pre><code> +BatchQueryPart request = BatchQueryPart.method("GET").uri("$metadata").build(); +</pre> + +<p></code> +<strong>Note:</strong> The valid method value is GET.</p> +<p><strong>ChangeSet construction</strong> +A BatchChangeSetPart is a representation of a single change request. You can use the following methods in order to fill out a change request:</p> +<ul> +<li>method(String)</li> +<li>uri(String)</li> +<li>headers(List<String>)</li> +<li>contentId(String)</li> +<li>body(String)</li> +</ul> +<pre><code>Map<String, String> changeSetHeaders = new HashMap<String, String>(); +changeSetHeaders.put("content-type", "application/json;odata=verbose"); +BatchChangeSetPart changeRequest = BatchChangeSetPart.method("PUT") +.uri("Employees('2')/EmployeeName") +.headers(changeSetHeaders) +.body("{\"EmployeeName\":\"Frederic Fall MODIFIED\"}") +.build(); +... +</pre> + +<p></code> +<strong>Note:</strong> The valid method values are POST, PUT, DELETE or MERGE.</p> +<p>The change request has to become a part of a changeSet. For that you need to create a changeSet object and to attach the change request to this object.</p> +<div class="codehilite"><pre><span class="p">...</span> +<span class="n">BatchChangeSet</span> <span class="n">changeSet</span> <span class="p">=</span> <span class="n">BatchChangeSet</span><span class="p">.</span><span class="n">newBuilder</span><span class="p">().</span><span class="n">build</span><span class="p">();</span> +<span class="n">changeSet</span><span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="n">changeRequest</span><span class="p">);</span> +</pre></div> + + +<p><strong>Batch request payload construction</strong> +After you collected all created parts, you can call the method writeBatchRequestBody(..) provided by EntityProvider</p> +<div class="codehilite"><pre><span class="p">...</span> +<span class="n">List</span><span class="o"><</span><span class="n">BatchPart</span><span class="o">></span> <span class="n">batchParts</span> <span class="p">=</span> <span class="n">new</span> <span class="n">ArrayList</span><span class="o"><</span><span class="n">BatchPart</span><span class="o">></span><span class="p">();</span> +<span class="n">batchParts</span><span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="n">request</span><span class="p">);</span> +<span class="n">batchParts</span><span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="n">changeSet</span><span class="p">);</span> + +<span class="n">InputStream</span> <span class="n">payload</span> <span class="p">=</span> <span class="n">EntityProvider</span><span class="p">.</span><span class="n">writeBatchRequest</span><span class="p">(</span><span class="n">batchParts</span><span class="p">,</span> <span class="n">BOUNDARY</span><span class="p">);</span> +</pre></div> + + +<p>The second parameter BOUNDARY is necessary information for the construction of the batch request payload. It is the value of the boundary parameter, that is set in Content-Type header of the batch request.</p> +<p><strong>Batch Response interpretation</strong> +Interpretation of the batch response payload +You receive a list of single response by calling EntityProvider.parseBatchResponse(..)</p> +<div class="codehilite"><pre><span class="n">List</span><span class="o"><</span><span class="n">BatchSingleResponse</span><span class="o">></span> <span class="n">responses</span> <span class="p">=</span> <span class="n">EntityProvider</span><span class="p">.</span><span class="n">parseBatchResponse</span><span class="p">(</span><span class="n">responseBody</span><span class="p">,</span> <span class="n">contentType</span><span class="p">);</span> +<span class="k">for</span> <span class="p">(</span><span class="n">BatchSingleResponse</span> <span class="n">response</span> <span class="p">:</span> <span class="n">responses</span><span class="p">)</span> <span class="p">{</span> + <span class="n">response</span><span class="p">.</span><span class="n">getStatusCode</span><span class="p">());</span> + <span class="n">response</span><span class="p">.</span><span class="n">getStatusInfo</span><span class="p">());</span> + <span class="n">response</span><span class="p">.</span><span class="n">getHeader</span><span class="p">(</span><span class="n">HttpHeaders</span><span class="p">.</span><span class="n">CONTENT_TYPE</span><span class="p">);</span> + <span class="n">response</span><span class="p">.</span><span class="n">getBody</span><span class="p">();</span> + <span class="n">response</span><span class="p">.</span><span class="n">getContentId</span><span class="p">();</span> +<span class="p">}</span> +</pre></div><div align="center"> +<p>Copyright © 2013-2014, The Apache Software Foundation<br> + Apache Olingo, Olingo, Apache, the Apache feather, and + the Apache Olingo project logo are trademarks of the Apache Software + Foundation.</p> + <small><a href="/doc/odata2/privacy.html">Privacy</a></small> + </div> + </div><!-- /container --> + <!-- Bootstrap core JavaScript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="/js/jquery.js" type="text/javascript"> +</script> + <script src="/js/bootstrap.js" type="text/javascript"> + <script src="/js/offcanvas.js" type="text/javascript"> +</script> + <!-- Google Analytics: change UA-XXXXX-X to be your site's ID. --> + <script> + (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]= + function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date; + e=o.createElement(i);r=o.getElementsByTagName(i)[0]; + e.src='//www.google-analytics.com/analytics.js'; + r.parentNode.insertBefore(e,r)}(window,document,'script','ga')); + ga('create','UA-44963757-1');ga('send','pageview'); + </script> + </body> +</html>
Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/debug.html ============================================================================== --- websites/staging/olingo/trunk/content/doc/odata4/tutorials/debug.html (added) +++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/debug.html Tue Sep 16 12:34:18 2014 @@ -0,0 +1,295 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html lang="en"> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="description" content="Apache Olingo provides libraries which enable developers to implement OData producers and OData consumers. The available OData Java library implements OData version 2.0. In future on goal is to provide an OData 4.0 compliant library once the OData standard is published at OASIS. The focus within the community is currently on the Java technology but it is up to the community to discuss if other environments find interest."> + <meta name="author" content=""> + <link rel="icon" href="/favicon.ico"> + <title> + Apache Olingo + </title><!-- Bootstrap core CSS --> + <link href="/css/bootstrap.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link href="/css/navbar.css" rel="stylesheet" type="text/css"><!-- Just for debugging purposes. Don't actually copy these 2 lines! --> + <link href="/css/offcanvas.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link rel="stylesheet" href="/css/main.css"> + <!--[if lt IE 9]><script src="/js/ie8-responsive-file-warning.js"></script><![endif]--> + + <script src="/js/ie-emulation-modes-warning.js" type="text/javascript"> +</script><!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> + + <script src="/js/ie10-viewport-bug-workaround.js" type="text/javascript"> +</script><!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> + </head> + + <body> + <div class="container"> + <!-- Static navbar --> + <div class="navbar navbar-default" role="navigation"> + <div class="container-fluid"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <img class="navbar-brand" src="/img/OlingoOrangeTM.png" style="width:62px;" > + <a class="navbar-brand" href="#">Apache Olingoâ¢</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + + <li><a href="/">Home</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="http://www.apache.org/foundation/";>ASF Home</a></li> + <li><a href="http://projects.apache.org/";>Projects</a></li> + <li><a href="http://people.apache.org/";>People</a></li> + <li><a href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a></li> + <li><a href="http://www.apache.org/dyn/closer.cgi";>Download</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Support Apache</a></li> + </ul> + </li> + + <li><a href="http://www.apache.org/licenses/";>License</a></li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/download.html">Download OData 2.0 Java</a></li> + <li><a href="/doc/javascript/download.html">Download OData 4.0 JavaScript</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/index.html">Documentation OData 2.0 Java</a></li> + <li><a href="/doc/javascript/index.html">Documentation OData 4.0 JavaScript</a></li> + </ul> + </li> + <li><a href="/support.html">Support</a></li> + + </ul> + + <img class="navbar-right" height="50px" src="/img/asf-logo.gif"> + + </div><!--/.nav-collapse --> + </div><!--/.container-fluid --> + </div><!-- Main component for a primary marketing message or call to action --><h1 id="debug-support-and-error-handling">Debug Support and Error Handling</h1> +<hr /> +<h3 id="odata-error-conditions">OData Error Conditions</h3> +<p>OData exposes error conditions as HTTP responses with error status code (4xx and 5xx) and it is in the responsibility of a client to handle this situations. For more details see +<a href="http://www.odata.org/documentation/odata-v2-documentation/operations/#13_Error_Conditions";>OData Error Conditions</a>.</p> +<p>In OData the format for error messages is described in <a href="http://www.odata.org/developers/protocols/atom-format";>OData-Atom</a> and <a href="http://www.odata.org/documentation/json-format";>Odata-JSON</a>. Apache Olingo OData2 has implemented this this format for error message.</p> +<h3 id="debug-support">Debug Support</h3> +<p>The OData V2 error message format is limited to the HTTP status codes and gives indicators for client errors (status code 4xx) and server errors (5xx). For development and support this is not sufficient because of more technical information is needed for doing a deep error analysis.</p> +<p>Apache Olingo has implemented a feature to return more error information (stack traces, object states, runtime measurements â¦) within a response to ease the development and support use case. </p> +<p>For productive uses cases this feature is by default off. The following explains how to enable the feature and gives options to a service implementation to switch if on and off e.g. role based or by configuration.</p> +<h5 id="debugcallback">DebugCallback</h5> +<p>The debug feature can be enabled by the following callback implementation:</p> +<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">MyDebugCallback</span> <span class="n">implements</span> <span class="n">ODataDebugCallback</span> <span class="p">{</span> + <span class="p">@</span><span class="n">Override</span> + <span class="n">public</span> <span class="n">boolean</span> <span class="n">isDebugEnabled</span><span class="p">()</span> <span class="p">{</span> + <span class="n">boolean</span> <span class="n">isDebug</span> <span class="p">=</span> â¦<span class="p">;</span> <span class="o">//</span> <span class="n">true</span><span class="o">|</span><span class="n">configuration</span><span class="o">|</span><span class="n">user</span> <span class="n">role</span> <span class="n">check</span> + <span class="k">return</span> <span class="n">isDebug</span><span class="p">;</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> + + +<h5 id="register-debugcallback">Register DebugCallback</h5> +<p>In your service factory (<code>ODataServiceFactory</code>) implement the following method to register the callback:</p> +<div class="codehilite"><pre><span class="kd">public</span> <span class="o"><</span><span class="n">T</span> <span class="kd">extends</span> <span class="n">ODataCallback</span><span class="o">></span> <span class="n">T</span> <span class="n">getCallback</span><span class="o">(</span><span class="kd">final</span> <span class="n">Class</span><span class="o"><?</span> <span class="kd">extends</span> <span class="n">ODataCallback</span><span class="o">></span> <span class="n">callbackInterface</span><span class="o">)</span> <span class="o">{</span> + <span class="n">T</span> <span class="n">callback</span> + + <span class="nf">if</span> <span class="o">(</span><span class="n">callbackInterface</span><span class="o">.</span><span class="na">isAssignableFrom</span><span class="o">(</span><span class="n">MyDebugCallback</span><span class="o">.</span><span class="na">class</span><span class="o">))</span> <span class="o">{</span> + <span class="n">callback</span> <span class="o">=</span> <span class="o">(</span><span class="n">T</span><span class="o">)</span> <span class="k">new</span> <span class="n">MyDebugCallback</span><span class="o">();</span> + <span class="o">}</span> <span class="k">else</span> <span class="o">{</span> + <span class="n">callback</span> <span class="o">=</span> <span class="o">(</span><span class="n">T</span><span class="o">)</span> <span class="kd">super</span><span class="o">.</span><span class="na">getCallback</span><span class="o">(</span><span class="n">callbackInterface</span><span class="o">);</span> + <span class="o">}</span> + + <span class="k">return</span> <span class="n">callback</span><span class="o">;</span> +<span class="o">}</span> +</pre></div> + + +<p>If this is in place then the url query option odata-debug=json will return detailed error information in json format for each request.</p> +<h5 id="query-for-debug-information">Query for Debug Information</h5> +<p><strong> JSON Debug View</strong></p> +<p>Request url: http://localhost:8080/olingo-odata2-ref-web/ReferenceScenario.svc/?odata-debug=json</p> +<p>Response:</p> +<div class="codehilite"><pre><span class="p">{</span> + <span class="nt">"body"</span><span class="p">:</span> <span class="s2">"<?xml version='1.0' encoding='utf-8'?><service xml:base=\"http://localhost:8080/olingo-odata2-ref-web/ReferenceScenario.svc/\" xmlns=\"http://www.w3.org/2007/app\" xmlns:atom=\"http://www.w3.org/2005/Atom\"><workspace><atom:title>Default</atom:title><collection href=\"Employees\"><atom:title>Employees</atom:title></collection><collection href=\"Teams\"><atom:title>Teams</atom:title></collection><collection href=\"Rooms\"><atom:title>Rooms</atom:title></collection><collection href=\"Managers\"><atom:title>Managers</atom:title></collection><collection href=\"Buildings\"><atom:title>Buildings</atom:title></collection><collection href=\"Container2.P hotos\"><atom:title>Photos</atom:title></collection></workspace></service>"</span><span class="p">,</span> + <span class="nt">"request"</span><span class="p">:</span> <span class="p">{</span> + <span class="nt">"method"</span><span class="p">:</span> <span class="s2">"GET"</span><span class="p">,</span> + <span class="nt">"uri"</span><span class="p">:</span> <span class="s2">"https://localhost:8080/olingo-odata2-ref-web/ReferenceScenario.svc/?odata-debug=json"</span><span class="p">,</span> + <span class="nt">"headers"</span><span class="p">:</span> <span class="p">{</span> + <span class="nt">"Accept"</span><span class="p">:</span> <span class="s2">"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"</span><span class="p">,</span> + <span class="nt">"accept-encoding"</span><span class="p">:</span> <span class="s2">"gzip, deflate"</span><span class="p">,</span> + <span class="nt">"accept-language"</span><span class="p">:</span> <span class="s2">"de-de,de;q=0.8,en-us;q=0.5,en;q=0.3"</span><span class="p">,</span> + <span class="nt">"connection"</span><span class="p">:</span> <span class="s2">"keep-alive"</span><span class="p">,</span> + <span class="nt">"Content-Type"</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span> + <span class="nt">"cookie"</span><span class="p">:</span> <span class="s2">"JSESSIONID=C6A2403F354B61B1E645744FABCB7FB6C6BC5DA41BC841823647CF2DFF001556; BIGipServerlocalhost=3543090186.26911.0000"</span><span class="p">,</span> + <span class="nt">"host"</span><span class="p">:</span> <span class="s2">"localhost:8080"</span><span class="p">,</span> + <span class="nt">"user-agent"</span><span class="p">:</span> <span class="s2">"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:24.0) Gecko/20100101 Firefox/24.0"</span><span class="p">,</span> + <span class="nt">"x-forwarded-for"</span><span class="p">:</span> <span class="s2">"173.12.210.11"</span> + <span class="p">}</span> + <span class="p">},</span> + <span class="nt">"response"</span><span class="p">:</span> <span class="p">{</span> + <span class="nt">"status"</span><span class="p">:</span> <span class="p">{</span> + <span class="nt">"code"</span><span class="p">:</span> <span class="mi">200</span><span class="p">,</span> + <span class="nt">"info"</span><span class="p">:</span> <span class="s2">"OK"</span> + <span class="p">},</span> + <span class="nt">"headers"</span><span class="p">:</span> <span class="p">{</span> + <span class="nt">"DataServiceVersion"</span><span class="p">:</span> <span class="s2">"1.0"</span><span class="p">,</span> + <span class="nt">"Content-Type"</span><span class="p">:</span> <span class="s2">"application/xml;charset=utf-8"</span> + <span class="p">}</span> + <span class="p">},</span> + <span class="nt">"runtime"</span><span class="p">:</span> <span class="p">[{</span> + <span class="nt">"class"</span><span class="p">:</span> <span class="s2">"ODataRequestHandler"</span><span class="p">,</span> + <span class="nt">"method"</span><span class="p">:</span> <span class="s2">"handle"</span><span class="p">,</span> + <span class="nt">"duration"</span><span class="p">:</span> <span class="mi">1911</span><span class="p">,</span> + <span class="nt">"memory"</span><span class="p">:</span> <span class="mi">191</span><span class="p">,</span> + <span class="nt">"children"</span><span class="p">:</span> <span class="p">[</span> + <span class="p">{</span> + <span class="nt">"class"</span><span class="p">:</span> <span class="s2">"UriParserImpl"</span><span class="p">,</span> + <span class="nt">"method"</span><span class="p">:</span> <span class="s2">"parse"</span><span class="p">,</span> + <span class="nt">"duration"</span><span class="p">:</span> <span class="mi">66</span><span class="p">,</span> + <span class="nt">"memory"</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> + <span class="nt">"children"</span><span class="p">:</span> <span class="p">{}</span> + <span class="p">},</span> + <span class="p">{</span> + <span class="nt">"class"</span><span class="p">:</span> <span class="s2">"Dispatcher"</span><span class="p">,</span> + <span class="nt">"method"</span><span class="p">:</span> <span class="s2">"dispatch"</span><span class="p">,</span> + <span class="nt">"duration"</span><span class="p">:</span> <span class="mi">1029</span><span class="p">,</span> + <span class="nt">"memory"</span><span class="p">:</span> <span class="mi">95</span><span class="p">,</span> + <span class="nt">"children"</span><span class="p">:</span> <span class="p">{}</span> + <span class="p">}</span> + <span class="p">]</span> + <span class="p">}]</span> +<span class="p">}</span> +</pre></div> + + +<p><strong> HTML Debug View</strong></p> +<p>Request url: http://localhost:8080/olingo-odata2-ref-web-incubating/ReferenceScenario.svc/?odata-debug=html +to get a self-contained HTML document with all information that is in the JSON +output but can be viewed conveniently in a browser.</p> +<h5 id="custom-debug-output">Custom Debug Output</h5> +<p>Starting with release 1.2, it is possible to create custom debug output. +The complete formatting of the debug-support information can be implemented +in a callback method.</p> +<p>Add to the already existing <code>getCallback</code> method before the line with <code>else</code> a condition check whether the given <code>ODataCallback</code> is a <code>DebugWrapperCallback</code>.</p> +<div class="codehilite"><pre><span class="o">}</span> <span class="k">else</span> <span class="k">if</span> <span class="o">(</span><span class="n">callbackInterface</span><span class="o">.</span><span class="na">isAssignableFrom</span><span class="o">(</span><span class="n">ODataDebugResponseWrapperCallback</span><span class="o">.</span><span class="na">class</span><span class="o">))</span> <span class="o">{</span> + <span class="n">callback</span> <span class="o">=</span> <span class="o">(</span><span class="n">T</span><span class="o">)</span> <span class="k">new</span> <span class="n">DebugWrapperCallback</span><span class="o">();</span> +<span class="o">}</span> +</pre></div> + + +<p>which then results in following method</p> +<div class="codehilite"><pre><span class="kd">public</span> <span class="o"><</span><span class="n">T</span> <span class="kd">extends</span> <span class="n">ODataCallback</span><span class="o">></span> <span class="n">T</span> <span class="n">getCallback</span><span class="o">(</span><span class="kd">final</span> <span class="n">Class</span><span class="o"><?</span> <span class="kd">extends</span> <span class="n">ODataCallback</span><span class="o">></span> <span class="n">callbackInterface</span><span class="o">)</span> <span class="o">{</span> + <span class="n">T</span> <span class="n">callback</span> + + <span class="nf">if</span> <span class="o">(</span><span class="n">callbackInterface</span><span class="o">.</span><span class="na">isAssignableFrom</span><span class="o">(</span><span class="n">MyDebugCallback</span><span class="o">.</span><span class="na">class</span><span class="o">))</span> <span class="o">{</span> + <span class="n">callback</span> <span class="o">=</span> <span class="o">(</span><span class="n">T</span><span class="o">)</span> <span class="k">new</span> <span class="n">MyDebugCallback</span><span class="o">();</span> + <span class="o">}</span> <span class="k">else</span> <span class="k">if</span> <span class="o">(</span><span class="n">callbackInterface</span><span class="o">.</span><span class="na">isAssignableFrom</span><span class="o">(</span><span class="n">ODataDebugResponseWrapperCallback</span><span class="o">.</span><span class="na">class</span><span class="o">))</span> <span class="o">{</span> + <span class="n">callback</span> <span class="o">=</span> <span class="o">(</span><span class="n">T</span><span class="o">)</span> <span class="k">new</span> <span class="n">DebugWrapperCallback</span><span class="o">();</span> + <span class="o">}</span> <span class="k">else</span> <span class="o">{</span> + <span class="n">callback</span> <span class="o">=</span> <span class="o">(</span><span class="n">T</span><span class="o">)</span> <span class="kd">super</span><span class="o">.</span><span class="na">getCallback</span><span class="o">(</span><span class="n">callbackInterface</span><span class="o">);</span> + <span class="o">}</span> + + <span class="k">return</span> <span class="n">callback</span><span class="o">;</span> +<span class="o">}</span> +</pre></div> + + +<p>and implement the callback class</p> +<div class="codehilite"><pre><span class="kd">private</span> <span class="kd">final</span> <span class="kd">class</span> <span class="nc">DebugWrapperCallback</span> <span class="kd">implements</span> <span class="n">ODataDebugResponseWrapperCallback</span> <span class="o">{</span> + <span class="nd">@Override</span> + <span class="kd">public</span> <span class="n">ODataResponse</span> <span class="nf">handle</span><span class="o">(</span><span class="kd">final</span> <span class="n">ODataContext</span> <span class="n">context</span><span class="o">,</span> <span class="kd">final</span> <span class="n">ODataRequest</span> <span class="n">request</span><span class="o">,</span> <span class="kd">final</span> <span class="n">ODataResponse</span> <span class="n">response</span><span class="o">,</span> + <span class="kd">final</span> <span class="n">UriInfo</span> <span class="n">uriInfo</span><span class="o">,</span> <span class="kd">final</span> <span class="n">Exception</span> <span class="n">exception</span><span class="o">)</span> <span class="o">{</span> + <span class="k">if</span> <span class="o">(</span><span class="s">"true"</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">request</span><span class="o">.</span><span class="na">getQueryParameters</span><span class="o">().</span><span class="na">get</span><span class="o">(</span><span class="s">"my-debug"</span><span class="o">)))</span> <span class="o">{</span> + <span class="k">return</span> <span class="n">DebugResponseWrapper</span><span class="o">.</span><span class="na">handle</span><span class="o">(</span><span class="n">context</span><span class="o">,</span> <span class="n">request</span><span class="o">,</span> <span class="n">response</span><span class="o">,</span> <span class="n">uriInfo</span><span class="o">,</span> <span class="n">exception</span><span class="o">);</span> + <span class="o">}</span> <span class="k">else</span> <span class="o">{</span> + <span class="k">return</span> <span class="n">response</span><span class="o">;</span> + <span class="o">}</span> + <span class="o">}</span> +<span class="o">}</span> +</pre></div> + + +<p>where <code>DebugResponseWrapper</code> is a class you have to implement which does +the real work.</p> +<p><strong>Please note</strong> that this callback is not called if the built-in debug output +is requested as described above.</p> +<h3 id="log-and-trace-support">Log and Trace Support</h3> +<p>Apache Olingo has no dependencies to any specific log and trace api (e.g. slf4j, log4j â¦) and with that it does not trace anything by default. This is to keep the library independent from a specific api so that it can be used on any JEE compliant platform independent from which l&t api is offered there.</p> +<p>Anyhow log and trace is required for productive use and the following recommendations are given:</p> +<h5 id="servlet-filter">Servlet Filter</h5> +<p>For tracing the http traffic (request url, query parameter, http headers, response code â¦) to and from the server it is recommended to implement a servlet filter on top of the service. This is completely independent from the Apache Olingo OData library and has no restrictions.</p> +<h5 id="service-processor-implementation">Service Processor Implementation</h5> +<p>To trace OData activities (read/write activities) at the server it is recommended to do that within a custom processor implementation. </p> +<h5 id="error-callback">Error Callback</h5> +<p>Because of OData requires to handle error situations someone can hook into the handling and trace information there. </p> +<p>Simply implement another <code>ODataCallback</code> interface and register it within a <code>ODataServiceFactory</code>.</p> +<p>Callback:</p> +<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">MyErrorCallback</span> <span class="n">implements</span> <span class="n">ODataErrorCallback</span> <span class="p">{</span> + <span class="p">@</span><span class="n">Override</span> + <span class="n">public</span> <span class="n">ODataResponse</span> <span class="n">handleError</span><span class="p">(</span><span class="n">ODataErrorContext</span> <span class="n">context</span><span class="p">)</span> <span class="n">throws</span> <span class="n">ODataApplicationException</span> <span class="p">{</span> + <span class="n">LOGGER</span><span class="p">.</span><span class="n">severe</span><span class="p">(</span><span class="n">context</span><span class="p">.</span><span class="n">getException</span><span class="p">().</span><span class="n">getClass</span><span class="p">().</span><span class="n">getName</span><span class="p">()</span> <span class="o">+</span> "<span class="p">:</span>" <span class="o">+</span> <span class="n">context</span><span class="p">.</span><span class="n">getMessage</span><span class="p">());</span> + <span class="k">return</span> <span class="n">EntityProvider</span><span class="p">.</span><span class="n">writeErrorDocument</span><span class="p">(</span><span class="n">context</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> + + +<p>Register Callback:</p> +<div class="codehilite"><pre><span class="kr">public</span> <span class="o"><</span><span class="nx">T</span> <span class="kr">extends</span> <span class="nx">ODataCallback</span><span class="o">></span> <span class="nx">T</span> <span class="nx">getCallback</span><span class="p">(</span><span class="kr">final</span> <span class="nx">Class</span><span class="cp"><?</span> <span class="k">extends</span> <span class="nx">ODataCallback</span><span class="o">></span> <span class="nx">callbackInterface</span><span class="p">)</span> <span class="p">{</span> + <span class="nx">T</span> <span class="nx">callback</span> + + <span class="k">if</span> <span class="p">(</span><span class="nx">callbackInterface</span><span class="o">.</span><span class="nx">isAssignableFrom</span><span class="p">(</span><span class="nx">MyDebugCallback</span><span class="o">.</span><span class="nx">class</span><span class="p">))</span> <span class="p">{</span> + <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="k">new</span> <span class="nx">MyDebugCallback</span><span class="p">();</span> + <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="nx">callbackInterface</span><span class="o">.</span><span class="nx">isAssignableFrom</span><span class="p">(</span><span class="nx">MyErrorCallback</span><span class="o">.</span><span class="nx">class</span><span class="p">))</span> <span class="p">{</span> + <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="k">new</span> <span class="nx">MyErrorCallback</span><span class="p">();</span> + <span class="p">}</span> <span class="k">else</span> <span class="p">{</span> + <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="nx">super</span><span class="o">.</span><span class="nx">getCallback</span><span class="p">(</span><span class="nx">callbackInterface</span><span class="p">);</span> + <span class="p">}</span> + + <span class="k">return</span> <span class="nx">callback</span><span class="p">;</span> +<span class="p">}</span> +</pre></div><div align="center"> +<p>Copyright © 2013-2014, The Apache Software Foundation<br> + Apache Olingo, Olingo, Apache, the Apache feather, and + the Apache Olingo project logo are trademarks of the Apache Software + Foundation.</p> + <small><a href="/doc/odata2/privacy.html">Privacy</a></small> + </div> + </div><!-- /container --> + <!-- Bootstrap core JavaScript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="/js/jquery.js" type="text/javascript"> +</script> + <script src="/js/bootstrap.js" type="text/javascript"> + <script src="/js/offcanvas.js" type="text/javascript"> +</script> + <!-- Google Analytics: change UA-XXXXX-X to be your site's ID. --> + <script> + (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]= + function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date; + e=o.createElement(i);r=o.getElementsByTagName(i)[0]; + e.src='//www.google-analytics.com/analytics.js'; + r.parentNode.insertBefore(e,r)}(window,document,'script','ga')); + ga('create','UA-44963757-1');ga('send','pageview'); + </script> + </body> +</html> Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/delta.html ============================================================================== --- websites/staging/olingo/trunk/content/doc/odata4/tutorials/delta.html (added) +++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/delta.html Tue Sep 16 12:34:18 2014 @@ -0,0 +1,231 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html lang="en"> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="description" content="Apache Olingo provides libraries which enable developers to implement OData producers and OData consumers. The available OData Java library implements OData version 2.0. In future on goal is to provide an OData 4.0 compliant library once the OData standard is published at OASIS. The focus within the community is currently on the Java technology but it is up to the community to discuss if other environments find interest."> + <meta name="author" content=""> + <link rel="icon" href="/favicon.ico"> + <title> + Apache Olingo + </title><!-- Bootstrap core CSS --> + <link href="/css/bootstrap.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link href="/css/navbar.css" rel="stylesheet" type="text/css"><!-- Just for debugging purposes. Don't actually copy these 2 lines! --> + <link href="/css/offcanvas.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link rel="stylesheet" href="/css/main.css"> + <!--[if lt IE 9]><script src="/js/ie8-responsive-file-warning.js"></script><![endif]--> + + <script src="/js/ie-emulation-modes-warning.js" type="text/javascript"> +</script><!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> + + <script src="/js/ie10-viewport-bug-workaround.js" type="text/javascript"> +</script><!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> + </head> + + <body> + <div class="container"> + <!-- Static navbar --> + <div class="navbar navbar-default" role="navigation"> + <div class="container-fluid"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <img class="navbar-brand" src="/img/OlingoOrangeTM.png" style="width:62px;" > + <a class="navbar-brand" href="#">Apache Olingoâ¢</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + + <li><a href="/">Home</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="http://www.apache.org/foundation/";>ASF Home</a></li> + <li><a href="http://projects.apache.org/";>Projects</a></li> + <li><a href="http://people.apache.org/";>People</a></li> + <li><a href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a></li> + <li><a href="http://www.apache.org/dyn/closer.cgi";>Download</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Support Apache</a></li> + </ul> + </li> + + <li><a href="http://www.apache.org/licenses/";>License</a></li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/download.html">Download OData 2.0 Java</a></li> + <li><a href="/doc/javascript/download.html">Download OData 4.0 JavaScript</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/index.html">Documentation OData 2.0 Java</a></li> + <li><a href="/doc/javascript/index.html">Documentation OData 4.0 JavaScript</a></li> + </ul> + </li> + <li><a href="/support.html">Support</a></li> + + </ul> + + <img class="navbar-right" height="50px" src="/img/asf-logo.gif"> + + </div><!--/.nav-collapse --> + </div><!--/.container-fluid --> + </div><!-- Main component for a primary marketing message or call to action --><h1 id="delta-responses">Delta Responses</h1> +<p>Delta responses is a feature on top of OData 2.0 for requesting changes. The feature is defined in OData 4.0 and this is a preliminary and lightweight implementation close to the OData 4.0 specification <a href="http://docs.oasis-open.org/odata/odata/v4.0/cos01/part1-protocol/odata-v4.0-cos01-part1-protocol.html#_Toc372793707";>(see here)</a>.</p> +<p>Because of delta responses are not defined in OData 2.0 this feature is optional.</p> +<p>Features:</p> +<ul> +<li>Delta Links (for Atom and Json)</li> +<li>Tombstones <a href="http://tools.ietf.org/html/rfc6721";>RFC6721</a> for deleted entries in Atom format</li> +<li>Deleted Entries in Json as a lightweight implementation of <a href="http://docs.oasis-open.org/odata/odata-json-format/v4.0/cos01/odata-json-format-v4.0-cos01.html#_Toc372793080";>Delta Responses</a> </li> +</ul> +<h3 id="use-case">Use Case</h3> +<p>A client requests a (paged) feed. A server can add a delta link on the last feed page. Using the delta link returns only changed data of the feed to the client. Changed data are feed entries with changed properties or deleted entries.</p> +<h3 id="implementation">Implementation</h3> +<p>A server has to implement the <code>TombstoneCallback</code> interface:</p> +<div class="codehilite"><pre><span class="n">public</span> <span class="n">interface</span> <span class="n">TombstoneCallback</span> <span class="n">extends</span> <span class="n">ODataCallback</span> <span class="p">{</span> +<span class="p">...</span> +<span class="p">}</span> +</pre></div> + + +<p>Basically the implementation of this interface has to carry information about deleted data and the delta link which is realized as custom query option:</p> +<div class="codehilite"><pre><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span>?!<span class="n">deltatoken</span><span class="p">=</span>1234 +</pre></div> + + +<p>Finally the following code has to go into a <code>ODataSingleProcessor</code> implementation:</p> +<div class="codehilite"><pre><span class="cm">/**</span> +<span class="cm"> * @see EntitySetProcessor</span> +<span class="cm"> */</span> +<span class="p">@</span><span class="n">Override</span> +<span class="n">public</span> <span class="n">ODataResponse</span> <span class="n">readEntitySet</span><span class="p">(</span><span class="k">final</span> <span class="n">GetEntitySetUriInfo</span> <span class="n">uriInfo</span><span class="p">,</span> <span class="k">final</span> <span class="n">String</span> <span class="n">contentType</span><span class="p">)</span> <span class="n">throws</span> <span class="n">ODataException</span> <span class="p">{</span> + + <span class="p">[...]</span> + + <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">ODataCallback</span><span class="o">></span> <span class="n">callbacks</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">ODataCallback</span><span class="o">></span><span class="p">();</span> + <span class="n">callbacks</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="n">TombstoneCallback</span><span class="p">.</span><span class="no">CALLBACK_KEY_TOMBSTONE</span><span class="p">,</span> <span class="n">tombstoneCallback</span><span class="p">);</span> + + <span class="n">EntityProviderWriteProperties</span> <span class="n">properties</span> <span class="o">=</span> <span class="n">EntityProviderWriteProperties</span><span class="p">.</span><span class="n">serviceRoot</span><span class="p">(</span><span class="k">new</span> <span class="no">URI</span><span class="p">(</span><span class="no">BASE_URI</span><span class="p">)).</span><span class="n">callbacks</span><span class="p">(</span><span class="n">callbacks</span><span class="p">).</span><span class="n">build</span><span class="p">();</span> + + <span class="k">final</span> <span class="n">ODataResponse</span> <span class="n">response</span> <span class="o">=</span> <span class="k">new</span> <span class="n">JsonEntityProvider</span><span class="p">().</span><span class="n">writeFeed</span><span class="p">(</span><span class="n">entitySet</span><span class="p">,</span> <span class="n">roomsData</span><span class="p">,</span> <span class="n">properties</span><span class="p">);</span> + + <span class="p">[...]</span> + + <span class="k">return</span> <span class="n">response</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> + + +<h5 id="json-response">Json Response</h5> +<p>This is an example for a Json response:</p> +<div class="codehilite"><pre> <span class="p">[...]</span> + <span class="p">{</span> + "<span class="n">__metadata</span>"<span class="p">:{</span> + "<span class="n">id</span>"<span class="p">:</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span><span class="p">(</span><span class="s">'2'</span><span class="p">)</span>"<span class="p">,</span> + "<span class="n">uri</span>"<span class="p">:</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span><span class="p">(</span><span class="s">'2'</span><span class="p">)</span>"<span class="p">,</span> + "<span class="n">type</span>"<span class="p">:</span>"<span class="n">RefScenario</span><span class="p">.</span><span class="n">Room</span>"<span class="p">,</span> + "<span class="n">etag</span>"<span class="p">:</span>"<span class="n">W</span><span class="o">/\</span>"2<span class="o">\</span>"" + <span class="p">},</span> + "<span class="n">Id</span>"<span class="p">:</span>"2"<span class="p">,</span> + "<span class="n">Name</span>"<span class="p">:</span><span class="n">null</span><span class="p">,</span> + "<span class="n">Seats</span>"<span class="p">:</span>66<span class="p">,</span> + "<span class="n">Version</span>"<span class="p">:</span>2<span class="p">,</span> + "<span class="n">nr_Employees</span>"<span class="p">:{</span> + "<span class="n">__deferred</span>"<span class="p">:{</span> + "<span class="n">uri</span>"<span class="p">:</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span><span class="p">(</span><span class="s">'2'</span><span class="p">)</span><span class="o">/</span><span class="n">nr_Employees</span>" + <span class="p">}</span> + <span class="p">},</span> + "<span class="n">nr_Building</span>"<span class="p">:{</span> + "<span class="n">__deferred</span>"<span class="p">:{</span> + "<span class="n">uri</span>"<span class="p">:</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span><span class="p">(</span><span class="s">'2'</span><span class="p">)</span><span class="o">/</span><span class="n">nr_Building</span>" + <span class="p">}</span> + <span class="p">}</span> + <span class="p">},</span> + <span class="p">{</span> + "<span class="p">@</span><span class="n">odata</span><span class="p">.</span><span class="n">context</span>"<span class="p">:</span>"$<span class="n">metadata</span>#<span class="n">Rooms</span><span class="o">/</span>$<span class="n">deletedEntity</span>"<span class="p">,</span> + "<span class="n">id</span>"<span class="p">:</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span><span class="p">(</span><span class="s">'3'</span><span class="p">)</span>" + <span class="p">},</span> + <span class="p">{</span> + "<span class="p">@</span><span class="n">odata</span><span class="p">.</span><span class="n">context</span>"<span class="p">:</span>"$<span class="n">metadata</span>#<span class="n">Rooms</span><span class="o">/</span>$<span class="n">deletedEntity</span>"<span class="p">,</span> + "<span class="n">id</span>"<span class="p">:</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span><span class="p">(</span><span class="s">'4'</span><span class="p">)</span>" + <span class="p">},</span> + <span class="p">{</span> + "<span class="p">@</span><span class="n">odata</span><span class="p">.</span><span class="n">context</span>"<span class="p">:</span>"$<span class="n">metadata</span>#<span class="n">Rooms</span><span class="o">/</span>$<span class="n">deletedEntity</span>"<span class="p">,</span> + "<span class="n">id</span>"<span class="p">:</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span><span class="p">(</span><span class="s">'5'</span><span class="p">)</span>" + <span class="p">},</span> + + <span class="p">],</span> + "<span class="n">__delta</span>"<span class="p">:</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="p">:</span>80<span class="o">/</span><span class="n">service</span><span class="o">/</span><span class="n">Rooms</span>?!<span class="n">deltatoken</span><span class="p">=</span>1234" + <span class="p">}</span> +<span class="p">}</span> +</pre></div> + + +<h5 id="atom-response">Atom Response</h5> +<p>This is an example of an Atom delta response (tombstones, RFC6721)</p> +<div class="codehilite"><pre><span class="nt"><feed</span> <span class="err">...</span><span class="nt">></span> + +[..] + +<span class="nt"><entry</span> <span class="na">m:etag=</span><span class="s">"W/&quot;3&quot;"</span><span class="nt">></span> + <span class="nt"><id></span>http://host:80/service/Rooms('2')<span class="nt"></id></span> + <span class="nt"><title</span> <span class="na">type=</span><span class="s">"text"</span><span class="nt">></span>Rooms<span class="nt"></title></span> + <span class="nt"><updated></span>2014-01-14T18:11:06.681+01:00<span class="nt"></updated></span> + <span class="nt"><category</span> <span class="na">term=</span><span class="s">"RefScenario.Room"</span> <span class="na">scheme=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"</span><span class="nt">/></span> + <span class="nt"><link</span> <span class="na">href=</span><span class="s">"Rooms('2')"</span> <span class="na">rel=</span><span class="s">"edit"</span> <span class="na">title=</span><span class="s">"Room"</span><span class="nt">/></span> + <span class="nt"><link</span> <span class="na">href=</span><span class="s">"Rooms('2')/nr_Employees"</span> <span class="na">rel=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/related/nr_Employees"</span> <span class="na">title=</span><span class="s">"nr_Employees"</span> <span class="na">type=</span><span class="s">"application/atom+xml;type=feed"</span><span class="nt">/></span> + <span class="nt"><link</span> <span class="na">href=</span><span class="s">"Rooms('2')/nr_Building"</span> <span class="na">rel=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/related/nr_Building"</span> <span class="na">title=</span><span class="s">"nr_Building"</span> <span class="na">type=</span><span class="s">"application/atom+xml;type=entry"</span><span class="nt">/></span> + <span class="nt"><content</span> <span class="na">type=</span><span class="s">"application/xml"</span><span class="nt">></span> + <span class="nt"><m:properties></span> + <span class="nt"><d:Id></span>2<span class="nt"></d:Id></span> + <span class="nt"><d:Name></span>Neu Schwanstein2<span class="nt"></d:Name></span> + <span class="nt"><d:Seats></span>20<span class="nt"></d:Seats></span> + <span class="nt"><d:Version></span>3<span class="nt"></d:Version></span> + <span class="nt"></m:properties></span> + <span class="nt"></content></span> +<span class="nt"></entry></span> +<span class="nt"><at:deleted-entry</span> <span class="na">ref=</span><span class="s">"http://host:80/service/Rooms('2')"</span> <span class="na">when=</span><span class="s">"2014-01-14T18:11:06.682+01:00"</span><span class="nt">/></span> +<span class="nt"><link</span> <span class="na">rel=</span><span class="s">"delta"</span> <span class="na">href=</span><span class="s">"http://host:80/service/Rooms?!deltatoken=1234"</span><span class="nt">/></span> +<span class="nt"></feed></span> +</pre></div><div align="center"> +<p>Copyright © 2013-2014, The Apache Software Foundation<br> + Apache Olingo, Olingo, Apache, the Apache feather, and + the Apache Olingo project logo are trademarks of the Apache Software + Foundation.</p> + <small><a href="/doc/odata2/privacy.html">Privacy</a></small> + </div> + </div><!-- /container --> + <!-- Bootstrap core JavaScript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="/js/jquery.js" type="text/javascript"> +</script> + <script src="/js/bootstrap.js" type="text/javascript"> + <script src="/js/offcanvas.js" type="text/javascript"> +</script> + <!-- Google Analytics: change UA-XXXXX-X to be your site's ID. --> + <script> + (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]= + function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date; + e=o.createElement(i);r=o.getElementsByTagName(i)[0]; + e.src='//www.google-analytics.com/analytics.js'; + r.parentNode.insertBefore(e,r)}(window,document,'script','ga')); + ga('create','UA-44963757-1');ga('send','pageview'); + </script> + </body> +</html> Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/deltaClient.html ============================================================================== --- websites/staging/olingo/trunk/content/doc/odata4/tutorials/deltaClient.html (added) +++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/deltaClient.html Tue Sep 16 12:34:18 2014 @@ -0,0 +1,161 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html lang="en"> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="description" content="Apache Olingo provides libraries which enable developers to implement OData producers and OData consumers. The available OData Java library implements OData version 2.0. In future on goal is to provide an OData 4.0 compliant library once the OData standard is published at OASIS. The focus within the community is currently on the Java technology but it is up to the community to discuss if other environments find interest."> + <meta name="author" content=""> + <link rel="icon" href="/favicon.ico"> + <title> + Apache Olingo + </title><!-- Bootstrap core CSS --> + <link href="/css/bootstrap.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link href="/css/navbar.css" rel="stylesheet" type="text/css"><!-- Just for debugging purposes. Don't actually copy these 2 lines! --> + <link href="/css/offcanvas.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link rel="stylesheet" href="/css/main.css"> + <!--[if lt IE 9]><script src="/js/ie8-responsive-file-warning.js"></script><![endif]--> + + <script src="/js/ie-emulation-modes-warning.js" type="text/javascript"> +</script><!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> + + <script src="/js/ie10-viewport-bug-workaround.js" type="text/javascript"> +</script><!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> + </head> + + <body> + <div class="container"> + <!-- Static navbar --> + <div class="navbar navbar-default" role="navigation"> + <div class="container-fluid"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <img class="navbar-brand" src="/img/OlingoOrangeTM.png" style="width:62px;" > + <a class="navbar-brand" href="#">Apache Olingoâ¢</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + + <li><a href="/">Home</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="http://www.apache.org/foundation/";>ASF Home</a></li> + <li><a href="http://projects.apache.org/";>Projects</a></li> + <li><a href="http://people.apache.org/";>People</a></li> + <li><a href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a></li> + <li><a href="http://www.apache.org/dyn/closer.cgi";>Download</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Support Apache</a></li> + </ul> + </li> + + <li><a href="http://www.apache.org/licenses/";>License</a></li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/download.html">Download OData 2.0 Java</a></li> + <li><a href="/doc/javascript/download.html">Download OData 4.0 JavaScript</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/index.html">Documentation OData 2.0 Java</a></li> + <li><a href="/doc/javascript/index.html">Documentation OData 4.0 JavaScript</a></li> + </ul> + </li> + <li><a href="/support.html">Support</a></li> + + </ul> + + <img class="navbar-right" height="50px" src="/img/asf-logo.gif"> + + </div><!--/.nav-collapse --> + </div><!--/.container-fluid --> + </div><!-- Main component for a primary marketing message or call to action --><h1 id="consuming-delta-responses">Consuming Delta Responses</h1> +<p>Delta responses is a feature on top of OData 2.0 for requesting changes. The feature is defined in OData 4.0 and this is a preliminary and lightweight implementation close to the OData 4.0 specification <a href="http://docs.oasis-open.org/odata/odata/v4.0/cos01/part1-protocol/odata-v4.0-cos01-part1-protocol.html#_Toc372793707";>(see here)</a>.</p> +<p>How delta responses can be produced by an OData service is documented here: <a href="/doc/odata2/tutorials/delta.html">server side delta responses</a>.</p> +<h3 id="use-case">Use Case</h3> +<p>A client reads a feed and later wants to get only the update of changed and deleted entries. </p> +<h3 id="principle">Principle</h3> +<p>A client has to read a complete (paged) feed. With the last feed page the service has to provide a delta link instead of a next link. A delta link us usually the same feed url containing a delta token as proprietary query parameter. With the delta link the client can query the service again and gets back a delta feed containing entries which were changed or deleted since the complete feed was received.</p> +<p><img alt="Class Diagram Delta Feeds" src="/img/DeltaFeedClassDiagram.png" /></p> +<h3 id="examples">Examples</h3> +<p>Example for a delta link: <code>http://<host>:<port>/odata/Rooms?!deltatoken=123</code></p> +<h5 id="delta-feed-handling">Delta Feed Handling</h5> +<p>Depends on the general client sample <a href="...">here</a></p> +<div class="codehilite"><pre><span class="c1">// retrieve a feed</span> +<span class="n">ODataFeed</span> <span class="n">feed</span> <span class="o">=</span> <span class="n">client</span><span class="p">.</span><span class="n">readFeed</span><span class="p">(</span><span class="s">"Container1"</span><span class="p">,</span> <span class="s">"Rooms"</span><span class="p">,</span> <span class="n">contentType</span><span class="p">);</span> +<span class="n">String</span> <span class="n">deltaLink</span> <span class="o">=</span> <span class="n">feed</span><span class="p">.</span><span class="n">getFeedMetadata</span><span class="p">().</span><span class="n">getDeltaLink</span><span class="p">();</span> + +<span class="c1">// store feed data</span> +<span class="n">List</span><span class="o"><</span><span class="n">ODataEntry</span><span class="o">></span> <span class="n">entries</span> <span class="o">=</span> <span class="n">feed</span><span class="p">.</span><span class="n">getEntries</span><span class="p">();</span> + +<span class="c1">// get delta link from feed</span> +<span class="n">String</span> <span class="n">deltaLink</span> <span class="o">=</span> <span class="n">feed</span><span class="p">.</span><span class="n">getFeedMetadata</span><span class="p">().</span><span class="n">getDeltaLink</span><span class="p">();</span> + +<span class="c1">// query delta feed using delta link</span> +<span class="n">ODataDeltaFeed</span> <span class="n">deltaFeed</span> <span class="o">=</span> <span class="n">client</span><span class="p">.</span><span class="n">readDeltaFeed</span><span class="p">(</span><span class="s">"Container1"</span><span class="p">,</span> <span class="s">"Rooms"</span><span class="p">,</span> <span class="n">contentType</span><span class="p">,</span> <span class="n">deltaLink</span><span class="p">);</span> + +<span class="n">List</span><span class="o"><</span><span class="n">ODataEntry</span><span class="o">></span> <span class="n">changedEntries</span> <span class="o">=</span> <span class="n">deltaFeed</span><span class="p">.</span><span class="n">getEntries</span><span class="p">();</span> +<span class="n">List</span><span class="o"><</span><span class="n">DeletedEntryMetada</span><span class="p">)</span> <span class="n">deletedEntries</span> <span class="o">=</span> <span class="n">deltaFeed</span><span class="p">.</span><span class="n">getDeletedEntries</span><span class="p">();</span> + +<span class="c1">// proceed with data handling of entries, changedEntries and deletedEntries</span> +</pre></div> + + +<h5 id="response-deserialization">Response Deserialization</h5> +<p>Precondition: Query the delta link using any HTTP client.</p> +<div class="codehilite"><pre><span class="n">InputStream</span> <span class="n">content</span> <span class="p">=</span> <span class="p">...;</span> <span class="o">//</span> <span class="n">retrieve</span> <span class="n">content</span> + +<span class="n">EdmEntityContainer</span> <span class="n">entityContainer</span> <span class="p">=</span> <span class="n">edm</span><span class="p">.</span><span class="n">getEntityContainer</span><span class="p">(</span>"<span class="n">Container1</span>"<span class="p">);</span> + +<span class="n">ODataFeed</span> <span class="n">deltaFeed</span> <span class="p">=</span> <span class="n">EntityProvider</span><span class="p">.</span><span class="n">readDeltaFeed</span><span class="p">(</span><span class="n">contentType</span><span class="p">,</span> <span class="n">entityContainer</span><span class="p">.</span><span class="n">getEntitySet</span><span class="p">(</span>"<span class="n">Rooms</span>"<span class="p">),</span> + <span class="n">content</span><span class="p">,</span> <span class="n">EntityProviderReadProperties</span><span class="p">.</span><span class="n">init</span><span class="p">().</span><span class="n">build</span><span class="p">());</span> +</pre></div> + + +<h3 id="links">Links</h3> +<ul> +<li>Delta Links (for Atom and Json)</li> +<li>Tombstones <a href="http://tools.ietf.org/html/rfc6721";>RFC6721</a> for deleted entries in Atom format</li> +<li>Deleted Entries in Json as a lightweight implementation of <a href="http://docs.oasis-open.org/odata/odata-json-format/v4.0/cos01/odata-json-format-v4.0-cos01.html#_Toc372793080";>Delta Responses</a> </li> +</ul><div align="center"> +<p>Copyright © 2013-2014, The Apache Software Foundation<br> + Apache Olingo, Olingo, Apache, the Apache feather, and + the Apache Olingo project logo are trademarks of the Apache Software + Foundation.</p> + <small><a href="/doc/odata2/privacy.html">Privacy</a></small> + </div> + </div><!-- /container --> + <!-- Bootstrap core JavaScript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="/js/jquery.js" type="text/javascript"> +</script> + <script src="/js/bootstrap.js" type="text/javascript"> + <script src="/js/offcanvas.js" type="text/javascript"> +</script> + <!-- Google Analytics: change UA-XXXXX-X to be your site's ID. --> + <script> + (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]= + function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date; + e=o.createElement(i);r=o.getElementsByTagName(i)[0]; + e.src='//www.google-analytics.com/analytics.js'; + r.parentNode.insertBefore(e,r)}(window,document,'script','ga')); + ga('create','UA-44963757-1');ga('send','pageview'); + </script> + </body> +</html>
