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 15:00:06 UTC
svn commit: r960873 - in /websites/staging/olingo/trunk/content: ./
doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html
Author: buildbot
Date: Wed Aug 5 13:00:06 2015
New Revision: 960873
Log:
Staging update by buildbot for olingo
Modified:
websites/staging/olingo/trunk/content/ (props changed)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html
Propchange: websites/staging/olingo/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Aug 5 13:00:06 2015
@@ -1 +1 @@
-1694201
+1694203
Modified: 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 (original)
+++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html Wed Aug 5 13:00:06 2015
@@ -98,7 +98,7 @@
}
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>
+<h1 id="part-51-system-query-options-top-skip-count">Part 5.1: System Query Options <code>$top</code>, <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 />
@@ -106,9 +106,11 @@ The <a href="http://docs.oasis-open.org/
<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>Query options are not part of the resource path, theyâre appended to the URL after the <code>?</code>.
+As an example the URL <a href="http://localhost:8080/my/page?example=true">http://localhost:8080/my/page?example=true</a> has <em>example</em> as <em>query option</em> with the value <em>true</em>.</p>
+<p>As an example for a system query option in Odata:<br />
+When querying the list of products, the order of the returned entries is defaulted by the OData service.<br />
+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>
@@ -119,7 +121,7 @@ When querying the list of products, the
<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>The present tutorial focuses on the first three 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 />
@@ -237,7 +239,7 @@ Furthermore, we create a new instance of
</pre></div>
-<p>Note:<br />
+<p><strong>Note:</strong><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 />
@@ -261,10 +263,11 @@ So we have to modify the line of code, w
<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>One important rule that we have to consider is described 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#_Toc406398306">OData V4 specification</a>: </p>
+<blockquote>
+<p>â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.â </p>
+</blockquote>
+<p>This means for us that we add the code for <code>$skip</code> before the code for <code>$top</code>.</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 />
@@ -296,7 +299,7 @@ Now we have to populate the <code>Entity
<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>
+With the query option <code>$top</code>, 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>
@@ -329,7 +332,7 @@ With the query option <em>$top</em>, the
<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="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>
@@ -338,14 +341,14 @@ With the query option <em>$top</em>, the
<span class="o">}</span>
<span class="o">}</span>
- <span class="c1">// handle `$skip`</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="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>
@@ -406,21 +409,21 @@ With the query option <em>$top</em>, the
</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>
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$skip=2">http://localhost:8080/DemoService/DemoService.svc/Products?$skip=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>
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$count=true">http://localhost:8080/DemoService/DemoService.svc/Products?$count=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 />
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$skip=1&$top=1">http://localhost:8080/DemoService/DemoService.svc/Products?$skip=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&$skip=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>
+<a href="http://localhost:8080/DemoService/DemoService.svc/Products?$skip=1&$top=1&$count=true">http://localhost:8080/DemoService/DemoService.svc/Products?$skip=1&$top=1&$count=true</a></p>
</li>
</ul>
<hr />
@@ -436,9 +439,9 @@ More system query options will be treate
<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>
+<li>Tutorial OData V4 service, part 5.1: <a href="/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html">System Query Options $top, $skip, $count (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 $select, $expand</li>
+<li>Tutorial OData V4 service, part 5.3: System Query Options $orderby, $filter (to be announced)</li>
</ul>
<h3 id="further-reading">Further reading<a class="headerlink" href="#further-reading" title="Permanent link">¶</a></h3>
<ul>