10
Transformers

This document describes how to create and manage Portal-to-Go transformers. Topics include:

What is a Portal-to-Go Transformer?

Portal-to-Go transformers are Java programs or XSLT stylesheets that convert a Portal-to-Go document into either the target format or another Portal-to-Go format.

Generally, transformers encapsulate the logic for presenting content. Since presentation logic is often platform- and device-dependent, centralizing the presentation logic in transformers enables services to be portable across platforms and devices.

Portal-to-Go supports the following types of transformers:

Result transformer
Device transformer

Result transformers typically convert content from Adapter Result format to Simple Result format. The Adapter Result format is an intermediary format layer that enables efficient exchange of user interface-independent data. You may use it, for example, to link chained services. A chained service is a Portal-to-Go service that invokes another service. An adapter can pass the service link using the Adapter Result format. A result transformer must render the Adapter Result document in Simple Result format before Portal-to-Go can deliver it to the user.

Device transformers convert Simple Result documents into the format of the target device. You can use two types of device transformers in Portal-to-Go:

Default transformer
Custom transformer

Portal-to-Go requires you to associate a transformer to each logical device. The transformer associated with a logical device is the device's default transformer.

Default transformers are typically generalized for a markup format, but they can also be specific to a target device.

Portal-to-Go uses the device's default transformer to convert any service targeted for that type of device, unless a custom device transformer overrides the default transformer. A custom device transformers enables you to control how a specific service appears on a specific device. While several logical devices can use a single default transformer, a custom transformer can be associated with only one master service and one logical device. The custom transformer optimizes the presentation of that service for a particular device.

Note:
A logical device is a repository object that represents either a physical device or an abstract device, such as an email server.

Transformers Provided by Portal-to-Go

Portal-to-Go provides transformers that convert Portal-to-Go XML for the following target formats:

Format Description

HDML

The Handheld Devices Markup Language is a version of HTML designed specifically for mobile phones.

Plain text

Converts Simple Result format to plain text. This transformer is implemented as an XSLT.

Plain text - Java

Converts Simple Result format to plain text. This transformer is implemented as a Java class.

WML 1.1

The Wireless Markup Language standard defined by the WAP Forum.

Tiny HTML

The Tiny HTML format is a lightweight version of HTML, suitable for most PDAs. It lacks advanced HTML features, such as frame and JavaScript support.

VoxML

Motorola's markup language for voice-capable gateways.

Format	Description
HDML	The Handheld Devices Markup Language is a version of HTML designed specifically for mobile phones.
Plain text	Converts Simple Result format to plain text. This transformer is implemented as an XSLT.
Plain text - Java	Converts Simple Result format to plain text. This transformer is implemented as a Java class.
WML 1.1	The Wireless Markup Language standard defined by the WAP Forum.
Tiny HTML	The Tiny HTML format is a lightweight version of HTML, suitable for most PDAs. It lacks advanced HTML features, such as frame and JavaScript support.
VoxML	Motorola's markup language for voice-capable gateways.

Creating Transformers

The Portal-to-Go initial repository includes transformers for several target formats, including WML, HDML, and VoxML. By modifying the transformers provided with Portal-to-Go, or creating new ones, you can target new device platforms and optimize content presentation for specific devices.

Transformers not only map source tags to target format tags, they can manipulate content. They can rearrange, filter, and add text (such as boilerplate text). This enables you to present content in the format, as well as the form factor best suited for the target device.

When you create a transformer, you map the elements in the source content to the result format. For example, the Tiny HTML transformer, which is included in the initial Portal-to-Go repository, maps several Simple Result elements as follows:

Simple Result Source HTML Result

<SimpleResult>Document</SimpleResult>

<html>Document</html>

<SimpleText title="Accounting">

<h2>Accounting</h2>

<SimpleTextItem name="Employee">Scott</SimpleTextItem>

<p>Employee: Scott</p>

Simple Result Source	HTML Result
<SimpleResult>Document</SimpleResult>	<html>Document</html>
<SimpleText title="Accounting">	<h2>Accounting</h2>
<SimpleTextItem name="Employee">Scott</SimpleTextItem>	<p>Employee: Scott</p>

Similarly, when you create a transformer, you create a logical mapping between the abstract user interface elements represented by the Simple Result elements and the target format.

You can implement Portal-to-Go transformers as either Java transformers or XSLT stylesheets.

Java Transformers

To create a Java transformer for Portal-to-Go, you extend the Transformer interface. The class must be thread-safe and it must provide an empty constructor. The transformer should return a String object, which is the result document.

You can create Java transformers using either the DOM interface or the SAX interface. The DOM interface accesses and manipulates the compiled document object. The SAX interface interacts directly with the parsing process. The Oracle parser supplements these standards-based interfaces with extensions. For more information, see the Portal-to-Go API Specification.

The following section describes the components of a transformer class implementation.

