Root resource classes

A root resource class is a public class of Java that is set up as an annotation using the Path annotation at a class level, and contains at least one of the resource methods, sub-resource methods, or sub-resource locators.

The following example describes a root resource class containing a resource method and a sub-resource locator.

package com.sample.resources;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/root")
public class Resource2 {
 
  //subresource locator corresponding to the request to context root+ "/root/sub1"
  @Path("/sub1")
  public SubResource1 subResourceLocator1() {
    //returns an instance of the subresource class to be processed
    return new SubResource1();
  }
 
  //subresource locator corresponding to the request to context root+ "/root/sub2"
  @Path("/sub2")
  public SubResource2 subResourceLocator2() {
    //returns an instance of the subresource class to be processed
 
    return new SubResource2();
}
  //resource method
  @GET
  public String getValue() {
    String returnValue = "";
    //sets a return value
    return returnValue;
  }
 
}

com.sample.resources.Resource2 is a root resource class. Note that the annotation is performed with the Path annotation at a class level. This root resource class contains two sub-resource locators; subResourceLocator1() and subResourceLocator2(), and the resource method getValue() for processing HTTP GET requests. Note that the Path annotation is used for the annotation of a sub-resource locator and the request method designator is used for the annotation of a resource method. Both SubResource1 and SubResource2 are sub-resource classes. For details, see the following subsections:

17.1.1(4) Resource method
17.1.1(5) Sub-resource method
17.1.1(6) Sub-resource locator

17.1.7 Sub-resource classes

package com.sample.resources;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/root")
public class Resource3 {
 
  //sub-resource method corresponding to the request to context root+ "root/sub1"
  @Path("/sub1")
  @GET
  public String subResourceMethod1() {
    String value = "";
    // Execute the process and then return the result.
    return value;
  }
 
  //sub-resource method corresponding to the request to context root+ "root/sub2"
  @Path("/sub2")
  @GET
  public String subResourceMethod2() {
    String value = "";
    // Execute the process and then return the result.
    return value;
  }
}

com.sample.resources.Resource3 is a root resource class. This root resource class contains two sub-resource methods; subResourceMethod1() and subResourceMethod2(). Both the Path annotation and the request method are used for the annotation of a sub-resource method.

If an asterisk (*) is specified in the URL of the Path annotation, you can invoke only a resource method. If you invoke a sub-resource method or a sub-resource locator, the system throws java.lang.StringIndexOutOfBoundsException exception, which can be handled by the exception mapping provider.

Organization of this subsection: (1) Life cycle; (2) Constructor; (3) Fields and Bean properties; (4) Resource method; (5) Sub-resource method; (6) Sub-resource locators

(1) Life cycle

(2) Constructor

A root resource class must contain at least one public constructor including the default public constructor (constructors that are not explicitly declared).

The following example describes a public constructor containing parameters.

package com.sample.resources;
 
import javax.ws.rs.DefaultValue;
import javax.ws.rs.Encoded;
import javax.ws.rs.QueryParam;
import javax.ws.rs.Path;
import javax.ws.rs.GET;
 
//root resource class 
@Path("/root")
public class Resource1 {
  private String query1;
 
  //public constructor containing parameters
  public Resource1(@Encoded @DefaultValue("abc") @QueryParam("query") String query){
    this.query1 = query;
  }
 
  //resource method
  @GET
  public String getValue() {
    return "Your requested query parameter \"query\" is: " + this.query1;
  }
}

In this example, the root resource class com.sample.resources.Resource1 is instantiated depending on the public constructor Resource1() containing the parameter query that is annotated using the QueryParam annotation.

The Encoded annotation allows you to disable the automatic URL decoding of the parameter query. Furthermore, the DefaultValue annotation is also included and used to specify the default value if the value to be injected into the parameter query does not exist in the request sent by a client.

package com.sample.resources;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/root")
public class Resource2 {
  //public constructor without parameters
  public Resource2() {
    // Execute the process
  }
 
 //resource method
  @GET
  public String getValue(){
    return "Your request was accepted.";
  }
}

In this example, the public constructor Resource2() that does not contain parameters instantiates the root resource class com.sample.resources.Resource2.

The following example describes multiple public constructors with parameters.

package com.sample.resources;
 
import javax.ws.rs.Encoded;
import javax.ws.rs.MatrixParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.QueryParam;
 
//root resource class 
@Path("/root/")
public class Resource3 {
  private String matrix1;
  private String query1;
 
