Pustefix Reference Documentation

Some parts of the Pustefix frameworks are configured using Java properties. To ease this configuration Pustefix provides you with a special XML format which is read instead of the usual Java property file format. This format provides some customization mechanism to allow configuration options to depend on settings like the makemode or the machine the application is being built on.

The structure of a standard .xml property file is very easy:

<standardprops version="1.0"
  xmlns="http://pustefix.sourceforge.net/2004/properties"
  xmlns:cus="http://www.schlund.de/pustefix/customize"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://pustefix.sourceforge.net/2004/properties http://pustefix.sourceforge.net/2004/properties.xsd">
      

The cus namespace is needed to use the customization tags explained below.

  <properties>
    <prop name="statuscodefactory.messagefile">common/dyntxt/statusmessages.xml</prop>

      

The prop tag is the most primitive way to enter a single property. The example above would simply result in the java property statuscodefactory.messagefile=common/dyntxt/statusmessages.xml.

  </properties>
</standardprops>
      

Pustefix allows to customize the creation of the property files in certain ways. When the file is being read, the system uses settings defined in common/conf/buildtime.prop (which itself is automatically generated by the build system) to provide the parameters used in the customization tags:

Certain customization tags work with these parameters:

<properties
  xmlns:cus="http://www.schlund.de/pustefix/customize">
  <prop name="foo">
    <cus:uid/>
  </prop>
      

Use cus:uid to reference the user that started the build process. In the same way you can use cus:machine and cus:fqdn to insert the value of the supplied XSLT parameter

  <choose>
    <when test="$mode='test'">
      
    </when>
    <when test="$uid='pfixuser'">
      
    </when>
    <when test="$machine='server1'">
      

These choose and when elements are allowed only within properties elements. The three test nodes above test for one of the supplied XSLT parameters...

    </when>
    <when test="$mode='prod' and $uid='pfixuser'">
      
    </when>
    <when test="$mode='prod' or machine='server1'">
      

...you can use boolean operators to combine tests

    </when>
    <otherwise>
      

The "default test" that will always pass.

    </otherwise>
  </choose>
</properties>
      

If you think the customization system really looks like XSLT, you are almost right as in fact the test expressions are coded using XPath - the same standard XSLT is using, too.

This customization mechanism is not only available within the XML property files but also in most other Pustefix configuration files.

Most projects use one or a (small) number of de.schlund.pfixxml.ContextXMLServlet servlets that drive the business logic of the application. All pages that are to be generated via XSLT from a data XML tree are handled by a servlet of this type.

This servlet uses a configuration file that has a special syntax. However properties and customization in this file work nearly the same way as explained for the standard property definitions.

<contextxmlserver version="1.0"
  xmlns="http://pustefix.sourceforge.net/2004/properties"
  xmlns:cus="http://www.schlund.de/pustefix/customize"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://pustefix.sourceforge.net/2004/properties http://pustefix.sourceforge.net/2004/properties.xsd">
  <servletinfo depend="MyProject/conf/depend.xml" name="AUniqueNameForTheServlet">
      

The attributes depend and name are mandatory. If depend starts with a '/' the value is used unchanged, otherwise (which is the usual case) it's interpreted as a path relative to the docroot.

    <editmode allow="true|false"/>
      

allow needs to be set to true if you want to be able to use the pustefix editor. You can wrap this tag within a customization element to allow edit mode only in certain modes (e.g. test mode). The whole node is optional.

    <ssl force="true|false" modes="ListOfModes"/>
      

force must be set to true if the servlet needs to run under SSL. You can wrap this tag within a customization element to force use of SSL only in certain modes (e.g. prod mode). The whole node is optional.

    <defaultstate class="a.state.Class"/>
    <defaultihandlerstate class="another.state.Class"/>
      

defaultstate and defaultihandlerstate are both optional. The class attribute must be given. a.state.Class should de a descendant of de.schlund.pfixcore.workflow.app.StaticState and another.state.Class should be a descendant of de.schlund.pfixcore.workflow.app.DefaultIWrapperState (unless you really know what you are doing). They are used to set the defaults for the state tag used when processing the pagerequest tag (see there for more info).

  </servletinfo>
  
  <context defaultflow="AFlowName" authpage="APageName" synchronized="true">
      

    <resource class="AContextResource">
      

class is mandatory, must be a ContextResource. There may be multiple resource tags given.

      <implements class="An_Interface">
      

