Using Request Filters to customize behavior and HTML generation

Request filters provide the ultimate control over the behavior and the HTML generation in WebCream. They allow pre- and post-processing of requests on several layers, starting from the servicing of HTTP request till the rendering of windows. Request filters wrap the default processing logic in WebCream, which allows interception and manipulation of requests and customization of generated HTML. Using request filter requires implementation of an interface provided by WebCream. The following section briefly discusses WebCream architecture and proceeds to show how to implement the required interface methods.

Request Processing Architecture

WebCream architecture follows HTTP request-response paradigm. Each internet user is associated with a virtual client that executes inside a JVM on the server. When the first request is received for an application, WebCream creates the application descriptor and initializes the client agent which typically runs the application's main() method. When main() returns, WebCream renders the top window as an HTML page and returns it as HTTP response to the browser. Subsequent requests are forwarded to the window that is currently in focus in the virtual application. WebCream uses a router servlet called WebCreamRouter that receives all requests, processes request parameters and dispatches the requests to the client agent. The client agent, which represents the virtual client application, first updates the user interface elements with the data received from the browser. This can include updating text of text fields, setting a new selected tab in tabbed pane or changing the selection state in a table. After the components are updated with the data, WebCream emulates the action. The action corresponds to the action in the browser that triggered the page submit. For instance, if the user pressed a button, the action emulation would be a click on the button in the virtual application. In certain cases there is no action to emulate (window resize is an example). Finally, the agent renders the window that is currently in focus as an HTML page and returns to the router servlet. The router writes the page to the response and completes the processing of the request. The simplified sequence diagram of request processing is shown below.

Request Filters

Request filters are classes that implement one or both of WebCream request filtering interfaces. If the request filters are registered, they are loaded at startup and their appropriate methods are executed as the request is being processed. The following diagram shows how and when each method is executed.

The first interface is RouterRequestFilter, which allows execution of custom code on the router servlet layer. After the implementation class is developed, it should be placed on WebCream's class path and registered in the WebCream/conf/default.properties configuration file using router.requestFilterClass property. Because the router servlet is shared by all applications, the router request filter will be called on any HTTP request received by WebCreamRouter. For sample implementation refer to RouterRequestFilterExample.java, which shows how to use router request filter to pass the remote user's IP address to the client agent and how to selectively append text to the generated HTML page. JavaDoc on RouterRequestFilter provides detailed documentation of methods and their parameters.

The second interface is AgentRequestFilter, which allows execution of custom code on the virtual client layer. After the implementation class is developed, it should be placed on WebCream's class path and registered in the application configuration file using agent.requestFilterClass property.  For sample implementation refer to AgentRequestFilterExample.java, which shows how to use agent request filter to intercept resize requests to a selected window and how to modify generated HTML to include user IP address passed by the RouterRequestFilterExample. JavaDoc on AgentRequestFilter provides detailed documentation of methods and their parameters.