Sample Java Device Transformer

Portal-to-Go includes a Java transformer that converts Simple Result documents to plain text. While the transformer does not create markup tags in the resulting document, it does apply simple text formatting elements, such as line breaks and tabs. Though simple, these elements illustrate how you can convert Simple Result elements into another format.

package oracle.panama.core.xform;
import org.w3c.dom.NodeList;
import org.w3c.dom.Element;
import oracle.panama.PanamaException;
import oracle.panama.core.LogicalDevice;
import oracle.panama.core.Service;
import oracle.panama.Arguments;
import oracle.panama.core.parm.PanamaRequest;
import oracle.panama.core.parm.AbstractRequest;

public class SimpleResultToText implements Transform {
    public SimpleResultToText() {}

    private String format(Element el) {
        if (el == null) {
            return "";
        }
        StringBuffer buf = new StringBuffer();
        String name = el.getTagName();
        if (name != null && name.length() > 0) {
            buf.append(name);
            buf.append(": ");
        }
        buf.append(el.getNodeValue());
        return buf.toString();
    }
    
    public String transform(Element element, LogicalDevice device) 
                                   throws PanamaException {
        PanamaRequest req = AbstractRequest.getCurrentRequest();
        Service service = req.getService();
        StringBuffer buf = 
          new StringBuffer((service == null) ? "" : service.getName());
        NodeList list = element.getElementsByTagName("*");
        Element el;
        String tag;
        boolean newRow = false;
        for (int i = 0; i < list.getLength(); i ++) {
            el = (Element)list.item(i);
            tag = el.getTagName();
            if (tag.equals("SimpleRow")) {
                newRow = true;
                buf.append("\n");
            } else if (tag.equals("SimpleCol")) {
                if (!newRow) {
                    buf.append("\t");
                } else {
                    newRow = false;
                }
                buf.append(format(el));
            } else if (tag.equals("SimpleText") || 
                       tag.equals("SimpleForm") || 
                       tag.equals("SimpleMenu")) {
                newRow = true;
                buf.append("\n");
            } else if (tag.equals("SimpleTextItem") || 
                       tag.equals("SimpleFormItem") || 
                       tag.equals("SimpleMenuItem")) {
                if (!newRow) {
                    buf.append("\n");
                } else {
                    newRow = false;
                }
                buf.append(format(el));
            }
        }
        return buf.toString();
    }
}

The following sections describe each method in the transformer.

SimpleResultToText()

The SimpleResultToText() method is the default constructor for instantiating the transformer. Any transformer you create must also provide an empty default constructor.

format()

This transformer uses the format() method to format text, form, and menu items. The format() method uses the tag name as the item label, followed by the text of the item. Element.getTagName() returns the name of the element.

For example, given the following XML element:

<User>Scott</User>

The format() method returns:

User: Scott

transform()

The transform() method is the only required method in a transformer class. In the sample, the transform() method places each element from the source document in a node list. A node list is an indexed collection of elements.

NodeList list = element.getElementsByTagName("*");

The transform() method then steps through every element in the node list, testing each against the elements in the Simple Result DTD. If the source element matches the test Simple Result element, the method formats the element. It then appends the results to a buffer which, when finished, is returned to the caller.

XSLT Stylesheets

XSLT stylesheets are XML documents that specify the processing rules for other XML documents. The XSLT processor included with the Oracle XML processor conforms to the final W3C XSLT specification, Working Draft of August 13, 1999.

An XSLT stylesheet, like a Java transformer, is specific to a particular DTD. It should handle all elements declared in a DTD. When it finds the element in a source document, it follows the rules defined for the element to format its content.

XSLT stylesheets can include complex pattern matching and result handling logic. They typically include literal result elements, such as the target format markup tags.

Sample XSLT Device Transformer

The following transformer, which is included in the Portal-to-Go initial repository, is the XSLT version of the Java transformer described in "Sample Java Device Transformer". It converts Simple Result documents to plain text.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/XSL/Transform/1.0">
   <xsl:template match="/">
      <xsl:apply-templates></xsl:apply-templates>
   </xsl:template>
      <xsl:template match="SimpleTextItem | SimpleFormItem | SimpleMenuItem">
      <xsl:text></xsl:text>
      <xsl:value-of select="."></xsl:value-of>
   </xsl:template>
   <xsl:template match="SimpleRow">
      <xsl:text></xsl:text>
      <xsl:for-each select="./SimpleCol">
         <xsl:text></xsl:text>
         <xsl:value-of select="."></xsl:value-of>
      </xsl:for-each>
   </xsl:template>
</xsl:stylesheet>

The sample illustrates the processing sequence for XSLT stylesheets. The stylesheet first matches, or selects, a Simple Result element using pattern-matching semantics. The <xsl:template match="/"> element, for example, matches the document's root element. It then uses the apply-template element to process the contents of a found element, including all sub-elements. A select attribute limits the processing scope to a specified sub-element.

