Changes between Version 30 and Version 31 of PluginDevelopmentGuide

Timestamp:

10.05.2013 23:41:44 (12 years ago)

Author:

jri

Comment:

Parsing the HTTP request body

PluginDevelopmentGuide

@@ -1034 +1034 @@
 || `@HeaderParam` || Extracts the value of a header ||
 
-A value extracted from a HTTP request is inherently a string. So DeepaMehta must know how to actually construct a Java object (resp. a primitive value) from it. That's why the type of a service method argument that is annotated with one of these annotations must satisfy one of these criteria:
+A value extracted from a HTTP request is inherently a string. So the JAX-RS implementation must know how to actually construct a Java object (resp. a primitive value) from it. That's why the type of a service method argument that is annotated with one of these annotations must satisfy one of these criteria:
 
 1. The type is a primitive type like `int`, `long`, `float`, `double`, `boolean`, `char`.
@@ -1066 +1066 @@
     The `clientState` value is extracted from the request's `Cookie` header value. The actual `ClientState` object is created by passing the value to the `ClientState(String)` constructor. Here criterion 2 is satisfied.
 
-==== Provider Classes ====
+==== Parsing the HTTP request body ====
+
+Until here we talked about how to extract values from the HTTP request's path, the request's query string, or the request headers. This section describes how to feed the //HTTP request body// into your service methods. Feeding here refers to a) parsing the body's byte stream, b) constructing a Java object from it, and passing that Java object to a particular service method.
+
+JAX-RS can't know how to construct arbitrary application objects from a sole byte stream. That's why JAX-RS comprises a extension facility called //Provider Classes//. A provider class is responsible to read the request body, parse it, and construct an particular application object from it. It is the duty of the application developer to implement the required provider classes for the application objects.
+
+A service method that want to receive the constructed application object must have a dedicated parameter called (in JAX-RS speak) the //Entity Parameter//. The entity parameter stands for the entity that is represented in the request body. Unlike the other service method parameters the entity parameter has //no// annotation. A service method can have //one// entity parameter at most (a HTTP request has //one// body).
+
+To feed the HTTP request body into a service method you must:
+
+* Add an entity parameter to the service method. That is a parameter without any annotation.  
+
+* Implement a provider class for the type of the entity parameter, resp. make sure such a provider class already exists (as part of the DeepaMehta Core or one of the installed DeepaMehta plugins).