svn commit: r1547406 - /incubator/olingo/site/trunk/content/doc/tutorials/Olingo_Tutorial_BasicWrite.mdtext

[sk...@apache.org]

Author: sklevenz
Date: Tue Dec  3 14:30:46 2013
New Revision: 1547406

URL: http://svn.apache.org/r1547406
Log:
CMS commit to olingo by sklevenz

Modified:
    incubator/olingo/site/trunk/content/doc/tutorials/Olingo_Tutorial_BasicWrite.mdtext

Modified: incubator/olingo/site/trunk/content/doc/tutorials/Olingo_Tutorial_BasicWrite.mdtext
URL: http://svn.apache.org/viewvc/incubator/olingo/site/trunk/content/doc/tutorials/Olingo_Tutorial_BasicWrite.mdtext?rev=1547406&r1=1547405&r2=1547406&view=diff
==============================================================================
--- incubator/olingo/site/trunk/content/doc/tutorials/Olingo_Tutorial_BasicWrite.mdtext (original)
+++ incubator/olingo/site/trunk/content/doc/tutorials/Olingo_Tutorial_BasicWrite.mdtext Tue Dec  3 14:30:46 2013
@@ -16,4 +16,131 @@ Notice:    Licensed to the Apache Softwa
            specific language governing permissions and limitations
            under the License.
 
-todo
\ No newline at end of file
+# Write Scenario 
+### How To Guide for building a Sample OData service with the OData Library (Java)
+
+
+This How To Guide shows how to create, update and delete an entry via your Data Provider (`ODataSingleProcessor`).
+
+### Prerequisites
+This tutorial is based on the [Read Scenario](doc/tutorials/basicread.html) - OData Library (Java) tutorial.  
+### Implementing create, update and delete entry at the single processor
+##### Shortcut
+As a shortcut you can download the project sample-service.zip
+
+##### Create entry
+- You already created the `MyODataSingleProcessor` in the basic tutorial 
+- Implement `MyODataSingleProcessor.createEntity(PostUriInfo uriInfo, InputStream content, String requestContentType, String contentType) throws ODataException` by overriding the corresponding method of the `ODataSingleProcessor` 
+  
+**Sample Code**
+
+    
+    @Override
+    public ODataResponse createEntity(PostUriInfo uriInfo, InputStream content, 
+    String requestContentType, String contentType) throws ODataException {
+      //No support for creating and linking a new entry
+      if (uriInfo.getNavigationSegments().size() > 0) {
+      throw new ODataNotImplementedException();
+      }
+
+      //No support for media resources
+      if (uriInfo.getStartEntitySet().getEntityType().hasStream()) {
+      throw new ODataNotImplementedException();
+      }
+
+      EntityProviderReadProperties properties = EntityProviderReadProperties.init().mergeSemantic(false).build();
+
+      ODataEntry entry = EntityProvider.readEntry(requestContentType, uriInfo.getStartEntitySet(), content, properties);
+      //if something goes wrong in deserialization this is managed via the ExceptionMapper
+      //no need for an application to do exception handling here an convert the exceptions in HTTP exceptions
+
+      Map<String, Object> data = entry.getProperties();
+      //now one can use the data to create the entry in the backend ...
+      //retrieve the key value after creation, if the key is generated by the server
+
+      //update the data accordingly
+      data.put("Id", Integer.valueOf(887788675));
+
+      //serialize the entry, Location header is set by OData Library
+      return EntityProvider.writeEntry(contentType, uriInfo.getStartEntitySet(), entry.getProperties(), EntityProviderWriteProperties.serviceRoot(getContext().getPathInfo().getServiceRoot()).build());
+    }
+
+
+##### Update entry
+- You already created the `MyODataSingleProcessor` in the basic tutorial 
+- Implement `MyODataSingleProcessor.updateEntity(PutMergePatchUriInfo uriInfo, InputStream content, String requestContentType, boolean merge, String contentType) throws ODataException` by overriding the corresponding method of the `ODataSingleProcessor` 
+
+**Sample Code**
+
+    @Override
+    public ODataResponse updateEntity(PutMergePatchUriInfo uriInfo, InputStream content, String requestContentType, boolean merge, String contentType) throws ODataException {
+    EntityProviderReadProperties properties = EntityProviderReadProperties.init().mergeSemantic(false).build();
+
+      ODataEntry entry = EntityProvider.readEntry(requestContentType, uriInfo.getTargetEntitySet(), content, properties);
+      //if something goes wrong in deserialization this is managed via the ExceptionMapper,
+      //no need for an application to do exception handling here an convert the exceptions in HTTP exceptions
+
+      Map<String, Object> data = entry.getProperties();
+
+      if ("Cars".equals(uriInfo.getTargetEntitySet().getName())) {
+      int key = getKeyValue(uriInfo.getKeyPredicates().get(0));
+
+        //if there is no entry with this key available, one should return "404 Not Found"
+        //return ODataResponse.status(HttpStatusCodes.NOT_FOUND).build();
+
+        //now one can use the data to create the entry in the backend ...
+        String model = (String) data.get("Model");
+        //...
+      } else if ("Manufacturers".equals(uriInfo.getTargetEntitySet().getName())) {
+      int key = getKeyValue(uriInfo.getKeyPredicates().get(0));
+      //now one can use the data to create the entry in the backend ...
+      }
+
+      //we can return Status Code 204 No Content because the URI Parsing already guarantees that
+      //a) only valid URIs are dispatched (also checked against the metadata)
+      //b) 404 Not Found is already returned above, when the entry does not exist 
+    return ODataResponse.status(HttpStatusCodes.NO_CONTENT).build();
+    }
+
+##### Delete entry
+- You already created the `MyODataSingleProcessor` in the basic tutorial 
+- Implement `MyODataSingleProcessor.deleteEntity(DeleteUriInfo uriInfo, String contentType) throws ODataException` by overriding the corresponding method of the `ODataSingleProcessor` 
+
+**Sample Code**
+
+    @Override
+    public ODataResponse deleteEntity(DeleteUriInfo uriInfo, String contentType) throws ODataException {
+      if ("Cars".equals(uriInfo.getTargetEntitySet().getName())) {
+      int key = getKeyValue(uriInfo.getKeyPredicates().get(0));
+
+        //if there is no entry with this key available, one should return "404 Not Found"
+        //return ODataResponse.status(HttpStatusCodes.NOT_FOUND).build();
+
+        //now one can delete the entry with this particular key in the backend...
+
+      } else if ("Manufacturers".equals(uriInfo.getTargetEntitySet().getName())) {
+      int key = getKeyValue(uriInfo.getKeyPredicates().get(0));
+      //now one can delete the entry with this particular key in the backend...
+      }
+
+      //we can return Status Code 204 No Content because the URI Parsing already guarantees that
+      //a) only valid URIs are dispatched (also checked against the metadata)
+      //b) 404 Not Found is already returned above, when the entry does not exist 
+      return ODataResponse.status(HttpStatusCodes.NO_CONTENT).build();
+    }
+
+### Test your Service
+
+After the implementation of the MyODataSingleProcessor the web application can be tested.
+
+- Build your project. Remember? mvn clean install 
+- In Eclipse, run the Web Application via Run As -> Run on Server 
+ - Create a new Car 
+ - Update an existing Car 
+ - Delete a Car 
+ - Create a new Manufacturer (this is a Media Link Entry), we expect not implemented 
+ - Update a Manufacturer (this is a Media Link Entry) 
+### Further Information
+- OData Library (Java) Git Repository **[link tbd]** 
+- OData Library (Java) Issue Tracker **[link tbd]** 
+     
\ No newline at end of file