Pustefix-Framework

In a typical Pustefix application the DispatcherServlet provided by Spring is usually the only servlet. This servlet instantiates a Spring ApplicationContext on startup and delegates all requests to the HttpRequestHandler found by using the HandlerMapping. If you want to do request processing for a certain path without using the HttpRequestHandlers provided by Pustefix, you can add your own instance of an UriProvidingHttpRequestHandler to the Spring configuration file.

All request handlers used by Pustefix are based on AbstractPustefixRequestHandler. The main feature of it's session handling is that it's mostly transparent to the user. You can submit data to a URL, and the system will take care to store the supplied data (this is done in the form of a PfixServletRequest, which can be seen as basically the same as a HttpServletRequest, with some additional features, e.g. more or less transparent handling of file uploads), create a session, redirect to the URL with an embedded session id, and continue with the business logic and the data submitted with the original request afterwards.

Even SSL is handled transparently. A descending request handler must implement the method + needsSession(): boolean to decide if the the current request should result into the session to be "secure". You don't have to make sure that the webpages use "https://" in all needed links, the target itself tells the system that it want's to run under SSL.

If the request handler decides that it want's to run under SSL from now on, a complex redirect sequence happens that makes sure that all data is copied from the previous insecure session into a new, secure session (a session is secure if it's session id was never transmitted over an insecure channel). After a session has once transformed into a secure one, there's no way back: Every time you try to use the session with "http://" it will create a new, secure session dropping the old one (because it's tainted now). If the visitor's browser supports cookies, the system manages to map request with the old, original, insecure session id (which can happen whenever the user uses the back button of her browser to go back to a page that has still the old session id embedded in every link) to the new, currently running secure session and silenty and securely redirects to this session.

5.1.1. HttpRequestHandlers provided by the core framework

Figure 5.1, “Pustefix HTTP request handlers” shows some of the HttpRequestHandlers that are already provided by the core framework and should be sufficient for most of your needs when building a web application with Pustefix.

Figure 5.1. Pustefix HTTP request handlers

DerefRequestHandler

This is a small request handler that should be used whenever a link to a URL outside the own site is made. All such external links must be of the form /xml/deref?link=http://some.other.domain/foo/bar. This is important because for any link that goes directly to a foreign destination (e.g. <a href="http://some.other.domain/foo/bar">) the session id visible in the logfile of the foreign site's webserver (via the Referer header). This is of course a security problem. Using the DerefServlet avoids this by using a redirect loop so the Referer header transmitted will no longer contain the session id.

AbstractPustefixXMLRequestHandler

This HTTP request handler, while still abstract, implements most of the output handling needed for request handlers that want use XSLT/XML to produce the final html sent to the browser.

The only thing a descendant needs to implement is the abstract method getDom(PfixServletRequest), whose return value can be thought of as a small container around a org.w3c.Document. The additional data stored in a SPDocument is among other things a map of XSLT transformation parameters that should be set and the "page name" which the system uses to choose the correct target stylesheet to transform the DOM with.

PustefixContextDirectOutputRequestHandler

In contrast to AbstractPustefixXMLRequestHandler and descendants, this request handler does not produce it's output by transforming XML with a XSLT stylesheet into HTML. There are situations where you need to stream some other format like pdf or images like PNG or GIF instead. The PustefixContextDirectOutputRequestHandler is used for exactly this purpose, because it delegates request processing to DirectOutputState objects which are allowed to write directly to the HttpServletResponse's OutputStream.

PustefixContextXMLRequestHandler

This is the main request handler that handles almost all pages in a typical Pustefix application - everything that produces HTML to be precise. The servlet doesn't do much on it's own, it delegates the request processing to a de.schlund.pfixcore.workflow.Context object. This Context is created by the PustefixContextXMLRequestHandler once for every session, stored into the HttpSession and reused for all later requests.

A Pustefix application has exactly one PustefixContextXMLRequestHandler. Although more than one additional >PustefixContextDirectOutputRequestHandler could be used, there is usually no need for such a configuration.

Every request that arrives at a pustefix application is processed in a specific way, depending on the HTTP request handler that is being selected by the PustefixHandlerMapping. In this chapter we will show how PustefixContextXMLRequestHandler handles requests.

The special processing of requests by this HTTP request handler is called the Pustefix Request Cycle. It is important to understand how this cycle works, and how to configure it in such a way to achieve the desired result for each request.

