You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@olingo.apache.org by bu...@apache.org on 2016/03/01 20:23:41 UTC
svn commit: r981511 - in /websites/staging/olingo/trunk/content: ./
doc/odata4/tutorials/streaming/tutorial_streaming.html
Author: buildbot
Date: Tue Mar 1 19:23:41 2016
New Revision: 981511
Log:
Staging update by buildbot for olingo
Modified:
websites/staging/olingo/trunk/content/ (props changed)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/streaming/tutorial_streaming.html
Propchange: websites/staging/olingo/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Mar 1 19:23:41 2016
@@ -1 +1 @@
-1733078
+1733123
Modified: websites/staging/olingo/trunk/content/doc/odata4/tutorials/streaming/tutorial_streaming.html
==============================================================================
--- websites/staging/olingo/trunk/content/doc/odata4/tutorials/streaming/tutorial_streaming.html (original)
+++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/streaming/tutorial_streaming.html Tue Mar 1 19:23:41 2016
@@ -115,13 +115,13 @@ This tutorial can be found in subdirecto
<li>Links</li>
</ol>
<h1 id="introduction">Introduction<a class="headerlink" href="#introduction" title="Permanent link">¶</a></h1>
-<p>The actual <em>streaming support</em> in the Olingo library enables a way to provide an Entity Collection on a single Entity granularity. This enables support for e.g. <em>chunked HTTP responses</em> without the need to have the whole Entity Collection pre-loaded (and probably in memory). Therefore the <code>EntityIterator</code> interface is used to check for additional entities and to provide the next available entity. The how a single Entity is provided is than completly based on the decision of the service developer.</p>
-<p>A possible implementation then could e.g. pre-load ten entities and serve them as <em>chunked HTTP responses</em> and first with the next requested chunkes the next (ten) entities would be loaded from the database. With such an implementation the runtime memory consumption could be reduced (with the counterpart of more database round trips) and the client has the possibility to visualize the already delivered enities (if the client support this).</p>
+<p>The actual <em>streaming support</em> in the Olingo library enables a way to provide an Entity Collection on a single Entity granularity. This enables support for e.g. <em>chunked HTTP responses</em> without the need to have the whole Entity Collection pre-loaded (and probably in memory). Therefore the <code>EntityIterator</code> interface is used to check for additional entities and to provide the next available entity. The how a single Entity is provided is than completely based on the decision of the service developer.</p>
+<p>A possible implementation then could e.g. pre-load ten entities and serve them as <em>chunked HTTP responses</em> and first with the next requested chunkes the next (ten) entities would be loaded from the database. With such an implementation the runtime memory consumption could be reduced (with the counterpart of more database round trips) and the client has the possibility to visualise the already delivered entities (if the client support this).</p>
<h1 id="preparation">Preparation<a class="headerlink" href="#preparation" title="Permanent link">¶</a></h1>
<p>You should read the previous tutorials first to have an idea how to read entity collections. In addition the following code is based on the <a href="/doc/odata4/tutorials/readep/tutorial_readep.html">read collection tutorial (Part 2)</a>.</p>
<p>As a shortcut for the upcoming modification steps you should checkout the mentioned tutorial project. It is available in the git repository in folder <code>/samples/tutorials/p2_readep</code> (for more information about checkout see in the <a href="/doc/odata4/tutorials/readep/tutorial_readep.html">read collection tutorial (Part 2)</a>).</p>
<p>The main idea of the following implementation is to enable a basic streaming support in the sample <em>data provider</em> (the <code>Storage</code> class) and use this in the already existing processors.</p>
-<p>Thefore following steps have to be performed:</p>
+<p>Therefore following steps have to be performed:</p>
<ul>
<li>Modify the <em>data provider</em> (the <code>Storage</code> class)<ul>
<li>Includes a basic implementation of the <code>EntityIterator</code> interface</li>
@@ -142,119 +142,136 @@ This tutorial can be found in subdirecto
<p>For demonstration of above steps the existing <a href="/doc/odata4/tutorials/readep/tutorial_readep.html">read collection tutorial</a> will be now enabled for <em>streaming of entity collections</em>.</p>
<h2 id="simplest-approach">Simplest approach<a class="headerlink" href="#simplest-approach" title="Permanent link">¶</a></h2>
<p>The <em>simplest approach</em> is to wrap the already existing <code>EntityCollection</code> into an <code>EntityIterator</code> and pass this to the according <code>entityCollectionStreamed(...)</code> method.
-With this the service would not change how the data is accessed but would (easily) enable the possibilty for a (streamed) <em>chunked HTTP response</em> (if this is supported by the environment e.g. JEE application server).</p>
+With this the service would not change how the data is accessed but would (easily) enable the possibility for a (streamed) <em>chunked HTTP response</em> (if this is supported by the environment e.g. JEE application server).</p>
<p>In the existing <a href="/doc/odata4/tutorials/readep/tutorial_readep.html">read collection tutorial</a> following new method is necessary to create an <code>EntityIterator</code> to wrap an <code>EntityCollection</code>:</p>
-<p>```java
-private EntityIterator wrapAsIterator(final EntityCollection collection) {
- final Iterator<Entity> it = collection.iterator();
- return new EntityIterator() {
- @Override
- public boolean hasNext() {
- return it.hasNext();
- }</p>
-<div class="codehilite"><pre><span class="p">@</span><span class="n">Override</span>
-<span class="n">public</span> <span class="n">Entity</span> <span class="n">next</span><span class="p">()</span> <span class="p">{</span>
- <span class="k">return</span> <span class="n">it</span><span class="p">.</span><span class="n">next</span><span class="p">();</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="kd">private</span> <span class="n">EntityIterator</span> <span class="nf">wrapAsIterator</span><span class="o">(</span><span class="kd">final</span> <span class="n">EntityCollection</span> <span class="n">collection</span><span class="o">)</span> <span class="o">{</span>
+ <span class="kd">final</span> <span class="n">Iterator</span><span class="o"><</span><span class="n">Entity</span><span class="o">></span> <span class="n">it</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="na">iterator</span><span class="o">();</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="nf">EntityIterator</span><span class="o">()</span> <span class="o">{</span>
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">hasNext</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="n">it</span><span class="o">.</span><span class="na">hasNext</span><span class="o">();</span>
+ <span class="o">}</span>
+
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="n">Entity</span> <span class="nf">next</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="n">it</span><span class="o">.</span><span class="na">next</span><span class="o">();</span>
+ <span class="o">}</span>
+ <span class="o">};</span>
+<span class="o">}</span>
</pre></div>
-<p>};
-}
-```</p>
<p>The (as anonymous inner class) created <code>EntityIterator</code> only iterates over the already loaded entities (of the <code>EntityCollection</code>).</p>
<p>To use this <code>EntityIterator</code> in the <code>readEntityCollection(..)</code> method the <code>EntityIterator</code> must be passed to the <code>ODataSerializer</code> via the <code>entityCollectionStreamed(...)</code> method and the <code>ODataContent</code> object of the resulting <code>SerializerStreamResult</code> must be set at the <code>ODataResponse</code> via the <code>setODataContent(...)</code> method.
-What sound like a lot to do is just the beolow code snippet:</p>
-<p>```java
- ...
- EntityIterator iterator = wrapAsIterator(entityCollection);
- SerializerStreamResult serializerResult = serializer.entityCollectionStreamed(serviceMetadata,
- edmEntityType, iterator, opts);</p>
-<p>// 4th: configure the response object: set the body, headers and status code
- response.setODataContent(serializerResult.getODataContent());
- ...
-}
-```</p>
+What sound like a lot to do is just the below code snippet:</p>
+<div class="codehilite"><pre> <span class="o">...</span>
+ <span class="n">EntityIterator</span> <span class="n">iterator</span> <span class="o">=</span> <span class="n">wrapAsIterator</span><span class="o">(</span><span class="n">entityCollection</span><span class="o">);</span>
+ <span class="n">SerializerStreamResult</span> <span class="n">serializerResult</span> <span class="o">=</span> <span class="n">serializer</span><span class="o">.</span><span class="na">entityCollectionStreamed</span><span class="o">(</span><span class="n">serviceMetadata</span><span class="o">,</span>
+ <span class="n">edmEntityType</span><span class="o">,</span> <span class="n">iterator</span><span class="o">,</span> <span class="n">opts</span><span class="o">);</span>
+
+ <span class="c1">// 4th: configure the response object: set the body, headers and status code</span>
+ <span class="n">response</span><span class="o">.</span><span class="na">setODataContent</span><span class="o">(</span><span class="n">serializerResult</span><span class="o">.</span><span class="na">getODataContent</span><span class="o">());</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+</pre></div>
+
+
<p>Which replaces following original code snippet:</p>
-<p>```java
- ...
- SerializerResult serializerResult = serializer.entityCollection(serviceMetadata,
- edmEntityType, entityCollection, opts);</p>
-<p>// 4th: configure the response object: set the body, headers and status code
- response.setContent(serializedContent);
- ...
-}
-```</p>
+<div class="codehilite"><pre> <span class="o">...</span>
+ <span class="n">SerializerResult</span> <span class="n">serializerResult</span> <span class="o">=</span> <span class="n">serializer</span><span class="o">.</span><span class="na">entityCollection</span><span class="o">(</span><span class="n">serviceMetadata</span><span class="o">,</span>
+ <span class="n">edmEntityType</span><span class="o">,</span> <span class="n">entityCollection</span><span class="o">,</span> <span class="n">opts</span><span class="o">);</span>
+
+ <span class="c1">// 4th: configure the response object: set the body, headers and status code</span>
+ <span class="n">response</span><span class="o">.</span><span class="na">setContent</span><span class="o">(</span><span class="n">serializedContent</span><span class="o">);</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+</pre></div>
+
+
<h2 id="dataprovider-based-approach">DataProvider based approach<a class="headerlink" href="#dataprovider-based-approach" title="Permanent link">¶</a></h2>
<p>The <em>realistic approach</em> is that the data provider (e.g. a database) creates an <code>EntityIterator</code> which is used to provide the entity collection data (<code>Entity</code> objects) to the <code>EntityProcessor</code> and <code>ODataSerializer</code>.</p>
<p>With this approach not only the option for a (streamed) chunked HTTP response (if this is supported by the environment e.g. JEE application server) is enabled. Furthermore the data provider is in charge at which time how many entities are loaded (and hold) in memory.
This means as example, that a data provider can implement a concept of lazy loading of the entity collection in which e.g. a database connection is established but only the first ten entities are loaded in memory and passed for response serialization. First when the serializer need the eleventh (and/or more) entity those are loaded from the database (and the first ten can be removed from memory).
Practically such an approach requires more database roundtrips but also a smaller memory footprint and less eager loading at the begin of the request/response cycle.</p>
<p>In the existing <a href="/doc/odata4/tutorials/readep/tutorial_readep.html">read collection tutorial</a> the <code>Storage</code> class is used a data provider (acting like a database).
-For enablement of the <em>streaming support</em> following new method is introduced thich create an <code>EntityIterator</code> to allow the iterable passed access to the stored entities:</p>
-<p>```java
-public EntityIterator readEntitySetDataStreamed(EdmEntitySet edmEntitySet)throws ODataApplicationException{
- // actually, this is only required if we have more than one Entity Sets
- if(edmEntitySet.getName().equals(DemoEdmProvider.ES_PRODUCTS_NAME)){
- final Iterator<Entity> it = productList.iterator();
- return new EntityIterator() {
- @Override
- public boolean hasNext() {
- return it.hasNext();
- }</p>
-<div class="codehilite"><pre> <span class="p">@</span><span class="n">Override</span>
- <span class="n">public</span> <span class="n">Entity</span> <span class="n">next</span><span class="p">()</span> <span class="p">{</span>
- <span class="k">return</span> <span class="n">it</span><span class="p">.</span><span class="n">next</span><span class="p">();</span>
- <span class="p">}</span>
-<span class="p">};</span>
+For enablement of the <em>streaming support</em> following new method is introduced which create an <code>EntityIterator</code> to allow the iterable passed access to the stored entities:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="n">EntityIterator</span> <span class="nf">readEntitySetDataStreamed</span><span class="o">(</span><span class="n">EdmEntitySet</span> <span class="n">edmEntitySet</span><span class="o">)</span><span class="kd">throws</span> <span class="n">ODataApplicationException</span> <span class="o">{</span>
+ <span class="c1">// actually, this is only required if we have more than one Entity Sets</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">edmEntitySet</span><span class="o">.</span><span class="na">getName</span><span class="o">().</span><span class="na">equals</span><span class="o">(</span><span class="n">DemoEdmProvider</span><span class="o">.</span><span class="na">ES_PRODUCTS_NAME</span><span class="o">)){</span>
+ <span class="kd">final</span> <span class="n">Iterator</span><span class="o"><</span><span class="n">Entity</span><span class="o">></span> <span class="n">it</span> <span class="o">=</span> <span class="n">productList</span><span class="o">.</span><span class="na">iterator</span><span class="o">();</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="nf">EntityIterator</span><span class="o">()</span> <span class="o">{</span>
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">hasNext</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="n">it</span><span class="o">.</span><span class="na">hasNext</span><span class="o">();</span>
+ <span class="o">}</span>
+
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="n">Entity</span> <span class="nf">next</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="n">it</span><span class="o">.</span><span class="na">next</span><span class="o">();</span>
+ <span class="o">}</span>
+ <span class="o">};</span>
+ <span class="o">}</span>
+
+ <span class="k">return</span> <span class="kc">null</span><span class="o">;</span>
+<span class="o">}</span>
</pre></div>
-<p>}</p>
-<p>return null;
-}
-```</p>
<p>As described above in the existing implementation the use of the <code>EntityCollection</code> has to be replaced with the <code>EntityIterator</code>, which means that this line:
<code>EntityCollection entityCollection = storage.readEntitySetData(edmEntitySet);</code>
has to be replaced by that line:
<code>EntityIterator iterator = storage.readEntitySetDataStreamed(edmEntitySet);</code></p>
-<p>And the
-<code>SerializerResult serializerResult = serializer.entityCollection(
- serviceMetadata, edmEntityType, entityCollection, opts);</code>
-has to be replaced by
-<code>SerializerStreamResult serializerResult = serializer.entityCollectionStreamed(
- serviceMetadata, edmEntityType, iterator, opts);</code></p>
+<p>And the</p>
+<div class="codehilite"><pre><span class="n">SerializerResult</span> <span class="n">serializerResult</span> <span class="o">=</span> <span class="n">serializer</span><span class="o">.</span><span class="na">entityCollection</span><span class="o">(</span>
+ <span class="n">serviceMetadata</span><span class="o">,</span> <span class="n">edmEntityType</span><span class="o">,</span> <span class="n">entityCollection</span><span class="o">,</span> <span class="n">opts</span><span class="o">);</span>
+</pre></div>
+
+
+<p>has to be replaced by</p>
+<div class="codehilite"><pre><span class="n">SerializerStreamResult</span> <span class="n">serializerResult</span> <span class="o">=</span> <span class="n">serializer</span><span class="o">.</span><span class="na">entityCollectionStreamed</span><span class="o">(</span>
+ <span class="n">serviceMetadata</span><span class="o">,</span> <span class="n">edmEntityType</span><span class="o">,</span> <span class="n">iterator</span><span class="o">,</span> <span class="n">opts</span><span class="o">);</span>
+</pre></div>
+
+
<p>And at the <code>ODataResponse</code> now instead of:
<code>response.setContent(serializerResult.getContent());</code>
the result is set as <code>ODataContent</code>:
<code>response.setODataContent(serializerResult.getODataContent());</code></p>
<p>As result the whole <code>readEntityCollection(...)</code> method now look like following:</p>
-<p>```java
-public void readEntityCollection(ODataRequest request, ODataResponse response, UriInfo uriInfo, ContentType responseFormat) throws ODataApplicationException, SerializerException {</p>
-<p>// 1st retrieve the requested EntitySet from the uriInfo (representation of the parsed URI)
- List<UriResource> resourcePaths = uriInfo.getUriResourceParts();
- UriResourceEntitySet uriResourceEntitySet = (UriResourceEntitySet) resourcePaths.get(0); // in our example, the first segment is the EntitySet
- EdmEntitySet edmEntitySet = uriResourceEntitySet.getEntitySet();</p>
-<p>// 2nd: fetch the data from backend for this requested EntitySetName and deliver as EntitySet
- EntityIterator iterator = storage.readEntitySetDataStreamed(edmEntitySet);</p>
-<p>// 3rd: create a serializer based on the requested format (json)
- ODataSerializer serializer = odata.createSerializer(responseFormat);</p>
-<p>// and serialize the content: transform from the EntitySet object to InputStream
- EdmEntityType edmEntityType = edmEntitySet.getEntityType();
- ContextURL contextUrl = ContextURL.with().entitySet(edmEntitySet).build();</p>
-<p>final String id = request.getRawBaseUri() + "/" + edmEntitySet.getName();
- EntityCollectionSerializerOptions opts = EntityCollectionSerializerOptions.with().id(id)
- .contextURL(contextUrl).build();</p>
-<p>SerializerStreamResult serializerResult = serializer.entityCollectionStreamed(serviceMetadata,
- edmEntityType, iterator, opts);</p>
-<p>// 4th: configure the response object: set the body, headers and status code
- response.setODataContent(serializerResult.getODataContent());
- response.setStatusCode(HttpStatusCode.OK.getStatusCode());
- response.setHeader(HttpHeader.CONTENT_TYPE, responseFormat.toContentTypeString());
-}
-```</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">readEntityCollection</span><span class="o">(</span><span class="n">ODataRequest</span> <span class="n">request</span><span class="o">,</span> <span class="n">ODataResponse</span> <span class="n">response</span><span class="o">,</span> <span class="n">UriInfo</span> <span class="n">uriInfo</span><span class="o">,</span> <span class="n">ContentType</span> <span class="n">responseFormat</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">ODataApplicationException</span><span class="o">,</span> <span class="n">SerializerException</span> <span class="o">{</span>
+
+ <span class="c1">// 1st retrieve the requested EntitySet from the uriInfo (representation of the parsed URI)</span>
+ <span class="n">List</span><span class="o"><</span><span class="n">UriResource</span><span class="o">></span> <span class="n">resourcePaths</span> <span class="o">=</span> <span class="n">uriInfo</span><span class="o">.</span><span class="na">getUriResourceParts</span><span class="o">();</span>
+ <span class="n">UriResourceEntitySet</span> <span class="n">uriResourceEntitySet</span> <span class="o">=</span> <span class="o">(</span><span class="n">UriResourceEntitySet</span><span class="o">)</span> <span class="n">resourcePaths</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="mi">0</span><span class="o">);</span> <span class="c1">// in our example, the first segment is the EntitySet</span>
+ <span class="n">EdmEntitySet</span> <span class="n">edmEntitySet</span> <span class="o">=</span> <span class="n">uriResourceEntitySet</span><span class="o">.</span><span class="na">getEntitySet</span><span class="o">();</span>
+
+ <span class="c1">// 2nd: fetch the data from backend for this requested EntitySetName and deliver as EntitySet</span>
+ <span class="n">EntityIterator</span> <span class="n">iterator</span> <span class="o">=</span> <span class="n">storage</span><span class="o">.</span><span class="na">readEntitySetDataStreamed</span><span class="o">(</span><span class="n">edmEntitySet</span><span class="o">);</span>
+
+ <span class="c1">// 3rd: create a serializer based on the requested format (json)</span>
+ <span class="n">ODataSerializer</span> <span class="n">serializer</span> <span class="o">=</span> <span class="n">odata</span><span class="o">.</span><span class="na">createSerializer</span><span class="o">(</span><span class="n">responseFormat</span><span class="o">);</span>
+
+ <span class="c1">// and serialize the content: transform from the EntitySet object to InputStream</span>
+ <span class="n">EdmEntityType</span> <span class="n">edmEntityType</span> <span class="o">=</span> <span class="n">edmEntitySet</span><span class="o">.</span><span class="na">getEntityType</span><span class="o">();</span>
+ <span class="n">ContextURL</span> <span class="n">contextUrl</span> <span class="o">=</span> <span class="n">ContextURL</span><span class="o">.</span><span class="na">with</span><span class="o">().</span><span class="na">entitySet</span><span class="o">(</span><span class="n">edmEntitySet</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
+
+ <span class="kd">final</span> <span class="n">String</span> <span class="n">id</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="s">"/"</span> <span class="o">+</span> <span class="n">edmEntitySet</span><span class="o">.</span><span class="na">getName</span><span class="o">();</span>
+ <span class="n">EntityCollectionSerializerOptions</span> <span class="n">opts</span> <span class="o">=</span> <span class="n">EntityCollectionSerializerOptions</span><span class="o">.</span><span class="na">with</span><span class="o">().</span><span class="na">id</span><span class="o">(</span><span class="n">id</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">contextURL</span><span class="o">(</span><span class="n">contextUrl</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
+
+ <span class="n">SerializerStreamResult</span> <span class="n">serializerResult</span> <span class="o">=</span> <span class="n">serializer</span><span class="o">.</span><span class="na">entityCollectionStreamed</span><span class="o">(</span><span class="n">serviceMetadata</span><span class="o">,</span>
+ <span class="n">edmEntityType</span><span class="o">,</span> <span class="n">iterator</span><span class="o">,</span> <span class="n">opts</span><span class="o">);</span>
+
+ <span class="c1">// 4th: configure the response object: set the body, headers and status code</span>
+ <span class="n">response</span><span class="o">.</span><span class="na">setODataContent</span><span class="o">(</span><span class="n">serializerResult</span><span class="o">.</span><span class="na">getODataContent</span><span class="o">());</span>
+ <span class="n">response</span><span class="o">.</span><span class="na">setStatusCode</span><span class="o">(</span><span class="n">HttpStatusCode</span><span class="o">.</span><span class="na">OK</span><span class="o">.</span><span class="na">getStatusCode</span><span class="o">());</span>
+ <span class="n">response</span><span class="o">.</span><span class="na">setHeader</span><span class="o">(</span><span class="n">HttpHeader</span><span class="o">.</span><span class="na">CONTENT_TYPE</span><span class="o">,</span> <span class="n">responseFormat</span><span class="o">.</span><span class="na">toContentTypeString</span><span class="o">());</span>
+<span class="o">}</span>
+</pre></div>
+
+
<p>After this changes the data access (encapsulated in the <code>EntityIterator</code>) and serialization is now done directly when the data is processed by the web framework layer (e.g. JEE servlet layer) and not within the call hierarchy of the <code>readEntityCollection(...)</code> method.</p>
-<p>The <em>counterpart</em> of this is that when an error/exception occurrs during the serialization of the data the <code>readEntityCollection(...)</code> method already returned and hence there is no possibility (at this point) to catch the exception and do an error handling.
+<p>The <em>counterpart</em> of this is that when an error/exception occurs during the serialization of the data the <code>readEntityCollection(...)</code> method already returned and hence there is no possibility (at this point) to catch the exception and do an error handling.
Furthermore because of the <em>streaming</em> the <em>HTTP Header</em> is already sent to the client (with e.g. a <code>HTTP Status-Code: 200 OK</code>).
Based on this the <em>OData-v4.0 Part1 Protocol</em> describes in chapter <em>9.4 In-Stream Errors</em> how to handle this:</p>
<blockquote>
@@ -264,53 +281,66 @@ Based on this the <em>OData-v4.0 Part1 P
<h3 id="more-realistic-data-provider">More realistic data provider<a class="headerlink" href="#more-realistic-data-provider" title="Permanent link">¶</a></h3>
<p>Because the simplistic data provider in the tutorial the <code>EntityIterator</code> is also very simplistic.
However it is also realistic to have an <code>EntityIterator</code> which e.g. access a database result set which is <code>next():Entity</code> call (see below code snippet to get the idea).</p>
-<p>```java
-public class MyEntityIterator extends EntityIterator {
- ResultSet set; //...</p>
-<p>public MyEntityIterator(ResultSet set) {
- this.set = set;
- }</p>
-<p>@Override
- public boolean hasNext() {
- return set.next();
- }</p>
-<p>@Override
- public Entity next() {
- return readNextEntityFromResultSet();
- }</p>
-<p>private Entity readNextEntityFromResultSet() {
- // read data from result set and return as entity object
- }
-}
-```</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyEntityIterator</span> <span class="kd">extends</span> <span class="n">EntityIterator</span> <span class="o">{</span>
+ <span class="n">ResultSet</span> <span class="n">set</span><span class="o">;</span> <span class="c1">//...</span>
+
+ <span class="kd">public</span> <span class="nf">MyEntityIterator</span><span class="o">(</span><span class="n">ResultSet</span> <span class="n">set</span><span class="o">)</span> <span class="o">{</span>
+ <span class="k">this</span><span class="o">.</span><span class="na">set</span> <span class="o">=</span> <span class="n">set</span><span class="o">;</span>
+ <span class="o">}</span>
+
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">hasNext</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="n">set</span><span class="o">.</span><span class="na">next</span><span class="o">();</span>
+ <span class="o">}</span>
+
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="n">Entity</span> <span class="nf">next</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="nf">readNextEntityFromResultSet</span><span class="o">();</span>
+ <span class="o">}</span>
+
+ <span class="kd">private</span> <span class="n">Entity</span> <span class="nf">readNextEntityFromResultSet</span><span class="o">()</span> <span class="o">{</span>
+ <span class="c1">// read data from result set and return as entity object</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
<h2 id="exceptionerror-handling">Exception/Error Handling<a class="headerlink" href="#exceptionerror-handling" title="Permanent link">¶</a></h2>
-<p>The <em>counterpart</em> of the <em>streaming support</em> is that when an error/exception occurrs during the serialization of the data the service implementation is not in charge anymore to catch the exception and do an error handling.</p>
+<p>The <em>counterpart</em> of the <em>streaming support</em> is that when an error/exception occurs during the serialization of the data the service implementation is not in charge anymore to catch the exception and do an error handling.</p>
<p>Furthermore because of the <em>streaming</em> the <em>HTTP Header</em> is already sent to the client (with e.g. a <code>HTTP Status-Code: 200 OK</code>).
Based on this the <em>OData-v4.0 Part1 Protocol</em> describes in chapter <em>9.4 In-Stream Errors</em> how to handle this:</p>
<blockquote>
<p>In the case that the service encounters an error after sending a success status to the client, the service MUST generate an error within the payload, which may leave the response malformed. Clients MUST treat the entire response as being in error. This specification does not prescribe a particular format for generating errors within a payload.</p>
</blockquote>
<p>For <em>exception/error handling</em> in Olingo exists the <code>ODataContentWriteErrorCallback</code> interface which must be implemented and then can be set as an option at the <code>EntityCollectionSerializerOptions</code> with the <code>writeContentErrorCallback(...)</code> method.</p>
-<p>If during processing (<em>write</em>) of the <code>ODataContent</code> object (normally serialization into an according <code>OutputStream</code>, like the <code>ServletOutputStream</code> in a JEE servlet environment) an exception occurrs the <code>ODataContentWriteErrorCallback</code> <code>handleError</code> method is called.
+<p>If during processing (<em>write</em>) of the <code>ODataContent</code> object (normally serialization into an according <code>OutputStream</code>, like the <code>ServletOutputStream</code> in a JEE servlet environment) an exception occurs the <code>ODataContentWriteErrorCallback</code> <code>handleError</code> method is called.
This method get as parameter the <code>ODataContentWriteErrorContext</code> which contains at least the thrown and to be handled <code>Exception</code> and the <code>WritableByteChannel</code> in which the payload of the response was written before the error occurred.
Based on the requirements of the OData specification that <em>the service MUST generate an error within the payload, which may leave the response malformed</em> the <code>WritableByteChannel</code> is still open and the service developer can write additional data to ensure that the response payload is malformed.</p>
<p>A basic <code>ODataContentWriteErrorCallback</code> implementation could look like this code snippet:</p>
-<p><code>java
-private ODataContentWriteErrorCallback errorCallback = new ODataContentWriteErrorCallback() {
- public void handleError(ODataContentWriteErrorContext context, WritableByteChannel channel) {
- String message = "An error occurred with message: ";
- if(context.getException() != null) {
- message += context.getException().getMessage();
- }
- channel.write(ByteBuffer.wrap(message.getBytes());
- }
-};</code></p>
+<div class="codehilite"><pre><span class="kd">private</span> <span class="n">ODataContentWriteErrorCallback</span> <span class="n">errorCallback</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ODataContentWriteErrorCallback</span><span class="o">()</span> <span class="o">{</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">handleError</span><span class="o">(</span><span class="n">ODataContentWriteErrorContext</span> <span class="n">context</span><span class="o">,</span> <span class="n">WritableByteChannel</span> <span class="n">channel</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">String</span> <span class="n">message</span> <span class="o">=</span> <span class="s">"An error occurred with message: "</span><span class="o">;</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">context</span><span class="o">.</span><span class="na">getException</span><span class="o">()</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">message</span> <span class="o">+=</span> <span class="n">context</span><span class="o">.</span><span class="na">getException</span><span class="o">().</span><span class="na">getMessage</span><span class="o">();</span>
+ <span class="o">}</span>
+ <span class="k">try</span> <span class="o">{</span>
+ <span class="n">channel</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="n">ByteBuffer</span><span class="o">.</span><span class="na">wrap</span><span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="na">getBytes</span><span class="o">()));</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">IOException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="k">throw</span> <span class="k">new</span> <span class="nf">RuntimeException</span><span class="o">();</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+<span class="o">};</span>
+</pre></div>
+
+
<p>And could be set in the <a href="/doc/odata4/tutorials/readep/tutorial_readep.html">read collection tutorial</a> at the <code>EntityCollectionSerializerOptions</code> via the <code>.writeContentErrorCallback(errorCallback)</code> method.</p>
-<p><code>java
-EntityCollectionSerializerOptions opts =
- EntityCollectionSerializerOptions.with().id(id)
- .writeContentErrorCallback(errorCallback)
- .contextURL(contextUrl).build();</code></p>
+<div class="codehilite"><pre><span class="n">EntityCollectionSerializerOptions</span> <span class="n">opts</span> <span class="o">=</span>
+ <span class="n">EntityCollectionSerializerOptions</span><span class="o">.</span><span class="na">with</span><span class="o">().</span><span class="na">id</span><span class="o">(</span><span class="n">id</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">writeContentErrorCallback</span><span class="o">(</span><span class="n">errorCallback</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">contextURL</span><span class="o">(</span><span class="n">contextUrl</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
+</pre></div>
+
+
<h1 id="run-sample-service">Run sample service<a class="headerlink" href="#run-sample-service" title="Permanent link">¶</a></h1>
<p>After building and deploying your service to your server, you can try a requests to the entity set via: <a href="http://localhost:8080/DemoService-Action/DemoService.svc/Products">http://localhost:8080/DemoService-Action/DemoService.svc/Products</a></p>
<h1 id="links">Links<a class="headerlink" href="#links" title="Permanent link">¶</a></h1>