You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@olingo.apache.org by mi...@apache.org on 2014/09/16 14:33:57 UTC
svn commit: r1625261 [5/8] - in /olingo/site/trunk: content/
content/doc/odata2/ content/doc/odata2/tutorials/ content/doc/odata4/
content/doc/odata4/tutorials/ templates/
Added: olingo/site/trunk/content/doc/odata4/release.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/release.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/release.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/release.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,238 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# Apache Olingo Release Documentation
+
+---
+
+### Introduction
+
+This document describes the release guidelines for Apache Olingo. It heavily refers
+to [standard Apache procedures to release](http://maven.apache.org/developers/release/apache-release.html)
+ Maven based projects at Apache.
+
+### Build Environments
+
+Apache Olingo is built and released with [Maven3](http://maven.apache.org) and uses
+the <a href="http://svn.apache.org/repos/asf/maven/pom/tags/apache-13/pom.xml">Apache POM version 13</a>.
+
+### Release Artifacts
+
+An Apache Olingo release consists of:
+
+ * All POMs/JARs/WARs built as part of the standard Maven build process. For
+an overview on the released modules see artifacts with groupId
+_org.apache.olingo_ in the [Apache Maven Repository](https://repository.apache.org/index.html#nexus-search;gav~org.apache.olingo~~~~).
+In detail, per every module, where applicable, the following artifacts are produced:
+ * **Main artifact**: `<artifactId>-<version>.<ext>`
+ * **Source artifact**: `<artifactId>-<version>-sources.<ext>`
+ * **Javadoc artifact**: `<artifactId>-<version>-javadoc.<ext>`
+ * **POM**: `<artifactId>-<version>.pom`
+
+
+ Also the following additional *distribution commodity packages* are
+provided as part of the release:
+
+ * `Olingo-OData-${version}-source-release.${ext}` <br/> A source-release
+bundle containing all files the sources necessary to build all other artifacts. <br/> **Package formats**: zip.
+
+ * `Olingo-OData-JavaDoc-${version}-javadoc.${ext}` <br/> A bundle
+containing JavaDoc of the OData4 library API and annotations, the
+JPA processor API as well as additional documentation and reference scenario
+examples. <br/> **Package formats**: zip.
+
+ * `Olingo-OData-Server-for-Java-${version}-lib.${ext}` <br/> A bundle containing the OData4 core
+library and dependencies required to implement an OData V4 Java server/processor. <br/> **Package formats**: zip.
+
+ * `Olingo-OData-Client-for-Java-${version}-jpa.${ext}` <br/> A bundle containing the OData4 client library
+ and dependencies required to implement an OData V4 Java client. <br/> **Package formats**: zip.
+
+ * `Olingo-OData-Client-for-Android-${version}-lib.${ext}` <br/> A bundle containing the OData4 client library
+and dependencies required to implement an OData V4 client for Android devices. <br/> **Package formats**: zip.
+
+### Documentation and JavaDoc
+
+The documentation that will be part of the release must match the code.
+All examples in the documentation must work. The Java package documentation must be
+up-to-date. Release independend documentation is maintained on the [Apache Olingo Documentation][1] page.
+
+### Preparation
+
+##### Release Manager
+
+A release manager must be appointed for a release. He or she is in charge of the release process,
+following the guidelines and eventually generating the release artifacts.
+The release manager might tailor the process for a specific release.
+
+##### Version
+
+The Olingo community decides if the release will be a major or a minor release and
+agrees on a version number.
+
+ mvn versions:set -DnewVersion=1.0.0-RC01
+ find . -name '*.versionsBackup' -type f -delete
+ git add .
+ git commit -am 'Issue OLINGO-25 - make release - set version 4.0.0-RC01'
+ git tag -f 4.0.0-RC01
+
+ mvn versions:set -DnewVersion=4.1.0-SNAPSHOT
+ find . -name '*.versionsBackup' -type f -delete
+ git add .
+ git commit -am 'Issue OLINGO-25 - make release - set version 4.1.0-SNAPSHOT'
+ git push
+ git push --tags
+
+
+##### Open Issues
+
+There must not be any open JIRA issues for this release. There might be open issues for
+future releases. Check with: [fix for version view][2]
+
+##### Unit Tests and Integration Tests
+
+All unit tests and integration tests must succeed on a
+clean machine (starting with an empty local Maven repository). The following Maven
+execution will run all unit and integration tests:
+
+ mvn clean install
+
+##### Apache License and Code Style
+
+Each source code file must have a current ASF license header. The source
+code should follow the Apache Olingo code style. For verification run following
+Maven execution
+
+ mvn clean install -Pbuild.quality
+
+##### Packaging
+
+NOTICE, LICENSE and DISCLAIMER must be present in all bundles and must be up-to-date.
+
+Remote resources are provided by the ASF and the Maven `remote-resources-plugin` is
+configured in the parent pom of the project.
+
+ :::xml
+ <resourceBundle>org.apache:apache-jar-resource-bundle:1.4</resourceBundle>
+ <resourceBundle>org.apache:apache-disclaimer-resource-bundle:1.1</resourceBundle>
+
+The Maven module `odata-dist` (in project sub-folder `dist`) is responsible to package convenience distribution zip files
+using the assembly plugin. The distributions are created with a release build `mvn clean install -Papache-release -Dgpg.passphrase="yourPassphraseHere"`
+
+##### MD5 and SHA for distribution packages
+
+MD5 and SHA files are created manually for distribution packages:
+
+ openssl md5 < ${filename}.zip > ${filename}.zip.md5
+ gpg --print-md SHA512 ${filename}.zip > ${filename}.zip.sha512
+
+
+##### Release Tag
+
+A tag has to be created for every release candidate. The naming rule
+for the tags is `${version}-RCxx`. This is created as
+part of the Maven release process. The tag will be renamed to the
+final version number upon vote approval.
+
+##### Release Branch
+
+A branch has to be created for every release. The naming rule for this
+branch is `${version}`. This has to be created manually upon release approval.
+
+### Release Candidate
+
+Once all preparations are done, a release candidate will be built.
+
+All release candidates must be cryptographically signed. The string
+"`-RCxx`" will be attached to the version number of the release candidate
+artifacts, where is the number of the release candidate starting with 01.
+If more than one release candidate is required a new tag has to be created
+and release candidate number will be increased by one.
+
+The release candidate artifacts:
+
+ - Maven artifacts will be staged on repository.apache.org. A new staging repo
+is created per RC and will be communicated upon release.
+ - Distribution commodity packages are staged at
+http://people.apache.org/~[username]/olingo2/[version] (e.g. http://people.apache.org/~mibo/olingo2/2.0.0-RC01)
+
+Once candidate artifacts are available, release manager kicks off the [VOTE process][3].
+
+If the vote fails, the raised issues will be fixed, a new release candidate will be
+built and the VOTE process will be restarted.
+
+If the release candidate gets approved, we can proceed to release publishing.
+
+#### How to verify a Release Candidate
+
+This checklist helps verifying if a release candidate is valid:
+
+* Are all files on "http://people.apache.org/~[username]/olingo2/[version]"?
+* Check if md5, sha512 and asc files are filled correctly?
+* Can the zip files be unpacked without issues?
+* Execute a "mvn clean install -Pbuild.quality" on parent distribution. It should work without issues.
+* Does the JavaDoc only contain API documentation?
+* Is there a Disclaimer, Notice, License and Dependencies File in every folder?
+* Do all License files contain the right amount of licenses?
+* Do Notice files mention 3rd party libraries if they are contained in the distribution?
+
+After all questions of this checklist can be answered with yes it is OK to give a +1 on the mailing list.
+Of course the Release Manager can also use this checklist to make sure all artifacts are correct before publishing the results on the mailing list.
+
+
+### Publishing the Release
+
+If the release candidate gets approved, we can proceed to release publishing:
+
+ - Release candidate maven artifacts are promoted in the Apache Maven Repository and
+made available [here](https://repository.apache.org/index.html#nexus-search;gav~org.apache.olingo~~~~).
+ - Publish final release Version to [Apache Repository](https://repository.apache.org/)
+ - First publish via `mvn deploy -Papache-release` into the *Staging Area*
+ - From *Staging Area* close and release the staged Artifacts to finish publishing
+ - Afterwards the Maven artifacts are automatically synced to [Maven Central](http://search.maven.org/#search|ga|1|org.apache.olingo).
+ - Release candidate commodity packages are synced (together with their checksum and
+signatures) to [Apache Distributions](http://www.apache.org/dist/olingo/).
+ - Release tag is renamed to final version.
+ - Release branch is created.
+ - Release is closed in Jira.
+ - Release is announced to dev@olingo.apache.org, announce@apache.org.
+
+### Maintain Version Section in DOAP File
+
+[http://olingo.apache.org/doap_Olingo.rdf][4]
+
+Results are shown here:
+
+[link text][5]
+
+### Additional Apache Release Information
+
+ - [Releases Policy][6]
+ - [Publishing Releases][7]
+ - [Publishing Maven Artifacts][8]
+ - [Release Management During Incubation][9]
+
+
+ [1]: http://olingo.apache.org/documentation.html
+ [2]: https://issues.apache.org/jira/browse/OLINGO/fixforversion/12324804
+ [3]: http://incubator.apache.org/guides/releasemanagement.html#best-practice-incubator-release-vote
+ [4]: http://olingo.apache.org/doap_Olingo.rdf
+ [5]: http://projects.apache.org/indexes/alpha.html#O
+ [6]: http://www.apache.org/dev/release.html
+ [7]: http://www.apache.org/dev/release-publishing.html
+ [8]: http://www.apache.org/dev/publishing-maven-artifacts.html
+ [9]: http://incubator.apache.org/guides/releasemanagement.html
Added: olingo/site/trunk/content/doc/odata4/sample-setup.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/sample-setup.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/sample-setup.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/sample-setup.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,30 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# Sample Project Setup
+
+Olingo has prepared a very simple sample car service that can work as a starting point for implementing a custom OData service.
+This service consists of a very simple EDM with two entity sets that are cars and manufactures and a memory based data provider that is a simple hash map.
+Therefore the project implements a very basic single OData processor supporting a minimal readonly scenario.
+If build with Maven the build result is a web application (`war` file) which can be deployed to any JEE compliant web application server (e.g. [Tomcat](http://tomcat.apache.org)).
+
+---
+
+### Maven Archetype
+
+**TBD**
Added: olingo/site/trunk/content/doc/odata4/tomcat.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tomcat.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tomcat.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/tomcat.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,29 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+### Run with Tomcat
+Necessary steps to get your project run with [Tomcat](http://tomcat.apache.org/index.html) (tested with version `7.0.32`).
+
+#### Required steps
+ * Download Tomcat 7.0.x from [Tomcat Downloads](http://tomcat.apache.org/download-70.cgi)
+ * Install Tomcat as described in [Tomcat Documentation](http://tomcat.apache.org/tomcat-7.0-doc/setup.html)
+ * Start Tomcat e.g. via `$TOMCAT_HOME/bin/startup.sh` (Linux) or `$TOMCAT_HOME/bin/startup.bat` (Windows)
+ * Build of OData Application
+ * Build your `WAR` file of your own project
+ * Deployment of the OData Application via simple copy of created `WAR` from the web project `./target` folder (for the technical scenario in version `4.0.0-beta-01` it is `$ODATA_PROJECT_HOME/lib/server-tec-svc/target/odata-server-tecsvc-4.0.0-beta-01.war`) into `$TOMCAT_HOME/webapps`
+ * After successful deployment for the sample project just open following link: http://localhost:8080/odata-server-tecsvc-4.0.0-beta-01 to see the project entry site.
Added: olingo/site/trunk/content/doc/odata4/tutorials/AnnotationProcessorExtension.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/AnnotationProcessorExtension.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/AnnotationProcessorExtension.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/tutorials/AnnotationProcessorExtension.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,381 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# Creating a Web Application with the Annotation Processor Extension
+
+### Shortcut: Creation via Archetype
+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:
+
+ mvn archetype:generate \
+ -DinteractiveMode=false \
+ -Dversion=1.0.0-SNAPSHOT \
+ -DgroupId=com.sample \
+ -DartifactId=my-car-service \
+ -DarchetypeGroupId=org.apache.olingo \
+ -DarchetypeArtifactId=olingo-odata2-sample-cars-annotation-archetype \
+ -DarchetypeVersion=2.0.0
+
+In the generated sample project you now can simply run Maven with the default goal (run `mvn` in the shell) which compiles the sources and starts an Jetty web server at `http://localhost:8080`.
+
+For more detailed documentation about Archetypes in Olingo take a look into the [sample setup](/doc/odata2/sample-setup) section.
+
+### Creation from Scratch
+A project which use the Annotation Processor Extension consists mainly of the model beans, the `ODataServiceFactory` implementation and the web resources (e.g. `web.xml`).
+In addition we use Maven so that it is necessary to create a `pom.xml` for project build information and dependency resolution.
+
+##### Create Maven Project structure
+To start a folder is created (e.g. *annotation-from-scratch*) which contains the Maven project.
+Within this the default Maven project structure is used, which looks like:
+
+ ./src/main/java
+ ./src/main/resources
+ ./src/main/webapp
+
+##### Create Maven pom.xml
+After creation of the project structure the default `pom.xml` for building of an `WAR-File` have to be created.
+In addition we need the dependency to all necessary _Apache Olingo artifacts_ and to the used `JAX-RS` implementation which in this sample is `Apache CXF`.
+
+The resulting `pom.xml` then looks like:
+
+ :::xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>cars-annotations-sample</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <name>${project.artifactId}</name>
+
+ <packaging>war</packaging>
+
+ <properties>
+ <!-- Dependency Versions -->
+ <version.cxf>2.7.6</version.cxf>
+ <version.servlet-api>2.5</version.servlet-api>
+ <version.jaxrs-api>2.0-m10</version.jaxrs-api>
+ <version.olingo>2.0.0</version.olingo>
+ </properties>
+
+ <build>
+ <finalName>${project.artifactId}</finalName>
+ <defaultGoal>clean package</defaultGoal>
+ </build>
+
+ <dependencies>
+ <!-- Apache Olingo Library dependencies -->
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-api</artifactId>
+ <version>${version.olingo}</version>
+ </dependency>
+ <dependency>
+ <artifactId>olingo-odata2-api-annotation</artifactId>
+ <groupId>org.apache.olingo</groupId>
+ <type>jar</type>
+ <version>${version.olingo}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-core</artifactId>
+ <version>${version.olingo}</version>
+ </dependency>
+ <!-- Apache Olingo Annotation Processor Extension dependencies -->
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-annotation-processor-api</artifactId>
+ <version>${version.olingo}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-annotation-processor-core</artifactId>
+ <version>${version.olingo}</version>
+ </dependency>
+ <!-- Servlet/REST dependencies -->
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>servlet-api</artifactId>
+ <version>${version.servlet-api}</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>javax.ws.rs</groupId>
+ <artifactId>javax.ws.rs-api</artifactId>
+ <version>${version.jaxrs-api}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.cxf</groupId>
+ <artifactId>cxf-rt-frontend-jaxrs</artifactId>
+ <version>${version.cxf}</version>
+ </dependency>
+ </dependencies>
+ </project>
+
+
+##### Create Sample (Entity) Model
+
+For this sample a simple model with the two entities _Manufacturer_ and _Car_ is created.
+
+The _Manufacturer_ consists of an `Id`, `Name`, `Founded` and a relation to a list of its `Cars`.
+The _Car_ consists of an `Id`, `Model`, `ProductionYear`, `Price` and a relation to its `Manufacturer`.
+
+**Create Java Beans for Entities**
+For each of both entities first a java bean (_POJO_) is created in the package `org.apache.olingo.sample.annotation.model` (which results in a created folder `src/main/java/org/apache/olingo/sample/annotation/model/`) which looks like:
+
+ :::java
+ package org.apache.olingo.sample.annotation.model;
+
+ /** required Imports */
+
+ public class Manufacturer {
+ private String id;
+ private String name;
+ private Calendar founded;
+ private List<Car> cars = new ArrayList<Car>();
+
+ /** optional getter and setter */
+ }
+
+and:
+
+ :::java
+ package org.apache.olingo.sample.annotation.model;
+
+ /** required Imports */
+
+ public class Car {
+ private String id;
+ private String model;
+ private Double price;
+ private Integer productionYear;
+ private Manufacturer manufacturer;
+
+ /** optional getter and setter */
+ }
+
+**Annotated created Java Beans**
+Now those beans have to be annotated with the annotations of the _Annotation Processor Extension_.
+
+Both beans needs at first the `@EdmEntityType` and `@EdmEntitySet` annotation to define that they represent an OData Entity. These annotation must be added at the bean class which as example for the _Manufacturer_ then look like:
+
+ :::java
+ @EdmEntityType
+ @EdmEntitySet
+ public class Manufacturer { /** more code */ }
+
+Then all simple properties of the Entity must be annotated with `@EdmProperty`, the _Key_ for the Entity additional must be annotated with `@EdmKey` which is in this sample the `Id` field of the entities.
+
+For the _Manufacturer_ it then look like:
+
+ :::java
+ @EdmEntityType
+ @EdmEntitySet
+ public class Manufacturer {
+ @EdmKey
+ @EdmProperty
+ private String id;
+ @EdmProperty
+ private String name;
+ @EdmProperty
+ private Calendar founded;
+
+ /** more code */
+ }
+
+A relation to another Entity must be annotated with `@EdmNavigationProperty`. In this sample this are the bi-directional relation between a _Manufacturer_ and its _Cars_.
+
+For the _Manufacturer_ the added annotation look like:
+
+ :::java
+ @EdmEntityType
+ @EdmEntitySet
+ public class Manufacturer {
+ /** more code */
+
+ @EdmNavigationProperty
+ private List<Car> cars = new ArrayList<Car>();
+
+ /** more code */
+ }
+
+
+The complete resulting Entities (POJOs) then look like:
+
+ :::java
+ package org.apache.olingo.sample.annotation.model;
+
+ import java.util.*;
+ import org.apache.olingo.odata2.api.annotation.edm.*;
+
+ @EdmEntityType
+ @EdmEntitySet
+ public class Manufacturer {
+ @EdmKey
+ @EdmProperty
+ private String id;
+ @EdmProperty
+ private String name;
+ @EdmProperty
+ private Calendar founded;
+ @EdmNavigationProperty
+ private List<Car> cars = new ArrayList<Car>();
+
+ /** optional getter and setter */
+ }
+
+and
+
+ :::java
+ package org.apache.olingo.sample.annotation.model;
+
+ import org.apache.olingo.odata2.api.annotation.edm.*;
+
+ @EdmEntityType
+ @EdmEntitySet
+ public class Car {
+ @EdmKey
+ @EdmProperty
+ private String id;
+ @EdmProperty
+ private String model;
+ @EdmProperty
+ private Double price;
+ @EdmProperty
+ private Integer productionYear;
+ @EdmNavigationProperty
+ private Manufacturer manufacturer;
+
+ /** optional getter and setter */
+ }
+
+
+The next step is to create the `ODataService`.
+
+##### Create ODataService
+The `ODataService` is created via an `ODataServiceFactory` implementation.
+For the sample a `AnnotationSampleServiceFactory` in the package `org.apache.olingo.sample.annotation.processor` (which results in a created folder `src/main/java/org/apache/olingo/sample/annotation/processor/`) is created which extends the `ODataServiceFactory`. The resulting code look like:
+
+ :::java
+ package org.apache.olingo.sample.annotation.processor;
+
+ /** required Imports */
+
+ public class AnnotationSampleServiceFactory extends ODataServiceFactory {
+ @Override
+ public ODataService createService(final ODataContext context) throws ODataException {
+ return null;
+ }
+ }
+
+
+In the `createService(...)` method now the `ODataService` needs to be created.
+The _Annotation Processor Extension_ provides therefore the method `createAnnotationService(...)` within the `AnnotationServiceFactory` which can be used. This method require as parameter the _Package_ which contains the _Model_ in form of annotated POJOs (as created in the section _Create the Model_).
+
+For a persistence between several request it is necessary to hold the created `ODataService` in an static instance. In the sample the [Initialization on demand holder idiom](http://en.wikipedia.org/wiki/Initialization-on-demand_holder_idiom) is used.
+
+As result the implementation look like:
+
+ :::java
+ package org.apache.olingo.sample.annotation.processor;
+
+ import org.apache.olingo.odata2.api.*;
+ import org.apache.olingo.odata2.api.exception.*;
+ import org.apache.olingo.odata2.api.processor.ODataContext;
+ import org.apache.olingo.odata2.annotation.processor.api.AnnotationServiceFactory;
+
+ public class AnnotationSampleServiceFactory extends ODataServiceFactory {
+
+ /**
+ * Instance holder for all annotation relevant instances which should be used as singleton
+ * instances within the ODataApplication (ODataService)
+ */
+ private static class AnnotationInstances {
+ final static String MODEL_PACKAGE = "org.apache.olingo.sample.annotation.model";
+ final static ODataService ANNOTATION_ODATA_SERVICE;
+
+ static {
+ try {
+ ANNOTATION_ODATA_SERVICE = AnnotationServiceFactory.createAnnotationService(MODEL_PACKAGE);
+ } catch (ODataApplicationException ex) {
+ throw new RuntimeException("Exception during sample data generation.", ex);
+ } catch (ODataException ex) {
+ throw new RuntimeException("Exception during data source initialization generation.", ex);
+ }
+ }
+ }
+
+ public ODataService createService(final ODataContext context) throws ODataException {
+ return AnnotationInstances.ANNOTATION_ODATA_SERVICE;
+ }
+ }
+
+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.
+
+##### Create Web Application resources
+To deploy and run the application on an application server it is necessary to provide a `web.xml` which defines the `JAX-RS` entry point which then calls the sample application.
+
+For this sample `Apache CXF` is used (see `<servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class>`) which need as parameter the `javax.ws.rs.Application` and the `org.apache.olingo.odata2.service.factory`.
+
+Therefore the `web.xml` is created in the `src/main/webapp/WEB-INF` folder with following content:
+
+ :::xml
+ <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ id="WebApp_ID" version="2.5">
+ <display-name>org.apache.olingo.sample.annotation</display-name>
+ <servlet>
+ <servlet-name>ServiceServlet</servlet-name>
+ <servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class>
+ <init-param>
+ <param-name>javax.ws.rs.Application</param-name>
+ <param-value>org.apache.olingo.odata2.core.rest.app.ODataApplication</param-value>
+ </init-param>
+ <init-param>
+ <param-name>org.apache.olingo.odata2.service.factory</param-name>
+ <param-value>org.apache.olingo.sample.annotation.processor.AnnotationSampleServiceFactory</param-value>
+ </init-param>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>ServiceServlet</servlet-name>
+ <url-pattern>/AnnotationSample.svc/*</url-pattern>
+ </servlet-mapping>
+ </web-app>
+
+
+##### Deploy and Run
+Build the project with maven via `mvm clean package` and copy the resulting `WAR-File` from the projects `target` folder in the `deploy` folder of the web application server (e.g. a [Tomcat](http://tomcat.apache.org/)).
+As example for a default Tomcat 7.x installation `cp $PROJECT_HOME/target/cars-annotations-sample.war $TOMCAT_HOME/webapps`.
+
+After starting the web application server it is possible to request...
+
+ * ...the *Service Document* via the URL: [http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/](http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/)
+ * ...the *Metadata* via the URL: [http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/$metadata](http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/$metadata)
+ * ...the *Cars* EntitySet via the URL: [http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/CarSet](http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/CarSet)
+ * ...the *Manufacturer* EntitySet via the URL: [http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/ManufacturerSet](http://localhost:8080/cars-annotations-sample/AnnotationSample.svc/ManufacturerSet)
+
+Also it is possible to create *Car* and *Manufacturer* Entities via `HTTP POST` requests.
+
+### More detailed look
+
+A more detailed look into the Annotation Processor Extension can be found in the [wiki](https://wiki.apache.org/Olingo/Documentation/AnnotationProcessor).
\ No newline at end of file
Added: olingo/site/trunk/content/doc/odata4/tutorials/CreateWebApp.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/CreateWebApp.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/CreateWebApp.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/tutorials/CreateWebApp.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,183 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+## Creating a Web Application Project for Transforming JPA Models into OData Services
+
+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.
+
+*Note*: 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.
+
+
+Group ID | Artifact ID | Version
+---------| ----------- | -------
+javax.servlet | servlet-api | 2.5
+org.apache.cxf | cxf-rt-frontend-jaxrs | 2.7.5
+org.slf4j | slf4j-log4j12 | 1.7.1
+junit | junit | 3.8.1
+org.apache.olingo | olingo.odata2.api | 1.0.0
+org.apache.olingo | olingo.odata2.jpa.processor.api | 1.0.0
+org.apache.olingo | olingo.odata2.jpa.processor.core | 1.0.0
+org.apache.olingo | olingo.odata2.jpa.processor.ref | 1.0.0
+org.apache.olingo | olingo.odata2.core | 1.0.0
+org.eclipse.persistence | eclipselink | 2.3.1
+org.eclipse.persistence | javax.persistence | 2.0.5
+org.hsqldb | hsqldb | 2.2.8
+
+
+
+Here is a [Sample JPA Model][1]
+
+
+##### Create a Dynamic Web Application Project from Scratch:
+
+1. In the command prompt, enter the maven command given here (change the DgroupId and DartifactId as per your requirement)
+
+ mvn archetype:generate -DgroupId=com.sample.jpa -DartifactId=salesorderprocessing.app -DarchetypeArtifactId=maven-archetype-webapp
+
+ 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.
+
+2. Create a folder by name 'java' in the path 'src/main/'.
+
+##### Tailor POM.xml
+
+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:
+
+ <?xml version="1.0" ?>
+ <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-parent</artifactId>
+ <version>1.0.0</version>
+ <relativePath>..</relativePath>
+ </parent>
+ <artifactId>olingo.odata2.jpa.processor.ref.web</artifactId>
+ <packaging>war</packaging>
+ <name>${project.groupId}-${project.artifactId}</name>
+ <dependencies>
+ <dependency>
+ <!-- required because of auto detection of web facet 2.5 -->
+ <groupId>javax.servlet</groupId>
+ <artifactId>servlet-api</artifactId>
+ <version>2.5</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.cxf</groupId>
+ <artifactId>cxf-rt-frontend-jaxrs</artifactId>
+ <version>2.7.5</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-core</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-api</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-jpa-processor-api</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-jpa-processor-core</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.olingo</groupId>
+ <artifactId>olingo-odata2-jpa-processor-ref</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-log4j12</artifactId>
+ <version>1.7.1</version>
+ </dependency>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.eclipse.persistence</groupId>
+ <artifactId>eclipselink</artifactId>
+ <version>2.3.1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.eclipse.persistence</groupId>
+ <artifactId>javax.persistence</artifactId>
+ <version>2.0.5</version>
+ </dependency>
+ <dependency>
+ <groupId>org.hsqldb</groupId>
+ <artifactId>hsqldb</artifactId>
+ <version>2.2.8</version>
+ </dependency>
+ </dependencies>
+ <build>
+ <finalName>olingo.odata2.jpa.processor.ref.web</finalName>
+ </build>
+ </project>
+
+##### Implement an OData Service
+
+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:
+
+1. Add a new Java class by extending ODataJPAServiceFactory.
+2. Declare persistence unit name as class variable. For example, private static final String PUNIT_NAME = "persistenceUnitName";
+ *Note*: The PUNIT_NAME refers to the persistence unit name maintained in the persistence.xml of JPA project.
+3. Implement the abstract method `initializeODataJPAContext`. Here is the code snippet:
+
+ ODataJPAContext oDataJPAContext = getODataJPAContext();
+ oDataJPAContext.setEntityManagerFactory(JPAEntityManagerFactory.getEntityManagerFactory(PUNIT_NAME));
+ oDataJPAContext.setPersistenceUnitName(PUNIT_NAME);
+
+##### Configure the Web Application
+
+1. 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.
+2. Replace in the following XML with the class name you created in the previous step:
+
+ - <servlet>
+ <servlet-name>JPARefScenarioServlet</servlet-name>
+ <servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class>
+ - <init-param>
+ <param-name>javax.ws.rs.Application</param-name>
+ <param-value>org.apache.olingo.odata2.core.rest.app.ODataApplication</param-value>
+ </init-param>
+ - <init-param>
+ <param-name>org.apache.olingo.odata2.service.factory</param-name>
+ <param-value>org.apache.olingo.odata2.jpa.processor.ref.web.JPAReferenceServiceFactory</param-value>
+ </init-param>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+ - <servlet-mapping>
+ <servlet-name>JPARefScenarioServlet</servlet-name>
+ <url-pattern>/SalesOrderProcessing.svc/*</url-pattern>
+ </servlet-mapping>
+
+After the implementation, test the web application using http://localhost:8080/olingo.odata2.jpa.processor.ref.web/SalesOrderProcessing.svc
+
+
+
+ [1]: https://cms.apache.org/olingo/wc/browse/deepa-udCb40/trunk/content/resources/SampleJPAModel
\ No newline at end of file
Added: olingo/site/trunk/content/doc/odata4/tutorials/CustomODataJPAProcessor.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/CustomODataJPAProcessor.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/CustomODataJPAProcessor.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/tutorials/CustomODataJPAProcessor.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,54 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+## Custom OData JPA Processor
+
+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.
+
+Custom OData JPA Processor is supported from Apache Olingo release 1.1.0 onwards.
+
+a) Write a Custom OData JPA Processor by extending the class `org.apache.olingo.odata2.jpa.processor.api.ODataJPAProcessor`. 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) `jpaProcessor` can be used to process the OData request. The `jpaProcessor` returns the JPA entities after processing the OData request. The instance variable `responseBuilder` can be used for building the OData response from the processed JPA entities.
+
+ public class CustomODataJPAProcessor extends ODataJPAProcessor{
+
+ @Override
+ public ODataResponse readEntitySet(final GetEntitySetUriInfo uriParserResultView, final String contentType)
+ throws ODataException {
+
+ /* Pre Process Step */
+ preprocess ( );
+
+ List<Object> jpaEntities = jpaProcessor.process(uriParserResultView);
+
+ /* Post Process Step */
+ postProcess( );
+
+ ODataResponse oDataResponse =
+ responseBuilder.build(uriParserResultView, jpaEntities, contentType);
+
+ return oDataResponse;
+ }
+
+ }
+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 `org.apache.olingo.odata2.jpa.processor.api.ODataJPAServiceFactory` part of the library cannot be used. Hence, create a class by extending `org.apache.olingo.odata2.api.ODataServiceFactory`. Follow the steps below to hook an existing flow to a custom OData JPA Processor. Copy the entire code from `ODataJPAServiceFactory` and replace the code as shown below.
+
+ ODataSingleProcessor odataJPAProcessor = accessFactory.createODataProcessor(oDataJPAContext);
+
+ with
+
+ ODataSingleProcessor odataJPAProcessor = new CustomODataJPAProcessor(oDataJPAContext);
\ No newline at end of file
Added: olingo/site/trunk/content/doc/odata4/tutorials/DeltaQuerySupport.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/DeltaQuerySupport.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/DeltaQuerySupport.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/tutorials/DeltaQuerySupport.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,107 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+## Delta Token Support
+
+Delta Query retrieves the changes done to a service. It is supported in OData JPA Processor Library from version 1.4.0. The data returned by the feed for the query would look exactly like any other dataset for an OData query but with delta link at the end.
+
+There are two approaches you can follow to generate delta token.
+
+
+### Generating Delta Token
+##### First Approach
+
+a. Create a Java class by extending `ODataJPATombstoneEntityListener.java`.
+
+b. Implement the abstract method `getQuery`. In the method, implement the logic to generate a `javax.persistence.Query`. The Query object can be created as shown below in the code snippet.
+
+ if (!resultsView.getStartEntitySet().getName().equals(resultsView.getTargetEntitySet().getName())) {
+ contextType = JPQLContextType.JOIN;
+ } else {
+ contextType = JPQLContextType.SELECT;
+ }
+
+ JPQLContext jpqlContext = JPQLContext.createBuilder(contextType, resultsView).build();
+ JPQLStatement jpqlStatement = JPQLStatement.createBuilder(jpqlContext).build();
+
+ Query query = em.createQuery(jpqlStatement);
+
+ The `JPQLStatement` is generated based on the OData request (resultsView). The generated `JPQLStatement` can be enhanced to introduce conditions that filters and fetches delta JPA Entities. To enhance the `JPQLStatement` and add a condition to the WHERE Clause, refer to the following code snippet.
+
+ *Note*: It is up to the JPA application developers to come up with a logic suitable for their use case.
+
+ String deltaToken = ODataJPATombstoneContext.getDeltaToken();
+
+ Query query = null;
+ if (deltaToken != null) {
+ String statement = jpqlStatement.toString();
+ String[] statementParts = statement.split(JPQLStatement.KEYWORD.WHERE);
+ String deltaCondition = jpqlContext.getJPAEntityAlias() + ".creationDate >= {ts '" + deltaToken + "'}";
+ if (statementParts.length > 1)
+ {
+ statement = statementParts[0] + JPQLStatement.DELIMITER.SPACE + JPQLStatement.KEYWORD.WHERE + JPQLStatement.DELIMITER.SPACE + deltaCondition + JPQLStatement.DELIMITER.SPACE + JPQLStatement.Operator.AND + statementParts[1];
+ }
+ else {
+ statement = statementParts[0] + JPQLStatement.DELIMITER.SPACE + JPQLStatement.KEYWORD.WHERE + JPQLStatement.DELIMITER.SPACE + deltaCondition;
+ }
+
+ query = em.createQuery(statement);
+ }
+ else
+ query = em.createQuery(jpqlStatement.toString());
+
+c. Implement the method `generateDeltaToken` to generate a string representation of the delta token. The delta token generated shall be used by the client applications to fetch delta in their subsequent OData requests.
+
+ SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.000");;
+ Date date = new Date(System.currentTimeMillis());
+ dateFormat.format(date);
+ return dateFormat.format(date);
+
+d. Register the class (created above) as an Entity Listener in JPA Entity.
+
+ @Entity
+ @Table(name = "T_SALESORDERHEADER")
+ @EntityListeners(com.sap.core.odata.processor.ref.jpa.listners.SalesOrderTombstoneListner.class)
+ public class SalesOrderHeader {
+
+
+##### Second Approach
+
+The OData JPA Processor Library also provides support so that the JPA application developer can write a call back method in the Entity Listener class and annotate them with `javax.persistence.PostLoad`. Such call back methods are executed by JPA providers in a stateless manner for every record fetched from the database table. In the call back method, logic can be provided to decide whether a JPA entity fetched from the database table is a delta or not as shown below:
+
+ @PostLoad
+ public void handleDelta(Object entity) {
+ SalesOrderHeader so = (SalesOrderHeader) entity;
+ if (so.getCreationDate().getTime() < ODataJPATombstoneContext.getDeltaTokenUTCTimeStamp())
+ return;
+ else
+ addToDelta(entity,ENTITY_NAME);
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
Added: olingo/site/trunk/content/doc/odata4/tutorials/ExtendingtheEDM.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/ExtendingtheEDM.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/ExtendingtheEDM.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/tutorials/ExtendingtheEDM.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,94 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# Extending the EDM Generated from the JPA Models
+
+The Entity Data Model (EDM) generated from the JPA models can be extended with new Entity Types, Complex Types and also the existing EDM elements can be modified by implementing the interface method `org.apache.olingo.odata2.jpa.processor.api.model.JPAEdmExtension.extendJPAEdmSchema`.
+
+Link to the code - [Support EDM Extension][1]
+
+#### How to Add a Complex Type to an EDM
+
+Consider a scenario where we have a Plain Old Java Object (POJO) in the OrderValue Java class and let us try to transform this POJO into a Complex Type in the EDM.
+
+###### POJO in OrderValue Java Class
+
+ public class OrderValue
+ {
+
+ private double amount;
+ private String currency;
+
+ public double getAmount()
+
+ { return amount; }
+ public void setAmount(double amount)
+
+ { this.amount = amount; }
+ public String getCurrency()
+
+ { return currency; }
+ public void setCurrency(String currency)
+
+ { this.currency = currency; }
+
+ }
+
+
+Here is an example where the `SalesOrderProcessingExtension` implements the `JPAEdmExtension`.
+
+##### Sample Code
+
+ @Override
+ public void extendJPAEdmSchema(final JPAEdmSchemaView view) {
+ Schema edmSchema = view.getEdmSchema();
+ edmSchema.getComplexTypes().add(getComplexType());
+ }
+
+ private ComplexType getComplexType() {
+ ComplexType complexType = new ComplexType();
+
+ List<Property> properties = new ArrayList<Property>();
+ SimpleProperty property = new SimpleProperty();
+
+ property.setName("Amount");
+ property.setType(EdmSimpleTypeKind.Double);
+ properties.add(property);
+
+ property = new SimpleProperty();
+ property.setName("Currency");
+ property.setType(EdmSimpleTypeKind.String);
+ properties.add(property);
+
+ complexType.setName("OrderValue");
+ complexType.setProperties(properties);
+
+ return complexType;
+
+ }
+
+You need to set your `JPAEDMExtension` type in the `initializeODataJPAContext` of `JPAReferenceServiceFactory`.
+
+The Complex Type added to the EDM can be used as Function Imports Return Type. See [Adding Function Imports to OData Services][2] for more information.
+
+
+
+
+
+ [1]: https://git-wip-us.apache.org/repos/asf?p=olingo-odata2.git;a=blob;f=odata2-jpa-processor/jpa-web/src/main/java/org/apache/olingo/odata2/jpa/processor/ref/extension/SalesOrderProcessingExtension.java;h=3dacd7e727528cb79cb3d4a878ac53d0a4b25277;hb=ecdc476
+ [2]: http://olingo.incubator.apache.org/doc/odata2/tutorials/jpafunctionimport.html
\ No newline at end of file
Added: olingo/site/trunk/content/doc/odata4/tutorials/HandlingClobAndBlob.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/HandlingClobAndBlob.mdtext?rev=1625261&view=auto
==============================================================================
--- olingo/site/trunk/content/doc/odata4/tutorials/HandlingClobAndBlob.mdtext (added)
+++ olingo/site/trunk/content/doc/odata4/tutorials/HandlingClobAndBlob.mdtext Tue Sep 16 12:33:56 2014
@@ -0,0 +1,107 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+## Handling BLOB and CLOB Data Types
+
+JPA entities can have properties that are of type `java.sql.Blob` or `java.sql.Clob`. Internally, JPA entities can instantiate a JPA provider (Eclipse Link or Hibernate or ...) specific implementation
+of the above two interfaces and bind them to the properties. To enable write on such properties using OData JPA Processor Library, an additional access modifier is required to be added to the JPA
+entities. Following is the proposal on how OData JPA Processor Library handles `java.sql.Blob` and `java.sql.Clob` during metadata generation and runtime processing.
+
+### EDM Generation
+
+Based on the JPA entity property type, the pseudocode for generating the EDM is as below.
+
+**For `java.sql.Blob`**:
+
+1. Check if JPA entity property is of type byte[] or of type java.sql.Blob and annotated with @Lob annotation.
+2. If Step 1 is true, then generate an EDM property with type as Edm.Binary
+
+**For `java.sql.Clob`**:
+
+1. Check if JPA entity property is of type `java.sql.Clob` and annotated with @Lob annotation.
+2. If Step 1 is true, then generate an EDM property with type as `Edm.String` (with no max length unless a max length is specified).
+
+### Runtime Processing
+
+**Prerequisites:**
+
+1. It is mandatory to implement the callback interface `org.apache.olingo.odata2.jpa.processor.api.OnJPAWriteContent`.
+2. The implemented interface needs to be registered with the service via the method `setOnJPAWriteContent` part of `ODataJPAServiceFactory`.
+
+Following is the pseudocode for handling the `java.sql.Blob` and `java.sql.Clob` during runtime.
+
+ /* Callback Implementation */
+
+ public class OnDBWriteContent implements OnJPAWriteContent {
+
+ @Override
+ public Blob getJPABlob(byte[] binaryData) throws ODataJPARuntimeException {
+ try {
+ return new JDBCBlob(binaryData);
+ } catch (SerialException e) {
+ ODataJPARuntimeException.throwException(ODataJPARuntimeException.INNER_EXCEPTION, e);
+ } catch (SQLException e) {
+ ODataJPARuntimeException.throwException(ODataJPARuntimeException.INNER_EXCEPTION, e);
+ }
+ return null;
+ }
+
+ @Override
+ public Clob getJPAClob(char[] characterData) throws ODataJPARuntimeException {
+ try {
+ return new JDBCClob(new String(characterData));
+ } catch (SQLException e) {
+ ODataJPARuntimeException.throwException(ODataJPARuntimeException.INNER_EXCEPTION, e);
+ }
+ return null;
+ }
+ }
+
+
+ /* Call Back registration in Service Factory */
+ public class JPAReferenceServiceFactory extends ODataJPAServiceFactory {
+
+ public static final OnJPAWriteContent onDBWriteContent = new OnDBWriteContent();
+
+ @Override
+ public ODataJPAContext initializeODataJPAContext()
+ throws ODataJPARuntimeException {
+
+ ....
+ ........
+ ..............
+
+ setOnWriteJPAContent(onDBWriteContent); //Register Call Back
+
+ return oDataJPAContext;
+ }
+ }
+
+OData JPA Processor Library internally does the following:
+
+1. Checks if the JPA entity property is of type `java.sql.Blob` or `java.sql.Clob`.
+2. If Step 1 is true, then it invokes the registered callback method `getJPABlob` or `getJPAClob` respectively.
+3. If callback method is not defined, it throws an exception.
+
+*Note*: Step 3 is needed because the OData JPA Processor Library is not bound to any specific implementation of BLOB or CLOB interface.
+
+
+
+
+
+