Japano Documentation - Annotation Reference

@JapanoTag

@JapanoTag is used to mark sub classes of org.japano.PageNode as custom tags. The class level javadoc of that class is used as tag description.

Elements:

name (String)

The name of the tag to generate.
default: the name is generated from the class name.

library (String)

The tag library to add the tag to.
default: library name is generated from package name

bodyContent (String)

Specifies what content is valid for this tag. Valid values are

"empty" - Tag can't have a body
"JSP" - Tag contains JSP code
"tagdependent" - Tag has tag dependend content.
"scriptless" - JSP with no expressions.

default: "JSP"

Tags valid in @JapanoTag marked classes :

Property mutator ("setter") methods in @JapanoTag marked classes can be marked as custom tag attributes with @JapanoAttribute. The javadoc comment of the method is used as attribute description.

Elements:

name (String): The name of the attribute to generate.
default: the name is generated from the property name of the mutator method.
required (boolean): If set to true, the attribute will be marked as required.
rtExprValue (boolean): If set to true, the attribute can be a tradional JSP expression or EL expression. This is mainly usefull to forbid runtime expression values for an attribute. default: true

@JapanoOutput

Methods in @JapanoTag marked classes can be marked with @JapanoOutput to mark them as output tags. Output tags are are normal tags in the JSP document but are resolved to a single method invocation on their parent at compile time. If the method is a property accesser ("getter") the property name will be used, otherwise the method name is used as output tag name. An attribute is created for every method parameter. If a parameter is of the type org.japano.Buffer no attribute will be created for it and the parameter will be set to the current ouput buffer when the method is called. The javadoc comment is used as output tag description.

Elements:

required (String[])

Contains an array of required parameters. the attributes created from this parameters are set to be required.
default: empty array.

properties (String[])

Contains an array of property chains to define the output tags for. If properties is set the output tag will not be defined for the method whose javadoc the tag is in but for a property accessor of the return value.

Example:

@JapanoOutput ( properties= { "alias", "address.street" } )
public User getUser()
{
 return user;
}

This would define two output tags. One for the getUser().getId() method and one for the getUser().getAddress().getStreet(). If the property chain cannot be resolved at JSP compile time error occurs.
default: empty array, the output tag is created for the marked method.

@JapanoAction

Implementations of org.japano.action.Action can use the @JapanoAction annotation to mark them as mapped action. The marked actions are mapped to an action URI and form and link invocation tags are created to invoke them from a JSP document.

Elements:

library (String): The tag library to add the tags to.
default: no default - you must specify this.
name (String): The name of the action to generate.
default: the name is generated from the class name.
extension (String): extension to use for this action. This is usefull if you want to serve other mime-typed than text/html and want (or must due to certain browsers) to serve common extensions, too.
default: ".do"
createTag (boolean): If set to false, no tag is created for this action tag. You will still be able to perform the action if you invoke the apropriate URI.
default: true
requiredMarker (String): HTML code to insert after form elements that are marked required.
default: <sup><small>*</small></sup>

Ping Pong Actions

Action can implement the org.japano.action.PingPongAction interface to be performed in two stages. When a jsp view builds the invocation form, the ping pong action is constructed and supplied with the session information. Then the readable properties of the action and included beans are used to populate the form fields with the current state.

The client changes the form fields and sends the form back to the japano site. Japano retrieves the action instance constructed above, updates the state and finally performs the action.

Action Mapping Details

The action is mapped to a qualified name which is build from the library path and the action name. An Action with the name "add" in the library "/japanosample/test" is mapped to a the qualified name "japanosample-test-add.do". The action is called by this qualified name in any sub directory of the web application. The action above deployed on www.example.org would be called by the following URL "http://www.example.org/any/path/japanosample-test-add.do"

Action Parameters

The following tags can be used to mark mutator ("setter") methods as parameters for the action:

@JapanoParameter

Marks the method as an action parameter. If an action contains only @JapanoParameter parameters a link invocation tag is created otherwise a form invocation tag is created.

The following tags are used to declare a form field action parameter:

@JapanoBean

The @JapanoBean annotation can be used to declare the properties of the return type of an accessor method as action parameter. The type is inspected and for every property a default form parameter is created. the default configuration can be changed by using the form field annotations below with a property attribute specifying which property the form field tag refers to.

Elements:

ignore (String[]): Array of properties to ignore. No action parameters are created for these properties.

See @JapanoBean below for another method of action bean declaration.

@JapanoInfo

Used to declare a static information field. Read-only properties of @JapanoBean marked classes are mapped to a @JapanoInfo field by default.

@JapanoPassword

is used to declare a password field.

Elements:

name (String): Name of the password field.
default: property name of the mutator method.
maxLength (int): Maximum length for this parameter value.

Attributes of the tag created for a @JapanoPassword tag:

size: used as input field size.
style, class: used as HTML CSS Attributes

@JapanoRadio

A @JapanoRadio annotation is used to define a radio button group for the mutator method it marks.

Elements:

options (@JapanoOption[]): Contains the options for the radio button group.
value (String): Initially selected radio option. Must be one of the option values.
default: first radio option.
name (String): Name of the radio button group.
default: property name of the mutator method.

The @JapanoOption annotation used for @JapanoRadio annotations has the following elements:

name (String): name of the option
value (String): value of this option

@JapanoSelect

The @JapanoSelect tag is the most complex of the field tags. It offers several ways of defining the selection values. You can either only specify texts to be displayed or text or text/value pairs where the text is displayed in the JSP page but the value is used for the HTTP parameter. You can define constant select fields whose values are known at compile time or dynamic select fields which values are only known at runtime.

Constant Select Fields

A constant select fields has the following elements:

options (@JapanoOption[]): Array containing the constant options for the select field.
value (String): Initially selected value. Must be one of the select field values.
default: first select option.
multiple (boolean): If set to true, the select field will allow multiple values to be selected. This element can only be set for mutator methods that take String[] as argument.
default: false
name (String): Name of the select field.
default: property name of the mutator method.

The @JapanoOption takes the following elements when used in a @JapanoSelect annotation:

text: text to be displayed for this option
value: value to be used for this option

You must either speficy all options with a value attribute or all without a value attribute.

Dynamic Select Fields

Dynamic select fields call one or two methods every time they are generated into a JSP page. The method must return a java.util.List.

Elements:

texts: Method to call for the list of texts to display
default: no default, must be specified.
values: Method to call for the list of values to send as HTTP parameters. if not given, the texts will be used instead.
multiple (boolean): If set to true, the select field will allow multiple values to be selected. This element can only be set for mutator methods that take String[] as argument.
default: false
name (String): Name of the select field.
default: property name of the mutator method.

If the action is a ping pong action the methods can be non-static otherwise they must be static methods.

Attributes of the tag created for for a @JapanoSelect tag:

size: size of select form field.
style, class: used as HTML CSS Attributes

Boolean properties of @JapanoBean marked classes are mapped to a @JapanoSelect field by default.

@JapanoSubmit

Used to declare a submit button. Every form has at least 1 submit button. If none is defined the meta processor adds one automatically.

Elements:

name (String): Name of the submit button.
default: property name of the mutator method.

Attributes of the tag created for a @JapanoSubmit tag:

image: URL of the image to use for the button
text: text to display on the button.
style, class: used as HTML CSS Attributes

@JapanoTextArea

Used to declare a text area.

Elements:

maxLength: maximum length of the text.
name (String): Name of the text area.
default: property name of the mutator method.

Attributes of the tag created for a @JapanoTextArea tag:

cols: number of columns
rows: number of rows
style, class: used as HTML CSS Attributes

@JapanoText

is used to declare a text field.

Elements:

maxLength: Maximum length for this parameter value.
name (String): Name of the text field.
default: property name of the mutator method.

Attributes of the tag created for a @JapanoText tag:

size: used as input field size.
style, class: used as HTML CSS Attributes

Properties of @JapanoBean marked classes are mapped to a @JapanoText field by default.

@JapanoBean

You can use a @JapanoBean annotation to mark a class as java bean to be nested inside actions. The methods of the class are scanned for form field annotations.

Note: You must also use a @JapanoBean on a accessor method of an action to use the marked class as form bean or to override or ignore form fields.

@JapanoValidation

Any parameter to an action can be ensured to have a valid value by declaring validators with a @JapanoValidation tag. One of the following attributes must be used to specify the validation rules:

limit: lower and upper limit of the integer value of this parameter separated by a comma.
regex: value must be a regular expression which the parameter value is matched against.
custom: uses an instance of the specified class to validate the parameter. The attribute value must be a full qualified java class name implementing org.japano.action.Validator.
errorMessage: Message displayed if the validation fails.
required: Determines whether the parameter required or not.
requiredMessage: Message displayed when a required parameter is not present.

Japano ensures that all parameters are validated before the first one is set. If any parameter validation fails, no parameter is set and the action is not performed and if its a normal action not even instanciated. (Actions can implement org.japano.action.ActionParameterValidator to act on failed invocation attempts.)

Failed parameter validations generate add a message to the last view and resend that view to the user. The form invocation fields targeting failed parameters will also preserve the user input to override their default value in this view. These fields are also generated with a special CSS class named "fieldError".

@JapanoFunction

A static method can be marked with @JapanoFunction to mark it as an EL function.

Elements:

library: tag library to define the EL function in.
default: none, must be set
name: name of the EL function. if this attribute is not set.
default: method name

Java1.4/compatibility

Every Annotation documented here has an equivalent javadoc tag which can be used instead to retain java1.4 compatibility. Instead of using the Annotation @JapanoTag you can use the javadoc tag @japano.tag. The javadoc tags have the same attributes as the annotations have elements but only use a string representation of the annotation element types. For Annotation elements which return array types the javadoc attributes except a comma seperated list of string representation of the array element type. The @JapanoSelect and @JapanoRadio annotations are an exception to this rule. While the annotation versions have an element named "options" which returns an Array of @JapanoOption annotations, the javadoc equivalent uses @japano.option sibling tags in the same javadoc.

Examples:

@JapanoTag ( library="/sample" )
is equivalent to
/** @japano.tag library="/sample" */
        
@JapanoText ( maxLength=50 )
is equivalent to
/** @japano.text maxLength="50" */
        
@JapanoOutput ( properties = { "alias", "address.street" } )
is equivalent to
/** @japano.output properties="alias, address.street" */
        
@JapanoSelect ( options = { @JapanoOption ( text="yes" ), @JapanoOption ( text="no" ) } )
is equivalent to
/** 
@japano.select
@japano.option text="yes"
@japano.option text="no"
*/

Both annotations and javadoc tags can also be used to mark normal java tags or simple tags.