The main "director" in this cycle is the Context object, that will handle all the processing logic and call other objects to handle the business logic part of the request cycle (aka: do something useful with all the user supplied parameters of the request). The other main participants are implementations of the State and PageFlow interfaces.

Pustefix supplies default implementations of these interfaces.

public interface PageFlow {
    String getName();
    String getRootName();
    boolean containsPage(String pagename);
    String findNextPage(PageFlowContext context, String currentpagename, boolean stopatcurrentpage, boolean stopatnextaftercurrentpage) throws PustefixApplicationException;    
    boolean precedingFlowNeedsData(PageFlowContext context, String currentpagename) throws PustefixApplicationException;
    boolean hasHookAfterRequest(String currentpagename);
    void hookAfterRequest(Context context, ResultDocument resdoc) throws PustefixApplicationException, PustefixCoreException;
    void addPageFlowInfo(String currentpagename, Element root);
}
      

public interface State {
    boolean        isAccessible(Context context, PfixServletRequest preq) throws Exception;
    boolean        needsData(Context context, PfixServletRequest preq) throws Exception;
    ResultDocument getDocument(Context context, PfixServletRequest preq) throws Exception;
}
      

Write introduction...

<interface xsi:schemaLocation="http://pustefix.sourceforge.net/interfacewrapper200401 http://pustefix.sourceforge.net/interfacewrapper200401.xsd" extends="some.other.iwrapper.class"
  xmlns="http://pustefix.sourceforge.net/interfacewrapper200401"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <!--
    The class attribute references the associated IHandler class. Alternatively you can
    reference an existing Spring bean using the bean-ref attribute.
    The ihandler node is optional, but if it is left out, the generated
    IWrapper will be abstract and cannot be used directly, unless an extends attribute
    has been given to the interface node. Normally you will want to specify an ihandler
    class here.
  -->
  <ihandler class="some.de.schlund.pfixcore.generator.IHandler.class"/>
  <!-- or <ihandler bean-ref="aBean"/> -->
  <!--
    This node can (and usually will) occur multiple times, one for every parameter that
    should be part of the interface
  -->
  <param name="AName" type="some.java.Type" occurrence="optional|mandatory|indexed" frequency="single|multiple" missingscode="some.defined.statuscode">
    <!--
      The whole node is optional. It allows to specify a default value (or multiple) for
      a parameter to use, when no value is supplied via the request. Note that this makes
      the destinction between optional and mandatory parameters nonsensical.
    -->
    <default>
      <value>a_default_value</value>
      <value>an_other_default_value</value>
    </default>
      
    <!--
      To test if a param value conforms to the rules, you can specify Check-Classes here
      whose check method will be called to test if the param value makes sense.
      The Check-Classes must implement de.schlund.pfixcore.generator.IWrapperParamPreCheck
      (the interface defines the check(...) method).
    -->
    <precheck class="a.prechecker.class">
      <cparam name="APreCheckerParamName" value="APreCheckerParamValue"></cparam>
    </precheck>
      
    <!--
      Each parameter must be casted from a String to the specific type (unless the type is java.lang.String itself, in this case, no caster need to be supplied). This is done by means of a class implementing de.schlund.pfixcore.generator.IWrapperParamCaster. For the usual simple types you can use a caster from the package de.schlund.pfixcore.generator.casters.
    -->
    <caster class="de.caster.class">
      <cparam name="ACasterParamName" value="ACasterParamValue"></cparam>
    </caster>

    <postcheck class="a.postchecker.class">
      <cparam name="APostCheckerParamName" value="APostCheckerParamValue"></cparam>
    </postcheck>
  </param>
</interface>

public class MyWrapper {
    Bar  getFoo();
    void setFoo(Bar value);
    void setStringValFoo(String str_value);
    void addSCodeFoo(de.schlund.util.statuscode.StatusCode scode);
    void addSCodeWithArgsFoo(de.schlund.util.statuscode.StatusCode scode, String[] args);
}

public class MyWrapper {
    Bar[] getFoo();
    void  setFoo(Bar[] value);
    void  setStringValFoo(String[] str_value);
    void  addSCodeFoo(de.schlund.util.statuscode.StatusCode scode);
    void  addSCodeWithArgsFoo(de.schlund.util.statuscode.StatusCode scode, String[] args);
}

