Jspx Under the Hood

Jspx main parts

1. Engine
2. Web UI
3. Static Resources

Engine

Jspx Engine is responsible for all core functionalities starting from receiving the HTTP request until rendering the final HTML to the browser. Jspx Engine is composed of several components

1. Request/Resource Servlets
2. EL Evaluator
3. Page Parser
4. JMX interface
5. DB Connector
6. Utilities

Request/Resource Servelt

RquestHandler and ResourceHandler are the main two servlets that need to be configured in the Web.xml file in order to allow jspx to recieve HTTP requests and renders your jspx pages.

Sometimes you may need to provide a customized handling for incomming request just before jspx part (like changing the default character set of your application, handling the errors with special page and so on.). You can extend the nature of the Request Handler by creating your own class that extends the RequestHandler and then provide your own customization The live demo source code shows an example on this you can download the demo from the download section . In most of cases you will not need to do so. Simply configure both servelts in the web.xml file to serve your jspx pages.

RequestHandler is the very first component to be invoked upon HTTP request on an jspx page. It is responsible for:

1. Set the character encoding of the request, the content type of the repsonse, the extra hearder to be added
2. Invoke the parser to get a parsed model (Page instance) of the HTML page requested.
3. Clones the Parsed Page Model and creates new instance that will serve this HTTP request.
4. Handle any exceptions and errors and propagate errors as needed.

The ResourceHanlder is responsible for rendering all embedded resources inside the jspx library to the end user. Jspx includes several out of the box resources that represents some of the open source projects that jspx uses inside. These resources are (Javascript, CSS, Images). There is no need at all to customize this class, however it is not final :).

EL Evaluator

Jspx does not allow java code inside the HTML. Still the need for declarative code inside the HTML is very important, for that jspx offers the ability of using EL syntax to inject values from your controller to the HTML. Jspx is fully supporting standard EL Expression Language, in Jspx 2.1 based on JEXL library the EL expressions are supported.
Some Examples on the EL syntax used:

1. 
   ${this.customerName} . The keyword this refers to the current instant of the page controller. customerName is the name of the Java property in the controller class. The property should have a getter method as

   
   public String getCustomerName()
   {
   	return "Test Customer";
   }
   			
   

