A target is everything that is the result of a XSLT transformation as seen in Figure 2.3, “Recursive XSL transformations”. It is also obvious that a target can be used to create new targets. For the sake of completeness, the initial XML or XSL files that are used in transformations are called targets, too.

The Pustefix system knows different types of targets:

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:

  
  <properties
    xmlns="http://www.pustefix-framework.org/2008/namespace/properties-config"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pustefix-framework.org/2008/namespace/properties-config http://www.pustefix-framework.org/2008/namespace/properties-config.xsd">
    
    <prop name="statuscodefactory.messagefile">common/dyntxt/statusmessages.xml</prop>
  </properties>
  
        

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. Pustefix allows to customize the creation of the property files using the mechanism described in Section 3.2, “Customization tools”.

You may reference customization variables in property values using the syntax ${variableName}. For example ${fqdn} will be replaced by the fully qualified domain name of the machine.

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 3.3.1, “XML property files syntax”.

The syntax of the common/conf/pustefix.xml file complies to the description in Section 3.3.1, “XML property files syntax”. 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?

The projects.xml file contains global settings for Apache HTTPd, Tomcat and Pustefix itself.

<global-config xmlns="http://www.pustefix-framework.org/2008/namespace/project-config">
  
  <!-- prefix to namespace url mappings to be used in pages xml -->
  <namespaces>
    <namespace-declaration prefix="pfx" url="http://www.schlund.de/pustefix/core"/>
    <namespace-declaration prefix="ixsl" url="http://www.w3.org/1999/XSL/Transform"/>
  </namespaces>
  
  <http-server>
    <tomcat>
      <minprocessors>100</minprocessors>
      <maxprocessors>500</maxprocessors>
      <connectorport>8009</connectorport>
      <debug>0</debug>
      <loglevel>info</loglevel>
      <jkhost>${fqdn}</jkhost>
      <!-- This is only for mod_jk A matching sample workers.prop file will be generated, but may need -->
      <!-- additional customization. Clustering will not work out of the box. -->
      <jkmount>router</jkmount>
      <defaulthost>sample1.${fqdn}</defaulthost>
      <jvmroute>foo</jvmroute>
    </tomcat>
    <apache>
      <logdir>pfixroot:/servletconf/log</logdir>
    </apache>
  </http-server>
  
  <application>
    <static>
      <path>common/img</path>
      <path>core/img</path>
      <path>core/script</path>
    </static>
  </application>
  
</global-config>

     

The namespaces section declares namespace prefixes, which are available when editing include parts in the Pustefix CMS. You can set the exclude-result-prefix to true in order to exclude the namespace declaration from XHTML output sent to the browser.

The http-server section specifies various settings for Apache Tomcat and Apache HTTPd. Usually you do not have to change these settings.

The application section is used to specify pathnames which contain static resources which should be made available to all projects.

The project.xml file contains references to all services and resources used by this project.

<project-config xmlns="http://www.pustefix-framework.org/2008/namespace/project-config">
  
  <project>
    <!-- Short project name, should equal the name 
         of the project directory                  --> 
    <name>projectname</name>
    <!-- Description shown in Pustefix CMS -->
    <description>Description for this project</description>
    <!-- 
      add
    <enabled>false</enabled>
      to make disregard this project when building the
      server configuration 
    -->
  </project>
  
  <editor>
    <!-- Set this to false to make the project disappear
         in the Pustefix CMS                             -->
    <enabled>true</enabled>
    <!-- Location of the Pustefix CMS, does not need to
         be changed usually                             -->
    <location>http://cms.${fqdn}/</location>
  </editor>
  
  <xml-generator>
    <!-- Path to the configuration file of 
         the TargetGenerator for this project -->
    <config-file>pfixroot:/projectname/conf/depend.xml</config-file>
  </xml-generator>
  
  <http-server>
    
    <!-- IP address and port Apache HTTPd (not Tomcat!) will
         listen on for HTTP connections                      -->
    <http-port>
      <address>${fqdn}</address>
    </http-port>
    
    <!-- IP address and port Apache HTTPd (not Tomcat!) will
         listen on for HTTPS connections                     -->
    <https-port>
      <address>${fqdn}</address>
      <ssl-key>pfixroot:/projectname/conf/server.key</ssl-key>
      <ssl-crt>pfixroot:/projectname/conf/server.crt</ssl-crt>
    </https-port>
    
    <!-- Name of the virtual host for this project -->
    <server-name>projectname.${fqdn}</server-name>
    <!-- Alias for the virtual host for this project -->
    <server-alias>projectname.${machine}</server-alias>
    
    <apache>
      <literal>
        <!-- Stuff that is copied to the Apache configuration -->
      </literal>
    </apache>
    
    <tomcat>
      <!-- Set this to true to enable extra context instances 
           for the virtual host created for this project      -->
      <enable-extra-webapps>false</enable-extra-webapps>
    </tomcat>
    
  </http-server>
  
  <application>
    
    <!-- Path that static resources will be delivered from -->
    <docroot-path>pfixroot:/sample1/htdocs</docroot-path>
    
    <!-- URI requests to / are redirected to -->
    <default-path>/xml/config</default-path>
    
    <!-- Only one context-xml-service may be specified per project -->
    <context-xml-service>
      <!-- URI the service will be available at -->
      <path>/xml/config</path>
      <!-- Path to the configuration file for the service -->
      <config-file>pfixroot:/projectname/conf/config.conf.xml</config-file>
    </context-xml-service>
    
    <direct-output-service>
      <!-- URI the service will be available at -->
      <path>/xml/download</path>
      <!-- Path to the configuration file for the service -->
      <config-file>pfixroot:/projectname/conf/direct.conf.xml</config-file>
    </direct-output-service>
    
    <!-- Extra paths for static resources -->
    <static>
      <path>sample1/img</path>
    </static>
    
    <!--  Custom Deplyment descriptor code
    <web-xml>
      <jee:web-app xmlns:jee="http://java.sun.com/xml/ns/javaee">
        <choose>
          <when test="$mode='test'">
            <jee:display-name>foo</jee:display-name>
          </when>
        </choose>
      </jee:web-app>
    </web-xml>
    -->
    
  </application>
  
</project-config>


      

As you can see, the configuration file consists of different sections: One for information about the project, one for configuring the Pustefix CMS, one for the server configuration and one for the application itself. The application consists of services and static resources. Please note that only one context-xml-service is allowed per project.

The depend.xml configuration file serves two purposes: First, it is used to create the hierarchical page structure of the project by defining a tree of pages. Then, it is used to define the internal structure of the pages by defining, for every single page, the tree of transformations that need to be applied to certain files to get the final stylesheet (which is the representation of the page in Pustefix). For an overview over the transformation aspect of the whole framework, please go here.

To make life a little easier, you can use convenience tags that are automatically transformed by the runtime system when the file is loaded.

<make project="MyProject" lang="en" themes="ThemeA ThemeB ... default">
  <navigation>
    <page name="foo" handler="/xml/static" accesskey="F">
      <page name="sub_foo1" handler="/xml/static"/>
      <page name="sub_foo2" handler="/xml/static"/>
    </page>
    <page name="bar" handler="/xml/config">...</page>
    
    <!-- Configuration fragements are supported as well -->
    <config-include file="myproject/conf/myfile.xml" section="navigation"/>
  </navigation>

  <!--
    The global section allows to set default values for ALL pages defined via the
    standardpage tag (see below). It's possible to set default params, and runtime
    stylesheets (see here). It's also possible to add more runtime stylesheets or
    overwrite params in the standardpage tag for a single page.
  -->
  <global>
    <param name="AName" value="AValue"/>
    <include stylesheet="path/to/AStyleSheet"/>
  </global>

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

  <!--
    The only other tags allowed besides the navigation tag are target, global,
    standardmaster, standardmetatags and standardpage. The latter three are only
    convenience tags that can be expressed fully in terms of target tags
    (Expanding those tags is one of the duties of the runtime transformation of
    the depend.xml file mentioned above).
  -->
  <target name="a_target_name.xsl" type="[xsl|xml]">...</target>
  <target name="another_target_name.xml" type="[xsl|xml]">...</target>...
  <standardmaster name="..."/>
  <standardmetatags name="..."/>
  <standardpage name="a_name" master="..."
                metatags="..." themes="..." variant="..."
                xml="a_base_xml_file.xml">
    ...
  </standardpage>
</make>

<target name="baz.xsl" type="xsl" page="foo" variant="bar" themes="Theme_A Theme_B ... default">
  <!--
    depxml and depxsl reference other targets by their name attribute
    that serve as the XML resp. XSL input used to create this target
    via a XSL transformation. If for a given name attribute of either
    depxml or depxsl no other target definition is found, the transformation
    parent is supposed to be a leaf target and the name attribute is 
    interpreted as a path relative to the docroot.
  -->
  <depxml name="foo/xsl/bar.xsl"/>
  <depxsl name="foo/xsl/baz.xsl"/>

  <!--
    Additional dependencies
  -->
  <depaux name="foo/xsl/snarf.xsl"/>
  <depaux name="foo/xsl/fubar.xsl"/>

  <!--
    param tags supply XSL transformation parameters that are used when the target is generated.
  -->
  <param name="AName" value="AValue"/>
</target>

<depaux name="foo/xsl/fubar.xsl"/>

<standardpage name="BazPage" master="AName" metatags="AName" xml="MyProject/xml/FooBase.xml" themes="Theme_A Theme_B ... default" variant="foo">
  <!--
    Note: All the child nodes are optional (and in fact usually not needed)
  -->
  <include stylesheet="MyProject/xsl/runtime.xsl"/>
  <param name="fubar" value="bar"/>
</standardpage>