public class MyWrapper {
    Bar  getFoo(String index);
    void setFoo(Bar value, String index);
    void setStringValFoo(String str_value, String index);
    void addSCodeFoo(de.schlund.util.statuscode.StatusCode scode, String index);
    void addSCodeWithArgsFoo(de.schlund.util.statuscode.StatusCode scode, String[] args, String index);
}

public class MyWrapper {
    Bar[] getFoo(String index);
    void  setFoo(Bar[] value, String index);
    void  setStringValFoo(String[] str_value, String index);
    void  addSCodeFoo(de.schlund.util.statuscode.StatusCode scode, String index);
    void  addSCodeWithArgsFoo(de.schlund.util.statuscode.StatusCode scode, String[] args, String index);
}

public interface IHandler {
    void    handleSubmittedData(Context context, IWrapper wrapper) throws Exception;
    void    retrieveCurrentStatus(Context context, IWrapper wrapper) throws Exception;
    boolean prerequisitesMet(Context context) throws Exception;
    boolean isActive(Context context) throws Exception;
    boolean needsData(Context context) throws Exception;
}

StatusCodes are assigned to IWrapper parameters and form fields to indicate invalid data and display according error messages. They are automatically assigned by the framework when prechecks, casters or postchecks fail, or they can be assigned programmatically by the application logic.

The framework predefines some common StatusCodes, e.g. MISSING_PARAM - indicating the missing of a mandatory form value, or StatusCodes for builtin prechecks, casters and postchecks, like precheck.REGEXP_NO_MATCH - indicating that a form field's value doesn't match a given regular expression. Application developers can arbitrarily define additional StatusCodes.

StatusCodes are defined as normal include parts. They're placed in their own files located under the dyntxt directory. Within such a statuscode file the part names uniquely identify the StatusCode, the content nested inside the part element represents the message.

<?xml version="1.0" encoding="UTF-8"?>
<include_parts xmlns:ixsl="http://www.w3.org/1999/XSL/Transform" xmlns:pfx="http://www.schlund.de/pustefix/core">
  <part name="ILLEGAL_LOGIN">
    <theme name="default">Illegal login data.</theme>
  </part>
  ...
</include_parts>

Those StatusCode files are used by the build process to automatically create Java classes containing the StatusCodes as constants, using the part names as field names (in uppercase form). Thus the StatusCodes can be safely referenced from within Java code.

Before the StatusCode files are recognized by the build process, they have to be configured inside a statuscode metainformation file. The file has to be called statuscodeinfo.xml and has to be located in the project's conf directory or in the dyntxt directory. Within this file you define which StatusCode constant class is built from which StatusCode files.

<?xml version="1.0" encoding="UTF-8"?>
<statuscodeinfo xmlns="http://pustefix-framework.org/statuscodeinfo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://pustefix-framework.org/statuscodeinfo ../../core/schema/statuscodeinfo.xsd">
  <statuscodes class="example.bank.BankStatusCodes">
    <file>statusmessages.xml</file>
    <file>...</file>
  </statuscodes>
  ...
</statuscodeinfo>

Using the above examples Pustefix will build the following Java class (excerpt):

package example.bank;
...
public class BankStatusCodes {
    public static StatusCode getStatusCodeByName(String name) { ... }
    ...
    public static final StatusCode ILLEGAL_LOGIN = new StatusCode("ILLEGAL_LOGIN", __RES[0]);
}

The following login handling example uses the generated StatusCode class to indicate a failed login:

public class LoginHandler implements IHandler {
    public void handleSubmittedData(Context context, IWrapper wrapper) throws Exception {
        Login login = (Login) wrapper;
        //check login data
        //if invalid
        login.addSCodeUser(BankStatusCodes.ILLEGAL_LOGIN);
    }
}

If you take a look at the resulting XML tree, you see like the according include part is referenced inside the error element (and thus can be displayed on the page using the pfx:checkfield, pfx:error and pfx:scode tags).

<formresult ...>
   ...
   <formvalues>
      <param name="login.User">xyz</param>
      ...
   </formvalues>
   <formerrors>
     <error name="login.User">
        <pfx:include href="samplebank/dyntxt/statusmessages.xml" part="ILLEGAL_LOGIN"/>
     </error>
   </formerrors>
   ...
</formresult>

If your error message should contain dynamic data, you can use placeholders, which will be replaced by the arguments passed along with the addScode call at the IWrapper:

<part name="ILLEGAL_LOGIN">
  <theme name="default">User <pfx:argref pos="1"/> is illegal.</theme>
