Toolbox Web API

$Id: web_api.xml,v 1.4 2008/10/17 11:33:59 hannes Exp $

Copyright © 2006 - 2012 Hannes Holtzhausen

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Table of Contents

1. Introduction
2. Web API Components
2.1. Filter Chain
2.2. Front Controller
2.3. Action
2.4. View
2.5. View Helper
2.6. Service Layer

1. Introduction

This document describes the functionality and purpose of the Toolbox Web API, as it is implemented in the toolbox.web.* packages. The API attempts to provide an implementation of a simple reference architecture that can be utilised to build J2EE based web applications.

2. Web API Components

The following sequence diagram shows the interaction between all components of the Web API:

Sequence One. The first sequence shown in the diagram describes a client request that results in a complext sequence of events that involve input validation, applying business logic and rendering the required view based on the result of applying the business logic. This type of sequence would most likely be triggered as a result of a user completing and submitting an HTML form.

Sequence Two. The second sequence shown in the diagram describes a less complex sequence that only involves the retrieval of some dynamic application data. No complex business logic or validation is required. This type of sequence would most likely occur to display an HTML form that contains dynamic elements such as select options or radio groups.

Sequence Three. The third sequence shown in the diagram describes a very simple sequence that involves no business logic or retrieval of application data. This type of sequence would most likely occur to display some form of informational page or message.

The following image provides a logical view of the Web API architecture:

The following sections will provide more detailed information about each of the API components, including implementation details.

2.1. Filter Chain

The Filter Chain provides intercepting filter functionalities. These functionalities may include supplementing client requests with generic information or simply rejecting client requests based on certain criteria. The Filter Chain provides a pluggable mechanism for generic and application specific operations that would otherwise have to be implemented at the Front Controller or Action levels. Implementing these functionalities at the Front Controller level could possibly result in tight coupling between the Front Controller and the application. This would render the Front Controller unusable across multiple applications. Implementing these functionalities at the Action level could result in cluttered or overly complex Action implementations.

The Web API does not provide a custom Filter Chain implementation, but instead relies on of the javax.servlet.Filter interface to provide the required infrastructure.

The Web API provides a few reusable filter implementations that can be configured for use with web applications:

  • SyncTokenFilter to detect the duplicate submission of HTML forms.

  • UserInfoFilter to facilitate direct integration with user repositories to retrieve user information.

  • PermissionFilter to apply authorisation based upon a client's session state. Detailed information on the configuration of the filter is provided in the DTD Reference.

  • OpenSSOFilter to perform single sign-on token validation and attribute retrieval from the OpenSSO access management system. This filter is provided as part of the Toolbox OpenSSO Module.

2.2. Front Controller

The Front Controller provides a single point of contact for all client requests. It provides a central point for implementing flow logic and Action management. In the absence of a Front Controller, flow logic and Action management would be spread across multiple Servlets and views, like JSP's, making it difficult to maintain and extend functionality.

The Web API provides a thin and configurable Front Controller implementation in the form of a javax.servlet.http.HttpServlet implementation. The ControllerServlet is configured using an XML document. Detailed information on the configuration document can be found in the DTD Reference.

2.3. Action

Actions provide an abstract type that can be implemented to perform input valiation and apply business logic through the use of the Service Layer. Actions provide atomic units of functionality that can be managed and invoked by the Front Controller. Actions can supplement client requests with the results of applying business logic and make decisions based on the results. In the absence of Actions, the interaction with business logic components would have to be implemented in views, like JSP's, or Java Servlets.

The Web API provides a simple interface and base class, in the form of the WebAction interface and BaseWebAction class, to facilitate action driven development. Actions are configured using the ControllerServlet XML configuration document. Detailed information on the configuration document can be found in the DTD Reference. The Web API also provides an input validation mechanism at the action level. The input validation mechanism is implemented in the toolbox.web.validation package. The package provides a generic Validator implementation that can be configured with an XML configuration document. Detailed information on the configuration document can be found in the DTD Reference.

2.4. View

Views represent the user interface. A view includes style elements (colours, fonts, logos, etc) and page layouts. In most J2EE based web applications views are implemented as JSP pages. A view is generated as a result of a client request. The view is responsible for displaying the results of a client request by formatting the information contained in, either the supplemented request, or by using View Helpers to obtain dynamic data.

Even though it is possible to use JSP's with the Web API, it is not the preferred view technology. The preferred alternative is to use a dedicated templating solution and specifically the FreeMarker template engine. The Web API provides a configurable wrapper servlet for the template engine, in the form of the ViewServlet. All view requests can be delegated to the ViewServlet. More detailed information on the configuration of the servlet can be found in the ViewServlet DTD Reference.

In a addition to the ViewServlet, a set of FreeMarker macros are provided to assist with the development of XHTML web pages. More information can be found in the Reference Guide.

2.5. View Helper

In some situations it is required to display application data as part of a view, but it is impratical to implement an Action to obtain the application data as no business logic or flow control is required. In situations like this the View Helper addresses the requirement by accessing application data without having to expose the Service Layer to the view directly. An example might be to display application data in select options on an HTML form. The View Helper reduces the coupling between the Service Layer and the view and so keeps the view implementations clean.

The FreeMarker template engine provides the freemarker.template.TemplateMethodModel interface that allows developers to create custom methods that can be used within templates. The ViewServlet XML configuration document provides a facility to incorporate these methods into the servlet at runtime. More detailed information on the configuration of the servlet can be found in the ViewServlet DTD Reference.

The Web API provides a few reusable method implementations that can be configured for use with web applications and can be found in the toolbox.web.template package:

  • DoBase64 to perform Base64 encoding and decoding.

  • GetBundle provides access to java.util.ResourceBundle instances.

  • GetSystemTime returns the system time as java.util.Data.

2.6. Service Layer

The Service Layer does not form part of the Web API, but refers to the interface that the Web API components must use to access business logic and information systems. The Service Layer can take many forms: It can be a wrapper around Enterprise Session and Entity Beans to abstract the lookup and interaction with these components. It can be a wrapper around Data Access Objects (DAO) to ease the interaction with the application data store.

The Toolbox Services API provides the necessary infrastructure to facilitate the development of very flexible and coarse grained service orientated API's that are well suited for use as a Service Layer.