Page History

...

Any incoming GET request that has the URL of "/welcome" is handled by WelcomeMessage class's returnWelcomeMessage() method. A string is returned that represents the response body and is sent as the response payload in a HTTP 200 status response.

Using a javax.ws.rs.core.Response

In the above previous GET resource method example, the response body is returned as a String. If a more complex response is required (i.e. requiredfor example, additional HTTP response headers , or a different status code, etc.), a javax.ws.rs.core.Response should be used as the Java method's return type. By building a Response object, additional information can be returned to the client.

@Path("/welcome")
public class WelcomeMessage {
    private String welcomeMessage = "Hello world!";

    @GET
    public Response returnWelcomeMessage() {
        String responseEntity = welcomeMessage;
        return Response.status(299).entity(responseEntity).header("CustomHeader", "CustomValue").build();
    }
}

While the above The previous example uses 299 as the status code, standard HTTP status codes should be used in order to help clients understand responses. Also, while Strings have been used When using Strings as the response entity, different Java types may be used for complex responses. See

Using Common HTTP Methods (@GET, @POST, @PUT, @DELETE)

There are well-defined HTTP methods that can be issued. The 4 The four most common HTTP methods are GET, POST, PUT, and DELETE.

As shown in the previous example above, a an HTTP GET response to "/welcome" would invoke invokes the Java method returnWelcomeMessage() Java method. To In order  to add a Java method that would be invoked when a HTTP PUT request is made to "/welcome", add the following code should be added:

@Path("/welcome")
public class WelcomeMessage {
    private String welcomeMessage = "Hello world!";

    @GET
    public String returnWelcomeMessage() {
        return welcomeMessage;
    }

    @PUT
    public String updateWelcomeMessage(String aNewMessage) {
        welcomeMessage = aNewMessage;
    }
}

Notice that the updateWelcomeMessage has an unannotated parameter which represents an incoming request's body. See

Subresource Methods (@Path and @GET, @POST, @PUT, @DELETE on a Java method)

Sometimes it is easier having a root resource resolve a generic URL path and to have @Path annotated methods further resolve the request. For instance, suppose that a HTTP GET to "/administrator" returned generic information about an administrator. However, sometimes it is better to return smaller bits or more detailed information about the resource using a slightly different URL identifier. Suppose that a HTTP GET to "/administrator/name" should return the name. Instead of creating many root resource classes for each URL, you can have the root resource initially resolve the beginning of the URL request and then further resolve the request against subresource methods.

...

@Path("/administrator")
public class Administrator{

    @GET
    public String findUserInfo() {
        String userInfo = null;
        /* build user info */
        return userInfo;
    }

    @GET
    @Path("/name")
    public String getJustUserName() {
        String userName = "";
        /* get the user name */
        return userName;
    }

    @GET
    @Path("/id")
    public String getUserId() {
        String userId = "";
        /* get the user id */
        return userId;
    }
}

A An HTTP URL request to the "/administrator" would resolve to Administrator#findUserInfo(). A HTTP URL request to "/administrator/name" would invoke the Administrator#getJustUserName() method. Finally a HTTP URL request to "/administrator/id" would resolve to Administrator#getUserId().

Using Subresource Locators (@Path on Java method)

In more complicated scenarios, subresource locators are needed. Subresource locators are particularly useful when requests must be further resolved by other objects. Subresource locators are Java methods which have only an @Path annotation. They are different than subresource methods because they do not have any HTTP method annotation on them.

...