| Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite 11g Release 1 (11.1.1.6.1) Part Number E10224-12 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite 11g Release 1 (11.1.1.6.1) Part Number E10224-12 |
|
|
PDF · Mobi · ePub |
This chapter describes how to use the XSLT Mapper to create, design, and test data transformations between source schema elements and target schema elements in either Oracle BPEL Process Manager or Oracle Mediator. Samples of creating a data transformation are also provided. Version 1.0 of XSLT is supported.
This chapter includes the following sections:
For information on invoking the XSLT Mapper from Oracle BPEL Process Manager, see Section 40.2.1, "How to Create an XSL Map File in Oracle BPEL Process Manager." For information on invoking the XSLT Mapper from Oracle Mediator, see Section 40.2.3, "How to Create an XSL Map File in Oracle Mediator."
You use the XSLT Mapper to create the contents of a map file. Figure 40-1 shows the layout of the XSLT Mapper.
The Source and the Target schemas are represented as trees and the nodes in the trees are represented using a variety of icons. The displayed icon reflects the schema or property of the node. For example:
An XSD attribute is denoted with an icon that is different from an XSD element.
An optional element is represented with an icon that is different from a mandatory element.
A repeating element is represented with an icon that is different from a nonrepeating element, and so on.
The various properties of the element and attribute are displayed in the Property Inspector in the lower right of the XSLT Mapper when the element or attribute is selected (for example, type, cardinality, and so on). The Component Palette in the upper right of Figure 40-1 is the container for all functions provided by the XSLT Mapper. The XSLT Mapper is the actual drawing area for dropping functions and connecting them to source and target nodes.
When an XSLT map is first created, the target tree shows the element and attribute structure of the target XSD. An XSLT map is created by inserting XSLT constructs and XPath expressions into the target tree at appropriate positions. When executed, the XSLT map generates the appropriate elements and attributes in the target XSD.
Editing can be done in design view or source view. When a map is first created, you are in design view. Design view provides a graphical display and enables editing of the map. To see the text representation of the XSLT being created, switch to source view. To switch views, click the Source or Design tabs at the bottom of the XSLT Mapper.
While in design view, the following pages from the Component Palette can be used:
General: Commonly used XPath functions and XSLT constructs.
Advanced: More advanced XPath functions such as database and cross-reference functions.
User Defined: User-defined functions and templates. This page is visible only when the user has templates in their XSL or user-defined external functions defined through the preferences pages.
All Pages: Provides a view of all functions in one page.
My Components: Contains user favorites and recently-used functions. To add a function to your favorites, right-click the function in the Component Palette and select Add to Favorites.
Note:
The following functions are only available with Oracle Mediator, and not Oracle BPEL Process Manager, in the XSLT Mapper.
getComponentInstanceID()
getComponentName()
getCompositeInstanceID()
getCompositeName()
getECID()
getHeader(xpath as string, namespaces as string)
getProperty(propertyName as string)
setCompositeInstanceTitle(titleElement)
setProperty(propertyName as string, value as string)
For Oracle BPEL Process Manager, you can use these functions in an assign activity.
While in source view, the XML and the http://www.w3.org/1999/XSL/Transform pages can be used.
The XSLT Mapper provides three separate context sensitive menus:
The source panel
The target panel
The center panel
Right-click each of the three separate panels to see what the context menus look like.
By default, design view shows all defined prefixes for all nodes in the source and target trees. You can elect not to display prefixes by selecting Hide Prefixes from the context menu in the center panel of the design view. After prefixes are hidden, select Show Prefixes to display them again.
It is important to understand how design view representation of the map relates to the generated XSLT in source view. This section provides a brief example.
After creating an initial map, the XSLT Mapper displays a graphical representation of the source and target schemas, as shown in Figure 40-2.
At this point, no target fields are mapped. Switching to source view displays an empty XSLT map. XSLT statements are built graphically in design view, and XSLT text is then generated. For example, design view mapping is shown in Figure 40-3.
The design view results in the generation of the following XSLT statements in source view:
The OrderDate attribute from the source tree is linked with a line to the InvoiceDate attribute in the target tree in Figure 40-3. This results in a value-of statement in the XSLT, as shown in Example 40-1.
The First and Last name fields from the source tree in Figure 40-3 are concatenated using an XPath concat function. The result is linked to the Name field in the target tree. This results in the XSLT statement shown in Example 40-2:
Note the inserted XSLT for-each construct in the target tree in Figure 40-3. For each HighPriorityItems/Item element in the source tree, a ShippedItems/Item element is created in the target tree and ProductName and Quantity are copied for each. The XSLT syntax shown in Example 40-3 is generated:
Example 40-3 for-each Construct
<xsl:for-each
select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
<Item>
<ProductName>
<xsl:value-of select="ProductName"/>
</ProductName>
<Quantity>
<xsl:value-of select="Quantity"/>
</Quantity>
</Item>
</xsl:for-each>
The line linking Item in the source tree to the for-each construct in the target tree in Figure 40-3 determines the XPath expression used in the for-each select attribute. In general, XSLT constructs have a select or test attribute that is populated by an XPath statement typically referencing a source tree element.
The XPath expressions in the value-of statements beneath the for-each construct are relative to the XPath referenced in the for-each. In general, the XSLT Mapper creates relative paths within for-each statements.
If you must create an absolute path within a for-each construct, you must do this within source view. When switching back to design view, it is remembered that the path is absolute and the XSLT Mapper does not modify it.
Note:
In Example 40-3, the fields ProductName and Quantity are required fields in both the source and target. If these fields are optional in the source and target, it is a good practice to insert an xsl:if statement around these mappings to test for the existence of the source node. If this is not done, and the source node does not exist in the input document, an empty node is created in the target document. For example, if ProductName is optional in both the source and target, then map them as follows:
<xsl:if test="ProductName">
<ProductName>
<xsl:value-of select="ProductName"/>
</ProductName>
</xsl:if>
The entire XSLT map generated for this example is shown in Example 40-4:
Example 40-4 Entire XSLT Map
<xsl:template match="/">
<tns1:Invoice>
<xsl:attribute name="InvoiceDate">
<xsl:value-of select="/ns0:PurchaseOrder/@OrderDate"/>
</xsl:attribute>
<ShippedTo>
<Name>
<xsl:value-of select="concat
(/ns0:PurchaseOrder/ShipTo/Name/First,/ns0:PurchaseOrder/ShipTo/Name/Last)"/>
</Name>
</ShippedTo>
<ShippedItems>
<xsl:for-each select="/ns0:PurchaseOrder/Items/HighPriorityItems/Item">
<Item>
<ProductName>
<xsl:value-of select="ProductName"/>
</ProductName>
<Quantity>
<xsl:value-of select="Quantity"/>
</Quantity>
</Item>
</xsl:for-each>
</ShippedItems>
</tns1:Invoice>
</xsl:template>
Subsequent sections of this chapter describe how to link source and target elements, add XSLT constructs, and create XPath expressions in design view.
A node in the target tree can be linked only once (that is, you cannot have two links connecting a node in the target tree).
An incomplete function and expression does not result in an XPath expression in source view. If you switch from design view to source view with one or more incomplete expressions, the Mapper Messages window displays warning messages.
When you map duplicate elements in the XSLT Mapper, the style sheet becomes invalid and you cannot work in the Design view. The Log window shows the error messages when you map an element with a duplicate name. Example 40-5 provides details.
Example 40-5 Duplicate Name Error Messages
Error: This Node is Already Mapped : "/ns0:rulebase/for-each/ns0:if/ns0:atom/ns0:rel" Error: This Node is Already Mapped : "/ns0:rulebase/for-each/ns0:if/ns0:atom/choice_1/ns0:ind" Error: This Node is Already Mapped : "/ns0:rulebase/for-each/ns0:if/ns0:atom/choice_1/ns0:var"
Duplicate nodes can be created in design view by surrounding each duplicate node with a for-each statement that executes once.
Transformations are performed in an XSL map file in which you map source schema elements to target schema elements. This section describes methods for creating the XSL map file.
Note:
You can also create an XSL map file from an XSL style sheet. Click New > SOA Tier > Transformations > XSL Map From XSL Stylesheet from the File main menu in Oracle JDeveloper.
A transform activity enables you to create a transformation using the XSLT Mapper 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:
From the Component Palette, drag a transform activity into your BPEL process diagram. Figure 40-4 provides an example.
Double-click the transform activity.
The Transform dialog shown in Figure 40-5 appears.
Specify the following information:
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.
Add target variables to which to map elements.
Add the target part of the variable (for example, a payload schema consisting of an invoice) to which to map.
In the Mapper File field, specify a map file name or accept the default name. The map file is the file in which you create your mappings using the XSLT Mapper.
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 Mapper appears.
Go to Section 40.1, "Introduction to the XSLT Mapper" for an overview of using the XSLT Mapper.
Note:
If you select a file with a.xslt extension such as xform.xslt, it opens the XSLT Mapper to create an XSL file named xform.xslt.xsl, even though your intension 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.
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:
In Oracle JDeveloper, select the application project in which you want to create the new XSL map.
Import the po.xsd and invoice.xsd files into the project (for example, in the Structure window of Oracle JDeveloper, right-click Schemas and select Import Schemas).
Right-click the selected project and select New.
The New Gallery dialog appears.
In the Categories tree, expand SOA Tier and select Transformations.
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).
Enter a name for the XSL map file in the File Name field.
Select the root element for the source and target trees. In the example in Figure 40-6, the PurchaseOrder element is selected for the source root element and the Invoice element is selected for the target root element.
Click OK.
A new XSL map is created, as shown in Figure 40-7.
Save and close the file now or begin to design your transformation. Information on using the XSLT Mapper is provided in Section 40.1, "Introduction to the XSLT Mapper."
From the Component Palette, drag a transform activity into your BPEL process.
Double-click the transform activity.
Specify the following information:
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.
Add target variables to which to map elements.
Add the target part of the variable (for example, a payload schema consisting of an invoice) to which to map.
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.
Click Open.
Click OK.
The XSLT Mapper displays your XSL map file.
Go to Section 40.1, "Introduction to the XSLT Mapper" for an overview of using the XSLT Mapper.
The XSLT Mapper 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 Mapper.
The XSLT Mapper is available from the Application Navigator 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 Mapper 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:
Open the Mediator Editor.
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.
To the right of the Transform Using field shown in Figure 40-8, click the appropriate transformation map icon to open the Transformation Map dialog.
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-9 appears.
Figure 40-9 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 timeout 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-10 provides an example.
Choose one of the following options:
Use Existing Mapper File, and then click the Search icon to browse for an existing XSLT Mapper file (or accept the default value).
Create New Mapper 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, the mediator's transformation dialog has a separate panel for each target part. For example, here is a request in which the target has three parts:
Figure 40-11 provides an example.
Figure 40-11 Request Transformation Map Dialog
Click OK.
If you chose Create New Mapper File, the XSLT Mapper opens to enable you to correlate source schema elements to target schema elements.
Go to Section 40.1, "Introduction to the XSLT Mapper" for an overview of using the XSLT Mapper.
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:
Create a transformation mapping of input data to output data in the XSLT Mapper.
Design the application to write the output data to a file using the file adapter.
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.
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.
If you import a SOA archive exported from Oracle Enterprise Manager Fusion Middleware Control into Oracle JDeveloper by selecting File > Import > SOA Archive Into SOA Project, you cannot open any XSL map files because the map headers have been removed.
As a work around, perform the following steps:
Select File > New > SOA Tier > Transformations > XSL Map From XSL Stylesheet, and click OK.
The Create XSL Map File From XSL Stylesheet appears.
In the File Name field, enter a new map name (for this example, Transformation_new.xsl).
In the XSL Stylesheet to Create From field, enter the name of the map file missing the map headers (for this example, Transformation_old.xsl).
For the source and target, enter the correct map source and target schema information to use for recovering the map header.
After successful creation of the new map file, delete the old map file (Transformation_old.xsl).
Rename the new map file with the recovered map header to the old map file name to prevent reference breakage (for this example, rename Transformation_new.xslt to Transformation_old.xsl).
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 target reference may fail to execute with error messages such as Input source like Null or Part not found.
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 a 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.
The following sections describe how to use the XSLT Mapper in Oracle BPEL Process Manager or Oracle Mediator.
You can add additional sources to an existing XSLT map. These sources are defined as global parameters and have schema files defining their structure. Multiple source documents may be required in certain instances depending upon the logic of the map. For instance, to produce an invoice, the map may need access to both a purchase order and a customer data document as input.
XSL has no knowledge of BPEL variables. When you add multiple sources in XSL design time, ensure that you also add these multiple sources in the transform activity of a BPEL process.
To add additional sources:
Right-click the source panel to display the context menu. Figure 40-12 provides details.
Select Add Source.
The Add Source dialog shown in Figure 40-13 appears.
Enter a parameter name for the source (the name can also be qualified by a namespace and prefix).
In the Source Schema section, click Select to select a schema for the new source.
The Type Chooser dialog appears.
Select or import the appropriate schema or WSDL file for the parameter in the same manner as when creating a new XSLT map. For this example, the Customer element from the sample customer.xsd file is selected.
Click OK.
The schema definition appears in the Source Schema section of the Create Source as Parameter dialog.
Click OK.
The selected schema is imported and the parameter appears in the source panel above the main source. The parameter can be expanded as shown in Figure 40-14 to view the structure of the underlying schema.
The parameter can be referenced in XPath expressions by prefacing it with a $. For example, a parameter named CUST appears as $CUST in an XPath expression. Nodes under the parameter can also be referenced (for example, $CUST/customer/Header/customerid).
To copy an attribute or leaf-element in the source to an attribute or leaf-element in the target, drag the source to the target. For example, copy the element PurchaseOrder/ID to Invoice/ID and the attribute PurchaseOrder/OrderDate to Invoice/InvoiceDate, as shown in Figure 40-15.
Perform the following steps to set a constant value.
To set constant values:
Select a node in the target tree.
Invoke the context menu by right-clicking the mouse.
Select the Set Text menu option.
A menu provides the following selections:
<Empty>: Enables you to create an empty node.
Enter Text: Enables you to enter text.
Select Enter Text.
The Set Text dialog appears.
In the Set Text dialog, enter text (for example, Discount Applied, as shown in Figure 40-16).
Click OK to save the text.
A T icon is displayed next to the node that has text associated with it. The beginning of the text that is entered is shown next to the node name.
To modify the text associated with the node, right-click the node and select Edit Text to invoke the Set Text dialog again.
Edit the contents and click OK.
For more information about the fields, see the online Help for the Set Text dialog.
To remove the text associated with the node, right-click the node and select Remove Text.
In addition to the standard XPath 1.0 functions, the XSLT Mapper provides many prebuilt extension functions and can support user-defined functions and named templates. The extension functions are prefixed with oraext or orcl and mimic XPath 2.0 functions.
Perform the following steps to view function definitions and use a function.
To add functions:
From the Component Palette, select a category of functions (for example, String Functions).
Right-click an individual function (for example, lower-case).
Select Help. A dialog with a description of the function appears, as shown in Figure 40-17. You can also click a link at the bottom to access this function's description at the World Wide Web Consortium at www.w3.org.
Drag a function from the Component Palette to the center panel of the XSLT Mapper. You can then connect the source parameters from the source tree to the function and the output of the function to a node in the target tree. For the following example, drag the concat function from the String section of the Component Palette to the center panel.
Concatenate PurchaseOrder/ShipTo/Name/First and PurchaseOrder/ShipTo/Name/Last. Place the result in Invoice/ShippedTo/Name by dragging threads from the first and last names and dropping them on the input (left) side on the concat function.
Drag a thread from the ShippedTo name and connect it to the output (right) side on the concat function, as shown in Figure 40-18.
To edit the parameters of any function, double-click the function icon to launch the Edit Function dialog. For example, to add a new comma parameter so that the output of the concat function used in the previous example is Last, First, then click Add to add a comma and reorder the parameters to get this output. Figure 40-19 provides details.
For more information about how to add, remove, and reorder function parameters, see the online Help for the Edit Function dialog.
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:
Drag the left-trim and right-trim functions into the border area of the concat function.
Chain them as shown in Figure 40-20 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.
Some complicated mapping logic cannot be represented or achieved by visual mappings. For these situations, named templates are useful. Named templates enable you to share common mapping logic. You can define the common mapping logic as a named template and then use it as often as you want.
You can define named templates in two ways:
Add the template directly to your XSL map in source view.
Add the template to an external file that you include in your XSL map.
The templates you define appear in the User Defined Named Templates list of the User Defined page in the Component Palette. You can use named templates in almost the same way as you use other functions. The only difference is that you cannot link the output of a named template to a function or another named template; you can only link its output to a target node in the target tree.
To create named templates, you must be familiar with the XSLT language. See any XSLT book or visit the following URL for details about writing named templates:
http://www.w3.org/TR/xslt
For more information about including templates defined in external files, see Section 40.3.6.7, "Including External Templates with xsl:include."
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:
Code and build your functions.
The XSLT Mapper 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. Example 40-6 provides the text for these functions. 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
Example 40-6 XSLT Mapper Extension Functions
// SampleExtensionFunctions.java
package oracle.sample;
/*
This is a sample XSLT Mapper 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));
}
}
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 Section B.7, "Creating User-Defined XPath Extension Functions" for more information on the format of this file. The file shown in Example 40-7 represents the functions toKilograms and replaceChar as they are coded in Example 40-6.
Example 40-7 XML Extension Function Configuration File
<?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:
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.
Go to Tools > Preferences > SOA.
Click the Add button and navigate to and select your JAR file.
Restart Oracle JDeveloper.
New functions appear in the Component Palette under the User Defined page in the User Defined Extension Functions group.
To make the functions available in the runtime environment, Section B.7.3, "How to Deploy User-Defined Functions to Runtime" for details.
To use an XPath expression in a transformation mapping, select the Advanced page and then the Advanced Function group from the Component Palette and drag xpath-expression from the list into the XSLT Mapper. This is shown in Figure 40-21.
When you double-click the icon, the Edit XPath Expression dialog appears, as shown in Figure 40-22. You can press Ctrl+Space to invoke the XPath Building Assistant.
Figure 40-22 Edit XPath Expression Dialog
Figure 40-23 shows the XPath Building Assistant.
Figure 40-23 The XPath Building Assistant
For more information about using the XPath Building Assistant, see the online Help for the Edit XPath Expression dialog and Section B.6, "Building XPath Expressions in Oracle JDeveloper."
While mapping complex schemas, it is essential to be able to add XSLT constructs. For instance, you may need to create a node in the target when a particular condition exists; this requires the use of an xsl:if statement or an xsl:choose statement. You may also need to loop over a node-set in the source such as a list of items in a sales order and create nodes in the target XML for each item in the sales order; this requires the use of an xsl:for-each statement. The XSLT Mapper provides XSLT constructs for performing these and other tasks.
There are two ways to add XSLT constructs such as for-each, if, or choose to the target XSLT tree:
To add XSLT constructs from the Component Palette:
Select the General page and open the XSLT Constructs group. Figure 40-24 provides details.
Figure 40-24 XSLT Constructs Available Through the Component Palette
Drag an XSLT construct from the group onto a node in the target tree. If the XSLT construct can be applied to the node, it is inserted in the target tree. The when and otherwise constructs must be applied to a previously-inserted choose node.
To add XSLT constructs through the context menu on the target tree:
Right-click the element in the target tree where you want to insert an XSLT construct. A context menu is displayed. Figure 40-25 provides details.
Figure 40-25 XSLT Constructs in Available Through the Context Menu
Select Add XSL Node and then the XSLT construct you want to insert.
The XSLT construct is inserted. In most cases, an error icon initially appears next to the construct. This indicates that the construct requires an XPath expression to be defined for it.
In the case of the for-each construct, for example, an XPath expression defines the node set over which the for-each statement loops. In the case of the if construct, the XPath expression defines a boolean expression that is evaluated to determine if the contents of the if construct are executed.
The XPath expression can be created in the same manner as mapping elements and attributes in the target tree. The following methods create an underlying XPath expression in the XSLT. You can perform all of these methods on XSLT constructs in the target tree to set their XPath expressions:
Creating a simple copy by linking nodes
Adding functions
Adding XPath expressions
The following sections describe specific steps for inserting each supported XSLT construct.
In Figure 40-26, HQAccount and BranchAccount are part of a choice in the PurchaseOrder schema; only one of them exists in an actual instance. To illustrate conditional mapping, copy PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/AccountNumber, only if it exists.
To use conditional processing with xsl:if:
In the target tree, select Invoice/BilledToAccount/AccountNumber and right-click to invoke the context sensitive menu.
Select Add XSL Node > if and connect PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/if.
Connect PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/if/AccountNumber.
Figure 40-26 shows the results.
Figure 40-26 Conditional Processing with xsl:if
When mapping an optional source node to an optional target node, it is important to surround the mapping with an xsl:if statement that tests for the existence of the source node. If this is not done and the source node does not exist in the input document, an empty node is created in the target document. For example, note the mapping shown in Example 40-8:
Example 40-8 Statement Without xsl:If
<ProductName> <xsl:value-of select="ProductName"/> </ProductName>
If the ProductName field is optional in both the source and target and the element does not exist in the source document, then an empty ProductName element is created in the target document. To avoid this situation, add an if statement to test for the existence of the source node before the target node is created, as shown in Example 40-9:
In this same example, you can copy PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/AccountNumber, if it exists. Otherwise, copy PurchaseOrder/BranchAccount to Invoice/BilledToAccount/AccountNumber.
To use conditional processing with xsl:choose:
In the target tree, select Invoice/BilledToAccount/AccountNumber and right-click to invoke the context sensitive menu.
Select Add XSL Node > choose from the menu.
Connect PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/choose/when to define the condition.
Connect PurchaseOrder/HQAccount/AccountNumber to Invoice/BilledToAccount/choose/when/AccountNumber.
In the target tree, select XSL Add Node > choose and right-click to invoke the context sensitive menu.
Select Add XSL node > otherwise from the menu.
Connect PurchaseOrder/BranchAccount/AccountNumber to Invoice/BilledToAccount/choose/otherwise/AccountNumber.
Figure 40-27 shows the results.
Figure 40-27 Conditional Processing with xsl:choose
The XSLT Mapper enables you to create loops with the xsl:for-each command. For example, copy PurchaseOrder/Items/HighPriorityItems/Item to Invoice/ShippedItems/Item.
To create loops with xsl:for-each:
In the target tree, select Invoice/ShippedItems/Item and right-click to invoke the context sensitive menu.
Select Add XSL Node > for-each and connect PurchaseOrder/Items/HighPriorityItems/Item to Invoice/ShippedItems/for-each to define the iteration.
Connect PurchaseOrder/Items/HighPriorityItems/Item/ProductName to Invoice/ShippedItems/for-each/Item/ProductName.
Connect PurchaseOrder/Items/HighPriorityItems/Item/Quantity to Invoice/ShippedItems/for-each/Item/Quantity.
Connect PurchaseOrder/Items/HighPriorityItems/Item/USPrice to Invoice/ShippedItems/for-each/Item/PriceCharged.
Figure 40-28 shows the results.
Figure 40-28 Creating Loops with xsl:for-each
Notes:
Executing an auto map automatically inserts xsl:for-each. To see the auto map in use, drag PurchaseOrder/Items/LowPriorityItems to Invoice/UnShippedItems; for-each is automatically created.
Ensure that your design does not include infinite loops. These loops result in errors similar to the following displaying during deployment and invocation of your application.
ORAMED-04001: . . . oracle.tip.mediator.service.BaseActionHandler requestProcess SEVERE: failed reference BPELProcess1.bpelprocess1_client operation = process
You can create additional loops by cloning an existing xsl:for-each. For example, copy all LowPriorityItems to ShippedItems, in addition to HighPriorityItems.
To clone xsl:for-each:
Under Invoice/ShippedItems, select for-each.
Right-click and select Add XSL Node > Clone 'for-each'.
This inserts a copy of the for-each node beneath the original for-each.
Drag PurchaseOrder/Items/LowPriorityItems/Item to the copied for-each to define the iteration.
Connect PurchaseOrder/Items/LowPriorityItems/Item/ProductName to Item/ProductName in the copied for-each.
Connect PurchaseOrder/Items/LowPriorityItems/Item/Quantity to Item/Quantity in the copied for-each.
Connect PurchaseOrder/Items/LowPriorityItems/Item/USPrice to Item/PriceCharged in the copied for-each.
The XSLT Mapper enables you to add xsl:sort statements to xsl:for-each commands.
To add an xsl:sort statement:
Right-click a for-each statement in the target tree.
A context menu appears.
Select Add XSL Node > sort. The Sort Edit Dialog is displayed, as shown in Figure 40-29.
Select options to add to the sort statement as needed. See the online Help for information on options.
Click OK. The sort statement is added following the for-each.
To set the field on which to sort, drag the necessary sort field node in the source tree to the sort node in the target tree. This creates a simple link and sets the XPath expression for the select attribute on the xsl:sort.
To add additional sort statements, right-click the for-each to add another sort or right-click an existing sort node to insert a new sort statement before the selected sort node.
To edit a sort node, double-click the sort node or right-click and select Edit Sort from the context menu. This invokes the Sort Edit Dialog and enables you to change the sort options.
You may need to use the XSLT copy-of construct to copy a node, along with any child nodes, from the source to the target tree. This is typically done when working with anyType or any element nodes. The anyType and any element and attribute nodes cannot be mapped directly. Use copy-of or element and type substitution.
To copy nodes with xsl:copy-of:
Select the node in the target tree to be created by the copy-of command.
Right-click the node and select Add XSL Node > copy-of.
If the node is not an any element node, a dialog appears requesting you to either replace the selected node or replace the children of the selected node.
Select the correct option for your application and click OK.
If you select Replace the selected node with the copy-of, a processing directive is created immediately following the copy-of in the XSL indicating which node is replaced by the copy-of. Without the processing directive in the XSL, the conversion back to design view is interpreted incorrectly. For this reason, do not remove or edit this processing instruction while in source view.
Set the source node for the copy-of by dragging and dropping from the source tree or by creating an XPath expression.
Note:
Always create the copy-of command in design view so that the correct processing directive can be created in the XSLT Mapper to indicate the correct placement of the copy-of command in the target tree.
WARNING:
The XSLT Mapper does not currently validate the mapping of data performed through use of the copy-of command. You must ensure that copy-of is used to correctly map elements to the target tree so that the target XML document contains valid data. You can test the validity by using the test tool.
You can reuse templates that are defined in external XSL files by including them in the current map with an include statement.
To include external templates with xsl:include:
In the target tree, select and right-click the root node.
From the menu, select Add Include File.
A dialog prompts you for the include file name.
Select the file and click OK.
The file is copied to the same project directory as the existing map file. A relative path name is created for it and the include statement instruction is inserted in the target tree.
The include file can only contain named template definitions. These are parsed and available to you in design view of the Component Palette under the User Defined Named Templates category in the User Defined page.
Note:
An oramds:// shared location cannot be referenced for a user-defined named template include file.
Mapping nonleaf nodes starts the auto map feature. The system automatically tries to link all relevant nodes under the selected source and target. Try the auto map feature by mapping PurchaseOrder/ShipTo/Address to Invoice/ShippedTo/Address. All nodes under Address are automatically mapped, as shown in Figure 40-30.
The behavior of the auto map can be tuned by altering the settings in Oracle JDeveloper preferences or by right-clicking the XSLT Mapper and selecting Auto Map Preferences. This displays the dialog shown in Figure 40-31.
This dialog enables you to customize your auto mapping as follows:
Invoke the automatic mapping feature, which attempts to automatically link all relevant nodes under the selected source and target. When disabled, you must individually map relevant nodes.
Display and review all potential source-to-target mappings detected by the XSLT Mapper, and then confirm to create them.
Be prompted to customize the auto map preferences before the auto map is invoked.
Select the Basic or Advanced method for automatically mapping source and target nodes. This action enables you to customize how the XSLT Mapper attempts to automatically link all relevant nodes under the selected source and target.
Manage your dictionaries. The XSLT Mapper uses the rules defined in a dictionary when attempting to automatically map source and target elements.
For more information on the fields, see the online Help for the Auto Map Preferences dialog.
Follow these instructions to see potential source mapping candidates for a target node.
To automatically map nodes:
Right-click the target node and select Show Matches.
Click OK in the Auto Map Preferences dialog.
The Auto Map dialog appears, as shown in Figure 40-32.
For more information on the fields, see the online Help for the Auto Map dialog.
When the Confirm Auto Map Results checkbox shown in Figure 40-31 is selected, a confirmation dialog appears. If matches are found, the potential source-to-target mappings detected by the XSLT Mapper are displayed, as shown in Figure 40-33. The dialog enables you to filter one or more mappings.
For more information about the fields, see the online Help for the Auto Map dialog.
The automatic mapping algorithm depends on existing maps between source and target nodes. When maps exist between source and target nodes before executing automatic mapping, these existing maps are used to define valid synonyms that are used by the algorithm.
For example, assume you have a simple source and target tree, each with two elements called test1 and test2, as shown in Figure 40-34.
Figure 40-34 Source and Target Tree with Two Elements
If no nodes are mapped, the automatic mapping algorithm does not match the names test1 and test2. However, if mapping exists between the test1 and test2 nodes, the algorithm predefines the names test1 and test2 as synonyms for any additional mapping.
In the example in Figure 40-34, if you drag the exampleElement from the source to the target, the automatic mapping algorithm maps the test1 node in the source to the test2 node in the target because your map previously linked those two names. This results in the map shown in Figure 40-35:
Figure 40-35 Results of Dragging exampleElement
You can view a list of target nodes that are currently unmapped to source nodes.
To view unmapped target nodes:
In the XSLT Mapper, right-click in the center panel and select Completion Status.
This dialog provides statistics at the bottom about the number of unmapped target nodes. This dialog enables you to identify and correct any unmapped nodes before you test your transformation mapping logic on the Test XSL Map dialog.
In the list, select a target node. The node is highlighted. A checkmark indicates that the target node is required to be mapped. If not required, the checkbox is empty.
Note:
Nodes are marked as required in the Completion Status dialog based on the XSD definition for a node. It is possible that a node marked as required is not actually required for a specific mapping if a parent node of the required node is optional and is not part of the XSL mapping.
Figure 40-36 provides an example of the Completion Status dialog.
A dictionary is an XML file used by automatic mapping. It contains synonyms for field names. For instance, assume that the element QtyOrdered should map to the element Quantity. The element names QtyOrdered and Quantity are then synonyms for one another. If this mapping commonly appears from one map to another, it is a good practice to save these synonyms in a dictionary file. After being saved, they can be reapplied to another map using automatic mapping.
A dictionary can be created from any existing XSL map and can contain all mappings that are not automatically generated by the XSLT Mapper for the existing map.
To generate and use dictionaries:
Create an XSL map that contains specific mappings to reuse in other maps.
Go to Tools > Preferences > XSL Maps > Auto Map and note the current automatic mapping settings.
Note:
Because dictionary entries are dependent upon the current automatic mapping settings, you must make a note of those settings for future use. To later reapply a dictionary mapping, it is best to set the automatic mapping preferences to those that were in effect at the time the dictionary was created. Therefore, it is important to note the automatic mapping settings at the time the dictionary is created.
In the XSLT Mapper, right-click the center panel of the XSLT Mapper and select Generate Dictionary.
This prompts you for the dictionary name and the directory in which to place the dictionary.
Check the Open Dictionary checkbox to view the dictionary after it is created. If the dictionary file is empty, this indicates that no fields were mapped that would not have been mapped with the current automatic mapping settings.
To use the dictionary in another map, load the dictionary by selecting Tools > Preferences > XSL Maps > Auto Map.
Click Add below the Dictionaries list.
Browse for and select the dictionary XML file that was previously created from a similar map.
Click OK.
Before leaving the automatic mapping preferences, modify the mapping settings to match those used when creating the dictionary.
Click OK.
Perform an automatic mapping of whichever portion of the new map corresponds to the saved dictionary mappings.
For more information about automatic mapping, see Section 40.3.7, "How to Automatically Map Nodes."
You cannot create a dictionary for mappings in which functions are used. In these cases, the dictionary XML instructions are missing for the elements that were automatically mapped or which had an XPath function mapping. For example, assume you use string functions to map XSDs during design time. If you right-click the center panel of the XSLT Mapper and select Generate Dictionary, the dictionary is created, but instructions are not created in all places in which the string functions were used during mapping.
You can create a dictionary for simple type mappings.
You can create map parameters and variables. You create map parameters in the source tree and map variables in the target tree.
Note the following issues:
Parameters are created in the source tree, are global, and can be used anywhere in the mappings.
Variables are created in the target tree, and are either global or local. The location in which they are defined in the target tree determines if they are global or local.
Global variables are defined immediately beneath the <target> node and immediately above the actual target schema (for example, POAcknowledge). Right-click the <target> node to create a global variable.
Local variables are defined on a specific node beneath the actual target schema (for example, subnode name on schema POAcknowledge). Local variables can have the same name provided they are in different scopes. Local variables can only be used in their scopes, while global variables can be used anywhere in the mappings.
To create a map parameter:
In the source tree root, right-click and select Add Parameter.
The Add Parameter dialog shown in Figure 40-37 appears.
Specify details for the parameter. For this example, a parameter named discount with a numeric default value of 0.0 is specified.
Click OK.
To create a map variable:
In the target tree, right-click the target tree root or any node and select Add Variable.
The Add Variable dialog shown in Figure 40-38 appears.
Specify details.
Since variables appear in the target tree, their XPath expression can be set in the same manner as other XSLT constructs in the target tree after inserting the variable. Therefore, the only required information in this dialog is a name for the variable. To set content for the variable, you must enter it through this dialog. Content is handled differently from the XSLT select attribute on the variable.
Click OK.
The variable is added to the target tree at the position selected. The variable initially has a warning icon beside it. This indicates that its select XPath statement is undefined. Define the XPath through linking a source node, creating a function, or defining an explicit XPath expression as done for other target elements and XSLT constructs.
You can search source and target nodes. For example, you can search in a source node named invoice for all occurrences of the subnode named price.
To search source and target nodes:
Right-click a source or target node and select Find from the context menu.
The Find Node dialog shown in Figure 40-39 is displayed.
Enter a keyword for which to search.
Specify additional details, as necessary. For example:
Select Search Annotations if you want annotations text to also be searched.
Specify the scope of the search. You can search the entire source or target tree, search starting from a selected position, or search within a selected subtree.
The first match found is highlighted, and the Find dialog closes. If no matches are found, a message displays on-screen.
Select the F3 key to find the next match in the direction specified. To search in the opposite direction, select the Shift and F3 keys.
Note:
You cannot search on functions or text values set with the Set Text option.
There are five options for controlling the generation of empty elements in the target XSL:
Do not generate unmapped nodes (default option).
Generate empty nodes for all unmapped target nodes.
Generate empty nodes for all required, unmapped target nodes.
Generate empty nodes for all nillable, unmapped target nodes.
Generate empty nodes for all required or nillable, unmapped target nodes.
Set these options as follows:
At the global level:
Select Tools > Preferences > XSL Maps. The global setting applies only when a map is created.
At the map level:
Select XSL Generation Options from the map context menu. Each map can then be set independently by setting the options at the map level.
Empty elements are then generated for the selected unmapped nodes. If the unmapped node is nillable, it is generated with xsi:nil="true".
When the XSLT Mapper encounters any elements in the XSLT document that cannot be found in the source or target schema, it cannot process them and displays an Invalid Source Node Path error. XSL map generation fails. You can create and import a file that directs the XSLT Mapper to ignore and preserve these specific elements during XSLT parsing by selecting Preferences > XSL Maps in the Tools main menu of Oracle JDeveloper.
For example, preprocessing may create elements named myElement and myOtherElementWithNS that you want the XSLT Mapper to ignore when it creates the graphical representation of the XSLT document. You create and import a file with these elements to ignore that includes the syntax shown in Example 40-10.
Example 40-10 File with Elements to Ignore
<elements-to-ignore> <element name="myElement"/> <element name="myOtherElementWithNS" namespace="NS"/> </elements-to-ignore>
You must restart Oracle JDeveloper after importing the file.
You can replace the map source or target schema that currently displays in the XSLT Mapper.
To replace a schema in the XSLT Mapper:
In either the source or target panel, right-click and select Replace Schema.
This opens the Type Chooser dialog shown in Figure 40-40, which enables you to select the new source or target schema to use.
Select the replacement schema and click OK.
You are then prompted to select to clear expressions in the current map.
Select Yes or No. If expressions are not cleared, you may need to correct the map in source view before entering design view again.
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:
In the source or target tree, right-click the element for which substitution applies.
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-41 appears.
Figure 40-41 Substitute Element or Type Dialog
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.
Select the type or element to substitute.
Click OK.
The element or type is substituted for the originally selected element. This selection displays differently depending upon whether this is a type or element substitution and this is the source or target tree.
If the element is in the target tree and type substitution is selected:
The xsi:type attribute is added beneath the original element, as shown in Figure 40-42. It is disabled in design view and set to the type value that was selected. An S icon displays to indicate the node was substituted. You can map to any structural elements in the substituted type.
Figure 40-42 If the Element is in the Target Tree and Type Substitution is Selected
If the element is in the source tree and type substitution is selected:
The xsi:type attribute is added beneath the original element, as shown in Figure 40-43. An S icon is displayed to indicate the node was substituted. You can map from any structural elements in the substituted type.
Figure 40-43 If the Element is in the Source Tree and Type Substitution is Selected
If the element is in the target tree and element substitution is selected:
The original element is replaced in the tree with the substituted element, as shown in Figure 40-44. A comment indicates that the original element name was added and an S icon displays to indicate the node was substituted. You may map to any structural elements in the substituted element.
Figure 40-44 If the Element is in the Target Tree and Element Substitution is Selected
If the element is in the source tree and element substitution is selected:
The original element and its possible replacement both display in the source tree under a new node named <Element Substitution>, as shown in Figure 40-45. An S icon displays to indicate that the node was added. This feature enables you to build a map where the source object can contain either the original node or a substituted node. You can map to any structural elements in the substituted element.
Figure 40-45 If the Element is in the Source Tree and Element Substitution is Selected
Note:
Unlike element substitution, only one type substitution at a time can display in the source tree. This does not prevent you from writing a map that allows the source to sometimes have the original type or the substituted type; you can switch to another type at any time. XPath expressions that map to nodes that may not be visible in the source tree at any given time are still retained.
To remove a substituted node, right-click any node with an S icon and select Remove Substitution from the context menu.
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.
To hide the icons, right-click and select Hide Substitution Node Icons.
The XSLT Mapper provides a test tool to test the style sheet or map. The test tool can be invoked by selecting the Test menu item, as shown in Figure 40-47.
The Test XSL Map dialog shown in Figure 40-48 enables you to test the transformation mapping logic you designed with the XSLT Mapper. 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.
To test the transformation mapping logic:
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.
Select the Generate Source XML File checkbox to create a sample XML file based on the map source XSD schema.
Select the Show Source XML File checkbox 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.
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 checkbox to generate a file.
If the Parameters Without Schema table appears, you can specify a value by selecting the Specify Value checkbox and making appropriate edits to the Type and Value columns.
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.
Select the Show Target XML File checkbox to display the target XML file for the test. The target XML file displays in an Oracle JDeveloper XML editor.
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.
Click OK.
The test results shown in Figure 40-49 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.
Note:
If the XSL map file contains domain value map (DVM) and cross reference (XREF) XPath functions, it cannot be tested. These functions cannot be executed during design time; they can only be executed during runtime.
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.
In the center panel, right-click and select Generate Report.
The Generate Report dialog appears, as shown in Figure 40-50. If the map has defined parameters, the appropriate parameter tables appear.
For more information about the fields, see the online Help for the Generate Report dialog.
If you attempt to generate a report and receive an out-of-memory error, increase the heap size of the JVM as follows.
To increase the JVM heap size:
Open the JDev_Oracle_Home\jdev\bin\jdev.conf file.
Go to the following section:
# Set the maximum heap to 512M # AddVMOption -Xmx512M
Increase the size of the heap as follows (for example, to 1024):
AddVMOption -Xmx1024M
In addition, you can also unselect the Open Report option on the Generate Report dialog before generating the report.
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.
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.
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).
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.
This sample demonstrates the following features of the XSLT mapper:
Element and type substitution
Multiple sources use
New XSL constructs xsl:sort and xsl:copy-of
New variable use
In addition to this sample, Oracle provides other transformation samples that are available for download from the Oracle Technology Network (OTN). These samples are described in Table 40-2. To access these samples, see the Oracle SOA Suite samples.
Table 40-2 Transformation Samples
| Sample | Description |
|---|---|
|
mapper-101-basic-mapping |
Demonstrates creation and basic editing of an XSLT map. |
|
mapper-102-import-and-test |
Demonstrates the following XSL mapper features:
|
|
mapper-104-auto-mapping |
Demonstrates the automatic mapping feature of the XSLT Mapper. |
|
mapper-105-multiple-sources |
Demonstrates the use of multiple sources. The following topics are also covered in the process of creating the map sample.
|
|
mapper-107-extension-functions |
Demonstrates the use of user-defined extension functions. |
|
mapper-108-substitution-mapping |
Demonstrates the use of element substitution when:
|
|
mapper-109-whats-new |
Demonstrates new 11g features in the XSLT Mapper. These features are described in Section 40.5.1, "Opening the Application" through Section 40.5.7, "Testing the Map." |
You first create the sample application. When complete, the application matches the one provided in the WhatsNewApplication directory described in Step 1.
Download sample mapper-109-whats-new from OTN.
The sample includes the following files and directories:
artifacts/schemas/po.xsd and Attachment.xsd: source schemas
artifacts/schemas/invoice.xsd and ReasonCodes.xsd: target schemas
artifacts/application: starting application for this sample
WhatsNewApplication directory: completed sample map
Copy the artifacts/application folder to a separate work area.
Start Oracle JDeveloper.
Click WhatsNewApplication.jws in the artifacts/application folder you copied to a separate area.
If prompted to migrate files, click Yes.
The WhatsNewApplication displays in the Application Navigator.
You now create a new XSLT map with two sources that is invoked from the BPEL process included in the WhatsNewApplication application.
In the Application Navigator, double-click the ProcessPO2Invoice.bpel BPEL process.
From the Oracle Extensions section of the Component Palette, drag a Transform activity below the SetDiscontinuedProducts assign activity.
Double-click the Transform activity.
In the Name field of the General tab, enter Po2Invoice.
In the Transformation tab, perform the following steps:
Click the Add icon.
From the Source Variable list, select inputVariable.
From the Source Part list, select payload.
This variable contains the purchase order that is input to the BPEL process.
Click OK.
Click the Add icon a second time and select DiscontinuedList from the Source Variable list. The variable is created in the SetDiscontinuedProducts assign activity before the transformation activity.
Click OK.
From the Target Variable list, select outputVariable. This is the invoice that is returned from the BPEL process.
In the Mapper File field, change the name to xsl/Po2Invoice.
Click the Create Mapping icon to the right of the Mapper Name field to create and open the mapper file.
The XSLT Mapper opens.
From the File menu, select Save All. Your map looks as shown in Figure 40-51. The second source is loaded as a parameter with the name DiscontinuedList:
You now use type and element substitutions to map the purchase order items to the invoice items.
In the target tree, expand the tree so that Invoice/Items/Item is visible. The Item element has an error icon next to it.
Move the mouse over the element to display a tool tip indicating that this element is defined as an abstract type.
To map to the Item element, you must first indicate which type the element takes in the final XML output.
Perform the following steps to indicate which type the element takes:
Right-click the Item element and select Substitute Element or Type.
The Substitute Element or Type dialog appears.
Select ShippedItemType from the list and click OK.
The Item element structure is filled out. The xsi:type attribute sets the type of the Item element in the target XML.
Note:
If you view invoice.xsd, ShippedItemType is derived from the abstract type ItemType, which is the type of the Item element.
Drag PurchaseOrder/Items to Invoice/Items to invoke the automatic mapper to map these nodes. To review automatic mapping functionality, see sample mapper-104-auto-mapping.
When complete, the Item elements in your map now look as shown in Figure 40-52:
Figure 40-52 Item Elements in XSLT Mapper
From the File menu, select Save All to save the map file.
You now use the information in the additional source variable, DiscontinuedList, to eliminate items that have been discontinued. If the product name for an item is in DiscontinuedList, then that item cannot be shipped and is not placed in the final shipped item list.
Add an if statement above the Item node in the target tree by right-clicking the Item node and selecting Add XSL Node > if.
The if statement must test if a discontinued product exists in DiscontinuedList with the name of the current item. The item is added only to the shipped items if it is not in DiscontinuedList. There are many ways to define the test expression for the if statement. One way is described in the following steps.
Define the test expression for the if statement by selecting the following (the method for how variables are set has changed from previous versions of Oracle JDeveloper):
Add a global variable to the target tree by right-clicking the Invoice node and selecting Add Variable.
The Add Variable dialog appears.
In the Local Name field, enter DelimitedList. In the following steps, this variable is set to a string with a delimited list of discontinued product names.
Click OK.
The variable is added with a warning icon next to it.
To set the value of the variable, drag the create-delimited-string function from the String section of the Component Palette to the center panel.
Drag DiscontinuedList/ProductName to the input side of the create-delimited-string function.
Drag the output side of the create-delimited-string function to the new variable named DelimitedList.
Double-click the create-delimited-string function to open the Edit Function dialog.
In the delimiter field, add the pipe ("|") character.
Click OK.
The input source is referenced in XPath expressions with $DiscontinuedList. This source is referenced as an input parameter in XPath expressions.
To set the XPath expression for the if statement, drag the contains function from the String section of the Component Palette to the center panel.
Drag the not function from the Logical Functions section of the Component Palette to the shaded area surrounding the contains function you added in Step 3.
Drag a line from the output side of the contains function to the input side of the not function.
Drag a line from the output side of the not function to the if statement.
Double-click the contains function to open the Edit Function dialog.
Enter values for the inputString and searchString, and click OK.
From the File menu, select Save All to save the map file.
The map file now looks as shown in Figure 40-53.
You now map a substituted shipping contact element in the source to the ShippedTo element in the target.
Expand the PurchaseOrder/CustomerContacts element in the source to see the Contact element.
This element has an error icon next to it.
Place the mouse over this element to display a tool tip indicating that this element is abstract.
In this situation, you must perform an element substitution to map the element.
Right-click the Contact element in the source tree and select Substitute Element or Type.
The Substitute Element or Type dialog is displayed with a list of elements in the substitution group of the abstract element Contact.
Select ShipToContact and click OK.
This is the element that you expect in the input XML. The structure of the ShipToContact element is now displayed in the source tree.
Expand the ShipToContact/InternationalAddress element in the source tree to show the address fields.
Expand the ShippedTo element in the target tree to show the target address fields.
Note the similarity in field names here, indicating that the automatic mapper can be used.
Drag the InternationalAddress element in the source tree to the ShippedTo element in the target tree and use the automatic mapper to help map the address fields below these elements.
Map any remaining elements not matched by the automatic mapper so that this section of the map is as shown in Figure 40-54:
From the File menu, select Save All to save the map file.
Map PurchaseOrder/ID to Invoice/ID.
Expand Invoice/Data to show an any element.
Use the copy-of xsl statement to copy the attachment data from the source to the target any element:
Right-click the Invoice/Data/any element and select Add XSL Node > copy-of.
The copy-of statement is added and the original any element is grayed out. This indicates that it is to be replaced by the nodes selected by the copy-of statement.
To set the copy-of selection, drag the PurchaseOrder/Attachments element in the source tree to the copy-of statement.
Perform the following steps to map the PurchaseOrder/Comment field to the Invoice/Comment field. The Invoice/Comment field is an anyType element.
Right-click the Invoice/Comment field and select Substitute Element or Type.
Select xsd:string from the list of types provided.
Drag the PurchaseOrder/Comment field to the Invoice/Comment field to map the fields.
Add an XSL sort statement to the for-each statement:
Right-click the for-each statement in the target tree and select Add XSL Node > sort.
The Sort Edit dialog appears.
Select sort according to data-type Number.
Select sort order Descending.
Click OK. The sort node is added to the target tree.
Drag PurchaseOrder/Items/Item/Price from the source tree to the sort node in the target tree.
This sets the field on which to sort.
From the File menu, select Save All to save the map file. The map now looks as shown in Figure 40-55:
An XSL map can be tested independently from the BPEL process in Oracle JDeveloper using the XSLT Mapper. XML files can be input for each source input to the map.
Right-click the center panel and select Test.
The Test XSL Map dialog appears after a warning dialog. The warning indicates that you can test the map by creating your own sample input XML. The sample XML generator cannot generate sample data for the source tree substitutions.
A sample input XML file is provided: artifacts/xml/POInput.xml.
Follow these steps to select the sample input file for testing:
Uncheck the Generate Source XML File checkbox.
Click the Browse button for the Source XML File field.
Navigate to select the artifacts/xml/POInput.xml file.
A second sample file has been created with discontinued item data. This file is artifacts/xml/DiscontinuedItems.xml.
Follow these steps to use this file as the second source input.
Uncheck the Generate File checkbox to the left of the DiscontinuedList parameter name in the Parameters With Schema section of the dialog.
Click Browse for the DiscontinuedList parameter and select the artifacts/xml/DiscontinuedItems.xml file.
Click OK on the Test XSL Mapper dialog to run the test.
A PO2Invoice-Target.xml file is generated by the execution of the map. Note the use of xsi:type attributes, the Attachments node created by the copy-of statement, and the ordering of items caused by the sort statement in the PO2Invoice-Target.xml file.
|
 Copyright © 2005, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
