Aranea—Java Web Framework Construction and Integration Kit

It is our firm belief that checked exceptions are unnecessary in Controller and therefore Aranea will in most cases allow to just declare your overriding method as throws Exception. On the other hand no framework interfaces throw checked exceptions so the exception-handling boilerplate can be delegated to a single error-handling component.

Since the application programmer implements the same components that are used for framework extension, it is important to discourage the access to public framework interfaces (which are necessarily visible in the overridden classes). Thus a simple convention is applied for core framework interfaces, which is best illustrated with the following example.

public interface Service extends Component, Serializable {
  public Interface _getService();

  public interface Interface extends Serializable {
    public void action(Path path, InputData input, OutputData output) throws Exception;
  }
}

As one can see, the real interface methods are relocated to an inner interface named Interface, that can be accessed using a method _get<InterfaceName>(), which starts with an underscore to discourage its use. As a rule of a thumb, in Aranea the methods starting with an underscore should only be used, when one really knows what one is doing.

Aranea has three main types of components: org.araneaframework.Component, org.araneaframework.Service and org.araneaframework.Widget. These components also have a number of orthogonal properties (like Viewable, Composite), which are represented by interfaces that need to be implemented. Since some particular API methods expect a particular type of component with a particular property (e.g. ViewableWidget) one would either have to abandon static type safety or define a lot of meaningless interfaces that would clutter the Javadoc index and confuse the source code readers. The approach chosen in Aranea is to make such interfaces internal to the property, like in the following example.

public interface Viewable extends Serializable {
  public Interface _getViewable();

  interface Interface extends Serializable {
    public Object getViewModel() throws Exception;
  }

  public interface ViewableComponent extends Viewable, Component, Serializable {}
  public interface ViewableService extends ViewableComponent, Service, Serializable {}
  public interface ViewableWidget extends ViewableService, Widget, Serializable {}
}

Composite pattern refers to a design approach prominent (specifically) in the GUI modeling when objects implementing the same interface are arranged in a hierarchy by containment, where the nodes of the tree propagate calls in some way to the leafs of the tree. It is shown on Figure 2.1, “Composite design pattern”.

Figure 2.1. Composite design pattern

Composite is one of the main patterns used in Aranea. It is mainly used to create a Hierarchical Controller using Component containment. In terms of Component interface Composite is used to propagate life cycle events and route messages (see Section 2.3.3, “Messaging Components”).

The flavor of the Composite pattern as used in Aranea typically means that every contained component has some kind of an identifier or name that distinguishes it from other children of the same parent (note that the child is not typically aware of its identifier). This identifiers are used to route messages and events and can be combined to form a full identifier which describes a "path" from the root component to the child in question. This paths are represented by a Iterator-like interface org.araneaframework.Path.

public interface Path extends Cloneable, Serializable {
  public Object getNext();
  public Object next();
  public boolean hasNext();
}

Each next() call will return the identifier of the next child in the path to the descendant in question. Default implementation (org.araneaframework.core.StandardPath) uses simple string identifiers like "a" or "b" and combines them using dots forming full paths like "a.b.c".

A Composite component may want to make its children visible to the outside world by implementing the org.araneaframework.Composite interface:

public interface Composite extends Serializable {
  public Composite.Interface _getComposite();
  public interface Interface extends Serializable {
    public Map getChildren();
    public void attach(Object key, Component comp);
    public Component detach(Object key); 
  }
}

This interface allows to both inspect and manipulate component children by attaching and detaching them from the parent component.

