This appendix describes the XPath extension functions for working with cross references and domain value maps in Service Bus. It also describes how to create user-defined XPath extension functions. Oracle provides XPath functions that use the capabilities built into Service Bus and XPath standards for adding new functions.
This appendix includes the following sections:
Using cross references, you can dynamically map values for an entity in one application to the equivalent values in other applications. This is useful for when you update information for an object in one application, and that information needs to be propagated to the same object in other applications. Each application may have its own way of identifying that object.
Cross references are stored in a lookup table, and the cross reference XPath functions let you monitor and manage the data in the table. Use theses functions to add, update, and lookup data in the cross reference mapping tables. A global transaction should be available during these function calls. If the transaction is not available, a new transaction is initiated.
Note:
Most of the cross reference functions take the location and name of the Service Bus cross reference resource as an argument. Service Bus does not support a direct reference to resources in the Oracle Metadata Services (MDS) Repository.
For complete information about cross references, see "Working with Cross References" in Developing SOA Applications with Oracle SOA Suite. For information about cross references in Service Bus, see Mapping Data with Cross-References.
This function looks up all the populated columns for a given cross reference table, cross reference column, and value. It returns a node-set, with each node containing a column name and the corresponding value. For a more detailed explanation of this function, see "About the xref:lookupPopulatedColumns Function" in Developing SOA Applications with Oracle SOA Suite.
Signature
xref:lookupPopulatedColumns(xref-location, column, value, need-exception)
Arguments
Unless otherwise noted, all argument are String values.
xref-location: The full path and name of the cross-reference resource.
column: The name of the reference column.
value: The value corresponding to the reference column.
need-exception: A boolean value indicating whether to throw an exception if the value is not found. When this is set to true, the function throws an exception if the value is not found. Otherwise, it returns an empty value.
At runtime, an exception can occur for the following reasons:
The cross reference table with the given name is not found.
The specified column names are not found.
The specified reference value is empty.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
Example
xref:lookupPopulatedColumns('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', true())
This function looks up a cross reference column for a value that corresponds to a specific value in a reference column. For a more detailed explanation of this function, see "About the xref:lookupXRef Function" in Developing SOA Applications with Oracle SOA Suite.
Signature
xref:lookupXRef(xref-location, ref-column, ref-value, column-name, need-exception)
Arguments
Unless otherwise noted, all argument are String values.
xref-location: The full path and name of the cross-reference resource.
ref-column: The name of the reference column.
ref-value: The value corresponding to the reference column.
column-name: The name of the column in which to look up the value.
need-exception: A boolean value indicating whether to throw an exception if the value is not found. When this is set to true, the function throws an exception if the value is not found. Otherwise, it returns an empty value.
At runtime, an exception can occur for the following reasons:
The cross reference table with the given name is not found.
The specified column names are not found.
The specified reference value is empty.
Multiple values are found.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
Example
xref:lookupXRef('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', false())
This function looks up a cross reference column for multiple values that correspond to a specific value in a reference column. It returns a node-set containing multiple nodes, and each node contains a value. For a more detailed explanation of this function, see "About the xref:lookupXRef1M Function" in Developing SOA Applications with Oracle SOA Suite.
Signature
xref:lookupXRef1M(xref-location, ref-column, ref-value, column-name, need-exception)
Arguments
Unless otherwise noted, all argument are String values.
xref-location: The full path and name of the cross-reference resource.
ref-column: The name of the reference column.
ref-value: The value corresponding to the reference column.
column-name: The name of the column in which to look up the values.
need-exception: A boolean value indicating whether to throw an exception if the values are not found. When this is set to true, the function throws an exception if the values are not found. Otherwise, it returns an empty value.
At runtime, an exception can occur for the following reasons:
The cross reference table with the given name is not found.
The specified column names are not found.
The specified reference value is empty.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
Example
xref:lookupXRef1M('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', true())
This function deletes a value in a cross reference table. The column value passed to the function is deleted from the XREF_DATA table and moved to the XREF_DELETED_DATA table. This function returns true if the deletion is successful. Otherwise, it returns false. If there is only one value left in the row after the deletion, that value is also deleted since there are no cross references remaining.
For a more detailed explanation of this function, see "Deleting a Cross Reference Table Value" in Developing SOA Applications with Oracle SOA Suite.
Signature
xref:markForDelete(xref-location, column, value)
Arguments
Unless otherwise noted, all argument are String values.
xref-location: The full path and name of the cross-reference resource.
column: The name of the column that contains the value to be deleted.
value: The value to be deleted.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
Example
xref:markForDelete('/BookSellers/XRefPublishers', 'HARPER', 'H_1500')
This function populates a column or columns in the cross-reference table with a single value, depending on the mode in which it is run. Use this function to add a new row or to add a value to a column in an existing row. This function returns a string value, which is the value being populated. Unlike the populateXRefRow function, the populateLookupXRefRow function does not throw a unique constraint violation error when records with the same ID are added simultaneously. Instead, it behaves as a lookup and returns the existing source value that caused the error and does not stop the processing flow. Use this function to resolve any concurrency issues that could arise when using the populateXRefRow function.
For a more detailed explanation of this function, see "About the xref:populateLookupXRefRow Function" in Developing SOA Applications with Oracle SOA Suite.
Signature
xref:populateLookupXRefRow(xref-location, ref-column, ref-value, column, value, mode)
Arguments
All argument are String values.
xref-location: The full path and name of the cross-reference resource.
ref-column: The name of the reference column.
ref-value: The value that corresponds to the reference column.
column: The name of the column to be populated.
value: The value to be populated in the above column.
mode: The XREF population mode. This can be ADD or LINK, and must be entered in all uppercase letters. For more information about these modes, see "xref:populateLookupXRefRow Function Results with Different Modes" in Developing SOA Applications with Oracle SOA Suite.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
Example
xref:populateLookupXRefRow('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', 'PEN_2001', 'ADD')
This function populates one or two columns in the cross-reference table with a single value, depending on the mode in which it is run. Use this function to add a new row, or to update or add a value in a column in an existing row. This function returns a string value, which is the value being populated. For a more detailed explanation of this function, see "About the xref:populateXRefRow Function" in Developing SOA Applications with Oracle SOA Suite.
Note:
If you find you have concurrency issues when using this function, you can also use the populateLookupXRefRow function, which should only be used in cases where simultaneous updates are being made that result in unique constraint violations.
Signature
xref:populateXRefRow(xref-location, ref-column, ref-value, column, value, mode)
Arguments
All argument are String values.
xref-location: The full path and name of the cross-reference resource.
ref-column: The name of the reference column.
ref-value: The value that corresponds to the reference column.
column: The name of the column to be populated.
value: The value to be populated in the above column.
mode: The XREF population mode. This can be ADD, LINK, or UPDATE, and must be entered in all uppercase letters. For more information about these modes, see "xref:populateXRefRow Function Modes" in Developing SOA Applications with Oracle SOA Suite.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
Example
xref:populateXRefRow('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', 'PEN_2001', 'ADD'
This function populates a column or columns in the cross-reference table with multiple values, depending on the mode in which it is run. Use this function to add a new row or to add values to a column in an existing row. Two values in one external system can correspond to a single value in another system. In such a scenario, use this function to populate a cross reference column with a value. This function returns a string value, which is the cross reference value being populated.
For a more detailed explanation of this function, see "About the xref:populateXRefRow1M Function" in Developing SOA Applications with Oracle SOA Suite.
Signature
xref:populateXRefRow1M(ref-location, ref-column, ref-value, column, value, mode)
Arguments
All argument are String values.
xref-location: The full path and name of the cross-reference resource.
ref-column: The name of the reference column.
ref-value: The value that corresponds to the reference column.
column: The name of the column to be populated.
value: The value to be populated in the above column.
mode: The XREF population mode. This can be ADD or LINK, and must be entered in all uppercase letters. For more information about these modes, see "xref:populateXRefRow1M Function Results with Different Modes" in Developing SOA Applications with Oracle SOA Suite.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
Example
xref:populateXRefRow1M(/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', 'PEN_2001', 'LINK'
Using domain value maps, you can map the terms used by different domains to describe the same entity, so values used by one domain for specific fields map to the values used by other domains for the same fields. For example, you can map country or state codes between applications. Domain value maps are stored in a lookup table, and the domain value map XPath functions let you look up the data in the table.
For complete information about domain value maps, see "Using Domain Value Map Functions" in Developing SOA Applications with Oracle SOA Suite. For information about cross references in Service Bus, see Mapping Data with Domain Value Maps..
This function returns a string by looking up the value for the target column in a domain value map, where the source column contains the given source value.
Signature
dvm:lookup(dvm-location, src-column, src-value, target-column, default-value)
Arguments
All arguments are String values.
dvm-location: The domain value map URI.
src-column: The source column name.
src-value: The source value (an XPath expression bound to the source document of the XSLT transformation).
target-column: The target column name.
default-value: If the value is not found, this default value is returned.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/dvm
namespace-prefix: dvm
Example
The following example looks for the value in the CityNames table that corresponds to the value "BO" in the CityCodes table. If no matching value is found, the function returns "CouldNotBeFound" instead.
dvm:lookup ('/CityMapsDVM/cityMap','CityCodes','BO','CityNames', 'CouldNotBeFound')
This function returns a string by looking up the value for the target column in a domain value map, where the source column contains the given source value. You can specify a qualifying column and value to help narrow down this lookup. For a more detailed explanation of this function, see "Using Domain Value Map Functions" in Developing SOA Applications with Oracle SOA Suite.
Signature
dvm:lookupValue(dvm-location, src-column, src-value, target-column, default-value, qualifiers[])
Arguments
All arguments are String values.
dvm-location: The full path and name of the DVM resource.
src-column: The source column name.
src-value: The source value (an XPath expression bound to the source document of the XSLT transformation).
target-column: The target column name.
default-value: If the value is not found, this default value is returned.
qualifier-column: A column that, along with the qualifier value, helps to narrow down the lookup. For more information about qualifiers, see "Qualifier Domains" in Developing SOA Applications with Oracle SOA Suite.
qualifier-value: A value in the qualifier column.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/dvm
namespace-prefix: dvm
Example
The following example looks for the value in the CityNames table that corresponds to the value "BO" in the CityCodes table. The qualifier "Massachusetts" in the State table helps to narrow down the city name to just that state. If no matching value is found, the function returns "CouldNotBeFound" instead.
dvm:lookupValue ('/CityMapsDVM/cityMap','CityCodes','BO','CityNames', 'CouldNotBeFound', 'State', 'Massachusetts')
This function returns an XML document fragment containing values for multiple target columns of a domain value map, where the value for the source column is equal to the source value. When using this function in an expression, if the returned value is directly assigned to a variable, the first occurrence is assigned to the variable. The returned value should be iterated to make the proper assignment.
For a more detailed explanation of this function, see "Using Domain Value Map Functions" in Developing SOA Applications with Oracle SOA Suite.
Signature
dvm:lookupValue1M(dvm-location, src-column, src-value, target-columns[])
Arguments
All arguments are String values.
dvm-location: The full path and name of the DVM resource.
src-column: The source column name.
src-value: The source value (an XPath expression bound to the source document of the XSLT transformation).
target-columns: The names of the target columns. At least one column name should be specified. You can specify multiple target column names, each as a separate argument.
Property IDs
namespace-uri: http://www.oracle.com/osb/xpath-functions/dvm
namespace-prefix: dvm
Example
The following example looks for the values in the CityNames and CityNickNames tables that correspond to the value "Garden City" in the CityCodes table.
dvm:lookupValue1M ('/CityMapsDVM/cityMap','CityCodes','Garden City','CityNames', 'CityNickName')
In addition to the standard XPath functions provided with Service Bus, you can create and register custom XPath functions to use in your expressions. Service Bus provides an extensible framework for creating custom XPath functions you can use in the XQuery expression editors in the development or runtime tooling, such as in pipelines, split-joins, and XQuery Mapper transformations.
This section includes the following topics:
Note:
Service Bus does not support custom functions that have side effects; for example, updating a database table or participating in a global transaction. Create custom functions that contribute only to an XQuery result, and perform side-effect behavior with other features such as Java Callouts.
Custom functions are available to all Service Bus projects and services within a WebLogic Server domain. To register a custom function, you create an XML file with an optional properties file for localization. The built-in functions that Service Bus provides use this function framework, so you can use those existing registration resources as a guide. Those files are located in the following directory:
/service_bus_home/config/xpath-functions
The Service Bus functions file is called osb-built-in.xml. In that file, keys wrapped in % symbols, such as %OSB_FUNCTIONS%, get their value from the corresponding .properties file. To extend custom functions to a new domain, you need to copy the registration files (XML and properties files) to the new domain in the following location:
/domain_home/config/osb/xpath-functions
You might need to create the xpath-functions subdirectory.
Below is an outline of the basic structure of a custom function registration file, followed by descriptions of the elements.
category id
group id
function
name
comment
namespaceURI
className
method
isDeterministic
scope
Elements have an xpf: prefix.
The following table lists and describes each element in the custom registration file.
Table B-1 Custom Function Registration File Properties
| Element | Description |
|---|---|
|
category |
The group that physically categorizes your group of functions in the expression editors, such as "Service Bus Functions." Use the |
|
group |
A subcategory for grouping functions in the user interface, such as "General" or "Accessors." Use the |
|
name |
The name of the function as it appears in XQuery expressions. Function names, which include the namespaceURI and prefix, must be unique. Service Bus does not support function overloading with different method arguments. Identical function names that have different namespaces, and thus different prefixes, are allowed. |
|
comment |
A description of the function. While the description does not appear in the Service Bus user interface, you should provide guidance that shows how to invoke the function with meaningful argument names. |
|
namespaceURI |
The namespace of the function. For example, the Service Bus functions namespace is |
|
className |
The fully qualified custom Java class that implements the function. |
|
method |
The custom Java method that implements the function, preceded by the return type; for example, If your method uses a single-dimensional array, see Using Single-Dimensional Arrays for guidance in making the entry in the XML file. |
|
isDeterministic |
A value of |
|
scope |
The type of Service Bus resource to which the function applies, such as Pipeline or SplitJoin. You can define multiple scope elements. |
Your custom functions do not appear in the expression editor until Service Bus can find your custom class. Use the following guidelines to create and package the class for a custom XPath function so Service Bus can locate and use it.
Use the following guidelines for creating the Java class and method for a custom function.
class: The class must be public.
method: The method must be public and static.
arguments and return values: The following table lists the supported types for method arguments and return values. If a type is not listed, it is not supported. Inner classes and multi-dimensional arrays are not supported.
Table B-2 Supported Java Method Types for Custom Functions
| Java Type | XQuery Type | XSLT Type |
|---|---|---|
|
java.lang.String |
xs:string |
string |
|
int, java.lang.Integer |
xs:int |
number |
|
boolean, java.lang.Boolean |
xs:boolean |
boolean |
|
long, java.lang.Long |
xs:long |
number |
|
short, java.lang.Short |
xs:short |
number |
|
byte, java.lang.Byte |
xs:byte |
number |
|
double, java.lang.Double |
xs:double |
number |
|
float, java.lang.Float |
xs:float |
number |
|
char, java.lang.Char |
xs:string |
object |
|
java.math.BigInteger |
xs:integer |
number |
|
java.math.BigDecimal |
xs:decimal |
number |
|
java.util.Date |
xs:datetime |
See footnoteFoot 1 |
|
java.sql.Date |
xs:date |
See footnote |
|
java.sql.Time |
xs:time |
See footnote |
|
javax.xml.namespace.QName |
xs:Qname |
See footnote |
|
org.apache.xmlbeans.XmlObject |
element() |
See footnote |
|
org.w3c.dom.Element |
element() |
The XSLT node-set type is not supported with custom XPath functions. |
Footnote 1
Converted to a string, then passed back as its original type.
Single-dimension arrays (using supported Java types) are mapped to corresponding XQuery types with an asterisk *, which is a wild card to imply the multiple cardinality of the array. For example:
public static XmlObject[] getArrayOfXmlObjects(XmlObject[] a)
is mapped to
namespace:getArrayOfXmlObjects($arg1 as element()*) as element()*
In function signatures that have single-dimensional array input arguments or return values, you must use the type encoding described at http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html#getName%28%29. The following examples show how to specify single-dimensional array methods in your custom function XML file using the required array encoding:
| Java Method | Entry in Custom Function XML File |
|---|---|
|
|
|
|
|
|
Service Bus must know about your custom function class in order to include your custom functions in the XQuery editors and let you use those functions. Package your custom function class in a JAR file, then place the JAR in one of the following directories:
service_bus_home/config/xpath-functions/
domain_home/config/osb/xpath-functions/
where service_bus_home is the location where Service Bus is installed and domain_home is the directory where the Service Bus domain is installed.
At IDE and server start-up, Service Bus looks for custom function classes in these directories to find the available custom functions. Be sure to correctly reference your custom class and method in the custom function XML file, described in Registering Custom Functions with Service Bus.
After you add new custom functions, you must restart the IDE and any servers that will use the new functions.
This section describes how to use custom functions in Service Bus XQuery expressions and resources.
You can include custom functions in both inline XQuery expressions and in XQuery resources just as you would use functions provided by Service Bus.
The syntax for invoking a custom function from within an XSLT resource varies by the XSLT engine you use with Service Bus. Given the following custom function code, the Syntax for Invoking a Custom Function with the Xalan Engine example, shown below, shows the syntax for invoking a custom function using the Xalan XSLT engine (the default on Microsoft Windows with the Oracle JDK).
package tests.pipeline;
public class CustomXQFunctions
{
public static String myUppercaseString(String arg)
{
return arg.toUpperCase();
}
}
Example - Syntax for Invoking a Custom Function with the Xalan Engine
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:param name="arg-string"/>
<xsl:template name="myUppercaseString"
xmlns:ns0="xalan://tests.pipeline.CustomXQFunctions">
<xsl:variable name="upcase" select="ns0:myUppercaseString($arg-string)" />
<originalInput>
<xsl:value-of select="$arg-string" />
</originalInput>
<result>
<xsl:value-of select="$upcase" />
</result>
</xsl:template>
<xsl:template match="*">
<xsl:copy>
<xsl:call-template name="myUppercaseString"/>
</xsl:copy>
</xsl:template>
</xsl:stylesheet>
With an input document of <example /> and an input arg-string value of hello, the transformation becomes:
<example> <originalInput>hello</originalInput> <result>HELLO</result> </example>
In a multiple-server environment with multiple Oracle Fusion Middleware product homes, you must manually add all custom function resources to any of those environments where the custom functions will be used. Clustering does not automatically distribute custom function resources across Managed Servers.