  //public constructor without parameters
  public Resource3() {
    // Execute the process
  }
 
  //public constructor with parameters(1st)
  @Encoded
  public Resource3(@MatrixParam("matrix1") String matrix1) {
    this.matrix1 = matrix1;
  }
 
  //public constructor with parameters(2nd)
  @Encoded
  public Resource3(@FormParam("form1") String form1,
      @QueryParam("query1") String query1) {
    this.form1 = form1;
    this.query1 = query1;
  }
 
  //resource method
  @GET
  public String getValue() {
    return "Your requested matrix parameter \"matrix1\" is: " + this.matrix1 +  "\n" +
      "Your requested query parameter \"query1\" is: " + this.query1;
  }
}

In this example, the second public constructor that contains the parameters matrix1 and query1, annotated respectively by the MatrixParam and QueryParam annotations, instantiates the root resource class com.sample.resources.Resource3.

The Encoded annotation used at the constructor level allows you to disable the automatic URL decoding of the parameters matrix1 and query1.

The following example describes the default constructor.

package com.sample.resources;
 
import javax.ws.rs.FormParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/root")
public class Resource4 {
 
  //resource method
  @POST
  public String getValue(@FormParam("form1") String form1) {
    return "Your requested form parameter \"form1\" is: " + form1;
  }
}

In this example, the implicitly declared default constructor Resource4() instantiates the root resource class com.sample.resources.Resource4.

If a default constructor throws the java.oi.IOException exception, an error (KDJJ10039-E) occurs, and the route resource class is not instantiated. 500 is returned as the HTTP status code.

If no public constructor is declared, an error (KDJJ10006-E) occurs, and the root resource class is not instantiated. The system returns 500 as the HTTP status code.

Note that the following constructors are not public constructors:

private constructors
protected constructors
Constructors without access identifiers

The following table describes the combinations of optional and injection annotations that you can use as constructor parameters.

Table 17-2 Annotations that can be used as constructor parameters

No.	Annotation for injection	Option annotation
No.	Annotation for injection	Encoded	DefaultValue
1	MatrixParam	Y	Y
2	QueryParam	Y	Y
3	PathParam	Y	N
4	CookieParam	N	Y
5	HeaderParam	N	Y
6	FormParam	N	Y
7	Context	N	N

Legends:: Y: Indicates the annotations that you can use in combination with injection annotations.; N: Indicates the annotations that you cannot use with injection annotations.

The optional Encoded annotation allows you to disable the automatic URL decoding of the parameters of the constructors to be injected.

The optional DefaultValue annotation allows you to specify an assumed default value, if a value is not available for injecting into the parameters of a constructor targeted for injection.

If a root resource class contains more than one public constructor with parameters, the JAX-RS engine instantiates a root resource class using the constructor with the maximum parameters. If a root resource class contains two or more constructors with the maximum parameters, the JAX-RS engine instantiates a root resource class using the constructor defined first. At this time, the warning message (KDJJ20010-W) is output to a log.

For all the conditions described below, the HTTP request will not be processed. The system returns 500 as the HTTP status code. Note that when confirming logs, you must confirm the J2EE server log file instead of the JAX-RS functionality log file.

From among the parameters of the root resource class constructor, if a parameter that uses the Injection and DefaultValue annotations throws a runtime exception while the JAX-RS engine executes the injection operation
If a default constructor of a root resource class throws a checked exception (excluding runtime exceptions) other than the java.lang.InstantiationException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, or the java.io.IOException exception

(3) Fields and Bean properties

The following table describes the combinations of injection and option annotations that you can use in the fields and bean properties of a root resource class. When instantiating a root resource class, the JAX-RS engine injects values in the annotated fields and bean properties based on annotations. The bean properties are not necessarily read-only.

Table 17-3 Annotations that can be used in fields and bean properties

No.	Annotation for injection	Option annotation
No.	Annotation for injection	Encoded	DefaultValue
1	MatrixParam	Y	Y
2	QueryParam	Y	Y
3	PathParam	Y	N
4	CookieParam	N	Y
5	HeaderParam	N	Y
6	FormParam	N	Y
7	Context	N	N

Legends:: Y: Indicates the annotations that you can use in combination with injection annotations.; N: Indicates the annotations that you cannot use with injection annotations.

The optional Encoded annotation allows you to disable the automatic URL decoding of the fields or bean properties to be injected.

The optional DefaultValue annotation allows you to specify an assumed default value, if a value is not available for injecting into the bean properties or the fields targeted for injection.

