Composer User's Guide

APPENDIX A

The Composer JSP Tag Library

Novell exteNd Composer comes with a tag library file, composer-taglib.tld, designed to make it easy for you to call Composer services, and manipulate associated DOM data, within your own Java Server Pages. The tags defined in this file are especially suited to JSP-driven applications in which XML data must be collated, formatted, or post-processed immediately before being sent to the client's browser.

In many cases, you will not need to do any hand-coding in order to use Composer's custom taglib, because many of the wizard-generated JSPs created by Director and Composer contain custom-tag calls. (For details on how to generate JSPs using these wizards, see the discussions at "Director JSP Wizard" and/or "Creating a JSP-Based Service Trigger".) In other cases, you will find it desirable to tap the full power of the tag library, which does require hand-coding. The discussion below summarizes the features available in the custom tag library and the syntax for using the various tags.

Preparing to Use the Tag Library

When you use Composer's built-in wizards to generate JSPs containing custom tags, then deploy your project using Composer's deployment UI, Composer takes care of certain "packaging" issues for you. But when you create your own JSPs from scratch and deploy a WAR/EAR manually, you must carry out the following steps yourself in order to ensure that your web app is fully custom-tag-enabled.

NOTE: The following steps apply only if you are hand-creating your own JSP. When you use the Composer and Director JSP wizards, these steps are taken care of for you.

Procedure To tag-enable your JSP-based web app:

Near the top of your JSP(s), insert the following line:
```
  <%@ taglib uri="/composer" prefix="composer" %>
```
- The uri attribute corresponds to a uri definition in the taglib entry of your WAR file's web.xml file. (See next two steps.)
- The prefix attribute allows you to specify a namespace prefix that you can combine with other tags specified in the tag library file.
In your WAR file, be sure to include the composer-taglib.tld file. A minimal WAR file composition is shown below.

In your web.xml file, be sure there is a taglib element referencing the uri from Step 1 above as well as the location of the tag library. For example:

  <web-app>
  	      . . .
       <taglib>
            <taglib-uri>/composer</taglib-uri>
            <taglib-location>/WEB-INF/composer-taglib.tld</taglib-location>
       </taglib>
       . . .
  </web-app>

Custom Tags Defined in composer-taglib.tld

The composer-taglib.tld file defines the following custom tags:

TAG NAME	PURPOSE
execute	Executes a Composer service
fault	Provides the ability to handle Composer fault documents
forEach	Provides the ability to loop over DOM nodes in a nodeset contained in an output document
hasnopart	Provides conditional processing based on the nonexistence of a particular output message part
hasnovalue	Provides conditional processing based on a particular node being empty
haspart	Provides conditional processing based on the existence of a particular output message part
hasvalue	Provides conditional processing based on a particular node being non-empty
if	Evaluates children if specified XPath condition is true
value	Obtains the data value of a particular node

Each of these tags relies on attribute values that, in effect, pass argument values to the underlying Java methods. Those attributes and their usage are discussed further below, in the individual discussions of the tags.

Tag API

execute

ATTRIBUTE

PURPOSE

converter

Converter class to be used when marshalling input data (see text for discussion)

faultHandled

Flag to indicate whether Composer faults will be handled inside the page using <composer:fault> tags. The default value is "false."

name

Arbitrary identifier for use within the JSP, to refer to the service in question.

root

Name of the root element of the input message part.

service

Name of the Composer service to invoke.

xmldoc

When the GXSInputFromJavaObject converter class is used, this attribute must be specified and must contain the name of the Java String (or String array) variable that points to the input document(s) to be passed to the service.

ATTRIBUTE	PURPOSE
converter	Converter class to be used when marshalling input data (see text for discussion)
faultHandled	Flag to indicate whether Composer faults will be handled inside the page using <composer:fault> tags. The default value is "false."
name	Arbitrary identifier for use within the JSP, to refer to the service in question.
root	Name of the root element of the input message part.
service	Name of the Composer service to invoke.
xmldoc	When the GXSInputFromJavaObject converter class is used, this attribute must be specified and must contain the name of the Java String (or String array) variable that points to the input document(s) to be passed to the service.

NOTE: Required attributes are shown in boldface type.

Inside your JSP, you will call your Composer service using the execute tag. The only required attribute is the service attribute, which specifies the fully qualified (full-context) service name. This attribute identifies the service for Composer's benefit but does not provide any access to the service elsewhere in the JSP (in other tags). If you want to refer to the service in another tag, you can define an alias for it using the name attribute.

