Jspx Under the Hood
JSPX is designed to serve the need of rich applications. The design of the framework is considering many targets
like modularity and extendability. The framework is composed of main three parts (Engine, Web UI, Static Resources).
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:
-
Set the character encoding of the request, the content type of the repsonse, the extra hearder to be added
-
Invoke the parser to get a parsed model (Page instance) of the HTML page requested.
-
Clones the Parsed Page Model and creates new instance that will serve this HTTP request.
-
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:
${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";
- }
-
public String getCustomerName()
{
return "Test Customer";
}
-
${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}.
-
${session.id}.The keyword session is used to access parameters in the HTTP Servlet Session.
-
${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.
-
${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:
-
Finds the localized version of the page to be parsed
-
Finds if there is a master page to be loaded and merged with the final output.
-
Creates new instant of the Page Controller class based on the developer definition, if no controller, then
default controller is used.
-
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);
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
Jspx reach controls like (DataTable, DataLookup, AutoComplet) need to interact with Database. For that need there is a set of classes
dedicated to connect to DB using managed JDBC connection offered by the Application server Connection pool. The DAO class is used to
do all the DB related tasks like,
-
Execute DataTable Search SQL and parses the results as model or map.
-
Get the lookup values
-
Paginate the sql result set for better performance.
This layer also is responsible for extracting results as Excel sheet and supporting the ListTable in the same functions offered for
DataTable.
Utilities
Jspx features are all served by Set of utility components. These components are including the following:
-
String manipulation.
String utility class that is used across the framework
-
Jspx Bean Handling.
Utility for creating, edit, retrieving, evaluating bean properties and scoping
-
Captcha Images creation.
Image creation and skewing for captcha image.
-
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:
- Pages
- 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
-
Page
Page controller is used to control HTML pages that does not have a Master template
-
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
-
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
Page controllers exposes set of life cycle events, the developer can override these life cycle events to execute some logic
during specific phase of the page. There is no need to create a different class for phase listener as the Page itself exposes
the phases as call back methods. The phases are:
-
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
-
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
-
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
-
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.
-
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.
- <page contoller="org.bay.jspx.demo.live.HelloJspxController" >
- <html>
- <body>
- <input type="button" onServerClick="doClick"></label>
- </body>
- </html>
- </page>
<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)
- {
-
- }
- }
-
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.
For many HTML Controls there are corresponding Classes to be used to interact with HTML controls through java code.
Please note that not all tags have a server side WebControl instance like (DIV,SPAN, BR, ...) even there are new tags to be
invented and not yet modeled, You don't have to worry, you still can interact with these unmapped tags using GenericWebControl
instance.