How to manage state in JAX-RS?

Question

How do I configure JAX-RS 2 implementation (RESTEasy 3) to send the state of the application to the client?

In JSF I am able to do it using the STATE_SAVING_METHOD parameter.

Is there a standard way of doing it using JAX-RS?

<context-param>
    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
    <param-value>client</param-value>
</context-param>

Just an example to illustrate my problem, I would like to configure the JAX-RS provider to return the cart variable state to the client, in that way I won't keep the data in-memory or persist the session state.

@Path("/cart")
public class ShoppingCart {

    // List of products presented to the user
    private List<Product> availableProducts;

    // Products selected by the user
    private List<Product> cart;

    @GET
    public List<Product> addProduct() {
        return availableProducts;
    }

    @POST
    public void addProduct(Product product) {
        cart.add(product);
    }

}

Update

I would like to add references that support the idea of managing the state of the appliations. I agree that in theory, all services should be stateless, but in practice I found out that many scenarios would make more sense if the state could be maintained, specially for security and productivity reasons.

It seems that the pattern is usually done via hyperlinks, with the content properly encrypted to secure data and integrity. I am now looking into the JAX-RS tools that support these scenarios.

How to Manage Application State from the RESTful Web Services Cookbook:

Since HTTP is a stateless protocol, each request is independent of any previous request. However, interactive applications often require clients to follow a sequence of steps in a particular order. This forces servers to temporarily store each client’s current position in those sequences outside the protocol. The trick is to manage state such that you strike a balance between reliability, network performance, and scalability.

And also from the JAX-RS documentation:

Stateful interactions through hyperlinks: Every interaction with a resource is stateless; that is, request messages are self-contained. Stateful interactions are based on the concept of explicit state transfer. Several techniques exist to exchange state, such as URI rewriting, cookies, and hidden form fields. State can be embedded in response messages to point to valid future states of the interaction. See Using Entity Providers to Map HTTP Response and Request Entity Bodies and “Building URIs” in the JAX-RS Overview document for more information.

this is against REST philosophy, a server shouldn't maintain the state of the clients, it should be stateless, of course you can do what you want :) — La VloZ Merrill, Apr 19 '16 at 07:35
I've updated my question with some solid references supporting this technique. — Evandro Pomatti, Apr 19 '16 at 17:54

score 4 · Accepted Answer · edited Oct 07 '21 at 08:57

While lefloh provided a very clear answer, I'd like to add a few more details that will help you to understand the REST architecture.

The REST architectural style

REST stands for Representational State Transfer. This architecture is protocol independent but it is frequently implemented over the HTTP protocol.

The REST architectural style was defined in the chapter 5 of Roy Thomas Fielding's PhD dissertation. And the following set of constraints was added to this architectural style:

Through the application of the constraints defined above, certain architectural properties are induced, such as visibility, portability, reliability, scalability and network efficiency.

The stateless constraint

In a REST applications, each request from the client to the server must contain all the necessary information to be understood by the server. With it, you are not depending on any session context stored on the server and you do not break the stateless constraint:

5.1.3 Stateless

[...] communication must be stateless in nature [...], such that each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client. [...]

When accessing protected resources that require authentication, for example, each request must contain all necessary data to be properly authenticated/authorized. It means the authentication will be performed for each request.

JAX-RS lifecycle

When creating a REST application using JAX-RS, you have resource classes, that is, Java classes that uses JAX-RS annotations to implement a corresponding Web resource.

Resource classes are POJOs that have at least one method annotated with @Path or a request method designator (@DELETE, @GET, @HEAD, @OPTIONS, @POST, @PUT, custom annotations created with @HttpMethod).

According to the JAX-RS specification, resource classes follow a well defined lifecycle:

3.1.1 Lifecycle and Environment

By default a new resource class instance is created for each request to that resource. First the constructor is called, then any requested dependencies are injected , then the appropriate method is invoked and finally the object is made available for garbage collection. [...]

In JAX-RS, there's no such javax.faces.STATE_SAVING_METHOD or similar. There's no state. There's no session.

