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/13 13:45:30 UTC

svn commit: r1695682 - in /olingo/site/trunk/content/doc/odata4/tutorials: sqo_es/tutorial_sqo_es.mdtext sqo_tcs/tutorial_sqo_tcs.mdtext

Author: mibo
Date: Thu Aug 13 11:45:30 2015
New Revision: 1695682

URL: http://svn.apache.org/r1695682
Log:
Fixed formatting issues

Modified:
    olingo/site/trunk/content/doc/odata4/tutorials/sqo_es/tutorial_sqo_es.mdtext
    olingo/site/trunk/content/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.mdtext

Modified: olingo/site/trunk/content/doc/odata4/tutorials/sqo_es/tutorial_sqo_es.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/sqo_es/tutorial_sqo_es.mdtext?rev=1695682&r1=1695681&r2=1695682&view=diff
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/sqo_es/tutorial_sqo_es.mdtext (original)
+++ olingo/site/trunk/content/doc/odata4/tutorials/sqo_es/tutorial_sqo_es.mdtext Thu Aug 13 11:45:30 2015
@@ -27,7 +27,7 @@ After we have learned the rather simple
 
 
 **Note:**  
-The full implementation of the OData service as described in the present tutorial can be found in the [attached zip file](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_Navigation.zip) that contains an Eclipse project that can be imported into your Eclipse workspace.
+The full implementation of the OData service as described in the present tutorial can be found in the [attached zip file](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.asc)) that contains an Eclipse project that can be imported into your Eclipse workspace.
 
 
 **Disclaimer:**  
@@ -68,7 +68,7 @@ ___
 # 3. Implementation
 
 Open the class `myservice.mynamespace.service.DemoEntityProcessor`  
-The method `readEntity()` contains the code for navigation which was treated in Tutorial Part 4. In the current tutorial we want to focus on query options and to keep the code as simple as possible, we delete the code of the `readEntity()` method and start from scratch.
+The method `readEntity()` contains the code for navigation which was treated in Tutorial Part 4. In the current tutorial we want to focus on query options and to keep the code as simple as possible, therefore we delete the code of the `readEntity()` method and start from scratch.
 
 ## 3.1. Implement `$select`
 
@@ -82,7 +82,7 @@ This parameter can be specified in the f
   * Specify a comma-separated list of properties: `$select=Name,Description`
   * Specify a star to include all properties: `$select=*`
 
-**Example**
+**Example**  
 First, just to remember how the full payload looks like, the “normal” query of the product without query options:  
 <http://localhost:8080/DemoService/DemoService.svc/Products>
 
@@ -199,29 +199,26 @@ In this tutorial we use the simple imple
 
 
 
-## 3.2. Implement $expand
+## 3.2. Implement `$expand`
 
 **Background**
 
-In order to understand the $expand system query option, let’s first quickly recap what we’ve learned in the navigation-tutorial:
+In order to understand the `$expand` system query option, let’s first quickly recap what we’ve learned in the navigation-tutorial:
 
   1. In order to be able to navigate from one entity to another entity, we need at least 2 EntityTypes and at least one NavigationProperty
+      ![Metadata](metadataNav.jpg "Declaring the navigation in the metadata")
 
-![Metadata](metadataNav.jpg "Declaring the navigation in the metadata")
-
- 1. We can invoke one single entity, e.g. display one product:
-
-![Products(1)SingleRead](responseProducts_1.jpg "The result of a single read")
+  1. We can invoke one single entity, e.g. display one product:
+      ![Products(1)SingleRead](responseProducts_1.jpg "The result of a single read")
 
   1. And we can follow the navigation to the second entity, by appending the navigation property name, e.g. invoke the category of that product.
   As we’ve seen in the metadata above, the name of the navigation property is *Category*
-
-![Products(1)NavToCat](responseProducts_1_navCat.jpg "Navigating from a Product to its Category")
+      ![Products(1)NavToCat](responseProducts_1_navCat.jpg "Navigating from a Product to its Category")
 
 We have executed two requests to our OData service, in order to obtain the data for the product and for its related category.  
 Now, since the category info is so tightly bound to the selected product, we’d like to get the same info by executing only **one** request.
 