2. ${request.parameters.id}. The keyword request refers to the HTTP Servlet Request. parameters refers to the Request parameters. id refers to the parameter name. HTTP Servlet Request attributes can be also accessed as ${request.attributes.id}.
3. ${session.id}.The keyword session is used to access parameters in the HTTP Servlet Session.
4. ${var.age}. In Data Item Controls like DataTable and List Table, custom rendering of Data Column can be done by using ItemTemplate. in order to access the current Database record a variable should be declared in the DataTable with name var for example. Then inside the ItemTemplate the values inside the var variable can be accessed as shown in the EL.
5. ${size(this.username). JEXL provides static methods to be invoked .

Page Parser

Jspx pages are written in HTML syntax, in fact XHTML syntax. It should be fully accurate XHTML syntax as these pages are parsed using XML parser. The page parser is reading the HTML pages and convert them into an instance of Page Class This page class is merges along with the controller the developer declares associated with the HTML Page.
The HTML controls declared in the HTML page are composed as a tree of controls that can be navigated forward and backward , you can query for a certain control and you can inject and delete controls at runtime.

The PageModelComposer class does the following:

1. Finds the localized version of the page to be parsed
2. Finds if there is a master page to be loaded and merged with the final output.
3. Creates new instant of the Page Controller class based on the developer definition, if no controller, then default controller is used.
4. Caches the parsed pages (Master, Content) in memory to be used in latter requests.

JMX interfacer

Jspx provides admin interface for controlling its settings and invoke some actions at runtime. The functions exposed are:

	public void clearAllChachedPages();

	public void removeChachedPage(String pageName);

	public List<String> getCachedPages();

	public List<String> getCachedMasterPages();

	public String getCharSet();

	public void setCharSet(String charset);

	public String getJspxVersion();

	public boolean isJEXL();

	public void setUseJEXL(boolean themeTwitter);

	public boolean isThemeTwitter();

	public void setThemeTwitter(boolean themeTwitter);

	public boolean isShowSQL();

	public void setShowSQL(boolean showSql);			

DB Connector

1. Execute DataTable Search SQL and parses the results as model or map.
2. Get the lookup values
3. Paginate the sql result set for better performance.

Utilities

Jspx features are all served by Set of utility components. These components are including the following:

1. String manipulation.
   String utility class that is used across the framework
2. Jspx Bean Handling.
   Utility for creating, edit, retrieving, evaluating bean properties and scoping
3. Captcha Images creation.
   Image creation and skewing for captcha image.
4. Reflection utilities.
   Classes for dynamically invoke server side events and methods to server user client side actions. They are also used to calculate the EL values from Beans and pages.

Web UI

This component is responsible for modeling all HTML and Jspx Controls to provide OOP API to interact with these controls from your java controller.

The Web UI layer is split into two parts:

1. Pages
2. Controls

Pages

The pages are the main controller that the developer use to interact with his web forms. For each HTML page there must be a Controller. Developer may choose not to define a controller for a page leaving jspx to create a default controller for it. Pages are simple POJO classes and they are not Servlets, however developer still have access on HTTP Servlet Request, Response and Session. Developer can define his own Page by creating a new class that extends one of the three types of a Page

1. Page
   Page controller is used to control HTML pages that does not have a Master template
2. MasterPage
   MasterPage is a controller that is used to control HTML page that is used as a template for many Content pages. The codes and events inside a controller that inherits a MasterPage will be invoked each time a content page is called
3. ContentPage
   ContentPage is a controller that must be used with any HTML page that uses a master template.Events and code inside it will be invoked only if the page is called.

Jspx Phase Events

1. pageInit
   This is the very first event to be invoked. Pretty much earlier that anything. This event is invoked right after your controller is instantiated and cloned from a parsed model. Most likely you may use this phase only if You need to set some flag or variable shared on you controller
2. pagePreLoad
   This phase is invoked after the Page model is created and all declared controls are defined and JsxpBean values are initialized. Until this moment the controls in the page still have the default values defined in HTML page. The post back data are note applied. You may need to override this phase to read the default values of the controls. Please note that any change applied to controls in this phase will be override by the framework after applying the post back data
3. pageDispatched
   This event is fired when another page had called dispatch(String targetPageName) method. The dispatch method asks the engine to transfer the execution to another page defined by the targetPageName argument.This event will fire in the target page that the request is dispatched to. Developer can still check on the status of dispatching by checking the flag isDispatched
4. pageLoaded
   This is the most common event developers are using to override and insert some logic inside it. At this level, the page is loaded with all data thay may be sent from end user (in case of Post back call) and the developer can execute the logic required for model initialization. It should be note that this event phase method is invoked whether this is GET or POST request. The developer should differentiate between them using the flag isPostBack where it is a boolean in the page if true it means that this is POST request. Until this moment the User clicks and events are not fired.
5. User Event Handlers (No method to override)
   There is no phase method to overrider, however for each event developer defines an event handler in the HTML.
   • helloJspxWithContoller.jspx
   • HelloJspxContoller.java

   
   			<page contoller="org.bay.jspx.demo.live.HelloJspxController" >
   				<html>
   					<body>
   						<input type="button" onServerClick="doClick"></label>
   					</body>
   				</html>
   			</page>
   			
   

   
   package org.bay.jspx.demo.live;
   
   import eg.java.net.web.jspx.engine.annotation.JspxWebControl;
   import eg.java.net.web.jspx.ui.controls.html.elements.Label;
   import eg.java.net.web.jspx.ui.controls.WebControl;
   import eg.java.net.web.jspx.ui.pages.Page;
   
   public class HelloJspxController extends Page
   {
   	public void doClick(WebControl invoker, String args)
   	{
   		// Developer logic to be executed upon click
   	}
   }
   			
   

   This example can be fully tested on Hello Jspx (with Java Controller) on live demo.