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;
   }
}

One can then use such a servlet to configure Aranea in a web application as by replacing the standard dispatcher servlet with the custom one in WEB-INF/web.xml.

Aranea also provides a central way to configure some settings that affect the way some components work or display data. These settings are stored in a Map, where the key names are defined in the org.araneaframework.uilib.ConfigurationContext interface.

The ConfigurationContext is accessible from the Environment or by the getConfiguration() method of BaseUIWidget.

Every application may provide their own values for settings by implementing their version of the ConfigurationContext like following:

public class CustomConfiguration implements ConfigurationContext {

  private Map configuration = new HashMap();

  public CustomConfiguration() {
    // Note that these constants are defined by the ConfigurationContext.
    configuration.put(CUSTOM_DATE_FORMAT, "dd.MM.yyyy|d.M.yyyy");
    configuration.put(CUSTOM_TIME_FORMAT, "HH:mm");
    configuration.put(FULL_LIST_ITEMS_ON_PAGE, new Long(20));
  }

  public Object getEntry(String entryName) {
    return configuration.get(entryName);
  }

}

For more information on the settings that can be changed, please see the ConfigurationContext interface in the Aranea API.

To make Aranea use the custom-created configuration, the class must be defined in aranea-conf.xml file like this:

<bean id="araneaConfiguration"
    class="com.company.conf.CustomConfiguration" singleton="false" />

Note that it is defined as not being a singleton. This means that the configuration is created for every context (user). Therefore, the settings can be further customized to be more user specific.

To compensate the lack of support for the back button of the web browser, a custom solution for this has been added to Aranea since release 1.2. This solution depends on rsh (Really Simple History), so you also need to import JavaScripts (js/aranea/aranea-rsh.js, js/rsh/rsh.js, see also System tags).

The main interface of this context is org.araneaframework.http.StateVersioningContext, and once enabled, it is accessible form the Environment, though one generally does not need to access it. Every application may provide their own values for costumizing the number of pages (default is 20) of the StateVersioningContext. To enable state versioning, one must add following XML code to aranea-conf.xml:

<bean id="araneaStateVersioningFilter"
  class="org.araneaframework.http.filter.StandardStateVersioningFilterWidget"
  singleton="false">
    <property name="maxVersionedStates" value="10"/>
</bean>

Note that it is defined as not being a singleton. This means that the configuration is created for every context (user). Therefore, the settings can be further customized to be more user specific.

In addition, an update region must be defined in your root.jsp that wraps system form and has a fixed name: araneaGlobalClientHistoryNavigationUpdateRegion. This is the region that is updated when the user moves between pages using the back button of the browser. Here's an example:

<ui:body>
        ...
        <ui:updateRegion globalId="araneaGlobalClientHistoryNavigationUpdateRegion">
                ...
                <ui:systemForm method="post">
                        ...
                </ui:systemForm>
                ...
        </ui:updateRegion>
        ...
</ui:body>

Finally, you also need to copy etc/js/rsh/blank.html from the Aranea 1.2 release package and place it in the root directory of your WAR bundle (the same directory where WEB-INF is located). This HTML file is needed for compatibility with Internet Explorer.

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

When framework receives an event(request) that has update region parameters defined, this filter is activated and takes care that only the smallest renderable unit that defines named update region is actually rendered. Generated response also contains only the rendered content of particular component(s) that needed to be rendered for updating the regions.

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.

Always 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).

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.

Transactions work in Aranea application by default. You may notice it in a web page as a hidden field, for example:

<input name="araTransactionId" type="hidden" value="-8629560801569274688"/>

The value is random, and a TransactionContext checks every request whether it is the same as expected (it remembers the previous transactionId value it gave to the page). If it is not the same, the request will be ignored. Therefore, one may notice when transactions are inconsistent: the pages won't update itself (on first click).

Sometimes, however, a transactionId may become inconsistent (for various reasons, such as due to a background request). Then the solution would be to change the transactionId value to "override" (for example, by using JavaScript). (In the next response, the transactionId will still have a new random numeric value.)

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”

When the file importer is used to provide aranea resources (styles/JavaScripts) it also defines cache time, after which the browser reloads the resources. You can configure this value through web.xml configuration parameter (the default time is 1 hour):

<context-param>
        <param-name>fileImporterCacheInMillis</param-name>
        <param-value>10800000</param-value>
</context-param>

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 acces to the root flow container at any time. Remember that RootFlowContext is the topmost flow context that everything else depends on. One can find it from the Environment.

Supports running processes in "overlay" layer (in parallel FlowContext of the same session thread). Allows construction of modal dialogs and modal processes.

Stores system form fields that will be written out when <ui:systemForm> tag is used. Form fields that indicate service levels (topServiceId and threadServiceId) are always automatically added to every response by this implementation.

This filter does not have any special injectable properties (except the usual childService). SystemFormContext interface is accessible from the Environment when this filter is present in the hierarchy and provides addField(String key, String value); and Map getFields(); methods for managing special form fields. See also information about systemForm tag.

This filter provides a way to preserve the scroll position of the window so that the user would not have to scroll back to the same place on the page every time they click on something. With every submit, the page sends its scroll coordinates so that the next response would know where to scroll the page. All-in-all, you can consider it a nice feature to have.

To enable this feature, one must define it in aranea-conf.xml:

 <bean id="araneaCustomWidgetFilters" singleton="false"
    class="org.araneaframework.framework.filter.StandardFilterChainWidget">
   <property name="filterChain">
     <list>
       <ref bean="araneaScrollingFilter"/>
     </list>
   </property>
 </bean>

Note the araneaScrollingFilter, which you do not have to define yourself (just reference it).

In addition, this feature must be registered in a (root) JSP page:

 ...
  <ui:body>

    <div id="cont1">
      <ui:systemForm method="POST">
        <ui:registerScrollHandler/>
        <ui:registerPopups/>
        <ui:registerOverlay/>
...

Notice the <ui:registerScrollHandler/> tag!

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.