class is mandatory, must be an interface implemented by the ContextResource. There may be more than one implements tag for a ContextResource, but each interface must be unique in the whole context. In other words: it's possible for a ContextResource to implement more than one interface, but not possible for one interface to be implemented by two ContextResources used in the same Context definition.

      </implements>
      <properties>
      

The whole node is optional.

        <prop name="AName">AValue</prop>
      

prop is mandatory and can be used multiple times. It's similar to the use as a child of pagerequest/properties, but used here to create properties that are related to a context resource implementation. The resulting property looks like this: context.resourceparameter.AContextResource.AName=AValue Customization tags may be used around a property to make it depend on a certain makemode, etc.

      </properties>
    </resource>
  </context>
  
  <scriptedflow name="AName" file="path/to/scriptfile.xml"/>
      

There may be an arbitrary number of scriptedflow tags, but each one must have a unique name. Scripted flows are a special method to control a session and do automatic requests based on initial user input.

  <role name="MY_ROLE">
    <pageaccess names="mypage*"/>
  </role>
      

You can define an arbitrary number of roles and assigned authorizations here, for details see Role-based authorization.

  <pageflow name="AName" final="APageName" stopnext="true|false">
       

There may be multiple pageflow tags defined, but you need at least one (which must be referenced by the defaultflow attribute above). We only describe the normal case without using variants. See here for more information on how to handle variants of pageflows.

    <flowstep name="AnotherPageName" stophere="true|false">
      

      <oncontinue applyall="true|false">
      

This tag (which is optional) starts a sequence of test/action pairs. The tests are XPath expressions which work on the DOM tree as produced by the flowstep's associated state (note that the navigation is not inserted into the DOM tree at this stage, and the /formresult/formvalues and /formresult/formerrors paths are also not present). The pageflow system calls the tests whenever a state returns a ResultDocument (before it continues with other stuff e.g. a pageflow run). The applyall attribute is optional. If given and true, all actions with matching conditions are executed, if not given or false (the default) only the first action with a matching condition is executed.

        <when test="A_XPath_Expression">
      

The when tag contains the XPath expression to try in it's test attribute. If this attribute is omitted, the whole condition is considered to be true.

          <action type="jumpto" page="APage" pageflow="APageFlow">
      

The action tag denotes the FlowStepAction to execute. The type attribute is mandatory and defines the special action to use. The string jumpto denotes the special FlowStepAction de.schlund.pfixcore.workflow.FlowStepJumpToAction which is used to set the jumptopage (defined via the page attribute) and/or the jumptopageflow (defined via the pageflow attribute).

          </action>
        </when>
        <when test="A_XPath_Expression">
          <action type="A_FlowStepAction" somekey="somevalue">
      

If the type attribute is not jumpto, the value is interpreted as a class of type de.schlund.pfixcore.workflow.FlowStepAction. There can be an arbitrary number of additional attributes (somekey in this example) which are supplied as named parameters to the special FlowStepAction.

          </action>
        </when>
      </oncontinue>
    </flowstep>
  </pageflow>
  
  <pagerequest name="APageName" nostore="true|false" copyfrom="APageName">
      

    <ssl force="true|false"/>
      

The node is optional. If given, and the attribute force is set to true, the page will only run under SSL when jumped to via a link or a submit of form data. If the session currently does not run under SSL, the system will make sure to redirect to a secure session prior to handling the request. After a session is running under SSL, there is no way back (so all other pages will run securely regardless if they have a ssl node or not). You can wrap this tag within a customization element to force use of SSL only in certain modes (e.g. prod mode).

	Note
	You can force the servlet as a whole to run only under SSL by specifying the ssl subnode of the servletinfo node.

<state class="AClassName"/>
      

The whole node is optional. If given, the class attribute must be the name of a java class implementing the de.schlund.pfixcore.workflow.State interface. The used State is determined as follows:

You can use any BSF-supported scripting language for writing your State-implementation, too. See PustefixScripting for details on how to do this.

    <finalizer class="AClassName"/>
      

The whole node is optional. It may only be given for a State that is either de.schlund.pfixcore.workflow.app.DefaultIWrapperState or a descendent of it. The class attribute is mandatory and denotes a class implementing de.schlund.pfixcore.workflow.app.ResdocFinalizer.

	Caution
	The use of finalizers is not suggested most of the time! They can completely change the result document and the logic when to trigger the next step in the current page flow. Use them at your own risk. Or better: Don't use them at all.

    <input policy="ANY|ALL|NONE">
      

The whole node is optional. It may only be given for a State that is either de.schlund.pfixcore.workflow.app.DefaultIWrapperState or a descendent of it! policy is optional (default is ANY). The policy decides when a whole page is considered to be accessible:

If one of the associated handlers returns false on calling prerequisitesMet(), the page is of course still inaccessible.

      <interface prefix="AName" class="AClassName" activeignore="true|false" continue="true|false" alwaysretrieve="true|false"/>
      

There can be many interface nodes for a page. Each one references an "atomic" functional entity consisting of an IWrapper java class (usually autogenerated from a .iwrp xml file, see here) that defines the type and names of the parameters passed between the UI and the functional entity and an associated IHandler java class that uses the IWrapper to retrieve the passed parameters via typed getter methods.

    </input>
      

	Caution
	Only one of input or auth may be given as a child node!

    <auth>
      

The whole node is optional. It may only be given for a page using a State that is either de.schlund.pfixcore.workflow.app.DefaultAuthIWrapperState or a descendent of it! There may be only one pagerequest using such a State, it must be the one that is also referred to via the authpage attribute of the context node above. Other pagerequest nodes must not have this subnode!

      <authinterface prefix="AName" class="AClassName"/>
      <auxinterface prefix="AName" class="AClassName"/>
      

One and only one authinterface node must be given. auxinterface nodes are optional and can be given multiple times. The prefix and class attributes are mandatory for both nodes. The meaning is the same as for the interface subnodes of the ihandler node. The authinterface node denotes the one IWrapper/IHandler combo that is responsible for checking the authentification of a user session. The auxinterface nodes denote additional IWrappers/IHandlers that are called after the authentification handler if the authorization is granted. Note that no error handling whatsoever takes place for auxinterface IHandlers.

    </auth>
    
    <output>
      

The whole node is optional. Every page using a State that is itself or a descendant of de.schlund.pfixcore.workflow.app.StaticState can use this. You can have as many resource childnodes as you like.

      <resource node="AName" class="AClassName"/>
      

    </output>
    
    <properties>
      

The whole node is optional.

      <prop name="APropertyKey">AValue</prop>
      

The node is mandatory and can be used multiple times. It will be transformed into a java property that is associated to the page. There are some props that are already defined for de.schlund.pfixcore.workflow.app.StaticState and descendants. These are listed below

    </properties>
  </pagerequest>
  
  <config-include file="myproject/conf/myfile.xml" section="pagerequests"/>
      

Includes a part of a config fragments file at this location. See Section 1.4, “Configuration fragments file format” for details on how to define config fragments.

One and only one of the section, refid or xpath attribute has to be specified for each config-include.

  <properties>
    <prop name="AProperty">AValue</prop>
      

You can also specify properties here that are understood by the ServletManager class.

  </properties>
</contextxmlserver>
      

Occasionally you don't want to generate output with an XSLT Transformation, but e.g. deliver binary content directly to the output stream instead. In this case you need to provide another servlet of type de.schlund.pfixxml.DirectOutputServlet. This servlet doesn't have it's own Context object but instead "hijacks" the Context of a foreign de.schlund.pfixxml.ContextXMLServlet. The context isn't used for any pageflow handling, only as a means to get to the data (via its ContextResources) of the "main" application.

