40 Creating Transformations with the XSLT Map Editor

This chapter describes how to use the XSLT Map Editor to create, design, and test data transformations between source schema elements and target schema elements.

This chapter includes the following sections:

• Introduction to the XSLT Map Editor

• Creating an XSLT Map

• Editing an XSLT Map in Map View

• Editing an XSLT Map in XSLT View

• Using XPath Expressions

• Using Auto Map to Map Complex Nodes

• Checking the Completion Status of the Map

• Testing the Map

• Importing an External XSLT Map

• Using Variables and Parameters

• Substituting Elements and Types

• Using Named Templates

• Using Template Rules

• Using the Execution View

• Debugging the XSLT Map

• Troubleshooting Memory Issues

• Setting XSL Map Preferences

40.1 Introduction to the XSLT Map Editor

The XSLT Map Editor enables you to edit XSLT stylesheets using a graphical editor. It also provides the feature to directly edit the XSLT source.

Figure 40-1 shows the XSLT Map Editor. You can switch between the graphical editor and the source view using the tabs at the bottom of the editor. Click Design to edit using the graphical editor. Click Source to edit using the source editor.

Figure 40-1 XSLT Map Editor

Description of "Figure 40-1 XSLT Map Editor"

You can move back and forth between the Source and Design tabs. Any change made under one tab is reflected in the other tab. A History tab is also available to enable you to view the revision history, and revert to any point in the edit history.

The XSLT Map Editor fully supports XSLT 1.0 and XPath 1.0.

If you want to use XSLT 2.0, then you can change the XSLT version in the source view.

All XSLT 2.0-specific constructs must be added in the source view. You can then choose to switch to the design view, and continue to edit the map. XSLT 2.0-specific constructs are shown in design view, but can be modified only in the source view. XPath 2.0 constructs can also be added in the design view. However, XPath 2.0 constructs are not parsed into separate graphical elements in the design view. You must edit the full XPath statement in text form.

The XSLT Map Editor provides the following edit views under the design view:

• Map View

• XSLT View

You can switch between the two views using the buttons at the top right hand corner of the XSLT editor. Click Map to use the traditional Map View of the XSLT editor. Click XSLT to use the XSLT View for more complex XSLT maps.

40.1.1 Using the Map View

Figure 40-1 shows the Map View of the XSLT Map Editor. The left pane contains the source tree representing the incoming source XML document. The source tree can be created from an XSD schema file or a sample XML file.

The center pane, or the canvas, is the place where you drop XPath expressions and functions that can be mapped to XSLT elements.

The right pane is the target pane representing a merged view of the XSLT being created, and the target tree that represents the target schema. The target tree can be created from an XSD schema file or a sample XML file.

The grayed nodes, in italics, in the target tree represent nodes that haven't been mapped yet. These nodes are not part of the XSLT, and are displayed for convenience. Once a grayed node is mapped, it appears in regular font, and gets represented in the XSLT map.

Map View supports drag-and-drop mappings from source tree to target tree. Map View also supports XPath function calls and XSLT statements such as xsl:if and xsl:for-each.

As Map View does not separate the XSLT statements from the target tree, it is limited to the following:

• Only one XSLT template rule with the match='/' attribute is supported.

• The following XSLT statements are supported: xsl:for-each, xsl:value-of, xsl:text, xsl:if, xsl:choose/when, xsl:variable and xsl:param.

Use the XSLT View for complex XSLT statements that require separating the XSLT statements from the target tree.

40.1.2 Using the XSLT View

The XSLT View is a more advanced mode that enables you to separate the XSLT statements from the target tree document. This enables you to create complex XSLT statements without leaving the design view. Source and target schemas are optional in the XSLT View.

The XSLT View includes the same panes as the Map View, except that the right target pane is divided into two panes. The top pane is called the XSLT pane and the lower pane is called the target pane. If no target schema is defined, then the lower pane is not shown. If no source schema is defined, the source pane is still displayed to enable you to add parameters and variables, whose values can be referenced by the XSLT.

In XSLT View, you can create any series of XSLT statements without having to intersperse these statements around target tree nodes. For instance, in the 11g mapper, all xsl:if statements had to contain a single target output node. In XSLT View, the xsl:if statement can be used anywhere, and can contain any other XSLT statement.

The XSLT View supports all XSLT 1.0 statements. The XSLT View also supports multiple template rules with or without source and target schemas. The XSLT View enables you to graphically display and edit any XSLT stylesheet, irrespective of the complexity involved.

40.1.3 Using the Components Window

The Components window contains all the XPath functions and XSLT elements and templates that you can use in your XSLT map.

The Components window is located at the upper right-hand corner of Oracle JDeveloper, by default. If the Components window does not appear, click Components under the Window menu to display the Components window. You can optionally choose to drag the Components window to any convenient location in the JDeveloper window. You can also resize the Components window, as desired.

The Components window organizes these functions, elements, and templates under the following categories:

• Advanced XPath:

• General XPath:

• XML:

• XSLT Elements:

• XSLT Templates:

• All Pages:

• User Defined:

• My Components:

40.1.4 Using the Properties Window

The Properties window shows the content and properties of the item selected in the XSLT Map Editor. Some of these properties can also be edited.

The Properties window is located below the XSLT Map Editor, by default. If the Properties window does not appear, click Properties under the Window menu to display the Properties window. You can optionally choose to drag the Properties window to any convenient location within the JDeveloper window. You can also resize the Properties window, as desired.

The Properties window, in general, can be used to display and edit the properties of the following items:

---

Selected Element in Editor	What is Shown in Properties Window	Whether Editable (Yes/No)
Source tree node	Schema Information for the selected element or attribute.	No
Target tree node	Schema information for the selected element or attribute.	No
XSLT tree node: XSLT element	XSLT element attributes and their values	Yes
XSLT tree node: literal element or attribute	Literal element or attribute name and namespace	Yes
XPath expression folder in Canvas pane	Full text XPath expression	Yes
Function icon within expression folder in Canvas pane	XPath field for each parameter of the function	Yes
Line connecting source and target node	Full text XPath expression	Yes

---

40.2 Creating an XSLT Map

XSLT maps can be created from scratch, or from other editors such as BPEL, BPM, and Mediator.

40.2.1 How to Create an XSLT Map

To create an XSLT Map:

1. From the File main menu, select New > XSL Map. Alternatively, right-click the project folder and select New > XSL Map.

   The Create XSL Map File dialog appears.

2. Under File Name, specify a name for your .xsl map file.
3. Under Directory name, select the destination directory for the .xsl file.
4. Under Sources, select Use Source Schema(s) to specify a source schema for the map.
5. Under Primary Source, click Browse to select the source schema. The Select Schema dialog box appears.
6. Choose Select Schema if you want to use an XSD schema file or WSDL file for the source schema.

   Note:

   You can alternatively use a sample XML file as the schema source.

   Select Generate from XML to generate the schema from an XML file. Select the sample file and click Open. Go to Step 9.

7. Click Browse to select a schema file and element for the source schema. The Type Chooser dialog appears.
8. Select the schema file and the corresponding element from the project schema files or project WSDL files tree. Click OK.

   If the schema or wsdl file that you need is not available in the tree, you may import a schema or wsdl file by clicking the Import Schema File or Import WSDL File button at the top right corner of the dialog.

9. Click OK in the Select Schema dialog.

   Note:

   Under Additional Sources, you can click the Add Schema button identified by the green plus icon (+) to add any additional sources in the form of parameters.

10. Select Use target schema to specify a target schema for your XSL map.
11. Click Browse to select the target schema. The Select Schema dialog appears.
12. After selecting the target schema, click OK in the Select Schema dialog.

    Note:

    When a Target Schema is used, initial element and attribute nodes may be generated in the XSLT pane depending upon the current Preferences setting.

    The default setting is to generate a root template with a match=''/'' attribute followed by all required elements and attributes in the target schema.

13. Click OK to create the XSL map file.

    Note:

    • Once the XSLT map is created you may add or replace source and target schemas by selecting the appropriate option from the context menu in the canvas pane.

      For example, you may add additional sources as parameters by selecting Add Parameter from the context menu on the source pane.

    • You may edit a source or target schema file that is being used by an XSLT Map, using JDeveloper. Upon saving the schema file, the source or target tree in the XSLT editor is automatically updated.

40.2.2 How to Create an XSL Map File in Oracle BPEL Process Manager

An XSLT Transform activity enables you to create a transformation using the XSLT Map Editor in Oracle BPEL Process Manager. This tool enables you to map one or more source elements to target elements. For example, you can map incoming source purchase order schema data to outgoing invoice schema data.

To create an XSL map file in Oracle BPEL Process Manager:

1. From the Components window, drag an XSLT Transform activity into your BPEL process diagram. Figure 40-2 provides an example.

   Figure 40-2 Transform Activity

   
   Description of "Figure 40-2 Transform Activity"

2. Double-click the XSLT Transform activity.

   The Transform dialog shown in Figure 40-3 appears.

   Figure 40-3 Transform Dialog

   
   Description of "Figure 40-3 Transform Dialog"

3. Specify the following information:

   1. Add source variables from which to map elements by clicking the Add icon and selecting the variable and part of the variable as needed (for example, a payload schema consisting of a purchase order request).

      Note:

      You can select multiple input variables. The first variable defined represents the main XML input to the XSL map. Additional variables that are added here are defined in the XSL map as input parameters.

   2. Add target variables to which to map elements.

      Note:

      Figure 40-3 shows the Edit Transformation dialog for BPEL 2.0. The Edit Transformation dialog for BPEL 1.1 is slightly different. In the Edit Transformation dialog for BPEL 1.1, you can select the Target Variable from the list of variables.

   3. Add the target part of the variable (for example, a payload schema consisting of an invoice) to which to map.

4. In the Mapper File field, specify a map file name or accept the default name. You create your mappings in the map file using the XSLT Map Editor.

5. Click the Add icon (second icon to the right of the Mapper File field) to create a mapping. If the file exists, click the Edit icon (third icon) to edit the mapping.

   The XSLT Map Editor appears.

   Note:

   If you select a file with a.xslt extension such as xform.xslt, it opens the XSLT Map Editor to create an XSL file named xform.xslt.xsl, even though your intention was to use the existing xform.xslt file. A .xsl extension is appended to any file that does not have a .xsl extension, and you must create the mappings in the new file. As a work around, ensure that your files first have an extension of .xsl. If the XSL file has an extension of .xslt, then rename it to .xsl.

6. Go to Introduction to the XSLT Map Editor for an overview of using the XSLT Map Editor.

40.2.3 How to Create an XSL Map File from Imported Source and Target Schema Files in Oracle BPEL Process Manager

The following steps provide a high level overview of how to create an XSL map in Oracle BPEL Process Manager using a po.xsd file and invoice.xsd file.

To create an XSL map file from imported source and target schema files in Oracle BPEL Process Manager:

1. In Oracle JDeveloper, select the application project in which you want to create the new XSL map.

2. Import the po.xsd and invoice.xsd files into the project. For example:

   1. In the Structure window of Oracle JDeveloper, right-click Schemas.

   2. Select Import Schemas.

3. Right-click the selected project and select New.

   The New Gallery dialog appears.

4. In the Categories tree, expand SOA Tier and select Transformations.

5. In the Items list, double-click XSL Map.

   The Create XSL Map File dialog appears. This dialog enables you to create an XSL map file that maps a root element of a source schema file or Web Services Description Language (WSDL) file to a root element of a target schema file or WSDL file. Note the following details:

   • • WSDL files that have been added to the project appear under Project WSDL Files.

     • Schema files that have been added to the project appear under Project Schema Files.

     • Schema files that are not part of the project can be imported using the Import Schema File facility. Click the Import Schema File icon (first icon to the right and above the list of schema files).

     • WSDL files that are not part of the project can be imported using the Import WSDL File facility. Click the Import WSDL File icon (second icon to the right and above the list of schema files).

6. In the File Name field, enter a name for the XSL map file.

7. Select the root element for the source and target trees. In the example in Figure 40-4, the PurchaseOrder element is selected for the source root element and the Invoice element is selected for the target root element.

   Figure 40-4 Expanded Target Section

   
   Description of "Figure 40-4 Expanded Target Section"

8. Click OK.

   A new XSL map is created, as shown in Figure 40-5.

   Figure 40-5 New XSL Map

   
   Description of "Figure 40-5 New XSL Map"

9. Save and close the file now or begin to design your transformation. Information on using the XSLT Map Editor is provided in Introduction to the XSLT Map Editor.

10. From the Components window, drag a transform activity into your BPEL process.

11. Double-click the transform activity.

12. Specify the following information:

    1. Add source variables from which to map elements by clicking the Add icon and selecting the variable and part of the variable as needed (for example, a payload schema consisting of a purchase order request).

       Note:

       You can select multiple input variables. The first variable defined represents the main XML input to the XSL map. Additional variables that are added here are defined in the XSL map as input parameters.

    2. Add target variables to which to map elements.

    3. Add the target part of the variable (for example, a payload schema consisting of an invoice) to which to map.

13. To the right of the Mapper File field, click the Search icon (first icon) to browse for the map file name you specified in Step 6.

14. Click Open.

15. Click OK.

    The XSLT Map Editor displays your XSL map file.

16. Go to Introduction to the XSLT Map Editor for an overview of using the XSLT Map Editor.

40.2.4 How to Create an XSL Map File in Oracle Mediator

The XSLT Map Editor enables you to create an XSL file to transform data from one XML schema to another in Oracle Mediator. After you define an XSL file, you can reuse it in multiple routing rule specifications. This section provides an overview of creating a transformation map XSL file with the XSLT Map Editor.

The XSLT Map Editor is available from the Applications window in Oracle JDeveloper by clicking an XSL file or from the Mediator Editor by clicking the transformation icon, as described in the following steps. You can either create a new transformation map or update an existing one.

To launch the XSLT Map Editor from the Mediator Editor and create or update a data transformation XSL file, follow these steps.

To create an XSL map file in the Mediator Editor:

1. Open the Mediator Editor.
2. To the left of Routing Rules, click the + icon to open the Routing Rules panel.

   The transformation map icon is visible in the routing rules panel.

3. To the right of the Transform Using field shown in Figure 40-6, click the appropriate transformation map icon to open the Transformation Map dialog.

   Figure 40-6 Routing Rules

   
   Description of "Figure 40-6 Routing Rules"

   The appropriate Transformation Map dialog displays with options for selecting an existing transformation map (XSL) file or creating a new map file. For example, if you select the transformation map icon in the Synchronous Reply section, the dialog shown in Figure 40-7 appears.

   Figure 40-7 Reply Transformation Map Dialog

   
   Description of "Figure 40-7 Reply Transformation Map Dialog"

   If the routing rule includes a synchronous reply or fault, the Reply Transformation Map dialog or Fault Transformation Map dialog contains the Include Request in the Reply Payload option. When you enable this option, you can obtain information from the request message. The request message and the reply and fault message can consist of multiple parts, meaning you can have multiple source schemas. Callback and callback time-out transformations can also consist of multiple parts.

   Each message part includes a variable. For a reply transformation, the reply message includes a schema for the main part (the first part encountered) and an in.partname variable for each subsequent part. The include request message includes an initial.partname variable for each part.

   For example, assume the main reply part is the out1.HoustonStoreProduct schema and the reply also includes two other parts that are handled as variables, in.HoustonStoreProduct and in.HoustonStoreProduct2. The request message includes three parts that are handled as the variables initial.expense, initial.expense2, and initial.expense3. Figure 40-8 provides an example.

   Figure 40-8 Reply Part

   
   Description of "Figure 40-8 Reply Part"
4. Choose one of the following options:

   • Click the Search icon to browse for an existing XSLT map file (or accept the default value).

   • Click the Add icon, to create a new XSLT map file, and then enter a name for the file (or accept the default value).

     If the source message in the WSDL file has multiple parts, variables are used for each part, as mentioned in Step 3. When the target of a transformation has multiple parts, multiple transformation files map to these targets. In this case, Oracle Mediator's transformation dialog has a separate panel for each target part. For example, Figure 40-9 shows a request in which the target has three parts:

   Figure 40-9 Request Transformation Map Dialog

   
   Description of "Figure 40-9 Request Transformation Map Dialog"
5. Click OK.

   If you chose to create a new XSLT map, the XSLT Map Editor opens to enable you to correlate source schema elements to target schema elements.

6. Go to Introduction to the XSLT Map Editor for an overview of using the XSLT Map Editor.

40.2.5 What You May Need to Know About Creating an XSL Map File

XSL file errors do not display during a transformation at runtime if you manually remove all existing mapping entries from an XSL file except for the basic format data. Ensure that you always specify mapping entries. For example, assume you perform the following actions:

1. Create a transformation mapping of input data to output data in the XSLT Map Editor.
2. Design the application to write the output data to a file using the file adapter.
3. Manually modify the XSL file and remove all mapping entries except the basic format data. For example:

   <?xml version="1.0" encoding="UTF-8" ?> 
   <xsl:stylesheet version="1.0" 
   xmlns:xp20="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.fu 
   nctions.Xpath20" 
   xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/" 
   xmlns:ns0="http://xmlns.oracle.com/pcbpel/adapter/file/MediaterDemo/Validation 
   UsingSchematron/WriteAccounInfoToFile/" 
   xmlns:orcl="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.fu 
   nctions.ExtFunc" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:dvm="http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.LookupValue 
   " 
   xmlns:hwf="http://xmlns.oracle.com/bpel/workflow/xpath" 
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
   xmlns:mhdr="http://www.oracle.com/XSL/Transform/java/oracle.tip.mediator.servi 
   ce.common.functions.GetRequestHeaderExtnFunction" 
   xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath" 
   xmlns:imp1="http://www.mycompany.com/MyExample/NewAccount" 
   xmlns:tns="http://oracle.com/sca/soapservice/MediaterDemo/ValidationUsingSchem 
   atron/CreateNewCustomerService" 
   xmlns:xref="http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRe 
   fXPathFunctions" 
   xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   xmlns:ora="http://schemas.oracle.com/xpath/extension" 
   xmlns:inp1="http://www.mycompany.com/MyExample/NewCustomer" 
   exclude-result-prefixes="xsi xsl tns xsd inp1 ns0 imp1 plt xp20 bpws orcl dvm 
   hwf mhdr ids xref ora"> 
   </xsl:stylesheet> 
   

   While the file can still be compiled, the XSL mapping is now invalid.

4. Deploy and create an instance of the SOA composite application.

   During instance creation, an exception error occurs when the write operation fails because it did not receive any input. However, no errors are displayed during XSL transformation.

40.2.6 What Happens at Runtime If You Pass a Payload Through Oracle Mediator Without Creating an XSL Map File

If you design a SOA composite application to pass a payload through Oracle Mediator without defining any transformation mapping or assigning any values, Oracle Mediator passes the payload through.

However, for the payload to be passed through successfully, the source and target message part names must be the same, and of the same type. Otherwise, the SOA project fails to compile. For projects that have been upgraded from 11g, the project compiles, but the target reference may fail to execute with error messages such as Input source like Null or Part not found.

40.2.7 What Happens If You Receive an Empty Namespace Tag in an Output Message

The XML representation from an XSL file may differ from that used in a scenario in which a message is passed through with a transformation being performed or in which an assign activity is used, even though the XMLs are syntactically and semantically the same. For example, if you use an Oracle Mediator service component to map an inbound payload that includes an element without a namespace to an outbound payload, you may receive an empty namespace tag in the output message.

<Country xmlns="">US</Country> 

This is the correct behavior. A blank namespace, xmlns="", is automatically added.

40.3 Editing an XSLT Map in Map View

This section discusses basic functionality available in Map View. The remaining sections discuss editing in the XSLT View with notes on restrictions that might apply to Map View for the specific activity being discussed.

40.3.1 How to Perform a Value Copy by Linking Nodes

To copy the value of an attribute or leaf-element in the source to an attribute or leaf-element in the target, drag a line from the source node to the target node. A green highlighted line appears as you are dragging and dropping. When you complete the drop, a line is drawn connecting the source and target nodes.

Figure 40-10 shows the map view where the PurchaseOrder/ID source element is mapped to the Invoice/ID target element. Notice that a line connects the source and target nodes. Also, the ID element in the target tree is no longer grayed, and appears in normal font. This means that the ID element has been added to the XSLT map.

Figure 40-10 Copying a Leaf Node in Map View

Description of "Figure 40-10 Copying a Leaf Node in Map View"

40.3.2 How to Create an Empty Node in the Output Document

To create an empty node in the output document:

1. Select the grayed node in the target pane.
2. Right-click the node, and select Create Node in XSLT from the context menu.

40.3.3 How to Set a Literal Text Value for a Target Node

To set a literal text value on an output/target node:

1. Right-click the node in the target pane. Select Edit Text Value from the context menu that appears.

   The Set Text dialog appears.

2. Enter the text value to be assigned to the node. Do not enclose the text in quotation marks.
3. Click OK.

   A yellow T icon appears next to the node indicating that a text value has been set for the item. If you move the mouse cursor over the node, the corresponding text appears. If the node was grayed earlier, it no longer appears gray, as the node has been added to the XSLT map.

40.3.4 How to Add an XSLT Statement

You can add XSLT statements to handle constructs such as conditional statements (if-then-else) and iterations (for-each).

40.3.4.1 To Add an XSLT Statement:

1. Right-click the target node, and select Add XSL Instruction from the context menu that appears. A submenu appears with the various XSL statements that you can add.

2. Select the desired XSL statement, such as if, choose, or for-each, from the submenu.

The xsl:text and xsl:variable XSLT statements can only be added for existing nodes.

40.3.4.2 To Add an xsl:text or xsl:variable Statement:

1. Make sure that the target node exists in the XSLT.

   If the target node appears gray, right-click the target node and select Create Node in XSLT from the context menu that appears. The node no longer appears gray, and is added to the XSLT map.

2. Right-click the target node, and select Add XSL Instruction from the context menu that appears. A submenu appears with the various XSL statements that you can add.

3. Select text or variable from the submenu.

   Note:

   The xsl:copy-of statement is not supported in Map View. It is supported in XSLT View.

You can also choose to drag and drop XSLT statements from the Components window.

40.3.4.3 To Drag and Drop an XSLT statement to a Target Node:

1. Select the XSLT Elements page from the Components Window. A list of statement categories appear.

2. Locate a supported statement, for Map View, from a category. For example, the for-each statement appears under the Flow Control category.

   The Map View supports only a subset of XSLT statements. These statements are discussed individually in the sections that follow.

3. Drag the statement to the desired target node until green highlighting appears over the node, indicating that the statement can be dropped.

4. Drop the statement to insert it into the XSLT map.

The following sections enumerate the different XSLT statements that you can add using the map view:

• How to Add Conditional Processing Using xsl:if

• How to Add Conditional Processing Using xsl:choose

• How to Add Loops Using xsl:for-each

• How to Add xsl:sort for an xsl:for-each Statement

• How to Duplicate XSLT Instructions

40.3.4.4 How to Add Conditional Processing Using xsl:if

If a source and target node are optional in their respective schemas, the xsl:if statement is often used to test for the existence of the source node before creating the corresponding target node.

In Figure 40-11, the Comment node is optional for both the source and the target. The square brackets around the Comment nodes indicate that they are optional nodes.

Figure 40-11 Optional Nodes in Source and Target Trees

Description of "Figure 40-11 Optional Nodes in Source and Target Trees"

If the source Comment node does not exist in the source document at runtime, its value is empty. This creates a Comment node in the target document and sets its value to empty.

To prevent creating an empty node when the source node is not there, add an xsl:if statement above the target Comment node. The xsl:if statement tests for the existence of the source node before creating the target node.

40.3.4.4.1 To add an xsl:if statement using the context menu:

1. Right-click the target node and select Add XSL Instruction -> if from the context menu that appears. An xsl:if node is added as the parent node of the target node.

2. To set the condition for the xsl:if node, drag and drop the source node to the xsl:if node.

   Figure 40-12 Dragging the Source Node to the xsl:if Node

   
   Description of "Figure 40-12 Dragging the Source Node to the xsl:if Node"

40.3.4.4.2 To add an xsl:if statement using drag and drop:

1. In the Components window, select the XSLT Elements page.

2. Expand the Flow Control section. You can click the plus sign (+) next to Flow Control to expand the section.

3. Drag the if icon to the right side of the target node until you can see the green highlighting, as shown in Figure 40-13.

   Figure 40-13 Adding an xsl:if Statement

   
   Description of "Figure 40-13 Adding an xsl:if Statement"

4. Drop the if icon while the green highlighting is visible. An xsl:if node is added as the parent node of the target node.

5. To set the condition for the xsl:if node, drag and drop the source node to the xsl:if node.

When viewed in source view, the xsl:if statement looks similar to the following:

<xsl:if test="/ns0:PurchaseOrder/ns0:Comment">
    <tns1:Comment>
       <xsl:value-of select="/ns0:PurchaseOrder/ns0:Comment"/>
    </tns1:Comment>
</xsl:if>

The preceding xsl:if statement ensures that the target node is created only if the source node exists.

40.3.4.5 How to Add Conditional Processing Using xsl:choose

The xsl:choose statement is similar to the xsl:if construct. You can use the xsl:choose XSLT statement if there are multiple conditions to evaluate.

Figure 40-14 shows the XSLT Map Editor containing sample source and target schemas. The source schema has an xsd:choice construct defined. The source schema can contain either an HQAccount or a BranchAccount node, but not both. The target schema has a BilledToAccount/AccountNumber node that must be defined.

If the HQAccount node exists, you must copy its AccountNumber to BilledToAccount/AccountNumber in the target. If the HQAccount node does not exist, you must copy the AccountNumber from the BranchAccount node. You can use the xsl:choose statement to accomplish this task.

Figure 40-14 XSLT Map Editor Containing Sample Source and Target Schemas

Description of "Figure 40-14 XSLT Map Editor Containing Sample Source and Target Schemas"

40.3.4.5.1 To add an xsl:choose statement using the context menu:

1. Right-click the target node and select Add XSL Instruction -> choose from the context menu that appears.

   A choose statement is added as the parent node of the target node along with an xsl:when statement. Figure 40-15 shows the result of adding the xsl:choose statement to the AccountNumber node.

   Figure 40-15 Adding an xsl:choose Statement

   
   Description of "Figure 40-15 Adding an xsl:choose Statement"

   An xsl:choose statement can contain multiple xsl:when statements followed by an optional xsl:otherwise statement.

2. To add an xsl:otherwise node to the xsl:choose node, right-click xsl:choose in the target tree and select Add XSL Instruction -> otherwise from the context menu that appears.

   Figure 40-16 shows the result of adding the xsl:otherwise statement to the xsl:choose statement. Note that the AccountNumber node is copied to each section of the xsl:choose statement.

   Figure 40-16 Adding an xsl:otherwise Statement to an xsl:choose Statement

   
   Description of "Figure 40-16 Adding an xsl:otherwise Statement to an xsl:choose Statement"

3. Map the xsl:when node to the source node whose existence is to be tested. In our current example, you drag a line from the HQAccount node in the source to the xsl:when node in the target.

4. Map the xsl:when and xsl:otherwise cases. In the current example, you drag a line from the HQAccount/AccountNumber node to the xsl:choose/xsl:when/AccountNumber node. Similarly, you drag a line from the BranchAccount/AccountNumber node to the xsl:choose/xsl:otherwise/AccountNumber node.

   Figure 40-17 shows the completed xsl:choose construct.

   Figure 40-17 Sample xsl:choose Construct

   
   Description of "Figure 40-17 Sample xsl:choose Construct"

40.3.4.5.2 To add an xsl:choose statement using drag and drop:

1. In the Components window, select the XSLT Elements page.

2. Expand the Flow Control section. You can click the plus sign (+) next to Flow Control to expand the section.

3. Drag the choose icon to the right side of the target node until you can see the green highlighting, as shown in Figure 40-18.

   Figure 40-18 Dragging the choose Icon to the Target Node

   
   Description of "Figure 40-18 Dragging the choose Icon to the Target Node"

4. Drop the choose icon while the green highlighting is visible. An xsl:choose node is added as the parent node of the target node. The xsl:choose node contains a child xsl:when node.

5. To create the otherwise clause, drag the otherwise icon from the Components Window to the left of the xsl:choose node until you can see the green highlighting, as shown in Figure 40-19.

   Figure 40-19 Dragging the otherwise Icon to the xsl:choose Node

   
   Description of "Figure 40-19 Dragging the otherwise Icon to the xsl:choose Node"

6. Drop the otherwise icon while the green highlighting is visible. An xsl:otherwise node is added as the child node of the xsl:choose node.

7. Map the xsl:when node to the source node whose existence is to be tested. In our current example, you drag a line from the HQAccount node in the source to the xsl:when node in the target.

8. Map the xsl:when and xsl:otherwise cases. In our current example, you drag a line from the HQAccount/AccountNumber node to the xsl:choose/xsl:when/AccountNumber node. Similarly, you drag a line from the BranchAccount/AccountNumber node to the xsl:choose/xsl:otherwise/AccountNumber node.

   Figure 40-17 shows the completed xsl:choose construct.

When viewed in source view, the xsl:choose statement looks similar to the following:

<BilledToAccount>
   <xsl:choose>
     <xsl:when test="/ns0:PurchaseOrder/HQAccount">
       <AccountNumber>
         <xsl:value-of select="/ns0:PurchaseOrder/HQAccount/AccountNumber"/>
       </AccountNumber>
     </xsl:when>
     <xsl:otherwise>
       <AccountNumber>
         <xsl:value-of select="/ns0:PurchaseOrder/BranchAccount/AccountNumber"/>
       </AccountNumber>
     </xsl:otherwise>
   </xsl:choose>
</BilledToAccount>

40.3.4.6 How to Add Loops Using xsl:for-each

The xsl:for-each statement can be used to loop over a source node-set, or set of nodes, and to create output nodes for each node in the source node-set.

40.3.4.6.1 To add an xsl:for-each statement using the context menu:

1. Right-click the target node and select Add XSL Instruction -> for-each from the context menu that appears. An xsl:for-each statement is added as the parent node of the target node.

2. To set the source node-set to loop over, drag and drop the source node to the xsl:for-each statement.

   Figure 40-20 shows an example of creating the xsl:for-each statement. The source PurchaseOrder document contains the Item node. The Item node is a repeating node, as represented by its icon. For each Item node in the source document, an Item node is created in the target document using the xsl:for-each statement.

   Figure 40-20 Creating an xsl:for-each Statement

   
   Description of "Figure 40-20 Creating an xsl:for-each Statement"

40.3.4.6.2 To add an xsl:for-each statement using drag and drop:

1. In the Components window, select the XSLT Elements page.

2. Expand the Flow Control section. You can click the plus sign (+) next to Flow Control to expand the section.

3. Drag the for-each icon to the right side of the target node until you can see the green highlighting, as shown in Figure 40-21.

   Figure 40-21 Dragging the for-each Icon to the Target Node

   
   Description of "Figure 40-21 Dragging the for-each Icon to the Target Node"

4. Drop the for-each icon while the green highlighting is visible. An xsl:for-each node is added as the parent node of the target node.

5. To set the source node-set to loop over, drag and drop the source node to the xsl:for-each statement, as shown in Figure 40-20.

When viewed in the source view, the xsl:for-each statement looks similar to the following:

<ShippedItems>
  <xsl:for-each select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
     <Item/>
  </xsl:for-each>
</ShippedItems>

Note that the Item node, created inside the xsl:for-each statement, is an empty node. You can map elements under the target Item node to set values for them.

For example, as shown in Figure 40-22, if you drag and drop Qty to Quantity, the value of the Qty element is copied to the Quantity element in the output.

Figure 40-22 Mapping Qty to Quantity

Description of "Figure 40-22 Mapping Qty to Quantity"

The following example shows the resulting code in source view. It also shows a sample source document and output document snippet.

<ShippedItems>
  <xsl:for-each select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
    <Item>
      <Quantity>
        <xsl:value-of select="Qty"/>
      </Quantity>
    </Item>
  </xsl:for-each>
</ShippedItems>

The following snippet shows some sample values for the source document:

<HighPriorityItems>
     <Item PartNum="000-AA">
          <Qty>20</Qty>
     </Item>
     <Item PartNum="000-AB">
          <Qty>24</Qty>
     </Item>
</HighPriorityItems>

The following snippet shows the output values corresponding to the preceding source document:

<ShippedItems>
     <Item>
          <Quantity>20</Quantity>
     </Item>
     <Item>
          <Quantity>24</Quantity>
     </Item>
</ShippedItems>

Within an xsl:for-each statement, XPath expressions are usually relative to the node selected by the xsl:for-each statement. For instance, in the preceding example Qty is relative to the current Item node /ns0:PurchaseOrder/Items/HighPriorityItems/Item:

  <xsl:for-each select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
    <Item>
      <Quantity>
        <xsl:value-of select="Qty"/>
      </Quantity>
    </Item>
  </xsl:for-each>

Using absolute paths within the xsl:for-each statement can result in unintended results. For example, if were to use absolute path in the preceding example instead of relative path, the code looks as follows:

<ShippedItems>
 <xsl:for-each select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
   <Item>
     <Quantity>
       <xsl:value-of 
              select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item/Qty"/>
     </Quantity>
   </Item>
 </xsl:for-each>
</ShippedItems>

The resultant output document looks like the following:

<ShippedItems>
  <Item>
    <Quantity>20</Quantity>
  </Item>
  <Item>
    <Quantity>20</Quantity>       <!-- repeating incorrect value! -->
  </Item>
</ShippedItems>

The absolute path always selects the first Qty element in the Item node-set and you see a repeating value placed into each output Item element.

The XSLT Map Editor creates relative paths when mapping nodes under a for-each statement, if possible. It is recommended that you create the xsl:for-each statement before mapping the nodes that appear under the for-each. If you map nodes such as Quantity before adding the for-each, the editor shows a warning and attempts to refactor the absolute XPath expressions to relative path expressions when you map the node-set to the for-each.

Note:

• Executing an auto map automatically inserts the xsl:for-each statement, where required.

• Ensure that your design does not include infinite loops. Infinite loops can result in errors similar to the following during deployment and invocation of your application:

  ORAMED-04001:
  . . .
  oracle.tip.mediator.service.BaseActionHandler requestProcess 
  SEVERE: 
  failed reference BPELProcess1.bpelprocess1_client operation =  process
  

40.3.4.7 How to Add xsl:sort for an xsl:for-each Statement

The xsl:sort statement can be added to an xsl:for-each statement to specify a field based on which sorting is performed. The xsl:sort instruction causes xsl:for-each to loop over the defined node-set in a particular order.

40.3.4.7.1 To add an xsl:sort statement using the context menu:

1. Right-click the xsl:for-each node and select Add XSL Instruction -> sort from the context menu that appears.

   The Set Attributes dialog appears.

2. Optionally specify attributes for the xsl:sort statement. Click OK.

   The Set Attributes dialog enables you to set attributes for the xsl:sort statement. Attributes control the way in which the sort is executed. For example, if you select the 'order' Attribute, you can then select ascending or descending for the sort order. Select the attributes desired for the sort.

   Note:

   The default values for attributes are pre-selected in the Set Attributes dialog. These values are used in the absence of any selected attribute.

   For instance, the default for sort order is ascending. You do not have to explicitly select 'order' Attribute to turn on ascending order.

   The xsl:sort statement is added just below the xsl:for-each statement and before any other nodes under the for-each.

3. To set the element to sort with, drag and drop a node from under the source node-set to the xsl:sort node. For instance, to sort on USPrice, drag the USPrice node from under the node-set element Item to the xsl:sort node, as shown in Figure 40-23.

   Figure 40-23 Connecting the Source Node-Set to the xsl:sort Node

   
   Description of "Figure 40-23 Connecting the Source Node-Set to the xsl:sort Node"

40.3.4.7.2 To add an xsl:sort statement using drag and drop:

1. In the Components window, select the XSLT Elements page.

2. Expand the Flow Control section. You can click the plus sign (+) next to Flow Control to expand the section.

3. Drag the sort icon to the top of the element below the for-each node until you can see the green highlighting, as shown in Figure 40-24.

   Figure 40-24 Adding sort to for-each

   
   Description of "Figure 40-24 Adding sort to for-each"

4. Drop the sort icon while the green highlighting is visible. An xsl:sort node is added as the sibling node of the highlighted node. In the example shown in Figure 40-24, the xsl:sort node is added as a sibling of the Item element.

5. To set the element to sort with, drag and drop a node from under the source node-set to the xsl:sort node. For instance, to sort on USPrice, drag the USPrice node from under the node-set element Item to the xsl:sort node, as shown in Figure 40-23.

When viewed in the source view, the xsl:sort statement looks similar to the following:

<xsl:for-each select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
  <xsl:sort select="USPrice"/>
  <Item>
    <Quantity>
      <xsl:value-of select="Qty"/>
    </Quantity>
  </Item>
</xsl:for-each>

40.3.4.8 How to Duplicate XSLT Instructions

Sometimes, you must duplicate XSLT instructions in the target tree. For example, you may create two for-each statements next to one another to loop over two node-sets in the source document, or possibly to loop over the same node-set twice.

Other XSLT instructions, such as xsl:if and xsl:sort, can also be duplicated. This section illustrates creating duplicate instructions using the xsl:for-each statement. The same process applies to other XSLT instructions.

To duplicate an xsl:for-each statement:

1. Right-click the xsl:for-each node in the target tree and select Duplicate from the context menu that appears.

   The node is duplicated together with its children and mappings. Figure 40-25 shows the duplicate nodes.

   Figure 40-25 Duplicating the xsl:for-each Statement

   
   Description of "Figure 40-25 Duplicating the xsl:for-each Statement"
2. Optionally modify the mapping for the xsl:for-each node or change mappings for nodes below the xsl:for-each node.

40.3.4.8.1 Example: Modifying the Mapping by Changing the XPath Expression

In this example, you modify the duplicate xsl:for-each statement to loop over the Item nodes under the LowPriorityItems node in the source document. There are several ways to modify the mappings. The following example discusses one way to modify the mappings.

If you edit the XPath expression associated with a for-each statement, all relative mappings under the for-each are automatically updated. Use the following steps to modify the XPath expression associated with the duplicate for-each statement:

1. To edit the XPath expression, double-click the line connected to the second for-each. This is the blue line in Figure 40-25.

   The Edit XPath dialog appears. The XPath Expression field displays the XPath expression corresponding to the map.

2. Change HighPriorityItems to LowPriorityItems in the XPath Expression. Click OK.

   
   Description of the illustration GUID-6C75D179-4FC8-4DF8-831F-A6E3C58D6FE5-default.gif

   The xsl:for-each statement and all its children now reference the LowPriorityItems/Item node-set.

   
   Description of the illustration GUID-D67E4311-B7B1-412E-8511-AEF6EEE2FB69-default.gif

40.3.4.8.2 Example: Modifying the Mapping by Deleting and Re-Creating It

To modify the mapping for the for-each statement, you can also choose to remove the mapping and re-create it. The following steps illustrate the process to modify the mappings for the duplicate for-each statement:

1. Right-click the duplicate xsl:for-each node and select Delete Mapping from the context menu that appears.

   The Refactor XPaths dialog appears asking if you want to refactor the XPath expressions under the for-each statement.

2. Click No to refactoring. This keeps the relative paths, as you plan to apply these relative paths to a different loop. After you click No, the lines underneath the for-each statement become temporarily disconnected from the source tree.

   
   Description of the illustration GUID-36651237-B774-477D-B238-F4D04BA0AA81-default.gif

   In the preceding figure, the relative XPath expression assigned to the Quantity field is Qty. Without the XPath expression on the for-each statement, the relative path has no Item node to be relative to, and consequently, no reference is found in the source tree.

   Note:

   In general, XPath expressions that cannot be resolved to nodes in the source tree are represented in the center panel. This can sometimes indicate an issue, as in the preceding case. There is a relative path that cannot be resolved because of a missing for-each expression above it.

   An XPath expression can also be represented in the center pane if the expression is too complex to determine a source reference node at design time.

3. Drag and drop a line from the LowPriorityItems/Item node in the source tree to the duplicate xsl:for-each statement.

   The mapping to the Quantity field automatically reconnects to the Qty field under the LowPriorityItems/Item node, as shown in the following figure.

   
   Description of the illustration GUID-0D13121A-8EA1-4717-A32C-783F10D8F37F-default.gif

40.3.5 How to Duplicate an Element

In order to duplicate a target node in Map view, the node must have been defined as a repeating node in the target schema. For certain cases, you can create repeating nodes using for-each loops, as discussed in the preceding section. In other cases, you may need to create several independent instances of a node and map data to them through different areas of the source document.

To duplicate a repeating target node:

1. If the target node text is grayed, and in italics, right-click the node and select Create Node in XSLT from the context menu that appears.

   Figure 40-26 Creating Node in XSLT

   
   Description of "Figure 40-26 Creating Node in XSLT "
2. Right-click the node again and select Duplicate from the context menu that appears. The node is duplicated.

   Figure 40-27 Duplicate Contact Nodes

   
   Description of "Figure 40-27 Duplicate Contact Nodes"
3. Map the appropriate fields from the source document to the two duplicate elements.

   In the following figure, the duplicate Contact nodes in the target tree are mapped to different areas of the source document. The first Contact node is mapped to the ShipTo data. The second Contact node is mapped to the BillTo data.

   
   Description of the illustration GUID-430EDCFD-9F52-4659-93B8-26F359130AA8-default.gif

40.3.6 How to Delete an Element or Attribute

To delete an element or attribute from the current XSLT Map, the element or attribute must first exist in the XSLT. Nodes in the target tree that are not grayed, and not in italics, are nodes that exist in the XSLT. Nodes that are grayed, and in italics, are not part of the XSLT. Such grayed nodes represent candidate elements and attributes from the target schema, and cannot be deleted from the display.

To delete a target node that exists in the XSLT, do one of the following:

• Click the target node to select it. Press the Delete key.

• Right-click the target node and select Delete from the context menu that appears.

The node is removed from the XSLT and any mapping to the node is also removed. The deleted node is not removed from the display. The deleted node becomes gray and italicized indicating that it is now just a possible target node from the target schema, and is no longer part of the XSLT. However, if the deleted node was a duplicate node, or was in a position non-compliant with the target schema, then the node is removed from the display.

The following figure shows two comment nodes that are part of the XSLT map.

Description of the illustration GUID-822ED4F9-4D66-4D81-9C8A-6F15D52A8C9C-default.gif

If you right-click the second Comment node and select Delete from the context menu, the duplicate node is removed from the XSLT and the display, as shown in the figure below.

Description of the illustration GUID-32A1D26B-698D-46A1-99C7-0635B02A3064-default.gif

Next, you right-click and remove the remaining Comment node. The node is not removed from the display, but is removed from the XSLT and its appearance changes to gray and italicized, as shown in the following figure.

Description of the illustration GUID-B6D3D94D-EF97-4732-9E6F-D56F116C8077-default.gif

40.3.7 How to Remove Mappings from an Element or Attribute

To remove the mapping to any target node, right-click the node in the target tree and select Delete Mapping from the context menu that appears. Alternatively, you can select the line representing the mapping, and press the Delete key.

When you remove a mapping in Map View, the node that was mapped to is not removed from the XSLT. To remove the node, right-click and select Delete from the context menu that appears. If only the mappings are removed and the node is not, the XSLT generates an empty node when executed.

40.4 Editing an XSLT Map in XSLT View

This section discusses basic editing using the XSLT pane in XSLT View. The following list includes the major differences between editing in XSLT View and editing in Map View:

• XSLT View does not provide a merged view of the XSLT nodes and the target schema. The right target pane is divided into two panes. The top pane is called the XSLT pane and the lower pane is called the target pane. If no target schema is defined, then the lower pane is not shown.

• In order to map to target nodes, these nodes must be explicitly added to the XSLT pane before they can be mapped. The editor provides several ways to do this. These are discussed in the subsequent sections.

• The complete range of XSLT 1.0 instructions is available in XSLT View. These instructions can be added anywhere within the XSLT panel, so long as their position is consistent with the XSLT specification.

• A number of advanced features are available in XSLT View, such as template rules (matched templates), named templates, import/include, and so on. These advanced features are discussed later in this chapter.

40.4.1 How to Add a Target Element or Attribute Before Mapping

Before mapping to target elements and attributes, the element or attribute must be explicitly added to the XSLT pane. This section contains the following topics:

• How to Add Elements and Attributes from the Target Schema

• How to Add Literal Elements and Attributes When No Target Schema Is Present

• How to Create an Empty Node in the Output Document

40.4.1.1 How to Add Elements and Attributes from the Target Schema

If the target schema is present, you can add elements and attributes from the target tree to the XSLT pane.

You can either use the context menu for an XSLT element or attribute to add a related element/attribute, or drag and drop the desired element/attribute from the target tree to the XSLT tree.

If elements are placed in positions that are inconsistent with the target schema, or if the editor cannot yet determine if the element is valid at the location due to an incomplete XSLT map, then a question mark is shown over the element's icon. The following figure shows an XSLT tree where the Item element is marked with a question mark.

Description of the illustration GUID-9978714C-0AA8-48BB-9075-CCC62FAC0377-default.gif

40.4.1.1.1 To add elements and attributes when target schema is present:

1. Right-click the element, in the XSLT pane, that is to contain the child element(s) or attribute(s). A context menu appears.

   Note:

   This action can also be executed from Map View if the selected node exists in the XSLT.

   In Map View, you can also add an empty XSLT node by choosing Create Node in XSLT. See How to Create an Empty Node in the Output Document for more details.

2. Select Add Children From Schema. A submenu appears with choices that are consistent with the target schema. Figure 40-28 shows the Add Children From Schema submenu.

   Figure 40-28 Selecting Child Elements/Attributes to Add

   
   Description of "Figure 40-28 Selecting Child Elements/Attributes to Add"

3. Select the element name or attribute name to add. To add all child elements or attributes, select All Elements or All Attributes. Select All Required to add all required child elements or attributes.

40.4.1.1.2 To drag and drop elements and attributes from the target schema tree:

• To insert an element as a child of an existing element:

  Drag the target element, or a selected range of elements, from the target pane to the left of the desired element in the XSLT tree. A green highlight appears to indicate that the element is being inserted as a child. Upon drop, the child is appended to the list of children.

  If the green highlight does not appear at a particular position, then it means it is invalid to insert the element at that position.

  
  Description of the illustration GUID-DCC7A7B3-7904-48FC-97F5-85EDB804B7CE-default.gif

• To insert an element as a sibling after an existing element:

  Drag the target element, or a selected range of elements, from the target pane to the bottom of the existing element in the XSLT tree. A green highlight appears to indicate that the element is being inserted as a sibling. Upon drop, the sibling is appended after the existing element.

  
  Description of the illustration GUID-9AAC301C-42A6-45E6-9B53-7FA343CDA266-default.gif

• To insert an element as a sibling before an existing element:

  Drag the target element, or a selected range of elements, from the target pane to the top of the existing element in the XSLT tree. A green highlight appears to indicate that the element is being inserted as a sibling. Upon drop, the sibling is appended before the existing element.

  
  Description of the illustration GUID-A8E5D444-6227-4E82-91CF-3EA86DA0A11B-default.gif

• To insert an element as a parent of an existing element:

  Drag the target element, or a selected range of elements, from the target pane to the right of the existing element in the XSLT tree. A green highlight appears to indicate that the element is being inserted as a parent. Upon drop, the element is inserted as the parent of the existing element.

  
  Description of the illustration GUID-07849B4D-5760-4A61-B73A-8476526D752E-default.gif

40.4.1.2 How to Add Literal Elements and Attributes When No Target Schema Is Present

This section applies to both XSLT and Map views.

40.4.1.2.1 To add a literal element when there is no target schema:

1. Right-click an element in the XSLT pane. The context menu for the element appears.

2. Select the relative position of the new literal element relative to the existing element. You can create the literal element as the child, sibling, or parent of the existing element. Figure 40-29 shows the available options (Append Child, Insert Parent, Insert Sibling Before, Insert Sibling After).

   Figure 40-29 Adding a Literal Element to the XSLT Pane

   
   Description of "Figure 40-29 Adding a Literal Element to the XSLT Pane"

3. Select Literal Element from the submenu. The Define Element dialog appears.

4. Under Local Name, enter a name for the literal element. You can optionally specify a namespace for the element.

5. Click OK to close the Define Element dialog.

40.4.1.2.2 To add a literal attribute when there is no target schema:

1. Right-click an existing literal element in the XSLT pane. The context menu for the literal element appears.

2. Select Append Child > Literal Attribute. The Define Element dialog appears.

3. Under Local Name, enter a name for the literal attribute. You can optionally specify a namespace for the attribute.

4. Click OK to close the Define Attribute dialog.

40.4.1.3 How to Create an Empty Node in the Output Document

When you use the methods discussed under the preceding sections (How to Add Elements and Attributes from the Target Schema and How to Add Literal Elements and Attributes When No Target Schema Is Present) to add nodes to the XSLT pane, these nodes are created as empty nodes unless you map them to source nodes. Also, when you add a complex node to the XSLT pane, all required nodes under the complex node are created automatically.

You can also set the XSL Map Initialization Options in the XSL Maps: XSL Editor preferences page to generate empty nodes when a map is created. See How to Set the XSL Editor Preferences for more information.

40.4.2 How to Perform a Value Copy by Linking Nodes

To copy the value of an attribute or leaf-element in the source to an attribute or leaf-element in the XSLT pane, drag a line from the source node to the XSLT node. A green highlighted line appears as you are dragging and dropping. When you complete the drop, a line is drawn connecting the source and target nodes.

Figure 40-30 shows the XSLT view where the PurchaseOrder/ID source element is mapped to the Invoice/ID XSLT element. A line connects the source and XSLT node.

Figure 40-30 Performing a Value Copy

Description of "Figure 40-30 Performing a Value Copy"

40.4.3 How to Insert an xsl:valueof Statement

When you map a source element to an XSLT element, as described in the preceding section, an implicit xsl:valueof statement is created in the XSLT.

In XSLT View, you can explicitly create multiple xsl:valueof elements for an XSLT element. The resultant value of the XSLT element is the concatenation of the individual xsl:valueof values.

To create an xsl:valueof element for an XSLT element:

1. Right-click the literal element in the XSLT pane. The context menu appears.
2. Select Append Child > XSL > value-of from the context menu. The Set Attributes dialog box appears.
3. Optionally select 'disable output escaping' Attribute. Click OK.

   The xsl:value-of element is inserted.

4. Map the xsl:value-of element to a source element just as you map a literal element. This is described in the preceding section.

If an xsl:value-of element is added to a literal element that has no mapping, the xsl:value-of statement appears under the literal element until it is mapped. After you map the xsl:value-of element, the editor hides the xsl:value-of statement under the literal element and shows only the line indicating the mapping.

If you add multiple xsl:value-of statements to the literal element, then all xsl:value-of statements are explicitly shown under the literal element, and mapping lines can be separately drawn to each xsl:value-of element.

40.4.4 How to Set a Literal Text Value for an XSLT Node

To set a literal text value for an XSLT node:

1. Right-click the node in the XSLT pane. Select Edit Text Value from the context menu that appears.

   The Set Text dialog appears.

2. Enter the text value to be assigned to the node. Do not enclose the text in quotation marks.
3. Click OK.

   A yellow T icon appears next to the node indicating that a text value has been set for the item. If you move the mouse cursor over the node, the corresponding text appears.

40.4.5 How to Set a Literal Text Value Using an xsl:text Instruction

To set the value for a literal element using the xsl:text instruction:

1. Right-click the literal element in the XSLT pane. The context menu appears.
2. Select Append Child > XSL > text from the context menu. The Set Attributes dialog box appears.
3. Optionally select 'disable output escaping' Attribute. Click OK.

   The xsl:text element is inserted.

4. Right-click the newly inserted xsl:text element and select Edit Text Value from the context menu that appears.

   The Set Text dialog box appears.

5. Enter the text value to be assigned Do not enclose the text in quotation marks.
6. Click OK.

   A yellow T icon appears next to the xsl:text node indicating that a text value has been set for the element. If you move the mouse cursor over the node, the corresponding text appears.

7. To change the text value at any time, right-click the xsl:text element again and select Edit Text Value from the context menu that appears.

40.4.6 How to Add XSLT Statements

This procedure applies to XSLT View only. XSLT statements can be added using the Components window or context menu.

40.4.6.1 To add an XSLT element using the context menu:

1. Right-click an element in the XSLT pane. The context menu for the element appears.

2. Select the relative position of the new element relative to the existing element. You can create the literal element as the child, sibling, or parent of the existing element. The available options are Append Child, Insert Parent, Insert Sibling Before, and Insert Sibling After.

3. Select XSL from the submenu. A list of available XSLT elements valid for the position is displayed. Figure 40-31 shows a sample XSL selection.

   Figure 40-31 Inserting an XSLT Element

   
   Description of "Figure 40-31 Inserting an XSLT Element"

4. Select the desired XSLT element.

   Depending on the element selected, a dialog may prompt you for attribute values. If so, then enter the attribute values, and click OK.

5. The XSLT element gets added to the tree.

   The attributes of the added element are not explicitly shown in the XSLT tree. Hover your mouse over the element to see its attributes in the tooltip text. Alternatively, select the XSLT element to view and edit the element properties in the Properties window.

40.4.6.2 To add XSLT elements from the Components window:

1. Make sure that the Components window is visible. The default location is the top right hand corner of Oracle JDeveloper.

2. If the Components window is not visible, select Components from the Window menu.

3. Select the XSLT Elements page.

4. Select the desired section under XSLT Elements. Drag the desired XSLT element to the XSLT pane.

   • To insert the XSLT element as a child of an existing element:

     Drag the XSLT element from the Components window to the left of the existing element in the XSLT tree. A green highlight appears to indicate that the XSLT element is being inserted as a child. Upon drop, the XSLT element is appended to the end of any existing children.

     If the green highlight does not appear at a particular position, then it means it is invalid to insert the element at that position.

     
     Description of the illustration GUID-DCC7A7B3-7904-48FC-97F5-85EDB804B7CE-default.gif

   • To insert the XSLT element as a sibling after an existing element:

     Drag the XSLT element from the Components window to the bottom of the existing element in the XSLT tree. A green highlight appears to indicate that the XSLT element is being inserted as a sibling. Upon drop, the XSLT element is appended after the existing element.

     
     Description of the illustration GUID-9AAC301C-42A6-45E6-9B53-7FA343CDA266-default.gif

   • To insert the XSLT element as a sibling before an existing element:

     Drag the XSLT element from the Components window to the top of the existing element in the XSLT tree. A green highlight appears to indicate that the XSLT element is being inserted as a sibling. Upon drop, the XSLT element is appended before the existing element.

     
     Description of the illustration GUID-A8E5D444-6227-4E82-91CF-3EA86DA0A11B-default.gif

   • To insert the XSLT element as a parent of an existing element:

     Drag the XSLT element from the Components window to the right of the existing element in the XSLT tree. A green highlight appears to indicate that the XSLT element is being inserted as a parent. Upon drop, the XSLT element is added as the parent of the existing element.

     
     Description of the illustration GUID-07849B4D-5760-4A61-B73A-8476526D752E-default.gif

   Depending on the XSLT element selected, a dialog may prompt you for attribute values. If so, then enter the attribute values, and click OK.

5. The XSLT element gets added to the tree.

   The attributes of the added element are not explicitly shown in the XSLT tree. Hover your mouse over the element to see its attributes in the tooltip text. Alternatively, select the XSLT element to view and edit the element properties in the Properties window.

40.4.7 How to Set the Value of an XSLT Expression Attribute

Many XSLT instructions contain special attributes that are interpreted as XPath expressions. These expression attributes are generally named select or test. For example, the xsl:for-each element contains a select attribute and the xsl:if element contains the test attribute.

Such attributes can be defined by XPath expressions. You can set the values for these attributes using drag and drop to the XSLT element in the XSLT pane (in XSLT View) or target pane (in Map View).

To set the value of an XSLT expression attribute using drag and drop from the source tree, drag a line from the desired node in the source tree to the desired XSLT element in the XSLT pane. A line appears connecting the source tree node to the XSLT element.

The appropriate expression attribute is inserted for the XSLT instruction in the source view. For example:

<xsl:if test="/ns0:PurchaseOrder/BillTo/Address/@country">

The preceding example code is formed by dragging the country attribute in the source schema to the xsl:if statement in the XSLT tree. The code causes the if condition to test for the presence of the country attribute in the source schema.

40.4.8 How to Duplicate an Element

To duplicate a literal element in the XSLT pane that is defined as a repeating node in the target schema, use the instructions under How to Duplicate an Element. The instructions are same as those for the Map View.

If no target schema is defined, you can duplicate any node in XSLT View, except the root node.

If a node needs to be duplicated, but the node is not defined as a repeating node in the target schema, you can create a duplicate node by explicitly creating a literal element as follows:

To duplicate a literal element that is not defined as a repeating node in the target schema:

1. In the XSLT pane, right-click the element to be duplicated. The context menu appears.
2. Select Insert Sibling After -> Literal Element from the context menu. The Define Element dialog appears.
3. Enter the element name and namespace of the node to be duplicated. Click OK.

40.4.9 How to Delete an Element or Attribute

This feature is available in both the XSLT and Map views. When using Map View, the action is to be performed in the target pane.

To delete a target node that exists in the XSLT, do one of the following:

• Right-click the node in the XSLT pane. Select Delete from the context menu that appears.

• Click the node in the XSLT pane to select it. Press the Delete key.

The node is removed from the XSLT pane together with any mappings to the node.

40.4.10 How to Move an Element

You can move an element by dragging it from one position and dropping it to another position in the XSLT pane. The element can be moved to become a sibling, parent, or child of another element. You cannot move an element in Map View.

In Figure 40-32, the AccountNumber element is at an incorrect location in the XSLT pane. To make it consistent with the target schema, you must move the AccountNumber element under the BilledToAccount element.

Figure 40-32 AccountNumber Element

Description of "Figure 40-32 AccountNumber Element "

Drag the AccountNumber node in the XSLT pane to the left of the BilledToAccount node until the green highlight appears, as shown in Figure 40-33. The green highlight indicates that the AccountNumber element is dropped as a child of BilledToAccount.

Figure 40-33 Dragging the AccountNumber Node

Description of "Figure 40-33 Dragging the AccountNumber Node"

Drop the element while the green highlight is visible. The AccountNumber node is repositioned under the BilledToAccount node, as shown in Figure 40-34.

Figure 40-34 Repositioned AccountNumber Node

Description of "Figure 40-34 Repositioned AccountNumber Node"

40.4.11 How to Remove Mappings from an Element or Attribute

To remove the mapping to any XSLT node, right-click the node and select Delete Mapping from the context menu. Alternatively, you can select the line representing the mapping, and press the Delete key. You can use the preceding methods in both the Map and XSLT views.

40.5 Using XPath Expressions

How to Perform a Value Copy by Linking Nodes and How to Perform a Value Copy by Linking Nodes discussed how to use the drag and drop action to create a mapping between a source and target element or attribute. The drag and drop action creates an XPath expression in the XSLT that references specific nodes in the source document.

For example, the following XSLT code is generated by mapping a source element to a target element:

<ID>
 <xsl:value-of select="/ns0:PurchaseOrder/ID"/>
</ID>

The preceding code contains an xsl:value-of statement. The select attribute for this statement contains an XPath expression (/ns0:PurchaseOrder/ID)that references the source node being mapped.

This XPath expression represents a location path expression. XPath expressions can also be complex and include XPath functions and operators.

For example, the following code concatenates the value of the source element /PurchaseOrder/ID to the value of the attribute, /PurchaseOrder/@PONumber. It then assigns the result to the target element, <ID>.

<ID>
 <xsl:value-of select="concat(/ns0:PurchaseOrder/ID,/ns0:PurchaseOrder/@PONumber )"/>
</ID>

In the preceding code, the value in the select attribute is the XPath expression. The XPath expression uses the concat function to concatenate two source node values.

The XSLT Map Editor provides a number of ways to enter more complex XPath expressions than those that are created by simple drag and drop actions. The following methods for creating XPath expressions are available in both Map and XSLT View.

40.5.1 How to Modify an Existing Source to Target Mapping

You can modify the XPath expression for a mapping created from a drag and drop action between a source and target node.

40.5.1.1 To edit an XPath expression using the Edit XPath dialog

1. Double-click the line representing the source to target mapping. The Edit XPath dialog appears.

   
   Description of the illustration GUID-05E5F62B-D0F0-447A-A524-CA7B6E8E7BD4-default.gif

2. Edit the XPath Expression, as needed.

   For example, if you want the Description field to contain the first Comment that occurs in the source, you add a predicate to the expression with the index of the first Comment.

   
   Description of the illustration GUID-4B39D3D1-2B21-4B09-B70E-7A8B060D60EB-default.gif

   Click Help if you need more information on editing the XPath expression.

3. Click OK in the Edit XPath dialog.

40.5.1.2 To edit an existing XPath expression using the Properties window

1. If the Properties window is not visible, select Window > Properties from the Oracle JDeveloper menu bar.

   The default location of the Properties window is below the XSLT Map Editor.

2. Click to select the line representing the source to target mapping. The Properties window shows the XPath expression corresponding to the selected map line.

   
   Description of the illustration GUID-D90B91DC-8E0B-4964-9282-25B20D738120-default.gif

3. Edit the XPath Expression, as needed.

   For example, if you want the Description field to contain the first Comment that occurs in the source, you add a predicate to the expression with the index of the first Comment.

   
   Description of the illustration GUID-10D9DF2B-6319-43E5-B451-8D8279A9D4EA-default.gif

   Click the Help icon in the Properties window, if you need more information on editing the XPath expression.

4. To update the XSLT with the changes, click the Apply Changes icon in the upper left corner of the Properties window. Alternatively, click anywhere in the XSLT Map Editor.

40.5.1.3 How to Add an XPath Function to an Existing XPath Expression

You can drag and drop a function onto an existing source to target mapping. When you drop a function on a map, the existing location path expression is used to populate the first parameter of the function that is dropped.

In the following steps, you change the expression you edited in the preceding section (How to Modify an Existing Source to Target Mapping). You use the concat function to concatenate the first Comment in the source with the Description in the source.

To add an XPath function to an existing XPath expression

1. If the Components window is not visible, select Window > Components from the Oracle JDeveloper menu bar.
2. In the Components window, select General XPath. Expand the String Functions section by clicking the plus sign (+) next to it.
3. Drag the concat function icon from the String Functions section to the line representing the existing map that you want to modify. The line turns green, indicating that you can drop the function.
   
   Description of the illustration GUID-33E3C42B-0324-4473-8D32-A01F0B5F80EA-default.gif
4. Drop the concat function on the line. The function is inserted into the map, and the first parameter of the concat function is set to the value of the existing XPath expression.
   
   Description of the illustration GUID-61674E37-5A37-44A3-AB9D-1AF2BC6AE338-default.gif

   Note:

   If a function does not get added to the map, the function may not have any parameters. For example, if you drag and drop the xp20:current-date function onto the existing line, it has no effect because the xp20:current-date function takes no parameters.

40.5.2 How to Modify an Existing Function XPath Expression in the Canvas Pane

XPath functions are shown in the canvas panel and can be edited in several ways. Continuing our example from the previous section (How to Add an XPath Function to an Existing XPath Expression), you set the value of the second parameter of the concat function in several ways.

40.5.2.1 To set a function parameter using drag and drop:

1. Drag a line from the Description element in the source tree to the left side of the concat function icon in the canvas pane. A pop-up panel appears with connectors for each possible parameter in the function.

   
   Description of the illustration GUID-31B5B8D6-7E99-4C61-9C35-DC1E8FB961C5-default.gif

2. Drop the line on the desired connector. In the preceding figure, you drop the line on the second connector, which represents the second required parameter. You can also choose to drop the line on the third optional parameter, and fill in the second parameter value later.

   The parameter is added to the function. The warning icon disappears after all required parameters have been added.

   
   Description of the illustration GUID-3D1D7E69-3E09-4A81-A353-269FF82B2BB6-default.gif

40.5.2.2 To delete a function parameter:

To delete a function parameter, select the line representing the input to the function parameter and press the Delete key. Alternatively, you can right-click the line and select Delete from the context menu.

Description of the illustration GUID-9A7DB236-3036-42E3-9163-607511D0636C-default.gif

40.5.2.3 How to Edit a Function as a Full XPath Expression

You can edit an XPath function as a textual XPath Expression using the XPath Edit dialog or the XPath Edit panel in the Properties Window.

40.5.2.3.1 To edit a function as a textual XPath expression using the XPath Edit dialog:

1. Double-click the expression folder in the canvas pane, in the area bordering the function icon. The Edit XPath dialog appears.

   
   Description of the illustration GUID-4A97599A-EE43-44DC-968A-34E6080C4023-default.gif

   If you double-click the center icon instead, it brings up the Edit Function dialog.

2. Edit the XPath Expression, as desired. To add the XPath location path for the Description node, for example, place the cursor after the first parameter. Press Ctrl + Space and double-click /ns0:PurchaseOrder to select it.

   
   Description of the illustration GUID-4D70BD91-E358-4806-BD51-83E618440161-default.gif

   /ns0:PurchaseOrder is inserted in the expression and the drop-down menu is populated with the possible children of the /ns0:PurchaseOrder node.

   
   Description of the illustration GUID-B66BA1A8-7E80-471A-9B97-367FE3DD0DAB-default.gif

3. Double-click the Description entry to select it. You can also put the mouse cursor on an entry, and press the Enter key to select it.

4. Click OK in the Edit XPath dialog.

40.5.2.3.2 To edit a function as a textual XPath expression using the Properties Window:

1. If the Properties window is not visible, select Window > Properties from the Oracle JDeveloper menu bar.

   The default location of the Properties window is below the XSLT Map Editor.

2. Click the expression folder in the canvas pane, in the area bordering the function icon. The full XPath Expression for the function appears in the right pane of the Properties window.

3. Edit the XPath Expression, as desired. You can also refer to Steps 2 to 3 in the preceding procedure.

4. To update the XSLT with the changes, click the Apply Changes icon in the upper left corner of the Properties window. Alternatively, click anywhere in the XSLT Map Editor.

40.5.2.4 How to Edit Individual Function Parameters

The XSLT Map Editor can parse a function into its corresponding parameters, so that the XPath for each parameter can be edited in a separate XPath Expression field.

40.5.2.4.1 To edit the parameters of a function using the Edit Function dialog:

1. Double-click the function icon in the canvas pane. The Edit Function dialog appears.

   
   Description of the illustration GUID-ABA7CC8D-1FAF-4399-82CA-C8A70C117856-default.gif

   Make sure you double-click the center function icon. Double-clicking the area bordering the function icon brings up the Edit XPath dialog.

2. Edit the function parameters individually, as desired. Optionally click Help for more information about editing the parameters.

3. Click the Add icon, represented by the green plus sign (+), to optionally add a new parameter.

4. Click OK after you finish editing the parameters.

40.5.2.4.2 To edit the parameters of a function using the Properties window:

1. If the Properties window is not visible, select Window > Properties from the Oracle JDeveloper menu bar.

   The default location of the Properties window is below the XSLT Map Editor.

2. Click the center area of the function icon in the canvas pane. The function parameters appear in the right pane of the Properties window.

3. Edit the function parameters, as desired. Optionally click the Help icon for more information about editing the parameters.

4. Click the Add icon, represented by the green plus sign (+), to optionally add a new parameter.

5. To update the XSLT with the changes, click the Apply Changes icon in the upper left corner of the Properties window. Alternatively, click anywhere in the XSLT Map Editor.

40.5.3 How to Create a New Function in the Canvas Pane

There are several ways to create a new function in the XSLT canvas pane. These are described in the sections that follow.

40.5.3.1 To create an XPath Function using the canvas context menu

1. Right-click a blank area in the center canvas pane. Select Create XPath from the context menu that appears.

2. Select the desired function from the Create XPath submenu. For example, select the current-date function from the Date Functions category.

   
   Description of the illustration GUID-CC19CF66-7CC2-4D3B-BEC8-54B636250115-default.gif

   An Information dialog may appear, prompting you to connect the function to a target node. Click OK.

   The function icon appears on the canvas pane.

3. Map the function to a target node by dragging a line from the function to the target node.

   
   Description of the illustration GUID-34D05DBA-DB73-48A1-A5E5-A2E282C7CB7B-default.gif

4. If the function requires parameters, edit the parameters using one of the methods discussed in How to Modify an Existing Function XPath Expression in the Canvas Pane.

40.5.3.2 To create an XPath function using the Components window

1. If the Components window is not visible, select Window > Components from the Oracle JDeveloper menu bar.

2. In the Components window, select General XPath or Advanced XPath. Select a category of functions, for example, String Functions.

3. Drag the desired function from the Components window to the center canvas pane of the XSLT Map Editor.

4. Map the function to a target node by dragging a line from the function to the target node.

5. If the function requires parameters, edit the parameters using one of the methods discussed in How to Modify an Existing Function XPath Expression in the Canvas Pane.

40.5.3.3 To create an XPath function using the target tree context menu

1. Right-click the target tree node (Map View) or the XSLT tree node (XSLT View) to which the XPath function needs to be assigned. The context menu appears.

2. Select Create XPath. Select the desired XPath function from the submenu that appears.

   
   Description of the illustration GUID-BEBC53A4-66D3-43FF-96B4-3A8600045819-default.gif

   The function is created in the canvas pane and linked to the target/XSLT node for which it was created.

3. If the function requires parameters, edit the parameters using one of the methods discussed in How to Modify an Existing Function XPath Expression in the Canvas Pane.

40.5.3.4 To create an XPath function by dragging it to the target tree

1. If the Components window is not visible, select Window > Components from the Oracle JDeveloper menu bar.

2. In the Components window, select General XPath or Advanced XPath. Select a category of functions, for example, String Functions.

3. Drag the desired function from the Components window to the target tree node (Map View), or XSLT tree node (XSLT View), to which the function is to be assigned. A green highlight appears to the left of the target/XSLT tree node.

   
   Description of the illustration GUID-F9A2C2F3-0D66-41BD-8D25-81C00F5592D6-default.gif

4. Drop the function while the green highlight is visible.

   The function is created in the canvas pane and linked to the target/XSLT node where the function was dropped.

5. If the function requires parameters, edit the parameters using one of the methods discussed in How to Modify an Existing Function XPath Expression in the Canvas Pane.

40.5.4 How to Chain Functions Together

To chain one function to another:

Complex expressions can be built by chaining functions (that is, mapping the output of one function to the input of another). For example, to remove all leading and trailing spaces from the output of the concat function, perform the following steps:

1. Drag the left-trim and right-trim functions into the border area of the concat function.
2. Chain them as shown in Figure 40-35 by dragging lines from the output side of one function to the input side of the next function.

Chaining can also be performed by dragging and dropping a function onto a connecting link.

Figure 40-35 Chaining Functions

Description of "Figure 40-35 Chaining Functions"

40.5.5 How to Remove an XPath Expression

To remove an XPath Expression:

1. Select the XPath expression/function icon in the Canvas pane.
2. Right-click the icon and select Delete from the context menu.

40.5.6 How to Import User-Defined Functions

You can create and import a user-defined Java function if you have complex functionality that cannot be performed in XSLT or with XPath expressions.

Follow these steps to create and use your own functions. External, user-defined functions can be necessary when logic is too complex to perform within the XSL map.

To import user-defined functions:

1. Code and build your functions.

   The XSLT Map Editor extension functions are coded differently than the Oracle BPEL Process Manager extension functions. Two examples are provided in the SampleExtensionFunctions.java file of the mapper-107-extension-functions sample scenario. To download these and other samples, see the Oracle SOA Suite samples.

   Each function must be declared as a static function. Input parameters and the returned value must be declared as one of the following types:

   • java.lang.String

   • int

   • float

   • double

   • boolean

   • oracle.xml.parser.v2.XMLNodeList

   • oracle.xml.parser.v2.XMLDocumentFragment

   The text for these functions is as follows:

   // SampleExtensionFunctions.java
   package oracle.sample;
   /*
   This is a sample XSLT Map Editor User Defined Extension Functions implementation
   class.
   */
   public class SampleExtensionFunctions
   {
      public static Double toKilograms(Double lb)
      {
         return new Double(lb.doubleValue()*0.45359237);
      }
      public static String replaceChar(String inputString, String oldChar, String
         newChar )
      {
         return inputString.replace(oldChar.charAt(0), newChar.charAt(0));
      }
   }
   

2. Create an XML extension function configuration file. This file defines the functions and their parameters.

   This file must have the name ext-mapper-xpath-functions-config.xml. See Creating User-Defined XPath Extension Functions for more information on the format of this file. The following syntax represents the functions toKilograms and replaceChar as they are coded in Step 1.

   <?xml version="1.0" encoding="UTF-8"?>
   <soa-xpath-functions version="11.1.1"
    xmlns="http://xmlns.oracle.com/soa/config/xpath" xmlns:sample=
   "http://www.oracle.com/XSL/Transform/java/oracle.sample.SampleExtensionFunctions"
    >
         <function name="sample:toKilograms">
                <className>oracle.sample.SampleExtensionFunctions</className>
                <return type="number"/>
                <params>
                       <param name="pounds" type="number"/>
                </params>
                <desc>Converts a value in pounds to kilograms</desc>
         </function>
         <function name="sample:replaceChar">
                <className>oracle.sample.SampleExtensionFunctions</className>
                <return type="string"/>
                <params>
                       <param name="inputString" type="string"/>
                       <param name="oldChar" type="string"/>
                       <param name="newChar" type="string"/>
                </params>
                <desc>Returns a new string resulting from replacing all occurrences
                      of oldChar in this string with newChar</desc>
         </function>
   </soa-xpath-functions>
   

   Some additional rules apply to the definitions of XSLT extension functions:

   • The functions need a namespace prefix and a namespace. In this sample, they are sample and http://www.oracle.com/XSL/Transform/java/oracle.sample.Sam pleExtensionFunctions.

   • The function namespace must start with http://www.oracle.com/XSL/Transform/java/ for extension functions to work with the Oracle XSLT processor.

   • The last portion of the namespace, in this sample oracle.sample.SampleExtensionFunctions, must be the fully qualified name of the Java class that implements the extension functions.

   • The types and their equivalent Java types shown in Table 40-1 can be used for parameter and return values:

     ---

     Table 40-1 Types and Equivalent Java Types

     XML Configuration File Type Name	Java Type
     string	java.lang.String
     boolean	boolean
     number	int, float, double
     node-set	oracle.xml.parser.v2.XMLNodeList
     tree	oracle.xml.parser.v2.XMLDocumentFragment

     ---

3. Create a JAR file containing both the XML configuration file and the compiled classes. The configuration file must be contained in the META-INF directory for the JAR file. For the example in this section, the directory structure is as follows with the oracle and META-INF directories added to a JAR file:

   • oracle

     • sample (contains the class file)

   • META-INF

     • ext-mapper-xpath-functions-config.xml

   The JAR file must then be registered with Oracle JDeveloper.

4. Go to Tools > Preferences > SOA.
5. Click the Add button and navigate to and select your JAR file.
6. Restart Oracle JDeveloper.

   New functions appear in the Components window under the User Defined page in the User Defined Extension Functions group.

7. To make the functions available in the runtime environment, see How to Deploy User-Defined Functions to Runtime for details.

40.6 Using Auto Map to Map Complex Nodes

When you map a non-leaf source element to a non-leaf target element, the Auto Map feature assists you by automatically matching the child source elements to their corresponding target elements. Auto Map looks at the element names, types, and paths to come up with the correct mappings. Auto map can also insert xsl:if statements for optional nodes, depending on your preferences.

The Auto Map feature is available only when a target schema is used. You can use Auto Map in both Map View and XSLT View.

40.6.1 How to Set Auto Map Preferences

You can specify the behavior of the Auto Map feature using the Preferences dialog. Select Preferences from the Tool menu. In the navigation tree on the left, select Auto Map under XSL Maps. Figure 40-36 shows the default settings for the Auto Map preferences.

Figure 40-36 Auto Map Preferences

Description of "Figure 40-36 Auto Map Preferences"

The following list describes the various Auto Map Preference settings that you can configure:

• Confirm Auto Map Results: If you select this option, Auto Map displays a list of matching source and target elements prior to automatically mapping these elements. You can choose the matches that you'd like to be applied.

• Prompt for Preferences before Auto Map: If you select this option, the Auto Map Preferences dialog appears every time you try to map two complex nodes.

• Mode: Determines whether the Auto Map executes in Basic or Advanced mode. The mode selection determines the rest of the options that appear in this dialog.

The following are the rest of the options available when Basic Mode is selected:

• Match Elements with Similar Names: Elements with similar names are matched.

• Match Elements with Exact Names: Elements with exactly same names are matched.

• Match Elements with Exact Types: Only elements with exactly same data types are matched.

• Match Elements Considering Their Ancestor Names: Element path is considered along with the element name when matching.

• Insert xsl:if: Determines if xsl:if statements are automatically inserted. The following settings are used:

  • Never: xsl:if statements are not inserted automatically.

  • Check source node exists: An xsl:if statement is inserted to check for the existence of the source node before the node is created in the output.

  • Check source node is not empty: An xsl:if statement is inserted to check that the source node is not empty before creating the node in the output.

The following are the rest of the options available when Advanced Mode is selected:

• Ancestor Weight: A number between 0 and 5 indicating the emphasis to be placed on matching of ancestors. The number 0 corresponds to turning the Match Elements Considering Their Ancestor Names option off in Basic mode. The number 5 corresponds to turning the Match Elements Considering Their Ancestor Names option on in Basic mode.

• Linguistic Weight: A number between 0 and 5 indicating the emphasis to be placed on matching of element names. The number 0 indicates that the element names need not match. The number 5 indicates that the element names must be an exact match.

• Type Weight: A number between 0 and 5 indicating the emphasis to be placed on matching of element names. The number 0 indicates that the element types need not match. The number 5 indicates that the element types must be an exact match.

• Match Threshold (%): The Auto Map computes a percentage match for each map (Ancestor, Linguistic, Type), and selects the highest percentage amongst these. If the highest match is above the threshold percentage, then a match is made.

• Dictionaries: Enables you to add existing dictionaries to the Auto Map. Dictionaries can be defined from existing maps and used in subsequent maps.

40.6.2 How to Execute an Auto Map

To execute an Auto Map:

1. Drag and drop a complex source node to the target element in the XSLT pane. If you are using Map View, then you'd drop the source node to a node in the target pane.
2. Depending on your Auto Map Preferences, the Preferences dialog might appear. Select your Auto Map preferences, and click OK.
3. Depending on your Auto Map Preferences, the Auto Map dialog might appear. Verify the matches created by the Auto Map, and click OK.

40.7 Checking the Completion Status of the Map

If you are using a target schema for your map, you can check the completion status of the map at any time. You can do this in both Map View and XSLT View. The completion status check flags the following:

• All unmapped target elements and attributes. A flag indicates if the target element is a required element in the target schema.

• Target elements mapped with incomplete XPath expressions. For instance, an XPath function, mapped to a target node, might be missing a parameter.

• All missing target elements and attributes. A flag indicates if the missing target element is a required element in the target schema.

To check the completion status of a map, right-click the Canvas (center) pane, and select Completion Status from the context menu. The Completion Status dialog appears showing all incomplete target nodes. Clicking a row in the Completion Dialog status selects the corresponding node location in the XSLT/target tree. Figure 40-37 shows the Completion Status dialog with a missing node highlighted.

Figure 40-37 Completion Status Dialog

Description of "Figure 40-37 Completion Status Dialog"

40.8 Testing the Map

The XSLT Map Editor provides a tool to test the map. To invoke the test tool, right-click the Canvas pane, and select Test from the context menu. You can use the test tool in both Map View and XSLT View.

Figure 40-38 demonstrates launching the Test XSL Map dialog.

Figure 40-38 Invoking the Test Dialog

Description of "Figure 40-38 Invoking the Test Dialog"

40.8.1 How to Test the Transformation Mapping Logic

The Test XSL Map dialog shown in Figure 40-39 enables you to test the transformation mapping logic you designed with the XSLT Map Editor. The test settings you specify are stored and do not need to be entered again the next time you test. Test settings must be entered again if you close and reopen Oracle JDeveloper.

Figure 40-39 Test XSL Map Dialog

Description of "Figure 40-39 Test XSL Map Dialog"

To test the transformation mapping logic:

1. In the Source XML File field, choose to allow a sample source XML file to be generated for testing or click Browse to specify a different source XML file.

   When you click OK, the source XML file is validated. If validation passes, transformation occurs, and the target XML file is created.

   If validation fails, no transformation occurs and a message displays on-screen.

2. Select the Generate Source XML File check box to create a sample XML file based on the map source XSD schema.

3. Select the Show Source XML File check box to display the source XML files for the test. The source XML files display in an Oracle JDeveloper XML editor.

   If the map has defined parameters, the Parameters With Schema or Parameters Without Schema table can appear.

   1. If the Parameters With Schema table appears, you can specify an input XML file for the parameter using the Browse button. Select the Generate File check box to generate a file.

   2. If the Parameters Without Schema table appears, you can specify a value by selecting the Specify Value check box and making appropriate edits to the Type and Value columns.

4. In the Target XML File field, enter a file name or browse for a file name in which to store the resulting XML document from the transformation.

5. Select the Show Target XML File check box to display the target XML file for the test. The target XML file displays in an Oracle JDeveloper XML editor.

6. If you select to show both the source and target XML, you can customize the layout of your XML editors. Select Enable Auto Layout in the upper right corner and click one of the patterns.

7. Click OK.

   The test results shown in Figure 40-40 appear.

   For this example, the source XML and target XML display side-by-side with the XSL map underneath (the default setting). Additional source XML files corresponding to the Parameters With Schema table are displayed as tabs in the same area as the main source file. You can right-click an editor and select Validate XML to validate the source or target XML against the map source or target XSD schema.

   Figure 40-40 Test Results

   
   Description of "Figure 40-40 Test Results"

40.8.1.1 How to Test XSLT Maps that Use DVM Lookup Functions

You can test an XSLT map that contains DVM lookup functions. If your map uses DVM lookup functions that reference local files or files in the MDS, and these files are accessible from your JDeveloper environment, then you need not perform any additional steps.

If your map uses DVM lookup functions that reference files not accessible in your JDeveloper environment, then you can create local DVM files for testing without requiring to modify the DVM references in your XSLT. Use the following steps:

1. If you have not already run the XSLT test, execute the test tool once. The test tool generates the file UnitTestURLs.dvm in the XSLNonDeployedFiles folder, located in the same folder as your XSLT file.

   The UnitTestURLs.dvm file contains mappings between the DVM references in your XSLT file and DVM references to local test files. For example, if the XSLT file that you are testing has a reference to the file, oramds:/apps/AIAMetaData/dvm/CUSTOMERPARTY_STATUSCODE.dvm, but you do not have access to this file in JDeveloper, then you can create a local DVM lookup file against which the test is performed.

2. Open the UnitTestURLs.dvm file, located in the XSLNonDeployedFiles folder, in JDeveloper.
3. Under the serverURL column, add the reference for the DVM file that you reference in your XSLT.
4. Under the testURL column, add the reference to a local file to be used for testing.
   
   Description of the illustration GUID-5BB56960-097F-4DC9-A0EE-EC1533418CF5-default.gif
5. Save the UnitTestURLs.dvm file.
6. Populate your test DVM file with test data.
7. Execute the test tool. The lookup is performed against the local file. You do not need to modify your XSLT to point to the local file. The test uses the UnitTestURLs.dvm file to look up the correct test file for the reference defined in the serverURL column.

40.8.1.2 How to Test XSLT Maps that Use XREF Functions

You can use the local dvm lookup file, called UnitTestXrefFunctionReturn.dvm to emulate the test. This file is automatically generated when you run the XSLT test for the first time.

The UnitTestXrefFunctionReturn.dvm file includes default responses for all the XREF functions. This simulates the expected responses when the functions execute correctly. You may modify the default responses. You can also create different return values for different calls of the same function when the parameter values are different.

The following figure shows the initial DVM file.

Figure 40-41 The UnitTestXrefFunctionReturn.dvm File

Description of "Figure 40-41 The UnitTestXrefFunctionReturn.dvm File"

The functionName column specifies the name of the function. To start with, there is only one entry for each function with the default behavior defined. All XREF functions execute with this default information. You can optionally create more entries for a given function, and enter different return values for the function based on the input parameters.

The returnValue column specifies the return value from the function. This defines what you would like to see returned from the function.

The other columns define qualifiers that you can use to differentiate one function call from another, based on the value of a given parameter. Each of these columns define a parameter available in a given function call. Not all parameters are available in all functions. When a parameter is not available, it is marked as NA (Not Available) in the original table.

40.8.1.2.1 Working with returnValue:

The returnValue column can either be defined as a text value, such as SBL_001, or may be defined by a parameter name. For instance, if we look at the first function, lookupXRef, this function has a return value of RefColumnValue. As this is the name of a parameter (RefColumnValue), the value of this parameter is the return value of the function to the XSLT.

For example, if the call to the lookupXRef function looks like the following:

lookupXRef( oramds:/apps/AIAMetaData/xref/CUSTOMERPARTY_PARTYLOCATIONID.xref",
"COMMON_ID", "COMMON_001", "SBL_ID", false())

Then the value COMMON_001 is returned, as this is the value of the RefColumnValue parameter that was passed.

For the markForDelete function, the value true is returned, converted to Boolean.

For the lookupXRef1M and lookupPopulatedColumns functions, a node-set is returned by the function. This node-set contains elements of the following form:

<column name="columnNameHere">columnValueHere</column>

As shown in Figure 40-41, the default value for the lookupXRef1M function is:

:RefColumnName:RefColumnValue:ColumnName:RefColumnValue

This encodes the column names and values for two column nodes that are returned in a node-set from the function. The first character defines the delimiter to be used in parsing the information. If your data contains a colon (:), you can use any character as the delimiter that is not in your test data, by putting that character as the first character and using it to delimit the data (say, #abc:def#abc:ghi).

For example, if we have the following function call to lookupXRef1M:

lookupXRef1M ("oramds:/mydata", "COMMON_ID", "COMMON_001", "SAP_ID", false())

Then using the default definition, for a return value of :RefColumnName:RefColumnValue:ColumnName:RefColumnValue, you would receive back two column elements:

<column name="COMMON_ID">COMMON_001</column>
<column name="SAP_ID">COMMON_001</column>

If you change the line in the DVM to have a returnValue of :SAP_ID:SAP_001:SBL_ID:SBL_001:ORCL_ID:ORCL_001, then the function returns three column nodes:

<column name="SAP_ID">SAP_001</column>
<column name="SBL_ID">SBL_001</column>
<column name="ORCL_ID">ORCL_001</column>

40.8.1.2.2 Adding Additional Rows:

You can also add additional rows to the DVM file. You can add additional rows for a function by providing different input values for the parameters resulting in different return values.

For example, if we have several lookups against the same XREF file, but want to get different values back from each lookup, we could add the following lines for lookupXRef to the DVM file:

In determining the correct return value, the design time emulator finds the first matching set of parameter values by starting at the bottom of the DVM table. The return value corresponding to the first matching row is returned.

As illustrated in the preceding figure, a call to lookupXRef("oramds:/apps/AIAMetaData/xref/CUSTOMERPARTY_PARTYLOCATIONID.xref", "COMMON_ID", "COMMON_001", "SBL_ID", false()), for example, would return the value, SBL_001.

A call to lookupXRef("oramds:/apps/AIAMetaData/xref/CUSTOMERPARTY_PARTYLOCATIONID.xref", "COMMON_ID", "COMMON_002", "SBL_ID", false()), on the other hand, does not match any of the last three rows, and returns the default value COMMON_002 (the value of the parameter, RefColumnValue).

40.8.2 How to Generate Reports

You can generate an HTML report with the following information:

• XSL map file name, source and target schema file names, their root element names, and their root element namespaces

• Target document mappings

• Target fields not mapped (including mandatory fields)

• Sample transformation map execution

Follow these instructions to generate a report.

1. In the Canvas (center) pane, right-click and select Generate Report for XSLT Map.

   The Generate Report dialog appears, as shown in Figure 40-42. If the map has defined parameters, the appropriate parameter tables appear.

   Figure 40-42 The Generate Report Dialog

   
   Description of "Figure 40-42 The Generate Report Dialog"

   For more information about the fields, see the online Help for the Generate Report dialog.

40.8.3 How to Customize Sample XML Generation

You can customize sample XML generation by specifying the following parameters. Select Preferences > XSL Maps in the Tools main menu of Oracle JDeveloper to display the Preferences dialog. You can modify the following settings under Sample XML Generation:

• Number of repeating elements

  Specifies how many occurrences of an element are created if the element has the attribute maxOccurs set to a value greater than 1. If the specified value is greater than the value of the maxOccurs attribute for a particular element, the number of occurrences created for that particular element is the maxOccurs value, not the specified number.

• Generate optional elements

  If selected, any optional element (its attribute minOccurs set to a value of 0) is generated the same way as any required element (its attribute minOccurs set to a value greater than 0).

• Maximum depth

  To avoid the occurrence of recursion in sample XML generation caused by optional elements, specify a maximum depth in the XML document hierarchy tree beyond which no optional elements are generated.

40.9 Importing an External XSLT Map

If you have an XSLT map that has been developed with an editor other than JDeveloper, you can import it into JDeveloper.

To import an external map:

1. From the File main menu, select New > From Gallery.
2. Under Categories, select General > XML. Under Items, select XSL Map from XSL Stylesheet. Click OK. The XSLT Chooser dialog appears.
3. Select the XSLT file to be imported. Click OK. The file is opened and a default header is inserted with no source or target schema definition.
4. To create source and target schema definitions, right-click the Canvas (center) pane, and select Replace/Add Source Schema to set the source schema. Select Replace/Add Target Schema to set the target schema.

   Note:

   Imported maps can use Map View only if both the source and target schemas are defined and there are no XSLT features not supported in Map View.

   All maps can use the XSLT View.

40.10 Using Variables and Parameters

You can add variables and parameters to the XSLT map. These are available in both Map View and XSLT View.

40.10.1 How to Add Global Variables

Global variables can be used in both Map View and XSLT View.

To create a global variable:

1. Right-click any node in the source pane and select Add Global Variable from the context menu. Alternatively, click the Add icon, identified by the green plus sign in the XSLT toolbar and select Add Global Variable. This option is also available on the canvas context menu under the Create option.

   The Variable dialog appears.

2. Enter a name for the variable, and an optional namespace and prefix if desired.
3. Click OK.

   The variable node appears at the top of the XSLT pane or target pane depending on whether you are using the XSLT View or Map View.

   The variable also appears in the source tree within the Variables folder. This enables you to map from the variable to XPath expressions or nodes in the target tree.

   Note:

   You cannot define a structure for the variable in the current release. If the variable you are referencing represents a complex structure, you can reference nodes within the structure by entering the appropriate XPath expression manually.

40.10.2 How to Add Local Variables in Map View

To add a local variable in Map View:

1. Right-click an existing node in the target tree (not grayed/italicized) and select Add XSL Instruction > variable from the context menu that appears.

   The Variable dialog appears.

2. Enter a name for the variable, and an optional namespace and prefix if desired.
3. Click OK.

   The variable is added to the target tree, just above the node that you selected.

   The variable also appears in the source tree within the Variables folder. This enables you to map from the variable to XPath expressions or nodes in the target tree.

   To determine if the variable is in scope for a particular XSLT node or XPath expression, select the target tree node or XPath expression. If the variable is in scope for the target tree node or XPath expression, then the variable appears in bold in the source tree. If the variable is not in scope for the selected target tree node or XPath expression, then the variable appears disabled in the source tree.

   Only scalar variables can be defined. You cannot define the structure of a variable. If the variable you are referencing represents a complex structure, you can reference nodes within the structure by entering the appropriate XPath expression manually.

40.10.3 How to Add Local Variables in XSLT View

In XSLT View, local variables are added in the same manner as other XSLT elements. See How to Add XSLT Statements for details about adding XSLT elements using the context menu or Components window.

So, for example, if you select Insert Sibling Before > XSL > Variable from the context menu of an XSLT node, you get the Variable dialog box. Enter the name of the variable, optionally specify a namespace, and click OK.

The variable appears at the appropriate place in the XSLT/target pane. You can choose to map XPath expressions to the variable to set the value of the variable.

The variable also appears in the source tree under the Variables folder. This enables you to map from the variable to other XPath expressions or XSLT nodes.

To determine if the variable is in scope for a particular XSLT node or XPath expression, select the XSLT node or XPath expression. If the variable is in scope for the XSLT node or XPath expression, then the variable appears in bold in the source tree. If the variable is not in scope for the selected XSLT node or XPath expression, then the variable appears disabled in the source tree.

Only scalar variables can be defined. You cannot define the structure of a variable. If the variable you are referencing represents a complex structure, you can reference nodes within the structure by entering the appropriate XPath expression manually.

Note:

If you are using XSLT 1.0, and using a complex variable, it might be necessary to wrap the variable in the ora:node-set function before an XPath expression can be used to access nodes within the variable.

For example, say the myVar variable has the following structure:

<xsl:variable name="myVar">
  <A>
     <B>sometext</B>
  </A>
</xsl:variable>

The text in B can be referenced as ora:node-set($myVar)/A/B. The node-set function is not necessary in XSLT 2.0.

40.10.4 How to Add Global Parameters

Parameters can be added to the XSLT map editor both as global parameters and named template parameters.

You can add global parameters when creating an XSLT map. See How to Create an XSLT Map for more details. You can also add global parameters to an existing map.

To add a global parameter to an existing map:

1. Right-click any node in the source pane, and select Add Global Parameter from the context menu.

   Alternatively, click the Add icon, identified by the green plus sign, in the XSLT toolbar, and select Add Global Parameter. Figure 40-43 shows the XSLT toolbar, which resides at the top of the XSLT Map Editor.

   Figure 40-43 Adding Global Parameter from the XSLT Toolbar

   
   Description of "Figure 40-43 Adding Global Parameter from the XSLT Toolbar"

   You can also right-click anywhere on the canvas (center) pane, and select Create > Add Global Parameter from the context menu.

   The Add Parameter dialog appears. Figure 40-44 shows the Add Parameter dialog.

   Figure 40-44 Add Parameter Dialog

   
   Description of "Figure 40-44 Add Parameter Dialog"
2. Enter a Local Name for the parameter and optionally specify a namespace.

   If the parameter is a complex parameter, you can specify a schema and an element definition for the parameter. Click the Help button in the dialog to get more information on the individual fields.

3. Click OK in the Add Parameter dialog to create the parameter.

The parameter node appears at the appropriate place in the target pane (for Map View) or XSLT pane (for the XSLT View). This enables you to map XPath expressions to the parameter to set the parameter's default value.

The parameter also appears in the source tree. This enables you to map the parameter to XPath expressions or nodes in the XSLT tree.

Note:

You can also add parameters like other XSLT elements. See How to Add XSLT Statements for details about adding XSLT elements using the context menu or Components window.

40.11 Substituting Elements and Types

You can substitute elements and types in the source and target trees.

Use element substitution when:

• An element is defined as the head of a substitution group in the underlying schema. The element may or may not be abstract. Any element from the substitution group can be substituted for the original element.

• An element is defined as an any element. Any global element defined in the schema can be substituted.

Use type substitution when:

• A global type is available in the underlying schema that is derived from the type of an element in the source or target tree. The global type can then be substituted for the original type of the element. Any type derived from an abstract type can be substituted for that abstract type.

• An element in the source or target tree is defined to be of the type anyType. Any global type defined in the schema can then be substituted.

Type substitution is supported by use of the xsi:type attribute in XML.

To substitute an element or type in the source and target trees:

1. In the source or target tree, right-click the element for which substitution applies. If you are working in the XSLT pane, the element you select must exist in the XSLT before substitution.
2. From the context menu, select Substitute Element or Type. If this option is disabled, no possible substitutions exist for the element or its type in the underlying schema.

   The Substitute Element or Type dialog shown in Figure 40-45 appears.

   Figure 40-45 Substitute Element or Type Dialog

   
   Description of "Figure 40-45 Substitute Element or Type Dialog"
3. Select either Substitute an element or Substitute a type (only one may be available depending upon the underlying schema).

   A list of global types or elements that can be substituted displays in the dialog.

4. Select the type or element to substitute.
5. Click OK.

   The element or type is substituted for the originally selected element. This selection displays differently depending upon the type of substitution and where the substitution is done, as described in the following sections:

   • For Type Substitutions

     • Type substitutions in the source tree

       
       Description of the illustration GUID-6E660428-8FC4-4556-B0E2-B170061774CD-default.gif

       The xsi:type attribute is added beneath the original element, as shown in the preceding figure. An S icon is displayed against the element to indicate that the node was substituted. You can map from any structural elements in the substituted type, including the xsi:type attribute.

       Note:

       Unlike element substitution, only one type substitution at a time can be displayed in the source tree. However, this does not prevent you from writing a map that allows the source to switch between the original type and the substituted type.

       If a node is not visible in the source tree, and the node is mapped to an XPath expression, the XPath expression mapped to the node is still displayed in the center canvas pane.

     • Type substitutions in the Map View target tree

       
       Description of the illustration GUID-F731C0D3-BE2F-4B24-B2BE-58FA3B3D45BA-default.gif

       The xsi:type attribute is added beneath the original element, as shown in the preceding figure. The attribute is disabled in Map View, and set to the type value that was selected. An S icon is displayed against the element to indicate that the node was substituted. You can map to any structural elements in the substituted type, except the xsi:type attribute.

     • Type substitutions in the XSLT pane of the XSLT View

       The xsi:type attribute is added beneath the original element. It's value is set to the type value that was selected, but may be mapped to. An S icon is displayed against the element to indicate that the node was substituted. You can add any structural elements through the Add Children From Schema context menu option.

       
       Description of the illustration GUID-DC604FB7-2AA3-4C14-B147-85D04000C4BC-default.gif

       In some cases, it may be necessary to set the value of the xsi:type field dynamically using an XPath statement. If you need to dynamically set the value of the xsi:type, you can use type substitution to temporarily provide access to the structural elements that are needed for the expected value at runtime.

       Add the elements that are needed, then map the desired XPath statement to the xsi:type attribute to set the value dynamically. As the runtime value for xsi:type is not available at design time, question-mark icons (?)are displayed on elements that depend upon the type value, if it is set dynamically.

       
       Description of the illustration GUID-3B6B4D4C-D3F0-4DD5-B35E-7C65DCAB9273-default.gif

     • Type substitutions in the target pane of the XSLT View

       You can also make substitutions in the target pane of the XSLT View. This pane represents the target schema document. After you make a type substitution in the target pane, the xsi:type attribute is added beneath the original element along with any structural elements associated with that type, as shown in the following figure.

       
       Description of the illustration GUID-CB8CD2F2-7A38-4595-8477-A4F9BB252E70-default.gif

       You can select these elements and drop them into the XSLT pane, as needed. These elements also show up in the Add Children From Schema context menu option available in the XSLT pane.

       For example, in the following figure, we select all children of a substituted element (Item).

       
       Description of the illustration GUID-5C243496-B76C-49DC-AB97-A00BCE7BF03B-default.gif

       We then drop the new Item node as a child of the Items node in the XSLT pane, as shown in the following figure.

       
       Description of the illustration GUID-DB4D832E-6AF4-4F7A-A58E-8AB389D339AA-default.gif

       The Item node and its children are added as children of the Items node. You can similarly create different structures from different substitutions in the target pane.

   • For Element Substitutions

     • Element substitutions in the source tree

       Both the original element and the substituted element are displayed in the source tree, and are connected by a blue bracket. An S icon is displayed against the node that is substituted. You can map from any structural elements in the substituted element.

       
       Description of the illustration GUID-10E8EA16-8016-492A-9C86-4EC72ABFB7A7-default.gif

       In the preceding figure, the ns1:ShipFutureDate is substituted for the any element.

       You can also substitute multiple elements at the same time, as shown in the following figure.

       
       Description of the illustration GUID-9650FF2D-13C2-4F09-A239-D1FD3BEF09B8-default.gif

     • Element substitutions in the Map View target tree

       
       Description of the illustration GUID-8849C4BE-E915-4CCF-BAAD-CD892F95C6DE-default.gif

       As shown in the preceding figure, both the original element and the substituted element are connected with a blue bracket. An S icon is displayed against the node that was substituted. You may map to any structural elements in the substituted element.

     • Element substitutions in the XSLT pane of the XSLT View

       In order to substitute an element in the XSLT pane, the original element must be one that can appear in the XSLT. Any elements cannot appear in the XSLT pane, and must be substituted in the XSLT View target pane, as discussed in the next section. Abstract elements can be added to the XSLT pane temporarily, but should not be used as final output. Elements that are the head of a substitution group and are not abstract can be used as normal elements, and also be substituted.

       In the following figure, the ns0:attachment element is an abstract element that is also the head of a substitution group. When a substitution is made for this in the XSLT pane, the element is replaced with the substitution.

       
       Description of the illustration GUID-BF7BEA96-EF79-448F-A291-B8671FD645BF-default.gif

       After substitution, the abstract element is replaced with the selected element. The S icon indicates the substitution. You can add child elements to the substituted element using the Add Children From Schema context menu. This is depicted in the following figure.

       
       Description of the illustration GUID-57DDE43C-7047-4FB6-9EDA-60FBFB130D8F-default.gif

     • Element substitutions in the target pane of the XSLT View

       You can also make substitutions in the target pane of the XSLT View. The target pane represents the target schema document. After making an element substitution in the target pane, the elements substituted are added beneath the original element along with any structural elements associated with that type, as shown in the following figure.

       
       Description of the illustration GUID-D9D19AD2-A3D2-4AB2-B13A-2369FCDA46E3-default.gif

       You can select these elements and drop them into the XSLT pane, as needed. These elements also show up in the Add Children From Schema context menu option available in the XSLT pane.

6. To remove a substituted node, right-click any node with an S icon and select Remove Substitution from the context menu.
7. To see all possible nodes where substitution is allowed, right-click the source or target tree and select Show Substitution Node Icons.

   All nodes where substitution is possible are marked with an * icon, as shown in Figure 40-46.

   Figure 40-46 All Possible Substitutions

   
   Description of "Figure 40-46 All Possible Substitutions"
8. To hide the icons, right-click and select Hide Substitution Node Icons.

40.12 Using Named Templates

You can add named templates to the XSLT map. These templates can be edited within the XSLT Map Editor. You can invoke named templates by using the xsl:call-template instruction.

Named templates can only be used with the XSLT View. Once you add a named template in an XSLT map, the map can only be opened in XSLT View.

40.12.1 How to Create a Named Template

To create a new named template:

1. Right-click a blank area in the XSLT pane, and select New Named Template from the context menu. Alternatively:

   • Right-click a blank area in the canvas (center) pane, and select Create >New Named Template from the context menu.

   • Right-click any source node in the source pane, and select New Named Template from the context menu.

   • Select the Add button, identified by the green plus (+) icon, in the XSLT toolbar, and select New Named Template.

   The Add Named Template dialog appears.

2. Enter a name for the template. Optionally, set a namespace.

   You can click Help to display help on the available options in the dialog.

3. Optionally click the Add button, identified by the green plus (+) icon, to add a parameter. The Add Parameter dialog appears.
4. Enter a name for the parameter. Optionally, set a namespace.

   If the parameter is a complex parameter, you can specify a schema and an element definition for the parameter. Click the Help button in the dialog to get more information on the individual fields.

5. Click OK in the Add Parameter dialog to add the parameter.
6. Add any more parameters required for the named template.
7. Click OK in the Add Named Template dialog to create the named template.

40.12.2 How to Edit a Named Template

When a named template is first created, it is opened for editing in the XSLT Map Editor. You can switch between editing the named template and editing the XSLT map by using the drop-down list in the XSLT toolbar.

Figure 40-47 shows a named template being edited in the XSLT Map Editor. The top-left hand corner has a drop-down list that lets you choose between the XSLT map and the named template (createStreet).

The source tree, any global parameters, and the named template parameters appear in the source pane on the left. The XSLT pane on the upper right represents the XSLT associated with the named template. If a target schema is used, then the target tree appears at the bottom-right corner of the editor.

Figure 40-47 Editing a Named Template

Description of "Figure 40-47 Editing a Named Template"

40.12.3 How to Add Parameters to an Existing Named Template

To add parameters to an existing named template:

1. Ensure that the named template appears in the XSLT Map Editor. To switch to the named template, select the name of the named template from the drop-down list in the XSLT toolbar. See Figure 40-47 for an example.
2. Right-click a source node and select Add Parameter from the context menu. Alternatively:

   • Right-click in a blank area on the canvas (center) pane, and select Create > Add Parameter from the context menu.

   • Click the Add button, identified by the green plus (+) icon, on the XSLT toolbar. Select Add Parameter from the drop-down list that appears.

3. Specify a name for the parameter, and other details, in the Add Parameter dialog. Click the Help button in the dialog to get more information on the individual fields.
4. Click OK in the Add Parameter dialog to add the parameter.

40.12.4 How to Invoke a Named Template

A named template is invoked using the xsl:call-template instruction. You can add the xsl:call-template instruction as a node in the XSLT pane.

To invoke a named template:

1. Add the xsl:call-template instruction as an XSLT node. You can add the xsl:call-template instruction from the context menu or the Component window. See How to Add XSLT Statements for details about adding XSLT elements.

   The Set Attribute dialog appears.

2. Select the named template to be invoked. Click OK.

   The xsl:call-template instruction is added to the XSLT tree.The parameters (xsl:use-param instructions) are added as child nodes.

3. Map values to the xsl:with-param XSLT nodes to set the values for the parameters.

40.13 Using Template Rules

Template rules are xsl:template statements with match attributes. Template rules are supported by the XSLT Map Editor. You can use template rules in the XSLT View only. Template rules are not supported in the Map View.

The XSLT Map Editor enables you to add template rules in various ways. You can insert the template rule manually, or refactor an existing mapping to create a template rule.

When adding the template rule manually, you also need to insert an apply-templates statement to invoke the template at the appropriate place in the XSLT. When refactoring an existing map to create a template rule, the apply-templates statement is inserted automatically.

40.13.1 How to Create a Template Rule

1. Use one of the following methods to invoke the New Template Rule dialog:

   • Right-click the node in the source pane that is to serve as the match node. Select New Template Rule from the context menu that appears.

   • Right-click a node in the target pane. Select New Template Rule from the context menu that appears.

   • Right-click a node in the XSLT pane. Select New Template Rule from the context menu that appears.

   • Right-click a blank area in the canvas (center) pane. Select Create > New Template Rule from the context menu that appears.

   • Click the Add icon, identified by the green plus (+) sign, on the XSLT toolbar. Select New Template Rule from the list of options that appears.

   The New Template Rule dialog appears. Figure 40-48 shows the New Template Rule dialog.

   Figure 40-48 New Template Rule Dialog

   
   Description of "Figure 40-48 New Template Rule Dialog"

   The New Template Rule dialog contains the following fields:

   • Match Node: Specifies the value for the match attribute in the xsl:template definition.

     The match attribute contains a pattern used to match a node in the input XML document. The XSLT processor executes the instructions within a template when the node it is processing matches the pattern defined in the template match attribute.

   • Initialization Section: Used to determine the content of the new template rule.

     You can choose to select Create empty template to create an xsl:template instruction with no content. Alternatively, you can select Select nodes to generate in template to view and select target schema nodes that you would like to create when the template is executed.

     The Select nodes to generate in template option is available only if a target schema is being used.

   • Search by local name: If the Select nodes to generate in template option is selected, a tree representing the target schema is displayed. This option enables you to search for a node in the target schema tree using its local name.

   The New Template Rule dialog box may have automatically populated fields, depending on the mode you choose to invoke the dialog. Table 40-2 lists the pre-populated fields corresponding to each choice. If the method of invocation is not listed, then no fields are pre-populated.

   ---

   Table 40-2 Methods of Invoking the New Template Rule Dialog

   Invoked From	Automatically Populated Information
   A node in the source pane	The Match Node is populated with the absolute path to the source node. You can edit this value, if required. The Create Emty Template option is pre-selected in the Initialization section. You may change this selection, if required.
   A node in the target pane	The Select nodes to generate in template option is pre-selected in the Initialization section and the target schema tree is displayed. The target schema node used to invoke the New Template Rule dialog is pre-selected in the target tree. You may change this selection, if desired. The Match Node field must be populated with the desired match pattern for the template.

   ---

2. Set the Match Node as desired. Here are some common examples:

   • /ns0:PurchaseOrder/ns0:ShipToContact/ns0:Region: The template executes when the processor is processing the node with this path.

   • Item: The template executes when the processor is processing any node with the name Item.

   • HighPriorityItems/Items/Item: The template executes when the processor is processing any Item node that is a child of an Items node that in turn is a child of a HighPriorityItems node.

3. Select the content desired in the Initialization section. If you know the output nodes that you would like the template to create, select the Select nodes to generate in template option, and select the output nodes from the target schema tree that is displayed. You can use the Search by local name field to search within the target schema tree. You can select multiple nodes in the target tree by clicking each desired node while holding down the Shift key.
4. Click OK in the New Template Rule dialog to create the template. A new xsl:template statement is inserted at the end of the XSLT.
5. If you do not have pre-existing apply-templates statement that invokes the template rule, then insert an appropriate apply-templates statement to invoke the template rule.

   If an apply-templates statement is not present, you can see a warning icon against the xsl:template statement and question-mark (?) icons against any nodes within the template. The following figure shows an example:

   
   Description of the illustration GUID-0E89C2B8-4BA3-457E-9AE9-F58CB3543394-default.gif

   In general, the apply-templates statement is inserted at the position where you would like to generate the nodes contained in the template. For example, in the preceding figure, the apply-templates statement needs to be inserted at the point where the Address node and its children need to be created.

   After you insert the apply-templates statement to invoke the template rule, the warning icon and the question mark (?) icons disappear.

40.13.1.1 Example: Creating a Template Rule

As an example, let us create a template rule for an existing map, as shown below:

Description of the illustration GUID-D6D847C9-265F-40DA-931A-10774DEAB82C-default.gif

This example seeks to create a single template that processes the Address information in the source ShipTo and BillTo elements to create the Address in the ShippedTo and BilledTo elements in the target. The following steps illustrate the process:

1. Right-click the Address node under the ShipTo or BillTo node in the source pane, and select New Template Rule from the context menu that appears.

   The New Template Rule dialog appears. The Match Node is pre-populated with the path to the Address node that you selected in the source pane. This match string is specific to the Address element under ShipTo, but we need to create a template that will process any Address field in the source document.

   
   Description of the illustration GUID-2C5CC69C-2AF5-4F23-9D29-BC5D1D75CF35-default.gif

2. Modify the Match Node string to contain only the name Address. This will match all Address nodes in the source document irrespective of where they appear in the document.

   
   Description of the illustration GUID-990687C8-4899-4305-A2BA-186319E74B30-default.gif

3. Select the Select nodes to generate in template option. The target schema tree appears.

   When the template rule is invoked, we would like to create the Address element in the target, along with its children.

4. Select the Address node under the ShippedTo or the BilledTo element, as both elements have identical structures.

5. To select the children of the Address node, press and hold down the Shift key, and click the Zip element, which is the last child of the Address element. This selects the Address element and all its children.

   
   Description of the illustration GUID-44E88789-3B6A-49D3-8837-EF671867EC88-default.gif

6. Click OK to create the template rule.

   
   Description of the illustration GUID-3B636F36-DB64-420E-BC6D-0B309891F5B5-default.gif

   As the rule is not yet invoked anywhere in the map, a warning icon appears against the template, and the nodes that the template creates have question mark (?) icons against them.

40.13.1.1.1 Invoking the Template

Next, we need to invoke the template for both the ShipTo and BillTo Address elements in the source to create the ShippedTo and BilledTo Address elements in the target. We need to create apply-templates statements in the XSLT at the places where we would like to create these Address elements. The following steps describe the process.

1. Right-click the Invoice node in the XSLT pane, and select Add Children From Schema > BilledTo from the context menu that appears. The BilledTo node is inserted along with its required child nodes.

   
   Description of the illustration GUID-5693D4DA-C168-42D4-A016-A4BA1621726D-default.gif

2. Right-click the Invoice node in the XSLT pane, and select Add Children From Schema > ShippedTo from the context menu that appears. The ShippedTo node is inserted along with its required child nodes.

   
   Description of the illustration GUID-C2F5AE6E-5739-4513-8241-C197441B7166-default.gif

3. Right-click the ShippedTo/Address node and select Delete. Repeat the same for the BilledTo/Address node. We would create the Address nodes using the template rule that we created.

4. Right-click the ShippedTo node and select Append Child > XSL > apply-templates from the context menu that appears. The xsl:apply-templates statement is added.

   
   Description of the illustration GUID-000C0FF1-B268-4605-8DE7-472C6F003BFE-default.gif

5. Right-click the BilledTo node and select Append Child > XSL > apply-templates from the context menu that appears. The xsl:apply-templates statement is added.

6. Drag a line from the ShipTo/Address node in the source pane to the ShippedTo/apply-templates node in the XSLT pane. This sets the select attribute of the apply-templates statement, so that only the ShipTo/Address node is processed by the xsl:apply-templates statement.

7. Drag a line from the BillTo/Address node in the source pane to the BilledTo/apply-templates node in the XSLT pane. This sets the select attribute of the apply-templates statement, so that only the BillTo/Address node is processed by the xsl:apply-templates statement.

   At this point, the warning icon on the template rule disappears, as we have defined the template invocation. If you click the template rule, the two source Address nodes processed by the template are highlighted, as illustrated in the following figure.

   
   Description of the illustration GUID-B22B2BD0-9237-4C53-8B9D-8D2575B7F698-default.gif

   Next, the nodes below the template rule can be mapped.

8. Drag and drop lines from the elements under the BillTo/Address node, or the ShipTo/Address node, to the appropriate elements under the Address template rule.

   As you drag from either source Address (BillTo or ShipTo), lines are drawn to both source addresses. This is because both BillTo/Address and ShipTo/Address are context nodes for the template.

   
   Description of the illustration GUID-F091ECDE-65E6-482A-AA46-97ACD99D9574-default.gif

   The source code for the template now appears as follows:

     <xsl:template match="Address">
       <Address country="{@country}">
         <Street>
           <xsl:value-of select="concat (Street1, ', ' , Street2 )"/>
         </Street>
         <City>
           <xsl:value-of select="City"/>
         </City>
         <State>
           <xsl:value-of select="State"/>
         </State>
         <Zip>
           <xsl:value-of select="Zipcode"/>
         </Zip>
       </Address>
     </xsl:template>
   

40.13.2 How to Refactor an Existing Map to Create a Template Rule

You can refactor code from an existing template to create a new template rule. This is useful if the template rule that is created can be reused in multiple places, as was the case with the Address template rule created in the previous section.

The Create in Template option enables you to refactor a section of XSLT instructions into a separate template that can be invoked from multiple places.

In the following example, we refactor an existing mapping to create a template rule.

In the following map, the XSLT that processes each Address element in the source is repeated for each Address node. For easier maintenance, you may want to consolidate redundant code into reusable templates. This way, if the code is later updated, you would not have to update multiple copies.

Description of the illustration GUID-3F3A7AE8-6E6B-4239-B2AA-C7005AEDE13C-default.gif

In the preceding map, if the XPath concat expression that creates Street from Street1 and Street2 needs to be modified, there are two copies that would have to be modified. However, if the concat function exists in a single template that is reused to produce both Address elements, then only one concat statement needs to be modified in future.

In the following steps, we refactor the existing mapping to create a single template that processes the Address elements:

1. Make sure that you are in the XSLT View. You can click XSLT in the top right corner of the XSLT Map Editor to switch to the XSLT View.
2. Right-click the ShippedTo/Address element in the XSLT pane and select Create in Template from the context menu that appears.
   
   Description of the illustration GUID-5D01F4DF-1170-4BB6-849C-C6E2E93046B7-default.gif

   The New Template Rule dialog appears.

   
   Description of the illustration GUID-EFD875F3-5103-462D-A9CC-333A6EFEFA12-default.gif

   The Match Node is pre-populated with a suggested match pattern derived from XPath expressions contained under the selected node in the XSLT pane. The elements selected in the target schema tree are the Address node and its children. These elements would be moved to a new template rule.

3. Click OK.

   A new template rule is created and an apply-templates statement is inserted in place of the Address node. The XPath expressions defined for the elements under the Address node in the XSLT pane are updated to contain relative paths to the Address node (context node) for the new template.

   
   Description of the illustration GUID-3BE3D280-505D-4FCA-BBBB-BE916B064699-default.gif

   Next, we use this template for both the ShipTo and BillTo Address elements.

4. Double-click the new template node. The Set Attributes dialog appears.
5. Under Enter Pattern, enter Address.
   
   Description of the illustration GUID-4A92AFFB-8B93-44A0-8CE5-32A70AB7D35A-default.gif
6. Click OK.
7. Delete the BilledTo/Address element in the XSLT pane.
8. Right-click the BilledTo node and select Add Child > XSL > apply-templates. This creates an xsl:apply-templates statement in place of the Address node.
9. Drag a line from the BillTo/Address node in the source pane to the new BilledTo/apply-templates node in the XSLT pane.
   
   Description of the illustration GUID-84C3E461-635B-4DE8-9556-05AB0643B316-default.gif

   Both BilledTo and ShippedTo Address elements are now created using a single template rule.

40.14 Using the Execution View

The Execution View displays the order of execution of your XSLT statements. When creating complex XSLT that uses named templates and template rules, it can get difficult to determine the order of execution of XSLT templates. The Execution View helps you troubleshoot issues by creating an execution tree for your XSLT.

The execution tree shows when the output nodes are created, and shows exactly which templates are invoked at various points during the XSLT execution.

40.14.1 How to Use Execution View to Prevent or Troubleshoot Runtime Errors

To launch the Execution View dialog, right-click the canvas (center) pane, and select Execution View. Alternatively, click the Execution View for XSLT Map button on the XSLT toolbar.

The Execution View is available in both the Map and XSLT views. However, it is most useful when the map contains multiple templates and the user needs to figure out as to where the templates are being invoked.

Figure 40-49 shows the Execution View dialog for an XSLT map that contains multiple templates. As per the execution view, the root template with match='/' executes first. This is followed by the creation of the Invoice, Description, and ID nodes. An apply-templates statement then invokes the ShipTo template followed by an apply-templates statement that invokes the BillTo template. Other nodes and templates are then created.

Figure 40-49 Execution View Dialog and Corresponding XSLT Tree

Description of "Figure 40-49 Execution View Dialog and Corresponding XSLT Tree"

If you click an element in the Execution View tree, the corresponding element is highlighted in the XSLT tree. For example, as shown in Figure 40-49, if you want to locate the apply-templates node that invokes the BillTo template, select the apply-templates node in the Execution View and the corresponding apply-templates statement is highlighted in the XSLT pane.

Execution View also shows calls to named templates. When you select a node inside a named template call in the Execution View tree, the XSLT editor view is refreshed to show the selected node in the named template implementation.

Execution View helps you understand the overall flow of an XSLT stylesheet. Using the Execution View, you can locate issues related to templates that are not invoked, or apply-templates statements that are invoking incorrect templates.

When using imported named templates or template rules, Execution View shows the corresponding calls, and you can use Execution View to troubleshoot problems like import precedence. However, Execution View cannot navigate to the external XSLT files.

40.14.1.1 Searching for Nodes

The Execution View dialog has a search facility that enables you to search for specific nodes in the Execution View tree. Click in the Search local names field, and type a name to search.

40.14.1.2 Setting Display Options

You can choose to show or hide certain XSLT elements in the execution tree. Click Options to bring up the Execution View Options dialog. Figure 40-50 shows the default selections in Execution View Options.

Figure 40-50 Default Execution View Options

Description of "Figure 40-50 Default Execution View Options"

40.15 Debugging the XSLT Map

Starting in 12.2.1, you can debug your XSLT maps using the SOA Debugger. You can add breakpoints at strategic locations in the XSLT map. When debugging, the debugger halts execution at the breakpoints, enabling you to verify the data and output.

XSLT maps can be complex, making them difficult to debug. For example, you may have a Java function, or other functionality, that is best tested in the application server. Also, you might find it easier to debug in the application environment, as the XSLT may be invoked from many different applications in the server. The SOA debugger provides remote debugging capability for XSLT maps that have been deployed in the application server.

You can debug any XSLT transformation used in a BPEL process or Mediator. When the BPEL process or Mediator is invoked in the composite, the debugger pauses at the breakpoints defined in the map. The XSLT map opens in JDeveloper and user data corresponding to the XSLT processing appears in the Data window.

You can also use the debugger with your Oracle Service Bus projects. For more details on using the debugger with Service Bus projects, refer to:

Debugging Oracle Service Bus Applications

40.15.1 Setting Breakpoints in the XSLT Map Editor

You can set breakpoints in the Design view of the XSLT Map Editor. This enables you to debug your XSLT map at runtime, using test data or payload.

Breakpoints may be set in either the Map or XSLT View. Breakpoints are marked with red dots in the breakpoint bar, which is to the right of the target or XSLT pane.

Before you can set breakpoints, make sure that the XSLT map is open and the Design tab is selected.

Use one of the following methods to set a breakpoint:

• Click the breakpoint bar to the right of an XSLT element or node.

• Right-click the breakpoint bar to the right of an XSLT element, or node, and select Toggle Breakpoint from the context menu that appears.

• Right-click an XSLT element, and select Debug > Toggle Breakpoint from the context menu that appears.

Note:

You can also use the preceding steps to remove existing breakpoints.

You can also choose to disable a breakpoint by selecting Disable Breakpoint from the context menus mentioned above. Disabled breakpoints show as gray icons in the breakpoint bar.

The following image shows a breakpoint set against the ponumber node.

40.15.2 Running the Debugger on the XSLT Map

Initiating a Debugging Session

After setting the breakpoints for your XSLT map, follow these instructions to start the SOA debugger:

Debugging a SOA Composite Application

Note:

For the debugger to step into the XSLT map, the map must be invoked by a mediator or BPEL process in your SOA composite.

Working with the Debugger in the XSLT Map Editor

After you run the debugger, and when the debugger comes across a breakpoint in the XSLT map, the debugger stops execution at the breakpoint. A blue arrow to the left of the breakpoint bar indicates the current position of the debugger. Also, a flashing blue icon appears against the corresponding XSLT element or node.

When the debugger is stepping through the XSLT map, all valid breakpoints in the XSLT editor change to red and green dots. Breakpoints that remain a solid red are currently invalid and are ignored by the debugger.

Note:

Some processes that invoke the XSLT map have time-out limits. If the debugger ends unexpectedly after exiting an XSLT map, the invoking process may have a time-out value defined. This time-out value may need to be redefined to support debugging the full process. Check server log files for information in the event of the debugger unexpectedly aborting.

The following example image shows breakpoints, as they appear during runtime. The breakpoints appear against the tID and Item elements. The debugger is currently at the Item node, as indicated by the blue arrow and flashing icon.

You can use the Step Over button in the main JDeveloper toolbar to step through the execution. The Step In button can be used to step into loops, call-template, apply-template, and apply-imports.The Step Out button can be used to step out of call-template, apply-template and apply-imports to the next XSLT statement.

At any point during the execution, you can look at the current values of parameters and variables in the Debugger Data window. The Data window also shows you the Context Node, Context Position, Context Size, and the Output Document being built by the XSLT processing. You can also choose to add any item visible in the Debugger Data window to the Watches window.

The following image shows sample debugger data, as it appears in the Data window on the right.

You can choose to edit the XSLT when debugging. You would need to redeploy the project before you can debug again.

40.15.3 Viewing Breakpoints

Breakpoints appear on the breakpoint bar along the right edge of the XSLT Map Editor. You can choose to see a list of all breakpoints in the XSLT map or the SOA project.

Viewing a List of All Breakpoints in the XSLT Map

Use one of the following methods to see all breakpoints in the current XSLT map:

• Right-click anywhere in the center canvas pane and select Breakpoints from the context menu that appears.

• Right-click anywhere on the breakpoint bar and select Breakpoints from the context menu that appears.

• Click Breakpoints in the XSLT toolbar.

The Breakpoints dialog appears, listing all breakpoints in the XSLT map. If a breakpoint is currently hidden in the XSLT pane, you can navigate to it by clicking the breakpoint in the Breakpoints dialog.

You can also use the Breakpoints dialog to disable or delete one or more breakpoints. A disabled breakpoint would appear as a grey dot on the breakpoint bar.

The Valid column indicates if a breakpoint is currently valid. Breakpoints can become invalid if edits to the XSLT map makes them invalid. You can choose to delete invalid breakpoints. Alternatively, invalid breakpoints can become valid again if you undo the changes made to the XSLT map.

Viewing all Breakpoints in the Current Project

The JDeveloper Breakpoints window shows all breakpoints in the current project. Select Breakpoints from the Window menu to see the Breakpoints window. You can double-click a breakpoint in the Breakpoints Window to navigate to that breakpoint in the project. You can also edit or delete breakpoints from the Breakpoints window. However, you cannot add a breakpoint from the Breakpoints window.

40.15.4 Setting Conditions for XSLT Breakpoints

You can set conditions for breakpoints, so that the execution is halted only when the breakpoint condition evaluates to true.

Use the following steps to set conditions for an XSLT breakpoint:

If the Breakpoints window is not visible, you can select Breakpoints from the JDeveloper Window menu.

1. Right-click the breakpoint in the Breakpoints window. Select Edit from the context menu that appears.
   The Edit XSLT Breakpoint dialog appears.
2. Under the Conditions tab, enter a conditional expression using javascript syntax.
   For example, the breakpoint below will break when the PartNum attribute in the $Part variable equals p1.
   
3. You can also choose to set a Pass Count for the condition. The pass count tells the debugger to ignore the breakpoint until it has been passed a certain number of times. After the pass count is met, the debugger breaks execution at the breakpoint.
4. Click OK to set the conditions.

40.16 Troubleshooting Memory Issues

If you work with large schema documents, you may sometimes encounter an out-of-memory error during auto-mapping, or during test and report generation. If you receive an out-of-memory error when using the XSLT Map Editor, you must increase the heap size of the JVM to resolve the problem.

To increase the JVM heap size:

1. Locate the config file for your application installation.

   Locate the shared Oracle JDeveloper product.conf file or the optional tool-specific .conf file located in the user's home directory. The location of these files depends on the host platform.

   • For Windows Platforms:

     The location of user/product files is often configured during installation, but may be found here:

     %APPDATA%\JDeveloper\product-version\product.conf

     %APPDATA%\JDeveloper\product-version\jdev.conf

   • For UNIX Platforms:

     $HOME/.jdeveloper/product-version/product.conf

     $HOME/.jdeveloper/product-version/jdev.conf

2. Edit the file to change the AddVMOption to the desired value. For example:

   AddVMOption -Xmx1024M
   

   Note:

   The AddVMOption value can be large for 64-bit machines. Setting it close to the amount of RAM provided by the machine provides better performance.

40.17 Setting XSL Map Preferences

Use the Preferences dialog to set preferences related to XSLT maps, such as expansion depth, and the XSLT Map Editor, such as initialization options.

40.17.1 How to Set XSLT Map Preferences

To set XSLT map preferences, select Preferences from the Tools menu. Click XSL Maps in the navigation tree that appears in the left pane of the Preferences dialog. Figure 40-51 shows the XSL Maps dialog that appears.

Figure 40-51 XSL Maps Preferences

Description of "Figure 40-51 XSL Maps Preferences"

You can set various options such as the expansion depth of the source and target trees. You can click the Help button for more information on each field.

40.17.2 How to Set the XSL Editor Preferences

To set XSLT map preferences, select Preferences from the Tools menu. In the navigation tree that appears in the left pane of the Preferences dialog, click the plus sign (+) next to XSL Maps. This expands the XSL Maps node. Select XSL Editor. Figure 40-52 shows the XSL Editor Preferences dialog.

Figure 40-52 XSL Editor Preferences

Description of "Figure 40-52 XSL Editor Preferences"

You can set various preferences for the XSLT Map Editors, such as the initialization mode. Click Help for more information on each field.

40.17.3 How to Import a Customization File to Specify Display Preferences in the XSLT Map Editor

You can specify a customization file containing display preferences for the XSLT Map Editor. In the XSL Editor Preferences dialog (Figure 40-52), click the Browse button to the right of the Custom Display Options Config File field. Select the file to import.

The customization file is an XML file that must conform to the XSLTEditorOptions.xsd schema located in the bpm-ide-common.jar file at:

oracle/tip/tools/ide/common/resource/XSLTEditorOptions.xsd

The following example shows a sample customization file. The important elements in the file are described following the example.

<?xml version="1.0" encoding="UTF-8" ?>
  <customizeXSLTeditor>
      <selectedArea>HL7</selectedArea>
      <abbreviationLists>
          <abbreviationList name="Siebel">
              <abbreviation long="Account" short="Acct"/>
          </abbreviationList>
          <abbreviationList name="SalesGeneral">
              <abbreviation long="SalesOrder" short="SO"/>
              <abbreviation long="PurchaseOrder" short="PO"/>
              <abbreviation long="BillOfMaterial" short="BOM"/>
              <abbreviation long="CreateEngineeringChangeOrderList" short="CECOL"/>
          </abbreviationList>
      </abbreviationLists>
      <customization area="HL7">
          <showFixedValueInElementName>
               <path>@LongName</path>
               <path>@LongName2</path>
               <path>@Name</path>
          </showFixedValueInElementName>
          <abbreviations>
             <apply display="treeLabels">
                 <hideText part="matchValue" maxLength="13" hide="left"/>
                 <hideText part="namedTemplateName" maxLength="15" hide="left"/>
                 <hideText part="importHref" maxLength="20" hide="left"/>
             </apply>
             <apply display="dropDownLists">
                 <hideText part="namedTemplateName" maxLength="40" hide="center"/>
             </apply>
          </abbreviations>
      </customization>
      <customization area="AIA">
          <abbreviations>
             <applyAbbreviations list="Siebel"/>
             <applyAbbreviations list="SalesGeneral"/>
             <apply display="treeLabels">
                 <hideText part="matchValue" maxLength="13" hide="left"/>
                 <hideText part="namedTemplateName" maxLength="15" hide="left"/>
                 <hideText part="importHref" maxLength="20" hide="left"/>
             </apply>
             <apply display="dropDownLists">
                 <hideText part="namedTemplateName" maxLength="40" hide="center"/>
             </apply>
          </abbreviations>
      </customization>
  </customizeXSLTeditor>
 

The following list describes the important elements in the preceding example:

• <selectedArea>: Selects the customization area to be used by the editor. A list of customization areas may be defined in the file.

• <abbreviationList name="listName">: Defines an abbreviation list that can be referenced by a customization area.

• <abbreviation name="Account" short="Acct">: Defines a specific abbreviation to use in an abbreviation list.

• <abbreviations>: Used within a customization area to define abbreviations and cut-off lengths for text in the editor.

• <applyAbbreviations>: Selects an abbreviation list or lists to use in this customization area.

• <apply display="treeLabels" | "dropDownLists">: Selects an area where text cut-offs occur.

• <hideText>: Selects specific text fields to cut-off when they are too long.

• @part: Either "matchValue", "namedTemplateName", or "importHref".

• @maxLength: Text value length limit.

• @hide: Specifies portion of the text to hide, "left" truncates the text on the left side, "right" truncates the text on the right side, "center" removes text in the center replacing it with '…'.

• <showFixedValueInElementName>: Used within a customization area. This element selects fixed value attributes that contain the long name or other text that the user wants to see displayed as part of the element name in the editor source or target tree.

  For example:

  <showFixedValueInElementName>
     <path>@LongName</path>
     <path>@LongName2</path>
     <path>@Name</path>
  </showFixedValueInElementName>
  

  In the preceding example, the first fixed attribute found on any element in the XSLT Map Editor trees with the name LongName, LongName2, or Name is shown as part of the element tree name.

  The fixed attribute value is shown in parentheses to the right of the actual element name in the tree. This is particularly useful for HL7 schemas where descriptive names are added as fixed attribute values in the schema.