Path, HTTP Method and MediaType annotations - 6.3

Talend ESB Service Developer Guide

EnrichVersion
6.3
EnrichProdName
Talend Data Fabric
Talend Data Services Platform
Talend ESB
Talend MDM Platform
Talend Open Studio for ESB
Talend Real-Time Big Data Platform
task
Design and Development
Installation and Upgrade
EnrichPlatform
Talend ESB

The @Path annotation is applied to root resource classes or methods. The @Path value is a relative URI with one or more path segments. The value may be literal, for example, "customers/1/orders" or parameterized and contain one or more URITemplate variables: "customers/{id}/orders/{orderid}". In the latter example the "id" and "orderid" are template variables. The actual values will be available to resource methods with the help of @PathParam annotations. Template variables may also contain explicit regular expressions, for example: "/{id:.*}/" where "id" is the name of the variable and the expression after the semicolon is a custom regular expression.

When @Path is not available on the resource method then it is assumed to be equal to "/".

When selecting the root resource class, the runtime will try to match the relative request path available to it after the HTTP servlet matched the absolute request URI with the @Path value of the root resource. If the current root resource is not matched then the next root resource, if available, will be tried. After the successful match, the resource method will be selected given the remaining relative path and the HTTP method

Every resource method which is not a subresource locator must have an annotation indicating which HTTP verb is supported by this method. JAX-RS provides @GET, @DELETE, @POST, @PUT, @HEAD and @OPTIONS. Annotations for supporting other HTTP verbs can be created. The current resource method may only be selected if the value of its HTTP Method annotation is equal to the request HTTP verb.

The @Consumes annotation is used to specify the acceptable format of the request message. If it is not available on the resource method then it is inherited from a class, and if it's not available on the class then it's indirectly inherited from a corresponding JAX-RS MessageBodyReader, if any. The default value is '*/*' but it is recommended that a concrete media type is specified.

When attempting to select a given resource method, the runtime will try to match the value of the Content-Type HTTP header with the @Consumes value. If the match is successful then it will try to find the JAX-RS MessageBodyReader which can read the request message and convert it into the method parameter representing a request body. When looking for the reader, the runtime will also try to match the @Consumes value of the current reader with the request media type.

The @Produces annotation is used to specify the format of the response. If it is not available on the resource method then it is inherited from a class, and if it's not available on the class then it's indirectly inherited from a corresponding JAX-RS MessageBodyWriter, if any. The initial default value is '*/*' which will set to "application/octet-stream" before writing the actula response, thus it is recommended that a concrete media type is specified. For example, getCustomers() method inherits @Produces annotation from its class, while getCustomer() method overrides it with its own value.

When attempting to select a given resource method, the runtime will try to match the value of the Accept HTTP header with the @Produces value. The Accept and @Produces values may list multiple media types - the most preferred media type is chosen during the intersection. Additionally, when the resource method returns an object, the runtime will try to find the suitable JAX-RS MessageBodyWriter. When looking for the writer, the runtime will also try to match the @Produces value of the current writer with the media type obtained during the earlier intersection.