Apache Click in a Click - Part 2 [Servlet Loading Life cycle]

This part of the blog will be detailing about ClickServlet [the heart of the click framework]. This is responsible for processing every requests from the client, and for providing a response back to the client. 

The ClickServlet is configured like any servlet in the web.xml as given below.

  <servlet>
     <servlet-name>ClickServlet</servlet-name>
     <servlet-class>org.apache.click.ClickServlet</servlet-class>
     <load-on-startup>0</load-on-startup>
  </servlet>
  <servlet-mapping>
     <servlet-name>ClickServlet</servlet-name>
     <url-pattern>*.htm</url-pattern>
  </servlet-mapping>  

The <load-on-startup> property is set to 0. This is for loading the ClickServlet when the application is started. The servlet is initialized and this in turn initializes the click application configuration service.

The following diagram show the life cycle of the servlet initialization.

When the servlet initializes, it will load the click's configuration file (click.xml). It will load the file from either of the following locations

• WEB-INF/click.xml: This is the default location for click.xml
• WEB-INF/classes/click.xml: If the click.xml is not found in the above location, it will check for it under the project classpath.

If the click's configuration file is not found, the click app will not get initialized at all.

Once the configuration file is loaded, it will create the configuration service. By default, the configuration service is XMLConfigService. You can override this configuration by extending XMLConfigService and overriding the relevant methods. Once this is done, the configuration service needs to be configured in the web.xml as shown below.

  <context-param>
     <param-name>config-service-class</servlet-name>
     <param-value>
         com.blogspot.javaclickonline.click.service.MyConfigService
     </param-value>
  </context-param>

A complete click configuration file [click.xml] is given here for reference. In the below steps of the life cycle, we will refer to each section of the application configuration file.

The first step is to load the log service. Click supports different kinds of log services to work with:

• ConsoleLogService: This is the default log service used if not specified in the click configuration file.
• Log4JLogService: This can be configured in the click.xml so as to override the default log service. This is done as shown below.

  <!-- Set the internal Logger to Log4J instead of default ConsoleLogService --> 
  <log-service classname="org.apache.click.extras.service.Log4JLogService"/> 

The next step is to load the mode. The mode defines the application logging and the caching mode. By default, the mode will be set to development mode. During the development mode, the page template caching will be switched off and the log level is set to INFO. The mode can be set to a different value in the click application configuration file as shown below.

<click-app>
  ..
<!-- Mode values include: [production], [profile], [development], 
  [debug], [trace] --> 
  <mode value="production">
</click-app>

The following are the different modes and their settings for page auto loading, template caching and logging levels.

Application mode	Page auto loading	Template caching	Click log level	Velocity log level
production	No	Yes	WARN	ERROR
profile	No	Yes	INFO	ERROR
development	Yes	No	INFO	ERROR
debug	Yes	No	DEBUG	ERROR
trace	Yes	No	TRACE	WARN

[PS: When page auto loading is enabled, the new page templates and classes will be automatically loaded at runtime. This feature is very useful for rapid application development and there is no need to deploy the application every now and then.] 

The next step is to deploy the static resources from the click's jar files into the web application's root folder. In this step, the controls in the click-controls.xml, extra-controls.xml and also the controls specified in the click's application configuration file (click.xml) are deployed.

The next step is to load the format object . The default implementation is org.apache.click.util.Format. This is used for formatting the model objects when displayed on velocity templates and jsp pages. We can override the default implementation as shown below.

<!-- Setup alternative Format. Default Format is org.apache.click.util.Format --> 
<format classname="com.blogspot.javaclickonline.click.util.Format"/>

For Velocity templates a Format object is added to the Velocity Context using the name format, while for JSP pages an instance is added as a request attribute using the same key. 
So in the page template, we can use the format object as shown below. 

$format.date($deliveryDate, "dd MMM yyyy")  

The next step is to load the headers. A header element defines the header name and value pairs which are applied to the HttpServletResponse. It is in the header, the browser caching is enabled for specific or globally. By default, the browser caching is disabled as a global setting but we can do it on a page by page basis too. The examples below show the different ways by which we can disable browser caching.

<click-app>
  <pages>
     ..
  </pages>
  <!-- By default, this is how click works if no header section is specified --> 
<headers>
    <header name="Pragma" value="no-cache"/>
    <header name="Cache-Control"
       value="no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/>
    <header name="Expires" value="1" type="Date"/>
  </headers> 
</click-app>  

Alternative way is define the browser caching on a page by page basis as given below.

<click-app> 
  <pages package="com.blogspot.javaclickonline.page">
  <page path="login.htm" classname="Login">
      <header name="Pragma" value="no-cache"/>
      <header name="Expires" value="1" type="Date"/>
    </page>
  </pages> 
</click-app>  

Also there is a way to enable caching for a particular page as shown below. This means the page will be cachable for a period of 1 hour after which it should be reloaded.

<click-app> 
  <pages package="com.blogspot.javaclickonline.page">
  <page path="home.htm" classname="Home">
      <header name="Cache-Control" value="max-age=3600, public, must-revalidate"/>
    </page>
  </pages> 
</click-app>  

The next step is to load the pages and also the default pages like error page and not-found page.

The next step is to load the character set and the locale. The charset and locale can be specified in the click.xml as shown below.

<click-app charset="UTF-8" locale="en">  
  ...
</click-app>  

The next step is to load the file upload service. The default implementation of the file upload service is org.apache.click.service.CommonsFileUploadService. We can set the properties: sizeMax and fileSizeMax as shown below.

<!-- Set the org.apache.click.service.CommonsFileUploadService properties: 
sizeMax and fileSizeMax. -->  
<file-upload-service> 
  <!-- Set the total request maximum size  
  to 10mb (10 x 1024 x 1024 = 10485760). The default request  
  upload size is unlimited. --> 
  <property name="sizeMax" value="10485760"/> 
  <!-- Set the maximum individual file size to 2mb (2 x 1024 x 1024 = 2097152).
  The default file size is unlimited. 
  <property name="fileSizeMax" value="2097152"/> 
</file-upload-service>

If we want to override the default file upload service, we can define it as shown below:

  <file-upload-service 
  classname="com.blogspot.javaclickonline.util.CustomFileUploadService"> 
      <property name="sizeMax" value="10485760"/> 
      <property name="fileSizeMax" value="2097152"/> 
  </file-upload-service>

The next step is to load the templating service. By default, the templating service is set to Velocity template but we can override this to FreeMarker templating as given below.

<!-- Set the template engine to use Freemarker instead of Velocity -->
<template-service 
  classname="org.apache.click.extras.service.FreemarkerTemplateService"/>

The next step is to load the resource service. The default resource service implementation is org.apache.click.service.ClickResourceService. This can be overridden as given below

<resource-service 
  classname="com.blogspot.javaclickonline.click.service.CustomResourceService"/>

The next step is load the page interceptors. Page interceptors can be used to provide security to pages. We can configure the page interceptors in the application configuration file as shown below.

<page-interceptor classname=
   "com.blogspot.javaclickonline.interceptor.security.PageSecurityInterceptor" 
   scope="application"> 
   <property name="notAuthenticatedPath" value="/not-authenticated.htm"/> 
   <property name="notAuthorizedPath" value="/not-authorized.htm"/>
</page-interceptor>

This completes the life cycle of the servlet initialization. Once all this is done, the servlet is ready to process requests from the client. In the next part of the blog, I will be detailing about the servlet request life cycle.