Expression in custom tags of Ze Framework

Before looking at custom tags, we need to know about how expression can be written. Because, expression is needed to use custom tags.

Basically, custom tags is used to get/set values from/to model. There are other useful custom tags also, but this is what basically custom tags are made for.
For this purpose, most of custom tags in the framework have "valuefrom" and "valueto" attributes. As name suggests, "valuefrom" is used to get value from a model and "valueto" used to set value to a model.

Now suppose, we can have some custom tag like

<zfw:out valuefrom="m{modelName.propertyName1.propertyName2}"/>

So, here "m" stands for "model", expression start with "{" and ends with "}".
Here, "modelName" is name of the model which we have defined in configuration file in
"Models -> Model -> name".
"propertyName1" is the property name of specified model. The model must have getter and setter method for this property. In our case "proeprtyName1" is a user defined class' object and it has a property named "propertyName2". The user defined object also must have getter and setter method for this property.

We can use the above expression as it is if "propertyName2" is any of the data types like "int", "short", "long", "float", "double", "char", "boolean", "java.lang.Integer", "java.lang.Short", "java.lang.Long", "java.lang.Float", "java.lang.Double", "java.lang.Char", "java.lang.Boolean", "java.lang.String", "java.util.Date".

When we need to get/set "java.util.Date" type property the framework converts date object into string object to get, and converts string object into date object to set, and for that it uses local timezone and default format. But, if we need specific timezone and/or specific format than we can specify it in above expression. Now, above expression looks like below to display date in specific timezone and format.

<zfw:out valuefrom="m{modelName.propertyName1.propertyName2}t{IST}f{dd/MM/yyyy HH:mm:ss}"/>

Here, "t" stands for "timezone" and "f" stands for "format". We can pass any timezone string which "java.util.TimeZone.getTimeZone" mothod can support. And we can pass any date format string which "java.text.SimpleDateFormat" class can support.

If the we need to get/set property of type "int", "short", "long", "float", "double", "java.lang.Integer", "java.lang.Short", "java.lang.Long", "java.lang.Float" and "java.lang.Double" in some specific format than we can specify it in expression like below.

<zfw:out valuefrom="m{modelName.propertyName1.propertyName2}f{Y:(5-2).(1-4)}"/>

Here, we can specify either "Y" or "N" as first letter in the format expression. It indicates that either the number has "," (comma) as separator or not. Within first "(" and ")" we can specify max integer digit (here 5) and min integer digit (here 2) the number can have. We need to put "." after it. Then we can specify within last "(" and ")" min fractional digit (here 1) and max fractional (here 4) digit the number can have.

The other custom tags which can set data to model with attribute named "valueto" has same expression syntax as defined above.

To get value of any variable defined in jsp page by "org.mvpanchal.zefw.tag.DefineTag" or any other jsp custom tag, we need to use syntax like below.

<zfw:out value="$variable1"/>

Please, notice that we have used "value" here instead of "valuefrom". If we need to get variable's value we always need to user "value" not "valuefrom". "valuefrom" should be used only to work with models.
We can see that we haven't used here curly braces. Because, it is conflicting with basic jsp syntax to get variable's value. Although, we can also use basic syntax also to get variable's value.

Suppose, that propertyName1 is an array of a user defined object, then what would be the syntax to get propertyName2. It looks like below.

<zfw:out valuefrom="m{modelName.propertyName1[0].propertyName2}"/>

Here we can use a variable instead of contanst "0". It looks like

<zfw:out valuefrom="m{modelName.propertyName1[$variable1].propertyName2}"/>

If propertyName2 is an array then we can write syntax as below.

<zfw:out valuefrom="m{modelName.propertyName1[$variable1].propertyName2[$variable2]}"/>

Configuration file for Ze Framework

The framework must have a xml file to get configuration information. The xml file is based on an xsd which is supplied with the framework. We will get information about each element of the configuration file in this post.

Below is the structure of the xml file.

ZeFWConfig (1..1)
    |
    |---> ApplicationLifeCycle (0..1)
    |     |
    |     |---> Initializer (0..1) [type]
    |     |
    |     |---> ProcessingTube (0..1) [type]
    |     |
    |     |---> Destroyer (0..1) [type]
    |
    |---> Exceptions (0..1)
    |     |
    |     |---> Exception (0..N) [type, handler(opt), page]
    |
    |---> Models (0..1)
    |     |
    |     |---> Model (0..N) [name, type, scope(opt)]
    |
    |---> Views (0..1)
    |     |
    |     |---> View (0..N) [name, page, loader(opt)]
    |           |
    |           |---> ModelNames (0..1)
    |           |     |
    |           |     |---> ModelName (0..N) [name]
    |           |
    |           |---> Exceptions (0..1)
    |           |     |
    |           |     |---> Exception (0..N) [type, handler(opt), page]
    |           |
    |           |---> ViewValidators (0..1)
    |                 |
    |                 |---> ViewValidator (0..N) [type]
    |
    |---> Actions (0..1)
    |     |
    |     |---> Action (0..N) [name, handler]
    |           |
    |           |---> ModelNames (0..1)
    |           |     |
    |           |     |---> ModelName (0..N) [name]
    |           |
    |           |---> Exceptions (0..1)
    |           |     |
    |           |     |---> Exception (0..N) [type, handler(opt), page]
    |           |
    |           |---> ActionValidators (0..1)
    |                 |
    |                 |---> ActionValidator (0..N) [type]
    |
    |---> ActionViewRedirects (0..1)
    |     |
    |     |---> ActionViewRedirect (0..N) [actionname, viewname, sendredirect]
    |
    |---> ApplicationProperties (0..1) [filepath]

