Java Web Application Development With Click Framework/Configuration

This section discusses how to setup configure a Click web application and covers to following topics:


 * How to set up the ClickServlet
 * How to configure the Click application descriptor
 * How to configure the Velocity runtime properties
 * Automatically deployed Click files

The Click configuration files include:

Servlet Configuration
For a Click web application to function the ClickServlet must be configured in the web application's /WEB-INF/web.xml file. A simple web application which maps all  *.htm  requests to a ClickServlet is provided below.

By default the ClickServlet will attempt to load an application configuration file using the path: /WEB-INF/click.xml

If this file is not found under the WEB-INF directory, then the ClickServlet will attempt to load it from the classpath as /click.xml.

Servlet Mapping
By convention all Click page templates should have a .htm extension, and the ClickServlet should be mapped to process all *.htm URL requests. With this convention you have all the static HTML pages use a .html extension and they will not be processed as Click pages.

Load On Startup
Note you should always set load-on-startup element to be 0 so the servlet is initialized when the server is started. This will prevent any delay for the first client which uses the application.

The ClickServlet performs as much work as possible at startup to improve performance later on. The Click start up and caching strategy is configured with the Click application mode element in the "<tt>click.xml</tt>" config file.

Application Configuration
The heart of a Click application is the <tt>click.xml</tt> configuration file. This file specifies the application pages, headers, the format object and the applications mode.

See Appendix C: Click DTD for the click-app XML definition.

A simple Click app config file is provided below:

An example of an optioned up config file is:

Click App
The root click-app element defines two application localization attributes charset and locale.

The charset attribute defines the character encoding set for:


 * Velocity templates
 * HttpServletRequest character encoding
 * Page Content-Type charset

The locale attribute defines the default application Locale. If this value is defined it will to override Locale returned by the request.

For example the following configuration sets the application character set to UTF-8 and the default Locale as German (de):

Pages
The first child element of the click-app is the mandatory <tt>pages</tt> element which defines the list of Click pages.

The pages element can specify a default package name which is prepended to the classname of any pages defined.

The pages element also defines the automapping attribute.

Page
The page element defines the Click application pages.

Each page path must be unique, as the Click application maps HTTP requests to the page paths.

The Click application will create a new Page instance for the given request using the configured page classname. All pages must subclass Page and provide a public no arguments constructor, so they can be instantiated.

Pages can also define header values which are discussed in the next topic.

When the Click application starts up it will check all the page definitions. If there is a critical configuration error the ClickSerlvet will log an <tt>ERROR</tt> message and throw a UnavailableException. If this occurs the click application will be permanently unavailable until the error is fixed and the web app is restarted.

Page Automapping
Page automapping will automatically configure application pages using a simple set of rules. This enables you to greatly streamline your configuration file as you only need to define pages which don't fit the automapping rules.

Automapping will attempt to associate each page template (*.htm) and JSP file in the web application (excluding those under the WEB-INF and click directories) to a Page class. Automapped pages are loaded after the manually defined pages are loaded, and manually defined pages taking preference. When automapping is enabled the Click application will log the page mappings when in debug or trace mode.

For example given a page path to class mapping:

This would be defined configured manually using the package prefix as:

Using automapping you only need to define the Home page which doesn't automatically map to index.html.

The page template name to classname convention is:

When automapping pages, if a class cannot be found Click will attempt to add the 'Page' suffix to the classname if not already present and map this. For example:

Automapping Excludes
With Page automapping there can be resources where you don't want automapping applied. For example when using a JavaScript library with lots of <tt>.htm</tt> files, you don't want automapping to try and find Page class for each of these files.

In these situations you can use the pages <tt>excludes</tt> element.

For example if our application uses the TinyMCE JavaScript library we could configure our pages automapping to exclude all <tt>.htm</tt> files under the <tt>/tiny_mce</tt> directory.

The excludes pattern can specify multiple directories or files using a comma separated notation. For example:

HTM files excluded from Page automapping are handled by an internal Page class with caching headers enabled.

Page Autobinding
By default all pages have autobinding enabled. With autobinding enabled the ClickServlet will automatically:


 * add any public controls to the page, after the page constructor has been invoked
 * bind any request parameters to public fields, after page constructor has been invoked
 * add any public fields to the page model, before rendering

You can turn this behaviour off by setting the autobinding attribute to false, for example:

Headers
The optional <tt>headers</tt> element defines a list of <tt>header</tt> elements which is applied to all pages.

The <tt>header</tt> element defines header name and value pairs which are applied to the HttpServletResponse.

Page headers are set after the Page has been constructed and before <tt>onInit</tt> is called. Pages can then modify their <tt>headers</tt> property using the <tt>setHeader</tt> method.

Browser Caching
Headers are typically used to switch off browser caching. By default Click will use the following no caching header values if you don't define a <tt>headers</tt> element in your application:

Alternatively you can define your headers individually in pages or for all application pages by setting headers values. For example to switch off caching in the login page, note the value for a Date type should be a long number value:

If you wanted to enable caching for a particular page you could set the following page cache control header. This will mark the page as cachable for a period of 1 hour after which it should be reloaded.

To apply header values globally define header values in the headers element. For example:

Format
The optional <tt>format</tt> element defines the Format object classname which is applied to all pages.

By default all Click pages are configured with a net.sf.click.util.Format object. The format object made available in the Velocity page templates using the name <tt>$ format </tt>.

