Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/AnnotationProcessorExtension.html ============================================================================== --- websites/staging/olingo/trunk/content/doc/odata4/tutorials/AnnotationProcessorExtension.html (added) +++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/AnnotationProcessorExtension.html Tue Sep 16 12:34:18 2014 @@ -0,0 +1,452 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html lang="en"> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="description" content="Apache Olingo provides libraries which enable developers to implement OData producers and OData consumers. The available OData Java library implements OData version 2.0. In future on goal is to provide an OData 4.0 compliant library once the OData standard is published at OASIS. The focus within the community is currently on the Java technology but it is up to the community to discuss if other environments find interest."> + <meta name="author" content=""> + <link rel="icon" href="/favicon.ico"> + <title> + Apache Olingo + </title><!-- Bootstrap core CSS --> + <link href="/css/bootstrap.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link href="/css/navbar.css" rel="stylesheet" type="text/css"><!-- Just for debugging purposes. Don't actually copy these 2 lines! --> + <link href="/css/offcanvas.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link rel="stylesheet" href="/css/main.css"> + <!--[if lt IE 9]><script src="/js/ie8-responsive-file-warning.js"></script><![endif]--> + + <script src="/js/ie-emulation-modes-warning.js" type="text/javascript"> +</script><!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> + + <script src="/js/ie10-viewport-bug-workaround.js" type="text/javascript"> +</script><!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> + </head> + + <body> + <div class="container"> + <!-- Static navbar --> + <div class="navbar navbar-default" role="navigation"> + <div class="container-fluid"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <img class="navbar-brand" src="/img/OlingoOrangeTM.png" style="width:62px;" > + <a class="navbar-brand" href="#">Apache Olingoâ¢</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + + <li><a href="/">Home</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="http://www.apache.org/foundation/";>ASF Home</a></li> + <li><a href="http://projects.apache.org/";>Projects</a></li> + <li><a href="http://people.apache.org/";>People</a></li> + <li><a href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a></li> + <li><a href="http://www.apache.org/dyn/closer.cgi";>Download</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Support Apache</a></li> + </ul> + </li> + + <li><a href="http://www.apache.org/licenses/";>License</a></li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/download.html">Download OData 2.0 Java</a></li> + <li><a href="/doc/javascript/download.html">Download OData 4.0 JavaScript</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/index.html">Documentation OData 2.0 Java</a></li> + <li><a href="/doc/javascript/index.html">Documentation OData 4.0 JavaScript</a></li> + </ul> + </li> + <li><a href="/support.html">Support</a></li> + + </ul> + + <img class="navbar-right" height="50px" src="/img/asf-logo.gif"> + + </div><!--/.nav-collapse --> + </div><!--/.container-fluid --> + </div><!-- Main component for a primary marketing message or call to action --><h1 id="creating-a-web-application-with-the-annotation-processor-extension">Creating a Web Application with the Annotation Processor Extension</h1> +<h3 id="shortcut-creation-via-archetype">Shortcut: Creation via Archetype</h3> +<p>As a shortcut it is possible to create a sample project which use the Annotation Processor Extension via a Maven Archetype. +Therefore Maven must be called as shown below:</p> +<div class="codehilite"><pre><span class="n">mvn</span> <span class="n">archetype</span><span class="p">:</span><span class="n">generate</span> <span class="o">\</span> + <span class="o">-</span><span class="n">DinteractiveMode</span><span class="p">=</span><span class="n">false</span> <span class="o">\</span> + <span class="o">-</span><span class="n">Dversion</span><span class="p">=</span>1<span class="p">.</span>0<span class="p">.</span>0<span class="o">-</span><span class="n">SNAPSHOT</span> <span class="o">\</span> + <span class="o">-</span><span class="n">DgroupId</span><span class="p">=</span><span class="n">com</span><span class="p">.</span><span class="n">sample</span> <span class="o">\</span> + <span class="o">-</span><span class="n">DartifactId</span><span class="p">=</span><span class="n">my</span><span class="o">-</span><span class="n">car</span><span class="o">-</span><span class="n">service</span> <span class="o">\</span> + <span class="o">-</span><span class="n">DarchetypeGroupId</span><span class="p">=</span><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">olingo</span> <span class="o">\</span> + <span class="o">-</span><span class="n">DarchetypeArtifactId</span><span class="p">=</span><span class="n">olingo</span><span class="o">-</span><span class="n">odata2</span><span class="o">-</span><span class="n">sample</span><span class="o">-</span><span class="n">cars</span><span class="o">-</span><span class="n">annotation</span><span class="o">-</span><span class="n">archetype</span> <span class="o">\</span> + <span class="o">-</span><span class="n">DarchetypeVersion</span><span class="p">=</span>2<span class="p">.</span>0<span class="p">.</span>0 +</pre></div> + + +<p>In the generated sample project you now can simply run Maven with the default goal (run <code>mvn</code> in the shell) which compiles the sources and starts an Jetty web server at <code>http://localhost:8080</code>.</p> +<p>For more detailed documentation about Archetypes in Olingo take a look into the <a href="/doc/odata2/sample-setup">sample setup</a> section.</p> +<h3 id="creation-from-scratch">Creation from Scratch</h3> +<p>A project which use the Annotation Processor Extension consists mainly of the model beans, the <code>ODataServiceFactory</code> implementation and the web resources (e.g. <code>web.xml</code>). +In addition we use Maven so that it is necessary to create a <code>pom.xml</code> for project build information and dependency resolution.</p> +<h5 id="create-maven-project-structure">Create Maven Project structure</h5> +<p>To start a folder is created (e.g. <em>annotation-from-scratch</em>) which contains the Maven project. +Within this the default Maven project structure is used, which looks like:</p> +<div class="codehilite"><pre><span class="o">./</span><span class="n">src</span><span class="o">/</span><span class="n">main</span><span class="o">/</span><span class="n">java</span> +<span class="o">./</span><span class="n">src</span><span class="o">/</span><span class="n">main</span><span class="o">/</span><span class="n">resources</span> +<span class="o">./</span><span class="n">src</span><span class="o">/</span><span class="n">main</span><span class="o">/</span><span class="n">webapp</span> +</pre></div> + + +<h5 id="create-maven-pomxml">Create Maven pom.xml</h5> +<p>After creation of the project structure the default <code>pom.xml</code> for building of an <code>WAR-File</code> have to be created. +In addition we need the dependency to all necessary <em>Apache Olingo artifacts</em> and to the used <code>JAX-RS</code> implementation which in this sample is <code>Apache CXF</code>.</p> +<p>The resulting <code>pom.xml</code> then looks like:</p> +<div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> +<span class="nt"><project</span> <span class="na">xmlns=</span><span class="s">"http://maven.apache.org/POM/4.0.0"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> + <span class="na">xsi:schemaLocation=</span><span class="s">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"</span><span class="nt">></span> + <span class="nt"><modelVersion></span>4.0.0<span class="nt"></modelVersion></span> + + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>cars-annotations-sample<span class="nt"></artifactId></span> + <span class="nt"><version></span>1.0.0-SNAPSHOT<span class="nt"></version></span> + <span class="nt"><name></span>${project.artifactId}<span class="nt"></name></span> + + <span class="nt"><packaging></span>war<span class="nt"></packaging></span> + + <span class="nt"><properties></span> + <span class="c"><!-- Dependency Versions --></span> + <span class="nt"><version.cxf></span>2.7.6<span class="nt"></version.cxf></span> + <span class="nt"><version.servlet-api></span>2.5<span class="nt"></version.servlet-api></span> + <span class="nt"><version.jaxrs-api></span>2.0-m10<span class="nt"></version.jaxrs-api></span> + <span class="nt"><version.olingo></span>2.0.0<span class="nt"></version.olingo></span> + <span class="nt"></properties></span> + + <span class="nt"><build></span> + <span class="nt"><finalName></span>${project.artifactId}<span class="nt"></finalName></span> + <span class="nt"><defaultGoal></span>clean package<span class="nt"></defaultGoal></span> + <span class="nt"></build></span> + + <span class="nt"><dependencies></span> + <span class="c"><!-- Apache Olingo Library dependencies --></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-api<span class="nt"></artifactId></span> + <span class="nt"><version></span>${version.olingo}<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><artifactId></span>olingo-odata2-api-annotation<span class="nt"></artifactId></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><type></span>jar<span class="nt"></type></span> + <span class="nt"><version></span>${version.olingo}<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-core<span class="nt"></artifactId></span> + <span class="nt"><version></span>${version.olingo}<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="c"><!-- Apache Olingo Annotation Processor Extension dependencies --></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-annotation-processor-api<span class="nt"></artifactId></span> + <span class="nt"><version></span>${version.olingo}<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-annotation-processor-core<span class="nt"></artifactId></span> + <span class="nt"><version></span>${version.olingo}<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="c"><!-- Servlet/REST dependencies --></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>javax.servlet<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>servlet-api<span class="nt"></artifactId></span> + <span class="nt"><version></span>${version.servlet-api}<span class="nt"></version></span> + <span class="nt"><scope></span>provided<span class="nt"></scope></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>javax.ws.rs<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>javax.ws.rs-api<span class="nt"></artifactId></span> + <span class="nt"><version></span>${version.jaxrs-api}<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.cxf<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>cxf-rt-frontend-jaxrs<span class="nt"></artifactId></span> + <span class="nt"><version></span>${version.cxf}<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"></dependencies></span> +<span class="nt"></project></span> +</pre></div> + + +<h5 id="create-sample-entity-model">Create Sample (Entity) Model</h5> +<p>For this sample a simple model with the two entities <em>Manufacturer</em> and <em>Car</em> is created.</p> +<p>The <em>Manufacturer</em> consists of an <code>Id</code>, <code>Name</code>, <code>Founded</code> and a relation to a list of its <code>Cars</code>.<br /> +The <em>Car</em> consists of an <code>Id</code>, <code>Model</code>, <code>ProductionYear</code>, <code>Price</code> and a relation to its <code>Manufacturer</code>.</p> +<p><strong>Create Java Beans for Entities</strong> +For each of both entities first a java bean (<em>POJO</em>) is created in the package <code>org.apache.olingo.sample.annotation.model</code> (which results in a created folder <code>src/main/java/org/apache/olingo/sample/annotation/model/</code>) which looks like:</p> +<div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">olingo</span><span class="o">.</span><span class="na">sample</span><span class="o">.</span><span class="na">annotation</span><span class="o">.</span><span class="na">model</span><span class="o">;</span> + +<span class="cm">/** required Imports */</span> + +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Manufacturer</span> <span class="o">{</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">id</span><span class="o">;</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">name</span><span class="o">;</span> + <span class="kd">private</span> <span class="n">Calendar</span> <span class="n">founded</span><span class="o">;</span> + <span class="kd">private</span> <span class="n">List</span><span class="o"><</span><span class="n">Car</span><span class="o">></span> <span class="n">cars</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o"><</span><span class="n">Car</span><span class="o">>();</span> + + <span class="cm">/** optional getter and setter */</span> +<span class="o">}</span> +</pre></div> + + +<p>and:</p> +<div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">olingo</span><span class="o">.</span><span class="na">sample</span><span class="o">.</span><span class="na">annotation</span><span class="o">.</span><span class="na">model</span><span class="o">;</span> + +<span class="cm">/** required Imports */</span> + +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Car</span> <span class="o">{</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">id</span><span class="o">;</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">model</span><span class="o">;</span> + <span class="kd">private</span> <span class="n">Double</span> <span class="n">price</span><span class="o">;</span> + <span class="kd">private</span> <span class="n">Integer</span> <span class="n">productionYear</span><span class="o">;</span> + <span class="kd">private</span> <span class="n">Manufacturer</span> <span class="n">manufacturer</span><span class="o">;</span> + + <span class="cm">/** optional getter and setter */</span> +<span class="o">}</span> +</pre></div> + + +<p><strong>Annotated created Java Beans</strong> +Now those beans have to be annotated with the annotations of the <em>Annotation Processor Extension</em>.</p> +<p>Both beans needs at first the <code>@EdmEntityType</code> and <code>@EdmEntitySet</code> annotation to define that they represent an OData Entity. These annotation must be added at the bean class which as example for the <em>Manufacturer</em> then look like:</p> +<div class="codehilite"><pre><span class="nd">@EdmEntityType</span> +<span class="nd">@EdmEntitySet</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Manufacturer</span> <span class="o">{</span> <span class="cm">/** more code */</span> <span class="o">}</span> +</pre></div> + + +<p>Then all simple properties of the Entity must be annotated with <code>@EdmProperty</code>, the <em>Key</em> for the Entity additional must be annotated with <code>@EdmKey</code> which is in this sample the <code>Id</code> field of the entities.</p> +<p>For the <em>Manufacturer</em> it then look like:</p> +<div class="codehilite"><pre><span class="nd">@EdmEntityType</span> +<span class="nd">@EdmEntitySet</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Manufacturer</span> <span class="o">{</span> + <span class="nd">@EdmKey</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">id</span><span class="o">;</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">name</span><span class="o">;</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">Calendar</span> <span class="n">founded</span><span class="o">;</span> + + <span class="cm">/** more code */</span> +<span class="o">}</span> +</pre></div> + + +<p>A relation to another Entity must be annotated with <code>@EdmNavigationProperty</code>. In this sample this are the bi-directional relation between a <em>Manufacturer</em> and its <em>Cars</em>. </p> +<p>For the <em>Manufacturer</em> the added annotation look like:</p> +<div class="codehilite"><pre><span class="nd">@EdmEntityType</span> +<span class="nd">@EdmEntitySet</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Manufacturer</span> <span class="o">{</span> + <span class="cm">/** more code */</span> + + <span class="nd">@EdmNavigationProperty</span> + <span class="kd">private</span> <span class="n">List</span><span class="o"><</span><span class="n">Car</span><span class="o">></span> <span class="n">cars</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o"><</span><span class="n">Car</span><span class="o">>();</span> + + <span class="cm">/** more code */</span> +<span class="o">}</span> +</pre></div> + + +<p>The complete resulting Entities (POJOs) then look like:</p> +<div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">olingo</span><span class="o">.</span><span class="na">sample</span><span class="o">.</span><span class="na">annotation</span><span class="o">.</span><span class="na">model</span><span class="o">;</span> + +<span class="kn">import</span> <span class="nn">java.util.*</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.olingo.odata2.api.annotation.edm.*</span><span class="o">;</span> + +<span class="nd">@EdmEntityType</span> +<span class="nd">@EdmEntitySet</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Manufacturer</span> <span class="o">{</span> + <span class="nd">@EdmKey</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">id</span><span class="o">;</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">name</span><span class="o">;</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">Calendar</span> <span class="n">founded</span><span class="o">;</span> + <span class="nd">@EdmNavigationProperty</span> + <span class="kd">private</span> <span class="n">List</span><span class="o"><</span><span class="n">Car</span><span class="o">></span> <span class="n">cars</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o"><</span><span class="n">Car</span><span class="o">>();</span> + + <span class="cm">/** optional getter and setter */</span> +<span class="o">}</span> +</pre></div> + + +<p>and</p> +<div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">olingo</span><span class="o">.</span><span class="na">sample</span><span class="o">.</span><span class="na">annotation</span><span class="o">.</span><span class="na">model</span><span class="o">;</span> + +<span class="kn">import</span> <span class="nn">org.apache.olingo.odata2.api.annotation.edm.*</span><span class="o">;</span> + +<span class="nd">@EdmEntityType</span> +<span class="nd">@EdmEntitySet</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Car</span> <span class="o">{</span> + <span class="nd">@EdmKey</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">id</span><span class="o">;</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">String</span> <span class="n">model</span><span class="o">;</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">Double</span> <span class="n">price</span><span class="o">;</span> + <span class="nd">@EdmProperty</span> + <span class="kd">private</span> <span class="n">Integer</span> <span class="n">productionYear</span><span class="o">;</span> + <span class="nd">@EdmNavigationProperty</span> + <span class="kd">private</span> <span class="n">Manufacturer</span> <span class="n">manufacturer</span><span class="o">;</span> + + <span class="cm">/** optional getter and setter */</span> +<span class="o">}</span> +</pre></div> + + +<p>The next step is to create the <code>ODataService</code>.</p> +<h5 id="create-odataservice">Create ODataService</h5> +<p>The <code>ODataService</code> is created via an <code>ODataServiceFactory</code> implementation. +For the sample a <code>AnnotationSampleServiceFactory</code> in the package <code>org.apache.olingo.sample.annotation.processor</code> (which results in a created folder <code>src/main/java/org/apache/olingo/sample/annotation/processor/</code>) is created which extends the <code>ODataServiceFactory</code>. The resulting code look like:</p> +<div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">olingo</span><span class="o">.</span><span class="na">sample</span><span class="o">.</span><span class="na">annotation</span><span class="o">.</span><span class="na">processor</span><span class="o">;</span> + +<span class="cm">/** required Imports */</span> + +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">AnnotationSampleServiceFactory</span> <span class="kd">extends</span> <span class="n">ODataServiceFactory</span> <span class="o">{</span> + <span class="nd">@Override</span> + <span class="kd">public</span> <span class="n">ODataService</span> <span class="nf">createService</span><span class="o">(</span><span class="kd">final</span> <span class="n">ODataContext</span> <span class="n">context</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">ODataException</span> <span class="o">{</span> + <span class="k">return</span> <span class="kc">null</span><span class="o">;</span> + <span class="o">}</span> +<span class="o">}</span> +</pre></div> + + +<p>In the <code>createService(...)</code> method now the <code>ODataService</code> needs to be created. +The <em>Annotation Processor Extension</em> provides therefore the method <code>createAnnotationService(...)</code> within the <code>AnnotationServiceFactory</code> which can be used. This method require as parameter the <em>Package</em> which contains the <em>Model</em> in form of annotated POJOs (as created in the section <em>Create the Model</em>). </p> +<p>For a persistence between several request it is necessary to hold the created <code>ODataService</code> in an static instance. In the sample the <a href="http://en.wikipedia.org/wiki/Initialization-on-demand_holder_idiom";>Initialization on demand holder idiom</a> is used.</p> +<p>As result the implementation look like:</p> +<div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">olingo</span><span class="o">.</span><span class="na">sample</span><span class="o">.</span><span class="na">annotation</span><span class="o">.</span><span class="na">processor</span><span class="o">;</span> + +<span class="kn">import</span> <span class="nn">org.apache.olingo.odata2.api.*</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.olingo.odata2.api.exception.*</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.olingo.odata2.api.processor.ODataContext</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.olingo.odata2.annotation.processor.api.AnnotationServiceFactory</span><span class="o">;</span> + +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">AnnotationSampleServiceFactory</span> <span class="kd">extends</span> <span class="n">ODataServiceFactory</span> <span class="o">{</span> + + <span class="cm">/**</span> +<span class="cm"> * Instance holder for all annotation relevant instances which should be used as singleton</span> +<span class="cm"> * instances within the ODataApplication (ODataService)</span> +<span class="cm"> */</span> + <span class="kd">private</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">AnnotationInstances</span> <span class="o">{</span> + <span class="kd">final</span> <span class="kd">static</span> <span class="n">String</span> <span class="n">MODEL_PACKAGE</span> <span class="o">=</span> <span class="s">"org.apache.olingo.sample.annotation.model"</span><span class="o">;</span> + <span class="kd">final</span> <span class="kd">static</span> <span class="n">ODataService</span> <span class="n">ANNOTATION_ODATA_SERVICE</span><span class="o">;</span> + + <span class="kd">static</span> <span class="o">{</span> + <span class="k">try</span> <span class="o">{</span> + <span class="n">ANNOTATION_ODATA_SERVICE</span> <span class="o">=</span> <span class="n">AnnotationServiceFactory</span><span class="o">.</span><span class="na">createAnnotationService</span><span class="o">(</span><span class="n">MODEL_PACKAGE</span><span class="o">);</span> + <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">ODataApplicationException</span> <span class="n">ex</span><span class="o">)</span> <span class="o">{</span> + <span class="k">throw</span> <span class="k">new</span> <span class="nf">RuntimeException</span><span class="o">(</span><span class="s">"Exception during sample data generation."</span><span class="o">,</span> <span class="n">ex</span><span class="o">);</span> + <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">ODataException</span> <span class="n">ex</span><span class="o">)</span> <span class="o">{</span> + <span class="k">throw</span> <span class="k">new</span> <span class="nf">RuntimeException</span><span class="o">(</span><span class="s">"Exception during data source initialization generation."</span><span class="o">,</span> <span class="n">ex</span><span class="o">);</span> + <span class="o">}</span> + <span class="o">}</span> + <span class="o">}</span> + + <span class="kd">public</span> <span class="n">ODataService</span> <span class="nf">createService</span><span class="o">(</span><span class="kd">final</span> <span class="n">ODataContext</span> <span class="n">context</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">ODataException</span> <span class="o">{</span> + <span class="k">return</span> <span class="n">AnnotationInstances</span><span class="o">.</span><span class="na">ANNOTATION_ODATA_SERVICE</span><span class="o">;</span> + <span class="o">}</span> +<span class="o">}</span> +</pre></div> + + +<p>Now the model as well as the service creation is done. +The next step is to provide the necessary resources to run the application within an application server. </p> +<h5 id="create-web-application-resources">Create Web Application resources</h5> +<p>To deploy and run the application on an application server it is necessary to provide a <code>web.xml</code> which defines the <code>JAX-RS</code> entry point which then calls the sample application.</p> +<p>For this sample <code>Apache CXF</code> is used (see <code><servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class></code>) which need as parameter the <code>javax.ws.rs.Application</code> and the <code>org.apache.olingo.odata2.service.factory</code>.</p> +<p>Therefore the <code>web.xml</code> is created in the <code>src/main/webapp/WEB-INF</code> folder with following content:</p> +<div class="codehilite"><pre><span class="nt"><web-app</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> + <span class="na">xmlns=</span><span class="s">"http://java.sun.com/xml/ns/javaee"</span> <span class="na">xmlns:web=</span><span class="s">"http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"</span> + <span class="na">xsi:schemaLocation=</span><span class="s">"http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"</span> + <span class="na">id=</span><span class="s">"WebApp_ID"</span> <span class="na">version=</span><span class="s">"2.5"</span><span class="nt">></span> + <span class="nt"><display-name></span>org.apache.olingo.sample.annotation<span class="nt"></display-name></span> + <span class="nt"><servlet></span> + <span class="nt"><servlet-name></span>ServiceServlet<span class="nt"></servlet-name></span> + <span class="nt"><servlet-class></span>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet<span class="nt"></servlet-class></span> + <span class="nt"><init-param></span> + <span class="nt"><param-name></span>javax.ws.rs.Application<span class="nt"></param-name></span> + <span class="nt"><param-value></span>org.apache.olingo.odata2.core.rest.app.ODataApplication<span class="nt"></param-value></span> + <span class="nt"></init-param></span> + <span class="nt"><init-param></span> + <span class="nt"><param-name></span>org.apache.olingo.odata2.service.factory<span class="nt"></param-name></span> + <span class="nt"><param-value></span>org.apache.olingo.sample.annotation.processor.AnnotationSampleServiceFactory<span class="nt"></param-value></span> + <span class="nt"></init-param></span> + <span class="nt"><load-on-startup></span>1<span class="nt"></load-on-startup></span> + <span class="nt"></servlet></span> + + <span class="nt"><servlet-mapping></span> + <span class="nt"><servlet-name></span>ServiceServlet<span class="nt"></servlet-name></span> + <span class="nt"><url-pattern></span>/AnnotationSample.svc/*<span class="nt"></url-pattern></span> + <span class="nt"></servlet-mapping></span> +<span class="nt"></web-app></span> +</pre></div> + + +<h5 id="deploy-and-run">Deploy and Run</h5> +<p>Build the project with maven via <code>mvm clean package</code> and copy the resulting <code>WAR-File</code> from the projects <code>target</code> folder in the <code>deploy</code> folder of the web application server (e.g. a <a href="http://tomcat.apache.org/";>Tomcat</a>). +As example for a default Tomcat 7.x installation <code>cp $PROJECT_HOME/target/cars-annotations-sample.war $TOMCAT_HOME/webapps</code>.</p> +<p>After starting the web application server it is possible to request...</p> +<ul> +<li>...the <em>Service Document</em> via the URL: <a href="http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/";>http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/</a></li> +<li>...the <em>Metadata</em> via the URL: <a href="http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/$metadata";>http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/$metadata</a></li> +<li>...the <em>Cars</em> EntitySet via the URL: <a href="http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/CarSet";>http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/CarSet</a></li> +<li>...the <em>Manufacturer</em> EntitySet via the URL: <a href="http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/ManufacturerSet";>http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/ManufacturerSet</a></li> +</ul> +<p>Also it is possible to create <em>Car</em> and <em>Manufacturer</em> Entities via <code>HTTP POST</code> requests.</p> +<h3 id="more-detailed-look">More detailed look</h3> +<p>A more detailed look into the Annotation Processor Extension can be found in the <a href="https://wiki.apache.org/Olingo/Documentation/AnnotationProcessor";>wiki</a>.</p><div align="center"> +<p>Copyright © 2013-2014, The Apache Software Foundation<br> + Apache Olingo, Olingo, Apache, the Apache feather, and + the Apache Olingo project logo are trademarks of the Apache Software + Foundation.</p> + <small><a href="/doc/odata2/privacy.html">Privacy</a></small> + </div> + </div><!-- /container --> + <!-- Bootstrap core JavaScript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="/js/jquery.js" type="text/javascript"> +</script> + <script src="/js/bootstrap.js" type="text/javascript"> + <script src="/js/offcanvas.js" type="text/javascript"> +</script> + <!-- Google Analytics: change UA-XXXXX-X to be your site's ID. --> + <script> + (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]= + function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date; + e=o.createElement(i);r=o.getElementsByTagName(i)[0]; + e.src='//www.google-analytics.com/analytics.js'; + r.parentNode.insertBefore(e,r)}(window,document,'script','ga')); + ga('create','UA-44963757-1');ga('send','pageview'); + </script> + </body> +</html>
Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/CreateWebApp.html ============================================================================== --- websites/staging/olingo/trunk/content/doc/odata4/tutorials/CreateWebApp.html (added) +++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/CreateWebApp.html Tue Sep 16 12:34:18 2014 @@ -0,0 +1,332 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html lang="en"> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="description" content="Apache Olingo provides libraries which enable developers to implement OData producers and OData consumers. The available OData Java library implements OData version 2.0. In future on goal is to provide an OData 4.0 compliant library once the OData standard is published at OASIS. The focus within the community is currently on the Java technology but it is up to the community to discuss if other environments find interest."> + <meta name="author" content=""> + <link rel="icon" href="/favicon.ico"> + <title> + Apache Olingo + </title><!-- Bootstrap core CSS --> + <link href="/css/bootstrap.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link href="/css/navbar.css" rel="stylesheet" type="text/css"><!-- Just for debugging purposes. Don't actually copy these 2 lines! --> + <link href="/css/offcanvas.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link rel="stylesheet" href="/css/main.css"> + <!--[if lt IE 9]><script src="/js/ie8-responsive-file-warning.js"></script><![endif]--> + + <script src="/js/ie-emulation-modes-warning.js" type="text/javascript"> +</script><!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> + + <script src="/js/ie10-viewport-bug-workaround.js" type="text/javascript"> +</script><!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> + </head> + + <body> + <div class="container"> + <!-- Static navbar --> + <div class="navbar navbar-default" role="navigation"> + <div class="container-fluid"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <img class="navbar-brand" src="/img/OlingoOrangeTM.png" style="width:62px;" > + <a class="navbar-brand" href="#">Apache Olingoâ¢</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + + <li><a href="/">Home</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="http://www.apache.org/foundation/";>ASF Home</a></li> + <li><a href="http://projects.apache.org/";>Projects</a></li> + <li><a href="http://people.apache.org/";>People</a></li> + <li><a href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a></li> + <li><a href="http://www.apache.org/dyn/closer.cgi";>Download</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Support Apache</a></li> + </ul> + </li> + + <li><a href="http://www.apache.org/licenses/";>License</a></li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/download.html">Download OData 2.0 Java</a></li> + <li><a href="/doc/javascript/download.html">Download OData 4.0 JavaScript</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/index.html">Documentation OData 2.0 Java</a></li> + <li><a href="/doc/javascript/index.html">Documentation OData 4.0 JavaScript</a></li> + </ul> + </li> + <li><a href="/support.html">Support</a></li> + + </ul> + + <img class="navbar-right" height="50px" src="/img/asf-logo.gif"> + + </div><!--/.nav-collapse --> + </div><!--/.container-fluid --> + </div><!-- Main component for a primary marketing message or call to action --><h2 id="creating-a-web-application-project-for-transforming-jpa-models-into-odata-services">Creating a Web Application Project for Transforming JPA Models into OData Services</h2> +<p>In this section, information on how to create a web application (Maven) for transforming JPA Models into OData Services using OData JPA Processor Library is provided. +The table gives the list of Maven dependencies you need to include in the POM.xml of your application.</p> +<p><em>Note</em>: The following dependencies are applicable for an application using EclipseLink as the JPA Provider and HSQLDB as the database. However, you are free to use any JPA provider (like Hibernate, OpenJPA and so on) and database of your choice.</p> +<table> +<thead> +<tr> +<th>Group ID</th> +<th>Artifact ID</th> +<th>Version</th> +</tr> +</thead> +<tbody> +<tr> +<td>javax.servlet</td> +<td>servlet-api</td> +<td>2.5</td> +</tr> +<tr> +<td>org.apache.cxf</td> +<td>cxf-rt-frontend-jaxrs</td> +<td>2.7.5</td> +</tr> +<tr> +<td>org.slf4j</td> +<td>slf4j-log4j12</td> +<td>1.7.1</td> +</tr> +<tr> +<td>junit</td> +<td>junit</td> +<td>3.8.1</td> +</tr> +<tr> +<td>org.apache.olingo</td> +<td>olingo.odata2.api</td> +<td>1.0.0</td> +</tr> +<tr> +<td>org.apache.olingo</td> +<td>olingo.odata2.jpa.processor.api</td> +<td>1.0.0</td> +</tr> +<tr> +<td>org.apache.olingo</td> +<td>olingo.odata2.jpa.processor.core</td> +<td>1.0.0</td> +</tr> +<tr> +<td>org.apache.olingo</td> +<td>olingo.odata2.jpa.processor.ref</td> +<td>1.0.0</td> +</tr> +<tr> +<td>org.apache.olingo</td> +<td>olingo.odata2.core</td> +<td>1.0.0</td> +</tr> +<tr> +<td>org.eclipse.persistence</td> +<td>eclipselink</td> +<td>2.3.1</td> +</tr> +<tr> +<td>org.eclipse.persistence</td> +<td>javax.persistence</td> +<td>2.0.5</td> +</tr> +<tr> +<td>org.hsqldb</td> +<td>hsqldb</td> +<td>2.2.8</td> +</tr> +</tbody> +</table> +<p>Here is a <a href="https://cms.apache.org/olingo/wc/browse/deepa-udCb40/trunk/content/resources/SampleJPAModel";>Sample JPA Model</a> </p> +<h5 id="create-a-dynamic-web-application-project-from-scratch">Create a Dynamic Web Application Project from Scratch:</h5> +<ol> +<li> +<p>In the command prompt, enter the maven command given here (change the DgroupId and DartifactId as per your requirement)</p> +<div class="codehilite"><pre><span class="n">mvn</span> <span class="n">archetype</span><span class="p">:</span><span class="n">generate</span> <span class="o">-</span><span class="n">DgroupId</span><span class="p">=</span><span class="n">com</span><span class="p">.</span><span class="n">sample</span><span class="p">.</span><span class="n">jpa</span> <span class="o">-</span><span class="n">DartifactId</span><span class="p">=</span><span class="n">salesorderprocessing</span><span class="p">.</span><span class="n">app</span> <span class="o">-</span><span class="n">DarchetypeArtifactId</span><span class="p">=</span><span class="n">maven</span><span class="o">-</span><span class="n">archetype</span><span class="o">-</span><span class="n">webapp</span> +</pre></div> + + +<p>Maven generates the file system structure for a web application project including a basic POM.xml. This step is completed by creating a Java source folder.</p> +</li> +<li> +<p>Create a folder by name 'java' in the path 'src/main/'.</p> +</li> +</ol> +<h5 id="tailor-pomxml">Tailor POM.xml</h5> +<p>POM.xml should be modified for adding dependencies like OData Library (Java) and OData JPA Processor Library. Add a dependency to the project that contains JPA models. Open POM.xml and replace the existing content with the following:</p> +<div class="codehilite"><pre> <span class="cp"><?xml version="1.0" ?></span> + <span class="nt"><project</span> <span class="na">xsi:schemaLocation=</span><span class="s">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"</span> <span class="na">xmlns=</span><span class="s">"http://maven.apache.org/POM/4.0.0"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span><span class="nt">></span> + <span class="nt"><modelVersion></span>4.0.0<span class="nt"></modelVersion></span> + <span class="nt"><parent></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-parent<span class="nt"></artifactId></span> + <span class="nt"><version></span>1.0.0<span class="nt"></version></span> + <span class="nt"><relativePath></span>..<span class="nt"></relativePath></span> + <span class="nt"></parent></span> + <span class="nt"><artifactId></span>olingo.odata2.jpa.processor.ref.web<span class="nt"></artifactId></span> + <span class="nt"><packaging></span>war<span class="nt"></packaging></span> + <span class="nt"><name></span><span class="cp">${</span><span class="n">project</span><span class="o">.</span><span class="n">groupId</span><span class="cp">}</span>-<span class="cp">${</span><span class="n">project</span><span class="o">.</span><span class="n">artifactId</span><span class="cp">}</span><span class="nt"></name></span> + <span class="nt"><dependencies></span> + <span class="nt"><dependency></span> + <span class="c"><!-- required because of auto detection of web facet 2.5 --></span> + <span class="nt"><groupId></span>javax.servlet<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>servlet-api<span class="nt"></artifactId></span> + <span class="nt"><version></span>2.5<span class="nt"></version></span> + <span class="nt"><scope></span>provided<span class="nt"></scope></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.cxf<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>cxf-rt-frontend-jaxrs<span class="nt"></artifactId></span> + <span class="nt"><version></span>2.7.5<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-core<span class="nt"></artifactId></span> + <span class="nt"><version></span><span class="cp">${</span><span class="n">project</span><span class="o">.</span><span class="n">version</span><span class="cp">}</span><span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-api<span class="nt"></artifactId></span> + <span class="nt"><version></span><span class="cp">${</span><span class="n">project</span><span class="o">.</span><span class="n">version</span><span class="cp">}</span><span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-jpa-processor-api<span class="nt"></artifactId></span> + <span class="nt"><version></span><span class="cp">${</span><span class="n">project</span><span class="o">.</span><span class="n">version</span><span class="cp">}</span><span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-jpa-processor-core<span class="nt"></artifactId></span> + <span class="nt"><version></span><span class="cp">${</span><span class="n">project</span><span class="o">.</span><span class="n">version</span><span class="cp">}</span><span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.apache.olingo<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>olingo-odata2-jpa-processor-ref<span class="nt"></artifactId></span> + <span class="nt"><version></span><span class="cp">${</span><span class="n">project</span><span class="o">.</span><span class="n">version</span><span class="cp">}</span><span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.slf4j<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>slf4j-log4j12<span class="nt"></artifactId></span> + <span class="nt"><version></span>1.7.1<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>junit<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>junit<span class="nt"></artifactId></span> + <span class="nt"><version></span>3.8.1<span class="nt"></version></span> + <span class="nt"><scope></span>test<span class="nt"></scope></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.eclipse.persistence<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>eclipselink<span class="nt"></artifactId></span> + <span class="nt"><version></span>2.3.1<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.eclipse.persistence<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>javax.persistence<span class="nt"></artifactId></span> + <span class="nt"><version></span>2.0.5<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"><dependency></span> + <span class="nt"><groupId></span>org.hsqldb<span class="nt"></groupId></span> + <span class="nt"><artifactId></span>hsqldb<span class="nt"></artifactId></span> + <span class="nt"><version></span>2.2.8<span class="nt"></version></span> + <span class="nt"></dependency></span> + <span class="nt"></dependencies></span> + <span class="nt"><build></span> + <span class="nt"><finalName></span>olingo.odata2.jpa.processor.ref.web<span class="nt"></finalName></span> + <span class="nt"></build></span> + <span class="nt"></project></span> +</pre></div> + + +<h5 id="implement-an-odata-service">Implement an OData Service</h5> +<p>The project is now ready to expose OData services. Service Factory provides a means for initializing Entity Data Model (EDM) Provider and OData JPA Processors. Following are the steps for implementing a Service Factory:</p> +<ol> +<li>Add a new Java class by extending ODataJPAServiceFactory.</li> +<li>Declare persistence unit name as class variable. For example, private static final String PUNIT_NAME = "persistenceUnitName"; + <em>Note</em>: The PUNIT_NAME refers to the persistence unit name maintained in the persistence.xml of JPA project.</li> +<li> +<p>Implement the abstract method <code>initializeODataJPAContext</code>. Here is the code snippet:</p> +<div class="codehilite"><pre><span class="n">ODataJPAContext</span> <span class="n">oDataJPAContext</span> <span class="p">=</span> <span class="n">getODataJPAContext</span><span class="p">();</span> +<span class="n">oDataJPAContext</span><span class="p">.</span><span class="n">setEntityManagerFactory</span><span class="p">(</span><span class="n">JPAEntityManagerFactory</span><span class="p">.</span><span class="n">getEntityManagerFactory</span><span class="p">(</span><span class="n">PUNIT_NAME</span><span class="p">));</span> +<span class="n">oDataJPAContext</span><span class="p">.</span><span class="n">setPersistenceUnitName</span><span class="p">(</span><span class="n">PUNIT_NAME</span><span class="p">);</span> +</pre></div> + + +</li> +</ol> +<h5 id="configure-the-web-application">Configure the Web Application</h5> +<ol> +<li>Configure the web application as shown below by adding the following servlet configuration to web.xml. The Service factory which was implemented is configured in the web.xml of the ODataApplication as one of the init parameters.</li> +<li> +<p>Replace in the following XML with the class name you created in the previous step:</p> +<div class="codehilite"><pre>- <span class="nt"><servlet></span> + <span class="nt"><servlet-name></span>JPARefScenarioServlet<span class="nt"></servlet-name></span> + <span class="nt"><servlet-class></span>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet<span class="nt"></servlet-class></span> + - <span class="nt"><init-param></span> + <span class="nt"><param-name></span>javax.ws.rs.Application<span class="nt"></param-name></span> + <span class="nt"><param-value></span>org.apache.olingo.odata2.core.rest.app.ODataApplication<span class="nt"></param-value></span> + <span class="nt"></init-param></span> + - <span class="nt"><init-param></span> + <span class="nt"><param-name></span>org.apache.olingo.odata2.service.factory<span class="nt"></param-name></span> + <span class="nt"><param-value></span>org.apache.olingo.odata2.jpa.processor.ref.web.JPAReferenceServiceFactory<span class="nt"></param-value></span> + <span class="nt"></init-param></span> + <span class="nt"><load-on-startup></span>1<span class="nt"></load-on-startup></span> + <span class="nt"></servlet></span> +- <span class="nt"><servlet-mapping></span> + <span class="nt"><servlet-name></span>JPARefScenarioServlet<span class="nt"></servlet-name></span> + <span class="nt"><url-pattern></span>/SalesOrderProcessing.svc/*<span class="nt"></url-pattern></span> + <span class="nt"></servlet-mapping></span> +</pre></div> + + +</li> +</ol> +<p>After the implementation, test the web application using http://localhost:8080/olingo.odata2.jpa.processor.ref.web/SalesOrderProcessing.svc</p><div align="center"> +<p>Copyright © 2013-2014, The Apache Software Foundation<br> + Apache Olingo, Olingo, Apache, the Apache feather, and + the Apache Olingo project logo are trademarks of the Apache Software + Foundation.</p> + <small><a href="/doc/odata2/privacy.html">Privacy</a></small> + </div> + </div><!-- /container --> + <!-- Bootstrap core JavaScript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="/js/jquery.js" type="text/javascript"> +</script> + <script src="/js/bootstrap.js" type="text/javascript"> + <script src="/js/offcanvas.js" type="text/javascript"> +</script> + <!-- Google Analytics: change UA-XXXXX-X to be your site's ID. --> + <script> + (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]= + function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date; + e=o.createElement(i);r=o.getElementsByTagName(i)[0]; + e.src='//www.google-analytics.com/analytics.js'; + r.parentNode.insertBefore(e,r)}(window,document,'script','ga')); + ga('create','UA-44963757-1');ga('send','pageview'); + </script> + </body> +</html> Added: websites/staging/olingo/trunk/content/doc/odata4/tutorials/CustomODataJPAProcessor.html ============================================================================== --- websites/staging/olingo/trunk/content/doc/odata4/tutorials/CustomODataJPAProcessor.html (added) +++ websites/staging/olingo/trunk/content/doc/odata4/tutorials/CustomODataJPAProcessor.html Tue Sep 16 12:34:18 2014 @@ -0,0 +1,147 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html lang="en"> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="description" content="Apache Olingo provides libraries which enable developers to implement OData producers and OData consumers. The available OData Java library implements OData version 2.0. In future on goal is to provide an OData 4.0 compliant library once the OData standard is published at OASIS. The focus within the community is currently on the Java technology but it is up to the community to discuss if other environments find interest."> + <meta name="author" content=""> + <link rel="icon" href="/favicon.ico"> + <title> + Apache Olingo + </title><!-- Bootstrap core CSS --> + <link href="/css/bootstrap.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link href="/css/navbar.css" rel="stylesheet" type="text/css"><!-- Just for debugging purposes. Don't actually copy these 2 lines! --> + <link href="/css/offcanvas.css" rel="stylesheet" type="text/css"><!-- Custom styles for this template --> + <link rel="stylesheet" href="/css/main.css"> + <!--[if lt IE 9]><script src="/js/ie8-responsive-file-warning.js"></script><![endif]--> + + <script src="/js/ie-emulation-modes-warning.js" type="text/javascript"> +</script><!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> + + <script src="/js/ie10-viewport-bug-workaround.js" type="text/javascript"> +</script><!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="/js/html5shiv.min.js"></script> + <script src="/js/respond.min.js"></script> + <![endif]--> + </head> + + <body> + <div class="container"> + <!-- Static navbar --> + <div class="navbar navbar-default" role="navigation"> + <div class="container-fluid"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <img class="navbar-brand" src="/img/OlingoOrangeTM.png" style="width:62px;" > + <a class="navbar-brand" href="#">Apache Olingoâ¢</a> + </div> + <div class="navbar-collapse collapse"> + <ul class="nav navbar-nav"> + + <li><a href="/">Home</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="http://www.apache.org/foundation/";>ASF Home</a></li> + <li><a href="http://projects.apache.org/";>Projects</a></li> + <li><a href="http://people.apache.org/";>People</a></li> + <li><a href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a></li> + <li><a href="http://www.apache.org/dyn/closer.cgi";>Download</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Support Apache</a></li> + </ul> + </li> + + <li><a href="http://www.apache.org/licenses/";>License</a></li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/download.html">Download OData 2.0 Java</a></li> + <li><a href="/doc/javascript/download.html">Download OData 4.0 JavaScript</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li><a href="/doc/odata2/index.html">Documentation OData 2.0 Java</a></li> + <li><a href="/doc/javascript/index.html">Documentation OData 4.0 JavaScript</a></li> + </ul> + </li> + <li><a href="/support.html">Support</a></li> + + </ul> + + <img class="navbar-right" height="50px" src="/img/asf-logo.gif"> + + </div><!--/.nav-collapse --> + </div><!--/.container-fluid --> + </div><!-- Main component for a primary marketing message or call to action --><h2 id="custom-odata-jpa-processor">Custom OData JPA Processor</h2> +<p>OData JPA Processor Library along with transforming an existing JPA model as EDM with no or minimalistic coding also processes the OData request and generates the OData response. However, at times it is required for an application using OData JPA Processor Library to perform some pre-processing of requests and post-processing of responses. To enable this in the application, following steps needs to be performed. </p> +<p>Custom OData JPA Processor is supported from Apache Olingo release 1.1.0 onwards.</p> +<p>a) Write a Custom OData JPA Processor by extending the class <code>org.apache.olingo.odata2.jpa.processor.api.ODataJPAProcessor</code>. In the code snippet below, pre-process and post-process are two private methods that can be written to process the request and response. The instance variable (part of ODataJPAProcessor) <code>jpaProcessor</code> can be used to process the OData request. The <code>jpaProcessor</code> returns the JPA entities after processing the OData request. The instance variable <code>responseBuilder</code> can be used for building the OData response from the processed JPA entities.</p> +<div class="codehilite"><pre> <span class="n">public</span> <span class="n">class</span> <span class="n">CustomODataJPAProcessor</span> <span class="n">extends</span> <span class="n">ODataJPAProcessor</span><span class="p">{</span> + + <span class="p">@</span><span class="n">Override</span> + <span class="n">public</span> <span class="n">ODataResponse</span> <span class="n">readEntitySet</span><span class="p">(</span><span class="n">final</span> <span class="n">GetEntitySetUriInfo</span> <span class="n">uriParserResultView</span><span class="p">,</span> <span class="n">final</span> <span class="n">String</span> <span class="n">contentType</span><span class="p">)</span> + <span class="n">throws</span> <span class="n">ODataException</span> <span class="p">{</span> + + <span class="o">/*</span> <span class="n">Pre</span> <span class="n">Process</span> <span class="n">Step</span> <span class="o">*/</span> + <span class="n">preprocess</span> <span class="p">(</span> <span class="p">);</span> + + <span class="n">List</span><span class="o"><</span><span class="n">Object</span><span class="o">></span> <span class="n">jpaEntities</span> <span class="p">=</span> <span class="n">jpaProcessor</span><span class="p">.</span><span class="n">process</span><span class="p">(</span><span class="n">uriParserResultView</span><span class="p">);</span> + + <span class="o">/*</span> <span class="n">Post</span> <span class="n">Process</span> <span class="n">Step</span> <span class="o">*/</span> + <span class="n">postProcess</span><span class="p">(</span> <span class="p">);</span> + + <span class="n">ODataResponse</span> <span class="n">oDataResponse</span> <span class="p">=</span> + <span class="n">responseBuilder</span><span class="p">.</span><span class="n">build</span><span class="p">(</span><span class="n">uriParserResultView</span><span class="p">,</span> <span class="n">jpaEntities</span><span class="p">,</span> <span class="n">contentType</span><span class="p">);</span> + + <span class="k">return</span> <span class="n">oDataResponse</span><span class="p">;</span> + <span class="p">}</span> + + <span class="p">}</span> +</pre></div> + + +<p>b) Write a Custom OData JPA Service Factory. Implement an OData JPA service factory to create an OData service with custom OData JPA Processor. The default service factory <code>org.apache.olingo.odata2.jpa.processor.api.ODataJPAServiceFactory</code> part of the library cannot be used. Hence, create a class by extending <code>org.apache.olingo.odata2.api.ODataServiceFactory</code>. Follow the steps below to hook an existing flow to a custom OData JPA Processor. Copy the entire code from <code>ODataJPAServiceFactory</code> and replace the code as shown below. </p> +<div class="codehilite"><pre> <span class="n">ODataSingleProcessor</span> <span class="n">odataJPAProcessor</span> <span class="p">=</span> <span class="n">accessFactory</span><span class="p">.</span><span class="n">createODataProcessor</span><span class="p">(</span><span class="n">oDataJPAContext</span><span class="p">);</span> + +<span class="n">with</span> + + <span class="n">ODataSingleProcessor</span> <span class="n">odataJPAProcessor</span> <span class="p">=</span> <span class="n">new</span> <span class="n">CustomODataJPAProcessor</span><span class="p">(</span><span class="n">oDataJPAContext</span><span class="p">);</span> +</pre></div><div align="center"> +<p>Copyright © 2013-2014, The Apache Software Foundation<br> + Apache Olingo, Olingo, Apache, the Apache feather, and + the Apache Olingo project logo are trademarks of the Apache Software + Foundation.</p> + <small><a href="/doc/odata2/privacy.html">Privacy</a></small> + </div> + </div><!-- /container --> + <!-- Bootstrap core JavaScript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="/js/jquery.js" type="text/javascript"> +</script> + <script src="/js/bootstrap.js" type="text/javascript"> + <script src="/js/offcanvas.js" type="text/javascript"> +</script> + <!-- Google Analytics: change UA-XXXXX-X to be your site's ID. --> + <script> + (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]= + function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date; + e=o.createElement(i);r=o.getElementsByTagName(i)[0]; + e.src='//www.google-analytics.com/analytics.js'; + r.parentNode.insertBefore(e,r)}(window,document,'script','ga')); + ga('create','UA-44963757-1');ga('send','pageview'); + </script> + </body> +</html>