<target name="BazPage::foo.xsl" type="xsl" themes="foo Target_A Target_B ... default" page="BazPage" variant="foo">
  <!--
    For every target that is only used in the generation of one single page
    (if you look at the example given here, this is true for the generated
    targets BazPage.xml and BazPage.xsl) you must give a parameter called page
    with the name of the resulting page as the value for the standard XSLT tags
    to be able to work correctly. They need this information e.g. to create links
    to other pages and many other things. While the standardpage tag does this
    automatically for you make sure that you don't forget it for target structures
    you define yourself.

    If the master attribute is not given, the depxsl will be master.xsl
  -->
  <depxml name="BazPage::foo.xml"/>
  <depxsl name="master-AName.xsl"/>
  <param name="page" value="BazPage"/>

  <!--
    parameters given to the standardpage tag are supplied to the first of the two
    transformations. The outputencoding parameter is inserted by the build system.
    Refrain from supplying this parameter on your own, unless you really know what
    you do. Changing the encoding should be done in the project.xml file.
  -->
  <param name="fubar" value="bar"/>
  <param name="outputencoding" value="UTF-8"/>

  <!--
    All include tags given are runtime stylesheets, given to the transformation via
    the parameter stylesheets_to_include (as a space separated list if multiple
    include tags are given). Note that the needed depaux nodes are inserted automatically.
  -->
  <param name="stylesheets_to_include" value="MyProject/xsl/runtime.xsl"/>
  <depaux name="/path/to/pustefix/projects/MyProject/xsl/runtime.xsl"/>
</target>

<target name="BazPage::foo.xml" type="xml" themes="foo Themes_A Themes_B ... default">

  <!--
    If the metatags attribute has not been given, the depxsl value is metatags.xsl  
  -->  
  <depxml name="MyProject/xml/FooBase.xml"/>
  <depxsl name="metatags-AName.xsl"/>

  <param name="fubar" value="bar"/>
  <param name="page" value="BazPage"/>
</target>

<standardmaster name="AName">
  <!-- The name attribute is optional -->
  <include stylesheet="MyProject/xsl/skin.xsl"/>
  <param name="AName" value="AValue"/>
</standardmaster>

<target name="master-AName.xsl" type="xsl">
  <!--
    If the name attribute of the standardmaster tag has not been given,
    the value for the target's name attribute will be master.xsl.
  -->
  <depxml name="core/xsl/master.xsl"/>
  <depxsl name="core/xsl/customizemaster.xsl"/>
  <depaux name="/path/to/pustefix/projects/core/xsl/default_copy.xsl"/>
  <depaux name="/path/to/pustefix/projects/core/xsl/include.xsl"/>
  <depaux name="/path/to/pustefix/projects/core/xsl/utils.xsl"/>
  <depaux name="/path/to/pustefix/projects/core/xsl/navigation.xsl"/>
  <depaux name="/path/to/pustefix/projects/core/xsl/forminput.xsl"/>
  <depaux name="/path/to/pustefix/projects/sample1/conf/depend.xml"/>
  <param name="AName" value="AValue"/>
  <param name="docroot" value="/path/to/pustefix/projects"/>
  <param name="product" value="MyProject"/>
  <param name="lang" value="en"/>
</target>

<standardmetatags name="AName">
  <!-- The name attribute is optional -->
  <include stylesheet="MyProject/xsl/metatags.xsl"/>
  <param name="AName" value="AValue"/>
</standardmetatags>

<target name="metatags-AName.xsl" type="xsl">
  <!--
    If the name attribute of the standardmetatags tag has not been given,
    the value of the name attribute here becomes metatags.xsl.
  -->

  <depxml name="core/xsl/metatags.xsl"/>
  <depxsl name="core/xsl/customizemaster.xsl"/>
  <depaux name="/path/to/pustefix/projects/core/xsl/default_copy.xsl"/>
  <depaux name="/path/to/pustefix/projects/core/xsl/include.xsl"/>
  <depaux name="/path/to/pustefix/projects/core/xsl/utils.xsl"/>
  <depaux name="/path/to/pustefix/projects/MyProject/conf/depend.xml"/>
  <depaux name="/path/to/pustefix/projects/MyProject/xsl/metatags.xsl"/>
  <param name="stylesheets_to_include" value="MyProject/xsl/metatags.xsl "/>
  <param name="AName" value="AValue"/>
  <param name="docroot" value="/path/to/pustefix/projects"/>
  <param name="product" value="MyProject"/>
  <param name="lang" value="en"/>
</target>

The ContextXMLService handles requests for all pages (where page means some content generated by an XSL transformation). The name of the configuration file is usually service.conf.xml where "service" is replaced by the name from the URI of the service. For example the configuration of the service available at /xml/info should use a configuration file named info.conf.xml.

This service 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.

  <context-xml-service-config
    xmlns="http://www.pustefix-framework.org/2008/namespace/context-xml-service-config"
  >
    <global-config>
      <force-ssl>false</force-ssl>
        

force-ssl can be set to true in order to enforce a secure connection for all pages of this service. The whole node is optional and defaults to false.

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

    </global-config>
    
    <context defaultpage="APageName" synchronized="true">
        

      <defaultpage>
        <variant name="VARIANTNAME">PAGENAME</variant>
        ...
        <default>PAGENAME</default>
      </defaultpage>
        

The defaultpage element can be used if you want to define multiple defaultpages for different variants. [Since: 0.13.1]

      <resource class="A_Resource">
        

class is mandatory, can be any Java class, that can be created with a default constructor. The scope attribute is optional and defines the scope in which the Spring bean representing the resource is instantiated. The bean-name attribute is optional and specifies the name of the Spring bean that is created for this resource. There may be multiple resource tags given.

        <implements class="A_Interface">
        

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

        </implements>
        <properties>
        

The whole node is optional.

          <prop name="A_Name">A_Value</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.A_Resource.A_Name=A_Value Customization tags may be used around a property to make it depend on a certain makemode or other parameters.

        </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="A_ROLE"/>
    <condition id="A_CONDITION"/>
    <authconstraint id="AN_AUTHCONSTRAINT"/>
        

You can define an arbitrary number of roles, conditions and authconstraints here, for details see Section 6.3, “Authentication and 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" 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.ConfigurableState interface. The used State is determined as follows:

You can use the scope attribute to specify the scope in which the Spring bean created for this page will be instantiated. You may specify the bean-name attribute to use a fixed name for the automatically created bean. You can use any BSF-supported scripting language for writing your State-implementation, too. Use script:path/to/script for the class attribute. Alternatively you can use an existing Spring bean that implements the de.schlund.workflow.State interface. Use the bean-ref attribute to specify the name of the bean. However the pagerequest may not contain any configuration if you are using a Spring bean.

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

        <wrapper prefix="AName" class="AClassName" checkactive="true|false"/>
        

	Caution
	Note: The tag name wrapper can also be called interface with the same allowed attributes for backwards compatibility reasons. This ambiguity may be removed in some future version.