The following example describes the usage of the DefaultValue annotation in the root resource class fields.

private @DefaultValue("value1") @QueryParam("id") String id;

In this example, if the query parameter id is not specified in the URL, the field id is "value1".

The following example describes the usage of the DefaultValue annotation in the bean properties of a root resource class.

private String property1;
  
@DefaultValue("10") @QueryParam("prop1")
public void setProperty1(String property1) {
  this.property1 = property1;
}

In this example, if the query parameter prop1 is not specified in the URI, the value of the bean property property1 is "10".

The following example describes the usage of the Encoded annotation in the fields of a root resource class:

 private @Encoded @QueryParam("id") String id;

In this example, the field id is not automatically URL decoded.

The following example describes the usage of the Encoded annotation in the bean property of a root resource class.

private String property1;
  
@Encoded @QueryParam("prop1")
public void setProperty1(String property1) {
  this.property1 = property1;
}

In this example, the value of the bean property property1 is not automatically URL decoded.

From among the bean properties or the fields of the root resource class, if a parameter that uses the Injection and DefaultValue annotation throws a runtime exception while the JAX-RS engine executes the injection operation, the HTTP request is not processed. The system returns 500 as the HTTP status code. Note that when confirming logs, you must confirm the J2EE server log file instead of the JAX-RS functionality log file.

(4) Resource method

The resource method is a method of a root resource class, annotated by one of the request method designators defined in the JAX-RS specifications. A root resource class can contain one or more resource methods.

The request method designators defined in JAX-RS specifications are as follows:

GET annotation
POST annotation
PUT annotation
DELETE annotation
HEAD annotation
OPTIONS annotation

An error (KDJJ10006-E) occurs when you use two or more request method designators for one resource method, and consequently the root resource class is not instantiated. 500 is returned as the HTTP status code.

An error (KDJJ10006-E) occurs when you use the same request method designator for two or more resource methods, and consequently the root resource class is not instantiated. The system returns. 500 as the HTTP status code.

If there is no resource method to dispatch a HTTP request, system specifies 405 as the HTTP status code, and the exception mapping provider throws the exception javax.ws.rs.WebApplicationException.

The following example describes how a request method designator is used with a resource method.

@GET
@Encoded
@Produces("text/plain")
public String echo(@QueryParam("id") String id){
  return "ID is: " + id;
}

In this example, the echo() method is annotated by the GET request method designator. Furthermore, the echo() method is annotated by the Produces annotation having "text/plain" in the value to return the HTTP response where the content type is "text/plain". Note that the parameter id is annotated by the QueryParam annotation that receives the query parameter id, and is additionally annotated by the Encoded annotation to disable the automatic URL decoding of query parameters.

(a) Visibility

The resource method must be a public method to which a request method designator is applied. Although the request method designators annotate the following methods, these methods are not the resource methods:

Private methods
Protected methods
Methods without access identifiers

When you apply the request method designator to any of the above-mentioned methods, the warning message or the error message (KDJJ20003-W or KDJJ10006-E) is output to the log.

For details on KDJJ20003-W and KDJJ10006-E, see 13.7.1 Checking the syntax when initializing Web resources (KDJJ20003-W and KDJJ10006-E).

(b) Parameter annotations

The following table describes the combinations of the injection and optional annotations that can be used in the resource method parameters.

Table 17-4 Annotations that can be used in the resource method parameters

No.	Annotation for injection	Option annotation
No.	Annotation for injection	Encoded	DefaultValue
1	MatrixParam	Y	Y
2	QueryParam	Y	Y
3	PathParam	Y	N
4	CookieParam	N	Y
5	HeaderParam	N	Y
6	FormParam	N	Y
7	Context	N	N

Legends:: Y: Indicates the annotations that you can use in combination with injection annotations.; N: Indicates the annotations that you cannot use with injection annotations.

The optional Encoded annotation allows you to disable the automatic URL decoding of the parameters of the resource method to be injected.

The optional DefaultValue annotation allows you to specify the default value of the annotations, which are annotated in the parameters of the resource method to be injected.

The following example describes how to use an annotation in the parameter of a resource method.

@GET
@Produces("text/plain")
public String echo(@Encoded @DefaultValue("10") @QueryParam("id") String id, @Encoded @MatrixParam("matrix1") String matrix1){
  return "ID is: " + id + "\nMatrix1 is: " + matrix1;
}