-This can be achieved with the $expand  
+This can be achieved with the `$expand`  
 
 The URL is built as follows:  
 
@@ -231,7 +228,7 @@ The URL is built as follows:
   * specify the name of the desired navigation property:  <http://localhost:8080/DemoService/DemoService.svc/Products(1)?$expand=Category>  
 
 As a result, the data of both entities is provided within one payload.  
-The data of the target entity is presented *“inline”*, which means as a child element of the source entity.  
+The data of the target entity is presented *inline*, which means as a child element of the source entity.  
 
 ![Products(1)Expanded](responseProducts_1_expandCat.jpg "The Product with its expanded Category")
 
@@ -253,11 +250,11 @@ In brief, what we have to do is: fetch t
 
 We can distinguish the following steps:  
 
-  1. Retrieve the ExpandOption from Uri  
+  1. Retrieve the ExpandOption from Uri.  
   In our example: `$expand=Category`  
-  2. Retrieve the (target) EdmEntityType which corresponds to the expand
+  2. Retrieve the (target) EdmEntityType which corresponds to the expand.  
   In our example: *Category*  
-  3. Build the response data for the entity, enriched with the data of the expand entity  
+  3. Build the response data for the entity, enriched with the data of the expand entity.  
   In our example: *product1* merged with *category1*  
 
 Let's have a detailed look.
@@ -274,12 +271,11 @@ As usual, if this object is `null`, then
 
 ##### Step 2: Retrieve the EdmEntityType corresponding to the expand
 
-
 In brief: `ExpandOption` -> `NavigationProperty` -> `EdmEntityType`  
 
 From the `ExpandOption`, we can get the ExpandItems.  
 An `ExpandItem` corresponds to the name of the navigation property.  
-So for the URL <http://localhost:8080/DemoService/DemoService.svc/Products?$expand=Category> we get one ExpandItem, which corresponds to the navigation property *Category*.  
+So for the URL <http://localhost:8080/DemoService/DemoService.svc/Products?$expand=Category> we get one `ExpandItem`, which corresponds to the navigation property *Category*.  
 
 In the present tutorial, we’re keeping the implementation as simple as possible.
 So we’re relying on the fact that our example service only contains one navigation property per entity type.
@@ -391,7 +387,7 @@ Also, the `expandOption` has to be consi
                                       .selectList(selectList)
                                       .suffix(Suffix.ENTITY).build();
 
-    // make sure that $expand and $select are considered by the serializer
+    // make sure that `$expand` and $select are considered by the serializer
     // adding the selectOption to the serializerOpts will actually tell the lib to do the job
     EntitySerializerOptions opts = EntitySerializerOptions.with()
                                                           .contextURL(contextUrl)
@@ -403,7 +399,7 @@ Also, the `expandOption` has to be consi
 **Note:**  
 The complete `readEntity(...)` method can be found in the *Appendix* at the end of the site or together with the `readEntityCollection(...)` method in the [sample project zip](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.asc)).
 
-## 3.3. Implement $expand with options
+## 3.3. Implement `$expand` with options
 
 **Background**
 
@@ -436,7 +432,7 @@ The procedure is:
   * Get the data for the navigation property (the normal expand)  
   * Refine the result by applying the system query options  
 
-**Support for `$select` with `$expand`**
+**Support for `$select` with `$expand`**  
 Like described in section 3.1, the Olingo library provides support and convenience methods for `$select` implementation. So the necessary creation and pass of the `selectList` to the creation of `ContextURL` and pass of the `selectOptions` to the `EntitySerializerOptions` is already done (see also code sample in the final step in section 3.2).  
 
 ---
@@ -459,19 +455,19 @@ After building and deploying your servic
     * <http://localhost:8080/DemoService/DemoService.svc/Products(1)?$expand=Category>
     * <http://localhost:8080/DemoService/DemoService.svc/Products(1)?$expand=Category>
     * <http://localhost:8080/DemoService/DemoService.svc/Categories(1)?$expand=Products>