For example, suppose you've built a Composer service called ListInventory (in a deployment context of com.inventory) and you want to refer to that service in downstream tags as inventory. To execute the ListInventory service, you would do:

  <composer:execute name="inventory" service="com.inventory.ListInventory" />

This line will execute your service, using the default "InputFromHttpParams" converter class that Composer uses when no other converter is specified. This is equivalent, in other words, to the Params (URL/Form) trigger mode.

You can specify the manner in which your service should obtain its input via the use of the converter attribute.

IMPORTANT: You should manually inspect all JSPs prior to deployment to verify that the deployment context matches the context used in the service attribute of the execute tag. (See example above.) To do this: In Composer Enterprise Edition, open your Deployment xObject, then use File > Properties to bring up the Properties dialog for the deployment. Inspect the deployment context (as shown under "Deployment Context in the Project JAR" on the Deploy tab of the Properties dialog). This context must match the context used in the service attribute of the execute tag, in any JSP that executes a Composer service.

Converter Classes

Composer Enterprise Server can marshall XML data in a number of ways, using helper classes that are part of the Composer installation. When calling a service from a JSP using the <composer:execute> tag, you can specify any of five different kinds of data marshalling.

Possible values for the converter attribute are:

  com.sssw.b2b.xs.service.conversion.GXSInputFromHttpParams
  com.sssw.b2b.xs.service.conversion.GXSInputFromHttpContent
  com.sssw.b2b.xs.service.conversion.GXSInputFromHttpMultiPartRequest
  com.sssw.b2b.xs.service.conversion.GXSInputFromHttpSpecificParam
  com.sssw.b2b.xs.service.conversion.GXSInputFromJavaObject

These classes are part of the Composer Enterprise Server installation runtime. You do not have to install them, package them, or register them in any special way to use them from your Composer web app.

The mode of operation of each of these classes is described below (and also in the Composer Enterprise Server documentation):

com.sssw.b2b.xs.service.conversion.GXSInputFromHttpParams

This converts HttpServletRequest parameters (i.e. those supplied either as URI parameters or form fields submitted) into an XML document. The document will use the root name that the service was defined with, unless you have specified the root name using the execute tag's root attribute.

com.sssw.b2b.xs.service.conversion.GXSInputFromHttpContent

This opens an InputStream from the supplied HttpServletRequest and retrieves the content of the request buffer, which it expects to be in XML format.

com.sssw.b2b.xs.service.conversion.GXSInputFromHttpMultiPartRequest

This class expects an HTML form with content type multipart/form-data. It will look for a specific file parameter ("xmlfile") and use that as the XML input document. If the mime type for the file thus found is not text/xml, then this class will create an XML document and place the contents of the file in a CDATA section within the XML document.

com.sssw.b2b.xs.service.conversion.GXSInputFromHttpSpecificParam

This class takes the contents of a form field and uses it as the input XML document. By default, the form field containing the XML is expected to be named "xmlfile."

com.sssw.b2b.xs.service.conversion.GXSInputFromJavaObject

This class expects the input XML document to be passed as raw XML contained in a Java String.The class's methods are overloaded in such a way that if your service is designed to handle more than one input document, you can pass multiple XML strings in a String array, in which case each String will be passed to your service as a message part.

fault

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to faults thrown by a <composer:execute> tag whose 'name' attribute has an identical value

part

Can be used to specify a user-defined custom fault document by name. If not specified, this attribute will take on a default value of "_SystemFault."

ATTRIBUTE	PURPOSE
name	Scopes the behavior of the tag to faults thrown by a <composer:execute> tag whose 'name' attribute has an identical value
part	Can be used to specify a user-defined custom fault document by name. If not specified, this attribute will take on a default value of "_SystemFault."

NOTE: Required attributes are shown in boldface type.

You can place a <composer:fault> element in the JSP to wrapper JSP code that should execute when a fault condition occurred in your service. The tag acts as a conditional expression: If a fault part is returned as the result of execution of a service using a <composer:execute> tag, the instructions between the start and end tag of the <composer:fault> element are executed. If no fault condition occurred during execution of the service, then the instructions bracketed by the <composer:fault> tags are ignored.

For example, to handle a standard Composer System Fault that might be returned from one Composer service and a custom fault returned from a second Composer service executed by a JSP, you might use JSP code similar to the following:

