Friday, October 17, 2014

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]}"/>


Thursday, October 16, 2014

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.