1. "ZeFWConfig" is the root element of the file.

2. "ApplicationLifeCycle" helps to configure handling life cycle events of an application.

3. "Initializer" has an attribute called "type". We can specify fully qualified class name to the "type". The class must implement "org.mvpanchal.zefw.lifecycle.ApplicationInitializer" interface. The class would be called when servlet context is initialized.

4. "ProcessingTube" has an attribute called "type". We can specify fully qualified class name to the "type". The class must extend "org.mvpanchal.zefw.processingtube.AbstractProcessingTube" class. The class would be called on each request of the application. If the request is of type "view" then "beforeProcessView" and "afterProcessView" methods would be called, and if the request is of type "action" then "beforeProcessAction" and "afterProcessAction" method would be called.

5. "Destroyer" has an attribute called "type". We can specify fully qualified class name to the "type". The class must implement "org.mvpanchal.zefw.lifecycle.ApplicationDestroyer" interface. The class would be called when servlet context is destroyed.

6. "Exceptions" helps to configure global exception handing on exception occurrence.

7. "Exception" has attributes called "type", "handler", "page". "type" is fully qualified class name of exception which needs to be handled. "handler" is fully qualified class name of a class which implements "org.mvpanchal.zefw.exceptionhandler.ExceptionHandler" interface. The handler would be called when the specified exception occurs. The "handler" is not a required attribute. "page" is the path of jsp which would be dispatched after handling the exception.

8. "Models" defines models classes which plays roll as carrier classes for data.

9. "Model" has attribute called "name", "type" and "scope". "name" is the model name. "type" is the fully qualified class name of the class which implements "org.mvpanchal.zefw.model.Model". "scope" is the scope value in which the model instance is available. "scope" can have the three values "request", "session", "application". The "scope" is not required attribute. If the scope is not specified, the default value is "session".

10. "Views" contains configuration for all views.

11. "View" defines all configuration needed for the view event. The element has attributes called "name", "loader" and "page". "name" is the name of the view event. "loader" is the fully qualified class name of the class which implements "org.mvpanchal.zefw.viewloader.ViewLoader". The class would called when the view event occurs. The class is to load data from some data source (like database, webservices etc.) and populates that models (defined in (12)) with the data. The "loader" is not a required attribute. "page" is the path of jsp page which need to be dispatched after processing of the event.

12. "ModelNames" specifies all model names which will be used to carry data from server to browser for this event.

13. "ModelName" has an attribute called "name". "name" contains value of model name which already defined in (8).

14. "Exceptions" same as (6), but this is special configuration. This can override global configuration for this particular event. If an exception is defined in global configuration, and the same exception is defined here then this configuration becomes available to this event. But, global configuration is still available to this event for exceptions which is not specified here.

15. "Exception" same as (7).

16. "ViewValidators" is the validators chain for this event. This specifies validators which validates the event before data loading occurs.

17. "ViewValidator" has an attribute called "type". The "type" is fully qualified class name of the class which implements "org.mvpanchal.zefw.viewvalidator.ViewValidator". The class would be called when the view event occurs. The "validate" method of the class returns another view name if the current view event should not be processed further. If the method returns null then next validator form the chain would be called.

18. "Actions" contains configuration for all actions.

19. "Action" defines all configuration needed for the action event. The element has attributes called "name" and "handler". "name" is the name of the action event. "handler" is the fully qualified class name of the class which implements "org.mvpanchal.zefw.actionhandler.ActionHandler". The class would called when the action event occurs. The class is to process incoming data from models (defined in (20)) and to send the data to some data target (like database, webservices etc.). The "handleAction" method of the class returns view name of the next view event should be occurred.

20. "ModelNames" specifies all model names which are will be used to carry data from browser to server for this event.

21. "ModelName" has an attribute called "name". "name" contains value of model name which already defined in (8).

22. "Exceptions" same as (6), but this is special configuration. This can override global configuration for this particular event. If an exception is defined in global configuration, and the same exception is defined here then this configuration becomes available to this event. But, global configuration is still available to this event for exceptions which is not specified here.

23. "Exception" same as (7).

24. "ActionValidators" is the validators chain for this event. This specifies validators which validates the event before data handling occurs.

25. "ActionValidator" has an attribute called "type". The "type" is fully qualified class name of the class which implements "org.mvpanchal.zefw.actionvalidator.ActionValidator". The class would be called when the action event occurs. The "validate" method of the class returns boolean value. If the value is "true" next validator from chain would be called otherwise normal event processing goes further.

