|
ActionServlet Specification
1. Definitions of terms1.1 Componentsare objects which action methods are invoked by HTTP requests. Each component is referenced by ActionConfig, where it has specified name, Java class and persistence and (optionally) instantiator.Name refers component in <property>, <input-variable> and <output-variable> elements. Class determines which class will be used to instantiate the component. Persistence determines durability of a component object and may be one of three types:
If the component wants to be notified when it
is no longer used by ActionServlet, it should implement
Component classes can be of any type (JavaBeans, EJBs, Corba objects etc.) and are created by instantiators (classes that implement org.actionframework.instantiators.Instantiator interface). Instantiators are referred by instantiator attribute of <component> element. If no instantiator is specified, the default instantiator is used. 1.2 Action methodsimplement the behaviour of a component. Each action method must be declared public. To parameters of action method are passed values of HTTP parameters automatically converted to Java types by type handlers}. Return values can be mapped to template names by <on-return> element and exceptions handled by <on-exception>s.The action method to be invoked is chosen after the name of parameter 'action' and, optionally, 'form' (if omitted, it has a default empty value: ""). For example, "login" action would invoke someComponent.login(...) method. Alternatively, any URL can be mapped to an action (see regex actions). Action selection can be also based on the request type, which means that some action my be limited to HTTP GET or POST requests only or require HTTPS. See <action> element for detailed information. 1.3 TemplatesYou should be familiar with WebMacro or Velocity templates already. The new thing is that you can pass HTTP parameter value(s) from template directly to the component's action method.Example: the following HTML form defines a parameter named userName and password (and of course, the mandatory 'action'):
<FORM METHOD="POST">
User name: <INPUT TYPE="Text" NAME="userName">
Password: <INPUT TYPE="Password" NAME="password">
<INPUT TYPE="Submit" NAME="action" VALUE="Login">
</FORM>
Values of these parameters can be easily passed to the action method:
public int login(String userName, String password)Note: A similar effect can be achieved by GET method - using a link like: <A HREF="$SERVLET?action=Login&userName=John+password=18x79Z">login as John</A> 1.4 Type handlersare used for conversions between different types in the case when the target type is not assignable from the source type. Assignable target types are assigned by implicit conversion. For example, java.lang.Integer is assignable to java.lang.Number (because Number is a supertype of Integer), but to assign java.lang.Number to java.lang.Integer a type handler is needed.Type handlers provide a convenient way to link various components together (see also <invoke> element), where the conversions of parameters types is done by separate (i.e. more independent and maintainable) code:  With servlets, most commonly are used type handlers for conversion from java.lang.String (supplied in HTTP request from <FORM> parameters or in URL) to other types - int, float, double etc. ActionServlet has already defined type handlers from java.lang.String to all primitive types. Also, a "dummy handler" for converting standard wrapper classes to primitive types (like Integer to int) and vice versa is set. Arrays are also passed to action methods automatically. If an array is needed to be converted to a non-array type with the same component type (for example, String[] to String) and a type handler for this operation is not defined, default "dummy array handler" - which just returns the first element of the array - is used (this is useful especially when values of HTTP parameters are retrieved). In case of array-to-array conversion (int[] to Integer[], for example *), if no type handler for array conversion is found, elements are converted one by one (by default dummy handler - for *). To support file uploading, virtual type handlers from java.lang.String to java.io.File and to java.io.InputStream are also defined. This means that you can pass the content of uploaded file to an action method as a temporarily stored File or directly as an InputStream - depending on your needs (see examples/FileUploads).
Every type handler must implement one of these interfaces:
1.4.1 Type handlers and actionsType handlers are used automatically when action method is to be called. [Note: You may need to read the rest of this specification first.]The following description refers to this ActionConfig example:
<type-handlers>
<type-handler target-type="java.util.Date" class="DateHandler"/>
</type-handlers>
<component name="DateComponent" class="DateComponent" persistence="application">
<action name="Submit" method="submit(java.util.Date date)">
<input-variable name="date" value="day,month,year"/>
<on-return value="void" show-template="SubmittedDate.wm"/>
</action>
</component>
When a HTTP request is made by user:
2 ActionConfig (XML configuration file)has a simple XML format and is divided into four main parts: <properties> (optional), <templates> (optional), <type-handlers> (optional) and <components> (mandatory):
<?xml version="1.0"?>
<!DOCTYPE application SYSTEM
"http://www.actionframework.org/dtd/ActionServlet_0_94.dtd">
<application>
<properties>
...
</properties>
<templates>
...
</templates>
<type-handlers>
...
</type-handlers>
<components>
...
</components>
</application>
ActionConfig filename must be passed to ActionServlet via a servlet init parameter named
"ActionConfig". For Servlet 2.2+ containers it is done inside the servlet
tag in web.xml file.Optional servlet init parameter named "ActionEngine" may specify template engine. The value of this parameter may be:
<servlet>
<servlet-name>LoginServlet</servlet-name>
<servlet-class>org.actionframework.ActionServlet</servlet-class>
<init-param>
<param-name>ActionConfig</param-name>
<param-value>LoginServlet.xml</param-value>
</init-param>
<init-param>
<param-name>ActionEngine</param-name>
<param-value>Velocity</param-value>
</init-param>
</servlet>
For other environments constult your servlet runtime documentation.Note: Velocity.properties file can passed to ActionServlet through init parameter named properties as usual (path can be relative to the servlet context). Example:
<init-param>
<param-name>properties</param-name>
<param-value>WEB-INF/classes/Velocity.properties</param-value>
</init-param>
2.1 The root <application> elementmay have optional repository attribute, which specifies a location where servlet components and other classes are stored. By default, this attribute may be used only if you don't subclass ActionServlet, otherwise it is expected that all classes are loaded from CLASSPATH or relatively to the servlet real path - by the servlet runtime, as usually. Subelements of <application> are described in the following sections. Example:
<application repository="c:/servlets/App1/classes">
...
</application>
Note: Custom class loading is possible by overriding getClassLoader() method.2.2 <properties> element contains one or more <property> subelements, which have attributes name, value and optionally component (refers to a <component> name). Example:
<properties>
<property name="server.url" value="http://some.server.com"/>
<property component="DbAccess" name="max.connections" value="10"/>
</properties>
Alternatively, <property> can contain <input-variable>, in which case the value for property is retrieved from this subelement. Value of the <property> must correspond to the name of <input-variable>. Example:
<properties>
<property name="jndiContext" value="ctx">
<input-variable name="ctx" component="JNDIComponent" value="getContext()"/>
</property>
</properties>
Note 1: Value of each property is retrieved by getProperty(name) and
getProperty(component,name).Note 2: ActionServlet components should be configured via properties with component attribute (other properties should be considered global). Note 3: Usage of JavaBeanInstantiator is highly recommended. Global property names starting with org.actionframework are reserved. Currently, the following properties can be used to configure ActionServlet.
2.3 <templates> element contains one or more <template> and zero or more <on-exception> subelements. Example:
<templates>
<template name="First.wm"/>
<template name="Second.wm"/>
<template name="Third.wm"/>
<on-exception class="java.lang.Exception" show-tepmplate="error.wm">
<output-variable name="error" value="Error in template ocurred!"/>
<on-exception>
</templates>
2.3.1 One or more <template> elements can be nested in <templates> element. These elements are used to specify:
Each <template> element must have a name attribute specifying the name of the template. A non new-session template name can also contain a regular expression (Perl5 compatible), which allows to specify common subelements processed for multiple temples. Example:
<templates>
<template name="Login.wm"/>
<template name="Main.wm" is-new-session="true">
<output-variable name="isAuthenticated"
component="Authenticator" value="isAuthenticated()"/>
<output-variable name="user"
component="Authenticator" value="getUser()"/>
</template>
<template name=".*">
<output-variable name="someString" value="Yes!"/>
</template>
</templates>
In the example is set $variable isAuthenticated to the value returned by isAuthenticated()
of component Authenticator and $user to the value returned by Authenticator.getUser() -
every time Main.wm template is shown. Variable someString is set to "Yes!" for all templates.
2.3.1.1 Zero or more <include-template> elements can be nested in <template> element. Each <include-template> element has attributes:
If there is no condition or the condition is true, <template> element of the specified template name is processed. This is useful when several templates are combined into one page. Example:
<templates>
<template name="Main.wm" is-new-session="true">
<include-template name="Login.inc.wm"/>
<include-template name="$currentSkin/footer.inc.wm"/>
</template>
<template name="Login.inc.wm"/>
<output-variable .../>
<output-variable .../>
<template>
<template name="default/footer.inc.wm"/>
<template name="nice/footer.inc.wm"/>
</templates>
2.4 <type-handlers> elementcontains one or more <type-handler> subelements, that bind type handlers to appropriate Java types. Each <type-handler> element has attributes:
<type-handlers>
<type-handler target-type="my.types.Email[]"
class="my.handlers.ArrayEmailHandler"/>
<type-handler target-type="java.util.Date"
class="my.handlers.DateHandler"/>
<type-handler source-type="java.io.File"
target-type="java.io.FileInputStream"
class="my.handlers.FileHandler"/>
</type-handlers>
Note: Inheritance of types is taken in account - for example, if you declare type handler for conversion from java.lang.Number to int, then all subclasses of java.lang.Number (i.e. java.lang.Byte, java.lang.Double etc.) will be converted automatically to int by this handler (if this setting is not overridden by another <type-handler> element). Example:
<type-handlers>
<type-handler source-type="java.lang.Number"
target-type="int"
class="some.Handler"/>
<-- the following element overrides handler on the previous line -->
<type-handler source-type="java.math.BigInteger"
target-type="int"
class="other.Handler"/>
</type-handlers>
Note 1: Whole tree of type handlers bindings is dumped to log during initialization of ActionServlet,
if logging level is set to DEBUG (see examples).Note 2: See also <invoke> to see how type handlers are also used. 2.5 <components> element contains:
<components>
<component .../>
<component .../>
<on-return .../>
<on-exception .../>
</components>
2.5.1 One or more <component> elementsmust be specified under <components> element. Each <component> element has attributes:
<component class="Authenticator" persistence="application">
<action name="Login" method="login(String userName, String password)"/>
<on-return value="void" show-template="SuccessfulLogin.wm"/>
<on-exception class="LoginException" show-template="LoginError.wm"/>
</component>
2.5.2 Zero or more <action> elements,which bind actions to components' action methods, can be specified inside each <component> element (before <on-return> elements). Element <action> has attributes:
Example:
<component name="Searcher" ...>
<action form="Search" name="OK" method="search(String str)"/>
<action form="Submit" name="OK" method="newURL(java.net.URL url)"/>
<action name="/download/*/images" method="getImage(String imgName)"/>
...
</component>
<component name="Authenticator" ...>
<action name="getUserCount" method="getUsersByName(String userName).size()"/>
</component>
<component name="MyComponent" ...>
<action name="*unassigned*" method="doDefaultAction()"/>
</component>
This maps http://some.server/yourServlet?form=Search&action=OK&str=Java to
search() method, http://some.server/yourServlet?form=Submit&action=OK&url=http://added.url/whatever to
submit() method, http://some.server/yourServlet/download/1/images?imgName=some.gif
to getImage() method and so on. MyComponent.doDefaultAction() would be called for all unmatched actions.Element <action> can optionally contain subelements:
<action name="Login" method="login(String userName, String password)">
<input-variable name="userName" value="defaultUser" if="!userName"/>
<input-variable name="password" value="defaultPassword" if="!password"/>
<output-variable name="user" component="Authenticator" value="getUser()"/>
</action>
Result of the action can be manipulated using <on-return>
and <on-exception> element.2.6 Zero or more <input-variable> elements can be specified inside <property> or <action>. Each <input-variable> has attributes:
Note 1: If component is specified and value is "this", then $variable will be
assigned the component itself. This element may also have nested <type-handler> (that has only class attribute in such case), which is used to override "global" <type-handler>. Example:
<input-variable name="userName"
value="defaultUserName"
if="!$userName || $userName.length()==0"/>
<input-variable name="source" component="SomeComponent" value="this"/>
<input-variable name="value" component="OtherComponent" value="getObject()">
<type-handler class="my.package.MyHandler"/>
</input-variable>
2.7 Zero or more <output-variable> elementscan be specified inside <template>, <action>, <on-return> or <on-exception> elements. It has four attributes:
Note 1. First are evaluated output variables of <action>, then of
<on-return> and at last of <template>. This element may also have nested <type-handler> (that has only class attribute in such case), which is used to override "global" <type-handlers>. Example:
<output-variable name="user" component="Authenticator" value="getUser()"/>
<output-variable name="name" value="$user.Name"/>
<output-variable name="number" value="123" if="$name == "admin""/>
<output-variable name="component" component="Counter" value="setCounter($number)"/>
<output-variable name="component" component="SomeComponent" value="this"/>
<output-variable name="value" component="OtherComponent" value="getObject()">
<type-handler class="my.package.MyHandler"/>
</output-variable>
<output-variable name="newURL" value="$URL/setUser/$name"/>
See also: examples/OutputVars.2.8 Zero or more <on-return> elements can be specified:
Zero or more <invoke> elements, which allow invocation of a subaction, and zero or more <output-variable>s can be nested inside <on-return> - evaluation and invocation takes place in the specified order. Example:
public class MyComponent {
public static final int OK = 0;
int firstMethod() {
return OK;
}
boolean secondMethod() {
return true;
}
int thirdMethod(int number) {
return number * 2;
}
void fourthMethod() {}
}
<component class="MyComponent" ...>
<action name="action1" method="firstMethod()"/>
<action name="action2" method="secondMethod()">
<on-return value="true" show-template="Template1.wm">
<invoke method="firstMethod()"/>
<output-variable name="number" value="123"/>
<invoke method="fourthMethod()"/>
</on-return>
</action>
<action name="action3" method="thirdMethod()">
<on-return value="*" assign-to="result" show-template="Template2.wm"/>
</action>
<action name="action4" method="fourthMethod()"/>
<on-return value="OK" show-template="Template3.wm"/>
<on-return value="void" show-url="myURL">
<output-variable name="myURL" value="http://www.actionframework.org"/>
</on-return>
</component>
can be specified:
Zero or more <invoke> elements, which allow invocation of a subaction, and zero or more <output-variable>s can be nested inside <on-return> - evaluation and invocation takes place in the specified order. The position of <on-exception>s has a similar meaning as for try-catch blocks: <on-exception>s inside <component>s (if any) handle uncaught exceptions from its <action>s and <on-exception>s in <components> (if any) handle uncaught exceptions from all <component>s and all <action>s. Similarly, uncaught exceptions from <template> are propagated to <on-exception>s of <templates>. Example:
public class MyComponent {
void myMethod(int i) throws Exception {
if (i < 0) throw new ArithmeticException();
else if (i > 0) throw new IllegalArgumentException();
else throw new NumberFormatException();
}
}
<components>
<component class="MyComponent" ...>
<action name="myAction" method="myMethod(int i)">
<on-exception class="java.lang.ArithmeticException"
show-template="Template1.wm"/>
<on-exception class="java.lang.NumberFormatException"
show-template="Template2.wm"/>
</action>
<on-exception class="java.lang.Exception" show-template="Template3.wm"/>
</component>
</components>
can be nested inside <template>, <on-return> and <on-exception>. This element is used to define methods executed when template is displayed or when <on-return> and <on-exception> are processed. Element <invoke> can contain the same subelements as <action>. Attributes of <invoke> are:
<application>
<templates>
<template name="welcome.wm" is-new-session="true">
<output-variable name="welcomeString" value="Welcome!"/>
<invoke component="counter" method="incNumberOfAccesses()"/>
</template>
</templates>
<components>
<component name="counter" class="Counter" persistence="application"/>
<component name="sender" class="Sender" persistence="session">
<action name="getData" method="getData()">
<on-return value="*" assign-to="result" show-template="data.wm">
<invoke component="receiver" method="receiveData(int result)"
if="$result!=0">
<input-variable name="result" value="$result"/>
<invoke/>
</on-return>
</action>
</component>
<component name="receiver" class="Receiver" persistence="session"/>
</components>
</application>
Element <invoke> allows sending data between components and is
useful when you need to pass data of one action to more components.
Type handlers automatically convert parameters values to
target types.2.11 Zero or more <pre-invoke> elements can be nested inside <components>, <component> and <action> - as their first element(s). These elements are invoked when <action> is known, but before it is processed - and therefore may be used:
Example:
<components>
<pre-invoke component="Logger" method="logNoHttps()"
if="$URL.getProtocol() != "https"">
<on-return value="*" show-template="YouMustUseHttps.wm"/>
</pre-invoke>
<component name="Authenticator" class="Authenticator" persistence="session">
<pre-invoke method="isLoggedIn()">
<on-return value="true"/>
<invoke method="logoff()"/>
</on-return>
</pre-invoke>
<action name="/login" method="login(String userName, String password)"/>
</component>
<component name="Logger" class="Logger" persistence="application"/>
</components>
First are processed <pre-invoke> elements of <components>,
then of <component> and at last of <action>.Element <pre-invoke> can contain the same subelements as <invoke> plus:
Example:
<components>
<pre-invoke component="Authenticator" method="isAdmin()" group="checkit,grp2">
<on-return value="true" show-template="NotAdminError.wm"/>
</pre-invoke>
<component name="Secure1" class="Secure1" persistence="session">
<action name="/secureAction1" method="secureMethod1()" group="checkIt"/>
</component/>
<component name="Secure2" class="Secure2" persistence="session">
<action name="/secureAction2" method="secureMethod2()" group="grp2"/>
</component/>
</components>
2.12 Zero or more <post-invoke> elementscan be nested inside <components>, <component> and <action> - as their last element(s). These elements are invoked after <action> is processed - and therefore may be used to perform some kind of default post-action. Example:
<components>
<component name="Authenticator" class="Authenticator" persistence="session">
<action name="/login" method="login(String userName, String password)"/>
</component>
<component name="Logger" class="Logger" persistence="application"/>
<post-invoke component="Logger" method="logAction(String url, String action)">
<input-variable name="url" value="$URL"/>
<input-variable name="action" value="$ACTION"/>
</post-invoke>
</components>
First are processed <post-invoke> elements of <action>,
then of <component> and at last of <components>.Element <post-invoke> can contain the same subelements as <invoke> plus:
Example:
<components>
<component name="C1" class="C1" persistence="session">
<action name="/someAction1" method="someMethod1()" group="grp1"/>
</component/>
<component name="C2" class="C2" persistence="session">
<action name="/someAction2" method="someMethod2()" group="grp1,grp2"/>
</component/>
<component name="Logger" class="Logger" persistence="application"/>
<post-invoke component="Logger" method="logAction(String action)" group="grp2">
<input-variable name="action" value="$ACTION"/>
</post-invoke>
</components>
2.13 Zero or more <validate> elementscan be nested inside <action>, <invoke>, <pre-invoke> and <post-invoke> - after their <input-variable>s. These elements are invoked after parameter conversion is done and may be used to validate values of parameters. Element <validate> has no nested elements and has attributes:
Example:
<action name="/submitEmail" method="login(String email)">
<validate component="validator" method="validate(String email)"/>
<on-exception class="my.package.BadEmailException" show-template="BadEmail.wm"/>
</action>
Note that any method (that throws some exception) of any component may be used for validation!An example of ActionConfig may look like this (not all combinations and elements are used):
<?xml version="1.0"?>
<!DOCTYPE application SYSTEM
"http://www.actionframework.org/dtd/ActionServlet_0_94.dtd">
<application>
<properties>
<property name="MaxUsers" value="500"/>
<property component="Authenticator"
name="PasswordRetries" value="3"/>
</properties>
<templates>
<template name="Login.wm" is-new-session="true">
<invoke component="Main" method="incNumberOfAccesses()"/>
</template>
<template name="Main.wm">
<output-variable name="isAuthenticated"
component="Authenticator"
value="isAuthenticated()"/>
</template>
</templates>
<type-handlers>
<type-handler target-type="shop.types.Email"
class="shop.handlers.EmailHandler"/>
</type-handlers>
<components>
<component name="Main" class="shop.Main" persistence="application">
<action name="showMain" method="showMain()"/>
<action name="showGoods" method="showGoods()">
<output-variable name="goods" component="Main" value="getGoods()"/>
</action>
</component>
<component name= "Authenticator"
class="shop.Authenticator"
instantiator="JavaBeansInstantiator"
persistence="session">
<action name="Login" method="login(String name, String passwd)">
<input-variable name="name" value="defaultUser" if="!user"/>
<input-variable name="passwd" value="defaultPasswd" if="!passwd"/>
<on-return value="void" show-template="Main.wm"/>
<on-exception class="LoginException" show-template="error.wm">
<output-variable name="retries"
component="Authenticator" value="getRetries()"/>
</on-exception>
</action>
</component>
</components>
</application>
It may be useful to divide ActionConfig into several parts, instead of one
big XML file. You can use standard external entities to achieve better
readibility:
Example: Main ActionConfig file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE application SYSTEM
"http://www.actionframework.org/dtd/ActionServlet_0_94.dtd" [
<!ENTITY my_components SYSTEM "my_components.xml">
]>
<application>
<templates>
<template name="main.wm" is-new-session="true">
</templates>
<components>
&my_components;
</components>
</application>
File my_components.xml then may contain only the XML header and <component> elements:
<?xml version="1.0" encoding="ISO-8859-1"?>
<component name="MyComponent1" class="MyClass1" persistence="session">
<action name="doIt" method="doIt()"/>
<component>
<component name="MyComponent2" class="MyClass2" persistence="static">
<component name="MyComponent3" class="MyClass3" persistence="application">
Detailed description of HTTP request processing follows:
Exceptions to this schema happen:
Destroyed interface.Note 2: error.wm template is used to display errors by default. Its presence is recommended for every application. You can change this behaviour by overriding error() method.
Benefits:
|