...

  <composer:execute name="myServ1" service="com.context.myService" xmldoc="myInput" />
  <composer:execute name="myServ2" service="com.context.myOtherService"/> 
  
  <HTML>
    <HEAD><TITLE>My Page<</TITLE></HEAD>
  <BODY>
  ...
  <composer:fault name="myServ1" part="_SystemFault">
  <B>A Fault has occurred!</B><P/>
  Component: <composer:value name="localName" xpath="FaultInfo/ComponentName" /><P/>
  Date: <composer:value name="localName" xpath="FaultInfo/DateTime" /><P/>
  MainCode: <composer:value name="localName" xpath="FaultInfo/MainCode" /><P/>
  SubCode: <composer:value name="localName" xpath="FaultInfo/SubCode" /><P/>
  Message: <composer:value name="localName" xpath="FaultInfo/Message" /><P/>
  </composer:fault>
  ...
  <composer:fault name="myServ2" part="myCustomFault">
    <B>Doh! A fault happened in my other service!</B>
  </composer:fault>
  ...
  </BODY>
  </HTML>

Note that a JSP may have more than one set of <composer:fault> tags. All tag sets that satisfy a specified name and part will be executed if a fault condition occurs in the service at runtime.

forEach

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.

part

Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).

xpath

An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that returns a nodelist (as defined by the Document Object Model).

ATTRIBUTE	PURPOSE
name	Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.
part	Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).
xpath	An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that returns a nodelist (as defined by the Document Object Model).

NOTE: Required attributes are shown in boldface type.

The forEach tag provides a looping construct so that you can iterate over the nodes in a nodelist at tag-execution time. The only required attribute is the xpath attribute, which should be an XPath expression that resolves to a nodelist. The expression will be evaluated against the service specified by name and the message part (or DOM) specified in part. If no extra attributes are defined, the most recently executed service's Output part is used.

The following example shows how you could loop over a set of ITEM nodes in a message part called Output1 produced by a service whose alias (defined by the name attribute in an execute tag) is inventory:

  <composer:forEach name="inventory" part="Output1" xpath="/MYROOT/INVENTORY/ITEM">
     <composer:value xpath="./ITEMNAME" /><br>
     <composer:value xpath="./SKU" /><br>
     <composer:value xpath="./QTY" /><br>
     <composer:value xpath="./PRICE" /><br>
  </composer:forEach>

A node value (XML data corresponding to the elements under /ITEM) will be placed in the page where each value tag occurs.

hasnopart

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.

ATTRIBUTE	PURPOSE
name	Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.

NOTE: Required attributes are shown in boldface type.

The hasnopart tag can be used to enclose a block that should execute only when a particular service (identified by name) has no Output part.

See haspart (below) for additional information and a code example.

hasnovalue

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.

part

Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).

xpath

An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that returns a DOM node that may contain data.

ATTRIBUTE	PURPOSE
name	Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.
part	Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).
xpath	An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that returns a DOM node that may contain data.

NOTE: Required attributes are shown in boldface type.

This tag can be used to enclose a block of markup that should only be evaluated if a particular node in a particular output message part contains no data. In other words, this tag can be used in cases where it is necessary to handle an empty node. It is complementary in function to the hasvalue tag (discussed further below).

haspart

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.

part

Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).

ATTRIBUTE	PURPOSE
name	Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.
part	Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).

NOTE: Required attributes are shown in boldface type.

This tag enables conditional processing based on the existence of a particular output message part from a particular service. Its behavior is similar to that of the hasvalue tag in that a number of HTML statements, JSP markup blocks, and/or <composer:> tags can be embedded between the < composer:haspart> opening tag and </composer:haspart> closing tag, and the embedded tags will be processed only if the specified part exists.

For example, the following JSP code fragment will display an HTML table and XML data retrieved from "myService" if and only if the service actually produced a part named "myFirstPart".

  <composer:haspart name="myServiceName" part="myFirstPart">
    <table>
      <tr>
        <td>some data</td>
        <td>
          <composer:value name="myServiceName" 
           part="mySecondPart" xpath="root/element/element"/>
        </td>
      </tr>
    </table>
  </composer:haspart>

hasvalue

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.

part

Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).

xpath

An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that returns a DOM node that may contain data.

ATTRIBUTE	PURPOSE
name	Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.
part	Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).
xpath	An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that returns a DOM node that may contain data.

NOTE: Required attributes are shown in boldface type.

The hasvalue tag enables conditional processing based on a given XPath node (in a particular message part, from a given service's output) being non-empty. This makes it possible for you to "skip over" a particular node if it is empty, but process or display it if it contains data. For example, consider the following usage:

  <composer:value xpath="./CUSTOMER/NAME" /><br>
  <composer:hasvalue xpath="./CUSTOMER/ADDRESS">
         <composer:value xpath="./CUSTOMER/ADDRESS" /><br/>
  </composer:hasvalue>
  <composer:value xpath="./CUSTOMER/CITY" /><br/>
  <composer:value xpath="./CUSTOMER/STATE" /><br/>
  <composer:value xpath="./CUSTOMER/ZIP" /><br/>

Data from the /ADDRESS node, in this example, will show up in the JSP's output only if that node is non-empty. Otherwise, it is skipped.

if

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.

part

Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).

