Author: buildbot
Date: Tue Nov 17 10:03:03 2015
New Revision: 972680
Log:
Staging update by buildbot for olingo
Modified:
websites/staging/olingo/trunk/content/ (props changed)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/batch/tutorial_batch.html
Propchange: websites/staging/olingo/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Nov 17 10:03:03 2015
@@ -1 +1 @@
-1713664
+1714747
Modified:
websites/staging/olingo/trunk/content/doc/odata4/tutorials/batch/tutorial_batch.html
==============================================================================
---
websites/staging/olingo/trunk/content/doc/odata4/tutorials/batch/tutorial_batch.html
(original)
+++
websites/staging/olingo/trunk/content/doc/odata4/tutorials/batch/tutorial_batch.html
Tue Nov 17 10:03:03 2015
@@ -115,25 +115,23 @@ This tutorial can be found in subdirecto
</ol>
<h1 id="1-introduction">1. Introduction<a class="headerlink"
href="#1-introduction" title="Permanent link">¶</a></h1>
<p>Batch requests <a
href="http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398359";>(OData
Version 4.0 Part 1: Protocol Plus Errata 02)</a> allow grouping multiple
operations into a single HTTP request payload. A batch request is represented
as a Multipart MIME v1.0 message <a
href="https://www.ietf.org/rfc/rfc2046.txt";>(RFC2046)</a>.
-Each part of a Multipart MINE message can have a differtent content type. For
example you can mix OData requests with Content-Type
<code>application/json</code> and Media Ressource Requests with Content Type
<code>image/png</code>.</p>
+Each part of a Multipart MINE message can have a different content type. For
example you can mix OData requests with Content-Type
<code>application/json</code> and Media Ressource Requests with Content Type
<code>image/png</code>.</p>
<p>The content of batch requests can consist of a series of individual
requests and Change Sets, each represented as a distinct MIME part. In
difference to OData V2 an individual request can be a Data Request, Data
Modification Request, Action invocation request or a Function invocation
request. So all kinds of OData requests are allowed at top level. The order of
individual requests and Change Set sets in significant. Within a Change Set you
can use Data Modification requests and Action invocation requests. Due to the
fact that all requests within a Change Set are unordered, GET requests must not
be used within a Change Set. All operations in a change set represent a single
change unit so a service must successfully process and apply all the requests
in the change set or else apply none of them.</p>
<p><strong>Example</strong></p>
-<p>The request below consists of a individual request (upper red box),
actually a GET request(the upper blue box) to the Entity Set
<code>Products</code> and a Change Set (lower red box). The Change Set contains
a single POST request (lower blue box) to create a new <code>Procuct</code>.
Please note that the <em>boundary delimiter</em> <code>abc123</code> is used in
the request below. The whole content must be wrapped in a single POST request
issued againest the resource <code>/$batch</code>. The Content-Type of the POST
request is consequently <code>Content-Type:
multipart/mixed;boundary=abc123</code></p>
+<p>The request below consists of an individual request (upper red box),
actually a GET request(the upper blue box) to the Entity Set
<code>Products</code> and a Change Set (lower red box). The Change Set contains
a single POST request (lower blue box) to create a new <code>Product</code>.
Please note that the <em>boundary delimiter</em> <code>abc123</code> is used in
the request below. The whole content must be wrapped in a single POST request
issued against the resource <code>/$batch</code>. The Content-Type of the POST
request is consequently <code>Content-Type:
multipart/mixed;boundary=abc123</code></p>
<p><img alt="Test" src="request.png" /></p>
<h1 id="2-preparation">2. Preparation<a class="headerlink"
href="#2-preparation" title="Permanent link">¶</a></h1>
-<p>You should read the previous tutorials first to have an idea how to read
and write entities. In addition the following code is based on the write
tutorial tutorial.</p>
-<p>As a shortcut you should checkout the prepared tutorial project in the <a
href="https://git-wip-us.apache.org/repos/asf/olingo-odata4";>git repository</a>
in folder /samples/tutorials/p3_write.</p>
-<p>Afterwards do a Deploy and run: it should be working. At this state you can
perform CRUD operations and do navigations between products and categories.</p>
-<h1 id="2-implementation">2. Implementation<a class="headerlink"
href="#2-implementation" title="Permanent link">¶</a></h1>
+<p>You should read the previous tutorials first to have an idea how to read
and write entities. In addition the following code is based on the write
tutorial.</p>
+<p>As a shortcut you should chec</p>
<p>The main idea of the following implementation is to reuse the existing
processors.
To do so, we will implement a new processor, which takes a batch request and
dispatches the single requests to the responsible processors.</p>
-<p>The folling steps have to be performed:</p>
+<p>The following steps have to be performed:</p>
<ul>
<li>Modify the data store</li>
<li>Implement the interface <code>BatchProcessor</code></li>
</ul>
-<h2 id="add-transactional-behaviour-to-the-data-store">Add transactional
behaviour to the data store<a class="headerlink"
href="#add-transactional-behaviour-to-the-data-store" title="Permanent
link">¶</a></h2>
-<p>Before we start with the actual processor implementation the data store has
to be modified to provide transactional behavior. In real world service the
underlaying database may supports transactional handling. This tutorial is not
based on a database so we have implement a simple transaction handling by
ourself.</p>
+<h2 id="add-transactional-behavior-to-the-data-store">Add transactional
behavior to the data store<a class="headerlink"
href="#add-transactional-behavior-to-the-data-store" title="Permanent
link">¶</a></h2>
+<p>Before we start with the actual processor implementation the data store has
to be modified to provide transactional behavior. In real world service the
underlying database may supports transactional handling. This tutorial is not
based on a database so we have implement a simple transaction handling by
ourselves.</p>
<p>Add the following methods to the class
<code>myservice.mynamespace.data.Storage</code>. When a new transaction has
been begun the data of the service is copied and stored in an instance
variable. If <code>rollbackTransaction</code> has been called the current data
is replaced with the previous copied one.</p>
<div class="codehilite"><pre><span class="kd">private</span> <span
class="n">List</span><span class="o"><</span><span
class="n">Entity</span><span class="o">></span> <span
class="n">productListBeforeTransaction</span><span class="o">;</span>
@@ -186,7 +184,7 @@ To do so, we will implement a new proces
<h2 id="implement-the-interface-batchprocessor">Implement the interface
<code>BatchProcessor</code><a class="headerlink"
href="#implement-the-interface-batchprocessor" title="Permanent
link">¶</a></h2>
<p>Create a new class
<code>myservice.mynamespace.service.DemoBatchProcessor</code>. The class should
implement the interface
<code>org.apache.olingo.server.api.processor.BatchProcessor</code>.</p>
-<p>Create a constructor and pass the data store to the procesoor.</p>
+<p>Create a constructor and pass the data store to the processor.</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">DemoBatchProcessor</span> <span
class="kd">implements</span> <span class="n">BatchProcessor</span> <span
class="o">{</span>
<span class="kd">private</span> <span class="n">OData</span> <span
class="n">odata</span><span class="o">;</span>
@@ -215,7 +213,7 @@ To do so, we will implement a new proces
</pre></div>
-<p>After that we are able to parse the multipart mixed body. The parser needs
to know what the base uri and the service resolution paths are. The result of
the parser is a list of BatchRequestParts. Each of these parts represents
either a single request or a Change Set (Collection of one or more
requests).</p>
+<p>After that we are able to parse the multipart mixed body. The parser needs
to know what the base URI and the service resolution paths are. The result of
the parser is a list of BatchRequestParts. Each of these parts represents
either a single request or a Change Set (Collection of one or more
requests).</p>
<div class="codehilite"><pre> <span class="c1">// 2. Prepare the batch
options</span>
<span class="kd">final</span> <span class="n">BatchOptions</span> <span
class="n">options</span> <span class="o">=</span> <span
class="n">BatchOptions</span><span class="o">.</span><span
class="na">with</span><span class="o">().</span><span
class="na">rawBaseUri</span><span class="o">(</span><span
class="n">request</span><span class="o">.</span><span
class="na">getRawBaseUri</span><span class="o">())</span>
<span
class="o">.</span><span class="na">rawServiceResolutionUri</span><span
class="o">(</span><span class="n">request</span><span class="o">.</span><span
class="na">getRawServiceResolutionUri</span><span class="o">())</span>
@@ -227,7 +225,7 @@ To do so, we will implement a new proces
</pre></div>
-<p>Now the requests have to be executed by our service. If you like, you can
do it by our own or simply call the method <code>handleBatchRequest</code>.
This method dispatches individual requests directly to the responsible
processor. If a Change Set is passed to <code>handleBatchRequest</code> the
implementation dispaches the request to the method
<code>processChangeSet</code> of our <code>DemoBatchProcessor</code>.</p>
+<p>Now the requests have to be executed by our service. If you like, you can
do it by our own or simply call the method <code>handleBatchRequest</code>.
This method dispatches individual requests directly to the responsible
processor. If a Change Set is passed to <code>handleBatchRequest</code> the
implementation dispatches the request to the method
<code>processChangeSet</code> of our <code>DemoBatchProcessor</code>.</p>
<div class="codehilite"><pre> <span class="c1">// 4. Execute the batch
request parts</span>
<span class="kd">final</span> <span class="n">List</span><span
class="o"><</span><span class="n">ODataResponsePart</span><span
class="o">></span> <span class="n">responseParts</span> <span
class="o">=</span> <span class="k">new</span> <span
class="n">ArrayList</span><span class="o"><</span><span
class="n">ODataResponsePart</span><span class="o">>();</span>
<span class="k">for</span> <span class="o">(</span><span
class="kd">final</span> <span class="n">BatchRequestPart</span> <span
class="n">part</span> <span class="o">:</span> <span
class="n">requestParts</span><span class="o">)</span> <span class="o">{</span>
@@ -236,7 +234,7 @@ To do so, we will implement a new proces
</pre></div>
-<p>The last steps are to serialize the responses and setup the reponse of the
batch request.</p>
+<p>The last steps are to serialize the responses and setup the response of the
batch request.</p>
<div class="codehilite"><pre> <span class="c1">// 5. Serialize the response
content</span>
<span class="kd">final</span> <span class="n">InputStream</span> <span
class="n">responseContent</span> <span class="o">=</span> <span
class="n">odata</span><span class="o">.</span><span
class="na">createFixedFormatSerializer</span><span class="o">().</span><span
class="na">batchResponse</span><span class="o">(</span><span
class="n">responseParts</span><span class="o">,</span> <span
class="n">boundary</span><span class="o">);</span>
@@ -254,7 +252,7 @@ To do so, we will implement a new proces
<h3 id="implement-change-set-handling">Implement Change Set handling<a
class="headerlink" href="#implement-change-set-handling" title="Permanent
link">¶</a></h3>
<p>As mentioned above Change Sets are dispatched to the method
<code>processChangeSet</code>.
In this tutorial the implementation is quite simple. First we begin a new
transaction. After that we try to execute all requests of the Change Set. If
one of the requests fail all changes have to be rolled back.
-The comments in the source code give a detailed explaination about the steps
done in this mehtod.</p>
+The comments in the source code give a detailed explanation about the steps
done in this method.</p>
<div class="codehilite"><pre><span class="nd">@Override</span>
<span class="kd">public</span> <span class="n">ODataResponsePart</span> <span
class="nf">processChangeSet</span><span class="o">(</span><span
class="kd">final</span> <span class="n">BatchFacade</span> <span
class="n">facade</span><span class="o">,</span> <span class="kd">final</span>
<span class="n">List</span><span class="o"><</span><span
class="n">ODataRequest</span><span class="o">></span> <span
class="n">requests</span><span class="o">)</span>
<span class="kd">throws</span> <span
class="n">ODataApplicationException</span><span class="o">,</span> <span
class="n">ODataLibraryException</span> <span class="o">{</span>
@@ -335,7 +333,7 @@ The comments in the source code give a d
Set the Content-Type header to <code>Content-Type:
multipart/mixed;boundary=abc123</code></p>
<p><strong>Example 1</strong> <br />
Please note that the second request in the Change Set references the first
request of the Change Set.
-This is done by by prefixing the Content-Id of the referenced request with a
$. e.g. <code>$abc</code></p>
+This is done by prefixing the Content-Id of the referenced request with a $.
e.g. <code>$abc</code></p>
<div class="codehilite"><pre><span class="o">--</span><span
class="n">abc123</span>
<span class="n">Content</span><span class="o">-</span><span
class="n">Type</span><span class="p">:</span> <span
class="n">application</span><span class="o">/</span><span class="n">http</span>
<span class="n">Content</span><span class="o">-</span><span
class="n">Transfer</span><span class="o">-</span><span
class="n">Encoding</span><span class="p">:</span> <span class="n">binary</span>
@@ -380,7 +378,7 @@ This is done by by prefixing the Content
</pre></div>
-<p>Now have a look at the response. As you can see a new product has been
created and the desciption has been updated to 'With a changed Description'</p>
+<p>Now have a look at the response. As you can see a new product has been
created and the description has been updated to 'With a changed Description'</p>
<div class="codehilite"><pre><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">Products</span>"<span class="p">,</span>
"<span class="n">value</span>"<span class="p">:</span> <span
class="p">[</span>
@@ -396,7 +394,7 @@ This is done by by prefixing the Content
<p><strong>Example 2</strong> <br />
-Let us try what is happing if the send a invalid request within a Change Set.
Use the same URI and Content Type as before and use the following body:</p>
+Let us try what is happing if we send a invalid request within an Change Set.
Use the same URI and Content-Type as before and use the following body:</p>
<div class="codehilite"><pre><span class="o">--</span><span
class="n">abc123</span>
<span class="n">Content</span><span class="o">-</span><span
class="n">Type</span><span class="p">:</span> <span
class="n">multipart</span><span class="o">/</span><span
class="n">mixed</span><span class="p">;</span><span
class="n">boundary</span><span class="p">=</span><span
class="n">changeset_abc</span>
@@ -426,7 +424,7 @@ Let us try what is happing if the send a
</pre></div>
-<p>As you can see the reponse contains a single request response instead of a
Change Set response. The error message in stored in the response body.</p>
+<p>As you can see the response contains a single request response instead of a
Change Set response. The error message in stored in the response body.</p>
<h1 id="5-links">5. Links<a class="headerlink" href="#5-links"
title="Permanent link">¶</a></h1>
<h3 id="tutorials">Tutorials<a class="headerlink" href="#tutorials"
title="Permanent link">¶</a></h3>
<p>Further topics to be covered by follow-up tutorials:</p>
