Workflow

Workflow is the main component of the whole framework.

Workflow is initialized through XML file written according to DTD, which is available at http://www.ais.pl/dtds/workflow_0_2.dtd. Public ID for this file is -//AIS.PL//DTD Workflow Description 0.2//EN.

Workflow consists of a set of 'Page' objects. Every Page is configured in XML with following attributes:

• name - identifies the given page across the Workflow set of pages;
• class - name of a class which represents the 'Page', this class must be a concrete, non-abstract subclass of pl.aislib.fm.Page abstract class;
• template - key for TemplateEngine, specifies the template used for generating response from page.
• session-expiration - indicates whether page can be displayed when there is a new HTTP session. Possible values: true (default) - flow will be redirected to start page; false - page can be displayed when the HTTP session is new. This attribute is considered only if attribute session-expiration-check of the workflow object is set to 'isNew'.

Every page may have triggers in their configuration. Triggers are responsible for moving application from one page to another. Definition of trigger consists of following attributes:

• name - name of trigger;
• page-ref - name of page we want to move to;
• predicate - full name of class implementing org.apache.commons.collections.Predicate;
• type - type of trigger, defines scope of trigger;

• request-param - default value, trigger will check request parameter with name specified by name attribute;
• request-attr - trigger will check request attribute with name specified by name attribute;
• session-attr - trigger will check session attribute with name specified by name attribute;
• request - trigger will check whole request, name attribute is ignored in this case;

Every page may have flows in their configuration. Flow entries declare, that page may move execution to different page. Definition of flow consist of two values: name and page-ref. If page code during execution moves execution to page which is not declared as flow, WARN message is generated.

A set of pages may be configured to use one template container. Template container represents the common look of HTML view of an application, sometimes called 'main template'. Configuration of template container consists of template-name (key for template engine) and slot - specifies where in the 'main templare' output from the page should be inserted.

Applicaton.dispatch method uses the following algorithm for moving servlet request and response to proper page and getting the response from page:

1. looks for a page parameter in the request, if there is no page parameter index value is used;
2. if there is no page configured with a given value as a name, PageNotFound error code is generated (404 error);
3. set of triggers of given page is examined, if there is a trigger, triggered page (page-ref) is selected;
4. instance of 'Page' class is instantied, configured and getPageResponse is called for performing the process of generating response;

Response from a page is encapsulated in the PageResponse class. PageResponse consists of content type and content. Content may be an array of bytes or Map instance. The following algorithm is used for performing response from the page:

1. if getPageResponse method returns null, it means that there is nothing to do - the page handles the output within getPageResponse method;
2. if pageResponse has content type configured, servlet response content type is set to the value from pageResponse, if there is no content type in pageResponse, default content type from Application is used (text/html);
3. if there is no content in the pageResponse, an algoritm applicable to Map is used to generate response to client;
4. if content of pageResponse is an array of bytes, then OutputStream is getting from the servlet response and the array is written to the stream;
5. if content of pageResponse is a Map instance, then template specified to page is loaded and evaluated with a given Map as a 'parameters' parameter. If given page is configured to be in template container, then template container is loaded and evaluated with Map from pageResponse (template from a page is added to this Map within a 'slot' name key). Evaluated template (the one from container if page is in container or the one from page if there is no container) is written to Writer from servlet response.

Workflow contains two attributes:

• start-page - page which should be displayed after launching the application (default 'index')
• session-expiration-check - if set to 'isNew' then framework will check before processing request if the HTTP session is new and if page has session-expiration set to 'true' then start page will be displayed; if set to 'none' (default) then session expiration will not be checked.

Consider the following example of workflow configuration:

<!DOCTYPE workflow PUBLIC "-//AIS.PL//DTD Workflow Description 0.2//EN"
         "http://www.ais.pl/dtds/workflow_0_2.dtd">
<workflow start-page="index" session-expiration-check="isNew">
  <page name="index" class="example.pages.Index" template="index.html"
        session-expiration="false"/>

  <page name="menu" class="example.pages.Menu" template="menu.html"
        session-expiration="false">
    <trigger name="sale" page-ref="sale"/>
  </page>

  <page name="sale" class="example.pages.Sale" template="sale.html"/ session-expiration="true"/>
</workflow>

• no action parameter: response from Index page;
• action=index: response from Index page;
• action=menu, no sale parameter: response from Menu page;
• action=menu, sale parameter is set: response from Sale page.