xpath

An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that evaluates to a boolean value.

ATTRIBUTE	PURPOSE
name	Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.
part	Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).
xpath	An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that evaluates to a boolean value.

NOTE: Required attributes are shown in boldface type.

The <composer:if> tag allows conditional evaluation of a block of markup based on the boolean value of an XPath expression. Consider the following example:

  <composer:if xpath="string(./CUSTOMER/STATE)=&quot;CA&quot;">
  	 <b>
  <composer:value xpath="./CUSTOMER/STATE" />
  </b>
  </composer:if>

In this example, if /STATE is "CA", the state value will be written out to output, wrapped in boldface tags.

A corresponding if block based on modification of the XPath to use inequality (instead of equality) can be used inline with the above block to achieve an "else" branch, so that states that are not "CA" are not boldfaced.

value

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.

part

Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).

xpath

An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that returns a DOM node containing data.

ATTRIBUTE	PURPOSE
name	Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.
part	Scopes the tag behavior to a particular message part associated with the service specified by `name` (above).
xpath	An XPath expression to be evaluated against the document associated with `part` and `name` attributes (or with the Output message part, if no `part` attribute is specified). This expression should be one that returns a DOM node containing data.

NOTE: Required attributes are shown in boldface type.

The value tag allows you to retrieve data from a DOM node at a specified location in a specified message part from a named service. The node location must be specified via an XPath expression. For example:

  <composer:value xpath="/MYROOT/INVENTORY/DATE" />

The data at /MYROOT/INVENTORY/DATE will be placed in the JSP output. This example presumes that /MYROOT/INVENTORY/DATE is a single, discrete node representing a single piece of XML data. When a nodeset is returned, you should iterate over the individual nodes by means of the forEach tag, then apply the value tag to each individual node:

  <composer:forEach name="inventory" xpath="/MYROOT/INVENTORY/ITEM">
     <composer:value xpath="./ITEMNAME" /><br>
     <composer:value xpath="./SKU" /><br>
     <composer:value xpath="./QTY" /><br>
     <composer:value xpath="./PRICE" /><br>
  </composer:forEach>

In this example, it is assumed that /MYROOT/INVENTORY/ITEM returns a set of nodes, each one in turn containing ITEMNAME, SKU, QTY, and PRICE child nodes. The above JSP fragment outputs a listing of the relevant data for each ITEM.

Notice that the opening forEach tag specifies a name attribute with a value of inventory. This is the local (within this JSP) name of the service whose Output DOM we are accessing at this point. You might very well execute more than one service from a single JSP page, then access data from each resulting Output DOM. The name attribute allows you to operate on different Output DOMs within the same JSP session.

For More Information

The xcs-src.jar file in the \xc_api folder of your Composer installation (under \Common) contains the actual Java source code for the Composer tag library. It also contains source code for various trigger classes, converter classes, and deployment-related interfaces and support classes that Composer relies on at runtime. Javadoc API documentation for these classes is available in the same folder.

The Composer JSP Tag Library

Preparing to Use the Tag Library

Custom Tags Defined in composer-taglib.tld

Tag API

Converter Classes

com.sssw.b2b.xs.service.conversion.GXSInputFromHttpParams

com.sssw.b2b.xs.service.conversion.GXSInputFromHttpContent

com.sssw.b2b.xs.service.conversion.GXSInputFromHttpMultiPartRequest

com.sssw.b2b.xs.service.conversion.GXSInputFromHttpSpecificParam

com.sssw.b2b.xs.service.conversion.GXSInputFromJavaObject

hasnopart ATTRIBUTE PURPOSE name Scopes the behavior of the tag to the service whose name attribute (as defined within an execute tag elsewhere in the JSP) has an identical value.

haspart ATTRIBUTE PURPOSE name Scopes the behavior of the tag to the service whose name attribute (as defined within an execute tag elsewhere in the JSP) has an identical value. part Scopes the tag behavior to a particular message part associated with the service specified by name (above).

For More Information

hasnopart

ATTRIBUTE

PURPOSE

name

Scopes the behavior of the tag to the service whose `name` attribute (as defined within an `execute` tag elsewhere in the JSP) has an identical value.