To start developing you require a source tree, or directory structure, suitable to hold all the source files required by the application. The Toolbox provides a utility script that creates an initial source tree structure. Perform the following to create a new source tree using the dirgen script:

Create the root of the source tree in a directory of your choice. The source root directory should reflect the application name:

The following directories will be visible in the beansdemo directory:

The dirgen script provides a starting point, but these directories can be supplemented as required by adding additional top level and sub- directories. Our application will be using a database, and for this purpose we will create one additional directory named sql that will contain the scripts required to generate the required database resources.

This section assumes that you have a running MySQL server and that you have permissions to create users and databases.

Our application requires the use of a database. Create the following two SQL scripts in the sql directory of your source tree:

The next step is to execute our scripts against the MySQL server using the mysql client application. Execute the following commands from the sql directory of your source tree:

Our database is configured and ready.

The Java Bean pattern is very useful for defining domain objects within an application realm. It allows us to decouple application logic from the details of the physical data store. Developing beans by hand can get rather tedious. The Toolbox provides a convenient utility, called the BeanGenerator, that is capable of generating Java Bean code based on an XML definition.

The utility can be invoked using the beangen script, located in the bin directory of the distribution, and has the following command synopsis:

In the previous section we created the required database tables. Now we will create the required beans that will map to the tables using the BeanGenerator utility.

First we have to prepare our java source directory with the required package structure to accommodate our beans. Execute the following command in the java directory of your source tree.

Next we have to author the appropriate XML definitions for our beans in the etc/beans directory of your source tree.

The first section of the definition specifies the class name, package name, imports and class level comment that will be used when generating the bean. The Properties section of the definition specifies all the bean properties for which a get() and a set(..) method will be created. The Mappings section of the document specifies property to database field mappings.

We are now ready to execute the BeanGenerator utility that will create the required Java source files for our defined beans. Perform the following from the top of your source tree:

Our beans are ready for compilation and use.

Application Services, in the context of the Toolbox, are API's that expose the necessary application functionality by hiding all of the complex details involved in the implementation of the application logic.

The Toolbox provides an API, in the form of the toolbox.services.* packages, to develop application services. The API provides high level abstractions for data access, integration (Mail,JMS,etc) and configuration facilities.

First we have to prepare our java source directory with the required package structure to accommodate our service. Execute the following command in the java directory of your source tree.

Next we will develop the Application Service. For the purpose of this example we will implement the application service by first creating a java interface that defines the public interface of the service, followed by an implementation class implementing the interface.

This is not required when using the services API, but serves as an example of doing contract driven implementation; i.e isolating application clients from the implementation details of the service.

Create the following source files in the java/app/services directory of your source tree:

You will notice that the code contains no JDBC API calls. The API provides a high level abstraction for JDBC and provides a flexible configuration facility that will be discussed in the Configuration section.

At this stage we have completed our application backend development by creating the beans and service. In the next section we will start the presentation tier development.

When developing web applications it is useful to be able to handle certain aspects, such as HTTP form submissions, as isolated and atomic pieces of logic. The Toolbox provides an API, in the form of the toolbox.web package, that provides a layer of abstraction on top of Servlet technology that facilitates action driven web application development.

The API provides the WebAction interface to facilitate action driven web application development.

Our application requires that we capture and update information to the database tables. To satisfy this requirement we will develop three WebAction implementations to interact with our ProductService Application Service.

Our action implementations will be subclasses of the toolbox.web.BaseWebAction class. This base class provides access to configuration properties and convenience methods for developing action implementations.

First we have to prepare our java source directory with the required package structure to accommodate our actions. Execute the following command in the java directory of your source tree.

Create the following three source files in the java/app/web directory of your source tree:

The configuration of these action implementations will be covered in the Configuration section.

In some cases it is required to access application data from within a web application view. To ease the interaction between web application views and Application Services we can expose application data by ways of View Helpers.

Our application will be using the FreeMarker Template Engine to render web application views. The Toolbox provides a Servlet implementation that acts as a wrapper around the template engine. This implies that all view requests can be forwarded using a normal javax.servlet.RequestDispatcher to the Toolbox provided wrapper Servlet (toolbox.web.ViewServlet). The ViewServlet also provides a facility to expose methods, implemented using the FreeMarker template API, within view templates.

In our application there is a requirement to view all the entries in the database tables, aswell as a requirement to retrieve a single entity's information using a primary key. To make the interaction between the views and the Application Service as simple as possible we will implement three methods (View Helpers) using the freemarker.template.TemplateMethodModel interface. The interface defines one method, Object exec(List), that must be implemented.

First we have to prepare our java source directory with the required package structure to accommodate our view helpers. Execute the following command in the java directory of your source tree.

Create the following three source files in the java/app/web/helper directory of your source tree.

The configuration of these method implementations will be covered in the Configuration section.

Our application will be using the FreeMarker Template Engine to render the web application views. In this section we will author all the templates required by our application.

First we need to update our source tree to accommodate all the required templates and associated files. Execute the following commands in the htdocs directory of your source tree:

The Toolbox provides some useful template macros to facilitate with the development of XHTML pages. The templates can be viewed in the share/freemarker directory of the distribution.

Create the following templates in the htdocs/ftl directory of your source tree: