Changes between Version 29 and Version 30 of PluginDevelopmentGuide


Ignore:
Timestamp:
10.05.2013 15:49:23 (8 years ago)
Author:
jri
Comment:

HTTP request value extraction example

Legend:

Unmodified
Added
Removed
Modified
  • PluginDevelopmentGuide

    v29 v30  
    10251025http://jsr311.java.net/nonav/releases/1.1/spec/spec.html 
    10261026 
    1027 ==== Extract values from HTTP requests ==== 
    1028  
    1029 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: 
     1027==== Extract values from a HTTP request ==== 
     1028 
     1029This 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: 
    10301030 
    10311031||= Annotation =||= Semantics =|| 
     
    10341034|| `@HeaderParam` || Extracts the value of a header || 
    10351035 
    1036 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: 
    1037  
    1038 1. The type is a primitive type like `int`, `long`, `float`, `double`, `boolean`. 
    1039  
    1040 2. The type have a constructor that accepts a single `String` argument. 
    1041  
    1042 3. The type have a static method named `valueOf` that takes a single `String` argument and returns an instance of the type. 
    1043  
    1044     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. 
    1045  
    1046 4. The type is `List<T>`, `Set<T>`, or `SortedSet<T>`, where `T` satisfies 2 or 3 above. 
     1036A 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: 
     1037 
     10381. The type is a primitive type like `int`, `long`, `float`, `double`, `boolean`, `char`. 
     1039 
     10402. The type has a constructor that accepts a single `String` argument. 
     1041 
     10423. The type has a static method named `valueOf` that takes a single `String` argument and returns an instance of the type. 
     1043 
     1044    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. 
     1045 
     10464. The type is `List<T>`, `Set<T>`, or `SortedSet<T>`, where `T` satisfies criterion 2 or 3. 
     1047 
     1048So, 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. 
     1049 
     1050As an example lets revisit the `getTopicmap` method from the previous section: 
     1051 
     1052{{{ 
     1053#!java 
     1054    @GET 
     1055    @Path("/{id}") 
     1056    @Override 
     1057    public Topicmap getTopicmap(@PathParam("id") long topicmapId, @HeaderParam("Cookie") ClientState clientState) { 
     1058        ... 
     1059    } 
     1060}}} 
     1061 
     1062Now you know how exactly the JAX-RS implementation extracts the `topicmapId` and `clientState` parameter values from the HTTP request: 
     1063 
     1064    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. 
     1065 
     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. 
    10471067 
    10481068==== Provider Classes ====