To specify a custom format class configure a <tt>format</tt> element in the click-app descriptor. For example:

Mode
The optional <tt>mode</tt> element defines the application logging and caching mode.

By default Click applications run in <tt>development</tt> mode, which switches off page template caching, and the logging level is set to <tt>INFO</tt>.

To change the default application mode configure a mode element in the click-app descriptor. For example to specify <tt>production</tt> mode you would add the following mode element:

The application mode configuration can be overridden by setting the system property <tt>"click.mode"</tt>. This can be use in the scenario of debugging a problem on a production system, where you change the mode to <tt>trace</tt> by setting the following system property and restarting the application.


 * -Dclick.mode=trace

The Click Application modes and their settings for Page auto loading, Velocity caching, template loading on startup and logging levels are:

Page Auto Loading
When Page Auto Loading is enabled any new page templates and classes will be automatically loaded at runtime. These pages are loaded using the Page Automapping rules.

Page auto loading is a very handy feature for rapid development as you do not have to restart you application server to pick up new pages.

Velocity Caching
When Velocity Caching is enabled Velocity page templates and macros files are loaded once and cached. With caching enabled following Velocity runtime properties are set:

When Velocity Caching is disabled Velocity templates and macros file are reloaded when ever they change. With caching disabled the following Velocity runtime properties are set:

Template reloading is useful for application development as you can edit page templates on a running application server and see the changes immediately. Note however, this should not be used for production as Velocity can use a lot of memory when introspecting templates and template reloading is significantly slower.

Click and Velocity Logging
The Click and Velocity runtimes use ClickLogger for logging messages. The runtime loggers will send messages to the console <tt>System.out</tt>. For example the following logging output is for a HomePage request when the application mode is <tt>trace</tt>: [Click] [debug] GET http://localhost:8080/quickstart/home.htm [Click] [trace]   invoked: HomePage.&lt;&lt;init&gt;&gt; [Click] [trace]   invoked: HomePage.onSecurityCheck : true [Click] [trace]   invoked: HomePage.onInit [Click] [trace]   invoked: HomePage.onGet [Click] [trace]   invoked: HomePage.onRender [Click] [info ]   renderTemplate: /home.htm - 6 ms [Click] [trace]    invoked: HomePage.onDestroy [Click] [info ] handleRequest: /home.htm - 24 ms

Any unhandled <tt>Throwable</tt> errors are logged by the ClickServlet.

When an application is not in <tt>production</tt> mode the error page displays detailed debugging information. When the application mode is <tt>production</tt> no debug information is displayed to prevent sensitive information being revealed. This behaviour can be changed by modifying the deployed <tt>click/error.htm</tt> page template.

Controls
The optional <tt>controls</tt> element defines a list of <tt>control</tt> elements which will be deployed on application startup.

The <tt>control</tt> registers Control classes which will have their onDeploy method invoked when the click application starts.

For example to register a <tt>CustomField</tt> control class you would add the following elements to your <tt>click.xml</tt> file:

File Item Factory
The optional <tt>file-item-factory</tt> element defines the Commons FileUpload FileItemFactory object to be used for processing multipart file upload requests.

By default file upload requests are processed using the DiskFileItemFactory.

Factory properties can also be set by specifying property elements. These property values will be applied to the FileItemFactory using OGNL type coercion. For example:

Velocity Properties
The Velocity runtime engine is configured through a series of properties when the <tt>ClickServlet</tt> starts up. The default Velocity properties set are:

See the Velocity Configuration Keys and Values Developer Guide for details about these properties. Note in <tt>trace</tt> mode the ClickServlet will log the Velocity properties used when in starts up.

If you want to add some of your own Velocity properties, or replace Click's properties, add a <tt>velocity.properties</tt> file in the <tt>WEB-INF</tt> directory. Click will automatically pick up this file and load these properties.

As a example say we have our own Velocity macro library called <tt>mycorp.vm</tt> we can override the default <tt>velocimacro.library</tt> property by adding a <tt>WEB-INF/velocity.properties</tt> file to our web application. In this file we would then define the property as:

Note do not place Velocity macros under the WEB-INF directory as the Velocity ResourceManager will not be able to load them.

The simplest way to set your own macro file is to add a file named <tt>macro.vm</tt> under your web application's root directory. At startup Click will first check to see if this file exists, and if it does it will use it instead of <tt>click/VM_global_library.vm</tt>.

Auto Deployed Files
The Click framework uses the Velocity Tools <tt>WebappLoader</tt> for loading templates. This avoids issues associate with using the Velocity <tt>FileResourceLoader</tt> on JEE application servers.

To make preconfigured resources (templates, stylesheets, etc.) available to web applications Click automatically deploys configured classpath resources to the <tt>/click</tt> directory at startup (if not already present).

You can modify these support files and Click will not overwrite them. These files include:


 * click/error.htm - the Page [pages.html#page-error-handling Error Handling] template
 * click/control.css - the Controls cascading stylesheet
 * click/control.js - the Controls JavaScript library
 * click/not-found.htm - the [pages.html#page-not-found Page Not Found] template
 * click/VM_Global_library.vm - an empty Velocity macro library

If Click cannot deploy these files because of restricted file system permissions warning messages will be logged.

If your application server has restricted permissions, you will need to package up these auto deployed files in your web applications WAR file. To do this you should run you application on a development machine without these restricted permissions and then package up the deployed files.