The servlet knows about one or many directoutputpagerequests. For the XML/XSLT side of things, they look like normal pages (in fact, the value of the directoutputpagerequest's name attribute must be a page defined in depened.xml. Of course, no target definition has to be given, only the page in the navigation structure must exist). But other than the usual pagerequest, a directoutputpagerequest has an associated directoutputstate whose class attribute is a java class implementing de.schlund.pfixcore.workflow.app.DirectOutputState.

<directoutputserver version="1.0"
  xmlns="http://pustefix.sourceforge.net/2004/properties"
  xmlns:cus="http://www.schlund.de/pustefix/customize"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://pustefix.sourceforge.net/2004/properties http://pustefix.sourceforge.net/2004/properties.xsd">
  
  <directoutputservletinfo depend="MyProject/conf/depend.xml" name="AUniqueNameForTheServlet">
    <ssl force="true|false"/>
    <editmode allow="true|false"/>
      

See the comment for the servletinfo node in Section 1.2, “ContextXMLServlet configuration format”.

  </directoutputservletinfo>
  
  <foreigncontext externalservletname="UniqueNameOfAnotherServlet" synchronized="true"/>
       

The externalservletname must reference the name of a servlet of type de.schlund.pfixxml.ContextXMLServlet. The Context (or better: the ContextResourceManager) of this servlet is used for getting stored application data. Additionally, if the ContextXMLServlet requires authentication, it's authentication page is checked before any DirectOutputState is called. The synchronized attribute is optional. It defaults to true. If set to true, only one request per session is handled concurrently. If set to false all requests will be handled concurrently, requiring thread-safe business logic.

  <config-include file="myproject/conf/myfile.xml" section="directoutputpagerequests"/>
       

Includes a part of a config-fragments at this location. See Section 1.4, “Configuration fragments file format” for details on how to define config fragments.

One and only one of the section, refid or xpath attribute has to be specified for each config-include.

  <directoutputpagerequest name="APageName">
    <directoutputstate class="AClassName"/>
    <properties>
      

The whole properties node is optional.

      <prop name="APropertyKey">AValue</prop>
      

The node is mandatory and can be used multiple times. It will be transformed into a java property that is associated to the page. The java property that is constructed will look like this: pagerequest.APpageName.APropertyKey=AValue where APageName is the value of the name attribute.

    </properties>
  </directoutputpagerequest>
</directoutputserver>
      

Configuration fragments files contain aggregated configuration directives that are intended to be reused in different configuration files.

<fr:config-fragments
  xmlns:fr="http://pustefix.sourceforge.net/configfragments200609"
  xmlns:pr="http://pustefix.sourceforge.net/properties200401"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://pustefix.sourceforge.net/configfragments200609 http://pustefix.sourceforge.net/configfragments200609.xsd">
  
  <fr:navigation id="nav1">
      

All sections have an optional id that can be used to identifiy the section when more than one section fo the same type is present in one file. The value of the id attribute has to be unique within the whole file.

    <page name="MyPage" handler="/xml/myhandler"/>
      

The structure here is the same as within the navigation tag of the depend.xml file.

  </fr:navigation>
  <fr:targets>
    <standardpage name="MyPage" xml="myproject/xml/mymaster.xml"/>
      

The tags allowed here are the same that are allowed for standardpage or target definitions in the depend.xml file.

  </fr:targets>
  <fr:resources>
    <pr:resource class="com.example.MyResourceImpl">
      <pr:implements class="com.example.MyResource"/>
    </pr:resource>
      

The tags allowed here are the same that are allowed for the definition of context resources within the context tag of the ContextXMLServlet configuration.

  </fr:resources>
  <fr:interceptors>
    <pr:interceptor class="com.example.MyInterceptor"/>
      

The tags allowed here are the same that are allowed within the startinterceptors and endinterceptors tags of the ContextXMLServlet configuration.

  </fr:interceptors>
  <fr:scriptedflows>
    <pr:scriptedflow name="myscript" file="myproject/conf/scriptedflows/myscript.script.xml"/>
      

The tags allowed here are the same that are allowed within the scriptedflows tag of the ContextXMLServlet configuration.

  </fr:scriptedflows>
  <fr:roles>
    <pr:role name="MY_ROLE">
      <pr:pageaccess names="mypage*"/>
    </pr:role>
      

The tags allowed here are the same that are used for role definition in the ContextXMLServlet configuration.

  </fr:roles>
  <fr:pageflows>
    <pr:pageflow name="MyFlow">
      <pr:flowstep name="MyFirstPage"/>
      <pr:flowstep name="MySecondPage"/>
    </pr:pageflow>
      

The tags allowed here are the same that are used for the definition of pageflows in the ContextXMLServlet configuration.

  </fr:pageflows>
  <fr:pagerequests>
    <pr:pagerequest name="MyPage"/>
      

The tags allowed here are the same that are used for the definition of pagerequets in the ContextXMLServlet configuration.

  </fr:pagerequests>
  <fr:properties>
    <pr:prop name="myproperty">myvalue</pr:prop>
      

The tags allowed here are the same that are allowed within the properties tag of the ContextXMLServlet configuration.

  </fr:properties>
  <fr:directoutputpagerequests>
    <pr:directoutputpagerequest name="foo">...</pr:directoutputpagerequest>
      

Direct output pagerequests can be defined here. See Section 1.3, “DirectOutputServlet” for details on this.

  </fr:directoutputpagerequests>
</fr:config-fragments>
      

This property file is located in projects/common/conf/factory.xml and used by the de.schlund.pfixxml.FactoryInitServlet servlet (contained in the special admin project used in every Pustefix environment) whenever the servletcontainer starts up to initialize services that are used by all the other projects. The syntax of this file is described in Section 1.1, “Java property files in Pustefix”.

The syntax of the common/conf/pustefix.xml file complies to the description in Section 1.1, “Java property files in Pustefix”. The properties defined here are merged with the properties defined for a specific servlet. However, there are some properties with a special meaning.

Exception processing is configured via prop elements whose names comply to following syntax: exception.TYPE.[page|forward|processor] For one single TYPE, there may be only one occurrence of page, forward and processor.

TYPE is a fully qualified class name of a valid exception class, for which the handling should be configured at this point. In this case it specifically means, that the specified class must be a descendant of java.lang.Throwable, as the catch-block that handles the exceptions which are specified here, catches Throwable.

If an exception occurs during exception processing, or during processing of the page the request got forwarded to, no further exception handling will take place. Therefore the code that processes exceptions and the code that drives pages to which requests get forwarded, in case of exceptions, should be robust. Otherwise the whole exception-handling thing would be quite useless, wouldn't it?

Pustefix provides a role-based authorization mechanism. You can define arbitrary roles, declare logical operations/combinations on this roles using authconstraints, and assign these authconstraints to pagerequests.

A role is defined using an according XML element with a unique name attribute value. Setting the initial attribute to true the role will be automatically set on context initialization.

  <role name="MYROLE" initial="true"/>

Authconstraints can combine various authorization conditions, supported conditions are: hasrole, and, or and not, represented by according XML elements. Using the authpage attribute you can define the page, which should be called on authorization failure. Using the default attribute you can set one toplevel authconstraint to be the default one for all pagerequests having no authconstraint asssigned.

  <authconstraint id="MYCONSTRAINT" authpage="login" default="true">
    <or>
      <hasrole name="MYROLE"/>
      <hasrole name="OTHERROLE"/>
    </or>
  </authconstraint>

Pagerequests can either define new authconstraints as child elements or can reference existing toplevel authconstraints by their id.

  <pagerequest name="mypage">
    <authconstraint ref="MYCONSTRAINT"/>
    ...
  </pagerequest>

  <pagerequest name="mypage">
    <authconstraint authpage="login">
      <hasrole name="MYROLE"/>
    </authconstraint>
    ...
  </pagerequest>

You can programmatically set/query roles using the de.schlund.pfixcore.auth.Authentication object, which can be retrieved from the Context calling its getAuthentication() method.

public interface Authentication {
    
    public boolean hasRole(String roleName);
    public boolean addRole(String roleName);
    public boolean revokeRole(String roleName);
    
    public Role[] getRoles();
    
}

You can add a new role using addRole(), revoke exisiting roles using revokeRole() or check for a role using hasRole(). Using getRoles() you get an array of all currently set roles. If a default role is defined, this role will be initially set.

You can also query the current roles from within your XML/XSLT code using the XPath extension function pfx:hasRole(rolename)

      <ixsl:if test="pfx:hasRole('MYROLE')">
         ...
      </ixsl:if>
    

If you try to access a page for which the authconstraint isn't fulfilled, you're forwarded to the according login page. The login page has to be a regular page, i.e. IWrappers on the page are configured the regular way (no authinterface elements). Login forms require the type attribute set to roleauth (instead of auth in the traditional login forms).

    <pfx:forminput type="roleauth">
      ...
    </pfx:forminput>
    

The framework automatically inserts an authentication element into the login page's DOM tree. This element contains the state of the authenticated flag, the targetpage which should be accessed, the current roles and the authorizationfailure containing the violated authconstraint.

    <formresult>
      <authentication authenticated="true" targetpage="mypage">
        <roles>
          <role name="SOMEROLE"/>
        </roles>
        <authorizationfailure authorization="pageaccess" target="mypage">
          <authconstraint>
            <hasrole name="MYROLE"/>
          </authconstraint>
        </authorizationfailure>
      </authentication>
      ...
    </formresult>
    

<contextxmlserver>
  
  <role name="ANONYMOUS" initial="true"/>
  <role name="USER"/>
  <role name="ADMIN"/>
  
  <authconstraint id="AC_DEFAULT" authpage="login" default="true">
    <hasrole name="ANONYMOUS"/>
  </authconstraint>
  
  <authconstraint id="AC_KNOWN" authpage="login">
    <or>
      <hasrole name="USER"/>
      <hasrole name="ADMIN"/>
    </or>
  </authconstraint>
  
  <pagerequest name="home">
    ...
  </pagerequest>
  
  <pagerequest name="login">
    <input>
      ...
    </input>
  </pagerequest>

  <pagerequest name="adminpage">
    <authconstraint authpage="login">
      <hasrole name="ADMIN"/>
    </authconstraint>
    ...
  </pagerequest>
  
  <pagerequest name="userpage">
    <authconstraint ref="AC_KNOWN"/>
    ...
  </pagerequest>

  ...

</contextxmlserver>

Pustefix provides a lightweight object serialization mechanism, which can be used to serialize arbitrary objects into the result DOM without having to do any DOM operations by yourself. The XML binding is customizable via Java annotations within the bean classes.

The framework supports arbitrary Beans, Arrays, Collections, Maps, Numbers (including the primitive types and their object wrapper types), Strings, and Date/Calendar. To support other types or to serialize to a custom format, it's possible to write your own serializers and annotations (to attach them to the according bean properties).

The serialization of beans can be customized using the generic Pustefix bean annotations, which are known from the JSON serialization framework. You can exclude individual properties from serialization by marking the according getter with an @Exclude annotation or you can exclude all properties by marking the bean class with an @ExcludeByDefault annotation and include individual properties with @Include annotations at their getters (marking public members is supported too). Using the @Alias annotation you can control the name used as the resulting attribute or element name.

The serialization to the result tree is done by calling one of the static addObject methods of the ResultDocument class. The element argument is the parent DOM element at which the serialized XML will be appended, the optional name argument can be used to create an additional child element for the serialized XML. The object argument is the object, which should be serialized.

	   public class ResultDocument {
	     ...
	     public static Element addObject(Element element, Object object) {...}
	     public static Element addObject(Element element, String name, Object object) {...}
	   }
	  

        ...
	  
        public class Account {
  
          private long accountNo;
          private float debit;
          ...
  
          public long getAccountNo() {
            return accountNo;
          }

          public void setAccountNo(long accountNo) {
            this.accountNo = accountNo;
          }

          @Alias("balance")
          public float getDebit() {
            return debit;
          }

          public void setDebit(float debit) {
            this.debit = debit;
          }
  
          public Currency getCurrency() {
            return currency;
          }
  
          public void setCurrency(Currency currency) {
            this.currency = currency;
          }
  
          @DateSerializer("yyyy-MM-dd HH:mm:ss")
          public Calendar getOpeningDate() {
            return openingDate;
          }

          public void setOpeningDate(Calendar openingDate) {
            this.openingDate = openingDate;
          }
  
          @Exclude
          public String getComment() {
            return comment;
          }

          public void setComment(String comment) {
            this.comment = comment;
          }

        }
	  

        ...
        
        public class ContextAccountImpl implements ContextAccount {

          private Account account;
	      ...
	
          public void insertStatus(ResultDocument resdoc, Element elem) throws Exception {
            ResultDocument.addObject(elem,"account",account);
          }
          
        }
      

        <formresult serial="1199439160721">
          ...
          <data>
            <account accountNo="2000123" currency="EUR" balance="332.54" openingDate="2003-11-04 09:15:38"/>
          </data>
          ...
        </formresult>
      

        <formresult serial="1199439160721">
          ...
          <data>
            <account accountNo="2000123" balance="EUR" debit="332.54" openingDate="2003-11-04 09:15:38">
              <customer customerId="100000" firstName="Mike" lastName="Foo"/>
            </account>
          </data>
          ...
        </formresult>
      

        <formresult serial="1199439160721">
          ...
          <data>
            <account accountNo="2000000" currency="EUR" balance="3124.49" openingDate="2003-10-23 08:05:10"/>
            <account accountNo="2000123" currency="EUR" balance="332.54" openingDate="2003-11-04 09:15:38"/>
            <account accountNo="2001405" currency="EUR" balance="25123.11" openingDate="2005-01-13 10:10:10"/>
          </data>
          ...
        </formresult>
      

      @ClassNameAlias("bankaccount")
      public class Account {
        ...
      }
      

        <formresult serial="1199439160721">
          ...
          <data>
            <entry>
              <long>2000000</long>
              <account accountNo="2000000" currency="EUR" debit="3124.49" openingDate="2003-10-23 08:05:34"/>
            </entry>
            <entry>
              <key>2001405</key>
              <account accountNo="2001405" currency="EUR" debit="25123.11" openingDate="2005-01-13 10:10:34"/>
            </entry>
            <entry>
              <key>2000123</key>
              <account accountNo="2000123" currency="EUR" debit="332.54" openingDate="2003-11-04 09:15:34"/>
            </entry>
          </data>
          ...
        </formresult>
      

      <formresult serial="1199702214819">
        ...
        <data>
          <account accountNo="2000123">
            <customer customerId="100000">
              <accounts>
                <account accountNo="2000000">
                  <customer xpathref="/formresult/data[1]/account[1]/customer[1]"/>
                </account>
                <account xpathref="/formresult/data[1]/account[1]"/>
                <account accountNo="2001405">
                  <customer xpathref="/formresult/data[1]/account[1]/customer[1]"/>
                </account>
              </accounts>
            </customer>
          </account>
        </data>
        ...
      </formresult>
      

        public class FragmentBean {

            private String myFragment = "<foo><bar baz=\"true\"/>character data</foo>";

            @XMLFragmentSerializer
            public String getMyFragment() {
                return myFragment;
            }
        }
      

        <?xml version="1.0" encoding="utf-8"?>
        <result>
           <myFragment>
              <foo>
                 <bar baz="true"/>character data</foo>
           </myFragment>
        </result>
      

        ...
        import de.schlund.pfixcore.oxm.impl.AnnotationAware;
        import de.schlund.pfixcore.oxm.impl.SimpleTypeSerializer;
        import de.schlund.pfixcore.oxm.impl.annotation.StringSerializer;
        ...

        public class StringTypeSerializer implements SimpleTypeSerializer, AnnotationAware {

          private boolean doLowerCase;
	
          public void setAnnotation(Annotation annotation) {
            StringSerializer s=(StringSerializer)annotation;
            doLowerCase=s.value();
          }
		
          public String serialize(Object obj, SerializationContext context) throws SerializationException {
            if(obj instanceof String) {
              String str=(String)obj;
              if(doLowerCase) str=str.toLowerCase();
              else str=str.toUpperCase();
              return str;
            } 
            throw new SerializationException("Illegal type: "+obj.getClass().getName());
          }
        }
      

        ...
        
        @SimpleTypeSerializerClass(StringTypeSerializer.class)
        @Target({ElementType.METHOD,ElementType.FIELD})
        @Retention(RetentionPolicy.RUNTIME)
        public @interface StringSerializer {
          boolean value();
        }
      

      public class Customer {
        ...
        @StringSerializer(false)
        public String getLastName() {...}
      }
      

      public class Customer {
        ...
        public long getCustomerId() {...}
        public String getFirsstName() {...}
        public String getLastName() {...}
        public List<Account> getAccounts() {...}
        ...
      }
      

      public class CustomerTypeSerializer implements ComplexTypeSerializer {

        public void serialize(Object obj, SerializationContext context, XMLWriter writer) throws SerializationException {
          if(obj instanceof Customer) {
            Customer customer=(Customer)obj;
            writer.writeStartElement("name");
            writer.writeCharacters(customer.getFirstName()+" "+customer.getLastName());
            writer.writeEndElement("name");
            context.serialize(customer.getAccounts(),writer);
          } else throw new SerializationException("Illegal type: "+obj.getClass().getName());
        }
       
      }
      

      @ComplexTypeSerializerClass(de.schlund.pfixcore.example.bank.oxm.CustomerTypeSerializer.class)
      @Target({ElementType.METHOD,ElementType.FIELD})
      @Retention(RetentionPolicy.RUNTIME)
      public @interface CustomerSerializer {}
	  

      public class Account {
        ...
        @CustomerSerializer
        public Customer getCustomer() {...}
        ...
      }
      

      <formresult serial="1199705488403">
        ...
        <data>
          <account accountNo="2000000" balance="3124.49" currency="EUR" openingDate="2003-10-23 08:05:22">
            <customer>
              <name>Mike Foo</name>
              <account accountNo="..."/>
              <account accountNo="..."/>
              ...
            </customer>
          </account>
        </data>
        ...
      </formresult>
      

The annotation-based IWrapper creation provides an alternative to the usual, XML configuration based, IWrapper creation. Using this approach you create IWrappers from standard Java Beans by adding the necessary configuration data in the form of annotations.

The IWrappers are automatically created during the build process using the Sun JVM's apt tool and a custom AnnotationProcessor which analyzes the Java bean's source code and generates the according IWrapper sources.

You're making a bean to a template for an IWrapper by adding an @IWrapper annotation to its class declaration. By default every bean property that is of a so-called builtin type, i.e. has a pre-defined IWrapperParamCaster implementation, will be automatically added as an IWrapper parameter.

Builtin types are boolean, byte, double, float, int, long, java.lang.Boolean, java.lang.Byte, java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.String, java.util.Date and Arrays with components of these types.

Bean properties of an unknown type are either ignored or require a @Caster annotation specifying an appropriate caster. Bean properties can be annotated at their getter methods or at the field itself, if it's public. If a property of a builtin type should be skipped you can mark the according property with a @Transient annotation.

Bean based IWrappers can be used to create new beans or fill existing beans with the IWrapper's state. Therefore the IWrapperToBean class provides the two static methods <T> T createBean(IWrapper wrapper, Class<T> beanClass) and populateBean(IWrapper wrapper, Object obj).

        @Target(ElementType.TYPE)
        @Retention(RetentionPolicy.RUNTIME)
        public @interface IWrapper {
          String name() default "";
          Class<? extends IHandler> ihandler() default IHandler.class;
        }
        
        @IWrapper(name="MyBeanWrapper",ihandler=MyBeanHandler.class)
        public class MyBean {
          ...
        }
      

        @Target({ElementType.METHOD,ElementType.FIELD})
        @Retention(RetentionPolicy.RUNTIME)
        public @interface Param {
          String name() default "";
          boolean mandatory() default true;
          boolean trim() default true;
          String missingscode() default "";
          String[] defaults() default {};
        }
        
        @IWrapper(name="MyBeanWrapper",ihandler=MyBeanHandler.class)
        public class MyBean {
          ...
          @Param(name="MyValue",mandatory=false)
          public int getValue() {...}
        }
      

        @Target({ElementType.METHOD,ElementType.FIELD})
        @Retention(RetentionPolicy.RUNTIME)
        public @interface Caster {
          Class<? extends IWrapperParamCaster> type();
          Property[] properties() default {};
        }
        
        @IWrapper(name="MyBeanWrapper",ihandler=MyBeanHandler.class)
        public class MyBean {
          ...
          @Caster(type=SomeClassCaster.class)
          public SomeClass getValue() {...}
        }
      

        @Target({ElementType.METHOD,ElementType.FIELD})
        @Retention(RetentionPolicy.RUNTIME)
        public @interface Property {
          String name();
          String value();
        }
      

        @Target({ElementType.METHOD,ElementType.FIELD})
        @Retention(RetentionPolicy.RUNTIME)
        public @interface PreCheck {
          Class<? extends IWrapperParamPreCheck> type();
          Property[] properties() default {};
        }
        
        @IWrapper(name="MyBeanWrapper",ihandler=MyBeanHandler.class)
        public class MyBean {
          ...
          @PreCheck(
            type=de.schlund.pfixcore.generator.prechecks.RegexpCheck.class,
            properties={
              @Property(name="regexp",value="/^(M|L|XL)$/")
            }
          )
          public String getValue() {...}
        }
      

        @Target({ElementType.METHOD,ElementType.FIELD})
        @Retention(RetentionPolicy.RUNTIME)
        public @interface PostCheck {
          Class<? extends IWrapperParamPostCheck> type();
          Property[] properties() default {};
        }
        
        @IWrapper(name="MyBeanWrapper",ihandler=MyBeanHandler.class)
        public class MyBean {
          ...
          @PostCheck(
            type=de.schlund.pfixcore.generator.postchecks.IntegerRange.class,
            properties={
              @Property(name="range",value="0:2")
            }
          )
          public int getValue() {...}
        }
      

        @Target({ElementType.METHOD,ElementType.FIELD})
        @Retention(RetentionPolicy.RUNTIME)
        public @interface Transient {}
        
        @IWrapper(name="MyBeanWrapper",ihandler=MyBeanHandler.class)
        public class MyBean {
          ...
          @Transient
          public int getValue() {...}
        }
      

FireDebug is a JAVA implementation of FirePHP for Pustefix. It enables you to send log messages to Firefox and display them via FireBug. You can find more informations about FirePHP at http://www.firephp.org.

<context defaultflow="DefaultFlow">
  <resource class="org.pustefixframework.util.firedebug.FireDebugImpl">
    <implements class="org.pustefixframework.util.firedebug.FireDebug" />
  </resource>
</context>

FireDebug firePHP = (FireDebug) getContextResource(FireDebug.class);        
firePHP.log(a * b, "Multipliziere a(" + a + ") * b(" + b + ")");

<pagerequest name="Calculator">
  <state class="org.pustefixframework.util.firedebug.FireDebugEnabledState" />
</pagerequest>

<servlet name="webservice">
  <active>true</active>
  <class>de.schlund.pfixcore.webservice.WebServiceServlet</class>
  <propfile>ajax-calculator/conf/webservice.conf.xml</propfile>
  <use-filter>FirePHPServletFilter</use-filter>
</servlet>