There can be many wrapper nodes for a page. Each one references an "atomic" functional entity consisting of an IWrapper java class (usually autogenerated from a .iwrp xml file 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. There may be an optional scope attribute, which specifies the scope in which the handler associated with the wrapper will be instantiated.

Attribute	Description
prefix	Mandatory. The prefix defines a name for the IWrapper and in effect a namespace for the IWrapper's parameters. If the prefix "bar" is defined for an IWrapper that contains a parameter called "Foo", the submitted HTTP parameter must be called bar.Foo.
class	Mandatory. Must be the name of a java class implementing de.schlund.pfixcore.generator.IWrapper. This implicitly defines a de.schlund.pfixcore.generator.IHandler, as every IWrapper knows it's associated IHandler and can be queried for it.
checkactive	Optional, default is true. The IHandler method isActive() is NOT called on handlers with checkactive set to false. In other words: the handler is ignored when the system tries to find out if the page is accessible or not. See also the comment for the policy attribute above. Caution Replaces the activeignore attribute since version 0.13.1. You should be aware that setting activeignore to true now complies with setting checkactive to false. Support for the activeignore attribute will be removed in future versions.

      </input>
        

      <process>
        

The process node holds a list of actions, which can be referenced from the UI when submitting forms or using GET requests to transmitt data. These actions group IWrappers into two groups: those that should have their handleSubmittedData() method called, and those that should have their retrieveCurrentStatus() method called when a submit has been handled sucessfully (and the same page is redisplayed). The idea beind the latter is, that sometimes you want to update the submitted form data to some canonical form (e.g. adresses or similar), so you don't want to see the exact same input in the form elements as you have submitted it, but some changed values. In other cases, submitting data to one wrapper may change the values of the form elements of another wrapper - in this case the second wrapper needs to be listed under the <retrieve> node.

        <action name="a_name">
          <submit>
            <wrapper ref="a_prefix_1"/>
            <wrapper ref="a_prefix_2"/>
            ...
          </submit>
          <retrieve>
            <wrapper ref="a_prefix_1"/>
            <wrapper ref="a_prefix_X"/>
            ...
          </retrieve>
        </action>
        <action name="another_name">
        ...
        </action>
      </process>
      
      <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 3.4.6, “Configuration Fragments” 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 AbstractPustefixRequestHandler and AbstractPustefixXMLRequestHandler classes.

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

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 can use the DirectOutputService. The name of the configuration file is usually service.conf.xml where "service" is replaced by the name from the URI of the service. For example the configuration of the service available at /xml/info should use a configuration file named info.conf.xml.

The service 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 the navigation section of 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.

  <direct-output-service-config
    xmlns="http://pustefix.sourceforge.net/2004/properties"
  >    
    <global-config>
      <force-ssl>false</force-ssl>
        

See the comment for the global-config node in Section 3.4.3, “ContextXMLService configuration file”.

    </global-config>
    
    <authconstraint ref="AN_AUTHCONSTRAINT"/>
         

You can reference an authconstraint from the context configuration, which has to be fulfilled to access a page. This default authconstraint can be overridden for single pages. If no default authconstraint is set here, the context's default authconstraint will be used. If no authconstraint is set at all, a page requires no authentication.

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

Includes a part of a config-fragments at this location. See Section 3.4.6, “Configuration Fragments” 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"/>
        

The class specified for the directoutputstate must implement the de.schlund.pfixcore.workflow.DirectOutputState interface. The tag may have an optional scope attribute which specifies the scope in which the corresponding state should be instantiated. There may also be an optional bean-name which, if present, will be used as the name of the Spring bean created for this direct output state. Instead of the class attribute, you may specify a bean-ref attribute which has to reference a Spring bean defined in the spring.xml file for this project. In this case, no Spring bean will be created but the existing bean will be used instead.

      <authconstraint ref="AN_AUTHCONSTRAINT"/>
        

You can optionally reference an authconstraint from the context configuration to override the default authconstraint.

      <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>
  </direct-output-service-config>
        

The configuration of AJAX / webservices is described in the corresponding section.

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:c="http://www.pustefix-framework.org/2008/namespace/context-xml-service-config"
  xmlns:d="http://www.pustefix-framework.org/2008/namespace/direct-output-service-config"
  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>
    <c:resource class="com.example.MyResourceImpl">
      <pr:implements class="com.example.MyResource"/>
    </c: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>
    <c: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.

  </c:interceptors>
  <fr:scriptedflows>
    <c: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>
    <c:role name="MY_ROLE">
      <c:pageaccess names="mypage*"/>
    </c:role>
      

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

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

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

  </fr:pageflows>
  <fr:pagerequests>
    <c: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>
    <d:directoutputpagerequest name="foo">...</d:directoutputpagerequest>
      

Direct output pagerequests can be defined here. See Section 3.4.4, “DirectOutputService configuration file” for details on this.

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

For a html delivering page without frames:

<pfx:document xmlns:pfx="http://www.schlund.de/pustefix/core">
  <html>
    <!--
      Any content valid for an html document
    -->
  </html>
</pfx:document>

If you don't want to deliver html, just omit the <html> tag. The following could be used to implement a CSS stylesheet.

<pfx:document>.foo { color: #ffff00; font-family: Helvetica; }</pfx:document>

The rule of thumb is: Whatever you put between <pfx:document> is up to you and will be delivered just as you write it there. Just remember that the <html> is not automatically inserted for you, you have to write it yourself.

There are only subtle differences. A document is a Type 2 doc by definition whenever there is a <pfx:frameset> and possibly a <head> node as the only direct children of <pfx:document>.

<pfx:document xmlns:pfx="http://www.schlund.de/pustefix/core">
  <head>
    <!--
      Again, put anything you want to appear in the head of the _top frame! This means
      page title, script stuff or stylesheets.
    -->
  </head>
  <pfx:frameset rows="20,*">
    <pfx:frame name="navi">
      <html>
        <head>...</head>
        <body>
          <!-- Any HTML content -->
        </body>
      </html>
    </pfx:frame>
    <pfx:frame name="main">
      <html>
        <body>
          <!-- Any HTML content -->
        </body>
      </html>
    </pfx:frame>
  </pfx:frameset>
</pfx:document>

As you can see there is NO <html> tag just below <pfx:document>. This is the one important difference between Type 1) and Type 2). As a rule you could say that you only have to insert the <html> yourself wherever the "real" content is. In a Type 1) doc this is the whole content of the <pfx:document> tag, so we need to set it there. But for a Type 2) doc, the "real" content is the content of the <pfx:frame> tags, so you need to set it there.

The <pfx:button> tag is responsible for generating links to other pages inside the pustefix environment. In fact, it not always creates a link, but depending on the fact if the target page is accessible ("invisible") or not, or if the target page is the same as the current page ("active", aka "the target page is already active") it can display completely different content, and only when the target page is accessible and is different from the current page, a <a href="...">...</a> is put around it.

The template takes care of constructing the correct url with session information embedded and builds up valid, url encoded query strings.

<pfx:button page="APage" pageflow="AFlow" jumptopage="APage" jumptopageflow="AFlow" forcestop="true|false|step" startwithflow="true|false">
  <!--
    Control the submit commands
  -->
  <pfx:command page="APage" name="SELWRP">prefix</pfx:command>
  <pfx:argument name="AName">AValue</pfx:argument>
  <pfx:anchor frame="AFrame">AnAnchor</pfx:anchor>

  <!--
    These three optional child nodes can be used to display different
    content depending on the situation:
  -->
  <pfx:invisible>
    <!-- Displayed when link is not accessible -->
  </pfx:invisible>
  <pfx:normal>
    <!-- Displayed when link is accessible -->
  </pfx:normal>
  <pfx:active>
    <!-- Displayed when current page == link target -->
  </pfx:active>
  <!--
    Displayed link content
  -->
</pfx:button>

The <pfx:button> tag supports the following attributes:

Link contents

The pfx:button template allows you to change the link content depending on the status of the target page.

• Content of pfx:invisible will be only displayed when the target page is not accessible.

• Content of pfx:active will be only displayed when the target page is the current page.

• Content of pfx:normal will be only displayed when the target page is different from the current page and when it's accessible.

Content outside of these tags will be used in any case. If you only want to have different content for the invisible case, just put the content for the active and normal case inside pfx:normal, and add a pfx:invisible child with the differing content. The content of a pfx:normal node serves as the fallback for the other two cases.

	Note
	Note that only in the normal (regardless if the content comes from a dedicated pfx:normal child node or not) a link is put around the generated content.

Note also, that for differences between the three cases that can be expressed with CSS, you don't need to use these special child nodes. The system makes sure to use the three associated classes explained above to allow styling.

It is also possible to change to content, depending on whether a page has already been visited or not.

• Content of pfx:visited will be only displayed when the link has been already visited at least once in this session.

• Content of pfx:visited will be only displayed when the link has not been visited in this session.

The two tags above may also be put inside pfx:normal and pfx:invisible tags to express different content for accessible (or inaccessible) pages depending on the fact if they have been visited at least once already.

This makes of course not much sense with pfx:active, because a page where this applies is always the current page and by that is always visited.

This tag takes mostly the same attributes as <pfx:button>, but it only creates the URL and does not build up any content or generate a whole link. You can use this template if you just need the pure URL string.

When creating links to external URLs care must be taken to ensure that no sensitive data (especially the session ID) leaks into log files of remote servers via the referer header. To make sure that this can't happen, all links to external sites must be propagated via a special servlet, the de.schlund.pfixxml.DerefServer.

Every Pustefix project has this servlet configured to be accessible under the path /xml/deref. To make the handling of external URLs easier, there also exists a special tag <pfx:elink> that automates the creation of the correct link.

<pfx:elink href="http://some.host/location" target="_popup|SomeName">
  <!--
    Optional, use the <pfx:host> child instead of the href attribute whenever you
    need to construct the URL with additional code (e.g. from data only available
    at runtime)
  -->
  <pfx:host>...</pfx:host>

  <!--
    Optional, use as many of <pfx:argument> tags as you need to supply the
    parameters for the query string.
  -->
  <pfx:argument name="SomeName">...</pfx:argument>

  <!--
    Place content of the link here
  -->
</pfx:elink>

Include parts contain the content that is displayed on your pages. The parts are organized into include files. Every part has the same structure:

The children of the part tag are theme tags (at least one). The name attribute of the theme tag is the name of a theme as it is defined in the projects depend.xml.in file. Often these themes are just the project name or "default", which is used as the fallback when no more specific theme name matches (see here on how to define themes in the depend.xml.in file).

	Note
	Earlier versions of Pustefix had no special themeing, the only thing that was used was the project name itself and "default" as the fallback. Still today, the default value for the "themes" attribute in the root node of the depend.xml.in file (when not given explicitely) is just "<ProjectName> default", which makes the new system behave exactly as the old one did.

The resolution of the matching theme is done at the time the part is included (see below). Every page "knows" which themes are defined for it, and therefore it is possible to decide which product branch to use on generation time. The language on the other hand can be changed dynamically while the user clicks through the application, so the selection of the right language subtree (if more than one is present) is done at runtime.

<include_parts>
  <part name="Foo">
    <theme name="default">
      <pfx:langselect>
        <pfx:lang name="default">
          <!--
            The default content of part Foo goes here...
          -->
        </pfx:lang>
        <pfx:lang name="en_GB">
          <!--
            Default content in british english goes here...
          -->
        </pfx:lang>
        <pfx:lang name="en_*">
          <!--
            Default content in any other english language goes here...
          -->
        </pfx:lang>
      </pfx:langselect>
    </theme>
    <theme name="Theme_A">
      <!--
        The default content for theme Theme_A goes here...
      -->
    </theme>
  </part>

  <part name="Baz">
    <!-- Other parts -->
  </part>
</include_parts>

A part is referenced with two attributes: The filename of the include file that contains it, and the name of the part.

<pfx:include href="MyProject/txt/MyIncludefile" part="Foo" noerror="true|false" noedit="true|false"/>

Table 4.3. Attributes of the pfx:include tag

Attribute name	Mandatory?	Description
href	optional	If not given, it defaults to the current include part file
part	mandatory	The name of the part to include
noerror	optional	Defaults to false. Set this to true to imply that no warning sign should be generated when the include is not found. Only set this when you know what you do.
noedit	optional	Defaults to false. Set this to true to imply that this include part should not be editable via the pustefix editor. Only set this when you know what you do.

Using this tag results in the matching product branch of the include part to be inserted in place of the tag.

