Page History

...

Resources are one of the fundamental concepts in REST. REST emphasizes the manipulation of resources rather than issuing function calls. Resources have unique identifiers. In HTTP terms, this means associating every resource with at least one URL.

To In order to manipulate a resource, requests are made with a specific HTTP method. For instance, in order to retrieve a representation of a resource, a an HTTP GET request to the resource's URL is issued. To In order to create a new item in a collection, a an HTTP POST could can be used with the collection URL.

Application developers can define resources and the HTTP methods in order to quickly manipulate them very quickly by using regular plain old Java objects and JAX-RS annotations.

...

Defining a Root Resource (@Path on Java class)

Developers can use POJOs to define a resource. Root resources have a @Path annotation at the class declaration level. JAX-RS matches an incoming request's URL with the @Path annotation on all of an application's root resources in order to determine which initial Java class will handle the request.

Root resources Java class instances are created per request by default. See

Resource classes have methods that are invoked when specific HTTP method requests are made, referred to as resource methods. To In order to create Java methods that will be invoked with specific HTTP methods, implement a regular Java method must be implemented and annotate it annotated with one of the JAX-RS @HttpMethod annotated annotations (namely, @GET, @POST, @PUT, and @DELETE).

For instanceexample, if there's a resource that is located at a "/welcome" URL, the following root resource could be is defined.

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

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

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

...

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

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

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

...

@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;
    }
}

...

@Path("/users")
public class UsersCollection {

    @Path("{userid}")
    public Object findUserInfo(@PathParam("userid") String userId) {
        if(userId.equals("superuser")) {
            return new SuperUser();
        }
        return User.findUserInDatabase(userId);
    }
}

public class Superuser { 
    @GET
    public String getUserInfo() {
       String userInfo = /* get the user info */;
       return userInfo;
    }

    @GET
    @Path("/contactinfo")
    public String getContactInfo() {
      String contactInfo = /* get the user contact info */;
      return contactInfo;
    }
}

public class User {
    protected String name;

    protected User() {
        /* subresource locator object lifecycles are controlled by the developer */
    }

    public static User findUserInDatabase(String userName) {
        User u = /* get user from database with assigned field values */
        return u;
    }

    @GET
    public String getInfo() {
        String info = /* get the user info */;
        return info;
    }

    @GET
    @Path("/name")
    public String getMyUserName() {
        return name;
    }
}

...