Author: chrish
Date: Tue Nov 17 12:30:04 2015
New Revision: 1714771
URL: http://svn.apache.org/viewvc?rev=1714771&view=rev
Log:
CMS commit to olingo by chrish
Added:
olingo/site/trunk/content/doc/odata4/tutorials/deep_insert/tutorial_deep_insert.mdtext
(with props)
Added:
olingo/site/trunk/content/doc/odata4/tutorials/deep_insert/tutorial_deep_insert.mdtext
URL:
http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/odata4/tutorials/deep_insert/tutorial_deep_insert.mdtext?rev=1714771&view=auto
==============================================================================
---
olingo/site/trunk/content/doc/odata4/tutorials/deep_insert/tutorial_deep_insert.mdtext
(added)
+++
olingo/site/trunk/content/doc/odata4/tutorials/deep_insert/tutorial_deep_insert.mdtext
Tue Nov 17 12:30:04 2015
@@ -0,0 +1,131 @@
+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.
+
+# How to build an OData Service with Olingo V4
+
+# Part 7: Handling "Deep Insert" requests
+
+## Introduction
+
+
+In the present tutorial, we will implement the handling of deep insert
requests.
+
+**Note:**
+The final source code can be found in the project [git
repository](https://git-wip-us.apache.org/repos/asf/olingo-odata4).
+A detailed description how to checkout the tutorials can be found
[here](/doc/odata4/tutorials/prerequisites/prerequisites.html).
+This tutorial can be found in subdirectory /samples/tutorials/p11_batch
+
+
+**Table of Contents**
+
+ 1. Introduction
+ 2. Preparation
+ 3. Implementation
+ 4. Run the implemented service
+ 5. Links
+
+# 1. Introduction
+
+In this tutorial shows how to handle "deep insert" requests. OData gives us
the possibility to create related entities, and bind existing entities to a
new created entity in a single request. (More detailed information: [OData
Version 4.0 Part 1:
Protocol](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398326),
[OData JSON Format Version
4.0](http://docs.oasis-open.org/odata/odata-json-format/v4.0/errata02/os/odata-json-format-v4.0-errata02-os-complete.html#_Toc403940637))
+
+OData uses to create a related entity the same syntax as for an expanded
navigation property, as descripted in [OData JSON
Format](http://docs.oasis-open.org/odata/odata-json-format/v4.0/errata02/os/odata-json-format-v4.0-errata02-os-complete.html#_Toc403940637).
To bind an existing entity, OData uses the `odata.bind` property annotation.
The value of the annotation is either an entity-Id or a collection of
entity-Ids. An
[entity-Id](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398204)
is a durable, opaque, globally unique
[IRI](https://www.ietf.org/rfc/rfc3987.txt). The specification recommends to
use the canonical URL of the entity. In this tutorial the relative canonical
URL of an entity is used.
+
+**Example**
+
+For example you may want to create a new category and also create new
products, which are related to the new created category. In addition you would
like to bind an existing entity to the new created category.
+Such a request is issued againest the URL of the entity set.
+
+In this example, a new Category "Food" and two products ("Bread", "Milk") are
created. In addition the Product with the key 5 is bind to the just created
entity.
+
+
+ POST /Categories HTTP/1.1
+ Content-Type: application/json
+
+ {
+ "name": "Food",
+ "[email protected]": [
+ "Products(5)"
+ ],
+ "Products": [
+ {
+ "Name": "Bread",
+ "Description": "Whole grain bread"
+ },
+ {
+ "Name": "Milk",
+ "Description": "Low fat milk"
+ }
+ ]
+ }
+
+# 2. Preparation
+
+You should read the previous tutorials first to have an idea how to read and
write entities. In addition the following code is based on the write tutorial
merged with the navigation tutorial.
+
+As a shortcut you should checkout the prepared tutorial project in the [git
repository](https://git-wip-us.apache.org/repos/asf/olingo-odata4) in folder
/samples/tutorials/p12_deep_insert_preparation.
+
+Afterwards do a Deploy and run: it should be working. At this state you can
perform CRUD operations and do navigations between products and categories.
+
+# 2. Implementation
+
+Before we start with the implementation, please have a look at the class
`myservice.mynamespace.data.Storage`. In difference to the [navigation
tutorial](http://olingo.apache.org/doc/odata4/tutorials/navigation/tutorial_navigation.html)
the relations between two entities can not be hard coded because we would like
to create and change relations between entities. In the constructor of the data
storage the sample data is created. After that the method
`linkProductsAndCategories`is called. This methods sets a few links between the
just created entities.
+
+To express the relation between two entities, Olingo uses the class
[Link](http://olingo.apache.org/javadoc/odata4/org/apache/olingo/commons/api/data/Link.html).
This class is used for related entites (directly connected via Java
references) and bindings (which are actually strings) to other entities
dynamically. To get the related entites for a particual navigation property,
you can ask an entity with the method [`getNavigationLink(String
name)`](http://olingo.apache.org/javadoc/odata4/org/apache/olingo/commons/api/data/Linked.html#getNavigationLink(java.lang.String))
for an navigation property. The link will contain either an entity or a
collection of entities dependenting on the type of the navigation property. To
get the actual entities use the methods
[`getInlineEntity()`](http://olingo.apache.org/javadoc/odata4/org/apache/olingo/commons/api/data/Link.html#getInlineEntity())
or
[`getInlineEntitySet()`](http://olingo.apache.org/javadoc/odata4/org/apache/olingo/commons/api/data/L
ink.html#getInlineEntitySet())
+The same can be done for bindings via the method [`getNavigationBinding(String
name)`](http://olingo.apache.org/javadoc/odata4/org/apache/olingo/commons/api/data/Linked.html#getNavigationBinding(java.lang.String)).
The values of the Binding can be got by the methods
[`getBindingLink()`](http://olingo.apache.org/javadoc/odata4/org/apache/olingo/commons/api/data/Link.html#getBindingLink())
and
[`getBindingLinks()`](http://olingo.apache.org/javadoc/odata4/org/apache/olingo/commons/api/data/Link.html#getBindingLinks()).
+
+The point is that the Entity deserializer uses the same concept to represent
the payload as Java objects.
+In the previous tutorials the entity object returned by the deserializer is
passed to the data store. Please open the class
`myservice.mynamespace.data.Storage` and jump the method `createEntity`.
+
+
+
+
+
+# 4. Run the implemented service
+
+After building and deploying your service to your server, you can try the
following requests:
+
+
+
+# 5. Links
+
+### Tutorials
+
+Further topics to be covered by follow-up tutorials:
+
+ * Tutorial OData V4 service part 1: [Read Entity
Collection](/doc/odata4/tutorials/read/tutorial_read.html)
+ * Tutorial OData V4 service part 2: [Read Entity, Read
Property](/doc/odata4/tutorials/readep/tutorial_readep.html)
+ * Tutorial OData V4 service part 3: [Write (Create, Update, Delete
Entity)](/doc/odata4/tutorials/write/tutorial_write.html)
+ * Tutorial OData V4 service, part 4:
[Navigation](/doc/odata4/tutorials/navigation/tutorial_navigation.html)
+ * Tutorial OData V4 service, part 5.1: [System Query Options $top, $skip,
$count (this page)](/doc/odata4/tutorials/sqo_tcs/tutorial_sqo_tcs.html)
+ * Tutorial OData V4 service, part 5.2: [System Query Options $select,
$expand](/doc/odata4/tutorials/sqo_es/tutorial_sqo_es.html)
+ * Tutorial OData V4 service, part 5.3: [System Query Options
$orderby](/doc/odata4/tutorials/sqo_o/tutorial_sqo_o.html)
+ * Tutorial OData V4 service, part 5.4: [System Query Options
$filter](/doc/odata4/tutorials/sqo_f/tutorial_sqo_f.html)
+ * Tutoral ODATA V4 service, part 6: [Action and Function
Imports](/doc/odata4/tutorials/action/tutorial_action.html)
+ * Tutoral ODATA V4 service, part 6: [Batch Request
support](/doc/odata4/tutorials/batch/tutorial_batch.html)
+ * Tutoral ODATA V4 service, part 6: Handling "Deep Insert" requests
+
+### Code and Repository
+ * [Git Repository](https://git-wip-us.apache.org/repos/asf/olingo-odata4)
+ * [Guide - To fetch the tutorial
sources](/doc/odata4/tutorials/prerequisites/prerequisites.html)
+ * [Demo Service source code as zip file (contains all
tutorials)](http://www.apache.org/dyn/closer.lua/olingo/odata4/4.0.0/DemoService_Tutorial.zip)
+
+### Further reading
+
+ * [Official OData Homepage](http://odata.org/)
+ * [OData documentation](http://www.odata.org/documentation/)
+ * [Olingo Javadoc](/javadoc/odata4/index.html)
\ No newline at end of file
Propchange:
olingo/site/trunk/content/doc/odata4/tutorials/deep_insert/tutorial_deep_insert.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