Looking at the example naturally leads to the question how it is possible to generate different pages with only a small number of structural xml files and always the same XSLT stylesheets. The answer is that at least one of the include parts isn't included via the pfx:include tag (which only handles static attribute values) but instead the filename of the include part is auto generated from the name of the page that is to be produced.

Looking at this page, one can see that the two transformations which produce BazPage.xml resp. BazPage.xsl have the page name supplied through the use of an XSLT transformation parameter. Using this parameter, the tag pfx:maincontent constructs an include request depending on the page name.

<pfx:maincontent part="content" path="MyProject/txt/pages" prefix="main_"/>

Table 4.4. Attributes of the pfx:maincontent tag

Attribute name	Mandatory?	Description
path	optional	If not given, but a XSLT parameter $maincontentpath has been defined in the depend.xml.in file, the value of the parameter is used. If there's even no $maincontentpath parameter, it defaults to PROJECTNAME/txt/pages
prefix	optional	defaults to main_
postfix	optional	defaults to .xml
part	optional	defaults to content

For the page "home" this is equivalent to <pfx:include href="MyProject/txt/pages/main_home.xml" part="content"/> and of course similar for every other page.

Starting with this page specific include, the content of the page can be included from many different include parts.

HTML <img> tags are usually not written directly, instead they are generated by using the <pfx:image> tag. Using this tag makes sure that the used image is registered in the runtime system as a dependency of the current target that's being generated.

One important feature of the <pfx:image> tag is that it inserts the natural height and width of the requested image unless they are explicitely given (as attributes width and height of course).

<pfx:image src="some/path/to/img.gif" themed-path="some/path" themed-img="img.gif"/>

Table 4.5. Attributes of the pfx:image tag

