Developing with japano

This document is thought to explain some basics about the work with japano. If you're totally new to japano you might want to check out the sample application you can also download from the sourceforge project page. It is a self-documenting webapplication which gives examples for the features explained in this document. You can also use the sample webapplication source as base for your project.

Once you have configured the japano servlet in the /WEB-INF/web.xml file you will not encounter any other XML descriptors or metadata files. You just use the japano API to write annotated tag and action sources and the japano build script will take care of everything else.

schematic view of the japano build process

Writing japano tags

Japano offers two possibilies to create your own tags: The japano way of writing a custom tag is to write classes which extend org.japano.PageNode If you mark the class with a @JapanoTag annotation, japano will include this tag into the tag library descriptors it creates. You can use @JapanoAttribute annotations to make japano produce custom tag attributes for "setter" methods. You can use @JapanoOutput annotations to mark a method with return value as output tags. Output tags are normal tags on the JSP side but just insert the return value of a method invocation on the parent tag into the document.

One of the reasons japano was written was dissatisfaction with the traditional JSP tag model. While the custom tag aproach is surely the best way to implement non-trivial websites, it was too cumbersome to use and suboptimal in several ways.

With the current beta release Japano now has experimental support for normal JSP tags and simple tags. Japano uses special adapter classes to offer a normal JSP environment. If you have problems running custom tags with japano, you can contact me to report about it, so I can fix it.

Writing actions

Japano also supports MVC (Model, View, Controller) functionality. The following diagram shows how this works:

schematic view of the japano MVC engine

Japano sends JSP pages (views) to the browser. Apart from normal tags these pages contain action invocation tags which insert hyperlinks and forms. Clicking/submiting these sends a request to the japano servlet. The servlet finds the correct action, parametrizes it and performs it. The action can access and modify the users session, connect to a database or access another JSP scope.

Actions are user-defined classes that implement org.japano.action.Action. The actions are marked with @JapanoAction to map them to a URI and to generate invocation tags for them. "Setter" methods of an action can be marked with @JapanoParameter or one of several form field tags to declare an action parameter.

A simple action is created when a user makes an HTTP request to the URI the action is mapped to. HTTP parameters of that request are used to configure the action instance before it is performed. The action can use org.japano.Session#setView to choose an appropriate JSP view and use org.japano.View#addAttribute to send initial pageScope attributes to that view or it can answer the request itself.

Parameter Validation

Using the @JapanoValidation tag any action parameter can be automatically validated. If a parameter is about to be performed all parameters are validated first. If all validations were successfull and all required parameters are present, the action and nested beans are modified using with the received parameters and the action is performed.

View messages are generated for all failed parameter validations and form fields that were source of an invalid parameter are marked with the CSS class "errorField". Invalid user input is preserved and overrides the form content in the following view. If the action also implements org.japano.action.ActionParameterValidator, the validate method is called to allow further validation or reaction to validation failures.

Action lifecycle

Simple actions are just instanciated after all action parameters are successfully validated, performed and destroyed.

The org.japano.action.PingPongAction interface can be used to create more complex HTML forms. A ping pong action is created when the associated invocation tag is used in a document. The instance is created and initialized with a session context. the action attributes are used to get the current state of the action. those state is used to prepolate the HTML form fields of the invocation tag. When the user sends back the changed content, that content is validated and set to in the same action instance which is then performed. Ping pong actions also support nested java beans. See the sample webapplication for an example of this.

( See also org.japano.action.DefaultView, org.japano.action.Lifecycle and org.japano.action.ActionParameterValidator )

Japano Session Handling

All sessions japano uses are subclasses of org.japano.Session. You can specify your own type in the japano configuration. You use normal java methods and fields to store the most common session attributes for your web page. EL expressions like for example ${pageContext.session.user} are resolved to direct method calls using the knowledge about the sub type.

Japano supports three different strategies for session id transport:

The first two strategies can be disabled via servlet configuration. If cookies are enabled, japano tries to set a cookie first and falls back on one of the other strategies if the client does not send the cookie back.

When putting the session id into the path, japano encodes it as first path part of the URI so that a typical URI looks like this.$--Random-Chars--/index.jsp

for the session id --Random-Chars--. The session id is an alphanumeric encoding of a 96bit value generated by a secure random generator. Japano wraps the request from the servlet container so that the session id is ignored by getURI() etc..

Because the session id is part of the path every relative link will still access the same session. If you use an absolute URI or an server relative uri starting with '/' japano will not find a session id and start a new session. Static files can be specified either absolutely, server root relative or relative. Japano forwards requests to static resources to the default servlet.

While this approach seems unusual and maybe confusing at first I believe that it's a good way to write a cookie-less web page without having to care about inserting the session id into all URIs. This is why this approach is enabled by default. You can disable it with the sessionIdPath init-parameter in the web.xml file.


Setting up a project

Japano uses ant for building. You can download the Japano Sample Webapplication and use it as starting point for your japano project. It contains the nessecary ant scripts.

The following classes are used in the ant build script:

For an example how to use these classes take a look at the build.xml file included with the sample application.