</part>

StatusCodes can be also referenced from within IWrapper definitions. If you're using a built-in StatusCode (from org.pustefixframework.generated.CoreStatusCodes), you can just use its name, if you're using a StatusCode from another module, you have to prefix the name with the class name of the generated class separated by a # sign:

<interface xmlns="http://pustefix.sourceforge.net/interfacewrapper200401">

  <ihandler class="..."/>
  
  <param name="Login" type="..." missingscode="example.bank.BankStatusCodes#MISSING_LOGIN_DATA">
    ...
  </param>

</interface> 

The statusmessage files for statuscodes coming from the Pustefix core or arbitrary modules can be edited to customize the messages for your project's requirements. Therefor the original statusmessage files are initially copied or if a copy already exists, the files are merged (statusmessages for new statuscodes are added, statusmessages for omitted statuscodes are removed) by the build process. You should only customize these merged files, changes in the original files will be overwritten with the next module update.

The built-in core and editor statuscodes are merged to projects/core-override/dyntxt/statusmessages-core-merged.xml and projects/core-override/dyntxt/statusmessages-editor-merged.xml. Pustefix module statuscodes are merged to projects/modules-override/MODULENAME/dyntxt/statusmessages-merged.xml.

Pustefix provides a mechanism to hook custom logic into the request processing lifecycle. Therefor it provides a set of interception points, where you can register classes or Spring beans implementing the ContextInterceptor interface, which then are automatically called during the processing of a request.

Figure 5.2. ContextInterceptors

Currently Pustefix supports three interception points: start, which is right before the actual request handling gets started, end, which is right after the DOM result tree has been created, and postrender, which is right after the view has been rendered.

public interface ContextInterceptor {
    void process(Context context, PfixServletRequest preq);
}

The framework calls the process method of the registered ContextInterceptor implementations, passing the Context and PfixServletRequest as parameters.

Note

Comparison with ServletFilters: ServletFilters apply right before/right after a request/response enters/leaves the framework's processing layer and give you means to manipulate the incoming ServletRequest and outgoing ServletResponse, whereas ContextInterceptors are part of the framework's lifecycle and give you direct access to the request (but not the response), Context and other Spring beans, and are meant to trigger logic or set data.

ContextInterceptors are configured in the Context's configuration file. Below you can see an a sample configuration fragment showing all available configuration options:

<context-xml-service-config>
 
   <context> ... </context>

   <!-- ContextInterceptors are defined within the <interceptors> element directly following the <context> element. -->
   <interceptors>

     <!-- The interceptors are grouped by their interception points (start, end, postrender), which are represented 
            by accordingly named elements. -->
     <start>

        <!-- Interceptors are registered either by setting the ContextInterceptor implementation class or by setting 
               an according reference to a Spring bean configured elsewhere. -->
        <interceptor class="mypackage.MyStartInterceptor"/>

        <!-- If you're setting an implementation class, the framework will create an according Spring bean for you. 
               By default it will get Singleton scope, but you can provide an alternative scope using the scope attribute. --> 
        <interceptor class="mypackage.MySessionScopedInterceptor" scope="session"/>

        <interceptor bean-ref="myStartInterceptor"/>

     </start>

     <end> ... </end>

     <postrender> ... </postrender>

   </interceptors>

   ...

</context-xml-service-config>

The following example interceptor tries to guess from which country the client request is coming and sets a special variant if it comes from Germany. Therefor it checks the client's IP retrieved from the servlet request using a GeoLocationAPI. It sets a flag after the first check to avoid multiple checks. Remembering the flag this way only works when the interceptor has session scope and synchronization can be omitted because the operation is repeatable and boolean access is atomic.

public class MySessionScopedInterceptor implements ContextInterceptor {
	
	private boolean checked;

	@Override
	public void process(Context context, PfixServletRequest preq) {
		if(!checked) {
			String country = GeoLocationAPI.getCountry(preq.getRemoteAddr());
			if(country.equals("DE")) context.setVariant("foo");
			checked = true;
		}
	}
	
}

	Note
	ContextInterceptors are singleton-scoped beans by default. So if you want to store data or call non-threadsafe code, you possibly will have to do some synchronization or use an appropriate scope. ContextInterceptors are called on every request. So you shouldn't execute long-running tasks and avoid that time-consuming code is unnecessarily called with each invocation.