The stylesheet then descends the source element tree, selecting and processing each sub-element. Character instructions, such as value-of and for-each, manipulate the content of matching elements. The value-of element extracts the actual content of the element. The for-each element applies iterative processing.

The sample does not include literal text elements. The following illustrates the use of literal text elements:

<xsl:template match="SimpleTextItem">
   <P>
      <xsl:value-of select="."/>
   </P>
</xsl:template>

This XSLT element maps the content of SimpleTextItem to HTML paragraph tags. For example, if passed the following Portal-to-Go element:

<SimpleTextItem>Scott</SimpleTextItem>

The XSLT segment would produce the following:

<P>
   Scott
</P>

Sample XSLT Result Transformer

The following result transformer segment shows how a result transformer can enable chain services. It uses the results of a user's selection to link to a target, which is the subsequent service in the chain.

<xsl:template match="AdapterResult">
   <SimpleResult>
      <SimpleMenu name="Query Results">
         <xsl:for-each select="Table/Row">
            <xsl:if test="position() &#60; 8">
               <SimpleMenuItem>
                  <xsl:attribute name="target">
      ___REQUEST_NAME__?PAservicepath=___SERVICE_URL_ENC__
      &#38;PAsection=Result&#38;href=<xsl:value-of
      select="./href"></xsl:value-of></xsl:attribute>
                  <xsl:value-of select="./Title"></xsl:value-of>
               </SimpleMenuItem>
            </xsl:if>
         </xsl:for-each>
      </SimpleMenu>
   </SimpleResult>
</xsl:template>

The XML parser processes the document using the result transformer. Variables are preceded and terminated by underscore characters. The previous result transformer, for example, includes the variables REQUEST_NAME and SERVICE_URL_ENC.

REQUEST_NAME represents the name of the JSP file that executes the request. SERVICE_URL_ENC represents the path to a Portal-to-Go service in URL-encoded format. In the example, this is the path to a subsequent service in a service chain.

For example, given the following string:

http://www.panama.com/master/parm.jsp?PAservicepath=/master/getQuote

_REQUEST_NAME is "parm.jsp"
_SERVICE_NAME is "getQuote"
_SERVICE_URL is "/master/getQuote"

You can select the values of these variables in a transformer directly with a construct such as the following:

<xsl:value-of select="//_REQUEST_NAME"/>

Testing the Transformer

Portal-to-Go provides a command-line utility you can use to test the transformers you create. The Xslt utility takes a source document and an XSLT stylesheet, and writes the result document to standard output.

You invoke Xslt from the command prompt as follows:

java oracle.panama.util.Xslt mystylesheet.xsl < myxml.xml

Managing Transformers with the Service Designer

The Service Designer enables you to manage transformers in the Portal-to-Go repository. Using the Service Designer, you can create and update transformers, and remove them from the repository.

Creating a Transformer in the Repository

You use the Create New Transformer form in the Service Designer to create a transformer in the repository. To display the form:

Right-click Transformers in the Portal-to-Go repository tree view.
Click Create New Transformer to display the first form in the sequence.

The Create New Transformer form appears.

The form includes the following parameters:

Parameter Value

Name

The transformer name. This must be a unique name in the transformer folder of the repository tree.

Master Service

In the case of a custom transformer, the master service associated with the transformer.

Logical Device

In the case of a custom transformer, the logical device associated with the transformer.

Java Transformer

Specifies a Java class transformer implementation.

Class Name

The name of the class that implements the transformer.

XSL Transformer

Specifies an XSLT stylesheet transformer implementation.

Style-sheet

The actual XSLT stylesheet that implements the transformer. You can cut and paste a transformer from another editing environment into this field.

Parameter	Value
Name	The transformer name. This must be a unique name in the transformer folder of the repository tree.
Master Service	In the case of a custom transformer, the master service associated with the transformer.
Logical Device	In the case of a custom transformer, the logical device associated with the transformer.
Java Transformer	Specifies a Java class transformer implementation.
Class Name	The name of the class that implements the transformer.
XSL Transformer	Specifies an XSLT stylesheet transformer implementation.
Style-sheet	The actual XSLT stylesheet that implements the transformer. You can cut and paste a transformer from another editing environment into this field.

Modifying a Transformer

To modify a transformer in the Portal-to-Go repository, follow these steps:

Expand the Transformers folder in the Portal-to-Go repository tree view.
Click the transformer you want to modify. The General tab of the properties panel appears.

Modify the parameters as required and click Apply. For information on the parameters in the transformer properties panel, see "Creating Transformers".

Removing a Transformer from the Repository

To remove a transformer from the repository:

Expand the Transformers folder in the Portal-to-Go repository tree view.
Right-click the transformer you want to delete.
Click Delete. The Confirm Delete dialog appears.
Click Yes to confirm the action.

10 Transformers