XPath Extension Functions

B XPath Extension Functions

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:

Cross-Reference Functions

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.

lookupPopulatedColumns

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())

lookupXRef

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())

lookupXRef1M

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())

markForDelete

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')

populateLookupXRefRow

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')

populateXRefRow

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'

populateXRefRow1M

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'

Domain Value Map Functions

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.

lookup

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')

lookupValue

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')

lookupValue1M

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')

Creating Custom XPath Functions

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.

Registering Custom Functions with Service Bus

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 `id` attribute to provide the name. If you are using a corresponding `.properties` file for localization, enter the key that contains the text value in the properties file; for example, `%MY_FUNCTIONS%`. Category IDs, which include the properties file key name and the actual name value, must be unique.
group	A subcategory for grouping functions in the user interface, such as "General" or "Accessors." Use the `id` attribute to provide the name. The naming guidelines for category ID apply to group ID. The group element is optional.
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 `http://www.bea.com/xquery/xquery-functions`. Namespaces and namespace prefixes must be unique. Custom namespaces that you provide appear in the default namespaces list in the XQuery editor.
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, `boolean isUserInGroup(java.lang.String, java.lang.String)`. 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 `true` or `false` declaring whether or not the function is deterministic. Deterministic functions always provide the same results; for example, a function that concatenates Strings. Non-deterministic functions return unique results; for example, a function that returns the time of day. Though you can use non-deterministic functions, the XQuery standard recommends that functions be deterministic to ensure XQuery engine optimization.
scope	The type of Service Bus resource to which the function applies, such as Pipeline or SplitJoin. You can define multiple scope elements.

Creating and Packaging the Custom Function Java Classes

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.

Creating the Class and Method

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 footnote^Foot 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.

Using Single-Dimensional Arrays

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
`public static String[] myUppercaseStringArray(String[] arg)`	`Ljava.lang.String; myUppercaseStringArray([Ljava.lang.String;)`
`public static int[] myAddInts(int[] arg)`	`[I myAddInts([I)`

Packaging the Custom Function Class

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.

Using Custom Functions

This section describes how to use custom functions in Service Bus XQuery expressions and resources.

Custom Functions In Inline XQuery Expressions and XQuery 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.

Custom Functions In XSLT Resources

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>

Deploying Custom Functions in a Cluster

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.