26. "ActionViewRedirects" defines that the jsp page should be redirected or dispatched for the "action" and the "view" event combination.

27. "ActionViewRedirect" has three attributes called "actionname", "viewname" and "sendredirect". "actionname" is a action event name. "viewname" is a view event name. "sendredirect" can have "true" or "false" values. If "sendredirect" is "true" the specified view event would be redirected after the specified action event. If "sendredirect" is "false" the specified view event would be dispatched after the specified action event.

28. "ApplicationProperties" defines property file path if application needed any one. The property file must be java standard property file. We can access properties from the property file using "org.mvpanchal.zefw.applicationproperties.ApplicationProperties" class.

Introduction of the framework

Hello...
The framework is developed by considering two basic request from browser.

[1] Requesting to view a web page. (e.g. We need to see some web page with informative data.).
[2] Submitting form data to server to be processed. (e.g. We need to submit some data to server and server process that data.).

When a user requesting to view a web page, we called it here as "View" event. And when user submitting some data, we called it as "Action" event.

We know that "View" event can be occurred independently, but "Action" event always followed by "View" event.

Here, I have separated the "View" event and "Action" event.


"View" event:

What do we need to implement "View" event? We need some data to be displayed on web page. So, first of all we should have a class (loader class) which can fetch that data from somewhere (like database or webservice), and after that that fetched data need be be set into some classes (model classes). When model is loaded with data, we need a web page (JSP) to display the data to user.
So, we need three component to fulfill the event: (1) A loader class (2) Some model classes (3) A JSP page.

So, now we need a configuration xml file in which we can map all this to a "View" event. The config file is based on an xsd. The framework parses the config file using JAXB, so we need that xsd along with the config xml.

"Action" event:

What do we need to implement "Action" event?. When user submits a form, data goes to a server. We get raw data at server side when user submit a form, but we need to convert that data into appropriate type and need to set into some classes (model classes). After setting the data into models, we need a class which can process that model's data (handler class). Now, it is obvious that after submit event finished, a different or same web page going to be displayed. So, the handler class has one more responsibility. It must return next view event name to be occurred. When a view event name returned the framework kick starts the "View" event. Converting the raw data and setting it into models is the responsibility of framework. So, we need two components to fulfill the event: (1) Some model classes (2) A handler class.

We can configure with the framework that a "View" event preceded by an "Action" event are to be dispatched or to be sent redirect.

What if an exception occurs during view loading or action handling phase? To handle this, the framework has a mechanism. We can configure an exception handler class and a JSP page with an exception. When the configured exception or its base exception would be thrown the handler class would be called by the framework and after finishing execution of the handler class the JSP page would be dispatched. The exception information can be displayed on the JSP by custom tags of the framework.

We can configure validator chain for an "Action" event. The validator validate form data populated in models and if there are some validation errors it populates the errors in error list and returns true or false to the framework. If it returns true the framework calls next validator in the validator chain other otherwise not. The validation errors will be displayed by the custom tags on web page later.

We can configure validator chain for a "View" event. The validator validates that the view is eligible to be displayed or not. If not than the validator returns other view name instead of current and the other "View" event occurs. But, if the validator returns null then next validator would be called in the validator chain.

We can configure application initializer and application destroyer classes. The classes would be called when application context initialized and destroyed respectively. There are an other configuration too. We can configure a processing tube class which would be called on each "View" or "Action" event.

The framework would generate conversation errors if form data are not the type of mapped model properties. It will be displayed by the custom tags on web page later.

User can generate application messages in any place of application. It will be displayed by the custom tags on web page later.

Other features of the framework:

[1] Model classes for an event ("View" or "Action") can be more than one.
[2] Model class can have below type of properties:
    (1) int, long, short, boolean, char, double, float
    (2) java.lang.Integer, java.lang.Long, java.lang.Short, java.lang.Boolean, java.lang.Character, java.lang.Double, java.lang.Float
    (3) java.lang.String, java.util.Date
    (4) Multi Dimensional array of above (1)st to (3)rd type
    (5) Any user defined object
    (6) Multi Dimensional array of (5)th type
[3] User defined object property of a model can have property of any of above (1)st to (6)th type
[4] The framework provides expressions by which JSP page can fetch data from any depth of model's properties.
[5] A JSP can read data of type (1)st, (2)nd, (3)rd and (4)th from model using the expressions. The last property in hierarchy should not be (5)th and (6)th type.
[6] When user inputs some data into form, the data is in string format. But, the framework can convert that data into above types except (5)th and (6)th . To convert data we just need to map that property with the input field of the form.
[7] An enough set of custom tags which are used:
    - to fetch model data to be displayed, to set model data to be processed later
    - to create html forms, input fields, links, buttons etc
    - to display application messages, conversation errors, validation errors
    - to loop for some integer variable
    - to define variable and assign some value to it
    - to display exception info

Please, find the code, release and tutorial of the framework here https://github.com/frozenarc/zeframework.
Please, mail me on zeframework@gmail.com or put comments for your suggestions and bugs.

Thanks