Home.md

@@ -4,16 +4,30 @@
 Legacy: [XML-RPC Delight](xmlrpc/Documentation)
 
 
+[Maven dependency](#maven-coordinates)
+
+[Available Features](#available-features)
+
+
 # Welcome to the delight JSON over HTTP
 
-This Delight backend implementation offers JSON-based RPC calls based on Java interfaces and abstract Java classes.
+This Delight backend implementation offers JSON-based RPC calls to simple Java objects implementing Java interfaces or abstract Java classes.
 
-Start your Java Service and access it without much effort ...
+The interface (or abstract class) is used to forge requests from __easy-to-use Java clients__ to the server. Non-java clients profit from
+the simple HTTP-request format which is also browser __browser-friendly__.
+
+## How it works
 
 Define a Java-Interface, for example
 
         public interface ServiceApi {
-           int doSometing(String parameter);
+           String doSometing(TestPojo parameter);
+        }
+e.g., with a self-defined bean named `TestPojo`
+
+        public class TestPojo {
+           int number; 
+           String string;
         } 
     
 Then you can register an implementation (let's call it `ServiceImpl`) of this API with the Delight backend.
@@ -22,25 +36,99 @@ The implementation is called a handler.
         DelightConfig cfg = DelightConfigFinder.getDefaultConfig()
         DelightServer server = new DelightServer(cfg)
             .port( 8080 )
-            .path( "/delight" )
+            .path( "/example-delight-webapp/delight" )
             .init( backend -> {
                 backend.addHandlerByClass("handler-x", ServiceImpl.class);
             });
         server.start();
         server.waitForShutdown();
     
-Now you can do RPC calls to this backend with any tool which is able to send HTTP requests. Here is the Java client:
+Now you can do RPC calls to this backend with any tool which is able to send HTTP requests.
+
+### Java Client
 
-        DelightConfig cfg = DelightConfigFinder.getDefaultConfig();
-        Delight delight = new Delight(cfg);
+Using the service from a Java client is as easy as
 
-        ServiceApi service = delight
-                    .connectingTo("http://localhost:8080/delight")
+        Delight delight = new Delight(DelightConfigFinder.getDefaultConfig());
+        ServiceApi client = delight.connectingTo("http://localhost:8080/example-delight-webapp/delight")
                                    .usingApi("handler-x", ServiceApi.class);
-        service.doSometing("acme param");
+        String retVal = client.soDomething( new TestPojo(...) );
+
+Delight will take care of object serialization out-of-the-box
+
+### Pure HTTP Requests
+
+Methods can be accessed through this pattern
+
+    WEB-CONTEXT/{handlerName}/{methodName}?parameter1=value1&parameterN=valueN...
+    
+Parameters are passed as JSON objects or literals: In our example a call would look like this:
+
+    GET http://localhost:8080/my-service/handler-x/doSometing?parameter=great
+    
+The following capabilities exist:
+
+*  __Primitive types__ (numbers, strings and boolean) will be transported as-is (simple strings)
+
+        GET http://localhost:8080/my-service/handler-x?simple=a%20string
+        GET http://localhost:8080/my-service/handler-x?simple=a%20string%20with%20saces
+    
+*  __Complex types__ will be converted into JSON representation
+
+        GET http://localhost:8080/my-service/handler-x?complexPar={"number":23,"string":"hello"}
+    
+*  __Arrays of primitive and complex types__ are permitted
+   
+*  __null String values__ are represented with the zero byte (ASCII 0 / NUL). Specify it with Url encoding: '?parameterNull=%00'
+
+        GET http://localhost:8080/my-service/handler-x?parameterNull=%00
+        
+*  __POST or GET__ is possible to make the call
+
+*  __Big data transfers__ (e.g. file uploads and downloads) are supported by InputStream parameters and return types. 
+    * The HTTP return values are of type `application/octet-stream`
+    * The parameters must be specified as multipart message parts: `Content-Type: multipart/form-data; boundary=...` 
+       * Each parameter values is sent in a separate part: `Content-Disposition: form-data; name="...PARAMETER_NAME..." `
+       * InputStream parameters must use mime-type `application/octet-stream` 
+       * All other parameters go as `application/x-www-form-urlencoded; charset=UTF-8` 
+
+* All parameters can be specified either as HTTP parameters or multipart message parts. Mixing is not possible.
+* You cannot omit parameters in a request - all are needed by the server to find the request associated method. Simply set empty string and list values (e.g. parameter1=&parameter2=[ ]&parameterN=...).
 
 ### Detailed Descriptions
 
  * [Create a Delight Service](ExampleService)
  * [Delight with Java Client](ExampleJavaClient)
  * [Delight with pure HTTP Requests](ExampleHttpRequests)
+ 
+### Maven Coordinates
+
+Use this repository
+
+    <repository>
+        <id>dfki-snapshots</id>
+        <url>http://www.dfki.uni-kl.de/artifactory/libs-snapshots</url>
+        <releases>
+            <enabled>false</enabled>
+        </releases>
+        <snapshots>
+            <enabled>true</enabled>
+        </snapshots>
+    </repository>
+
+User this dependency:
+
+    <dependency>
+        <groupId>dfki.sds.delight</groupId>
+        <artifactId>json-over-http-delight</artifactId>
+        <version>4.0-SNAPSHOT</version>
+    </depencency>
+
+
+### Available Features
+
+* [Online Documentation Generator](DocuFeature.md)
+
+* [Server-Sent Events](ServerSentFeature.md)
+
+* [Call Statistics](CallStatisticsFeature.md)