Attribute name	Mandatory?	Description
src	optional	The src path references an image in the file system. It must be given as a path relative to the docroot (typically this means something like MyProject/img/foo.gif. Note that you need to define an alias for the image directories in your project.xml config file for Apache to be able to find the image. Note that you can either specify the src attribute OR both of themed-path and themed-img
themed-path & themed-img	optional	These two attributes allow for themed images. The mechanism uses the same theme fallback queue as it is used for include parts. The algorithm to find the image to use is quite easy: Build an image path by concatenating themed-path, a / sign, the most specific theme, a / sign, and themed-img. Check if this image exists. If yes, use it as the src attribute for the resulting img tag. If not, take the next specific theme from the fallback queue (if it exists) and try again, until the image is found. Example: The themes fallback list is "foo bar default", themed-path is "MyProject/img" and themed-img is "test.gif". The image file names that are tried one after the other are MyProject/img/foo/test.gif MyProject/img/bar/test.gif MyProject/img/default/test.gif
other attributes	optional	All other attributes given (e.g. alt, width, height, title, etc. are copied unchanged into the resulting img tag

The creation of a html form is done with the help of the tag <pfx:forminput>. Most often you don't need to set any attributes, the defaults should work just fine.

<pfx:forminput send-to-page="APage" send-to-pageflow="APageFlow" frame="AFrameName" target="ATargetName" type="auth|data">
  <!-- place form elements here -->
</pfx:forminput>

Table 4.6. Attributes of the pfx:forminput tag

Attribute name	Mandatory?	Description
type	optional	Defaults to data. Must be set to auth, if the submitted information contains authentication data (e.g. userid, password).
target	optional	Defaults to the parent frame (if frames are used, current window otherwise)
frame	optional	This is used to select which named frame is about to be loaded into the target frame after submit. The default when frames are used is the parent frame. Most often you have to set neither frame nor target.
send-to-page	optional	Selects the page the submitted data is send to. Default is to use the current page. Most of the time, this is the right thing to do.
send-to-pageflow	optional	Should not be used. Selects the pageflow to use. Default is to not set a pageflow name explicitely, but let the backend reuse the current flow or select a matching one. Leave it that way if you don't know why you want to change it. If you want to select a pageflow to use, better do so via the submit button as explained below. Note that this mechanism will most likely not work when using the send-to-pageflow attribute here.

Make sure that all the other form related tags detailed below are contained inside a pfx:forminput block.

The form can be submitted by clicking on submit controls which can be realized in two ways: The simple html submit button is made with the tag <pfx:xinp type="submit">, while using an image as the submit control is done with <pfx:xinp type="image">.

A very useful ability of both submit controls is that it's possible to attach additional form parameters to them, that are only transmitted when that exact submit control is pressed. This way it's possible for a form to have two or more submit controls, each with different additional data attached and submitted, depending on which submit control the user clicks on.

pfx:xinp type="submit|image" pageflow="APageFlow" jumptopage="APage" jumptopageflow="APageFlow" forcestop="true|false|step">
  <!--
    Attach additional information to the controls
  -->
  <pfx:command page="APage" name="SELWRP">prefix</pfx:command>
  <pfx:argument name="AName">AValue</pfx:argument>
  <pfx:anchor frame="AFrame">AnAnchor</pfx:anchor>
</pfx:xinp>

Table 4.7. Attributes of form submit controls

Attribute name	Mandatory?	Description
type	mandatory	submit creates a simple html submit button, image uses an image as the submit button.
pageflow	optional	Used to explicitely set a pagflow to use after the submit has been handled sucessfully. Note that there is no corresponding way to set the page the submit is directed at, you need to set the send-to-page attribute of the pfx:forminput tag.
jumptopage / jumptopageflow	optional	If you don't want the pageflow mechanism to control which page to display as the next page after a successful submit, you can set this page via the jumptopage attribute. In this case, you also have the possibility to set the pageflow to use for this follow-up page and submit circle via the jumptopageflow attribute.
forcestop	optional	Default is false. If you don't want the pageflow mechanism control wether to stay on the current page after a successful submit or not, you can unconditionally force it to stay on the current page (when setting the attribute to true). Alternatively, if you want the pageflow mechanism to stop at most no more than one step further in the flow (e.g. a wizard like application) you can set this attribute to step.

When setting the type to image, you may also specify the attributes src, themed-path and themed-img. These attributes work exactly as described in Section 4.3.3, “Displaying images (<pfx:image>)”.

Command controls (like described in Section 4.4.2, “Submitting forms”) and links (like described in Section 4.2.1, “pfx:button”) can contain child tags that are used to pass additional data when the link or button is clicked.

<pfx:anchor frame="AFrame">AnAnchor</pfx:anchor>

<pfx:argument name="AName">AValue</pfx:argument>

<pfx:argument name="foo"><ixsl:value-of select="/formresult/bar"/><pfx:argument>

Commands

The <pfx:command> tag is used to explicitly select the wrappers to submit on a page.

 <pfx:command page="APage" name="SELWRP">prefix</pfx:command>

The content gives the prefix of the wrapper to select as defined on the target page.

	Note
	Note: If you don't give and selected wrappers, all wrappers defined on the target page become selected.

Table 4.10. Attributes of pfx:command

Attribute name	Mandatory?	Description
name	mandatory	The name of the command. Currently, the only non-deprecated command is the SELWRP command. This is used to select a wrapper with the matching prefix on the page that is designated by the page attribute (or the current page, when empty) as a wrapper that should be used for handling the data that is submitted. You can use more than one pfx:command to select as many wrappers as you want. Note: As this is the only command left, it is possible that the whole pfx:command stuff will go away, being replaced by e.g. an attribute of the submit control that holds all selected wrappers.
page	optional	Most often empty. This should be set to the page the request is directed at if it's not the current page.

Using these form element tags ensures that values, that are supplied by the backend application are used as values for the generated html form elements. This is done dynamically by generating the necessary ixsl: statements that will check the DOM tree for matching values and adding them as value attributes (text, password and hidden input fields) or content (text areas) or selecting them according to their value (check boxes, radio boxes, option menus).

Another thing these tags do is to automatically check if the runtime DOM tree contains an error attached to their name. In this case, the resulting html input field is augmented with special CSS classes to help with styling these fields depending on the state they have (error/no error).

Typically the CSS used when no attached error is detected is just the value of a class attribute given to the pustefix input tag. On the other hand, if an error is attached, the class attribute looks like this:

[@class] PfxError PfxInputTextError [PfxErrorLevel_$level]

where @class is the user supplied class attribute mentioned above (if it's there at all) and $level is an optional attribute of the error element in the runtime DOM tree. The example works the same for other input fields of the form <input type="...">, by replacing "Text" with "Password", "Check" or "Radio" (Hidden input fields are not visible anyway. Select menus and text areas don't need a special class as they can be easily selected via CSS rules. For the last two, the error CSS looks like this:

[@class] PfxError [PfxErrorLevel_$level])

<pfx:xinp type="text" name="AName" default="AValue" position="1|..|n" class="ACssClass">
  <!--
    name and default can also be set at runtime
  -->
  <pfx:default>
    <ixsl:value-of select="/some/runtime/value"/>
  </pfx:default>
  <pfx:name>
    <ixsl:value-of select="/some/runtime/name"/>
  </pfx:name>
 </pfx:xinp>

<pfx:xinp type="radio|check" name="AName" value="AValue" default="true|false" class="ACssClass">
  <pfx:name>
    <ixsl:value-of select="/some/runtime/name"/>
  </pfx:name>
  <pfx:value>
    <ixsl:value-of select="/some/runtime/value"/>
  </pfx:value>
  <pfx:default>
    <ixsl:value-of select="/runtime/true/or/false"/>
  </pfx:default>
</pfx:xinp>

<pfx:xinp type="select" name="AName" class="ACssClass" multiple="true|false">
  <pfx:name>
    <ixsl:value-of select="/some/runtime/name"/>
  </pfx:name>

  <!--
    One option tag per option that is available in the menu
  -->
  <pfx:option value="AValue" default="true|false">
    <pfx:value>
      <ixsl:value-of select="/some/runtime/value"/>
    </pfx:value>
    <pfx:default>
      <ixsl:value-of select="/runtime/true/or/false"/>
    </pfx:default>
  </pfx:option>
</pfx:xinp>

Errors in Pustefix come in two variants:

<pfx:checkerror level="AString">
  <!--
    Content to be displayed when any error with the matching level attribute is present in the
    runtime DOM tree. The level attribute is optional, when it's missing, any error will trigger
    the display of the content of the pfx:checkerror tag.
  -->
</pfx:checkerror>

<pfx:checkfield name="prefix.Name">
  <pfx:error>
    <!--
      Content that's displayed when an error associated to the form field referenced
      in the name attribute is present in the runtime DOM tree.
    -->
  </pfx:error>
  <pfx:normal>
    <!--
      Content that's displayed when no error associated to the form field referenced
      in the name attribute is present in the runtime DOM tree.
    -->
  </pfx:normal>
  <!--
    Content outside of the two child nodes is displayed in both cases.
  -->
</pfx:checkfield>

<tr>
  <pfx:checkfield name="addr.Street">
    <td class="{$pfx_class}">Street:</td>
  </pfx:checkfield>
  <td><pfx:xinp type="text" name="addr.Street"/></td>
</tr> 
<pfx:checkfield name="addr.Street">
  <pfx:error>
    <tr>
      <td colspan="2" class="{$pfx_class}">
        <ixsl:apply-templates select="$pfx_scode"/>
      </td>
    </tr>
  </pfx:error>
</pfx:checkfield>

<pfx:checkmessage level="AString">
  <!--
    Content to be displayed when any page message with the matching level attribute is
    present in the runtime DOM tree. The level attribute is optional, when it's missing,
    any page message will trigger the display of the content of the pfx:checkmessage tag.
  -->
<pfx:checkmessage>

<pfx:checkmessage level="AString">
  <pfx:messageloop>
    <!--
      This content is repeated for all the page messages that match the restrictions imposed by
      the parent's level attribute (or all page messages, if the attribute isn not given).
    -->
  </pfx:messageloop>.
</pfx:checkmessage>

You may face situations where you want to prevent, that the same form is submitted multiple times (e.g. by double-click, back button) or that a form, opened in a new window/tab, but already opened in another window/tab, can still be submitted from the old window/tab.

Using the <pfx:token> tag a hidden field with a random token is included into its parent form. The token is stored in the Context, keyed by a customizable name (by default pagename#elementid, which can be overwritten/replaced using the name attribute). After the form is submitted, the token is invalidated and submitting the form again causes the setting of a page message. Via the errorpage attribute you can optionally jump to an error page.

<pfx:forminput>
  <pfx:token errorpage="multisubmiterror"/>
  <!-- place form elements here -->
</pfx:forminput>

You should be aware that this mechanism depends on the caching behaviour of the used browser, e.g. for browsers, which don't cache but reload pages accessed via the back button, it can't prevent the repeated form submission, because the form in fact is a new instance and we can't detect or decide that the submit is illegal.

This mechanism by default only prevents forms with illegal tokens from being processed. If you want to ensure that form submits including no token will fail too, you can force this behaviour by setting the requirestoken attribute at the pagerequest's input element to true. This will force tokens for every form that's submitted to this page.

<contextxmlserver>
  <!--
    servlet config options
  -->
  <pagerequest name="...">
    <input requirestoken="true">
      <interface prefix="..." class="..."/>
    </input>
  </pagerequest>
</contextxmlserver>

The <pfx:checkactive> and <pfx:checknotactive> allow you to check from the XSL-stylesheet, whether a specific IHandler currently is active or not.

<pfx:checkactive page="APageName" prefix="AHandlerName">
  <!--
    Content to be displayed, if the handler is active
  -->
</pfx:checkactive>

Table 4.15. Attributes of the pfx:checkactive and pfx:checknotactive tags

Attribute name	Mandatory?	Description
page	optional	When using the page attribute, the content of the tag is only displayed if the referenced page is accessible. This is an easy way to display complete subparts of a page depending on the accessibility of another page.
prefix	optional	When using the prefix, the content of the tag is only displayed if a referenced handler on the current page is active. The prefix is the same name as used in the servlet property file for the handler. You can only use one of the attributes page and prefix.

The selection mechanism of <pfx:langselect> allows to select matching content anywhere inside a include part depending on the current language that is set in the running session. The <pfx:lang name="default"> tag is acting as the fallback for all languages that don't have a better, more specific named <pfx:lang> node.

<pfx:langselect>
  <pfx:lang name="en_*">...</pfx:lang>
  <pfx:lang name="en_GB">...</pfx:lang>
  <pfx:lang name="default">...</pfx:lang>
</pfx:langselect>

The system doesn't enforce but expects languages to be of the standard form of ISO language codes. In this case, a <pfx:lang> node with a name attribute ending in an asterisk (*) can be used to create a fallback for a whole "family" of languages. In the example above, the en_* node will serve as a fallback for all language codes starting with en_ except en_GB (which has a more specific node below).

The selection mechanism of <pfx:themeselect> allows to select matching content anywhere inside a include part depending on the same selection mechanism that is used to select the include part the first hand as described in Section 4.3.1, “Include parts (<pfx:include>)”

<pfx:themeselect>
  <pfx:theme name="ATheme">...</pfx:theme>
  <pfx:theme name="default">...</pfx:theme>
</pfx:themeselect>

Of course this makes most sense, when the containing include part uses a general theme, so there are specialized themes in the theme fallback queues to select from.

	Note
	This tag is only to be used in very special situations. Normally you would like to use different themes for the include part to register itself correctly with the runtime system.

Pustefix provides an edit-console and webservice-console that are helpful during debugging.

Those consoles can be included in your pages using the <pfx:editconsole> and <pfx:webserviceconsole> tags. The webservice-console may also be included within the editconsole using the following form: <pfx:editconsole webserviceconsole="true">.

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

The PustefixContextXMLRequestHandler does most of the request handling in an object called the "context". The interface Context provides the applications view on this object. From the applications view the context mainly is:

The context provides a de.schlund.pfixxml.SPDocument to the servlet. This class is a small wrapper around a org.w3c.Document and supplies the XML input document for the final transformation which produces the HTML output. Besides the DOM tree it contains the information the system needs to choose the right stylesheet for the desired page that is to be shown plus some other stuff like XSLT parameters that should be set for the transformation process. The Context doesn't produce the SPDocument itself but delegates this to the State's getDocument() method.

For the PageFlow interface there is currently only one implementation, and at the time of this writing it's not yet possible to change this implementation by supplying your own, although this is planned for the near future. The current implementation is called DataDrivenPageFlow, and it will be explained in more detail below. For the discussion presented here, it is sufficient to know the general PageFlow interface.

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

Both getName() and getRootName() return the name of the pageflow, the difference being that getName() contains the full qualified name (the root name together with any variant name, if present) while get RootName() only returns the root name.

containsPage(String pagename) must return true if the given page name is part of the page flow.

findNextPage(...) is more interesting. It implements the main duty of a page flow: To supply some sort of "next" page, given the context (in the form of a PageFlowContext which is just a stripped down version of the Context interface to only support getting information, but no changing the inner state of the context object), the information what the current page name is (currentpagename), and two flags:

The rest of the methods will be explained in more detail below.

The situation is different for States; Pustefix supplies implementations to cover most of the needs one may have in a normal application, however there are always situations where it is needed or at least much easier to write a specialized State instead of trying to re- or misuse one of the two "standard" implementations supplied with the framework.

These two implementations are StaticState and DefaultIWrapperState. The first is used for all static pages, i.e. pages that don't need to process any input parameters, but merely display more or less static content. The only dynamic thing this state can do is to include information from context resources into it's output DOM tree. The second one implements the concept of wrappers and handlers, which is the standard way in pustefix to handle input data.

Both of these states inherit from the abstract class StateImpl, a class that implements a bunch of helper methods useful for basically every conceivable state implementation. So it is strongly suggested to use this (or one of the two described states) as the base class for your own implementations.

While both of these states will be explained in detail below, it is important to note that the context only knows about states, not a special implementation of it. So on this level it makes no difference if a request supplies data to be processed, or if it only request the display of a certain page. So the only thing we need to know for this chapter is the interface all states have to implement:

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

These three methods are quite easy to explain. isAccessible(...) is used to check if a page is accessible (the exact wording would be "the associated State of the page", but we use page/state interchangeable here, as there is a n:1 association of pages to states anyway, i.e. every page has exactly one associated state, but most of the time many pages share the same state. States are singletons, so they don't store any data themselves. This allows to share them between many pages). getDocument(...) is the method that does all the work. Here we produce the result DOM tree that is used to render the final HTML page with. needsData(...) is (or better: can be) used only during page flow processing to determine what the next page is that needs to be shown. This method will be explained when we describe the PageFlow and it's default implementation in greater detail below.

During the request-response cycle, the Context maintains a set of variables that influence the processing of the request. These are listed in the following table. Use these as a reference to see how they can be set and changed, either by specifying values for them in the request (directly, or by referencing an action that sets them) or by calling a method of Context somewhere from Java code during the processing of the request.

The currentpageflow variable needs some more explanation, as in many cases, it is not given explicitly neither by submitting an action that specifies the page flow nor directly from the request parameter __pageflow. If this is the case, the Context tries to find a matching page flow by using the following algorithm.

In this section we want to explain the way the request cycle is handled in Pustefix by the Context and its peer objects (State, PageFlow) used during processing.

After the variables have been initialized, we have two different ways to go on. Either startwithflow is set to true, or not. The first case will be explained below in more detail, for now we assume that the value of startwithflow is false. We also do neglect some other aspects, that have to be taken care of during request processing: Role based authentication isn't mentioned here and also the fact that each State will always be asked if it is accessible before calling one of the other two methods won't be mentioned explicitly for the remainder of this explanation.

Despite all the explanation about States, most of the time one doesn't write States directly, but rather uses one of two predefined States (or trivial descendants of them).

IWrappers are used to store the request data that is used as input for corresponding IHandler classes. IWrappers are not explicitly written by the developer, but are generated from .iwrp files which contain a high level XML description of the parameter types and certain checks that should be applied to them. Each .iwrp file is translated into a .java file with the same name during the build process, and a java class is created. In the corresponding IHandler, you use the IWrapper to access or store data by calling the IWrapper's get and set methods.

The syntax of the .iwrp file is given below.

<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. The class attribute is
    mandatory. 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"/>
  <!--
    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;
}

Describe themes here.

Variants are a way to have the same page look and behave different depending on a variant id that can be set freely at runtime. This allows to select different look and behaviour depending on data collected during the user sesion.

<standardpage xml="MyProject/xml/frame.xml" name="Home" variant="foo:bar:baz">

Defining variants of pagerequests

Variants can also be used to create different implementations for the same pagerequest. This is done by a simple extension to the way a pagerequest is defined in the servlet configuration file.

<pagerequest name="foo">
  <default>
    [Any other tag that is allowed inside a pagerequest]
  </default>
  <variant name="var_id">
    [Any other tag that is allowed inside a pagerequest]
  </variant>
  <variant name="another_var_id">
    [Any other tag that is allowed inside a pagerequest]
  </variant>
 </pagerequest>

	Note
	You must give a <default> definition when using named variants. Each of the <default> and all <variant> definitions are self contained, full definitions of pagerequests. Nothing is shared between them.

Defining variants of pageflows

Variants can also be used to create different implementations for the same pageflow. This is done by a simple extension to the way a pageflow is defined in the servlet configuration file.

<pageflow name="fooFlow">
  <default>
    [Any other tag that is allowed inside a pageflow]
  </default>
  <variant name="var_id">
    [Any other tag that is allowed inside a pageflow]
  </variant>
  <variant name="another_var_id">
    [Any other tag that is allowed inside a pageflow]
  </variant>
</pageflow>

	Note
	You must give a <default> definition when using named variants. Each of the <default> and all <variant> definitions are self contained, full definitions of pagerequests. Nothing is shared between them.

See Section 4.5.2, “Displaying content based on the language” on more information on how the access the currently selected language in the presentation layer.

If your business logic needs to react to the currently selected language, you can retrieve the current language of the application via the getLanguage() : String of the Context.

The Context also provides a method setLangauge(String language), which allows you to change the selected language at run-time.

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, e.g. containing a login form. Login forms require the type attribute set to auth.

<pfx:forminput type="auth">
  ...
</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>

You can use this information to decide which information to display on the login page.

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

You can extend the authentication mechanism by providing custom conditions (additionally to the predefined conditions: hasrole, and, or, not). Therefore you just have to implement the Condition interface and register your implementation class in the context configuration file. Then your custom condition can be used within authconstraints, just as the builtin conditions and arbitrarily mixed with them.

public interface Condition {
    public boolean evaluate(Context context);
}

You have to implement the evaluate method, which returns if the condition is fulfilled. Therefore the evaluation logic can access the Context. Implementations shouldn't change the data model, perform fast and hold only immutable state (or be stateless).

The following example shows a condition which retrieves a ContextResource for a customer and checks if its debit exceeds a configured limit. The limit is automatically set to a value configured as property in the condition's configuration.

package example;

import de.schlund.pfixcore.auth.Condition;
import de.schlund.pfixcore.workflow.Context;
import example.ContextCustomer;

public class PremiumCustomerCondition implements Condition {
    
    private float limit;

    public boolean evaluate(Context context) {
        ContextCustomer contextCustomer=context.getContextResourceManager().getResource(ContextCustomer.class);
        return contextCustomer.getTotalDebit() >= limit;
    }
    
    public void setLimit(float limit) {
        this.limit = limit;
    }
    
}

Let's look how this condition is registered and used in the context configuration:

<condition id="isPremiumCustomer" class="example.PremiumCustomerCondition">
  <property name="limit" value="100000"/>
</condition>
  
<authconstraint id="..." authpage="...">
  <and>
    <hasrole name="..."/>
    <condition ref="isPremiumCustomer"/>
  </and>
</authconstraint>

Conditions are registered using top-level condition elements. They require an id and a class attribute. Authconstraints can reference conditions using condition elements with an according ref attribute.

Conditions can be checked from within XML/XSL using the pfx:condition function, e.g.:

<ixsl:if test="pfx:condition('isPremiumCustomer')">
  ...
</ixsl:if>

Roles by default are configured within the context configuration. As an alternative approach you're able to plug-in your own RoleProvider implementation. Thus you can provide roles programmatically or from another source.

You just have to implement the RoleProvider interface and register the implementation class in the context configuration.

public interface RoleProvider {
    public Role getRole(String roleName) throws RoleNotFoundException;
    public List<Role> getRoles();
}

The getRole method returns a Role object by name. The getRoles method returns a list of all available roles.

public interface Role {
    public String getName();
    public boolean isInitial();
}

Role objects can either be created by implementing the Role interface or by using the default implementation de.schlund.pfixcore.auth.RoleImpl. Role implementations have to return a unique name and if they should be initially set.

The following example shows a simple RoleProvider implementation, which holds the roles in a programmatically filled map.

public class MyRoleProvider implements RoleProvider {
    private Map<String, Role> roles;

    public MyRoleProvider() {
        roles = new HashMap<String, Role>();
        Role role = new RoleImpl("ADMIN", false);
        roles.put(role.getName(), role);
    	...
    }

    public Role getRole(String roleName) throws RoleNotFoundException {
        Role role = roles.get(roleName);
        if(role == null) throw new RoleNotFoundException(roleName);
        return role;
    }

    public List<Role> getRoles() {
        return new ArrayList<Role>(roles.values());
    }
}

The RoleProvider implementation is registered using the context configuration top-level roleprovider element with a class attribute. You can optionally configure properties, which will be automatically injected into the RoleProvider instance using according setter methods (Spring bean-style setter injection).

<roleprovider class="example.MyRoleProvider">
  <property name="..." value="..."/>
</roleprovider>

You should be aware that the current mechanism doesn't support dynamic RoleProviders. The provided roles have to be constant, i.e. they're read at application startup time and aren't updated at a later time.

Spring-managed services are configured as part of the Spring configuration. You can export an arbitrary bean as webservice using the webservice element (from the http://pustefixframework.org/schema/webservices namespace). Therefor you have to reference it using the ref attribute and set a unique servicename.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ws="http://pustefixframework.org/schema/webservices"
       xmlns:aop="http://www.springframework.org/schema/aop"
       xsi:schemaLocation="
            http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
            http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-2.5.xsd
            http://pustefixframework.org/schema/webservices http://pustefixframework.org/schema/webservices/pustefix-webservices.xsd">

  <bean id="MyBeanId" class="mypackage.MyBean" scope="session">
    <aop:scoped-proxy/>
  </bean>
  
  <ws:webservie
    id="Webservice_MyBean" 
    servicename="MyBean" 
    interface="MyBeanServiceInterface"
    ref="MyBeanId" 
    protocol="ANY"
  />
 
</beans>
      

You can optionally set an interface which defines the methods which should be exported (by default all public methods are exported, if you're using SOAP/JAXWS you can also exclude methods using the @WebMethod(exclude=true) annotation). Using the protocol attribute you can set the webservice protocol (default is JSONWS, other options are SOAP or ANY).

The webservice configuration file PROJECTNAME/conf/webservices.conf.xml contains global settings for the runtime system, default settings for webservices, and optionally webservice-specific settings. If you're using Spring-managed services only, you can ignore the webservice-specific settings in this file as they're done as part of the Spring configuration. The global and default settings are applied to the managed services too.

<webservice-config schemaLocation="http://pustefix.sourceforge.net/wsconfig200401 ../../core/schema/wsconfig200401.xsd"
  xmlns="http://pustefix.sourceforge.net/wsconfig200401"
  xmlns:xsi="xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <!--
    The webservice-global section contains general configuration options, which are applied to
    all webservices. Some of the options can be overridden individually for single webservices.
  -->
  <webservice-global>

    <!--
      Set the path under which the webservice servlet is reachable (as defined in you project
      configuration)
      
      [Optional - Default: /xml/webservice]
    -->  
    <requestpath>/xml/webservice</requestpath>

    <!--
      Set if WSDL should be generated for SOAP-enabled webservices and where to store it (absolute path within
      the project's webapp directory)
      
      [Optional - Default: enabled="true" repository="/wsdl"]
    -->
    <wsdlsupport enabled="true" repository="/wsdl"/>

    <!--
      Set if Javascript stubs should be generated and where to store it (absolute path within the
      project's webapp directory - only for SOAP). The jsnamespace attribute controls what namespace
      prefix the generated Javascript should use (COMPAT: WS_, COMPAT_UNIQUE: WS_ for SOAP JWS_ for JSON,
      JAVA_NAME: full Java class name, other values are used as namespace themselves, dot-separated
      namespaces are supported too, code to setup the according JS context objects gets auto-generated)
      
      [Optional - Default: enabled="true" repository="/wsscript" jsnamespace="COMPAT"]
    -->
    <stubgeneration enabled="true" repository="/wsscript" jsnamespace="COMPAT"/>

    <!--
      Set which service protocol should be used. You can set a certain protocol (SOAP|JSONWS) or allow all
      protocols (ANY). If you choose to use JSONWS only, you should set the type to JSONWS to accelerate
      the build process, otherwise the SOAP stubs will be generated unnecessarily.
      
      [Optional - Default: type="JSONWS"]
    -->
    <protocol type="ANY"/>

    <!--
      Set which SOAP encoding style should be used. The best supported style is rpc/encoded.
      The server-side also supports other styles like rpc/literal and document/literal, but the client-side
      support for these styles is rudimentary.
      
      [Optional - Default: style="rpc" use="encoded"]
    -->
    <encoding style="rpc" use="encoded"/>

    <!--
      Set if the JSON representation of serialized Java beans should be augmented with
      type meta information (classhinting).
      
      [Optional - Default: classhinting="false"]
    -->
    <json classhinting="true"/>

    <!--
      Set if webservice requests need to have a valid HTTP/Pustefix-Session (servlet) or they should
      work without one too (none).
      
      [Optional - Default: type="servlet"]
    -->
    <session type="servlet"/>

    <!--
      Set the service object's scope. Scope application means that the service object is created only
      once and shared between all sessions, session, that it's created once per session, request, that
      it's created newly for each request.
      
      [Optional - Default: type="application"]
    -->
    <scope type="application"/>

    <!--
      Set if only https requests should be allowed.
      
      [Optional - Default: force="false"]
    -->
    <ssl force="true"/>

    <!--
      Set the identifier of the Context the services need to access (from /contextxmlserver/servletinfo/@name
      in your project's ContextXMLServer configuration file). Via synchronize you can control whether the service
      requests should be synchronized on the Pustefix Context (default is true).
      
      [Optional - Default: synchronize="true"]
    -->
    <context name="pfixcore_project:webservice::servlet:config" synchronize="true"/>


    <!--
      There are some options which should be configured differently in development and production mode.
      Therefor you can use the following choose/when elements (which are optional, you can just leave them out).
    -->
    <choose>
      <when test="$mode = 'prod'">
        <!--
          Set if admin tool should be available (see Development Tools).
          
          [Optional - Default: enabled="false"]
        -->
        <admin enabled="false"/>

        <!--
          Set if monitor tool should be available (see Development Tools).
          
          [Optional - Default: enabled="false"]
        -->
        <monitoring enabled="false"/>

        <!--
          Set if extensive logging should be enabled (i.e. logging of all request/response messages in
          pustefix-webservice.log).
          
          [Optional - Default: enabled="false"]
        -->
        <logging enabled="false"/>

        <!--
          Set a FaultHandler, which will process exceptions before they are sent to the client
          (see Exception Handling).
          
          [Optional - Default: none]
        -->
        <faulthandler class="de.schlund.pfixcore.webservice.fault.EmailNotifyingHandler">
          <param name="recipients" value="[email protected]"/>
          <param name="sender" value="[email protected]"/>
          <param name="smtphost" value="localhost"/>
        </faulthandler>
      </when>
      <otherwise>
        <admin enabled="true"/>
        <monitoring enabled="true" scope="session" historysize="10"/>
        <logging enabled="true"/>
        <faulthandler class="de.schlund.pfixcore.webservice.fault.LoggingHandler"/>
      </otherwise>
    </choose>
  </webservice-global>

  <!--
    Each service has to define name, interface and implementation. All other options are
    optional and inherited from the global section respectively. Some global options
    can be overridden here (stubgeneration, protocol, encoding, json, session, scope,
    ssl, context, faulthandler).
  -->

  <webservice name="Counter">
  
    <!--
      Set the service interface. [Mandatory]
    -->
    <interface name="de.schlund.pfixcore.example.webservices.Counter"/>

    <!--
      Set the service implementation class. [Mandatory]
    -->
    <implementation name="de.schlund.pfixcore.example.webservices.CounterImpl"/>
  </webservice>
  <webservice name="...">...</webservice>...
</webservice-config>

Pustefix provides a special exception handling mechanism for AJAX services. You can register predefined or custom FaultHandlers, which are automatically called before an exception is sent to the client. Thus you can filter exceptions, change them or do some logging or notification stuff.

There are three predefined FaultHandlers:

You are free to implement your own FaultHandler and register it with your services in the webservice configuration file. You just have to extend the abstract base class de.schlund.pfixcore.webservice.fault.FaultHandler and implement the abstract methods init() and handleFault(Fault). The Fault object methods getThrowable() and setThrowable can be used to get the thrown exception and to change or replace it.

You also can derive from one of the predefined handlers. E.g. you can extend the EmailNotifyingHandler by overriding the two methods public boolean isInternalServerError(Fault fault) and public boolean isNotificationError(Fault fault) to customize if error details should be hidden from the client and if a notification mail should be sent for certain exceptions.

Pustefix provides some tools, which can help you during the development process. It provides an admin and monitoring webinterface. The admin tool lists all registered services with their service methods. The monitoring tool shows a history of the last requests including the request and response messages.

You can access these tools by including the special tag <pfx:webserviceconsole/> (see Section 4.5.4, “Using the Pustefix console”) into your Pustefix page and enabling them in the global webservice configuration (as shown in the Configuration section: the admin and monitoring elements within the choose/when elements).

By the way, if any unexplainable problems occur, you're recommended to take a look into the logfile pustefix-webservice.log, where (if log4j log level is set to DEBUG) among other things the request and response messages are logged too.

Doing asynchronous webservice calls, you can choose between two different webservice callback mechanisms.

var service=new WS_Service();
var callback=function(result,requestid,exception) {
   if(exception) {
      ...
   } else {
      ...
   }
}
var requestid="...";
service.serviceMethod(arg0, arg1, ... , callback); //asynchronous with callback
service.serviceMethod(arg0, arg1, ... , callback, requestid); //asynchronous with callback and requestid

var object={
   serviceMethod: function(result,requestid,exception) {
      if(exception) {
         ...
      } else {
         ...
      }
   }
};
var service=new WS_Service(object); //instantiate service with callback object 
//optionally you can pass the scope object within 
var requestid="...";
service.serviceMethod(arg0, arg1, ...); //asynchronous
service.serviceMethod(arg0, arg1, ... , requestid); //asynchronous with requestid

        var service = new WS_Service(object, scope);

Supported Java types are:

Primitive, wrapper, String and Date types are mapped to their according Javascript counterpart (Number, Boolean, String, Date). Java beans are mapped to general Javascript objects with the according properties (there's no representation/simulation of the Java bean's type hierarchy, using JSON you optionally can enable classhinting, which provides every object instance with a special property - javaClass - containing the full Java class name).

The Java bean mapping mechanism supports both, so-called simple properties (having according getter and setter methods as defined in the Java Bean Specification) and public members (without access methods).

Additional Java types supported by JSON services:

Because of the restrictions of the JSON format, especially the absence of type information and the usage of builtin Javascript types (arrays for Lists, objects for Maps), the support for Lists and Maps itself is restricted: deserializing Lists to Java requires a parameterized type parameter and this type has to be instantiable (or be a parameterized List or Map itself), the same with Map values, Map keys have to be java.lang.String instances.

public class A {

    int foo;
    int bar;
    int baz;

    public int getFoo() {return foo;}
    public void setFoo(int foo) {this.foo=foo;}

    @Exclude
    public int getBar() {return bar;}
    public void setBar(int bar) {this.bar=bar;}

    public int getBaz() {return baz;}
    public void setBaz(int baz) {this.baz=baz;}

}

@ExcludeByDefault
public class A {

    int foo;
    int bar;
    int baz;

    @Include
    public int getFoo() {return foo;}
    public void setFoo(int foo) {this.foo=foo;}

    public int getBar() {return bar;}
    public void setBar(int bar) {this.bar=bar;}

    @Include
    public int getBaz() {return baz;}
    public void setBaz(int baz) {this.baz=baz;}                                                                                                           }

}

public class A {

    int foo;
    int bar;
    int baz;

    public int getFoo() {return foo;}
    public void setFoo(int foo) {this.foo=foo;}

    @Exclude
    public int getBar() {return bar;}
    public void setBar(int bar) {this.bar=bar;}

    public int getBaz() {return baz;}
    public void setBaz(int baz) {this.baz=baz;}
}

@ExcludeByDefault
public class B extends A {

    int hey;
    int ho;

    @Include
    public int getHey() {return hey;}
    public void setHey(int hey) {this.hey=hey;}

    public int getHo() {return ho;}
    public void setHo(int ho) {this.ho=ho;}

    @Override
    public int getBaz() {return super.getBaz();}

}

public class A {

    @Alias("mybaz")
    public int baz;
    int foo;

    @Alias("myfoo")
    public int getFoo() {return foo;}
    public void setFoo(int foo) {this.foo=foo;}

}

<bean-metadata xsi:schemaLocation="http://pustefix.sourceforge.net/bean-metadata http://pustefix.sourceforge.net/beanmetadata.xsd">
  <bean class="de.schlund.pfixcore.webservice.beans.A">
    <property name="foo" alias="myfoo"/>
    <property name="bar" exclude="true"/>
  </bean>
  <bean class="de.schlund.pfixcore.webservice.beans.B" exclude-by-default="true">
    <property name="hey"/>
  </bean>
</bean-metadata>

The default serialization process tries to produce relatively compact XML. Thus it favours attributes over elements and serializes so-called simple types, which can be represented as strings, into attributes where it's possible and makes sense, e.g. for bean properties.

Let's look at an example, which shows the serialization of a simple bean using bean and serializer annotations to customize the serialization behaviour:

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

Here you see how the bean's serialized to the ResultDocument within a ContextResource:

...
        
public class ContextAccountImpl implements ContextAccount {

    private Account account;
    ...

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

The resulting DOM fragment looks like this:

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

The data element is the ContextResource's root node as configured in the configuration file. Calling addObject with the additional account argument, the serialized bean isn't added directly to the data element, but an additional element is used. The bean's properties are serialized as attributes of this element.

The debit property is renamed to balance using the @Alias annotation. The comment property is excluded using the @Exclude annotation. The openingDate property is serialized using the built-in DateSerializer, which can be customized using the @DateSerializer annotation. Thus you can provide your own date format pattern (must be a pattern supported by java.text.SimpleDateFormat).

Only simple type properties, i.e. properties which can be serialized to string values, can be represented as attributes. If the Account bean would have an additional property customer of a bean type, e.g. a Customer class, this property would be serialized as a child element:

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

Collections and Arrays are represented using an element for each entry. The element name is derived from the the simple name of the entry's class (without package name and starting lowercase):

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

The element name can be changed using the @ClassNameAlias annotation, e.g. to rename the account element to bankaccount:

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

Maps are represented using an entry element for each map entry. Key and value are represented by child elements (whereas the element names are derived from the class names):

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

	Changing the tag name for map entries
	The tag name, that is used for the entries in the map can be changed using the @MapSerializer (see the section called “@MapSerializer”).

Circular object references are handled by adding a xpathref attribute to the according element. Its value is an absolute XPath expression referencing the according object's element:

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

In this example the Account bean has a reference to a Customer bean, which itself has a reference to all of its Accounts. You can see that all beans, which were already serialized (as ancestors in the tree) contain an according back-reference.

Pustefix already provides several XML serializers for common serialization tasks.

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>

If you don't like the default serialization mechanism or you use unsupported types, you can write your own serializers. There are two types of serializers: SimpleTypeSerializers, which can produce String values (e.g. for primitive types), and ComplexTypeSerializers, which can produce structured XML data (e.g. for bean types).

Implementing your own serializer just requires to implement the SimpleTypeSerializer or ComplexTypeSerializer interface and create a custom annotation to be able to attach your serializer to a bean property.

Let's look at an example of a SimpleTypeSerializer: a custom String serializer, which allows to configure if Strings should be ouput lower- or uppercase. Here's the implementation:

...
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());
    }
}

The serializer implements the SimpleTypeSerializer interface. Its serialize method checks if the passed object is of type String and calls toLowerCase or toUpperCase before returning the new String. The doLowerCase property controls which method is used. This property is set within the setAnnotation method. The method is defined in the AnnotationAware interface. This method is called by the framework after the serializer is instantiated and passes the annotation set at the according bean property. So you can access the configured values and configure your serializer. Let's look at the according annotation definition:

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

You have to annotate the custom annotation with a SimpleTypeSerializerClass annotation with the serializer class as value, make the annotation available to methods and fields using the @Target annotation and make it visible at runtime using the @Retention annotation. The rest of the annotation definition can be done according to your needs. In the example we just define a boolean property indicating if the String should be converted to lower- or uppercase. Here you see how the annotation is applied to serialize a customer's lastname as uppercase:

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

Let's look at an example of a ComplexTypeSerializer. We want to customize the serialization of a Customer bean: the firstName and lastName properties should be output together within a name element:

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

The serializer just implements ComplexTypeSerializer. We don't need to implement AnnotationAware because our annotation will have no parameter we may want to read:

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

The serialize method gets a XMLWriter object, which is used to write the name element. Then the passed SerializationContext is used to serialize the customer's accounts using the default serialization mechanism.

Finally we implement a custom annotation:

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

Here we apply the annotation to the Account bean's customer property:

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

Here's an excerpt of the resulting XML:

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

Every IWrapper configuration element known from the XML configuration has an annotation counterpart. Besides there are some special annotations like @IWrapper and @Transient. In the following we'll give a short overview of all avaible annotations:

        @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 {
          ...
        }
      

The @IWrapper annotation is used to mark a class as template for an IWrapper. The name attribute denotes the class name of the generated IWrapper class (without package). By default the bean name with the suffix Wrapper is used (and the same package). The ihandler attribute denotes the IHandler implementation class.

        @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() {...}
        }
      

The @Param annotation is used to mark a bean property as parameter and configure its name and all the other options known from the IWrapper XML configuration. This annotation is optional, leaving it out, the property name is used as name and the other attributes are set to their default values.

        @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() {...}
        }
      

The @Caster annotation denotes the caster implementation class. The nested properties attribute can be used to set properties via @Property annotations. That's the same as the cparam elements in the XML configuration (the params/properties are set using according methods prefixed with put_).

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

The @Property annotation is used as nested annotation within the properties array attribute of various annotations. It consists of simple name/value pairs.

        @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() {...}
        }
      

The @PreCheck annotation denotes the precheck implementation class with optional properties/parameters.

        @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() {...}
        }
      

The @PostCheck annotation denotes the postcheck implementation class with optional properties/parameters.

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

The @Transient annotation can be used to avoid that a bean property of a builtin type is made to an IWrapper parameter.

A scripted flow is started by using the special __scriptedflow=[FLOWNAME] parameter in the query string of a request URI. In this query string additonal parameters can be given which are then made available inside the script.

Scripted Flows are programmed using assorted statements which are explained here:

<interactive-request>
  <param name="thename">static text combined with <value-of select="$thevar"/> calculated text (if needed)</param>
  <param name="otherparam">other text</param>
</interactive-request>

<virtual-request page="thepage" dointeractive="false|true|reuse">
  <param name="thename">static text combined with <value-of select="$thevar"/> calculated text (if needed)</param>
  <param name="otherparam">other text</param>
</virtual-request>

<choose>
  <when test="...">
    <!-- ... -->
  </when>
  <when test="...">
    <!-- ... -->
  </when>
  <otherwise>
    <!-- ... -->
  </otherwise>
</choose>

Instead of providing a class name inside an IWrapper's IHander definition like this:

<ihandler class="de.schlund.pfixcore.example.TShirtHandler"/>

you can define that a file containing dynamic language code should be used as an IHandler. It's done like this:

<ihandler class="script:sample1/script/ScriptingTShirt.js"/>

... that's it! (see below under "Path Definitions" on details about difference between scripts under docroot and scripts placed in classpath).

Simply create a file containing the dynamic language code inside the docroot or the classpath.

If you want to script a State, then simply use the above definition format inside a pagerequest's state definition, like in the following example:

<pagerequest name="scriptingstate">
  <state class="script:sample1/script/ScriptingState?.bsh"/>
</pagerequest>

The following rules have to be considered, when scripting IHandlers and States alike.

You should override the void doFilter(HttpServletRequest, HttpServletResponse, FilterChain, Context) method to implement your own filter code. This code must either handle the request completely or has to call the doFilter() method on the FilterChain object to pass the request to the next instance in the filter chain. If you have to make sure that some code is always run after a request has been completely processed, you can wrap the call to doFilter() within a try{}...finally{} block.

	Overriding the init() method
	When overriding the init() method of the filter you have to make sure that they call the init() method of the base class.

The context instance provided by the base class is not fully initialized at this stage of processing. Basically only session focused methods are available. Calling a method not being available will result in an IllegalStateException being thrown.

Configuration of filters takes place in the Section 3.4, “Project configuration files”. Filter declarations are placed directly within the <project/> tag:

<filter name="filtername">
  <active>true</active>
  <class>my.filter.class</class>
  <foreigncontext>config</foreigncontext>
  <init-param>
    <param-name>myParam</param-name>
    <param-value>myValue</param-value>
  </init-param>
 </filter>

The name of the filter has to be unique within the whole project and is used in mappings. The filter is only considered active if the <active> tag contains the value true. The <class/> tag contains the fully qualified class name of the filter class. The <foreigncontext/> tag takes a reference to a ContextXMLServlet. The context instance of this servlet (if present within the session) will be provided to the filter code. In addition to that an arbitrary number (0..n) of <init-param/> tags can be used to pass configuration information to the filter. However the special parameter name "contextRef" is reserved and may not be used.

Mappings can be performed by adding a <use-filter>filtername</use-filter> tag within a <servlet> tag. This will force requests made to the servlet to be pre-processed by the servlet filter.

Mappings to URIs can be performed by adding a <filter-mapping/> tag to the project node of the configuration file. This filter-mapping tag uses exactly the same schema used in web application deployment descriptors.

The first (preferred) way is to place a JAR archive somewhere in the library path (usually lib/) that contains a special deployment descriptor. This deployment descriptor has to be named META-INF/pustefix-module.xml in order to be recognized by the Pustefix build system. This deployment descriptor is a XML file with the following format:

<module-descriptor
  xsi:schemaLocation="http://pustefix.sourceforge.net/moduledescriptor200702 http://pustefix.sourceforge.net/moduledescriptor200702.xsd"
  xmlns="http://pustefix.sourceforge.net/moduledescriptor200702"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  
  <!--
    The module name is used to construct the path the resources will be extracted to.
    In this example the path would be projects/modules/mytest/.
  -->  
  <module-name>mytest</module-name>
  <resources>
    <!--
      The srcpath attributes the directory within the JAR archive that contains the
      resources. The targetpath attribute is optional and specifies the path the
      resources are copied to (relative to the module directory). An empty targetpath
      (the default) specifies the module directory itself
      (e.g. projects/modules/mymodule) as the target directory.
    -->
    <resource-mapping srcpath="resources/txt" targetpath="txt"/>
    <resource-mapping srcpath="resources/images" targetpath="img"/>
  </resources>
</module-descriptor>

The old way is to place a JAR file in the modules/ directory of the Pustefix environment. In this case no deplyoment descriptor is needed (and even if present it is not read). However you have to ensure that all files within the JAR file are in a properly named directory as the archive will be directly extracted to the projects/modules/ directory.

	Deprecated
	It is not recommended to use these types of modules in Pustefix 0.12.x or higher. The the new way (see Section 7.1.1, “Resources within library JARs”) is much more powerful, we will drop support for the modules directory in a future Pustefix release.