RequestResponse

From APIDesign

Revision as of 20:49, 25 June 2008

Response Reply

Design pattern that solves the problem of growing parameters and return values from API methods. Beyond its basic purpose, it can help with delivering multiple results and providing the results in an incremental way, one by one. It also helps a lot with ability to cancel a computation in the middle.

public interface ComputeSomething {
    public void compute(Request request, Response response);
 
    public static final class Request {
        Request() {}
 
        public int getArg1();
        public String getArg2();
    }
 
    public static final class Response {
        Response() {}
 
        public void addResult(int r);
        public void addResult(String[] arr);
    }
}

Evolution Story

The evolution of the whole pattern is based on the assumption that the fixed point of communication with users of the API is the ComputeSomething interface with its one method that has to be implemented. From this interface we have two evolution paths:

1. clients of the API can require more methods to call. those can be added to Request class
2. the infrastructure may want to give the clients more richer way to specify return values. This means to add new methods into the Response class.

Additional Attributes

This API pattern naturally solves the problem of multiple return values from a method. Java does not support that easily, while with Response class, it is easy to add new result methods into it. Allowing type safe extensibility of return types.

Also this API pattern supports incremental return values, as compute method can work in a loop and add one result by another into the Response class, feeding it by as many results as possible.

Related to this, the API pattern allows the infrastructure, which provides the Response class, to process the results sooner before they are fully computed. The compute method can still be running, incrementally computing its results, and yet, the infrastructure may process the already generated values.

Last, but not least, this API pattern supports easy interruption of long computations. The Response or even the Request can contain boolean isCancelled() method which may allow the provider of the compute method implementation to check this value and exist earlier, before everything is computed. In addition to this, the addResult methods can check this flag themselves, and potentially abort the computation by their own, usually by emitting some checked exception.