1 package pt.digitalis.dif.controller.interfaces;
2
3 import pt.digitalis.dif.controller.objects.RESTAction;
4 import pt.digitalis.dif.exception.controller.ControllerException;
5
6 /**
7 * AbstractChAL stands for <b>Ch</b>annel <b>A</b>bstraction <b>L</b>ayer and as the name implies it's purpose is to
8 * insulate the framework from the transport channel used by the original request. As can be implied from the statement
9 * above, AbstractChAL should be tailored to take care of a specific transport channel details. As such, AbstractChAL
10 * should be extended using inheritance and is the subclass that should be instantiated. To enforce the subclass
11 * instantiation AbstractChAL is declared <code>abstract</code>. AbstractChAL is responsible for translating the
12 * original request into a format that the framework can understand, then executing the appropriated Dispatcher and
13 * finally publish the results.
14 *
15 * @author Pedro Viegas <a href="mailto:pviegas@digitalis.pt">pviegas@digitalis.pt</a>
16 * @param <RequestType>
17 * the type of request of the specific AbstractChAL
18 * @param <ResponseType>
19 * the type of response of the specific AbstractChAL
20 */
21 public interface IChAL<RequestType, ResponseType> {
22
23 /**
24 * This method is responsible for the response translation from the framework internal format into the channel's own
25 * format. Each AbstractChAL should implement this method in a way adapted to the specific needs of the incoming
26 * request. The original request type is passed to the method because some technologies (such as Servlets) don't
27 * allow content writing on the response object.
28 *
29 * @param difResponse
30 * the framework's response
31 * @param originalRequest
32 * the original request
33 * @param finalResponse
34 * the response to send back to the Listener
35 */
36 public void publish(IDIFResponse difResponse, RequestType originalRequest, ResponseType finalResponse);
37
38 /**
39 * This method will be called by the client via Listener.
40 *
41 * @param originalRequest
42 * the original request made by the client
43 * @param finalResponse
44 * the response object passed by the Listener and that will be sent back
45 * @param action
46 * the REST action if specified
47 * @return the DIFResponse containing the framework's response
48 */
49 public IDIFResponse serve(RequestType originalRequest, ResponseType finalResponse, RESTAction action);
50
51 /**
52 * This method should receive the request from the Listener and translate it to a format understandable by the
53 * framework. Each AbstractChAL should implement this method in a way adapted to the specific needs of the incoming
54 * request.
55 *
56 * @param originalRequest
57 * The request received from the Listener
58 * @return a BaseDIFRequest object that will be sent to the Dispatcher
59 * @throws ControllerException
60 * when any runtime exception is thrown
61 */
62 public IDIFRequest translateRequest(RequestType originalRequest) throws ControllerException;
63 }