The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at Mozilla Public License Version 1.1
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Original Code is Presenting XML.
The Initial Developer of the Original Code is Daniel Parker. Portions created by Daniel Parker are Copyright (C) 2003 Economic Technology, Inc. All Rights Reserved.
Contributor(s): Bob Bartholomay
Alternatively, the contents of this file may be used under the terms of the LGPL license (the "GNU LESSER GENERAL PUBLIC LICENSE") license, in which case the provisions of LGPL License are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of the LGPL License and not to allow others to use your version of this file under the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the LGPL License. If you do not delete the provisions above, a recipient may use your version of this file under either the MPL or the LGPL License.
Table of Contents
Table of Contents
Table of Contents
Presenting XML is an extendible, component-based framework for XML/XSLT applications that aims at achieving a complete separation of content from presentation. It supports styling XML content with XSLT stylesheets, as well as additional processing to other formats like pdf. It supports targeting different types of devices (e.g. browsers,handhelds) with different flavors of markup (e.g. HTML,WML.)
The promise of an XML/XSLT based approach to achieve separation of content and presentation is compelling. Many companies are moving in this direction, away from approaches like JSPs.
There are a number of frameworks out there that support publishing content styled with XSLT sheets. Apache Coccon is one that is well known in the open source community. Most existing approaches, however, do not allow for much richness in the way that XSLT sheets get selected to style content. Obviously required is the ability to choose stylesheets based on target device, but that is not enough.
Dynamic, interactive sites require a much richer way of selecting styleheets at runtime. The selection of a stylesheet may need to depend on parameters in the http request, and also on tags in the supplied XML content. A request may be for a summary or a detailed view; we may want to style the same content differently depending on the view requested. A request may be for dynamic content to be fed back from some remote resource; that request may fail, and we may end up needing to style error tags with an error sheet.
Presenting XML attempts to recognize the device and determine its supported MIME types, and then sends the request to the most conforming request handler. The request handler authenticates the request, and, if the request passes, assembles a pipeline for servicing the request. Alternate pipelines may be assembled based on tests of XPATH expressions matched on request parameters. Simple examples with XML, XSLT, and java are used to illustrate how this works.
The current version can be configured to work with any fully TrAX conformant XSLT transformer, including Saxon and Apache Xalan. The default configuration is for the Saxon XSLT transformer, the Apache Xerces XML parser, and the Apache fop pdf driver. Future versions will support any conformant XML parser.
Configuration is based on XML files.
Presenting XML provides a Model-View-Presenter framework for web applications that supports:
The nature of the model data itself is largely outside the scope of the Presenting XML pipeline framework; the content management layer merely specifies a way for transferring XML back to the presenter as SAX events. Where that content comes from is no business of the framework; it could come from Entity Java Beans, direct access to the database, or system files - the framework doesn't care.
The distribution provides components that implement adapters for certain kinds of content, including XML files, delimited and fixed length flat files, and SQL databases. It also provides a component that implements a more general adapter for user defined dynamic content.
The presenter gets back a representation of the data as a stream of SAX events. The presenter then needs to do something - perhaps style the XML source with an XSLT sheet and send the result back to a browser, or perhaps redirect the request to another url. These actions are described declaratively in a resources script.
Table of Contents
The full Presenting XML distribution may be obtained from https://sourceforge.net/projects/presentingxml/. It includes the source code and build files as well as binary jar files, a sample web application, and run scripts. It includes api documentation and a user guide. It also includes a number of third party jar files.
The directory layout under the top level presentingxml directory is as follows:
src/java - Directory containing the java source files for the Presenting XML framework.
src/docs - Directory containing the DocBook XML source files for documentation.
src/resources - Directory containing the startup.xml file for managing configuration.
modules - Directory containing the source code and third party jar files for optional modules.
docs - Directory containing javadoc and a user guide.
lib/ - Directory containing jar files that will be copied to the web server lib deployment directory.
lib/local - Directory containing your own jar files you want to use in a console app or web app.
lib/optional - Directory containing jar files copied during the build process from the modules/<module>/lib directories.
lib/servletapi - Contains the servlet.jar file used in building the distribution files.
tools/junit - Directory containing the junit jar file for the test suite.
tools/ant - Directory containing the ant jar files for the builds.
webapps/bookstore - Directory containing a sample web application.
consoleapps - Directory containing examples of running presentingxml from the command line.
tests - Directory containing junit tests.
build - Directory containing temporary files during the build process.
The following software components are not included and must be downloaded and installed separately:
Java development environment.
Servlet 2.2 compliant web server, such as Jakarta Tomcat
A WAP browser emulator.
Presenting XML requires Java JDK 1.3 or later (it will not work with earlier versions.) It has been tested with Sun's Java JDK 1.3.1, on Windows 2000 and on Linux.
You will need to configure your web server to work with Presenting XML. This section describes how to do that for Jakarta Tomcat 4.0.
The distribution files for the Jakarta Tomcat 4.0 web server may be obtained from http://jakarta.apache.org/site/binindex.html.
The steps to configure Jakarta Tomcat to work with Presenting XML are as follows:
Edit the server.xml file in the tomcat conf directory. Add the following Context element in the server.xml file (changing docBase as appropriate):
<Context path="/bookstore"
docBase="C:/Projects/presentingxml/webapps/bookstore"
debug="0"
reloadable="true" >
</Context>
Set the environmental variable JAVA_HOME to a version of the jdk 1.3 or above, i.e.
set JAVA_HOME=C:\tools\java\jdk1.3.1(changing C:\tools as appropriate), or add the above line to the top of the startup.bat file (tomcat.sh for Unix) in the jakarta tomcat bin directory.
Presenting XML requires a WAP browser emulator for viewing the sample WML pages. A free WAP browser emulator may be obtained from OPENWAVE.
Before building the sample web application, be sure to build the presentingxml project. From the command prompt in the top level presentingxml directory, enter build.
The webapps/bookstore subdirectory is the "document root" for a sample web application. It is set up to be compatible with the Web Application Architecture (WAR) standard. It has the following components:
config - Directory containing the presentingxml.xml configuration file.
pages - Directory containing the pages.xml file.
documents - Directory containing the document catalog and any system XML files.
styles - Directory containing the style catalog and the stylesheets.
java - Directory containing the java source files for the sample.
build - Directory containing temporary files during the build process.
WEB-INF/web.xml - The Web Application Deployment Descriptor for the sample application.
WEB-INF/lib - Directory that will contain the deployed jar files.
Set the environmental variable JAVA_HOME to a version of the jdk 1.3 or above, i.e.
set JAVA_HOME=C:\tools\java\jdk1.3.1(changing C:\tools as appropriate), or add the above line to the top of the build.cmd file (build.sh for Unix) in the webapps/bookstore directory.
Build the sample web application by entering build at the command prompt in the webapps/bookstore directory.
If everything has gone correctly you should now be able to run the sample web application.
Start the tomcat server by entering startup at the command prompt in the jakarta tomcat bin directory.
Open the following URL in a browser: http://localhost:8080/bookstore/pages/books
Now click on one of the categories in the left panel.
For a pdf example, under the Featured Books section in the left panel, click on "Pulp"
Finally, try opening the books URL http://localhost:8080/bookstore/pages/books in a WAP browser emulator.
Shutdown the tomcat server by entering shutdown at the command prompt in the jakarta tomcat bin directory.
The pages subdirectory contains the pages.xml file. The purpose of the pages.xml file is to define the pages that a client may request of the web server. Each request for a page has a specified source of XML content and the rules for styling that XML content. The source of XML content is represented by a document name. The rules for styling that XML content are specified by transform and serialize actions. A style attribute specifies which stylesheet to use.
The documents sub-directory contains the configuration file documents.xml. The purpose of the documents.xml file is to define sources of XML content and to give them names. A source of XML content need not exist as a document per se. It may exist as a java object which is capable of feeding start/end elements into a SAX 2 ContentHandler.
The documents.xml defines a source of XML content with a url (if it is really an XML file) or a request handler (if the data will be coming from a SAX source.)
There are two types of request handlers.
SelectHandler - Defines an interface for getting dynamic XML content (e.g. a document, results from a database query.) This content may be cached depending on the caching options in effect. An example is BookCatalog under the java/samples/books subdirectory.
UpdateHandler - Defines an interface for posting data values (e.g. updating values in a database.) A UpdateHandler may also return dynamic XML content. If it does, that content is never cached.
The WEB-INF/web.xml file is the Web Application Deployment Descriptor for the sample application.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
<servlet>
<servlet-name>presenter</servlet-name>
<servlet-class>com.presentingxml.presenter.http.PresenterServlet</servlet-class>
<load-on-startup>1</load-on-startup>
<init-param>
<param-name>appName</param-name>
<param-value>myapp</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>presenter</servlet-name>
<url-pattern>/pages/*</url-pattern>
</servlet-mapping>
</web-app>
Note the init-param element, which defines the name of the web app as "myapp."
Table of Contents
The purpose of a resources script is to provide a catalog of named pages that encapsulate a service of some kind. A page is associated with actions - transforming XML to HTML through the application of a stylesheet, serializing XML to PDF, transforming a flat file to XML, updating records in a database, and so forth.
A simple example is shown below.
Example 3.1. The Books Resources Script
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
xmlns:myapp="http://www.presentingxml.com/myapp"
ns="http://www.presentingxml.com/myapp">
<px:app>
<px:mapRequest>
<px:matchRequestURI match="/bookstore/pages/(.+)">$1</px:matchRequestURI>
</px:mapRequest>
</px:app>
<px:page name="books">
<px:parameter ns="" name="category"/>
<px:show>
<px:transform>
<px:content ref="myapp:books"/>
<px:style ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
<px:dynamicContent name="books" className="samples.books.BookCatalog">
<px:key>
<px:field name="category"/>
</px:key>
</px:dynamicContent>
<px:style name="books" href="html/books/books.xsl"/>
</px:resources>
Each element in the resources script has a prefix px:. The resources element associates the px: prefix with the Presenting XML namespace in the declaration xmlns:px="http://www.presentingxml.com/PresentingXML". In this way, the page, content and style elements are identified as belonging to Presenting XML, not to the author of the books content and stylesheet.
Note the px:app element at the head of the books resources script. The app element optionally contains a px:mapRequest element that defines the mapping of request URIs into page names. If no request mapper element is specified, the default is to look for a page with whatever namespace happens to be in scope and a local name the same as the request URI. In the example, we see a single px:matchRequestURI element that maps a request URI like /bookstore/pages/welcome into a page with namespace "http://www.presentingxml.com/myapp" and local name "welcome".
The books resources script defines a number of resources: a page, a document, and a style. These names belong to the author of the books resources. Each resource is given a name. A name has two parts, a local name and a namespace URI. The local name is specified by a name attribute. The namespace URI is specified by a ns attribute. If the element defining the resource does not specify a ns attribute, the namespace URI defaults to that of the nearest ancestor element that does have a ns attribute, or the empty string if there is none. In the books example, therefore, the page takes a local name "books" and the namespace URI "http://www.presentingxml.com/myapp". The prefix myapp: is associated with that namespace.
Pages are defined with the page element. In the books page element above, we see a page element that defines a response, which consists of a transform instruction applied to a document and a stylesheet. The consequence of this definition is that if a browser sends a request to the web server for the page named books, the document named "books" will be styled with the stylesheet named "books", resulting in an HTML page being returned to the browser.
Documents are defined with a content element. In the books example above, we see a px:dynamicContent element with a className attribute, associating the document "books" with the Java class sample.books.BookCatalog.
public class BookCatalog implements SelectHandler {
public void doRequest(PageContext context, Book parameters,
ContentWriter contentWriter) throws PresentingXMLException {
// Implementation
}
public long getLastModified(RuntimeContext context, Book key,
long timestamp, long elapsed) {
// Indicate changed if older than 10 seconds
return elapsed > 10000 ? timestamp : timestamp + elapsed;
}
}
The consequence of this definition is that when the document named "books" is accessed,
the doRequest method of the BookCatalog object is called.
The Presenting XML framework
is responsible for mapping request parameters to properties
declared in the Book interface; the
BookCatalog object is responsible for feeding start/end elements to the
SAX 2 ContentHandler.
Note that the doRequest method defined above takes a user defined interface Book as its second argument,
public interface Book {
public String getCategory();
}
The Presenting XML framework creates a proxy class that implements this interface at runtime.
If the HTTP request has the parameter category, the value of that parameter may be obtained
with the getCategory() method. The method signatures on the user defined parameters interface
need to follow the standard naming conventions for beans.
Stylesheets are defined with the style element. In the books example above, we see a px:style element with an href attribute, associating it with the relative url "html/books/books.xsl". By default this relative url is resolved relative to the location of the resources script. The base may be overriden with an xml:base attribute.
There are three kinds of elements that may appear in a resources script:
As the resources script becomes larger, it becomes desirable to reorganize it, splitting off document and style elements into separate files, in separate directories. For example, we may wish to have the directory tree:
pages - Directory containing the books pages.xml file.
documents - Directory containing the documents.xml file.
styles - Directory containing the styles.xml file, with subdirectories containing the actual stylesheets.
Example 3.2. The Reorganized Books Resources Script
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
xmlns:myapp="http://www.presentingxml.com/myapp"
ns="http://www.presentingxml.com/myapp">
<px:include href="../documents/documents.xml"/>
<px:include href="../styles/styles.xml"/>
<px:app>
<px:mapRequest>
<px:matchRequestURI match="/bookstore/pages/(.+)">$1</px:matchRequestURI>
</px:mapRequest>
</px:app>
<px:page name="books">
<px:parameter ns="" name="category"/>
<px:show>
<px:transform>
<px:content ref="myapp:books"/>
<px:style ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
</px:resources>
A pipeline body defines the sequence of steps applied to content to transform it into an XML stream for the serializer. A pipeline starts with content, passes it through a number of stages where it gets filtered and transformed, and finally hands it off to a serializer.
The simplest possible pipeline is a single px:content instruction. Such a pipeline simply passes the content "as is" to the serializer.
Consider the following pipeline body.
<px:transform>
<px:transform>
<px:systemContent href="documents/mixed-up.xml"/>
<px:saxFilter className="PreFilter"/>
</px:transform>
<px:style href="styles/filter.xsl"/>
<px:saxFilter className="PostFilter"/>
</px:transform>
This pipeline body may be thought of as a sequential process that executes from right to left. The inner transform is executed first. Here, the content mixed-up.xml is passed through the SAX filter PreFilter, and then streamed to the outer transform. In the outer transform, the result tree is first transformed with the XSLT stylesheet filter.xsl, and then passed through the SAX filter PostFilter, finally making its way to the serializer.
A pipeline body may have any number of nested transform stages. The innermost transform stage must contain a content instruction. Within a transform stage, there may be any number of filters and XSLT transformations that are executed in document order.
A filter performs processing on the XML tags at a lower stage before passing them on to a higher stage.
Presenting XML supports a rich variety of ways for selecting a pipeline body at runtime. Test expressions may be used to pick one of a number of candidate pipeline bodies based on the request parameters. The example below shows a page that is styled differently depending on whether the HTTP request has a parameter named "category."
Example 3.3. The Books Resources Script with Choices
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
xmlns:myapp="http://www.presentingxml.com/myapp"
ns="http://www.presentingxml.com/myapp">
<px:include href="../documents/documents.xml"/>
<px:include href="../styles/styles.xml"/>
<px:app>
<px:mapRequest>
<px:matchRequestURI match="/bookstore/pages/(.+)">$1</px:matchRequestURI>
</px:mapRequest>
</px:app>
<px:page name="books">
<px:parameter ns="" name="category"/>
<px:show>
<px:choose>
<px:when test="$category">
<!-- request has parameter category -->
<px:transform>
<px:style ref="myapp:books"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:when>
<px:otherwise>
<!-- request does not have parameter category -->
<px:transform>
<px:style ref="myapp:welcome"/>
<px:content ref="myapp:request"/>
</px:transform>
</px:otherwise>
</px:choose>
</px:show>
</px:page>
</px:resources>
The syntax for a test expression is a small subset of the syntax for an XPath expression, including the parts that make sense for testing parameter values.
Examples of test expressions are shown below.
A serializer takes the output of a transformer - an XML or HTML tree - and serializes it to a byte stream before sending it back to the client device. The default serializer simply transforms the tree to text and sends that back as a byte stream.
The example below illustrates the use of a serializer to produce a pdf document:
Example 3.4. A Serializer to Produce PDF
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
xmlns:myapp="http://www.presentingxml.com/myapp"
ns="http://www.presentingxml.com/myapp">
<px:app>
<px:mapRequest>
<px:matchRequestURI match="/bookstore/pages/(.+)">$1</px:matchRequestURI>
</px:mapRequest>
</px:app>
<px:page name="pulp">
<px:clientOptions caching="yes"/>
<px:cachingOptions caching="yes" revalidate="synch"/>
<px:show>
<px:fopSerializer/>
<px:transform>
<px:style ref="myapp:novel-fo"/>
<px:content ref="myapp:pulp"/>
</px:transform>
</px:show>
</px:page>
<px:systemContent name="pulp" href="books/pulp.xml"/>
<px:style name="novel-fo" href="fo/books/novel.xsl"/>
</px:resources>
A serializer is defined with the serializer element. The example above uses the apache fop serializer.
The example below shows the "update-cart" page which updates a shopping cart in a Java UpdateCart object, adding a new book title, and then performs a client-side redirect to the "books" page. The URI of the "books" page is evaluated as an XPATH expression that can refer to any XML content generated in the pipeline that appears in its content, or to any parameters passed to the page.
<px:page name="update-cart">
<px:parameter ns="" name="category"/>
<px:parameter ns="" name="bookId"/>
<px:parameter ns="" name="title"/>
<px:show>
<px:clientRedirect select="concat('/bookstore/pages/books?category=',$category)">
<px:dynamicContent className="samples.books.UpdateCart"/>
</px:clientRedirect>
</px:show>
</px:page>
Presenting XML uses the <xsl:output> element in the XSLT stylesheet to obtain information about the MIME type that the stylesheet produces. It is therefore important that the media-type attribute of the <xsl:output> element is assigned a value, for example "text/html" for HTML stylesheets and "text/vnd.wap.wml" for WML stylesheets.
The figure below shows the px:devices section in the system configuration file. It defines a number of known devices and the MIME-types they accept. It also defines maps from the HTTP User-Agent to the device. If the device can be identified, Presenting XML will use that information first. If the device cannot be identified, Presenting XML will use the HTTP accept header.
Figure 3.1. Device Configuration
<px:devices>
<!-- Define devices and accepted MIME types -->
<px:device name="explorer"
accept="text/html,application/pdf"/>
<px:device name="pocketexplorer"/>
<px:device name="handweb"/>
<px:device name="avantgo"/>
<px:device name="imode"/>
<px:device name="opera"/>
<px:device name="lynx"/>
<px:device name="java"/>
<px:device name="wap"
accept="text/vnd.wap.wml"/>
<px:device name="mozilla5"
accept="text/html"/>
<px:device name="netscape"
accept="text/html,application/pdf"/>
<!--
Map a pattern in the User-Agent to a device name.
A pattern may contain unix wildcards.
-->
<px:deviceMap search="MSIE" device="explorer"/>
<px:deviceMap search="MSPIE" device="pocketexplorer"/>
<px:deviceMap search="HandHTTP" device="handweb"/>
<px:deviceMap search="AvantGo" device="avantgo"/>
<px:deviceMap search="DoCoMo" device="imode"/>
<px:deviceMap search="Opera" device="opera"/>
<px:deviceMap search="Lynx" device="lynx"/>
<px:deviceMap search="Java" device="java"/>
<px:deviceMap search="(Nokia)|(UP)|(Wapalizer)" device="wap"/>
<px:deviceMap search="(Mozilla/5)|(Netscape6/)" device="mozilla5"/>
<px:deviceMap search="Mozilla" device="netscape"/>
</px:devices>
Note that the search attribute appearing in the px:deviceMap element can take regular expressions.
The following example shows how the same request URI may be mapped into different pages depending on the device and on the mime types that the device accepts.
Example 3.5. Device Configuration
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
xmlns:myapp="http://www.presentingxml.com/myapp"
ns="http://www.presentingxml.com/myapp">
<px:include href="../styles/styles.xml"/>
<px:include href="../documents/documents.xml"/>
<px:app>
<px:mapRequest>
<px:matchDevice device="explorer">
<px:matchRequestURI match="/bookstore/pages/(.+)">$1/explorer</px:matchRequestURI>
</px:matchDevice>
<px:matchDevice accept="text/html">
<px:matchRequestURI match="/bookstore/pages/(.+)">$1/html</px:matchRequestURI>
</px:matchDevice>
<px:matchDevice accept="text/vnd.wap.wml">
<px:matchRequestURI match="/bookstore/pages/(.+)">$1/wml</px:matchRequestURI>
</px:matchDevice>
</px:mapRequest>
</px:app>
<px:page name ="books/wml">
<px:parameter ns="" name="category"/>
<px:show>
<px:transform>
<px:style ref="myapp:books/wml"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
<px:page name ="books/html">
<px:parameter ns="" name="category"/>
<px:show>
<px:transform>
<px:style ref="myapp:books/html"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
</px:resources>
Suppose in this example we receive the request URI "/bookstore/pages/books".
If the sending device is recognized to be "explorer" according to the rules defined in the presentingxml.xml configuration file, the first request matcher attempts to resolve the request to a page with namespace "http://www.presentingxml.com/myapp" and local name "books/explorer". This fails, since there is no such page, The second request matcher then checks that the device accepts the mine type "text/html" (which it does) and also that there is a page having namespace "http://www.presentingxml.com/myapp" and local name "books/html", which there is.
If the sending device is unrecognized, and the HTTP accept header indicates that the device does not accept mime type "text/html", but does accept mime type "text/vnd.wap.wml", then the third request matcher will attempt to find a page having namespace "http://www.presentingxml.com/myapp" and local name "books/wml".
Table of Contents
The config subdirectory is found immediately beneath the document root. The configuration file presentingxml.xml is in the config folder. It contains a number of sections:
The transformer section species the jaxp transformer factory that is used. A jaxp transformer factory is any java class that implements the javax.xml.transform.TransformerFactory interface.
The device-map section defines a mapping of device descriptions (e.g. "MSIE") to device names (e.g. "explorer"). This roughly follows Cocoon's approach. Regular expressions are allowed for device descriptions.
The Presenting XML framework supports caching document, stylesheet and page resources. Whether or not a resource can be cached is configurable, and the way in which a resource becomes invalidated - asynchronously or synchronously - is also configurable.
For documents, the framework supports caching both
XML content read from system files, and
XML content generated dynamically through a SAX 2 ContentHandler.
Documents are optionally cached, depending on the settings in the px:cachingOptions element in scope when the documents are defined. Cached representations are built from the stream of SAX events when the document is initially loaded.
Stylesheets are cached as compiled Templates objects.
Pages are cached as text markup.
Two major issues in caching are object identity and cache entry invalidation:
How do we know that two requests are for the same cached node, particularly when the node has been generated dynamically?
How can we tell when an entry in the cache needs to be reloaded?
Caching has the result of improving performance but using up valuable memory. The final section describes the role of the cache manager in managing the memory resource, in ensuring that the cached nodes will not grow to the point of overwhelming the available memory.
A request for dynamic XML content comes with a document name and some parameters. The document name determines the RequestHandler used to handle the request. Different requests, of course, could come with different parameter values and so result in different nodes.
The notion of keys is used to assign an identity to what a RequestHandler writes into a ContentHandler. Keys are set up for dynamic content in the documents.xml file. A key consists of the document name and an ordered sequence of attributes that taken together assigns an identity to the XML content.
When a request for dynamic XML content comes in, the parameters are matched up by name with the attributes that make up the key. The matched parameter values are saved in the key object. These key objects are used to identify the dynamic resource.
If a request for dynamic content originates through a call to the document function in an XSLT stylesheet, an additional parameter may be added to the current parameter set by appending a ? to the document URL followed by a name/value pair.
Suppose, for example, that the key for some dynamic content is defined by the following entry in the documents.xml file:
<px:systemContent name="categories" className="books.CategoryHandler">
<px:key>
<px:field name="category"/>
</px:key>
</px:systemContent>
Now, suppose that the following document function call occurs in an XSLT stylesheet:
<xsl:value-of select="document('categories?category=S',/)//category/@desc" />
Then, the URI resolver that resolves the request for the url categories?category=S
will add a parameter named category to the current parameter set that has the value "S".
Table of Contents
There are three kinds of elements that may appear in a resources script:
A property element may appear anywhere in a resources script. The following elements fall into this category.
The example below shows two named resources (the px:content elements), and two properties (the px:cachingOptions elements.)
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML">
<px:cachingOptions caching="no"/>
<px:systemContent name="books" href="documents/books.xml"/>
<px:systemContent name="authors" href="documents/books.xml">
<px:cachingOptions caching="yes"/>
</px:systemContent>
</px:resources>
In this example, the default rule is set so that there is no caching of content. In particular, the books document is not cached. The authors document, on the other hand, is cached.
Any element, in addition to the attributes listed in the reference entries, may have the following attributes.
| Name | Mand. | Value | Description |
|---|---|---|---|
| ns | no | URI | The namespace of the resource. Defaults to the namespace in scope. |
Many of the elements listed below permit a pipeline body in their content. A pipeline body defines the sequence of steps applied to content to transform it into an XML stream for the serializer.
A pipeline body may contain one of the following elements:
Table of Contents
This reference provides an alphabetical list of the core elements that may appear in a resources script.
Below is a list of the core elements in alphabetical order.
Example 9.1. Example of px:app element.
<px:app name="bookstore">
<px:validateRequest><px:page ref="myapp:gatekeeper"/></px:validateRequest>
<px:mapRequest>
<px:matchDevice accept="text/html">
<px:matchRequestURI match="/bookstore/pages/(.+)">$1/html</px:matchRequestURI>
</px:matchDevice>
<px:matchDevice accept="application/vnd.wap.wmlc">
<px:matchRequestURI match="/bookstore/pages/(.+)">$1/wml</px:matchRequestURI>
</px:matchDevice>
<px:matchRequestURI match="/bookstore/pages/(.+).pdf">$1/pdf</px:matchRequestURI>
</px:mapRequest>
</px:app>
<px:page name="gatekeeper">
<px:show>
<px:localRedirect select="$px:requestURI">
<px:dynamicContent className="samples.common.BookstoreGatekeeper"/>
</px:localRedirect>
</px:show>
</px:page>
| Name | Mand. | Value | Description |
|---|---|---|---|
| caching | yes | "yes" or "no" | Indicates whether server side caching is in effect for the pages, documents and styles in the current scope. |
| revalidate | no | string | A list of revalidation codes with possible values "synch" or "asynch" (or both), or "full" or "none". |
| Name | Mand. | Value | Description |
|---|---|---|---|
| caching | yes | "yes" or "no" | Indicates client side caching is in effect for the pages in the current scope. |
Optionally, a pipeline body.
Performs a client-side redirect to the URI that results from evaluating the xpath expression in the select attribute.
A client-side redirect sends a URI back to the client, in the expectation that the client will resubmit the request with the new URI. If you want to have state sent with the new URI, you have two options:
Example 9.2. Example of a client-side redirect.
This example shows the "update-cart" page which updates a shopping cart in a Java UpdateCart object, adding a new book title, and then performs a client-side redirect to the "books" page. The URI of the "books" page is evaluated as an XPATH expression that can refer to any XML content generated in the pipeline that appears in its content, or to any parameters passed to the page.
<px:page name="update-cart">
<px:parameter ns="" name="category"/>
<px:parameter ns="" name="bookId"/>
<px:parameter ns="" name="title"/>
<px:show>
<px:clientRedirect select="concat('/bookstore/pages/books?category=',$category)">
<px:dynamicContent className="samples.books.UpdateCart"/>
</px:clientRedirect>
</px:show>
</px:page>
| Name | Mand. | Value | Description |
|---|---|---|---|
| ref | no | QName | A reference to a defined top-level px:content resource. |
Example 9.3. Using a px:content instruction to refer to dynamic content.
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
ns="http://www.presentingxml.com/myapp">
<px:page name="books">
<px:parameter ns="" name="category"/>
<px:show>
<px:transform>
<px:style ref="myapp:books"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
<px:dynamicContent name="books" className="samples.books.BookCatalog">
<px:key>
<px:field name="category"/>
</px:key>
</px:dynamicContent>
</px:resources>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the serializer. |
| className | yes | Java Class | The name of a java class that implements com.presentingxml.components.serializer.Serializer. |
Example 9.4. Defining an Apache fop serializer.
<px:serializer name="fop-serializer"
className="com.presentingxml.components.serializer.fop.FOPSerializer">
</px:serializer>
Example 9.5. Serializing an xsl-fo XML tree with an Apache fop serializer to produce pdf.
<px:page name="pulp">
<px:show>
<px:serializer ref="myapp:fop-serializer"/>
<px:transform>
<px:style ref="myapp:novel-fo"/>
<px:content ref="myapp:pulp"/>
</px:transform>
</px:show>
</px:page>
One or more action elements from the following list.
Example 9.6. Apply a stylesheet to a SOAP fault raised in the book-order document handler.
<px:page name="post-book-order">
<px:parameter ns="" name="name"/>
<px:parameter ns="" name="addressLine1"/>
<px:parameter ns="" name="addressLine2"/>
<px:parameter ns="" name="city"/>
<px:parameter ns="" name="state"/>
<px:parameter ns="" name="zip"/>
<px:parameter ns="" name="country"/>
<px:parameter ns="" name="phoneNumber"/>
<px:show>
<px:transform>
<px:style ref="myapp:confirm-order"/>
<px:content ref="myapp:book-order"/>
</px:transform>
<px:doFault>
<px:transform>
<px:style ref="myapp:book-order"/>
</px:transform>
</px:doFault>
</px:show>
</px:page>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the content resource. |
| className | no | Java Class | The name of a java class that implements com.presentingxml.components.content.dynamic.SelectHandler or com.presentingxml.components.content.dynamic.UpdateHandler. |
Example 9.7. Defining a document with reference to a java class that simulates a SAX parser.
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
ns="http://www.presentingxml.com/myapp">
<px:dynamicContent name="books" className="samples.books.BookCatalog">
<px:key>
<px:field name="category"/>
</px:key>
</px:dynamicContent>
</px:resources>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | Name | Reference to the name of a parameter. On a request, the field value will be set to that parameter value. |
See px:dynamicContent.
| ref | no | QName | A reference to a defined top-level filter. |
Optionally, a pipeline body.
Allows a resources script to pass control locally to another page.
A local redirect computes a new request URI in its select attribute, transfers the request back to the app, skips the validation steps defined in the px:validateRequest element (since its already inside the gate), and attempts to match the new request URI with a page using the rules defined in the px:mapRequest element.
Example 9.8. Example of a local redirect to the original request URI.
<px:page name="bookstore-gatekeeper">
<px:show>
<px:localRedirect select="$px:requestURI">
<px:dynamicContent className="samples.common.BookstoreGatekeeper"/>
</px:localRedirect>
</px:show>
</px:page>
Note that the variable px:requestURI appearing in the select attribute of the local redirect is a built-in variable that holds the original request URI. This local redirect transfers the request back to the app, skips the validation steps defined in the px:validateRequest element (since its already inside the gate), and attempts to match the request URI with a page using the rules defined in the px:mapRequest element.
| Name | Mand. | Value | Description |
|---|---|---|---|
| ref | no | QName | A reference to a defined top-level request matcher. |
One or more elements derived from px:mapRequest, including px:matchDevice and px:matchRequestURI elements.
Example 9.9. Example of px:mapRequest element.
<px:app name="bookstore">
<px:mapRequest>
<px:matchDevice accept="text/html">
<px:matchRequestURI match="/bookstore/pages/(.+)">$1/html</px:matchRequestURI>
</px:matchDevice>
<px:matchDevice accept="application/vnd.wap.wmlc">
<px:matchRequestURI match="/bookstore/pages/(.+)">$1/wml</px:matchRequestURI>
</px:matchDevice>
<px:matchRequestURI match="/bookstore/pages/(.+).pdf">$1/pdf</px:matchRequestURI>
</px:mapRequest>
</px:app>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the px:matchRequestURI instruction. |
| device | no | String | A comma separated list of device names. |
| accept | no | String | A comma separated list of mime types. |
Text.
Optionally, one or more px:mapRequest type elements, including px:matchDevice and px:matchRequestURI elements.
Example 9.10. Example of matching on a device and request URI.
<px:matchDevice accept="text/vnd.wap.wml">
<px:matchRequestURI match="/bookstore/pages/(.+)">$1/wml</px:matchRequestURI>
</px:matchDevice>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the px:matchRequestURI instruction. |
| match | yes | Regex | A perl regular expression that matches on the rquest URI. |
Text that may include regular expression wildcard characters.
Optionally, one or more px:mapRequest type elements, including px:matchDevice and px:matchRequestURI elements.
Example 9.11. Example of matching on a request URI.
<px:matchRequestURI match="/bookstore/pages/(.+)">html/$1</px:matchRequestURI>
Optionally, one or more px:parameter elements.
One or more action elements from the following list.
Example 9.12. Books page.
<px:page name="books">
<px:parameter ns="" name="category"/>
<px:show>
<px:transform>
<px:style ref="myapp:books"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
Optionally, text. If the content contains text, it is evaluated as the value of the parameter.
Used to define the parameters of a px:page element.
A document root element, which in turn may contain other elements and a px:recordMapping element.
| Name | Mand. | Value | Description |
|---|---|---|---|
| ns | no | URI | The default namespace for the pages, documents, styles and serializers defined in this resources script. |
The list of elements that may be defined with a qualified name at the top level of the resources script includes all the elements that are defined in the px:instructions section of the presentingxml.xml configuration file. These include
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the filter. |
| className | yes | Java Class | The name of a java class that implements org.xml.sax.XMLFilter. |
Example 9.13. Constructing a SAX pipeline.
The example below shows a resources script that implements a SAX pipeline. PreFilter and PostFilter are the names of Java classes that implement the org.xml.sax.XMLFilter interface.
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML">
<px:page name="pipeline">
<px:show>
<px:transform>
<px:systemContent href="documents/mixed-up.xml"/>
<px:saxFilter className="PreFilter"/>
<px:style href="styles/filter.xsl"/>
<px:saxFilter className="PostFilter"/>
</px:transform>
</px:show>
</px:page>
</px:resources>
| Name | Mand. | Value | Description |
|---|---|---|---|
| ref | no | QName | A reference to a defined top-level serializer. |
Optionally, a pipeline body.
Performs a server-side redirect to the URI that results from evaluating the xpath expression in the select attribute.
A server-side redirect forwards the request received from the client to another URI. All the parameters sent with the original request will go with the forwarded request, they should not be added to the new URI.
Example 9.14. Example of forwarding a request to the pulp.pdf page.
<px:page name="bukowski">
<px:show>
<px:serverRedirect select="'/pages/pulp.pdf'"/>
</px:show>
</px:page>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the style resource. |
| ref | no | QName | A reference to a defined top-level px:style resource. |
| href | yes | URI | The URI of an XSLT stylesheet. |
| documentNS | no | ns prefix | Identifies the namespace of documents to be looked up by the document URI resolver. Defaults to the namespace of the stylesheet. |
Example 9.15. Defining a style with reference to an XSLT file.
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
ns="http://www.presentingxml.com/myapp">
<px:style name="books" href="books/books.xsl"/>
</px:resources>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the content resource. |
| href | no | URI | The URI of an XML document. |
Example 9.16. Defining a document with reference to an XML file.
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
ns="http://www.presentingxml.com/myapp">
<px:systemContent name="countries" href="books/countries.xml"/>
</px:resources>
Example 9.17. Transforming the books XML document with the books XSLT stylesheet.
<px:page name="books">
<px:parameter ns="" name="category"/>
<px:show>
<px:transform>
<px:style ref="myapp:books"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
Table of Contents
Table of Contents
This appendix provides an alphabetical list of the elements that may appear as content in a px:flatFileContent instruction.
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | yes | NCName | The name of the field. |
| offset | no | number | For positional fields, the zero based offset of the field in the record. If it is not specified and the field is fixed width, it defaults to one past the last character of the previous field (including its field delimiter, if any.) |
| width | no | number | For fixed width fields, the width of the field. |
| trim | no | "yes" or "no" | Indicates whether to trim leading and trailing whitespace. The default is yes |
| trimLeading | no | "yes" or "no" | Indicates whether to trim leading whitespace. The default is yes |
| trimTrailing | no | "yes" or "no" | Indicates whether to trim trailing whitespace. The default is yes |
| quote | no | "yes" or "no" | Indicates whether a value may be enclosed in quote marks, where the enclosing quote marks serve to delimit the value but are not part of the value itself. This allows the value to contain a field delimiter. The default is no. |
| justify | no | "left","right", or "center" | When serializing XML to a flat file, for fixed width fields, indicates how to align the data within the field. The default is "left". |
| padCharacter | no | Character | When serializing XML to a flat file, for fixed width fields, specifies the character to pad the field, e.g., a space or zero. The default is a space. |
Optionally, a px:fieldAttributeMap element.
Optionally, one or more px:fieldDelimiter elements. If it is not specified, it defaults to the field delimiter specified in the px:record element, if there is one. If none is specified and there is no default, and if this field is not the last field before a record delimiter, then the field must have fixed width and the width attribute must be specified.
If you have a field value that includes a character that is the same as the quote symbol, you must escape that character. For example, if the quote symbol is the default double quotation mark, escaped by a second quote symbol, and if your record data is
"Gun, with Occaisonal Music","""SHARP, FUNNY, VISIONARY"""then the values become
Gun, with Occaisonal Music "SHARP, FUNNY, VISIONARY"
| Name | Mand. | Value | Description |
|---|---|---|---|
| value | yes | String | A string of one or more characters that indicates the end of a field. |
The field delimiter indicates the end of the field value. It is excluded from the field value. It may be one or more characters in length.
The following special encodings may appear in a delimiter value.
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the page. |
| href | no | URI | The URI of a flat file. |
Example 10.1. Example of Comma Separated Value (csv) file content.
<px:flatFileContent name="countries" href="books/countries.csv">
<px:fileLayout>
<px:record>
<px:fieldDelimiter value=","/>
<px:field name="countryCode"/>
<px:field name="countryName" quote="yes"/>
</px:record>
</px:fileLayout>
<px:recordSetMapping>
<countries>
<px:recordMapping>
<country>
<px:fieldAttributeMap name="countryCode" attribute="countryCode"/>
<px:fieldElementMap name="countryName" element="countryName"/>
</country>
</px:recordMapping>
</countries>
</px:recordSetMapping>
</px:flatFileContent>
Suppose the flat file countries.csv contains the lines
ATF,"FRENCH SOUTHERN TERRITORIES, D.R. OF" VUT,VANUATU WLF,WALLIS & FUTUNA ISLANDSThen the document named "countries" will have the following XML representation:
<countries>
<country countryCode="ATF">
<countryName>FRENCH SOUTHERN TERRITORIES, D.R. OF</countryName>
</country>
<country countryCode="VUT">
<countryName>VANUATU</countryName>
</country>
<country countryCode="WLF">
<countryName>WALLIS & FUTUNA ISLANDS</countryName>
</country>
</countries>
Example 10.2. Example of Java properties file content.
<px:flatFileContent name="messages" href="messages.properties">
<px:fileLayout>
<px:commentSymbol value="#"/>
<px:record>
<px:fieldDelimiter value=","/>
<px:field name="name"/>
<px:field name="value" quote="yes"/>
</px:record>
</px:fileLayout>
<px:recordSetMapping>
<messages>
<px:recordMapping>
<px:fieldElementMap name="name" element="message">
<px:fieldAttributeMap name="value" attribute="key"/>
</px:fieldElementMap>
</px:recordMapping>
</messages>
</px:recordSetMapping>
</px:flatFileContent>
Suppose the properties file messages.properties contains the lines
parser.next.1=A character is required after \\. parser.next.2='?' is not expected. '(?:' or '(?=' or '(?!' or '(?<' or '(?#' or '(?>'? #parser.next.3='(?<=' or '(?<!' is expected. parser.next.4=A comment is not terminated.Then the document named "messages" will have the following XML representation:
<messages> <message key="parser.next.1">A character is required after \\.</message> <message key="parser.next.2">'?' is not expected. '(?:' or '(?</message> <message key="parser.next.4">A comment is not terminated.</message> </messages>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the page. |
Example 10.3. Example of a serializer producing Comma Separated Value (csv) files.
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
xmlns:myapp="http://www.presentingxml.com/myapp"
ns="http://www.presentingxml.com/myapp">
<px:page name="countries">
<px:show>
<px:flatFileSerializer>
<px:fileLayout ref="myapp:countriesFileLayout"/>
<px:recordSetMapping ref="myapp:countriesFileMapping"/>
</px:flatFileSerializer>
<px:transform>
<px:systemContent href="documents/countries.xml"/>
</px:transform>
</px:show>
</px:page>
<px:fileLayout name="countriesFileLayout">
<px:commentSymbol value="#"/>
<px:record>
<px:fieldDelimiter value=","/>
<px:quoteSymbol value='"' escapedBy="\"/>
<px:field name="code"/>
<px:field name="name" quote="yes" trimLeading="yes"/>
</px:record>
</px:fileLayout>
<px:recordSetMapping name="countriesFileMapping">
<countries>
<px:recordMapping>
<country>
<px:fieldElementMap field="name" element="countryName"/>
<px:fieldAttributeMap field="code" attribute="countryCode"/>
</country>
</px:recordMapping>
</countries>
</px:recordSetMapping>
</px:resources>
Suppose the input XML file countries.xml contains the lines
<?xml version="1.0" encoding="utf-8"?>
<countries>
<country countryCode="ATF">
<countryName>FRENCH SOUTHERN TERRITORIES, D.R. OF</countryName>
</country>
<country countryCode="DEU">
<countryName>GERMANY, FEDERAL REPUBLIC OF</countryName>
</country>
</countries>
Then the output csv file countries.csv will look like:
ATF,"FRENCH SOUTHERN TERRITORIES, D.R. OF" DEU,"GERMANY, FEDERAL REPUBLIC OF"
| Name | Mand. | Value | Description |
|---|---|---|---|
| value | no | Character | The symbol to optionally enclose field values. Defaults to the double quotation mark. |
| escapedBy | no | Character | The symbol used to escape the quote symbol, e.g. the backslash ('\') or the quote symbol itself. Defaults to the quote symbol. |
Optionally, one or more px:recordDelimiter elements. The default is two possible delimiters: a linefeed, or a carriage return followed by a linefeed.
When serializing XML to a flat file, if more than one record delimiter has been defined, the serializer checks to see if one of the delimiters matches the system conventional end-of-line character. If so, it uses that one, otherwise it uses the first one.
Optionally, a px:quoteSymbol element.
Optionally, one or more px:fieldDelimiter elements.
One or more px:field elements.
| Name | Mand. | Value | Description |
|---|---|---|---|
| value | yes | String | A string of one or more characters that indicates the end of a record. |
Table of Contents
This appendix provides an alphabetical list of the elements that may appear as content in a px:sqlContent instruction.
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the JDBC connection pool. |
| driver | yes | Java class | The class name of the JDBC driver. |
| databaseURL | yes | URL | The JDBC database URL. |
| user | yes | String | The database user name. |
| password | yes | String | The database password. |
| minConnections | no | Number | The minimum number of connections to keep in the pool. The default is zero. |
| maxConnections | no | Number | The maximum number of connections to keep in the pool. The default is any number. |
| testStatement | no | String | A statement to test the liveness of the database before obtaining a connection. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the JDBC connection pool. |
Example 11.1. Example of SQL Content.
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
xmlns:myapp="http://www.presentingxml.com/myapp"
ns="http://www.presentingxml.com/myapp">
<px:page name="employees">
<px:show>
<px:content ref="myapp:employees"/>
</px:show>
</px:page>
<px:jdbcConnectionPool name="jdbc-pool"
driver="oracle.jdbc.driver.OracleDriver"
databaseURL="jdbc:oracle:thin:@127.0.0.1:1521:dev"
user="scott"
password="dev"
minConnections="2"
testStatement="SELECT * FROM DUAL"/>
<px:sqlContent name="employees">
<px:jdbcConnectionPool ref="myapp:jdbc-pool"/>
<px:sqlQuery>
SELECT EMPNO, ENAME AS NAME,JOB FROM EMP WHERE JOB = '{$job}'
</px:sqlQuery>
<px:recordSetMapping>
<employees>
<px:recordMapping>
<employee>
<px:fieldAttributeMap field="EMPNO" attribute="employee-no"/>
<px:fieldElementMap field="NAME" element="name"/>
<px:fieldElementMap field="JOB" element="job"/>
</employee>
</px:recordMapping>
</employees>
</px:recordSetMapping>
</px:sqlContent>
</px:resources>
When the page employees is requested with the parameter job=action, the result is the following XML document:
<?xml version="1.0" encoding="utf-8"?>
<employees>
<employee employee-no="7788">
<name>SCOTT</name>
<job>ANALYST</job>
</employee>
<employee employee-no="7902">
<name>FORD</name>
<job>ANALYST</job>
</employee>
</employees>
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the JDBC connection pool. |
See px:sqlContent
Table of Contents
This appendix provides an alphabetical list of the elements that may appear as content in a px:msvFilter instruction.
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the filter. |
| schema | no | URI | The location of the schema document. |
Example 12.1. Validating the countries document.
<px:resources xmlns:px="http://www.presentingxml.com/PresentingXML"
ns="http://www.presentingxml.com/myapp">
<px:page name="countries">
<px:show>
<px:transform>
<px:msvFilter schema="data/countries.xsd"/>
<px:content ref="myapp:countries"/>
</px:transform>
</px:show>
</px:page>
<px:systemContent name="books" href="books/countries.xml"/>
</px:resources>
Table of Contents
This appendix provides an alphabetical list of the elements that may appear as content in a px:fopSerializer instruction.
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the serializer. |
Example 13.1. Defining an Apache fop serializer.
<px:fopSerializer/>
Example 13.2. Serializing an xsl-fo XML tree with an Apache fop serializer to produce pdf.
<px:page name="pulp">
<px:show>
<px:fopSerializer/>
<px:transform>
<px:style ref="myapp:novel-fo"/>
<px:content ref="myapp:pulp"/>
</px:transform>
</px:show>
</px:page>
Table of Contents
This appendix provides an alphabetical list of the elements that may appear as content in the px:mailAccount and px:sendMail instructions.
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the response instruction. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the mail account. |
| smtpHost | yes | host | The smtp host. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the response instruction. |
| type | no | type code | The type of a part. The only allowed value is "alternative" |
| Name | Mand. | Value | Description |
|---|---|---|---|
| displayName | no | NCName | The display name for the owner of the account. |
| emailAddess | yes | address | The email address of the sender. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the mail sender. |
| subject | yes | Text | The subject of the message. |
| to | yes | addresses | A comma separated list of email addresses of recipients. |
| cc | yes | addresses | A comma separated list of email addresses of recipients. |
Example 14.2. Mail example.
<px:page name="books/html">
<px:parameter ns="" name="category"/>
<px:sendMail subject="test"
to="changeme"
cc="changeme">
<px:mailAccount ref="myapp:my-account"/>
<px:message>
<px:part>
<px:transform>
<px:style ref="myapp:welcome/html"/>
</px:transform>
</px:part>
<px:attachment filename="pulp.pdf">
<px:fopSerializer/>
<px:transform>
<px:style ref="myapp:novel/fo"/>
<px:content ref="myapp:pulp"/>
</px:transform>
</px:attachment>
</px:message>
</px:sendMail>
Table of Contents
The px:streamFilter instruction provides a way of filtering a stream of XML content in a pipeline without requiring the construction of a tree representation of the document. The input into the filter is a sequence of SAX events and the output is a sequence of SAX events. The events allowed into the filter are restricted by a match expression, using the in attribute, and the events allowed out of the filter are restricted by another match expression, using the out attribute. Within the body of the filter, the nodes flowing through the stream may be updated, removed, and given new siblings or children.
This chapter provides an alphabetical list of the elements that may appear as content in a px:streamFilter instruction.
An insert body.
Inserts content as a child of the current node. The new child is inserted after the last child of the current node.
| Name | Mand. | Value | Description |
|---|---|---|---|
| match | yes | SAXMatchExpr | A pattern that determines which elements go into the filter. Matching is on element names and attribute names and values (see example below.) If an element is matched, all of its children are also matched. |
An insert body.
An insert body.
| Name | Mand. | Value | Description |
|---|---|---|---|
| match | no | SAXMatchExpr | A pattern that determines which elements come out of the filter. Matching is on element names and attribute names and values (see example below.) If an element is matched, all of its children are also matched. The default is all elements. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | no | NCName | The name of the page. |
Any number of the following elements:
Examples of SAXMatchExpr expressions.
The three examples below all produce the same output.
Example 15.1. Adding the title Small Holdings to the Books HTML page with three transform steps.
<px:page name="books">
<px:show>
<px:transform>
<px:style ref="myapp:books"/>
<px:transform>
<px:streamFilter>
<px:input match="books[@cat='F']"/>
<px:appendChild>
<book><title>Small Holdings</title><author>Nicola Barker</author></book>>
</px:appendChild>
</px:streamFilter>
<px:content ref="myapp:books"/>
</px:transform>
</px:transform>
</px:show>
</px:page>
Example 15.2. Adding the title Small Holdings to the Books HTML page with two transform steps.
<px:page>
<px:show>
<px:transform>
<px:streamFilter>
<px:input match="books[@cat='F']"/>
<px:appendChild>
<book><title>Small Holdings</title><author>Nicola Barker</author></book>>
</px:appendChild>
</px:streamFilter>
<px:style ref="myapp:books"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
Example 15.3. Adding the title Small Holdings to the Books HTML page with one transform step.
<px:page name="books">
<px:show>
<px:transform>
<px:streamFilter">
<px:input match="books[@cat='F']"/>
<px:appendChild>
<book><title>Small Holdings</title><author>Nicola Barker</author></book>>
</px:appendChild>
</px:streamFilter>
<px:style ref="myapp:books"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
| Name | Mand. | Value | Description |
|---|---|---|---|
| searchFor | no | string | Search for occurance of string. |
| replaceWith | yes | string | Replace occurance of searchFor string. If no searchFor string is specified, replace the entire element value. |
| elements | no | Whitespace-separated list of NameTests | Defines the elements within the filter whose text nodes are to be updated. |
| attributes | no | Whitespace-separated list of NameTests | Defines the attributes within the filter whose values are to be updated. |
Example 15.4. Update example 1.
<px:page name="books">
<px:show>
<px:transform>
<px:streamFilter>
<px:input match="*"/>
<px:update attributes="cat" searchFor="F" replaceWith="C"/>
</px:streamFilter>
<px:style ref="myapp:books"/>
<px:content ref="myapp:books"/>
</px:transform>
</px:show>
</px:page>
This example checks the values of all attributes named "cat" and replaces occurances of "F" with "C".
Example 15.5. Update example 2
<px:page name="books">
<px:show>
<px:transform>
<px:streamFilter>
<px:input match="*[@cat='F']"/>
<px:update replaceWith="C"/>
</px:streamFilter>
</px:transform>
<px:style ref="myapp:books"/>
<px:content ref="myapp:books"/>
</px:show>
</px:page>
This example checks the values of all attributes named "cat" that have the value "F" and substitutes "C".
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | yes | QName | The name of the variable. |
| value | yes | SAXValueExpr | The value of the variable. The string value may contain one or more SAXValueExprs enclosed within curly braces, e.g. "{lastName},{firstName}". |
Table of Contents
Ant is used for building the Presenting XML source. Ant is an open source java-based build tool. It specifies an XML format for projects. It is cross-platform.
A version of ant is included with the Presenting XML distribution files, in the lib/ant directory. You can obtain the latest version of Ant from the Jarkarta web site http://jakarta.apache.org/site/binindex.html
An ant build.xml file is located in the presentingxml directory. To build the distribution jar file presentingxml.jar, enter the command
build
The build.xml file defines three build targets:
dist, the default, which builds the distribution jar file presentingxml.jar in the lib directory.
tests, which builds the test suite jar file tests.jar in the tests directory.
javadoc, which builds the javadoc files in the docs/api directory.
To specify a target, provide the target name as an argument to the build command, e.g. to build the javadoc target, enter the command
build javadoc
The build requires the presence of certain third party jar files in the lib directory. These are described in a readme file in the lib directory.
Table of Contents
You will need to configure your web server to work with Presenting XML. This section describes how to do that for Jakarta Tomcat.
The distribution files for the Jakarta Tomcat web server may be obtained from http://jakarta.apache.org/site/binindex.html.
Presenting XML may be deployed in Tomcat in a number of ways, by pointing the document root of the web application to an unpacked directory hierarchy in the development source tree, or by copying an application archive file into the $CATALINA_HOME/webapps directory.
The steps to configure Jakarta Tomcat to work with Presenting XML are as follows:
Edit the server.xml file in the tomcat conf directory. Add the following Context element in the server.xml file (changing docBase as appropriate):
<Context path="/bookstore"
docBase="C:/Projects/presentingxml/webapps/bookstore"
crossContext="false"
debug="0"
reloadable="true" >
</Context>
Set the environmental variable JAVA_HOME to a version of the jdk 1.3 or above, i.e.
set JAVA_HOME=C:\tools\java\jdk1.3.1(changing C:\tools as appropriate), or add the above line to the top of the startup.bat file (tomcat.sh for Unix) in the jakarta tomcat bin directory.
You will need to restart Tomcat to have the changes in the server.xml file take effect.
The steps to configure Jakarta Tomcat to work with Presenting XML are as follows:
Create the web application archive file. From the web application directory, e.g. webapps/bookstore, run the following command:
jar cf ../bookstore.war *
Edit the server.xml file in the tomcat conf directory. Add the following Context element in the server.xml file (changing docBase as appropriate):
<Context path="/webapps/bookstore"
docBase="/bookstore"
crossContext="false"
debug="0"
reloadable="true" >
</Context>
Set the environmental variable JAVA_HOME to a version of the jdk 1.3 or above, i.e.
set JAVA_HOME=C:\tools\java\jdk1.3.1(changing C:\tools as appropriate), or add the above line to the top of the startup.bat file (tomcat.sh for Unix) in the jakarta tomcat bin directory.
You will need to restart Tomcat to have changes in the server.xml file take effect.
The steps to configure Jakarta Tomcat 3.x to work with Presenting XML are as follows:
Edit the server.xml file in the tomcat conf directory. Add the following Context element in the server.xml file (changing docBase as appropriate):
<Context path="/bookstore"
docBase="C:\Projects\presentingxml\webapps\bookstore"
crossContext="false"
debug="0"
reloadable="true" >
</Context>
Set the environmental variable JAVA_HOME to a version of the jdk 1.3 or above, i.e.
set JAVA_HOME=C:\tools\java\jdk1.3.1(changing C:\tools as appropriate), or add the above line to the top of the startup.bat file (tomcat.sh for Unix) in the jakarta tomcat bin directory.
Delete jaxp.jar and parser.jar in the tomcat lib directory, replace them with xerces.jar (from the presentingxml/lib directory), and modify the config file workers.properties, replacing
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)jaxp.jar worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)parser.jarwith
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)xerces.jar
Table of Contents
In the sample bookstore web application, the steps to switch from the saxon transformer to the xalan transformer are as follows:
In the config subdirectory, open the presentingxml.xml file. Locate the px:transformer element shown below.
<px:transformer className="com.icl.saxon.TransformerFactoryImpl">
<px:outputProperties>
<px:property name="indent" value="no"/>
<px:property name="{http://icl.com/saxon}omit-meta-tag" value="yes"/>
</px:outputProperties>
</px:transformer>
In the build subdirectory, edit the build.properties file. Comment out the line below # saxon lib list and uncomment the line below # xalan lib list.
In the build subdirectory, rebuild the sample web application by entering build at the command prompt.
Table of Contents
This appendix provides an alphabetical list of all the elements that may appear in a system configuration script.
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | yes | String | The name of a device. |
| accept | no | Comma-separated list | List of MIME types accepted by the device. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| search | yes | Regular expression pattern | Searches for a pattern in the User-Agent to identify a device. |
| device | yes | Name | Identifies a device. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| className | no | Java Class | An implementation of the jaxp javax.xml.parsers.DocumentBuilderFactory class. |
Optionally, a px:systemProperties element.
| Name | Mand. | Value | Description |
|---|---|---|---|
| className | yes | String | A class that implements com.presentingxml.tools.system.Logger. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| className | yes | Java Class | An implementation of the com.presentingxml.tools.patternmatcher.PatternMatcher interface. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| name | yes | String | The name of a property. |
| value | yes | String | The value of a property. |
| Name | Mand. | Value | Description |
|---|---|---|---|
| className | no | Java Class | An implementation of the jaxp javax.xml.parsers.SAXParserFactory class. |
Optionally, a px:systemProperties element.
| Name | Mand. | Value | Description |
|---|---|---|---|
| className | no | Java Class | An implementation of the jaxp javax.xml.transform.TransformerFactory class. |
Table of Contents
This appendix describes the Presenting XML console app.
The following software must be installed:
Java JDK 1.3 or later (it will not work with earlier versions.)
The third party libraries that come with the Presenting XML distribution (the servletapi jar file is not needed.)
An application jar file that contains the custom error handler and requestListener implementations.
The java class com.presentingxml.presenter.consoleapp.ConsoleApp has a main program that may be used to generate pages based on the resources script. The form of the command is
java -classpath <jar files> com.presentingxml.presenter.consoleapp.ConsoleApp
[options] page {param=value}...
The options are as follows:
Overrides the default system configuration file. The default is the presentingxml.xml file in the presentingxml resources directory, which is included in the presentingxml.jar file.
Identifies the resources script.
Indicates the desired MIME type of the output, or a comma separated list if more than one is acceptable. The default is "text/html".
Identifies the output file. The default is standard out.
From an app directory, e.g. the sample webapps/bookstore, you can use the simpler expression
java -jar WEB-INF\lib\bookstore.jar [options] page {param=value}...
The syntax for generating the default (HTML) books page is as follows:
java -jar WEB-INF\lib\bookstore.jar -c config\presentingxml.xml -r pages\pages.xml
-o books.html /bookstore/pages/books
The syntax for generating the associated WML books page is:
java -jar WEB-INF\lib\bookstore.jar -c config\presentingxml.xml -r pages\pages.xml
-o books.wml -a text/vnd.wap.wml /bookstore/pages/books
The syntax for generating the HTML file for computer books is:
java -jar WEB-INF\lib\bookstore.jar -c config\presentingxml.xml -r pages\pages.xml
-o /bookstore/pages/books.html books category=C
Comma separated values (CSV).
SAXMatchExpr stands for "SAX match expression." An example is "author | title[@cat='F']." A SAX match expression restricts the flow of elements through a SAX filter. The syntax for a SAXMatchExpr is a small subset of the syntax for an XPath expression, including the parts that make sense for filtering on the startElement event, with just the current element name and the attributes accessible.
Examples of SAXMatchExpr expressions.
SAXValueExpr stands for "SAX value expression." An example is "@category"
A sequence of literal result elements and px:transform instructions forming the content of a px:insertSiblingAfter, px:insertSiblingBefore, or px:appendChild element.
The Multipurpose Internet Mail Extension (MIME) type provided by the server and used by the browser to identify the type of document.
A NameTest may be a name, the symbol "*", which stands for any name, or the expression "prefix:*" which represents all names in the specified namespace.
NCName stands for "no colon name." An example is "books."
QName stands for "qualified name." An example is "myapp:books."
A top level element is an element that appears as an immediate child of px:resources.
A short string that stands for the name or address of a resource.