Sub-resource class

A sub-resource class is a Java class that contains any one of the resource methods, sub-resource methods, or sub-resource locators, and is not annotated by the Path annotation at the class level.

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

package com.sample.resources;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
public class Resource {
  @Path("/subresourcemethod1")
  @GET
  public String subResourceMethod1() {
    return "from sub resource method1";
  }
  @GET
  public String resourceMethod() {
    return "from resource method";
  }
}

The JAX-RS engine does not generate an instance of a sub-resource class. The sub-resource class must be instantiated with a corresponding sub-resource locator.

Organization of this subsection: (1) Mechanism; (2) Life cycle; (3) Constructor; (4) Fields and bean properties; (5) Resource methods, sub-resource methods, and sub-resource locators

(1) Mechanism

A sub-resource class is generated in the following way. The generated sub-resource class processes an HTTP request as follows:

The HTTP request is dispatched to the sub-resource locator.
The sub-resource locator generates a sub-resource class and delegates the processing of the HTTP request to the generated sub-resource class.
The sub-resource class directly processes the HTTP request, or the request is further delegated to a sub-resource class in the same way.

For details on sub-resource locators, see 17.1.1(6) Sub-resource locators.

The JAX-RS engine treats the instance returned by the sub-resource locator at runtime as a sub-resource class and not the return value type declared in the method signature of the sub-resource locator.

For example, assume that there are three sub-resource classes - M, N and O. N inherits M and O inherits N. In the same way, assume a sub-resource locator named R that contains the return value M. When a sub-resource locator returns an instance of M, the sub-resource class M executes the HTTP request. Similarly, when the sub-resource locator returns an instance of N, the sub-resource class N executes the HTTP request. When the system returns an instance of O, the sub-resource class O executes the HTTP request.

(2) Life cycle

A JAX-RS engine does not generate an instance of a sub-resource class. The sub-resource class must be instantiated with the corresponding sub-resource locator. Accordingly, the bean properties, fields, and parameters of the constructor must be initialized with a sub-resource locator or a sub-resource class.

(3) Constructor

(4) Fields and bean properties

(5) Resource methods, sub-resource methods, and sub-resource locators

A resource method of a sub-resource class, a sub-resource method, and a sub-resource locator match with the resource methods of the root resource class except for the differences explained hereafter. For details on root resource classes, see the following sub-sections:

If the return value type of a sub-resource locator is void, an error occurs and the HTTP request sent by the client is not processed. 500 is returned as the HTTP status code. Note that you must confirm the J2EE server log file instead of the JAX-RS functionality log file.

When the following conditions hold true, the (KDJJ10006-E) error occurs, and consequently the system throws java.lang.RuntimeException, which can be handled by the exception mapping provider.

When two or more request method designators are used for one resource method
When the same request method designator is used for two or more resource methods
When a sub-resource locator contains an entity parameter

17.1.7 Sub-resource class

(1) Mechanism

(2) Life cycle

(3) Constructor

(4) Fields and bean properties

(5) Resource methods, sub-resource methods, and sub-resource locators