Vroom Framework

Vroom Framework is Java based web application development framework. It is written using J2EE 1.4 Specifications to make compatible with all J2EE 1.4 compliant Web/Application Servers.

History

Vroom Framework is architectured and developed by Farrukh Ijaz s/o Mohammad Riaz in March 2008. It was originally designed with a concept of altering the source code of web pages at run-time based on a configuration file (vroom-config.xml) to create binding between the HTML DOM events and server side Java methods.

Vroom-2, which is the latest version of Vroom Framework, has been revamped to eliminate all the limitations of the first version.

Architecture

The framework consists of following elements:

• Core API: The API of the framework is packaged as vroom.jar which contains filter, controller, and other helper classes. The filter and controller is configured by defining entries in web.xml file of the web application.
• JavaScripts: There is one JavaScript file named vroom.js which is part of the framework but it is not packaged as vroom.jar file. It is placed in \WEB-INF\ folder of the web application. The reason for keeping it outside the package is to provide the developer an opportunity to improve the existing functions as well as to include additional functions if required.
• Configuration File: Once the framework is set up, a configuration file is maintained for the web application to instruct the framework how to perform certain actions. The file is typically named as vroom-config.xml. It is placed in \WEB-INF\ folder and specified in the config-file attribute of the filter definition in web.xml.

Installation and Configuration

The framework's latest distribution can be obtained from Project's website. To install the framework, following the instructions below:

1. Download the latest Vroom-x.x.x.zip file and extract it to the location which is normally used for java libraries e.g. C:\CLASSPATH\Vroom-x.x.x\.
2. Create a web application and copy the contents available in Vroom-x.x.x\WEB-INF\ folder of the library to your web application's \WEB-INF\ folder.
3. Define the following entries in web.xml of the application:

   
       VroomFilter
    net.openkoncept.vroom.VroomFilter
    
        config-file
        /WEB-INF/vroom-config.xml
    


    VroomFilter
    *.jsp


    VroomController
    net.openkoncept.vroom.VroomController
    
        upload-file-size-threshold
        1024000
    
    
        upload-file-temp-folder
        /WEB-INF/temp
    


    VroomController
    /vroom
   

   Note: You can change config-file, upload-file-size-threshold, upload-file-temp-folder attributes. However, url-pattern for VroomController have to be /vroom. Also remember, the filter-mapping is very important in terms of intercepting the requests. If you want to intercept Html pages (*.html), Struts Actions (*.do) or JSF pages (*.faces), you need to define separate filter-mapping for each of them, otherwise the framework won't be able to manage them.

That's all related to Installation and Configuration of the framework and web application is ready to utilize Vroom Framework.

How it works?

Vroom Framework can manage anything related to HTML DOM, including Document, Window and Navigator objects. The framework can be used independently or it can be integrated with other Model-2, MVC frameworks. In some aspects, Vroom Framework provides better control of your website e.g. You may want to include Google Analytics JavaScript to your webpages. To do that you probably use one of the following approaches:

• Open every webpage and paste the JavaScript code Or
• Use a separate html/jsp file for JavaScript code and modify every webpage to include the include statement Or
• Use tiles approach if you're using Struts Framework

The first two approaches are quite time consuming; the second approach does not work with HTML pages and in case of third approach, not all applications are built on Struts Framework. Vroom Framework eliminates all this hassle and provides you an easy to use approach to inject such type of scripts by defining webpage element in vroom-config.xml file. Below is the sample webpage definition to accomplish the goal:

<webpage uri="/|(/|[a-z]|[A-Z]|[0-9]|-|_)*.(jsp|html)">
    <script type="text/javascript" url="#{contextPath}/scripts/google-analytics-script1.js"/>
    <script type="text/javascript" url="#{contextPath}/scripts/google-analytics-script2.js"/>

Here is the detail of the above definition:

• With webpage element, we instruct the framework to intercept all the webpages satisfying the uri /|(/|[a-z]|[A-Z]|[0-9]|-|_)*.(jsp|html) which is a Java specific regular expression. You can always define your own regular expression to include/exclude specific webpage.
• The script child tag instructs the framework to inject the script to all the webpages.
• The #{} is the format to access server variables. #{contextPath} is replaced with web application's context path.

The benefits of this approach are:

1. You don't need to modify your webpages to include the scripts
2. The approach works for any type of HTML file whether it's *.jsp or *.html
3. The rule will automatically include newly added pages or exclude removed pages

Coming back to the original point, how the framework works?

It's driven by vroom-config.xml file. When a web application is deployed to the application server, the server loads the filter and controller defined in the web.xml file. As part of VroomFilter loading, the vroom-config.xml file is loaded and becomes available to the framework as a configuration object. Every time when the filter intercepts a request, it consults the configuration object to provide rules (defined as webpage elements) for the request. If no rule is found, the filter ignores the request and processing continues as normal, otherwise, based on the rules, the filter injects the required scripts, stylesheets and meta-tags to the final response of the request and delivers the modified response to the client. User interacts with the webpage as usual and if in execution of any HTML DOM event, which was bound to a server side Java method as per definition in the configuration file, an AJAX request is initiated. The response of the AJAX request is always JSON string. In the vroom-config.xml file, it can be define what to do in response of the event. E.g. to update HTML content or to invoke any JavaScript code. This is explained in detail in the following section.

Structure of the Configuration File (vroom-config.xml)

The configuration file contain following elements and attributes: