![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Composer User's Guide
APPENDIX A
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.
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.
To tag-enable your JSP-based web app:
Near the top of your JSP(s), insert the following line:
<%@ taglib uri="/composer" prefix="composer" %>
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>
The composer-taglib.tld
file defines the following custom tags:
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.
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.
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):
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.
This opens an InputStream from the supplied HttpServletRequest
and retrieves the content of the request buffer, which it expects to be in XML format.
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.
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."
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.
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.
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.
ATTRIBUTE |
PURPOSE |
---|---|
name |
Scopes the behavior of the tag to the service whose |
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.
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).
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>
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.
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)="CA""> <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.
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.
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.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...