Author: mibo
Date: Tue May 5 12:49:23 2015
New Revision: 1677809
URL: http://svn.apache.org/r1677809
Log:
CMS commit to olingo by mibo
Modified:
olingo/site/trunk/content/doc/odata4/tutorials/read/tutorial_read.mdtext
Modified:
olingo/site/trunk/content/doc/odata4/tutorials/read/tutorial_read.mdtext
URL:
http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/read/tutorial_read.mdtext?rev=1677809&r1=1677808&r2=1677809&view=diff
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/read/tutorial_read.mdtext
(original)
+++ olingo/site/trunk/content/doc/odata4/tutorials/read/tutorial_read.mdtext
Tue May 5 12:49:23 2015
@@ -22,12 +22,12 @@ This tutorial guides you through the ste
We will create a Web Application and deploy it on a local Tomcat server.
Afterwards, the OData service can be invoked from a browser and it will
provide the data according to the OData V4 specification.
-This tutorial is kept as minimalistic as possible, in order to fully
concentrate on the implementation of the service.
+This tutorial is kept as simple as possible, in order to fully concentrate on
the implementation of the service.
For example, only READ scenario is covered in this tutorial, whereas creation,
modification and deletion will be covered in the subsequent tutorial.
**Scenario**
-The OData service that weâre going to create will implement the following
model:
+The OData service that we are create will implement the following model:
@@ -39,20 +39,20 @@ This data model will be enhanced in the
We will be dealing with 3 java classes and the web.xml descriptor file.
-Furthermore, for building with maven, weâll edit the pom.xml file.
+Furthermore, for building with maven, we will edit the `pom.xml` file.
-This is how our working directory in Eclipse will look like:
+This is how our working directory in Eclipse will look:
-At the end of this tutorial, youâll have written an OData service and
youâll be able to invoke the following URL in a browser:
+At the end of this tutorial, you will have written an OData service and you
will be able to invoke the following URL in a browser:
:::html
http://localhost:8080/DemoService/DemoService.svc/Products
-And the browser will display the following little collection of data:
+And the browser will display the following collection of data:
:::json
{
@@ -83,7 +83,7 @@ And the browser will display the followi
2. Preparation
3. Create Project
* Create Project
- * Edit pom file
+ * Edit `pom.xml` file
* Check build path
* Build the project
4. Implementation - Read scenario to request the EntitySet âProductsâ
@@ -102,7 +102,7 @@ ___
In order to follow this tutorial, you should have
* Basic knowledge about OData and OData V4
-* Knowledge about Java as programming language
+* Knowledge of the Java programming language
* Optional: knowledge about developing web applications
* Optional: knowledge about building with Maven
@@ -110,14 +110,15 @@ ___
# 2. Preparation
-Before starting off with the creation of our OData service, we need to prepare
for the following needs:
+Before starting off with the creation of our OData service, we need to prepare
the following:
+ 1. Installed JDK 1.6 (or higher version)
1. An IDE for writing the Java code
2. A builder to build the .war file, which will be deployed on server
3. A web server to run our web application / OData service
I recommend using Eclipse for all 3 needs, as it is the easiest approach.
-This means, you should install the pre-packed Eclipse distribution called
âEclipse IDE for Java EE developersâ and which can be found here:
http://www.eclipse.org/downloads/
+This means, you should install the pre-packaged Eclipse distribution called
âEclipse IDE for Java EE developersâ which can be found here:
<http://www.eclipse.org/downloads/>
@@ -160,8 +161,8 @@ After finishing the wizard, the next ste
**Edit pom file**
-In our project, weâll be using several libraries, e.g. the Olingo libraries.
-In the pom.xml file, we specify the dependencies and Maven will take care to
download them to our local maven repository.
+In our project, we will be using several libraries, e.g. the Olingo libraries.
+In the pom.xml file, we specify the dependencies and Maven will download them
to our local maven repository.
Furthermore, the *pom.xml* file tells Maven which output we want to have as
result of our build. In our case, this is a war file.
In our example, the pom.xml file looks as follows:
@@ -232,7 +233,7 @@ In order to check the Build path setting
Select the *Source* tab.
-You might see that the source folder *src/main/java* is configured, but marked
with an error marker.
+You might see that the source folder *src/main/java* is configured, but
displays an error marker.
@@ -250,10 +251,10 @@ Since we donât need it for our tuto
**Build the project**
-Although the project doesnât contain any source files yet, letâs perform
our first Maven build, in order to check if there are any problems.
+Although the project doesnât contain any source files yet, letâs perform
our first Maven build, in order to check for any problems.
-From context menu on project node, chose *Run As -> maven build*
-If youâve never executed the build before, Maven asks you to specify at
least one goal.
+From the context menu on the project node, chose *Run As -> maven build*
+If you have never executed the build before, Maven asks you to specify at
least one goal.
Enter the usual goals âclean installâ and press âRunâ
@@ -262,8 +263,7 @@ The log output is provided in the Eclips
You should check it for the output âBuild Successâ
> Note:
-> It might be the case that maven provides an error marker right from the
beginning.
-> In such case it helps to update your Project:
+> If maven provides an error marker right from the beginning,it would help to
update your Project:
> From context menu on project node, choose Maven -> update Project -> <your
> project>
___
@@ -275,7 +275,7 @@ The implementation of an OData service b
* Declaring the metadata of the service
* Handle service requests
-Furthermore, since our example service has to run on a web server, we have to
create some code which allows to call our service in a web application:
+Since our example service has to run on a web server, we have to create some
code which calls our service in a web application:
* Web application implementation
@@ -304,7 +304,7 @@ The service document can be invoked via
<serviceroot>/
The information that is given by these 2 URIs, has to be implemented in the
service code.
-Olingo provides API for it and weâll use it in the implementation of our
*EdmProvider.*
+Olingo provides API for it and we will use it in the implementation of our
*EdmProvider.*
### 4.1.2. Create class
@@ -355,9 +355,9 @@ Select the mentioned methods and press O
-Letâs have a closer look at the methods in detail.
+Letâs have a closer look at our methods in detail.
-First, we need to declare some constants, to be used in below code
+First, we need to declare some constants, to be used in the code below:
:::java
// Service Namespace
@@ -379,7 +379,7 @@ First, we need to declare some constants
**_getEntityType()_**
In our example service, we want to provide a list of products to users who
call the OData service.
-The user of our service, for example an app-developer, will ask himself: how
does such a "product" entry look like? How is it structured? Which information
about a product is provided? For example, the name of it? And which data types
can be expected from these properties?
+The user of our service, for example an app-developer, may ask: What does such
a "product" entry look like? How is it structured? Which information about a
product is provided? For example, the name of it and which data types can be
expected from these properties?
Such information is provided by the _EdmProvider_.
In our example service, for modelling the _EntityType_, we have to provide the
following metadata:
@@ -422,12 +422,12 @@ Which of the properties is the âkey
The procedure for declaring the _EntitySets_ is similar.
An _EntitySet_ is a crucial resource, when an OData service is used to request
data.
-In our example, weâll invoke the following URL, which we expect to provide
us a list of products:
+In our example, we will invoke the following URL, which we expect to provide
us a list of products:
:::html
http://localhost:8080/DemoService/DemoServlet.svc/Products
-When declaring an _EntitySet_, we need to define the type of entries which are
contained in the list. Such type is an _EntityType_.
+When declaring an _EntitySet_, we need to define the type of entries which are
contained in the list, such as an _EntityType_.
In our example, we set our previously created _EntityType_, which is referred
by a _FullQualifiedName_.
:::java
@@ -474,8 +474,8 @@ In our example, we have only one _Entity
**_getSchemas()_**
-Up to this point, we have declared the type of our data (_EntityType_) and our
list (_EntitySet_), and weâve put it into a container (_EntityContainer_).
-Now weâre required to put all these elements into a _Schema_.
+Up to this point, we have declared the type of our data (_EntityType_) and our
list (_EntitySet_), and we have put it into a container (_EntityContainer_).
+Now we are required to put all these elements into a _Schema_.
While the model of an OData service can have several schemas, in most cases
there will probably be only one schema.
So, in our example, we create a list of schemas, where we add one new _Schema_
object.
The schema is configured with a _Namespace_, which serves to uniquely identify
all elements.
@@ -530,13 +530,9 @@ We have declared the main elements of an
At runtime of an OData service, such metadata can be viewed by invoking the
Metadata Document.
-In our example invoke the URL:
+In our example invokation of the URL:
<http://localhost:8080/DemoService/DemoService.svc/$metadata>
- :::xml
- http://localhost:8080/DemoService/DemoService.svc/$metadata
-
-
-Give us this result:
+Give us the result below:
:::xml
<?xml version='1.0' encoding='UTF-8'?>
@@ -559,12 +555,9 @@ Give us this result:
</edmx:Edmx>
-The Service Document can be invoked to view the Entity Sets, like in our
example at
-
- :::html
- http://localhost:8080/DemoService/DemoService.svc/
+The Service Document can be invoked to view the Entity Sets, like in our
example at the URL: <http://localhost:8080/DemoService/DemoService.svc/>
-with give us this result:
+Which give us the service document as result:
:::json
{
@@ -580,7 +573,7 @@ with give us this result:
> Note:
> After implementing the _EdmProvider_, we can, as an intermediate step,
> build/deploy the service and invoke the 2 static pages: service document
> and metadata document.
> 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
+4.3. and run the application as described in chapter 5.
## 4.2. Provide the data
@@ -598,7 +591,7 @@ The work that we have to do in this chap
3. Serialize the data
The data has to be transformed into the required format
4. Configure the response
- Since weâre implementing a âprocessorâ, the last step is to provide
the response object
+ Since we are implementing a âprocessorâ, the last step is to provide
the response object
These 4 steps will be considered in the implementation of the
_readEntityCollection()_ method.
@@ -610,13 +603,13 @@ _Olingo_ provides API for processing dif
Such a service request can ask for a list of entities, or for one entity, or
one property.
Example:
-In our example, weâve stated in our metadata document that weâll provide a
list of âproductsâ whenever the _EntitySet_ with name âProductsâ is
invoked.
+In our example, we have stated in our metadata document that We will provide a
list of âproductsâ whenever the _EntitySet_ with name âProductsâ is
invoked.
This means that the user of our OData service will append the _EntitySet_ name
to the root URL of the service and then invoke the full URL.
This is http://localhost:8080/ExampleService1/ExampleServlet1.svc/Products
So, whenever this URL is fired, Olingo will invoke the
_EntityCollectionProcessor_ implementation of our OData service.
-And our _EntityCollectionProcessor_ implementation is expected to provide a
list of products.
+Then our _EntityCollectionProcessor_ implementation is expected to provide a
list of products.
-As weâve already mentioned, the metadata document is the contract for
providing data.
+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.
For example, the property names have to match, also the types of the
properties, and, if specified, the length of the strings, etc
@@ -633,9 +626,9 @@ Within our package _myservice.mynamespac
After creation of the Java class, we can see that there are 2 methods to be
implemented:
* _init()_
- This method is invoked by the _Olingo_ Framework, allowing us to
store the context object
+ This method is invoked by the _Olingo_ library, allowing us to store
the context object
* _readEntityCollection()_
- Here we have to fetch the required data and pass it back to the _Olingo_
FWK
+ Here we have to fetch the required data and pass it back to the _Olingo_
library
Letâs have a closer look
@@ -646,7 +639,7 @@ Letâs have a closer look
This method is common to all processor interfaces.
The _Olingo_ framework initializes the processor with an instance of the
_OData_ object.
According to the Javadoc, this object is the âRoot object for serving
factory tasksâ¦â
-Weâll need it later, so we store it as member variable.
+We will need it later, so we store it as member variable.
:::java
@@ -705,7 +698,7 @@ In this case as well, our readEntityColl
If the user doesnât specify any content type, then the default is JSON.
Why is this parameter needed?
-Because the _readEntityCollection_ method is supposed to deliver the data in
the format that is requested by the user. Weâll use this parameter when
creating a serializer based on it.
+Because the _readEntityCollection_ method is supposed to deliver the data in
the format that is requested by the user. We will use this parameter when
creating a serializer based on it.
The steps for implementating the method _readEntityCollection_ are:
@@ -721,7 +714,7 @@ The steps for implementating the method
3. Transform the data
- _Olingo_ expects from us to provide the data as low-level _InputStream_
object. However, _Olingo_ supports us in doing so, by providing us with a
proper "serializer".
+ _Olingo_ expects us to provide the data as low-level _InputStream_ object.
However, _Olingo_ supports us in doing so, by providing us with a proper
"serializer".
So what we have to do is create the serializer based on the requested
content type, configure it and call it.
4. Configure the response
@@ -766,9 +759,9 @@ Sample:
**_getData()_**
-Up to now, we havenât elaborated on fetching the actual data.
+We have not elaborated on fetching the actual data.
In our tutorial, to keep the code as simple as possible, we use a little
helper method that delivers some hardcoded entries.
-Since weâre supposed to deliver the data inside an _EntitySet_ instance, we
create the instance, ask it for the (initially empty) list of entities and add
some new entities to it.
+Since we are supposed to deliver the data inside an _EntitySet_ instance, we
create the instance, ask it for the (initially empty) list of entities and add
some new entities to it.
We create the entities and their properties according to what we declared in
our _ExampleEdmProvider_ class. So we have to take care to provide the correct
names to the new property objects.
@@ -802,7 +795,7 @@ We create the entities and their propert
After declaring the metadata and providing the data, our OData service
implementation is done.
The last step is to enable our OData service to be called on a web server.
-Therefore, weâre wrapping our service by a web application.
+Therefore, we are wrapping our service by a web application.
The web application is defined in the web.xml file, where a servlet is
registered.
The servlet is a standard _HttpServlet_ which dispatches the user requests to
the _Olingo_ framework.
@@ -819,12 +812,12 @@ Create Java class with name _DemoServlet
Override the `service()` method.
-Basically, what weâre doing here is to create an _ODataHttpHandler_, which
is a class that is provided by _Olingo_.
+Basically, what we are doing here is to create an _ODataHttpHandler_, which is
a class that is provided by _Olingo_.
It receives the user request and if the URL conforms to the OData
specification, the request is delegated to the processor implementation of the
OData service.
This means that the handler has to be configured with all processor
implementations that have been created along with the OData service (in our
example, only one processor).
Furthermore, the `ODataHttpHandler` needs to carry the knowledge about the
`EdmProvider`.
-As such, hereâs the location where our 2 implemented classes come together,
the metadata declaration and the data provisioning.
+This is where our two implemented classes come together, the metadata
declaration and the data provisioning.
:::java
@@ -894,7 +887,7 @@ Thatâs it. Now we can build and run
Running the service means build the war file and deploy it on a server.
-In our tutorial, weâre using the Eclipse web integration tools, which make
life easier.
+In our tutorial, we are using the Eclipse web integration tools, which make
life easier.
### Run with Eclipse
@@ -906,15 +899,15 @@ If not, you can use the _Basic -> J2EE P
-**Note:**
-You might have to first execute maven build and also press F5 to refresh the
content of the Eclipse project
+> Note:
+> You might have to first execute maven build and also press F5 to refresh the
content of the Eclipse project
After pressing "run", Eclipse starts the internal server and deploys the web
application on it.
Then the Eclipse internal Browser View is opened and the index.jsp file that
has been generated into our Example project is opened.
We ignore it. Instead, we open our OData service in our favorite browser.
-**Note:**
-If you face problems related to the server, it helps to restart your Eclipse
IDE.
+> Note:
+> If you face problems related to the server, it helps to restart your Eclipse
IDE.
### The service-URLs
@@ -1004,7 +997,7 @@ The expected result is the hardcoded lis
# 6. Summary
-Finally, weâve created our first OData service based on the V4 version of
the OData specification and using the V4 server library provided by _Olingo_.
+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 _Olingo_.
Our first OData service is very simple; it only allows invoking one entity
collection, apart from the service document and the metadata document.
**Outlook**
@@ -1020,4 +1013,4 @@ Further topics to be covered by follow-u
**Further reading**
OData specification: <http://odata.org/>
-Olingo Javadoc: <http://olingo.apache.org/javadoc/odata4/index.html>
\ No newline at end of file
+Olingo Javadoc: <http://olingo.apache.org/javadoc/odata4/index.html>
