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 2015/08/05 14:49:45 UTC
svn commit: r960872 - in /websites/staging/olingo/trunk/content: ./
doc/odata4/tutorials/sqo_tcs/
Author: buildbot
Date: Wed Aug 5 12:49:44 2015
New Revision: 960872
Log:
Staging update by buildbot for olingo
Added:
websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/
websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseCount.jpg (with props)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseFull.jpg (with props)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseSkip2.jpg (with props)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseSkipTopCount.jpg (with props)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseTop2.jpg (with props)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html
Modified:
websites/staging/olingo/trunk/content/ (props changed)
Propchange: websites/staging/olingo/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Aug 5 12:49:44 2015
@@ -1 +1 @@
-1694170
+1694201
Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseCount.jpg
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseCount.jpg
------------------------------------------------------------------------------
svn:executable = *
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseCount.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseFull.jpg
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseFull.jpg
------------------------------------------------------------------------------
svn:executable = *
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseFull.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseSkip2.jpg
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseSkip2.jpg
------------------------------------------------------------------------------
svn:executable = *
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseSkip2.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseSkipTopCount.jpg
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseSkipTopCount.jpg
------------------------------------------------------------------------------
svn:executable = *
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseSkipTopCount.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseTop2.jpg
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseTop2.jpg
------------------------------------------------------------------------------
svn:executable = *
Propchange: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/responseTop2.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html
==============================================================================
--- websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html (added)
+++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html Wed Aug 5 12:49:44 2015
@@ -0,0 +1,473 @@
+<!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 Library
+ </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/odata4/download.html">Download OData 4.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/odata4/index.html">Documentation OData 4.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 --><style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h1 id="how-to-build-an-odata-service-with-olingo-v4">How to build an OData Service with Olingo V4<a class="headerlink" href="#how-to-build-an-odata-service-with-olingo-v4" title="Permanent link">¶</a></h1>
+<h1 id="part-51-system-query-options-top-skip-count">Part 5.1: System Query Options $top, <code>$skip</code>, <code>$count</code><a class="headerlink" href="#part-51-system-query-options-top-skip-count" title="Permanent link">¶</a></h1>
+<h2 id="introduction">Introduction<a class="headerlink" href="#introduction" title="Permanent link">¶</a></h2>
+<p>In the present tutorial, weâll learn how to implement <strong>system query options</strong>.<br />
+Query options are used to refine the result of a query.<br />
+The <a href="http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part2-url-conventions/odata-v4.0-errata02-os-part2-url-conventions-complete.html#_Toc406398093">OData V4 specification document</a> gives the following definition:</p>
+<blockquote>
+<p>âSystem query options are query string parameters that control the amount and order of the data returned for the resource identified by the URL. The names of all system query options are prefixed with a dollar ($) character.â</p>
+</blockquote>
+<p>Query options are not part of the resource path, theyâre appended to the URL after the â?â</p>
+<p>For example:<br />
+When querying the list of products, the order of the returned entries is defaulted by the OData service. However, the user can change the order of the list by specifying the query option <code>$orderby</code>.</p>
+<p>Examples for system query options that are commonly used: </p>
+<ul>
+<li><code>$top</code> </li>
+<li><code>$skip</code> </li>
+<li><code>$count</code> </li>
+<li><code>$select</code> </li>
+<li><code>$orderby</code> </li>
+<li><code>$filter</code> </li>
+<li><code>$expand</code> </li>
+</ul>
+<p>The present tutorial focuses on the first 3 query options: <code>$top</code>, <code>$skip</code> and <code>$count</code></p>
+<p><strong>Examples</strong></p>
+<p>The following example calls are based on our sample service and illustrate the usage of these 3 query options.</p>
+<p>First, just to remember, the ânormalâ query of the product without query options:<br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products">http://localhost:8080/DemoService/DemoService.svc/Products</a></p>
+<p><img alt="AllProductsNoQueryOption" src="responseFull.jpg" title="The full list of Products" /></p>
+<p>The following URL provides only the first 2 entries and ignores all the rest:<br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$top=2">http://localhost:8080/DemoService/DemoService.svc/Products?$top=2</a></p>
+<p><img alt="ProductsWith$top" src="responseTop2.jpg" title="The first 2 entries of the list of Products" /></p>
+<p>The following request returns the products starting with the 3rd and ignores the first 2 entries:
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$skip=2">http://localhost:8080/DemoService/DemoService.svc/Products?<code>$skip</code>=2</a></p>
+<p><img alt="ProductsWith$skip" src="responseSkip2.jpg" title="Skipping the first 2 entries of the list of Products" /></p>
+<p>The following request returns the total number of products and includes it in the payload:<br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$count=true">http://localhost:8080/DemoService/DemoService.svc/Products?<code>$count</code>=true</a></p>
+<p><img alt="ProductsWith$count" src="responseCount.jpg" title="The full list of Products with the count added in the payload" /></p>
+<p><strong>Note:</strong><br />
+The full implementation of the OData service as described in the present tutorial can be found in the attached zip file that contains an Eclipse project that can be imported into your Eclipse workspace.</p>
+<p><strong>Disclaimer:</strong><br />
+Again, in the present tutorial, weâll focus only on the relevant implementation, in order to keep the code small and simple. The sample code shouldnât be reused for advanced scenarios.</p>
+<p><strong>Table of Contents</strong></p>
+<ol>
+<li>Prerequisites</li>
+<li>Preparation</li>
+<li>Implementating system query options<ol>
+<li>Implement <code>$count</code></li>
+<li>Implement <code>$skip</code></li>
+<li>Implement <code>$top</code></li>
+</ol>
+</li>
+<li>Run the implemented service</li>
+<li>Summary</li>
+<li>Links</li>
+</ol>
+<hr />
+<h1 id="1-prerequisites">1. Prerequisites<a class="headerlink" href="#1-prerequisites" title="Permanent link">¶</a></h1>
+<p>Same prerequisites as in <a href="/doc/odata4/tutorials/read/tutorial_read.html">Tutorial Part 1: Read Entity Collection</a>
+ and <a href="/doc/odata4/tutorials/readep/tutorial_readep.html">Tutorial Part 2: Read Entity</a> as well as basic knowledge about the concepts presented in both tutorials.</p>
+<hr />
+<h1 id="2-preparation">2. Preparation<a class="headerlink" href="#2-preparation" title="Permanent link">¶</a></h1>
+<p>Follow <em>Tutorial Part 1: Read Entity Collection</em> and <em>Tutorial Part 2: Read Entity</em> or as shortcut import the project attached to Tutorial Part 2 into your Eclipse workspace.</p>
+<p>Afterwards do a <em>Deploy and run</em>: it should be working.</p>
+<hr />
+<h1 id="3-implementing-system-query-options">3. Implementing system query options<a class="headerlink" href="#3-implementing-system-query-options" title="Permanent link">¶</a></h1>
+<p>The system query options weâre focusing on are applied to the entity collection only (for example, it doesnât make sense to apply a $top to a READ request of a single entity)</p>
+<p>Therefore our implementation for all three query options is done in the class<br />
+<em>myservice.mynamespace.service.DemoEntityCollectionProcessor</em></p>
+<p>The general sequence of the implementation remains unchanged:</p>
+<ol>
+<li>Analyze the URI</li>
+<li>Fetch data from backend</li>
+<li>Serialize</li>
+<li>Configure the response</li>
+</ol>
+<p>The only difference is that we apply the query options after getting the data from the backend (our database-mock).<br />
+So the procedure will be:</p>
+<ol>
+<li>Analyze the URI</li>
+<li>Fetch data from backend</li>
+<li>Apply all system query options</li>
+<li>Serialize</li>
+<li>Configure the response</li>
+</ol>
+<p>The following sections describe how such system query options are implemented.<br />
+The procedure will be similar in all 3 cases: </p>
+<ol>
+<li>Get the query option from the UriInfo. If null is returned then nothing has to be done. </li>
+<li>Get the value from the query option </li>
+<li>Analyze the value </li>
+<li>Modify the EntityCollection </li>
+</ol>
+<h2 id="31-implement-count">3.1. Implement <code>$count</code><a class="headerlink" href="#31-implement-count" title="Permanent link">¶</a></h2>
+<p><strong>Background</strong><br />
+The <code>$count</code> allows users to request a count of the matching resources.<br />
+The number will be included with the resources in the response (see screenshot above).</p>
+<p>The user specifies the <code>$count</code> as follows:<br />
+<code>$count=true</code><br />
+<code>$count=false</code> </p>
+<p>If the value of <code>$count</code> is set to <em>false</em>, then no number is returned, the same like if <code>$count</code> is not specified at all. However, this case has to be considered in our code as well.</p>
+<p>Note:<br />
+For those who are used to OData V2:<br />
+In V2, the query option <code>$inlinecount</code> has now been replaced in V4 by <code>$count=true</code>.
+In V2, the <code>/$count</code> that was part of the resource path, has now been removed in V4. </p>
+<p>Thereâs one more important detail that we have to consider before writing the code:<br />
+<code>$count</code> always returns the original number of entities, without considering <em>$top</em> and <code>$skip</code>.<br />
+This is specified by the <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#_Toc406398308">OData V4 specification</a>: </p>
+<blockquote>
+<p>âThe <code>$count</code> system query option ignores any $top, <code>$skip</code>, or <code>$expand</code> query options, and returns the total count of results across all pages including only those results matching any specified <code>$filter</code> and $search.â </p>
+</blockquote>
+<p>Therefore, in our sample code, the <code>$count</code> will be the first to be implemented, to make sure that the data provided by the backend is not modified at the moment when we "count" it.</p>
+<p><strong>Implementation</strong><br />
+As in the previous tutorials, the data is fetched from the backend.<br />
+It is provided as <code>EntityCollection</code> which we can ask for the list of contained <code>Entity</code> instances.<br />
+The size of this genuine list is the relevant information for our <code>$count</code>.<br />
+Furthermore, we create a new instance of an <code>EntityCollection</code> object, which will carry the modified list of entities after applying all the query options. </p>
+<div class="codehilite"><pre><span class="n">EntityCollection</span> <span class="n">entityCollection</span> <span class="o">=</span> <span class="n">storage</span><span class="o">.</span><span class="na">readEntitySetData</span><span class="o">(</span><span class="n">edmEntitySet</span><span class="o">);</span>
+<span class="n">List</span><span class="o"><</span><span class="n">Entity</span><span class="o">></span> <span class="n">entityList</span> <span class="o">=</span> <span class="n">entityCollection</span><span class="o">.</span><span class="na">getEntities</span><span class="o">();</span>
+<span class="n">EntityCollection</span> <span class="n">returnEntityCollection</span> <span class="o">=</span> <span class="k">new</span> <span class="n">EntityCollection</span><span class="o">();</span>
+</pre></div>
+
+
+<p>Then we proceed with the 4 steps as described above: </p>
+<ol>
+<li>Get the query option from the <code>UriInfo</code>. If null is returned then nothing has to be done. </li>
+<li>Get the value from the query option </li>
+<li>Analyze the value </li>
+<li>Modify the <code>EntityCollection</code></li>
+</ol>
+<p>And this is the sample code:</p>
+<div class="codehilite"><pre><span class="n">CountOption</span> <span class="n">countOption</span> <span class="o">=</span> <span class="n">uriInfo</span><span class="o">.</span><span class="na">getCountOption</span><span class="o">();</span>
+<span class="k">if</span> <span class="o">(</span><span class="n">countOption</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="kt">boolean</span> <span class="n">isCount</span> <span class="o">=</span> <span class="n">countOption</span><span class="o">.</span><span class="na">getValue</span><span class="o">();</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">isCount</span><span class="o">){</span>
+ <span class="n">returnEntityCollection</span><span class="o">.</span><span class="na">setCount</span><span class="o">(</span><span class="n">entityList</span><span class="o">.</span><span class="na">size</span><span class="o">());</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Note:<br />
+We donât need to check if the value of the <code>$count</code> is incorrect (e.g. <code>$count=xxx</code>), as this is handled by the <em>Olingo OData V4</em> library.</p>
+<p>One additional step has to be considered:<br />
+As we know, if <code>$count=true</code> is specified, the structure of the response payload is different.<br />
+So we have to inform the serializer.that <code>$count</code> has to be considered.<br />
+So we have to modify the line of code, where the <code>EntityCollectionSerializerOptions</code> is created: </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="o">.</span><span class="na">contextURL</span><span class="o">(</span><span class="n">contextUrl</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">count</span><span class="o">(</span><span class="n">countOption</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
+</pre></div>
+
+
+<p>Furthermore, we have to change the following line, because the <code>EntityCollection</code> to be returned is now different;</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">returnEntityCollection</span><span class="o">,</span>
+ <span class="n">opts</span><span class="o">);</span>
+</pre></div>
+
+
+<h2 id="32-implement-skip">3.2. Implement <code>$skip</code><a class="headerlink" href="#32-implement-skip" title="Permanent link">¶</a></h2>
+<p><strong>Background</strong><br />
+With the query option <code>$skip</code>, the user of an OData service can specify the number of entries that should be ignored at the beginning of a collection.<br />
+So if a user specifies <code>$skip=n</code> then our OData service has to return the list of entries starting at position n+1</p>
+<p>One important rule that we have to consider is described by the OData specification:<br />
+âWhere $top and <code>$skip</code> are used together, <code>$skip</code> MUST be applied before $top, regardless of the order in which they appear in the request.â<br />
+See <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#_Toc406398306">here</a></p>
+<p>This means for us that we add the code for <code>$skip</code> before the code for <em>$top</em>.</p>
+<p><strong>Implementation</strong></p>
+<p>Again we follow the 4 mentioned steps.<br />
+We get the <code>SkipOption</code> object from the <code>UriInfo</code>.<br />
+If the <code>SkipOption</code> is null, then it hasnât been specified by the user.<br />
+Since it is not mandatory to specify any query option, we can ignore the case of <code>SkipOption</code> being null.<br />
+We ask the <code>SkipOption</code> object for the value that has been specified by the user.<br />
+Since the user might give invalid numbers, we have to check that and throw an exception with HTTP status as âBad Requestâ.<br />
+Then we can do the actual job, which is adapting the backend-data according to the specified <code>$skip</code>. </p>
+<div class="codehilite"><pre><span class="n">SkipOption</span> <span class="n">skipOption</span> <span class="o">=</span> <span class="n">uriInfo</span><span class="o">.</span><span class="na">getSkipOption</span><span class="o">();</span>
+<span class="k">if</span> <span class="o">(</span><span class="n">skipOption</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="kt">int</span> <span class="n">skipNumber</span> <span class="o">=</span> <span class="n">skipOption</span><span class="o">.</span><span class="na">getValue</span><span class="o">();</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">skipNumber</span> <span class="o">>=</span> <span class="mi">0</span> <span class="o">&&</span> <span class="n">skipNumber</span> <span class="o"><=</span> <span class="n">entityList</span><span class="o">.</span><span class="na">size</span><span class="o">()){</span>
+ <span class="n">entityList</span> <span class="o">=</span> <span class="n">entityList</span><span class="o">.</span><span class="na">subList</span><span class="o">(</span><span class="n">skipNumber</span><span class="o">,</span> <span class="n">entityList</span><span class="o">.</span><span class="na">size</span><span class="o">());</span>
+ <span class="o">}</span><span class="k">else</span><span class="o">{</span>
+ <span class="k">throw</span> <span class="k">new</span> <span class="nf">ODataApplicationException</span><span class="o">(</span><span class="s">"Invalid value for `$skip`"</span><span class="o">,</span>
+ <span class="n">HttpStatusCode</span><span class="o">.</span><span class="na">BAD_REQUEST</span><span class="o">.</span><span class="na">getStatusCode</span><span class="o">(),</span><span class="n">Locale</span><span class="o">.</span><span class="na">ROOT</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>After applying the query option, we have the desired set of entities in the variable <code>entityList</code>.<br />
+Now we have to populate the <code>EntityCollection</code> instance, that we created in the section above, with these entities, before we can pass it to the serializer:</p>
+<div class="codehilite"><pre><span class="k">for</span><span class="o">(</span><span class="n">Entity</span> <span class="n">entity</span> <span class="o">:</span> <span class="n">entityList</span><span class="o">){</span>
+ <span class="n">returnEntityCollection</span><span class="o">.</span><span class="na">getEntities</span><span class="o">().</span><span class="na">add</span><span class="o">(</span><span class="n">entity</span><span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h2 id="33-implement-top">3.3. Implement $top<a class="headerlink" href="#33-implement-top" title="Permanent link">¶</a></h2>
+<p><strong>Background</strong><br />
+With the query option <em>$top</em>, the user of an OData service can specify the maximum number of entries that should be returned, starting from the beginning.</p>
+<p><strong>Implementation</strong></p>
+<p>Again we follow the 4 mentioned steps, the code is very similar, only the logic for reducing the entityList is different:</p>
+<div class="codehilite"><pre><span class="n">TopOption</span> <span class="n">topOption</span> <span class="o">=</span> <span class="n">uriInfo</span><span class="o">.</span><span class="na">getTopOption</span><span class="o">();</span>
+<span class="k">if</span><span class="o">(</span><span class="n">topOption</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">){</span>
+ <span class="kt">int</span> <span class="n">topNumber</span> <span class="o">=</span> <span class="n">topOption</span><span class="o">.</span><span class="na">getValue</span><span class="o">();</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">topNumber</span> <span class="o">>=</span> <span class="mi">0</span> <span class="o">&&</span> <span class="n">topNumber</span> <span class="o"><=</span> <span class="n">entityList</span><span class="o">.</span><span class="na">size</span><span class="o">()){</span>
+ <span class="n">entityList</span> <span class="o">=</span> <span class="n">entityList</span><span class="o">.</span><span class="na">subList</span><span class="o">(</span><span class="mi">0</span><span class="o">,</span> <span class="n">topNumber</span><span class="o">);</span>
+ <span class="o">}</span><span class="k">else</span><span class="o">{</span>
+ <span class="k">throw</span> <span class="k">new</span> <span class="nf">ODataApplicationException</span><span class="o">(</span><span class="s">"Invalid value for $top"</span><span class="o">,</span>
+ <span class="n">HttpStatusCode</span><span class="o">.</span><span class="na">BAD_REQUEST</span><span class="o">.</span><span class="na">getStatusCode</span><span class="o">(),</span><span class="n">Locale</span><span class="o">.</span><span class="na">ROOT</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>So now we can finally have a look at the full implementation of the <code>readEntityCollection()</code> method, containing all the three query options:</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</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="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</span>
+ <span class="n">EntityCollection</span> <span class="n">entityCollection</span> <span class="o">=</span> <span class="n">storage</span><span class="o">.</span><span class="na">readEntitySetData</span><span class="o">(</span><span class="n">edmEntitySet</span><span class="o">);</span>
+
+ <span class="c1">// 3rd: apply System Query Options</span>
+ <span class="c1">// modify the result set according to the query options, specified by the end user</span>
+ <span class="n">List</span><span class="o"><</span><span class="n">Entity</span><span class="o">></span> <span class="n">entityList</span> <span class="o">=</span> <span class="n">entityCollection</span><span class="o">.</span><span class="na">getEntities</span><span class="o">();</span>
+ <span class="n">EntityCollection</span> <span class="n">returnEntityCollection</span> <span class="o">=</span> <span class="k">new</span> <span class="n">EntityCollection</span><span class="o">();</span>
+
+ <span class="c1">// handle `$count`: return the original number of entities, ignore $top and `$skip`</span>
+ <span class="n">CountOption</span> <span class="n">countOption</span> <span class="o">=</span> <span class="n">uriInfo</span><span class="o">.</span><span class="na">getCountOption</span><span class="o">();</span>
+ <span class="k">if</span> <span class="o">(</span><span class="n">countOption</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="kt">boolean</span> <span class="n">isCount</span> <span class="o">=</span> <span class="n">countOption</span><span class="o">.</span><span class="na">getValue</span><span class="o">();</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">isCount</span><span class="o">){</span>
+ <span class="n">returnEntityCollection</span><span class="o">.</span><span class="na">setCount</span><span class="o">(</span><span class="n">entityList</span><span class="o">.</span><span class="na">size</span><span class="o">());</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+
+ <span class="c1">// handle `$skip`</span>
+ <span class="n">SkipOption</span> <span class="n">skipOption</span> <span class="o">=</span> <span class="n">uriInfo</span><span class="o">.</span><span class="na">getSkipOption</span><span class="o">();</span>
+ <span class="k">if</span> <span class="o">(</span><span class="n">skipOption</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="kt">int</span> <span class="n">skipNumber</span> <span class="o">=</span> <span class="n">skipOption</span><span class="o">.</span><span class="na">getValue</span><span class="o">();</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">skipNumber</span> <span class="o">>=</span> <span class="mi">0</span> <span class="o">&&</span> <span class="n">skipNumber</span> <span class="o"><=</span> <span class="n">entityList</span><span class="o">.</span><span class="na">size</span><span class="o">()){</span>
+ <span class="n">entityList</span> <span class="o">=</span> <span class="n">entityList</span><span class="o">.</span><span class="na">subList</span><span class="o">(</span><span class="n">skipNumber</span><span class="o">,</span> <span class="n">entityList</span><span class="o">.</span><span class="na">size</span><span class="o">());</span>
+ <span class="o">}</span><span class="k">else</span><span class="o">{</span>
+ <span class="k">throw</span> <span class="k">new</span> <span class="nf">ODataApplicationException</span><span class="o">(</span><span class="s">"Invalid value for `$skip`"</span><span class="o">,</span>
+ <span class="n">HttpStatusCode</span><span class="o">.</span><span class="na">BAD_REQUEST</span><span class="o">.</span><span class="na">getStatusCode</span><span class="o">(),</span><span class="n">Locale</span><span class="o">.</span><span class="na">ROOT</span><span class="o">);</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+
+ <span class="c1">// handle $top</span>
+ <span class="n">TopOption</span> <span class="n">topOption</span> <span class="o">=</span> <span class="n">uriInfo</span><span class="o">.</span><span class="na">getTopOption</span><span class="o">();</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">topOption</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">){</span>
+ <span class="kt">int</span> <span class="n">topNumber</span> <span class="o">=</span> <span class="n">topOption</span><span class="o">.</span><span class="na">getValue</span><span class="o">();</span>
+ <span class="k">if</span><span class="o">(</span><span class="n">topNumber</span> <span class="o">>=</span> <span class="mi">0</span> <span class="o">&&</span> <span class="n">topNumber</span> <span class="o"><=</span> <span class="n">entityList</span><span class="o">.</span><span class="na">size</span><span class="o">()){</span>
+ <span class="n">entityList</span> <span class="o">=</span> <span class="n">entityList</span><span class="o">.</span><span class="na">subList</span><span class="o">(</span><span class="mi">0</span><span class="o">,</span> <span class="n">topNumber</span><span class="o">);</span>
+ <span class="o">}</span><span class="k">else</span><span class="o">{</span>
+ <span class="k">throw</span> <span class="k">new</span> <span class="nf">ODataApplicationException</span><span class="o">(</span><span class="s">"Invalid value for $top"</span><span class="o">,</span>
+ <span class="n">HttpStatusCode</span><span class="o">.</span><span class="na">BAD_REQUEST</span><span class="o">.</span><span class="na">getStatusCode</span><span class="o">(),</span><span class="n">Locale</span><span class="o">.</span><span class="na">ROOT</span><span class="o">);</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+
+ <span class="c1">// after applying the query options, create EntityCollection based on the reduced list</span>
+ <span class="k">for</span><span class="o">(</span><span class="n">Entity</span> <span class="n">entity</span> <span class="o">:</span> <span class="n">entityList</span><span class="o">){</span>
+ <span class="n">returnEntityCollection</span><span class="o">.</span><span class="na">getEntities</span><span class="o">().</span><span class="na">add</span><span class="o">(</span><span class="n">entity</span><span class="o">);</span>
+ <span class="o">}</span>
+
+ <span class="c1">// 4th: create a serializer based on the requested format (json)</span>
+ <span class="n">ODataFormat</span> <span class="n">format</span> <span class="o">=</span> <span class="n">ODataFormat</span><span class="o">.</span><span class="na">fromContentType</span><span class="o">(</span><span class="n">responseFormat</span><span class="o">);</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">format</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="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="o">.</span><span class="na">contextURL</span><span class="o">(</span><span class="n">contextUrl</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">count</span><span class="o">(</span><span class="n">countOption</span><span class="o">).</span><span class="na">build</span><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">returnEntityCollection</span><span class="o">,</span>
+ <span class="n">opts</span><span class="o">);</span>
+ <span class="n">InputStream</span> <span class="n">serializedContent</span> <span class="o">=</span> <span class="n">serializerResult</span><span class="o">.</span><span class="na">getContent</span><span class="o">();</span>
+
+ <span class="c1">// 5th: 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="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>
+
+
+<hr />
+<h1 id="4-run-the-implemented-service">4. Run the implemented service<a class="headerlink" href="#4-run-the-implemented-service" title="Permanent link">¶</a></h1>
+<p>After building and deploying your service to your server, you can try the following URLs: </p>
+<ul>
+<li>
+<p>The full collection, no query option<br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products">http://localhost:8080/DemoService/DemoService.svc/Products</a></p>
+</li>
+<li>
+<p>First 2 products only<br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$top=2">http://localhost:8080/DemoService/DemoService.svc/Products?$top=2</a></p>
+</li>
+<li>
+<p>Exclude the first 2 products<br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$skip=2">http://localhost:8080/DemoService/DemoService.svc/Products?<code>$skip</code>=2</a></p>
+</li>
+<li>
+<p>Add the full number of all products to the response payload<br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$count=true">http://localhost:8080/DemoService/DemoService.svc/Products?<code>$count</code>=true</a></p>
+</li>
+<li>
+<p>Combine $top and <code>$skip</code>
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$skip=1&$top=1">http://localhost:8080/DemoService/DemoService.svc/Products?<code>$skip</code>=1&$top=1</a><br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$top=1&$skip=1">http://localhost:8080/DemoService/DemoService.svc/Products?$top=1&<code>$skip</code>=1</a><br />
+Regardless of the order, the result should be the same</p>
+</li>
+<li>
+<p>Combine all 3 query options<br />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$skip=1&$top=1&$count=true">http://localhost:8080/DemoService/DemoService.svc/Products?<code>$skip</code>=1&$top=1&<code>$count</code>=true</a></p>
+</li>
+</ul>
+<hr />
+<h1 id="5-summary">5. Summary<a class="headerlink" href="#5-summary" title="Permanent link">¶</a></h1>
+<p>In this tutorial we have learned how enhance our OData service to support system query options.
+In a first step, weâve covered <code>$top</code>, <code>$skip</code> and <code>$count</code>.<br />
+More system query options will be treated in the subsequent tutorials. </p>
+<hr />
+<h1 id="6-links">6. Links<a class="headerlink" href="#6-links" title="Permanent link">¶</a></h1>
+<h3 id="tutorials">Tutorials<a class="headerlink" href="#tutorials" title="Permanent link">¶</a></h3>
+<ul>
+<li>Tutorial OData V4 service part 1: <a href="/doc/odata4/tutorials/read/tutorial_read.html">Read Entity Collection</a> | <a href="http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_Read.zip">sample project</a> (<a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Read.zip.md5">md5</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Read.zip.sha512">sha512</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Read.zip.asc">pgp</a>).</li>
+<li>Tutorial OData V4 service part 2: <a href="/doc/odata4/tutorials/readep/tutorial_readep.html">Read Entity, Read Property</a> | <a href="http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_ReadEp.zip">sample project zip</a> (<a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_ReadEp.zip.md5">md5</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_ReadEp.zip.sha512">sha512</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_ReadEp.zip.asc">pgp</a>) </li>
+<li>Tutorial OData V4 service part 3: <a href="/doc/odata4/tutorials/write/tutorial_write.html">Write (Create, Update, Delete Entity)</a> | <a href="http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_Write.zip">sample project zip</a> (<a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Write.zip.md5">md5</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Write.zip.sha512">sha512</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Write.zip.asc">pgp</a>) </li>
+<li>Tutorial OData V4 service, part 4: <a href="/doc/odata4/tutorials/navigation/tutorial_navigation.html">Navigation (this page)</a> | <a href="http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip">sample project zip</a> (<a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip.md5">md5</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip.sha512">sha512</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip.asc">pgp</a>)</li>
+<li>Tutorial OData V4 service, part 5.1: <a href="/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html">System Query Options $top, <code>$skip</code>, <code>$count</code> (this page)</a> | <a href="http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip">sample project zip</a> (<a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.md5">md5</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.sha512">sha512</a>, <a href="https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.asc">pgp</a>) </li>
+<li>Tutorial OData V4 service, part 5.2: System Query Options <code>$select</code>, <code>$expand</code></li>
+<li>Tutorial OData V4 service, part 5.3: System Query Options <code>$orderby</code>, <code>$filter</code> (to be announced)</li>
+</ul>
+<h3 id="further-reading">Further reading<a class="headerlink" href="#further-reading" title="Permanent link">¶</a></h3>
+<ul>
+<li>OData specification: <a href="http://odata.org/">http://odata.org/</a></li>
+<li><a href="/javadoc/odata4/index.html">Olingo Javadoc</a></li>
+</ul><div align="center">
+<p>Copyright © 2013-2015, 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>