-      **NOTE:** In current `4.0.0-beta-03` version of Olingo is a minor bug which prevents the expand of a navigation which has the same name as an EntitySet (see [OLINGO-741](https://issues.apache.org/jira/browse/OLINGO-741)).
-      Hence above link will work with latest SNAPSHOT version or the final `4.0.0` release.
+        **NOTE:** In current `4.0.0-beta-03` version of Olingo is a minor bug which prevents the expand of a navigation which has the same name as an EntitySet (see [OLINGO-741](https://issues.apache.org/jira/browse/OLINGO-741)).
+        Hence above link will work with latest SNAPSHOT version or the final `4.0.0` release.
     * <http://localhost:8080/DemoService/DemoService.svc/Categories(1)?$expand=*>
 
-  * Using `$select` and $expand  
+  * Using `$select` and `$expand`  
     * <http://localhost:8080/DemoService/DemoService.svc/Products(1)?$select=Name&$expand=Category>  
 
-  * Using $expand with nested `$select`  
+  * Using `$expand` with nested `$select`  
   We’re interested in *Product* and the name of its *Category*
     * <http://localhost:8080/DemoService/DemoService.svc/Products(1)?$expand=Category($select=Name)>
     * <http://localhost:8080/DemoService/DemoService.svc/Products(1)?$expand=Category($select=Name,ID)>
 
-  * Using `$select` and $expand with nested $select  
+  * Using `$select` and `$expand` with nested $select  
   We’re interested in *Product* and its *Category*, but only the *name* of both  
     * <http://localhost:8080/DemoService/DemoService.svc/Products(1)?$select=Name&$expand=Category($select=Name)>
 
@@ -495,7 +491,7 @@ In this tutorial we have learned the bas
   * 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](/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](/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 (this page)](/doc/odata4/tutorials/sqo_es/tutorial_sqo_es.html) | [sample project zip](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.asc))  
+  * Tutorial OData V4 service, part 5.2: [System Query Options $select, $expand (this page)](/doc/odata4/tutorials/sqo_es/tutorial_sqo_es.html) | [sample project zip](http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip) ([md5](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.md5), [sha512](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.sha512), [pgp](https://dist.apache.org/repos/dist/release/olingo/odata4/Tutorials/DemoService_Tutorial_sqo_es.zip.asc))  
   * Tutorial OData V4 service, part 5.3: System Query Options $orderby, $filter (to be announced)
 
 ### Further reading

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=1695682&r1=1695681&r2=1695682&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 Thu Aug 13 11:45:30 2015
@@ -63,18 +63,18 @@ The following URL provides only the firs
 ![ProductsWith$top](responseTop2.jpg "The first 2 entries of the list of Products")
 
 The following request returns the products starting with the 3rd and ignores the first 2 entries:
-<http://localhost:8080/DemoService/DemoService.svc/Products?`$skip`=2>
+<http://localhost:8080/DemoService/DemoService.svc/Products?$skip=2>
 
 ![ProductsWith`$skip`](responseSkip2.jpg "Skipping the first 2 entries of the list of Products")
 
 The following request returns the total number of products and includes it in the payload:  
-<http://localhost:8080/DemoService/DemoService.svc/Products?`$count`=true>
+<http://localhost:8080/DemoService/DemoService.svc/Products?$count=true>
 
 ![ProductsWith`$count`](responseCount.jpg "The full list of Products with the count added in the payload")
 
 
 **Note:**  
-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.
+The full implementation of the OData service as described in the present tutorial can be found in the [attached 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)) that contains an Eclipse project that can be imported into your Eclipse workspace.
 
 **Disclaimer:**  
 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.
@@ -114,7 +114,7 @@ ___
 
 # 3. Implementing system query options
 
-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)
+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)
 
 Therefore our implementation for all three query options is done in the class  
 `myservice.mynamespace.service.DemoEntityCollectionProcessor`
@@ -233,7 +233,7 @@ With the query option `$skip`, the user
 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 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.”  
+> “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`.
 
@@ -389,7 +389,7 @@ After building and deploying your servic
   * Add the full number of all products to the response payload  
   <http://localhost:8080/DemoService/DemoService.svc/Products?$count=true>
 
-  * Combine $top and `$skip`
+  * 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>  
   Regardless of the order, the result should be the same