Your resource class can follow the pseudo-code suggested in lefloh's answer. And don't forget you always can perform injections into your resource class:

<!- language: lang-java -->

@Path("/cart")
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
public class ShoppingCart {

    @Inject
    private ShoppingCartService service;

    @GET
    public Response getProducts() {
        ...
    }

    @POST
    public Response addProduct(Product product) {
        ...
    }
}

Hyperlinks in JAX-RS

A very important aspect of REST is hyperlinks, URIs, in representations that clients can use to transition the web service to new application states. This is known as hypermedia as the engine of application state, frequently abreviated as HATEOAS.

JAX-RS 2.0 introduced the Link class, which serves as a representation of the web link defined in RFC 5988. The JAX-RS Link class adds API support for providing additional metadata in HTTP messages.

A Link can be serialized to the HTTP response as additional HTTP header (there might be multiple Link headers provided, thus multiple links can be served in a single message). Such HTTP header may look like:

Link: <http://example.com/api/books/1/chapter/2>; rel="prev"; title="previous chapter"

Producing Links with JAX-RS API can be done as following:

Response response = Response.ok()
                      .link("http://example.com/api/books/1/chapter/2", "prev")
                      .build();

Instances of Link can be also created directly by invoking one of the factory methods on the Link API that returns a Link.Builder that can be used to configure and produce new links:

URI uri = URI.create("http://example.com/api/books/1/chapter/2");
Link link = Link.fromUri(uri).rel("prev").title("previous chapter").build();

Response response = Response.ok().link(link).build();

Links can be also added to your response entity models:

public class Book {

    private String title;
    
    private Link link;
    
    // Default constructor, getters and setters ommited
}

When serialized to JSON, for example, you will have something like:

{
    "title" : "The Lord of the Rings",
    "link" : {
        "rel" : "self",
        "uri" : "http://example.com/api/books/1",
        "title": "self"
      }
}

Cássio, very complete but can you please check the bullet [Stateful interactions through hyperlinks](https://docs.oracle.com/cd/E19798-01/821-1841/giepu/index.html) from the JAX-RS documentation. There are state management strategies provided by the framework, not that they are compliant to RESTful architecture. Usually encrypted URI values seems to used. — Evandro Pomatti, Apr 19 '16 at 18:12
@BonanzaOne I updated my answer with a few more details that may be useful for you. — cassiomolin, Apr 19 '16 at 19:28
Very good answer but your `ShoppingCart` example code lacks the information how the cart should be identified. Why not adding a path parameter? — lefloh, Apr 20 '16 at 07:10

score 2 · Answer 2 · answered Apr 19 '16 at 06:38

2

As you usually avoid serverside state in a RESTful application you simply can't send the state to the client. You don't have one. Usually you identify your resources by an URI and fetch them from for instance a database.

In pseudo-code you may implement it this way:

@Path("{customerId}/cart")
public class ShoppingCart {

    @GET
    public List<Product> getProducts(@PathParam("customerId") long customerId) {
        // check if the caller has access-rights
        // fetch all products for given customerID from a database, 
        // and return it to the client
    }

    @POST
    public Response addProduct(@PathParam("customerId") long customerId, Product product) {
        // check if the caller has access-rights,
        // save the product in the database
        // and return a 201 maybe with the product as entity
    }

}

answered Apr 19 '16 at 06:38

lefloh

10,653
3
28
50

I agree with you, but (1) Constantly validating data against the authentication seems to be too much work, which in my web experience are solved by the presentation layer (2) There might be a scenario where I'll need to transfer state. I've found solid references pointing to that, which I'll increment to my question. Could you please check it out and share your thoughts? – Evandro Pomatti Apr 19 '16 at 17:37
1) Every technique has it's pros and cons. 2) There's no problem mit transferring state. Problem is holding it in the memory of the server. Having a typical wizard you can of course e.g. add the values from page one as hidden input fields to page 2 and get 'the full state' when the client submits this page. – lefloh Apr 20 '16 at 07:16