A URI template can contain zero or more embedded parameters called template parameters. Start coding the template parameters with an opening curly bracket ({), and continue coding one or more alphanumeric characters and symbols other than a forward slash (/) and code a closing bracket (}) at the end. You can acquire the actual values of the template parameters by injecting to the parameters, fields, or bean properties annotated by the PathParam annotation. For details on how to code the template parameters, check the standard specifications.

An example of a template parameter is as follows.

package com.someshop;
 
import javax.ws.rs.PathParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/customers")
public class CustomerResource {
  //subresource method
  @GET
  @Path("{id}")
  public String getCustomer(@PathParam("id") int id) {
    //execute to return the assigned value
  }
}

In this example, the expression {id} included in the Path annotation is the template parameter. Consider the context root of the Web application containing the root resource class com.someshop.CustomerResource to be "resource" and that the Web application is published on a host named "someshop.com". In this case, the HTTP GET request corresponding to the URL "http://someshop.com/resource/customers/333" is dispatched to the sub-resource method getCustomer() and the actual value of the template parameter id is injected to the parameter id annotated by the PathParam annotation.

However, the HTTP GET request corresponding to the URL "http://someshop.com/resource/customers/333/444" is not dispatched by any method. 404 is returned as the HTTP status code.

The template parameters can be embedded anywhere in the value of the Path annotation (URI template). The following example describes the usage of multiple template parameters.

package com.someshop;
 
import javax.ws.rs.PathParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/")
public class CustomerResource {
  //subresource class
  @GET
  @Path("customers/{firstname}-{lastname}")
  public String getCustomer(@PathParam("firstname") String firstname,
      @PathParam("lastname") String lastname) {
    //execute to return the assigned value
  }
}

In this example, the expressions {firstname} and {lastname} to be included in the Path annotation are the two template parameters separated by a hyphen.

The HTTP GET request corresponding to the URL "http://someshop.com/resource/customers/John-Smith" is dispatched to the sub-resource method getCustomer() and the actual values of the template parameters firstname and lastname are respectively injected to the parameters firstname and lastname annotated by the PathParam annotation.

(a) Regular expressions

The regular expressions other than wild cards can be used in the Path annotation. The following example describes the usage of regular expressions in template parameters.

package com.someshop;
 
import javax.ws.rs.PathParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/customers")
public class CustomerResource {
  //subresource method1
  @GET
  @Path("{id : \\d+}")
  public String getCustomer(@PathParam("id") int id) {
    // Implementation to return appropriate value
  }
//subresource method2
@GET
  @Path("{path : .+}")
  public String getCustomerIdAndName(@PathParam("path") String path) {
    //execution to return the assigned value
  }
}

In this example, the expression {id : \\d+} to be included in the Path annotation is a template parameter that uses a regular expression. The identifier id and the regular expression "\\d+" are used together. A colon (:) separates the identifier and the regular expression.

The regular expression "\\d+" matches with one or more digits. The HTTP request corresponding to the URL "http://someshop.com/resource/customers/333" is dispatched to the sub-resource method getCustomer().

The regular expression " +" matches with any character. The HTTP GET request corresponding to the URL "http://someshop.com/resource/customers/33/John/Smith" is dispatched to the sub-resource method getCustomerIdAndName().

(b) Notes when using template parameters

The system returns an error (KDJJ10006-E) in the following cases:

• If invalid characters are used in template parameters
• If invalid syntactical regular expressions are written in template parameters

The system returns an HTTP response with the HTTP status code 500 in the root resource class and throws java.lang.RuntimeException, which can be handled by the exception mapping provider, in the sub-resource class (KDJJ10006-E).