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/04 12:34:31 UTC
svn commit: r960747 - in /websites/staging/olingo/trunk/content: ./
doc/odata4/tutorials/read/tutorial_read.html
Author: buildbot
Date: Tue Aug 4 10:34:31 2015
New Revision: 960747
Log:
Staging update by buildbot for olingo
Modified:
websites/staging/olingo/trunk/content/ (props changed)
websites/staging/olingo/trunk/content/doc/odata4/tutorials/read/tutorial_read.html
Propchange: websites/staging/olingo/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Aug 4 10:34:31 2015
@@ -1 +1 @@
-1694019
+1694021
Modified: websites/staging/olingo/trunk/content/doc/odata4/tutorials/read/tutorial_read.html
==============================================================================
--- websites/staging/olingo/trunk/content/doc/odata4/tutorials/read/tutorial_read.html (original)
+++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/read/tutorial_read.html Tue Aug 4 10:34:31 2015
@@ -108,7 +108,7 @@ For example, only READ scenario is cover
<p>The OData service that we are create will implement the following model:</p>
<p><img alt="datamodel" src="model1.png" title="The OData model" /></p>
<p>The service will display a list of products and a few properties that describe each product.
-This data model will be enhanced in the subsequent tutorials in order to display Categories and to support navigation from a product to its Category.</p>
+This data model will be enhanced in the subsequent tutorials in order to display categories and to support navigation from a product to its category.</p>
<p><strong>Goal</strong></p>
<p>We will be dealing with 3 java classes and the web.xml descriptor file.
Furthermore, for building with Maven, we will edit the <code>pom.xml</code> file.</p>
@@ -196,12 +196,11 @@ Furthermore, using Maven is convenient f
The description within this section is based on an Eclipse installation that contains the Maven integration.</p>
<p><strong>Create Project using the maven archetype âwebappâ</strong></p>
<p>Within Eclipse, open the Maven Project wizard via
-<em>File -> New -> other -> Maven -> Maven Project</em></p>
+<em>File -> New -> Other -> Maven -> Maven Project</em></p>
<p>On the second wizard page, choose the archetype: maven-archetype-webapp</p>
<p><img alt="mavenArchetype" src="mavenArchetype.png" title="The Maven Archetype" /></p>
<p>On the next page, enter the following information: </p>
<ul>
-<li>Project Name: <em>DemoService</em></li>
<li>Groupd Id: <em>my.group.id</em></li>
<li>Artifact Id: <em>DemoService</em></li>
<li>Version: <em>0.0.1</em></li>
@@ -316,14 +315,14 @@ From context menu on project node, choos
<p>The following section will guide you through every step in detail.</p>
<h2 id="41-declare-the-metadata">4.1. Declare the metadata<a class="headerlink" href="#41-declare-the-metadata" title="Permanent link">¶</a></h2>
<h3 id="411-background">4.1.1. Background<a class="headerlink" href="#411-background" title="Permanent link">¶</a></h3>
-<p>According to the OData specification, an OData service has to declare its structure in the so-called <em>metadata document</em>.
+<p>According to the OData specification, an OData service has to declare its structure in the so-called <em>Metadata Document</em>.
This document defines the contract, such that the user of the service knows which requests can be executed, the structure of the result and how the service can be navigated.</p>
-<p>The metadata document can be invoked via the following URI:</p>
+<p>The Metadata Document can be invoked via the following URI:</p>
<div class="codehilite"><pre><span class="nt"><serviceroot></span>/$metadata
</pre></div>
-<p>Furthermore, OData specifies the usage of the so-called service document
+<p>Furthermore, OData specifies the usage of the so-called Service Document
Here, the user can see which Entity Collections are offered by an OData service.</p>
<p>The service document can be invoked via the following URI:</p>
<div class="codehilite"><pre><span class="nt"><serviceroot></span>/
@@ -331,13 +330,13 @@ Here, the user can see which Entity Coll
<p>The information that is given by these 2 URIs, has to be implemented in the service code.
-Olingo provides API for it and we will use it in the implementation of our <em>CsdlEdmProvider</em>.</p>
+Olingo provides an API for it and we will use it in the implementation of our <em>CsdlEdmProvider</em>.</p>
<h3 id="412-create-class">4.1.2. Create class<a class="headerlink" href="#412-create-class" title="Permanent link">¶</a></h3>
<p>Create package <em>myservice.mynamespace.service</em><br />
Create class <em>DemoEdmProvider</em> and specify the superclass <em>org.apache.olingo.commons.api.edm.provider.CsdlAbstractEdmProvider</em></p>
<p>Note: <strong>edm</strong> is the abbreviation for <strong>Entity Data Model</strong>.<br />
Accordingly, we understand that the <em>CsdlEdmProvider</em> is supposed to provide static descriptive information.</p>
-<p>The Entity Model of the service can be defined in the EDM Provider. The EDM model basically defines the available EntityTypes and the relation between the entities. An EntityType consists of primitive, complex or navigation properties. The model can be invoked with the metadata document request.</p>
+<p>The Entity Model of the service can be defined in the EDM Provider. The EDM model basically defines the available EntityTypes and the relation between the entities. An EntityType consists of primitive, complex or navigation properties. The model can be invoked with the Metadata Document request.</p>
<p>As we can see, the Olingo server API provides one package that contains interfaces for the description of the metadata:</p>
<p><img alt="edmPackage" src="edmPackage.png" title="The edm package" /></p>
<p>Some of these interfaces are going to be used in the following sections.
@@ -346,7 +345,7 @@ You can find the Javadoc here: <a href="
<h3 id="413-implement-the-required-methods">4.1.3. Implement the required methods<a class="headerlink" href="#413-implement-the-required-methods" title="Permanent link">¶</a></h3>
<p>The base class <em>CsdlAbstractEdmProvider</em> provides methods for declaring the metadata of all OData elements.</p>
<p>For example:
-<em> The entries that are displayed in the service document are provided by the method
+<em> The entries that are displayed in the Service Document are provided by the method
</em>getEntityContainerInfo()<em>
</em> The structure of EntityTypes is declared in the method <em>getEntityType()</em></p>
<p>In our simple example, we implement the minimum amount of methods, required to run a meaningful OData service.<br />
@@ -497,25 +496,23 @@ Then our elements are added to the Schem
<p><strong><em>getEntityContainerInfo()</em></strong></p>
-<div class="codehilite"><pre><span class="kd">public</span> <span class="n">CsdlEntityContainer</span> <span class="nf">getEntityContainer</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">ODataException</span> <span class="o">{</span>
-
- <span class="c1">// create EntitySets</span>
- <span class="n">List</span><span class="o"><</span><span class="n">CsdlEntitySet</span><span class="o">></span> <span class="n">entitySets</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o"><</span><span class="n">CsdlEntitySet</span><span class="o">>();</span>
- <span class="n">entitySets</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">getEntitySet</span><span class="o">(</span><span class="n">CONTAINER</span><span class="o">,</span> <span class="n">ES_PRODUCTS_NAME</span><span class="o">));</span>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="n">CsdlEntityContainerInfo</span> <span class="nf">getEntityContainerInfo</span><span class="o">(</span><span class="n">FullQualifiedName</span> <span class="n">entityContainerName</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">ODataException</span> <span class="o">{</span>
- <span class="c1">// create EntityContainer</span>
- <span class="n">CsdlEntityContainer</span> <span class="n">entityContainer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CsdlEntityContainer</span><span class="o">();</span>
- <span class="n">entityContainer</span><span class="o">.</span><span class="na">setName</span><span class="o">(</span><span class="n">CONTAINER_NAME</span><span class="o">);</span>
- <span class="n">entityContainer</span><span class="o">.</span><span class="na">setEntitySets</span><span class="o">(</span><span class="n">entitySets</span><span class="o">);</span>
+ <span class="c1">// This method is invoked when displaying the Service Document at e.g. http://localhost:8080/DemoService/DemoService.svc</span>
+ <span class="k">if</span> <span class="o">(</span><span class="n">entityContainerName</span> <span class="o">==</span> <span class="kc">null</span> <span class="o">||</span> <span class="n">entityContainerName</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">CONTAINER</span><span class="o">))</span> <span class="o">{</span>
+ <span class="n">CsdlEntityContainerInfo</span> <span class="n">entityContainerInfo</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CsdlEntityContainerInfo</span><span class="o">();</span>
+ <span class="n">entityContainerInfo</span><span class="o">.</span><span class="na">setContainerName</span><span class="o">(</span><span class="n">CONTAINER</span><span class="o">);</span>
+ <span class="k">return</span> <span class="n">entityContainerInfo</span><span class="o">;</span>
+ <span class="o">}</span>
- <span class="k">return</span> <span class="n">entityContainer</span><span class="o">;</span>
+ <span class="k">return</span> <span class="kc">null</span><span class="o">;</span>
<span class="o">}</span>
</pre></div>
<p><strong>Summary:</strong><br />
We have created a class that declares the metadata of our OData service.
-We have declared the main elements of an OData service: <em>EntityType</em>, <em>EntitySet</em>, <em>EntityContainer</em> and <em>Schema</em> (with us of the according Olingo classes <code>CsdlEntityType</code>, <code>CsdlEntitySet</code>, <code>CsdlEntityContainer</code> and <code>CsdlSchema</code>).</p>
+We have declared the main elements of an OData service: <em>EntityType</em>, <em>EntitySet</em>, <em>EntityContainer</em> and <em>Schema</em> (with the corresponding Olingo classes <code>CsdlEntityType</code>, <code>CsdlEntitySet</code>, <code>CsdlEntityContainer</code> and <code>CsdlSchema</code>).</p>
<p>At runtime of an OData service, such metadata can be viewed by invoking the Metadata Document.</p>
<p>In our example invokation of the URL: <a href="http://localhost:8080/DemoService/DemoService.svc/$metadata">http://localhost:8080/DemoService/DemoService.svc/$metadata</a></p>
<p>Give us the result below:</p>
@@ -541,9 +538,9 @@ We have declared the main elements of an
<p>The Service Document can be invoked to view the Entity Sets, like in our example at the URL: <a href="http://localhost:8080/DemoService/DemoService.svc/">http://localhost:8080/DemoService/DemoService.svc/</a></p>
-<p>Which give us the service document as result:</p>
+<p>Which give us the Service Document as result:</p>
<div class="codehilite"><pre><span class="p">{</span>
- <span class="nt">"@odata.context"</span> <span class="p">:</span> <span class="s2">"http://localhost:8080/DemoService/DemoService.svc/$metadata"</span><span class="p">,</span>
+ <span class="nt">"@odata.context"</span> <span class="p">:</span> <span class="s2">"$metadata"</span><span class="p">,</span>
<span class="nt">"value"</span> <span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">"name"</span> <span class="p">:</span> <span class="s2">"Products"</span><span class="p">,</span>
@@ -555,7 +552,7 @@ We have declared the main elements of an
<blockquote>
<p>Note:<br />
-After implementing the <em>EdmProvider</em>, we can, as an intermediate step, build/deploy the service and invoke the 2 static pages: service document and metadata document.<br />
+After implementing the <em>EdmProvider</em>, we can, as an intermediate step, build/deploy the service and invoke the 2 static pages: Service Document and Metadata Document.<br />
If desired, you can proceed with implementing the required steps for web application as described in
4.3. and run the application as described in chapter 5.</p>
</blockquote>
@@ -569,7 +566,7 @@ Providing the list of products is the ta
<li>Check the URI<br />
We need to identify the requested resource and have to consider Query Options (if available)</li>
<li>Provide the data<br />
- Based on the URI info, we have to obtain the data from our data store (can be e.g. a Database)</li>
+ Based on the URI info, we have to obtain the data from our data store (can be e.g. a database)</li>
<li>Serialize the data<br />
The data has to be transformed into the required format</li>
<li>Configure the response<br />
@@ -581,12 +578,12 @@ Providing the list of products is the ta
<em>Olingo</em> provides API for processing different kind of service requests:<br />
Such a service request can ask for a list of entities, or for one entity, or one property.</p>
<p>Example:<br />
-In our example, we have stated in our metadata document that We will provide a list of âproductsâ whenever the <em>EntitySet</em> with name âProductsâ is invoked.<br />
+In our example, we have stated in our Metadata Document that we will provide a list of âproductsâ whenever the <em>EntitySet</em> with name âProductsâ is invoked.<br />
This means that the user of our OData service will append the <em>EntitySet</em> name to the root URL of the service and then invoke the full URL.<br />
This is http://localhost:8080/DemoService/DemoServlet1.svc/Products
So, whenever this URL is fired, Olingo will invoke the <code>EntityCollectionProcessor</code> implementation of our OData service.
Then our <code>EntityCollectionProcessor</code> implementation is expected to provide a list of products.</p>
-<p>As we have already mentioned, the metadata document is the contract for providing data.
+<p>As we have already mentioned, the Metadata Document is the contract for providing data.
This means that when it comes to provide the actual data, we have to do it according to the specified metadata.<br />
For example, the property names have to match, also the types of the properties, and, if specified, the length of the strings, etc</p>
<h3 id="422-create-class">4.2.2. Create class<a class="headerlink" href="#422-create-class" title="Permanent link">¶</a></h3>
@@ -608,12 +605,14 @@ According to the Javadoc, this object is
We will need it later, so we store it as member variable.</p>
<div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">init</span><span class="o">(</span><span class="n">OData</span> <span class="n">odata</span><span class="o">,</span> <span class="n">ServiceMetadata</span> <span class="n">serviceMetadata</span><span class="o">)</span> <span class="o">{</span>
<span class="k">this</span><span class="o">.</span><span class="na">odata</span> <span class="o">=</span> <span class="n">odata</span><span class="o">;</span>
+ <span class="k">this</span><span class="o">.</span><span class="na">serviceMetadata</span> <span class="o">=</span> <span class="n">serviceMetadata</span><span class="o">;</span>
<span class="o">}</span>
</pre></div>
-<p>Donât forget to declare the member variable</p>
+<p>Donât forget to declare the member variables</p>
<div class="codehilite"><pre><span class="kd">private</span> <span class="n">OData</span> <span class="n">odata</span><span class="o">;</span>
+<span class="kd">private</span> <span class="n">ServiceMetadata</span> <span class="n">serviceMetadata</span><span class="o">;</span>
</pre></div>
@@ -655,7 +654,7 @@ Because the <code>readEntityCollection(.
Usually, an OData service provides different <em>EntitySets</em>, so first it is required to identify which <em>EntitySet</em> has been requested. This information can be retrieved from the <em>uriInfo</em> object.</p>
</li>
<li>
-<p>Fetch the data
+<p>Fetch the data <br />
As a developer of the OData service, you have to know how and where the data is stored. In many cases, this would be a database. At this point, you would connect to your database and fetch the requested data with an appropriate SQL statement. The data that is fetched from the data storage has to be put into an <em>EntityCollection</em> object.
The package <code>org.apache.olingo.commons.api.data</code> provides interfaces that describe the actual data, not the metadata.</p>
<p><img alt="datapackage" src="datapackage.png" title="The package containing the interfaces for handling runtime data" /></p>
@@ -825,16 +824,16 @@ We ignore it. Instead, we open our OData
<p>Note:
If you face problems related to the server, it helps to restart your Eclipse IDE.</p>
</blockquote>
-<h3 id="the-service-urls">The service-URLs<a class="headerlink" href="#the-service-urls" title="Permanent link">¶</a></h3>
+<h3 id="the-service-urls">The Service URLs<a class="headerlink" href="#the-service-urls" title="Permanent link">¶</a></h3>
<p>Try the following URLs:</p>
<p><strong>Service Document</strong></p>
<div class="codehilite"><pre>http://localhost:8080/DemoService/DemoService.svc/
</pre></div>
-<p>The expected result is the service document which displays our <em>EntityContainerInfo</em>:</p>
+<p>The expected result is the Service Document which displays our <em>EntityContainerInfo</em>:</p>
<div class="codehilite"><pre><span class="p">{</span>
- <span class="nt">"@odata.context"</span> <span class="p">:</span> <span class="s2">"http://localhost:8080/DemoService/DemoService.svc/$metadata"</span><span class="p">,</span>
+ <span class="nt">"@odata.context"</span> <span class="p">:</span> <span class="s2">"$metadata"</span><span class="p">,</span>
<span class="nt">"value"</span> <span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">"name"</span> <span class="p">:</span> <span class="s2">"Products"</span><span class="p">,</span>
@@ -849,7 +848,7 @@ If you face problems related to the serv
</pre></div>
-<p>The expected result is the metadata document that displays our <em>Schema</em>, <em>EntityType</em>, <em>EntityContainer</em> and <em>EntitySet</em>.</p>
+<p>The expected result is the Metadata Document that displays our <em>Schema</em>, <em>EntityType</em>, <em>EntityContainer</em> and <em>EntitySet</em>.</p>
<div class="codehilite"><pre><span class="cp"><?xml version='1.0' encoding='UTF-8'?></span>
<span class="nt"><edmx:Edmx</span> <span class="na">Version=</span><span class="s">"4.0"</span> <span class="na">xmlns:edmx=</span><span class="s">"http://docs.oasis-open.org/odata/ns/edmx"</span><span class="nt">></span>
<span class="nt"><edmx:DataServices></span>
@@ -902,7 +901,7 @@ If you face problems related to the serv
<hr />
<h1 id="6-summary">6. Summary<a class="headerlink" href="#6-summary" title="Permanent link">¶</a></h1>
<p>Finally, we have created our first OData service based on the V4 version of the OData specification and using the V4 server library provided by <em>Olingo</em>.<br />
-Our first OData service is very simple; it only allows invoking one entity collection, apart from the service document and the metadata document.</p>
+Our first OData service is very simple; it only allows invoking one entity collection, apart from the Service Document and the Metadata Document.</p>
<p>The project as final result can be download <a href="http://www.apache.org/dyn/closer.cgi/olingo/odata4/Tutorials/DemoService_Tutorial_Read.zip">here</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>).</p>
<h1 id="links">Links<a class="headerlink" href="#links" title="Permanent link">¶</a></h1>
<h3 id="tutorials">Tutorials<a class="headerlink" href="#tutorials" title="Permanent link">¶</a></h3>