You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@olingo.apache.org by mi...@apache.org on 2015/08/05 14:59:59 UTC
svn commit: r1694203 -
/olingo/site/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.mdtext
Author: mibo
Date: Wed Aug 5 12:59:59 2015
New Revision: 1694203
URL: http://svn.apache.org/r1694203
Log:
Minor changes
Modified:
olingo/site/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.mdtext
Modified: olingo/site/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.mdtext?rev=1694203&r1=1694202&r2=1694203&view=diff
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.mdtext (original)
+++ olingo/site/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.mdtext Wed Aug 5 12:59:59 2015
@@ -1,6 +1,6 @@
# How to build an OData Service with Olingo V4
-# Part 5.1: System Query Options $top, `$skip`, `$count`
+# Part 5.1: System Query Options `$top`, `$skip`, `$count`
## Introduction
@@ -11,10 +11,12 @@ The [OData V4 specification document](ht
> â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.â
-Query options are not part of the resource path, theyâre appended to the URL after the â?â
+Query options are not part of the resource path, theyâre appended to the URL after the `?`.
+As an example the URL <http://localhost:8080/my/page?example=true> has *example* as *query option* with the value *true*.
-For example:
-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 `$orderby`.
+As an example for a system query option in Odata:
+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 `$orderby`.
Examples for system query options that are commonly used:
@@ -26,7 +28,7 @@ Examples for system query options that a
* `$filter`
* `$expand`
-The present tutorial focuses on the first 3 query options: `$top`, `$skip` and `$count`
+The present tutorial focuses on the first three query options: `$top`, `$skip` and `$count`
**Examples**
@@ -181,7 +183,7 @@ And this is the sample code:
}
-Note:
+**Note:**
We donât need to check if the value of the `$count` is incorrect (e.g. `$count=xxx`), as this is handled by the _Olingo OData V4_ library.
One additional step has to be considered:
@@ -211,11 +213,10 @@ Furthermore, we have to change the follo
With the query option `$skip`, the user of an OData service can specify the number of entries that should be ignored at the beginning of a collection.
So if a user specifies `$skip=n` then our OData service has to return the list of entries starting at position n+1
-One important rule that we have to consider is described by the OData specification:
-âWhere $top and `$skip` are used together, `$skip` MUST be applied before $top, regardless of the order in which they appear in the request.â
-See [here](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398306)
+One important rule that we have to consider is described by the [OData V4 specification](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398306):
+> âWhere $top and `$skip` are used together, `$skip` MUST be applied before $top, regardless of the order in which they appear in the request.â
-This means for us that we add the code for `$skip` before the code for _$top_.
+This means for us that we add the code for `$skip` before the code for `$top`.
**Implementation**
@@ -252,7 +253,7 @@ Now we have to populate the `EntityColle
## 3.3. Implement $top
**Background**
-With the query option _$top_, the user of an OData service can specify the maximum number of entries that should be returned, starting from the beginning.
+With the query option `$top`, the user of an OData service can specify the maximum number of entries that should be returned, starting from the beginning.
**Implementation**
@@ -290,7 +291,7 @@ So now we can finally have a look at the
List<Entity> entityList = entityCollection.getEntities();
EntityCollection returnEntityCollection = new EntityCollection();
- // handle `$count`: return the original number of entities, ignore $top and `$skip`
+ // handle $count: return the original number of entities, ignore $top and $skip
CountOption countOption = uriInfo.getCountOption();
if (countOption != null) {
boolean isCount = countOption.getValue();
@@ -299,14 +300,14 @@ So now we can finally have a look at the
}
}
- // handle `$skip`
+ // handle $skip
SkipOption skipOption = uriInfo.getSkipOption();
if (skipOption != null) {
int skipNumber = skipOption.getValue();
if(skipNumber >= 0 && skipNumber <= entityList.size()){
entityList = entityList.subList(skipNumber, entityList.size());
}else{
- throw new ODataApplicationException("Invalid value for `$skip`",
+ throw new ODataApplicationException("Invalid value for $skip",
HttpStatusCode.BAD_REQUEST.getStatusCode(),Locale.ROOT);
}
}
@@ -364,18 +365,18 @@ After building and deploying your servic
<http://localhost:8080/DemoService/DemoService.svc/Products?$top=2>
* Exclude the first 2 products
-<http://localhost:8080/DemoService/DemoService.svc/Products?`$skip`=2>
+<http://localhost:8080/DemoService/DemoService.svc/Products?$skip=2>
* Add the full number of all products to the response payload
-<http://localhost:8080/DemoService/DemoService.svc/Products?`$count`=true>
+<http://localhost:8080/DemoService/DemoService.svc/Products?$count=true>
* Combine $top and `$skip`
-<http://localhost:8080/DemoService/DemoService.svc/Products?`$skip`=1&$top=1>
-<http://localhost:8080/DemoService/DemoService.svc/Products?$top=1&`$skip`=1>
+<http://localhost:8080/DemoService/DemoService.svc/Products?$skip=1&$top=1>
+<http://localhost:8080/DemoService/DemoService.svc/Products?$top=1&$skip=1>
Regardless of the order, the result should be the same
* Combine all 3 query options
-<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>
---
@@ -393,9 +394,9 @@ More system query options will be treate
* Tutorial OData V4 service part 2: [Read Entity, Read Property](/doc/odata4/tutorials/readep/tutorial_readep.html) | [sample project zip](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_ReadEp.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_ReadEp.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_ReadEp.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_ReadEp.zip.asc))
* Tutorial OData V4 service part 3: [Write (Create, Update, Delete Entity)](/doc/odata4/tutorials/write/tutorial_write.html) | [sample project zip](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_Write.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Write.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Write.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Write.zip.asc))
* Tutorial OData V4 service, part 4: [Navigation (this page)](/doc/odata4/tutorials/navigation/tutorial_navigation.html) | [sample project zip](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip.asc))
- * Tutorial OData V4 service, part 5.1: [System Query Options $top, `$skip`, `$count` (this page)](/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html) | [sample project zip](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.asc))
- * Tutorial OData V4 service, part 5.2: System Query Options `$select`, `$expand`
- * Tutorial OData V4 service, part 5.3: System Query Options `$orderby`, `$filter` (to be announced)
+ * Tutorial OData V4 service, part 5.1: [System Query Options $top, $skip, $count (this page)](/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html) | [sample project zip](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_tcs.zip.asc))
+ * Tutorial OData V4 service, part 5.2: System Query Options $select, $expand
+ * Tutorial OData V4 service, part 5.3: System Query Options $orderby, $filter (to be announced)
### Further reading
* OData specification: [http://odata.org/](http://odata.org/)