Apache Click in a Click - Part 3 [Servlet Request Life cycle]

This part of the blog will be detailing about the servlet request life cycle of apache click framework. In the previous blog post, [Apache Click in a Click - Part 2 [Servlet Loading Life cycle]], we detailed about the ClickServlet and its initialization life cycle. In the previous blog, we also discussed a little about the different configurations that can be done in click.xml [the application configuration file].

The following pictures shows the life cycle of a servlet request.

When a client (browser) makes a request, it is handled by the ClickServlet's doPost(...) or doGet(...) based on whether the request is a GET request or a POST request. This method in turn calls the handleRequest(...) method where the request is handled by Click.

The first step is to create a page instance based on request. For instantiating the page class, it should have a no argument constructor. So we should make sure that when we subclass the page class, we should have a no argument constructor defined in case we are writing another constructor with arguments.  Also during this process, the page attributes like context, header, format and locale will be set to the page instance. The next step is to bind the request parameter values to the matching page fields.

The page class provides the following empty handler methods which can be overridden by subclasses to implement specific functionality.

• onSecurityCheck(): This method can be overridden by sub classes on a need basis. This can be used to make sure that the user is authorized to access a page and if necessary to abort further processing.
  
  
• onInit(): This is the next method that is invoked during the life cycle. This is the method we can create the page controls [forms, fields, tables etc] that is required for the page. 
  • As the next step, each of the control's onit() method will be called to perform any initialization process. 
  • The next step is processing of the page's controls. Here the ClickServlet gets all the page controls and iterates through and calls the onProcess() method of each control. If the onProcess() method returns false for any of the controls, the processing of the subsequent controls and the Page's onGet() or onPost() is aborted. 
   
• onGet(): Once the page's onInit() is executed properly, the next step in the process to call the Page's onGet() method. This is based on whether the request is a GET request.
  
  
• onPost(): As stated above for onGet(), the Page's onPost() is called if the request is a POST request.
  
  
• onRender(): The next step and the most important step is rendering the page template to generate the HTML for display. The ClickServlet gets the model (Map) from the Page then adds the following objects to the model:
  • All public Page fields will be added to the model with the key as the field property's name.

  • context - The Servlet context path or generally termed as context root. eg: /clickapp 

  • format - The Format object used for formatting the display of objects. This object can be used for formatting date, time, currency etc.

  • headElements - The HEAD elements, excluding JavaScript, to include in the page header.An example of this would be the following - 
  • CssImport (for importing external css using <link> element) 
  • CssStyle (for including inline css using <style> element)
  • jsElements - The JavaScript imports and script blocks to include in the pages footer.An example of this would be the following - 
  • JsImport (for importing external js files using the <script> element) 
  • JsScript (for including the inline js using the <script> element)
  • messages - This is the instance of the MessagesMap which is made available to every Page and controls. 
  • We can access the message from a page using the Page's getMessage() methd.
  • We can also get the messages on the page template like $messages.title
  • path - The path of the page template to render
  • request - The pages HttpServletRequest object
  • response - The pages HttpServletResponse object
  • session - This is the instance of SessionMap which is available in each Velocity page using the name "session"
  • For example suppose we have a User object in the session with the attribute name "user" when a user is logged on. We can display the users name in the page when the are logged onto the system.

   #if ($session.user)
     $session.user.fullname you are logged on.
   #else
     You are not logged on.
   #end 
  
  The next step is merging the template with the page model and writing out results to the HttpServletResponse. When the model is being merged with the template, any Controls in the model may be rendered using their toString() method.
  
• onDestroy(): Once all the above steps happen, the onDestroy() method is called on each of the controls and then finally the page's onDestroy() method is called. This method can be used to clean up the resources associated with a control or a page before it is garbage collected. Also this method is guaranteed to run even if an error occurs in any of the above steps.

This completes the servlet request life cycle of an apache click application. In the next part of the blog, we will be concentrating on implementing a simple application with apache click.


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.

Apache Click in a Click - Part 1 [General Overview]

Apache Click is another JEE web application framework similar to Apache Wicket and Struts. The initial version of Apache Click started in 2003 and there were constant improvements happening for this framework through the years. Now the framework has become very mature and in my view, it is ready to be used in Production applications.

Apache Click is a modern JEE web application framework providing a rich client style programming model. Apache Click is an open source project and this uses an event based programming model for processing Servlet requests and Velocity for rendering the response.

The advantages of Apache Click are: 

1. Easy to learn 

• Click is designed to be very simple and easy to get started on the first day itself [provided the user has the basic knowledge of how web applications work]. 
• Apache Click is one of the open source frameworks that has a very good tutorial on the web [http://click.apache.org/docs/user-guide/htmlsingle/click-book.html]. 
• Eclipse plug-ins available for supporting Click application development. [clickide-2.2.0.0.zip]. This helps in rapid application development with project and page creation wizard etc. 
• A good book to read [Getting Started With Apache Click - Freddy Daoud]

2. Component and Page Oriented design
   

• Click provides a page oriented design featuring control components and an event based programming model
• There are over 40 controls that comes along with the click distribution which we can readily use in our applications. The controls are divided into 2: 
• Core Controls:  For example, ActionLink, ActionButton, Checkbox etc.
• Extra Controls:  For example, CreditCardField, TelephoneField, EmailField etc.
• Very easy to develop and deploy our own custom controls too. For example, a Scrollable data table etc.

3. Stateless and stateful page support

• Click provides support for implementing stateless pages. Stateless pages can be marked as stateless if it doesn't have any callbacks to itself. It doesn't care about saving the state of the page for any reason. 
• Examples of stateless pages are bookmarks, login page etc.
• Click provides support for implementing stateful pages. Stateful pages can be marked as stateful since it saves the state of the page between the user requests.   
• Examples of stateful pages are wizard kind of pages where in the user has to complete the different steps in different pages to complete a flow. The user will also have the option to go back and forth between pages and also save in between without completing the full flow.

4. Automatic form rendering and client/server side validation

• Click provides Forms and controls which will help us in automatic form rendering and validation and it also helps in making the development faster and error free. 

5. Supports Velocity, JSP or FreeMarker page rendering

• By default, click uses Velocity for rendering the pages. It uses Velocity because of the following reasons - 
• Velocity is a proven templating mechanism
• Velocity has very simple instruction set for usage and it is very easy to learn.
• Click also provides support for using other templating mechanism like FreeMarker and the very well known and widely used JSP.   

As a next step, the next part of the blog will be detailing about the servlet's [ClickServlet] loading life cycle.

Great Java tech page

This blog is intended to be an encyclopedia for all the new frameworks/features that have been proven or in beta releases stage. The blog will try to explain the life cycle of the frameworks/features with simple examples.

PS: The blog is still in its initial phases. Also feel free to place requests on what frameworks you need to have posts on.