Changes between Version 28 and Version 29 of PluginDevelopmentGuide

Timestamp:

09.05.2013 16:39:42 (12 years ago)

Author:

jri

Comment:

Extract values from HTTP requests

PluginDevelopmentGuide

@@ -959 +959 @@
 * Annotate each service method with one of `@GET`, `@POST`, `@PUT`, or `@DELETE` to declare the HTTP method that will invoke that service method.
 
-* Annotate each service method with `@Path` to declare the URI template that will invoke that service method. The URI template can contain parameters, notated as `{...}`.
+* Annotate each service method with `@Path` to declare the URI template that will invoke that service method. The URI template can contain parameters, notated with curly braces `{...}`.
 
 * Annotate service method parameters with `@PathParam` to map URI template parameters to service method parameters.
@@ -1022 +1022 @@
 }}}
 
-
-
-JAX-RS: Java API for RESTful Web Services
+JAX-RS: Java API for RESTful Web Services[[BR]]
 http://jsr311.java.net/nonav/releases/1.1/spec/spec.html
+
+==== Extract values from HTTP requests ====
+
+This section describes in more detail how the service method argument values are extracted from the various parts of a HTTP request. As seen in the example above this is controlled by annotating the service method arguments. Besides `@PathParam` you can use further annotations:
+
+||= Annotation =||= Semantics =||
+|| `@PathParam` || Extracts the value of a URI template parameter ||
+|| `@QueryParam` || Extracts the value of a URI query parameter ||
+|| `@HeaderParam` || Extracts the value of a header ||
+
+A value extracted from a HTTP request is inherently a string. So DeepaMehta (resp. the underlying JAX-RS implementation) must know how to actually construct a Java object (resp. a scalar value) from it. That's why the type of a service method argument that is annotated with one of the annotations above must fulfill at least one of these criteria:
+
+1. The type is a primitive type like `int`, `long`, `float`, `double`, `boolean`.
+
+2. The type have a constructor that accepts a single `String` argument.
+
+3. The type have a static method named `valueOf` that takes a single `String` argument and returns an instance of the type.
+
+    Enum types are special in one regard as they already have a static `valueOf` method. If this one does not fit your need add a `fromString` method to your enum type that has the same characteristics as the `valueOf` method mentioned above.
+
+4. The type is `List<T>`, `Set<T>`, or `SortedSet<T>`, where `T` satisfies 2 or 3 above.
+
+==== Provider Classes ====