As most of the Aranea abstractions are built to be used with the Composite concept we will illustrate it in greater detail when examining other abstractions and their implementation. Further on we will assume that any Component has a parent that contains it and every child has some kind of name in relation to the parent unless noted otherwise (obviously there is at least one Composite that does not have a parent, but we don't really care about that at the moment).

org.araneaframework.Environment is another important concept that represents the way Components interact with the framework. Environment interface is rather simple:

public interface Environment extends Serializable {
  public Object getEntry(Object key);
}

It basically provides means of looking up entry objects by their key. A typical usage of the Environment can be illustrated with an example.

...
MessageContext msgCtx = (MessageContext) getEnvironment().getEntry(MessageContext.class);
msgContext.showInfoMessage("Hello world!");
...

As one can see from the example Environment will typically allow to look up implementations of the interfaces using their Class as the key (this is in fact an Aranea convention in using and extending the Environment). The interfaces serving as keys for Environment entries are referred to as contexts. It is thus not unlike JNDI or some other directory lookups that allow to hold objects, however unlike them Environment is very specific to the Component it is given to, and can be influenced by its parents. In fact, all contexts available in the Environment will be provided to the Component by its parents or ancestors (in the sense of containment rather than inheritance). Thus, two different Components may have completely different Environments.

A default implementation of Environment is org.araneaframework.core.StandardEnvironment. It provides for creating an Environment from a java.util.Map, or extending an existing environment with map entries.

A component can provide an environment entry to its descendant, by providing it to the initializer of its direct child. For instance the MessageContext could be provided by the following message component:

public class MessageFilterService implements MessageContext, Component, Service {
  protected Service childService;
  public void setChildService(Service childService) {
    this.childService = childService;
  }

  public void init(Environment env) {
    childService.init(
      new StandardEnvironment(env, MessageContext.class, this);
  }

  //MessageContext implementation...
  public String showInfoMessage(String message) {
    //Show message to user...
  }  

  //...
}

After that the childService, its children and so on will be able to use the MessageContext provided by MessageFilterService. Of course this can be done simpler as shown in examples in chapter

So far, we have looked at the component management and environment. However what makes the component hierarchy such a powerful concept is messaging. Basically, messaging allows us to send any events to any component in the hierarchy (including all components or a specific one). The messaging is incorporated using the org.araneaframework.Message interface

public interface Message extends Serializable {
  public void send(Object id, Component component) throws Exception;
}

and Component.propagate(Message message) method. The default behavior of the propagate() method should be to send the message to all component children, passing the send() method the identifier of the child and the child itself. It is up to the message what to do with the child further, but typically Message just calls the propagate() method of the child passing itself as the argument after possibly doing some custom processing (the double-dispatch OO idiom).

A standard Message implementation that uses double-dispatch to visit all the components in hierarchy is org.araneaframework.core.BroadcastMessage. It usage can be illustrated with the following example:

...
Message myEvent = new BroadcastMessage() {
  public void execute(Component component) throws Exception {
  if (component instanceof MyEventListener)
    ((MyEventListener) component).onMyEvent(data);
  }
}
myEvent.send(null, rootComponent);
...

This code will call all the components in the hierarchy that subscribed to the event and pass them a certain data parameter. As one can see, when calling Message.send() we will typically pass null as the first parameter, since it is needed only when propagating messages further down the hierarchy. Note that messages can be used to gather data from the components just as well as for passing data to them. For example one could construct message that gathers all FormWidgets from the widget hierarchy:

public static class FormWidgetFinderMessage extends BroadcastMessage {
  List formList = new ArrayList();

  protected void execute(Component component) throws Exception {
    if (component instanceof org.araneaframework.uilib.form.FormWidget) {
      formList.add(component);
    }
  }

  public List getAllForms() { return formList; }
}

Another standard Message implementation is org.araneaframework.core.RoutedMessage, which allows us to send a message to one specific component in the hierarchy as in the following example:

...
Message myEvent = new RoutedMessage("a.b.c") {
  public void execute(Component component) throws Exception {
    ((MyPersonalComponent) component).myMethod(...);
  }
}
myEvent.send(null, rootComponent);
...

This code will send the message to the specific component with path "a.b.c" and call myMethod() on it.

The handling of persistent state in Aranea is very simple. There are no scopes and every component state is saved until it is explicitly removed by its parent. This does not mean that all of the components are bound to the session, but rather that most components will live a period of time appropriate for them (e.g. framework components will live as long as the application lives, GUI components will live until user leaves them, and so on). This provides for a very flexible approach to persistence allowing not to clutter memory with unused components.

The end result is that typically one needs not worry about persistence at all, unless one is programming some framework plug-ins. All class fields (except in some cases transient fields) can be assumed to persist while the host object is live.

However such handling does not guarantee that the component state is anyhow synchronized. As a matter of fact most of the framework components outside the user session should be able to process concurrent calls and should take care of the synchronization themselves. However application components are typically synchronized by the framework. More information on the matter will follow in Section 2.7, “Application Widgets”.

InputData an OutputData both implement a way to extend their functionality without wrapping or extending the objects themselves. This is achieved by providing the following two methods:

void extend(Class interfaceClass, Object extension)
Object narrow(Class interfaceClass);

The following example should give an idea of applying these methods:

input.extend(FileUploadExtension.class, new FileUploadExtension(input));

...

FileUploadExtension fileUploadExt = 
  (FileUploadExtension) input.narrow(FileUploadExtension.class);
if (fileUploadExt.uploadSucceeded()) {
  //...
}

Although all of the core Aranea abstractions are independent of the Servlet API and web in general, we also provide a way to manipulate low-level HTTP constructs. To that goal we provide to interfaces, HttpInputData and HttpOutputData, which extend respectively InputData and OutputData.

Let's examine the HttpInputData. First of all it provides methods that are similar to the ones found in the HttpServletRequest:

However next methods are a bit different from the HttpServletRequest alternatives:

The interesting part here are the methods that deal with the path. The problem is that unlike most common cases Aranea components form a hierarchy. Therefore if a parent is mapped to path prefix "myPath/*" and its child is mapped to a path prefix "myChildPath/*" if the path handling were absolute the child would never get the mapped calls. This is due to the child being really mapped to the path "myPath/myChildPath". Therefore the parent must consume the prefix "myPath/" using method pushPathPrefix() and then the child will be correctly matched to the relative path "myChildPath".

HttpOutputData contains methods that are comparable to the ones found in HttpServletResponse:

One of the most common ways to use the services it to create a filter service, that wraps a child service and provides some additional functionality and/or environment entries. To that purpose Aranea provides a filter base class — org.araneaframework.framework.core.BaseFilterService. This class implements all of the Service methods, by default just delegating them to the corresponding child methods. A common thing to do is override the action() method to add functionality and getChildEnvironment() to add environment entries, as shown in the following example:

public class StandardSynchronizingFilterService 
  extends BaseFilterService {
  
  protected Environment getChildEnvironment() {
    return new StandardEnvironment(
        getEnvironment(), 
        SynchronizingContext.class, 
        new SynchronizingContext() {});
  }
  
  protected synchronized void action(
      Path path, 
      InputData input, 
      OutputData output) throws Exception {
    super.action(path, input, output);
  }
}

More information on services and other components that make up the framework can be found in Chapter 3, Framework and Configuration.

The default model of both widget and service rendering is that they render themselves. However, in most cases the widget might want to delegate the rendering to some templating language. In some other cases the widget might be rendered externally, without calling render() at all. Further on, we will describe these three cases in detail.

BaseApplicationWidget provides a number of methods for managing child widgets:

public abstract class BaseApplicationWidget ... {
  ...
  public void addWidget(Object key, Widget child);
  public void removeWidget(Object key);
  public void enableWidget(Object key);
  public void disableWidget(Object key);
  ...
}

As one can see, every added child has an identifier which should be unique among its siblings. This identifier is used when rendering and sending events to the widget in question, to identify it among its peers.

Typically, children are added when created:

addWidget("myChildWidget", new MyChildWidget("String parameter", 1));

An added child will be initialized, will receive updates and events and may be rendered. A widget can be active only if added to a parent. It will live as long as the parent, unless the parent explicitly removes it:

removeWidget("myChildWidget");

Removing a child widget will destroy it and one should also dispose of any references that may be pointing to it, to allow the child to be garbage collected.

A usual idiom is to save a reference to the newly created and added child using a parent widget field:

public class MyWidget extends BaseUIWidget {
  private MyChildWidget myChildWidget;
  
  protected void init() {
    myChildWidget = new MyWidget("String parameter", 1);
    addWidget("myChildWidget", myChildWidget);
  }
}

This allows to call directly child widget methods and does not anyhow significantly increase memory usage, so this technique may be used everywhere when needed.

Disabling a child (disableWidget("myChildWidget")) will stop it from receiving any events or rendering, but will not destroy it. It can later be reenabled by calling enableWidget("myChildWidget").

Registering event listeners allows widgets to subscribe to some specific user events (widget will receive only events specially sent to it). The distinction comes by the "event identifier" that is assigned to an event when sending it. The events are handled by the classes extending org.araneaframework.core.EventListener:

public interface EventListener extends Serializable {
  public void processEvent(Object eventId, InputData input) throws Exception;
}

The event listeners are registered as following:

addEventListener("myEvent", new EventListener() {
  public void processEvent(Object eventId, InputData input) throws Exception {
    log.debug("Received event: " + eventId);
  }
}

Of course, the event listener does not have to be an anonymous class and can just as well be an inner or even a usual public class. A standard base implementation org.araneaframework.core.StandardEventListener is provided that receives an optional String event parameter:

addEventListener("myEvent", new StandardEventListener() {
  public void processEvent(Object eventId, String eventParam, InputData input) throws Exception;
    log.debug("Received event " + eventId + " with parameter " + parameter);
  }
}

Another useful way to process events is to register a proxy event listener (org.araneaframework.core.ProxyEventListener) that will proxy the event to a method call, e.g.:

protected void init() {
  addEventListener("myEvent", new ProxyEventListener(this));
}

public void handleEventMyEvent(String parameter) {
    log.debug("Received event myEvent with parameter " + parameter);
}

The convention is that the proxy event listener translates an event "<event>" into a method call handleEvent<event> making the first letter of <event> uppercase. The "String parameter" is optional and can be omitted.

A useful feature is the method setGlobalEventListener(EventListener listener) that allows to register a listener that will receive all events sent to the widget. In fact BaseUIWidget does that by default, and typically you will use the individual event listeners only when you want to override this default behaviour. This allows to just define correct method names (handleEvent<event>) and all events will be translated to the calls to these methods. Certainly this can also be cancelled by calling clearGlobalEventListener(), or overridden by adding your own global event listener.

Registering action listeners allows widgets to subscribe to some specific user generated actions. Actions differ from events in that widget lifecycle execution for whole component tree is not triggered upon request—actions are just sent to the receiving widget's ActionListener, which is SOLELY responsible for generating the whole response. For rich UI components this allows a quick conversations with server, without requiring full form submits and generating whole view.

Every initialized widget has a reference to org.araneaframework.Environment available through the getEnvironment() method. Environment allows to look up framework services (called contexts):

MessageContext msgCtx = (MessageContext) getEnvironment().getEntry(MessageContext.class);
msgCtx.showInfoMessage("Hello world!");

As one can see from the examples, contexts are looked up using their interface Class object as key. All framework services in Aranea are accessible only using the environment.

To find out more about InputData and OutputData see Section 2.3.2, “Environment”

The main method that is typically overridden in a widget is init(). As widget does not get an environment before it is added and initialized it is impossible to access framework services in the constructor, therefore most of the initialization logic moves to the custom init() method. A dual overridable method is destroy(), though it is used much less.

In addition to event processing it is sometimes useful to do some kind of pre- and post-processing. The BaseApplicationWidget has the following methods that may be overridden to allow this processing:

protected void handleUpdate(InputData input) throws Exception {}
protected void handleProcess() throws Exception {}

handleUpdate() is called before event listeners are notified and allows to read and save request data preparing it for the event. More importantly, this method is called even when no event is sent to the current widget allowing one to submit some data to any widget. handleProcess() is called after the event listeners are notified and again is called event if current widgets receives no events at all. It allows to prepare the widget for rendering, post-processing the request results without concern whether or not events have been delivered.

In Aranea one usually does not need to handle request manually in custom application widgets. Even more, the request is not accessible by default. The usual way to submit custom data to a widget and read it is using Aranea Forms (see Chapter 5, Forms and Data Binding). However, when one needs to access the submitted data, one can do that using the org.araneaframework.InputData. This class can be used as follows:

...
String myData1 = 
  (String) getInputData().getScopedData().get("myData1");
String globalSubmittedParameter = 
  (String) getInputData().getGlobalData().get("globalSubmittedParameter");
...

getInputData() is a BaseApplicationWidget method that returns the input data for the current request (one can also use the input parameter given to event listener directly).

org.araneaframework.OutputData is accessible through the getOutputData() method of BaseWidget or directly as the output parameter passed to render() method.

To find out more about InputData and OutputData see Section 2.4, “InputData and OutputData”

BaseApplicationWidget also contains methods that facilitate transferring data to the presentation layer. This is achieved using a View model—an object containing a snapshot of the widget current state. The most typical way to use the view model it to add data to it:

...
putViewData("today", new Date());
putViewData("currentUser", userBean);
...

View data is typically accessible in the presentation layer as some kind of a variable (e.g. a JSP EL variable) for the current widget. If the data becomes outdated one can override it using putViewData() call or remove it using the removeViewData() call. In case one needs to put view data that would last one request only there is an alternative method:

...
putViewDataOnce("now", new Date());
...

Finally widget instance is also visible to the view, so one of the ways to make some data accessible is just to define a JavaBean style getter:

...
public Date getNow() {
  return new Date();
}
...

BaseUIWidget allows to render the current widget using a JSP page. To do that one needs to select a view as follows:

...
setViewSelector("myWidget/form");
...

This code makes the widget render itself using the JSP situated in WEB-INF/jsp/myWidget/form.jsp (of course the exact place is configurable). It is also possible to render the widget using other template technologies with the same view selector by overriding the render() method in the base project widget.

A typical application custom widget will look like that:

public class TestWidget extends BaseUIWidget {

  private static final Logger log = Logger.getLogger(TestWidget.class);
  
  private Data data;
  
  protected void init() throws Exception {
    //Sets the JSP for this widget to "/WEB-INF/jsp/home.jsp"
    setViewSelector("home");
    
    //Get data from the business layer
    data = ((TestService) lookupService("testService")).getData("test parameter");
    
    //Make the data accessible to the JSP for rendering
    putViewData("myData", data);    
  }
  
  /*
   * Event listener method that will process "test" event.
   */
  public void handleEventTest() throws Exception {
    getMessageCtx().showInfoMessage("Test event received successfully");       
  }
}

org.araneaframework.framework.MessageContext allows to show messages to the user. The messages can be of several types, including predefined error and informative types. Typically messages will be shown somewhere in the application (exact way is application-specific). MessageContext is available through a BaseUIWidget method getMessageCtx() and is typically used as follows:

getMessageCtx().showInfoMessage("Hello world!");

MessageContext divides messages by type (with predefined "info", "warning" and "error" types available) and life span (usual or permanent). Usual messages are shown to user once and then cleared, while permanent messages will be shown to user until explicitly cleared by the programmer:

For information on implementation of the MessageContext see Section 3.5.8, “User Messages Filter”.

org.araneaframework.framework.LocalizationContext allows to get and set current session locale, localize strings and messages, and lookup resource bundles. The context is available through the BaseUIWidget method getL10nCtx(). Typically it is used as follows:

...
String message = getL10nCtx().localize("my.message.key");
getMessageCtx().showInfoMessage(message);
...

LocalizationContext provides the following methods:

For information on implementation of the LocalizationContext see Section 8.1.2, “Spring Localization Filter”.

A common need in a web programming is to support navigation style known as flows—interactive stateful processes that can navigate to each other passing arguments when needed. A more complex case is when we also have flow nesting—a flow can call a subflow, and wait for it to finish, then reactivate again. In this case we can have at any given moment a stack of flows, where the top one is active, and the next one will reactivate when the top one finishes. It is also useful if nested flows can return resulting values when they finish.

Figure 2.2. Flow diagram

org.araneaframework.framework.FlowContext is the Aranea context that provides support for nested flow navigation. Aranea flow is a widget that is running in the flow container (using the FlowContext.start() method. Aranea abstraction for the nested state is that of a function—the nested flow takes in some parameters and when finished may return some value or signal that no value can be returned. The context is available as getFlowCtx() method of BaseUIWidget and allows to start flows, finish flows and return the resulting value.

To start a new flow one needs to create a widget as usual. The widget may take some parameters in the constructor—they are considered to be the incoming parameters of the flow:

...
getFlowCtx().start(new TestFlow(new Long(5)), null, null);
...

This call will start a new nested flow for the widget TestFlow making the current flow inactive. TestFlow will render and receive event until it explicitly returns control to the starting flow. Note that this code will start the flow and then return the control, so it is important not to do anything in the same method after starting a new flow.

To end the flow successfully one needs to do as follows:

...
getFlowCtx().finish(new Long(8));
...

This call will finish the current flow (in our case TestFlow) and return the control to the starting flow and its widget.

Often one needs to handle the return from the flow, processing the returned result. This corresponds to our abstraction of a method, however since Java does not support continuations we chose to allow the caller to register a handler when starting the flow by passing a FlowContext.Handler:

...
getFlowCtx().start(new TestFlow(new Long(5)), null, 
  new FlowContext.Handler() {
    public void onFinish(Object result) {
      getMessageCtx().showInfoMessage("TestFlow returned value " + result);
    }
    public void onCancel() {
      //Ignore cancelled flow
    }
  });
...

A less common but nevertheless useful feature is to configure the starting flow after it has been initialized. For that the caller needs to pass a FlowContext.Configurator:

...
getFlowCtx().start(new TestFlow(new Long(5)), 
  new FlowContext.Configurator() {
     public void configure(Component comp) {
      ((TestFlow) comp).setStrategy(TestFlow.ATTACK);
     }
  }, null);
...

Finally FlowContext also allows to replace the current flow instead of deactivating it by using the replace() method and to cancel the current flow by using the cancel() method.

For standard implementation, please see Section 3.5.19, “Root Flow Container”

The simplest way to configure Aranea for a web application is to set the araneaApplicationStart init parameter of the dispatcher servlet to the starting widget or flow of the application:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC 
  "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
  "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
  <listener>
    <listener-class>
      org.araneaframework.http.core.StandardSessionListener
    </listener-class>
  </listener>
   
   <servlet>
      <servlet-name>araneaServlet</servlet-name>
      <servlet-class>
        org.araneaframework.integration.spring.AraneaSpringDispatcherServlet
      </servlet-class>
      <init-param>
        <param-name>araneaApplicationStart</param-name>
        <param-value>example.StartWidget</param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
   </servlet>
   
   <servlet-mapping>
      <servlet-name>araneaServlet</servlet-name>
      <url-pattern>/main/*</url-pattern>
   </servlet-mapping>  
</web-app>

This configuration will load Aranea using example.StartWidget as the application starting point.

Aranea can also be configured using a Spring configuration file located in /WEB-INF/aranea-conf.xml. Particularly it may be used to set the starting widget instead of the init-parameter:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" 
  "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>   
    <bean id="araneaApplicationStart" 
      class="example.StartWidget"
      singleton="false"/>
</beans>

This seems to be more verbose, but it also allows to configure the framework components as described in Section 3.4, “Framework Configuration”.

Aranea also takes into account a property file located in /WEB-INF/aranea-conf.properties. The following properties are recognized:

AraneaSpringDispatcherServlet provides a number of init-params that allow to further customize Aranea configuration:

Currently, the most common way to put Aranea to work is to host it in a Servlet 2.3 or compatible container. The most generic way to do that is to extend the org.araneaframework.http.core.BaseAraneaDispatcherServlet and build the root component of type org.araneaframework.http.ServletServiceAdapterComponent in the overrided method buildRootComponent():

package com.foobar.myapp;

class MyServlet extends BaseAraneaDispatcherServlet {
   protected ServletServiceAdapterComponent buildRootComponent() {
     StandardServletServiceAdapterComponent root = new StandardServletServiceAdapterComponent();

     //Configure the child components, service widgets using setter injection
     //...

     return root;
   }
}

And one can then use such a servlet to configure Aranea in a web application as usually replacing the standard dispatcher servlet with our custom one.

Provides localization services to children. See Section 2.8.2, “LocalizationContext”.

When serving AJAX requests made with AjaxAnywhere (see Section 9.1.2, “AjaxAnywhere (http://ajaxanywhere.sourceforge.net/)”), extracts from the initial response these page regions that need to be updated (request includes the names of these regions), then modifies the response to include just these regions (not the whole page).

Filter widget that enriches children environment with specified context entries.

Catches the exceptions (if any) occuring while executing children methods; passes the exceptions on to Service that deals with exception handling (obtained from ExceptionHandlerFactory).

Enriches child environment with FileUploadContext (which is just a marker interface). When incoming request is multi-part request, children's InputData is extended with FileUploadInputExtension that allows children easy access to uploaded files.

Filter that sets necessay headers of the response.

Provides JSP specific information to children.

See Section 2.8.1, “MessageContext”.

Provides methods for opening new session-threads and renders these in different browser windows at client-side.

Serializes the the session during the request routing. This filter helps to be aware of serializing issues during development as when the session does not serialize, exception is always thrown. In production configuration, this filter should never be enabled, thus it is disabled by default.

Filter that logs the time it takes for the child service to serve the request (complete its action method).

Synchronizes the calls to its child widget. Enriches environment with SynchronizingContext (which is just marker interface).

Implementation of a service that clones currently running session thread upon request and sends a response that redirects to cloned session thread. It can be used to support "open link in new window" feature in browsers. Cloning is generic and resource demanding, as whole tree of session thread components is recreated. Custom applications may find that they can implement some application specific cloning strategy that demands less memory and processing power.

TransactionContext implementation that filters routing of duplicate requests. The detection of duplicate requests is achieved through defining new transaction ID in each response and checking that next request submits the consistent transaction ID. Missing (null) transaction ID is always considered inconsistent. For purposes of asynchronous requests, override transaction ID is always considered consistent.

This filter allows to reload the underlying object classes dynamically. This means that you can just change the widget source file, compile it (e.g. with IDE built-in compiler) and it will be reloaded seamlessly in Aranea. This will apply only to Aranea widget classes under this filter and the classes they contain (but not e.g. Spring beans). This filter must be registered instead of the araneaApplicationStart to function.

This filter will serialize the state of underlying widgets onto client-side. This significantly decreases the server-side session size and thus memory use. It is especially useful in intranet applications with lots of spare bandwidth. The filter should be positioned as the first custom widget filter for most gain.

This filter is responsible for providing a virtual file system so that extensions could make use of the resources included in .JAR files. See Section 3.6.1, “Extension Resources”

Implementation of a service that allows to "mount" flow components to a publicly accessible URL. It is used when it is needed that some (read-only) parts of application are accessible to users who are not able to enter the session-based conversation with application.

See Section 2.8.3, “FlowContext” for purpose and philosophy behind FlowContext. RootFlowContext is same as FlowContext, but allows to acces the root flow container at any time.

External resources, such as javascript, style and image files of Aranea components are managed through different configuration files. The resources are listed in XML files and can be accessed through StandardFileImportFilterService. This approach makes it possible to package all the resources into the aranea jar archives and no manual copying of necessary files to fixed locations is needed.

Aranea comes bundled with a aranea-resources.xml file which defines all the external resources.

<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <files content-type="text/css" group="defaultStyles">
    <file path="styles/_styles_global.css"/>
    ...
    <file path="styles/_styles_screen.css"/>
  </files>

  <files content-type="image/gif">
    <file path="gfx/i01.gif"/>
    ...
    <file path="gfx/i02.gif"/>
  </files>
  ...
</resources>

All the files listed in the configuration files are allowed to be loaded through the FileImportFilter. Some are grouped by name to provide an easy access for reading files in bulk.

To override specific files in the configuration file, the new file should be placed in a subdirectory override. When loading a file, Aranea first trys to open the file in the override directory and on failure trys to read the file without the prefix directory.

To add files to the defined list, construct a configuration file and name it aranea-resources.xml. All such configuration files from the classpath are parsed for the resources. If two file groups are defined with the same name, the group is formed by taking a union from the files in the group.

Groupnames defaultStyles and defaultScripts are predefined groups for managing the necessary core files that must be included for Aranea to work correctly.

For custom loading a resource, the URL to use is /fileimporter/filepath. The fileimporter is StandardFileImportFilterService.FILE_IMPORTER_NAME and filepath is the path that is defined for the file in the resource configuration file.

Extensions of the framework provide their own configuration files for configuring their resources. New extensions cannot be defined right now on the fly.

This tag should always be the root of any Aranea template JSP. Its main function is to allow JSP access the controller.

This tag should be immediately under the <ui:root> tag for any application that uses widgets. It allows widgets to be rendered and included.

Aranea comes bundled with different external resources: javascript libraries, stylesheets and images. To automate the process of loading the javascript files without the manual copying of them to specific webapp locations, a special filter is used. The filter is able to read files from aranea jar files.

<ui:importScripts> depends on the filter StandardServletFileImportFilterService being set. The filter provides the functionality of reading files from the jars on the server.

If no attributes specified, the default group of javascript files are loaded.

<?xml version="1.0" encoding="UTF-8"?>
<ui:importScripts/> <!-- imports files from 'defaultScripts' group -->
<ui:importScripts group="debugScripts"/> <!-- imports additional debug scripts (js logger) -->

Aranea comes bundled with CSS files to provide custom look for different predefined components (the template app, calendar, htmleditor, etc.). Just as with javascript, to use them one would have to extract them from the jars and use them just like any other css file would be used. To automate this process with aranea css files one can use the <ui:importStyles> tag to include the css files automatically.

<ui:importStyles> depends on the filter StandardServletFileImportFilterService being set. The filter provides the functionality of reading files from the jars on the server.

If no attributes specified, the default group of css files are loaded.

This tag will render an HTML <body> tag with Aranea JSP specific onload and onunload events attached. It usually writes out some other page initialization scripts too, depending on the circumstances.

This tag will render an HTML <form> tag along with some Aranea-specific hidden fields. When making custom web applications it is strongly suggested to have only one system form in the template and have it submit using POST. This will ensure that no matter what user does no data is ever lost. However Aranea does not impose this idiom and one may just as well submit using GET, define system forms in widgets and use usual HTML links instead of JavaScript. See Section 4.2, “System Tags” for usage example.

This tag will render messages of given type if they are present in current MessageContext. When type is not specified, all types of messages are rendered. As MessageContext is typically used for error messages, it is common to render these messages somewhere near top of the page, where they can easily be spotted.

<?xml version="1.0" encoding="UTF-8"?>
...
<ui:messages type="info"/>
<ui:messages type="error" styleClass="custom-error-message-class"/>
<ui:messages/>
...

Defines an attribute of the containing element, where possible. See also Section 4.3.3, “<ui:element>”. Most form element tags accept attributes set by this tag too, see the section called “Examples”.

<?xml version="1.0" encoding="UTF-8"?>
...
  <!-- set the onkeypress attribute for HTML input produced by ui:textInput-->
  <ui:textInput>
    <ui:attribute name="onkeypress" value="upperCase(this);"/>
  </ui:textInput>
...

Defines an HTML element content, meaning the body of the HTML element where text and other tags go.

Defines HTML node, can be used together with <ui:attribute> and <ui:elementContent> to define a full HTML node.

<?xml version="1.0" encoding="UTF-8"?>
<ui:element name="span">
  <ui:attribute name="class" value="fancy"/>
  <ui:elementContent>Contents of fancy span.</ui:elementContent>
</ui:element>

Registers a simple javascript keyboard handler.

function(event, elementId) { alert(elementId); }

<!-- Globally-scoped F2 listener -->
<ui:keyboardHandler 
  scope="" 
  key="f2" 
  handler="function() { alert('You pressed F2. Do it again if you dare!');}"/>

Registers a 'server-side' keyboard handler that sends an event to the specified widget.

<!-- F2 listener that sends event 'add' to context widget upon activation -->
<ui:eventKeyboardHandler eventId="add" key="f2" widgetId="${widgetId}"/>

This tag should generally be the root of every widget JSP. It makes the widget view model accessible as an EL variable. It can also be used to render a descendant widget in the same JSP with the current widget. In the latter case you should set the id attribute to the identifier path of the descendant widget in question. Note that all widget-related tags inside of this tag will assume that the widget in question is their parent or ancestor (that is all the identifier paths will start from it).

<?xml version="1.0" encoding="UTF-8"?>
...
  <ui:widgetContext>
    ...
    <c:out value="${viewData.myMessage}"/>
    ...
  </ui:widgetContext>
...

<?xml version="1.0" encoding="UTF-8"?>
...
  <ui:widgetContext>
    ...
    <ui:widgetContext id="child.ofMyChild">
      <c:out value="${viewData.messageFromChildOfMyChild}"
    </ui:widgetContext>
    ...
  </ui:widgetContext>
...

This tag is used when one needs to render a child or descendant widget while still retaining in both current widget context and JSP. It publishes the widget view model and full identifier as EL variables, but does little else and does not setup a widget context (e.g. <ui:widgetInclude> tag will not take it into account).

<?xml version="1.0" encoding="UTF-8"?>
...
  <ui:widgetContext>
    ...
    <ui:widget id="child.ofMyChild">
      <c:out value="${viewData.messageFromChildOfMyChild}"
          <ui:widgetInclude id="child"/>
    </ui:widget>
    ...
  </ui:widgetContext>
...

This tag is used to render some child or descendant widget. It will call the widget's render() method, which will allow the target widget to choose how to render itself.

<?xml version="1.0" encoding="UTF-8"?>
...
  <ui:widgetContext>
    ...
    <ui:widgetInclude id="child.ofMyChild"/>
    ...
  </ui:widgetContext>
...

These tags will render a button (or a link) that when clicked will send a specified event to the target widget with an optional String parameter.

<?xml version="1.0" encoding="UTF-8"?>
...
  <ui:widgetContext>
    ...
    <ui:eventButton eventId="test" eventParam="${bean.id}"/>
    <ui:eventLinkButton eventId="edit" eventParam="${bean.id}">
      <img src="editButton.png"/>
    </ui:eventLinkButton>
    ...
  </ui:widgetContext>
...

This tag will register events that are executed when HTML page body has completely loaded. This tag can be used multiple times, all specified events will be added to event queue and executed in order of addition.

<?xml version="1.0" encoding="UTF-8"?>
...
    <ui:onLoadEvent event="activateFlashLights();"/>
    <ui:onLoadEvent event="changeMenuBackGroundColor();"/>
...

This tag checks presence of server-side session-threads that represent popups and adds system loadevent for opening them in new browser window at client-side. For tag to have an effect, HTML page BODY tag must have attribute onload event set to AraneaPage (See Aranea Clientside Javascript) onload event. Also, this tag only works inside <ui:systemForm> tag.

<?xml version="1.0" encoding="UTF-8"?>
...
<ui:body>
  <ui:systemForm method="POST">
    <ui:registerPopups/>
  </ui:systemForm>
</ui:body>
...

The following predefined entities also accept the count attribute. It defines the number of times to repeat the entity.

Represents a layout. Layouts allow to describe the way content will be placed on the page.

Represents a row in layout.

Represents a cell in layout.

<?xml version="1.0" encoding="UTF-8"?>
...
  <ui:layout rowClasses="even,odd" cellClasses="one,two,three,four">
    <ui:row>
      <ui:cell>
         <!-- cell content -->
      </ui:cell>
    </ui:row>
  </ui:layout>
...

These two tags define the update regions in the output that can be updated via AJAX requests. The update regions chosen to be updated when some event occurs is decided by tags that take the updateRegion attribute (See Section 5.2.1, “Common attributes for all form element rendering tags.”).

The <ui:updateRegion> should be used when defining updateregion when the region is not contained in HTML table (layout). The <ui:updateRegionRows> is for defining a region which is contained in HTML table and contains table rows itself. Updating just cells is not possible.

Either id or globalId attribute is required.

<?xml version="1.0" encoding="UTF-8"?>
<!-- First update region, placed outside HTML table -->
<ui:updateRegion id="outsideTable">
</ui:updateRegion>

<ui:layout>
  <!-- Second update region, placed inside HTML table -->
  <ui:updateRegionRows id="insideTable"/>
    <ui:row>
      ...
    </ui:row>
  </ui:updateRegionRows>
</ui:layout>

<!-- Button that makes a background submit of specified event. 
     When response arrives specified updateregions are updated -->
<ui:eventButton id="test" updateRegions="outsideTable,insideTable"/>

Acts as the HTML <b> tag.

Acts as <i> HTML tag.

Acts as <font> HTML tag.

Sets a CSS class for the tag content, acts as a <span> HTML tag with the class atribute set.

Puts a visual new line (<br/>).

Represents an HTML form button.

Represents a link with an onClick JavaScript action.

Usual HTML link, acts as a <a> HTML tag.

Custom tags should extend at least org.araneaframework.jsp.tag.BaseTag that provides methods for registering subtags, manipulation of pagecontext and attribute evaluation.

import java.io.Writer;
import org.araneaframework.jsp.tag.entity.NbspEntityHtmlTag;
import org.araneaframework.jsp.util.JspUtil;

public class DummyTag extends BaseTag {
  public static String KEY = "org.araneaframework.jsp.tag.DummyTag";
  
  BaseTag subTag;
  
  @Override
  protected int doStartTag(Writer out) throws Exception {
    int result = super.doStartTag(out);

    // make this tag implementation accessible to subtags which 
    // is quite pointless since this tag does not implement any useful interface.
    // it demonstrates Aranea JSP convention for providing info to subtags
    addContextEntry(KEY, this);
    
    // write some real output that ends up at the served web page
    JspUtil.writeOpenStartTag(out, "div");
    JspUtil.writeAttribute(out, "id", "dummyDivId");
    JspUtil.writeCloseStartTag(out);
    
    // it is possible to register in JAVA code too, this one just writes out nbsp entity.
    subTag = new NbspEntityHtmlTag();
    registerSubtag(subTag);
    executeStartSubtag(subTag);
    
    return result;
  }

  @Override
  protected int doEndTag(Writer out) throws Exception {
    executeEndTagAndUnregister(subTag);
    
    JspUtil.writeEndTag(out, "div");
    
    return super.doEndTag(out);
    // Now everything about this tag ceases to exist, 
    // context entries are removed, souls are purged.
  }
}

org.araneaframework.jsp.util.JspUtil that was used here is an utility class containing some functions for writing out (XML) tags with somewhat less room for errors than just out.write(). Other notable methods provided by BaseTag are getOutputData() that returns response data, getConfiguration() and getLocalizationContext(). For tags with attributes, attribute evaluation functions that support Expression Language (EL) expressions are provided in BaseTag. Typical usage of these functions is following:

public void setWidth(String width) throws JspException {
  this.width = (String)evaluate("width", width, String.class);
}

Another common base tag for tags that output real HTML is org.araneaframework.jsp.PresentationTag. The DummyTag should really extend it too, since it outputs some HTML. PresentationTag defines style and styleClass attributes that can be applied to most HTML tags.

Important tag cleanup method is doFinally() that is called after rendering. It should be used to clear references to objects that should no longer be referenced after rendering. As in containers tag instances can live very long time, they can leak quite a lot of memory unless resources are deallocated.

Custom tags extending Aranea tags are able to accept all supertag attributes, but these must be also defined in TLD, otherwise the JSP containers will complain. As some base tags may be abstract, information about their attributes cannot be deduced from Aranea JSP standard TLD. To address this problem, Aranea distribution does the following: aranea.jar and aranea-jsp.jar include the file META-INF/aranea-standard.tcd (TCD stands for Tag Class Descriptor) which includes the attribute information for all Aranea Standard JSP classes. To make use of this information, one first generates TLD for custom tag classes and then merges the TCD information into it. It is done with org.araneaframework.buildutil.TcdAndTldMerger utility included in aranea.jar (since 1.0.10, previously it had to be compiled separately after downloading distribution). All custom compiled tag classes as well as Aranea JSP tag classes must be available on classpath when using this utility.

Example of using the TcdAndTldMerger utility:

<target name="tld">
  <!-- generate TLD without parent attribute information -->
  <webdoclet destdir="somedir" force="false" >
    <fileset dir="${src.dir}" includes="**/*Tag.java"/>

    <jsptaglib validatexml="true"
      shortName="shortName"
      filename="filename.tld"
      uri="customuri"
      description="description"
    />
  </webdoclet>

  <!-- invoke the TcdAndTldMerger utility -->
  <java classname="org.araneaframework.buildutil.TcdAndTldMerger" fork="true">
    <arg value="META-INF/aranea-standard.tcd"/>    <!-- Tag class descriptor to merge with -->
    <arg value="somedir/filename.tld"/>            <!-- Source TLD -->
    <arg value="somedir/filename.tld"/>            <!-- Destination TLD -->
    <classpath>
    <path refid="araneaclasspath"/>
      <path refid="compiledcustomtagclasses"/>
      <path refid="varia">
    </classpath>
  </java>

</target>

When running given target, one should see messages similar to following:

8 attributes for 'custom.RandomTag' found from 'org.araneaframework.jsp.tag.presentation.PresentationTag'.

Sending events to widgets is accomplished with javascript submit functions, helpful utility being org.araneaframework.jsp.util.JspUtil and org.araneaframework.jsp.util.JspWidgetCallUtil. First one would construct org.araneaframework.jsp.UiEvent and (in case of HTML element which receives only one event) calls JspUtil.writeEventAttributes(Writer out, UiEvent event) and afterwards writeSubmitScriptForEvent(Writer out, String attributeName).

//public UiEvent(String eventId, String eventTargetWidget, String eventParameter)
UiEvent event = new UiEvent("hello", "contextWidgetId", "name");
// long way to ouput custom attributes version
JspUtil.writeEventAttributes(out, event);
JspWidgetCallUtil.writeSubmitScriptForEvent(out, attributeName);
// short version
JspWidgetCallUtil.writeSubmitScriptForEvent(out, "onclick", event);

// both will output something like this:
    // arn-evntId="hello" 
    // arn-trgtwdgt="contextWidgetId" 
    // arn-evntPar="name" 
    // onclick="return _ap.event(this);"

New layouts are mostly concerned with styles or render layouts with some additional tags instead plain table, tr, td. As simple example, we define a layout that applies a class "error" to cells which contain invalid FormElement. Note that approach we use only works when cell tag is aware of the surrounding FormElement at the moment of rendering, meaning that FormElement is rendered in JSP something like this:

<?xml version="1.0" encoding="UTF-8"?>
...
<ui:formElement id="someId">
    <ui:cell>
        <ui:label/>
    </ui:cell>

    <ui:cell>
        <ui:textInput/>
    </ui:cell>
</ui:formElement>
...

What is needed foremost is a decorator for cells that are used inside invalid FormElement.

public class ErrorMarkingCellClassProviderDecorator implements CellClassProvider {
  protected CellClassProvider superProvider;
  protected PageContext pageContext;

  // constructs a decorator for superProvider, makes pageContext accessible
  public ErrorMarkingCellClassProviderDecorator(CellClassProvider superProvider, PageContext pageContext) {
    this.superProvider = superProvider;
    this.pageContext = pageContext;
  }

  public String getCellClass() throws JspException {
    FormElement.ViewModel formElementViewModel = (FormElement.ViewModel)
      pageContext.getAttribute(FormElementTag.VIEW_MODEL_KEY, PageContext.REQUEST_SCOPE);
    // superProvider.getCellClass() may only be called once, otherwise moves on to next cell's style
    String superClass = superProvider.getCellClass();

    if (formElementViewModel != null && !formElementViewModel.isValid()) {
      if (superClass != null)
        return superClass + " error";
      else
        return "error";
    }

    return superClass;
  }
}

Actual layout tag that decorates its cells according to described logic:

public class CustomLayoutTag extends LayoutHtmlTag {
  protected int doStartTag(Writer out) throws Exception {
    int result = super.doStartTag(out);
    addContextEntry(CellClassProvider.KEY, new ErrorMarkingCellClassProviderDecorator(this, pageContext));

    return result;
  }
}

Let's say we have a Person model JavaBean that looks like this:

public class Person {
  private Long id;
  private String name;
  private String surname;   
  private String phone;

  public Long getId() {return id;}
  public void setId(Long id) {this.id = id;}
  
  public String getName() {return name;}
  public void setName(String name) {this.name = name;}
  
  public String getSurname() {return surname;}
  public void setSurname(String surname) {this.surname = surname;}
  
  public String getPhone() {return phone;}
  public void setPhone(String phone) {this.phone = phone;}
}

A typical form will be created and used like this:

...
private BeanFormWidget personForm;
private Person person;
...
protected void init() {
  ...
  personForm = new BeanFormWidget(Person.class);
  addWidget("personForm", personForm);

  personForm.addBeanElement("name", "#Name", new TextControl(new Long(3), null), true);
  personForm.addBeanElement("surname", "#Last name", new TextControl(), true);
  personForm.addBeanElement("phone", "#Phone no", new TextControl(), true);
  ...
  person = lookupPersonService().getSomePerson();
  personForm.readFromBean(person);
  ...
}
...

Note that here we basically do three things:

Now that we have created the form we show how to process events, validate and read the request data. The following example code should be in the same widget as the previous:

...
private void handleEventSave() {
  if (personForm.convertAndValidate()) {
   personForm.writeToBean(person);
   ...
   lookupPersonService()().savePerson(person);
  }
}
...

This code will execute if an event "save" comes and will do the following:

Note the use of the getValueByFullName() method. Form API contains several such methods (named *ByFullName()), which allow to access fields, controls and values using full dot-separated element names.

If you have a composite JavaBean (containing other JavaBeans) you may want to create a form with a similar structure. Let's say that our Person bean contains an Address under "address" JavaBean property:

...
personForm = new BeanFormWidget(Person.class);
addWidget("personForm", personForm);
...
BeanFormWidget addrForm = personForm.addBeanSubForm("address");
addrForm.addBeanElement("postalCode", "#Postal code", new TextControl(), true);
addrForm.addBeanElement("street", "#Street", new TextControl(), true);
...

Note that the fields will be available from the main form using a dot-separated name, e.g. String street = (String) personForm.getValueByFullName("address.street").

At the core of the data binding API lies the notion of controls (org.araneaframework.uilib.form.Control). Controls are the widgets that do the actual parsing of the request parameters and correspond to the controls found in HTML forms, like textbox, textarea, selectbox, button, ... Additionally controls also do a bit of validating the submitted data. For example textbox control validates the minimum and maximum string length, since the HTML tag can do the same. Programmer usually does not read values from Control directly, but from FormElement that takes care of converting value of Control to FormElement Data.

The following example shows how to create a control:

...
TextControl textBox = new TextControl(new Long(10), null);
...

This code will create a textbox with a minimal length of 10. Note that this code does not yet put the control to work, as controls are never used without forms, which are reviewed in the next section.

Follows a table of standard controls all found in org.araneaframework.uilib.form.control package:

SelectControl and MultiSelectControl deserve a special mention, as they need a bit more handling than the rest. The difference comes from the fact that we also need to handle the selectable options, which we refer to as DisplayItem. Each DisplayItem has a label, a string value and can be disabled. Disabled display items cannot be selected in neither select box nor multiselect box.

Both SelectControl and MultiSelectControl implement the DisplayItemContainer interface that allows to manipulate the DisplayItem:

interface DisplayItemContainer {
  void addItem(DisplayItem item);
  void addItems(Collection items);
  void clearItems();
  List getDisplayItems();
  int getValueIndex(String value);
}

In addition to this interface we also provide a DisplayItemUtil that provides some support methods on display items. These include the method addItemsFromBeanCollection that allows to add the items to a (multi)select control from a business method returning a collection of model JavaBean objects (which is one of the most common use cases). So a typical select control will be filled as follows:

SelectControl control = new SelectControl();
control.addItem(new DisplayItem(null, "- choice -"));
DisplayItemUtil.addItemsFromBeanCollection(
  control,
  lookupMyService().getMyItemCollection(),
  "value",
  "label");

Controls can also listen to user events. For example ButtonControl can react to an onClick event, while most others can react to an onChange event. The only thing needed to receive the control events is to register an appropriate event listener:

...
SelectControl selControl = new SelectControl();
FormElement selEl = form.addBeanElement("clientId", "#Client id", selControl, true);
selControl.addOnChangeEventListener(new OnChangeEventListener() {
  public void onChange() {
    //We convert and validate one element only as the rest of the form
    //might be invalid
    if (selEl.convertAndValidate()) {
      Long clientId = (Long) selEl.getValue();
      //Now we can use the client id to do whatever we want
      //E.g. update another select control
    }
  }
});
...

onChange events are also produced by text boxes and similar, so the user input can processed right after the user has finished it.

Though controls provide some amount of validation they are limited only to the rules that can be controlled on the client-side. To support more diverse rules Aranea has org.araneaframework.uilib.form.Constraint, that allows to put any logical and/or business validation rules. Typically constraints are used as follows:

...
myForm.addBeanElement("registration", "#Registration", new DateControl(), true);
myForm.getElement("registration").setConstraint(new AfterTodayConstraint(false));
...

The org.araneaframework.uilib.form.constraint.AfterTodayConstraint makes sure that the date is today or later, with the boolean parameter indicating whether today is allowed. The constraint will validate if the form or the element in question is validated (e.g. convertAndValidate() is called) and will show an error message to the user, if the constraint was not satisfied. The error message is customizable using localization and involves the label of the field being validated.

The following is a more complex example that shows how to use constraints that apply to more than one field, and how to combine constraints using logical expressions:

...
searchForm = new FormWidget();

//Adding form controls
searchForm.addElement("clientFirstName", "#Client first name", 
  new TextControl(), new StringData(), false);
searchForm.addElement("clientLastName", "#Client last name", 
  new TextControl(), new StringData(), false);

searchForm.addElement("clientAddressTown", "#Town", 
  new TextControl(), new StringData(), false);
searchForm.addElement("clientAddressStreet", "#Street", 
  new TextControl(), new StringData(), false);

//First searching scenario
AndConstraint clientNameConstraint = new AndConstraint();
clientNameConstraint.addConstraint(
  new NotEmptyConstraint(searchForm.getElementByFullName("clientFirstName")));
clientNameConstraint.addConstraint(
  new NotEmptyConstraint(searchForm.getElementByFullName("clientLastName")));

//Second searching scenario
AndConstraint clientAddressConstraint = new AndConstraint();
clientAddressConstraint.addConstraint(
  new NotEmptyConstraint(searchForm.getElementByFullName("clientAddressTown")));
clientAddressConstraint.addConstraint(
  new NotEmptyConstraint(searchForm.getElementByFullName("clientAddressStreet")));

//Combining scenarios
OrConstraint searchConstraint = new OrConstraint();    
searchConstraint.addConstraint(clientNameConstraint);
searchConstraint.addConstraint(clientAddressConstraint);

//Setting custom error message
searchConstraint.setCustomErrorMessage("Not enough data for search!");

//Setting constraint
searchForm.setConstraint(searchConstraint);

//Putting the widget
addWidget("searchForm", searchForm);    
...

The example use case is a two scenario search—either both client first name and client last name fields are filled in or both town and street address fields are filled in, otherwise an error message "Not enough data for search!" is shown. The constraints will be validated when convertAndValidate() method is called on searchForm. Note that the constraint is added to the form itself, rather than to its elements—this is a typical idiom, when the constraint involves several elements.

Table of standard Constraints.

There are two constraints that deserve a special mention. One of them is OptionalConstraint that will only let its subconstraint to validate the field, if the field has been submitted by user (it is very useful for instance when non-mandatory fields must nevertheless follow some pattern, whereas empty input should still be allowed).

The other constraint is called GroupedConstraint. It is useful in cases when different constraints should be activated depending on the particular state of the component (a typical use case is that some groups of fields are made mandatory in different states of document approval). The constraint is created using the ConstraintGroupHelper as follows:

...
ConstraintGroupHelper groupHelper = new ConstraintGroupHelper();
AndConstraint andCon = new AndConstraint();
andCon.addConstraint(
  groupHelper.createGroupedConstraint(new NotEmptyConstraint(field1), "group1"));
andCon.addConstraint(
  groupHelper.createGroupedConstraint(new NotEmptyConstraint(field2), "group1"));
andCon.addConstraint(
  groupHelper.createGroupedConstraint(new NotEmptyConstraint(field3), "group2"));
andCon.addConstraint(
  groupHelper.createGroupedConstraint(new NotEmptyConstraint(field4), "group2"));
form.setConstraint(andCon);

//Now only field1 and field2 will be required from user!
groupHelper.setActiveGroup("group1");
...

...
public class PersonIdentifierConstraint extends BaseFieldConstraint {
  public void validateConstraint() {
    if (!PersonUtil.validateIdentifier(getValue()) {
      addError("Field '" + getLabel() + "' is not a valid personal identifier");
    }
  }
}
...

The typical use of forms includes associating the form fields with JavaBean properties. However this is not always possible, since it is not feasible to make a JavaBean property for each and every form field. In such cases one may still want to use type conversion and data validation. To do that forms allow the org.araneaframework.uilib.form.Data and its subclasses (subclasses correspond to specific types) to be associated with the field:

...
personForm = new BeanFormWidget(Person.class);
addWidget("personForm", personForm);
...
personForm.addElement("numberOfChildren", "#No. of chidren",
  new NumberControl(), new LongData(), true);
...

In such a case one can retrieve the data directly from the field:

...
private void handleEventSave() {
  if (myForm.convertAndValidate()) {
    ...
    Long numberOfChildren = (Long) personForm.getValueByFullName("numberOfChildren");
    //Alternative:
    //FormElement nocEl = (FormElement) personForm.getElement("numberOfChildren");
    //Long numberOfChildren = (Long) nocEl.getValue();
    ...
  }
}
...

If there is no JavaBean to associate the form with org.araneaframework.uilib.form.FormWidget may be used instead of BeanFormWidget.

Note that the reason for existence of Data objects is that Java types correspond poorly to some restricted types—for instance enumerations, type encodings and collections container types (this problem is somewhat solved in Java 5, but Aranea is compatible with Java 1.3).

Table of Data types.

Finally Data constructor also accepts both a Class instance and a simple string. So if you have a custom datatype with an appropriate converter (see next section) you can just assign the data with the same type (in fact if you have your own converter the type doesn't matter that much, it will just allow some checks to be done on the programmer).

Converter sole purpose is conversion of values with one type to values of another type. Conventionally converter which convert() method accepts object of type A and returns object of type B is named AToBConverter. Converter from type B to type A is obtained with new ReverseConverter(new AToBConverter()).

public interface Converter extends Serializable, FormElementAware {
    public void setFormElementCtx(FormElementContext feCtx);
    public Object convert(Object data);
    public Object reverseConvert(Object data);
    public Converter newConverter();
}

Converters are used internally to convert Control values to values of FormElement Data and vice-versa. Converters are usually looked up from ConverterFactory, but each FormElement can be set explicit Converter by calling FormElement.setConverter(). Direction of Converter set this way should be from FormElement Control value type to FormElement Data type.

Specifies form context for inner tags. Form view model and id are made accessible to inner tags as EL variables.

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    ...  <!-- formElements, formElementLabels, ... --> ...
</ui:form>

Specifies form element context for inner tags. Must be surrounded by <ui:form> tag. Form element view model, id and value are made accessible to inner tags as EL variables.

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    <ui:formElement id="username">
        ...
    </ui:formElement>
</ui:form>

Renders localizable label bound to form element. Rendered with HTML <span> and <label> tags.

<?xml version="1.0" encoding="UTF-8"?>
<ui:form id="loginForm">
    <ui:row>
        <ui:formElement id="username">
            <ui:cell>
                <ui:label/>
            </ui:cell>
        </ui:formElement>
    </ui:row>
</ui:form>

Renders localizable label (with HTML <span> and <label> tags).