In this example, the resource method echo() contains the parameter id annotated by the QueryParam annotation and the parameter matrix1 annotated by the MatrixParam annotation. The parameter id is additionally annotated by the Encoded and DefaultValue annotations to disable the automatic URL decoding and to specify the default value respectively. The matrix parameter is additionally annotated by the Encoded annotation to disable the automatic URL decoding.

From among the parameters of a resource method or sub-resource method, if a parameter that uses DefaultValue and the injection annotation throws a runtime exception while the JAX-RS engine executes the injection operation, an error (KDJJ10009-E or KDJJ10006-E) occurs, and consequently the HTTP request is not processed. The system returns 500 as the HTTP status code.

(c) Entity parameters

For details on entity parameters, see 17.1.2 Entity parameter.

(d) Return values

For details on return values, see 17.1.3 Return values.

(5) Sub-resource method

The resource methods annotated by the Path annotation are specifically referred to as sub-resource methods. The only difference between a sub-resource method and resource method is whether the Path annotation is used.

An example of a sub-resource method is as follows.

package com.sample.resources;
 
import javax.ws.rs.POST;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/root/") 
public class Resource1 {
 
  //sub-resource method
  @Path("sub1")
  @POST
  public String doSomething(String entityBody) {
    return "By Sub-Resource Method.";
  }
 
  //resource method
  @POST
  public String doOthers(String entityBody){
    return "By Resource Method.";
  }
}

In this example, the doSomething() method is a sub-resource method. Consider the context root of the Web application (WAR file) containing the root resource class com.sample.resources.Resource1 to be "example" and that the Web application is considered to be published on a host named "sample.com". In this case, the HTTP POST request corresponding to the URL "http://sample.com/example/root/sub1" is dispatched to the sub-resource method doSomething().

On the other hand, the HTTP POST request corresponding to the URL "http://sample.com/example/root" is dispatched to the resource method doOthers().

(6) Sub-resource locators

A method of the root resource class that is annotated only by the Path annotation and where the request method designators are not applied is called a sub-resource locator.

The sub-resource locators return sub-resource classes that execute the remaining processing of the HTTP request. For details on sub-resource classes, see 17.1.7 Sub-resource classes.

An example of a sub-resource locator of a root resource class is as follows.

package com.sample.resources;
 
import javax.ws.rs.Encoded;
import javax.ws.rs.QueryParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
//root resource class 
@Path("/root/")
public class Resource {
 
  //subresource locator corresponding to the request to context root+ "/root/sub1"
  @Path("sub1")
  public SubResource getRequestHandler(@PathParam("id") String id,
      @Encoded @QueryParam("query1") String query1) {
    return new SubResource(id, query1);
  }
}

An example of the corresponding sub-resource class is as follows.

//subresource class
public class SubResource {
  private String id;
  private String query;
 
  public SubResource(String id, String query){
    this.id = id;
    this.query = query;
  }
  @GET
  public String getRequestParameter(){
    return "ID is: " + this.id + "\nQuery is: " + this.query;
  }
}

In this example, the root resource class com.sample.resources.Resource does not process the HTTP request directly. com.sample.resources.SubResource processes the sub-resource class returned by the sub-resource locator getRequestHandler.

You consider the context root of the Web application (WAR file) containing the resource class com.sample.resources.Resource to be "example" and that the Web application is assumed to be published on a host named "sample.com". In this case, the HTTP GET request corresponding to the URL "http://sample.com/example/root/sub1?query1=10" is dispatched to the method getRequestHandler() of the root resource class com.sample.resources.Resource.

The resource method getRequestParameter() of the sub-resource class com.sample.resources.SubResource executes the remaining processing of the HTTP GET request.

If you use an entity parameter as the parameter of a sub-resource locator, the (KDJJ10006-E) error occurs, and consequently the HTTP request sent by the client is not processed. The system returns 500 as the HTTP status code.

The operation when a sub-resource locator is not public, the sub-resource class performs the same operations as the operations of resource method.

If the type of the return value of a sub-resource locator is void, the (KDJJ10006-E) error occurs, and consequently the HTTP request sent by the client is not processed. The system returns 500 as the HTTP status code.

From among the parameters of sub-resource locators, if a parameter that uses the Injection and DefaultValue annotation throws a runtime exception when the JAX-RS engine executes the injection operation, the HTTP request is not processed. The system returns 500 as the HTTP status code. Note that when confirming the log, you must confirm the J2EE server log file instead of the JAX-RS functionality log file.

17.1.1 Root resource classes