Changes between Version 29 and Version 30 of PluginDevelopmentGuide

Timestamp:

10.05.2013 15:49:23 (11 years ago)

Author:

jri

Comment:

HTTP request value extraction example

PluginDevelopmentGuide

@@ -1025 +1025 @@
 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:
+==== Extract values from a HTTP request ====
+
+This section describes in more detail how DeepaMehta (resp. the underlying JAX-RS implementation to be precise) extracts the service method argument values 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 =||
@@ -1034 +1034 @@
 || `@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.
+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:
+
+1. The type is a primitive type like `int`, `long`, `float`, `double`, `boolean`, `char`.
+
+2. The type has a constructor that accepts a single `String` argument.
+
+3. The type has a static method named `valueOf` that takes a single `String` argument and returns an instance of the type.
+
+    Enum types are special 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 criterion 2 or 3.
+
+So, when you use a self-defined class (including enum classes) along with `@PathParam`, `@QueryParam`, or `@HeaderParam` make sure your class satisfies criterion 2 or 3.
+
+As an example lets revisit the `getTopicmap` method from the previous section:
+
+{{{
+#!java
+    @GET
+    @Path("/{id}")
+    @Override
+    public Topicmap getTopicmap(@PathParam("id") long topicmapId, @HeaderParam("Cookie") ClientState clientState) {
+        ...
+    }
+}}}
+
+Now you know how exactly the JAX-RS implementation extracts the `topicmapId` and `clientState` parameter values from the HTTP request:
+
+    The `topicmapId` value is extracted from the request's URI path and then converted to a `long`. Here criterion 1 is satisfied and the conversion is straight-forward.
+
+    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 ====