B XPath Extension Functions

This appendix describes the XPath extension functions for Oracle SOA Suite, Oracle BPEL Process Manager, Oracle Mediator, and human workflow. It also describes advanced XPath functions, how to build XPath expressions in Oracle JDeveloper, and how to create user-defined XPath extension functions. Oracle provides XPath functions that use the capabilities built into Oracle SOA Suite and XPath standards for adding new functions.

B.1 SOA XPath Extension Functions

This section describes the following types of SOA XPath extension functions:

Database functions

Date functions

Mathematical functions

String functions

B.1.1 Database Functions

This section describes the following database functions:

B.1.1.1 lookup-table

This function returns a string based on the SQL query generated from the parameters.

The string is obtained by executing:

SELECT outputColumn FROM table WHERE inputColumn = key

against the data source that can be either a JDBC connect string (jdbc:oracle:thin:username/password@host:port:sid) or a data source JNDI identifier. Only the Oracle thin driver is supported if the JDBC connect string is used.

B.1.1.3 sequence-next-val

Returns the next value of an Oracle sequence.

The next value is obtained by executing the following:

SELECT sequence.nextval FROM dual

against a data source that can be either a JDBC connect string (jdbc:oracle:thin:username/password@host:port:sid) or a data source JNDI identifier. Only the Oracle thin driver is supported if a JDBC connect string is used.

B.1.4.8 get-localized-string

This function returns the locale-specific string for the key. This function uses language, country, variant, and resource bundle to identify the correct resource bundle. All parameters must be in string format. Use the string() function to convert any parameter values to strings before sending them to get-localized-string.

The resource bundle is obtained by resolving resourceLocation against the resourceBaseURL. The URL is assumed to be a directory only if it ends with /.

Usage:oraext:get-localized-string(resourceBaseURL as string, resourceLocation as string, resource bundle as string, language as string, country as string, variant as string, key as string)

Example:oraext:get-localized-string('file:/c:/','','MyResourceBundle','en','US','','MSG_KEY') returns a locale-specific string from a resource bundle 'MyResourceBundle' in the C:\ directory

B.2 BPEL XPath Extension Functions

This section describes the following BPEL XPath extension functions.

Notes:

Do not use the ora:getDomainid() XPath function, even though it is displayed in the XPath Expression Builder dialog in Oracle JDeveloper. This function is not applicable to 11g SOA composite applications and is only displayed because it is used as part of upgrading BPEL processes from Release 10g to Release 11g.

The processXSLTAttachment and processXSQL functions have been deprecated for Release 11g. Do not use these XPath functions, even though they are displayed in the XPath Expression Builder dialog in Oracle JDeveloper.

B.2.1 addQuotes

This function returns the content of a string with single quotes added.

Signature:

ora:addQuotes(string)

Arguments:

string - The string to which this function adds quotes.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.2 authenticate

This function authenticates an LDAP user and returns true or false.

The authenticate, listUsers, lookupUser, and search XPath functions provide the lookup and search functionality to obtain information from the LDAP server (typically, the LDAP user details).

These XPath functions use a configuration file to obtain server access information for the JNDI (for example, context factory, LDAP server provider URL, authenticate type, and so on). The configuration file is named directories.xml and must be placed in the same directory in which the .bpel file for the BPEL project is located. To call these XPath functions, you must provide this file.

locationPath - Provides an absolute location path (with / meaning the root of the document fragment representing the entire part) to identify the root of a subtree within the document fragment representing the part (optional).

Object - The object can be either a list or a single item. If the object is a list, this function appends each item in the list. Each appended item is either an element, or an element with the string value of the node created.

Property IDs:

deprecated

Use the bpelx:copyList or bpelx:append extension activity to append to a list.

This function copies a node list or a node. The node list to be copied to should not be null or empty.

Signature:

ora:copyList('variableName', 'partName'?, 'locationPath'?, Object)

Arguments:

variableName - The source variable for the data.

partName - The part to select from the variable (optional).

locationPath - Provides an absolute location path (with / meaning the root of the document fragment representing the entire part) to identify the root of a subtree within the document fragment representing the part (optional).

Object - The object can be either a list or a single item. If the object is a list, each item in the list is copied. Each item to be copied is either an element, or an element with the string value of the node created.

Property IDs:

deprecated

Use the bpelx:copyList extension activity to append to a list.

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.5 countNodes

Note:

While the countNodes function is still available for use, Oracle recommends that you use version 1.0 of the XPath count() function to return the size of the elements as an integer.

This function returns the size of the elements as an integer.

Signature:

ora:countNodes('variableName', 'partName'?, 'locationPath'?)

Arguments:

variableName - The source variable for the data.

partName - The part to select from the variable (optional).

locationPath - Provides an absolute location path (with / meaning the root of the document fragment representing the entire part) to identify the root of a subtree within the document fragment representing the part (optional).

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.6 doc

This function returns the content of an XML file.

Signature:

ora:doc('fileName','xpath'?)

Arguments:

fileName - The name of the XML file.

xpath - A part of an XML file (for example, the node set, node list, or leaf node).

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.7 doStreamingTranslate

This function translates using the streaming XPath APIs. It uses a unique concept called batching so that the transformation engine does not materialize the result of a transformation into memory. Therefore, it can handle arbitrarily large payloads of the order of gigabytes. However, it can only handle forward-only XSL constructs such as for-each. The targetType can be SDOM or ATTACHMENT.

In these situations, you must set the following property in the schema node of the NXSD for this function to execute properly.

nxsd:useArrayIdentifiers="true"

This setting can adversely impact the performance of this function for very large inputs (in which case, use the dostreamingxlate function).

nxsdTemplate - The NXSD schema to use to translate the input data to XML format.

nxsdRoot - The root element in the NXSD schema.

targetType - Decides how the XPath function translates the native data into XML.

attachment element - This is the attachment for the returned XML. This parameter is optional.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.10 doXSLTransform

This function implements WS-BPEL 2.0's doXSLTransform function that supports multiple parameters of XSLT. When using this function, the XSL template match must not be set to root (which is /). It must be the root element.

Signature:

ora:doXSLTransform('url_to_xslt',input,['paramQname',paramValue]*)

Arguments:

url_to_xslt - Specifies the XSL style sheet URL.

input - Specifies the input variable name.

paramQname - Specifies the parameter QName.

paramValue - Specifies the value of the parameter.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.11 doXSLTransformForDoc

This function is a complement XPath function to doXSLTransform(). It aims to perform the transformation when the XSLT template matches the document.

You can use the ora:doXSLTransformForDoc function to write the results of large XSLT/XQuery operations to a temporary file in a directory system. The document is then loaded from the temporary file when needed. This eliminates the need for caching an entire document as binary XML in memory.

B.2.12 formatDate

dateTime - Contains a date-related value in XSD format. For nonstring arguments, this function behaves as if a string() function were applied. If the argument is not a date, the output is an empty string. If it is a valid XSD date and some fields are empty, this function attempts to fill unspecified fields. For example, 2003-06-10T15:56:00.

format - Contains a string formatted according to java.text.SimpleDateFormat format.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.13 generateGUID

Generates a unique GUID.

Signature:

ora:generateGUID()

Arguments: There are no arguments for this function.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.14 getApplicationName

This function returns the application name.

Signature:

ora:getApplicationName()

Arguments: There are no arguments for this function.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.15 getAttachmentContent

This function gets the attachment content from an href function.

Signature:

ora:getAttachmentContent(varName[, partName[, query]])

Arguments:

varName - Specifies the source variable for the data.

partName - (Optional) Specifies the part to select from the variable.

query - (Optional) Specifies an absolute location path (with / meaning the root of the document fragment representing the entire part) to identify the root of a subtree within the document fragment representing the part.

B.2.28 getElement

This function returns an element using index from the array of elements.

Signature:

ora:getElement('variableName', 'partName', 'locationPath', index)

Arguments:

variableName - The source variable for the data.

partName - The part to select from the variable (required).

locationPath - Provides an absolute location path (with / meaning the root of the document fragment representing the entire part) to identify the root of a subtree within the document fragment representing the part (required).

index - Dynamic index value. The index of the first node is 1.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.29 getFaultAsString

This function returns the fault as a string value.

Signature:

ora:getFaultAsString()

Arguments: There are no arguments for this function.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.30 getFaultName

This function returns the fault name.

Signature:

ora:getFaultName()

Arguments: There are no arguments for this function.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.31 getGroupIdsFromGroupAlias

This function returns a List of user IDs for a group alias specified in the TaskServiceAliases section of the BPEL suitcase descriptor.

Signature:

ora:getGroupIdsFromGroupAlias(String aliasName)

Arguments:

aliasName - The alias for a list of users or groups.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.32 getInstanceId

This function returns the instance ID.

Signature:

ora:getInstanceId()

Arguments: There are no arguments for this function.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.33 getNodeValue

This function returns the value of a DOM node as a string.

Signature:

ora:getNodeValue(node)

Arguments:

node - The DOM node.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.34 getNodes

This function gets a node list. This is implemented as an alternate to bpws:getVariableData, which does not return a node list.

Signature:

ora:getNodes('variableName', 'partName'?, 'locationPath'?)

Arguments:

variableName - The source variable for the data.

partName - The part to select from the variable (optional).

locationPath - Provides an absolute location path (with / meaning the root of the document fragment representing the entire part) to identify the root of a subtree within the document fragment representing the part (optional).

Create a SetParams.xsl file to populate the properties. Within the XSLT, the parameters are accessible through their names. For this example, the parameter names are userName and location, and the values are jsmith and CA, respectively.

You can use the ora:processXSLT function to write the results of large XSLT/XQuery operations to a temporary file in a directory system. The document is then loaded from the temporary file when needed. This eliminates the need for caching an entire document as binary XML in memory.

B.2.54 readFile

This function returns the content of the file.

Signature:

ora:readFile('fileName','nxsdTemplate'?,'nxsdRoot'?)

Arguments:

fileName - The name of the file. This argument can also be an HTTP URL.

This function by default reads files relative to the suitcase JAR file for the process. If the file to read is located in a different directory path, you must specify an extra directory slash ( /) to indicate that this is an absolute path. For example:

ora:readFile('file:///c:/temp/test.doc')

If you specify only two directory slashes (//), you receive an error similar to that shown in Example B-10:

Example B-10 Error Message with readFile Function

XPath expression failed to execute.
Error while processing xpath expression,
the expression is "ora:readFile("file://c:/temp/test.doc")",
the reason is c. Verify the xpath query.

nxsdTemplate - The NXSD template for the output.

nxsdRoot -The NXSD root.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

Note:

Currently, the readFile function does not support the functionality to access files on a web server that requires authorization. If you tried to access such a file, then you get the following error:

java.io.IOException: Server returned HTTP response code: 401 for URL

B.2.55 search

This function returns a list of LDAP entries.

Signature:

ldap:search('directoryName','filter','scope')

Parameters:

directoryName: The directory name specified in the directories.xml file. For information about the directories.xml file, see Section B.2.2, "authenticate."

filter: The filter expression to use for the search; this value cannot be null.

scope: The scope of the search. It must be one of the following values: 1: one level, 2: subtree, or 0: named object. This parameter is optional. By default, its value is 2.

Return

An XML element that contains the list of entries.For this XPath function, all properties must be specified in the directories.xml file.Example

B.2.56 writeBinaryToFile

This function writes the binary bytes of a variable (or part of the variable) to a file of the given file name.

Signature:

ora:writeBinaryToFile(varName[, partName[, query]])

Arguments:

varName - The name of the variable.

partName - The name of the part in the messageType variable.

query - The query string to a child of the root element.

Property IDs:

namespace-uri:http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.57 BPEL Extension Functions in BPEL 1.1 and BPEL 2.0

This section describes BPEL extension functions.

Table B-1 lists the BPEL extension functions supported by either version 1.1 or version 2.0 of the BPEL specification. If a function is supported by a specific version, it displays for selection in the BPEL Extension Functions list of the Expression Builder dialog in Oracle JDeveloper. Otherwise, it does not appear. BPEL version 1.1 functions use the namespace prefix bpws. BPEL version 1.1 functions use the namespace prefix bpel.

Table B-1 BPEL Extension Functions Supported in BPEL 1.1 or BPEL 2.0

Function

Supported in BPEL 1.1?

Supported in BPEL 2.0?

bpws:getLinkStatus

Yes

No

bpws:getVariableData

Yes

No

getVariableProperty

Yes

No

bpel:getVariableProperty

No

Yes

B.2.57.1 getLinkStatus

This function returns a boolean value indicating the status of the link. If the status of the link is positive, the value is true. Otherwise, the value is false. This function can only be used in a join condition.

The linkName argument refers to the name of an incoming link for the activity associated with the join condition.

B.2.57.2 getVariableData

This function extracts arbitrary values from BPEL variables.

When only the first argument is present, the function extracts the value of the variable, which in this case must be defined using an XML schema simple type or element. Otherwise, the return value of this function is a node set containing the single node representing either an entire part of a message type (if the second argument is present and the third argument is absent) or the result of the selection based on the locationPath (if both optional arguments are present).

Signature:

bpws:getVariableData ('variableName', 'partName'?, 'locationPath'?)

Arguments:

variableName - The source variable for the data.

partName - The part to select from the variable (optional).

locationPath - Provides an absolute location path (with / meaning the root of the document fragment representing the entire part) to identify the root of a subtree within the document fragment representing the part (optional).

B.2.57.2.1 selectionFailure Fault is Thrown if the Result Node Set is a Size Other Than One During Execution

According to the Business Process Execution Language for Web Services Specification, if the locationPath argument selects a node set of a size other than one during execution, the standard fault bpws:selectionFailuremust be thrown by a compliant implementation.

For example, the count() function shown in Example B-12 does not work if there are multiple entries of product elements under StoreRequest; this causes a selectionFailure fault to be thrown.

B.2.57.3 getVariableProperty (For BPEL 1.1)

This function extracts arbitrary values from BPEL variables. The first argument specifies the source variable for the data and the second argument identifies the QName of the property to select from that variable. If the given property selects a node set of a size other than one during execution, the standard fault bpws:selectionFailure is thrown.

B.2.57.4 getVariableProperty (For BPEL 2.0)

This function extracts arbitrary values from BPEL variables. The first argument specifies the source variable for the data and the second argument identifies the QName of the property to select from that variable. If the given property selects a node set of a size other than one during execution, the standard fault bpws:selectionFailure is thrown.

Signature:

bpel:getVariableProperty ('variableName', 'propertyname')

Arguments:

variableName - The source variable for the data.

propertyName - The QName of the property. If the given property selects a node set of a size other than one during execution, the standard fault selectionFailure is thrown.

B.2.58.3 format

This function formats a message using Java's message format.

Signature:

ora:format(formatStrings, args+)

Arguments:

formatStrings - The string of data to be formatted.

args+ - The arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The number of arguments is variable and may be zero.

Property IDs:

namespace-uri: http://schemas.oracle.com/xpath/extension

namespace-prefix: ora

B.2.58.4 genEmptyElem

This function generates a list of empty elements for the given QName.

Signature:

ora:genEmptyElem('ElemQName',size?, 'TypeQName'?, xsiNil?)

Arguments:

ElemQName - The first argument is the QName of the empty elements.

size - The second optional integer argument for the number of empty elements. If missing, the default size is 1.

TypeQName - The third optional argument is the QName, which is the xsi:type of the generated empty name. This xsi:type pattern matches SOAPENC:Array. If missing or an empty string, the xsi:type attribute is not generated.

xsiNil - The fourth optional boolean argument is to specify whether the generated empty elements are XSI - nil, provided the element is XSD-nillable. The default is false. If missing or false, xsi:nil is not generated.

B.2.58.8 min-value-among-nodeset

This function returns the minimum value from a list of input numbers, the node set inputNumbers.The node set can be a collection of text nodes or elements containing text nodes.In the case of elements, the first text node's value is considered.

B.3 Oracle Mediator XPath Extension Functions

This section describes the Oracle Mediator XPath extension functions.

B.3.1 doStreamingTranslate

This function translates using the streaming XPath APIs. It uses a unique concept called batching so that the transformation engine does not materialize the result of transformation into memory. Therefore, it can handle arbitrarily large payloads of the order of gigabytes. However, it can only handle forward-only XSL constructs such as for-each. The targetType can be SDOM or ATTACHMENT.

B.3.2 doTranslateFromNative

This function translates the input data to XML, where the input can be a string to translate, a file or FTP adapter attachment, an attachment, or an element that contains Base64-encoded data. The targetType can be DOM, ATTACHMENT or SDOM.

In the XSLT Mapper in Oracle JDeveloper, drag the getHeader function into the mapper. In the Edit Function - getHeader dialog, click Add. The namespaces argument is added for you to enter the required information.

B.4.8 lookup-xml

This function returns the string value of an element defined by lookupXPath in an XML file (docURL) given its parent XPath (parentXPath), the key XPath (keyXPath), and the value of the key (key).

Example:

oraext:lookup-xml('file:/d:/country_data.xml', '/Countries/Country', 'Abbreviation', 'FullName', 'UK') returns the value of the element FullName child of /Countries/Country, where Abbreviation = 'UK' is in the file D:\country_data.xml.

B.5.2 createWordMLDocument

This function creates a Microsoft Word ML document as a base 64-encoded string.

Signature:

hwf:createWordMLDocument(node, xsltURI)

Arguments:

node - The node is an XML node that is an input to the transformation.

xsltURI - The XSLT used to transform the node (the first argument) to Microsoft Word ML.

Property IDs:

namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.3 getNotificationProperty

This function retrieves a notification property. This function evaluates to corresponding values for each notification. Only use this function in the notification content XPath expression. If used elsewhere, it returns null.

Signature:

hwf:getNotificationProperty(propertyName)

Arguments:

propertyName - The name of the notification property. It can be one of the following values:

recipient - The recipient of the notification.

recipientDisplay - The display name of the recipient.

taskAssignees - The task assignees.

taskAssigneesDisplay - The display names of the task assignees.

locale - The locale of the recipient.

taskId - The task ID of the task for which the notification is meant.

taskNumber - The task number of the task for which the notification is meant.

appLink - The HTML link to the Oracle BPM Worklist task details page.

Property IDs:

namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.4 getNumberOfTaskApprovals

This function computes the number of times the task was approved.

Signature:

hwf:getNumberOfTaskApprovals(taskId)

Arguments:

taskId - The ID of the task.

Property IDs:

namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.5 getPreviousTaskApprover

This function retrieves the previous task approver.

Signature:

hwf:getPreviousTaskApprover(taskId)

Arguments:

taskId - The ID of the task.

Property IDs:

namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.6 getTaskAttachmentByIndex

This function retrieves the task attachment at the specified index.

Signature:

hwf:getTaskAttachmentByIndex(taskId, attachmentIndex)

Arguments:

taskId - The task ID of the task.

attachmentIndex - The index of the attachment. The index begins at 1. The attachmentIndex argument can be a node whose value evaluates to the index number as a string (all node values are strings). If specified statically, it can be specified as '1'.

Property IDs:

namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.7 getTaskAttachmentByName

This function retrieves the task attachment by the attachment name.

Signature:

hwf:getTaskAttachmentByName(taskId, attachmentName)

Arguments:

taskId - The task ID of the task.

attachmentName - The name of the attachment.

Property IDs:

namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.8 getTaskAttachmentContents

This function retrieves the task attachment contents by the attachment name.

Signature:

hwf:getTaskAttachmentContents(taskId, attachmentName)

Arguments:

taskId - The task ID of the task.

attachmentName - The name of the attachment.

Property IDs:

namespace-uri:http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.9 getTaskAttachmentsCount

This function retrieves the number of task attachments.

Signature:

hwf:getTaskAttachmentsCount(taskId)

Arguments:

taskId - The task ID of the task.

Property IDs:

namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.10 getTaskResourceBundleString

This function returns the internationalized resource value from the resource bundle associated with a task definition.

Signature:

hwf:getTaskResourceBundleString(taskId, key, locale?)

Arguments:

taskId - The task ID of the task.

key - The key to the resource.

locale - (Optional) The locale. This value defaults to system locale. This returns a resourceString XML element in the namespace http://xmlns.oracle.com/bpel/services/taskService, which contains the string from the resource bundle.

Property IDs:

namespace-uri:http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.11 wfDynamicGroupAssign

This function gets the name of an identity service group, selected according to the specified assignment pattern. The group is selected from either the subordinate groups of the specified group (if a single group name is supplied), or from the list of groups (if a list of user names is supplied). If the identity service is configured with multiple realms, the realm name for the group and groups must also be supplied. Additional assignment pattern-specific parameters can be supplied. These additional parameters are optional, depending on the details of the specific assignment pattern used.

patternName - The name of the assignment pattern (for example, ROUND_ROBIN).

groupList - The list of groups from which to select a group.

realmName - The name of the identity service realm to which the groups belong.

patternParam1...patternParamN - Any additional parameters required by the assignment pattern implementation (may be optional, depending on the pattern).

Property IDs:

namespace-uri: http://xmlns.oracle.com/bpel/workflow/xpath

namespace-prefix: hwf

B.5.12 wfDynamicUserAssign

This function returns the name of an identity service user, selected according to the specified assignment pattern. The user is selected from either the subordinate users of the specified group (if a single group name is supplied), or from the list of users (if a list of user names is supplied). If the identity service is configured with multiple realms, the realm name for the group and users must also be supplied. Additional assignment pattern-specific parameters can be supplied. These additional parameters are optional, depending on the details of the specific assignment pattern used.

B.5.13.4 getReportees

This function gets the reportees of the user. If the user does not exist, it returns null. This function returns a list of nodes. Each node in the list is called user.

Signature:

ids:getReportees(userName, upToLevel, realmName)

Arguments:

userName - The user name.

upToLevel- Defines the levels of indirect reportees to be included in the result. If the value is 1, it returns only direct reportees. If the value is -1, it returns all levels of reportees. It can be either an element with value xsd:number or a string, for example '1'.

realmName - The realm name. This is optional and if not specified, the default realm is assumed.

B.6 Building XPath Expressions in Oracle JDeveloper

You can use the Expression Builder dialog and the XPath Building Assistant to create XPath expressions. You can visually design XPath expressions in a BPEL process or Oracle Mediator service component in the Expression Builder dialog.

B.6.1 How to Use the Expression Builder

To use the Expression Builder:

In the Functions list, select the function category to use (for example, Identity Service Functions).

B.6.2 Introduction to the XPath Building Assistant

Several dialogs enable you to specify XPath expressions with the XPath Building Assistant, including:

Expression field of the Expression Builder dialog

Expression field of the Initialize tab of the Create Variable dialog in BPEL 2.0

Edit XPath Expression and Edit Function dialogs of the XSLT Mapper

Manually specifying long and complex expressions is supported, but can be a cumbersome and error-prone process. The XPath Building Assistant provides the following set of features that simplify this process:

Automatic completion of the following:

Elements and attributes

Functions

BPEL variables and parts

Function parameter tool tips

Syntactic and semantic validation of XPaths

B.6.3 How to Use the XPath Building Assistant

This section provides an example of using the XPath Building Assistant to build an expression in the Expression field of the Expression Builder dialog.

To use the XPath Building Assistant:

Click inside the Expression field and press Ctrl and then the space bar. The menu of available selections is displayed.

Make a selection from the list in either of the following ways:

Scroll down the list and double-click a function.

Enter the beginning letter (for example, c) to display only items starting with that letter and double-click the appropriate function.

Instead of double-clicking selections in the XPath Building Assistant popups, you can also use the Enter key to make the selection. If your expression is complete, but you are still being prompted to enter information, press Esc. This closes the list.

B.6.4 Using the XPath Building Assistant in the XSLT Mapper

This section provides an example of using the XPath Building Assistant to build an expression in the Edit XPath Expression dialog of the XSLT Mapper.

To use the XPath Building Assistant in the XSLT Mapper:

Go to the XSLT Mapper.

From the ComponentPalette list, select Advanced Functions.

Scroll down the list to the xpath-expression function.

Drag and drop the xpath-expression function into the XSLT Mapper, as shown in Figure B-8.

This selection is added to the XPath Expression field. The list automatically displays again with different options and prompts you to enter the next portion of the XPath expression.

Continue this process to build the remaining parts of the XPath expression.

Click OK to close the Edit XPath Expression dialog when complete.

B.6.5 Function Parameter Tool Tips

Function parameter tool tips display the expected arguments of a chosen XPath function. For example, if you manually enter the function concat, and then enter (, the parameter tool tip appears and displays the expected arguments of the concat function. The current argument name of the function is highlighted in bold. Figure B-11 provides details.

Once you finish specifying one argument, and enter a comma to move to the next argument, the tool tip updates itself to highlight the second argument name in bold, and so on. While editing existing XPaths that contain functions, you can re-invoke parameter tool tips by positioning the cursor within the function and then pressing a combination of the Ctrl, Shift, and space bar keys.

B.6.6 Syntactic and Semantic Validation

Within Oracle JDeveloper, an XPath expression is considered syntactically valid if it conforms to the XPath 1.0 specification. The XPath Building Assistant warns you about syntactically incorrect XPaths (for example, a missing parenthesis or apostrophe) by underlining the erroneous area in red. Drag the mouse pointer over this area. The error message displays as a tool tip. The red underlining error disappears after you make corrections. Figure B-12 provides details.

Syntactically valid XPaths may be semantically invalid. This can cause unexpected errors at runtime. For example, you can misspell the name of an element, variable, function, or part. The XPath Building Assistant warns you about semantic errors by underlining the erroneous area in blue. Drag the mouse pointer over this area. The error message displays as a tool tip. The blue underlining error disappears after you make corrections. Figure B-13 provides details.

If possible, write functions that can be shared across all components. Functions shared by all components can be created in a configuration file named ext-soa-xpath-functions-config.xml. You must implement XSLT Mapper functions differently than Oracle BPEL Process Manager, Oracle Mediator, and human workflow functions.

If you create a function for one component that cannot be used by others (for example, a function for Oracle BPEL Process Manager that cannot be used by Oracle Mediator or human workflow), then create that function in the configuration file specific to that component. For this example, the Oracle BPEL Process Manager function must be created in a configuration file named ext-bpel-xpath-functions-config.xml.

Example B-15 shows the function schema used by system and user-defined functions.

B.7.1 How to Implement User-Defined XPath Extension Functions

B.7.1.1 How to Implement Functions for the XSLT Mapper

Implementation of user-defined XPath extension functions for the XSLT Mapper is different than for other components:

Each XSLT Mapper function requires a corresponding public static method from a public static class. The function name and method name must match.

XSLT Mapper function namespaces must take the form http://www.oracle.com/XSL/Transform/java/mypackage.MyFunctionClass, where mypackage.MyFunctionClass is the fully qualified class name of the public static class containing the public static methods for the functions.

B.7.1.2 How to Implement Functions for All Other Components

For Oracle BPEL Process Manager, Oracle Mediator, and human workflow functions, you must implement either the oracle.fabric.common.xml.xpath.IXPathFunction interface (defined in the fabric-runtime.jar file) or javax.xml.xpath.XPathFunction.

To implement functions for all other components:

Implement the oracle.fabric.common.xml.xpath.IXPathFunction interface for your XPath function. The IXPathFunction interface has one method named call(context, args). The signature of this method is as shown in Example B-16:

package oracle.fabric.common.xml.xpath;
public interface IXPathFunction
{
/** Call this function.
*
* @param context The context at the point in the
* expression when the function is called.
* @param args List of arguments provided during
* the call of the function.
*/
public Object call(IXPathContext context, List args) throws
XPathFunctionException;
}

where:

context - The context at the point in the expression when the function is called.

args - The list of arguments provided during the call of the function.

For the example shown in Example B-17, a function named getNodeValue(arg1) is implemented that gets a value of w3cnode:

Table B-2 describes the elements of the configuration file. Each function configuration file uses soa-xpath-functions as its root element. The root element has an optional resourceBundle attribute. The resourceBundle value is the fully qualified class name of the resource bundle class providing NLS support for all function configurations.

Table B-2 Function Schema Elements

Element

Description

className

The fully qualified class name of the function implementation class.

return

The return type of the function. This can be one of the following types supported by XPath and XSLT: string, number, boolean, node set, and tree.

params

The parameters of the function. A function can have no parameters. A parameter has the following attributes:

name: The name of the parameter.

type: The type of the parameter. This can be one of the following types supported by XPath and XSLT: string, number, boolean, node set, and tree.

minOccurs: The minimum occurrences of the parameter. If set to 0, the parameter is optional. If set to 1, the parameter is required. The current restriction is that this attribute must only take a value of either 0 or 1 and that optional parameters must be defined after the required parameters. The default value is 1 if this attribute is absent.

maxOccurs: The maximum occurrences of the parameter. If set to unbounded, the parameter can repeat anytime. This can support functions such as XPath 1.0 function concat(), which can take unlimited parameters. The current restriction is that no parameters except the last parameter of the function can have maxOccurs greater than 1 or unbounded. The default value is 1 if this attribute is absent.

wizardEnabled: Indicates whether to enable a wizard to enter the parameter value. This supports a user interface where the parameter value must be entered. If set to true, a wizard launch button is rendered next to the parameter value field. The wizard launch button, when pressed, launches a popup wizard to help the user enter the parameter value. The wizard class must be specified later. The default value is false if this attribute is absent, meaning there is no wizard support for the parameter by default.

desc

An optional description of the function. If the resourceKey is present, the description is retrieved from the resource bundle specified earlier on the root element.

detail

An optional longer (detailed) description of the function. If the resourceKey is present, the description is retrieved from the resource bundle specified earlier on the root element.

icon

An optional icon URL of the function. If the resourceKey is present, the icon URL is retrieved from the resource bundle specified earlier on the root element. This is to support a user interface in which the function must be displayed.

helpURL

An optional help HTML URL of the function. If the resourceKey is present, the help URL is retrieved from the resource bundle specified earlier on the root element. This is to support a user interface in which the function help link must be displayed.

group

An optional group name of the function. If the resourceKey is present, the group name is retrieved from the resource bundle specified earlier on the root element. This is to support a user interface where functions must be grouped. If no group name is specified, the function falls into a built-in advanced functions group when being grouped in a user interface.

wizardClass

The fully qualified class name of the wizard class for all parameters that are wizard-enabled. This is to support a user interface in which parameter values must be entered. This wizard class is invoked by wizard launch buttons to help you enter parameter values. If there is no wizard-enabled parameter, this element must be absent.

Note: This element is not supported for user-defined functions. Only system functions currently support this feature.

Name your user-defined XPath extension configuration file based on the component type with which to use the function. Table B-3 describes the naming conventions to use for user-defined configuration files.

Table B-3 User-Defined Configuration Files

To Use with This Component...

Use This Configuration File Name...

Oracle BPEL Process Manager

ext-bpel-xpath-functions-config.xml

Oracle Mediator

ext-mediator-xpath-functions-config.xml

XSLT Mapper

ext-mapper-xpath-functions-config.xml

Human workflow

ext-wf-xpath-functions-config.xml

All components

ext-soa-xpath-functions-config.xml

Place the configuration file inside a JAR file along with the compiled classes. Within the JAR file, the configuration file must be located in the META-INF directory. The JAR file does not need to reside in a specific directory.

Note:

The customXpathFunction JAR must be added explicitly as it is not part of the SOA composite.

In Oracle JDeveloper, go to Tools > Preferences > SOA.

Click the Add button and select your JAR file.

Restart Oracle JDeveloper for the changes to take effect.

The JAR file is automatically added to the JVM's class path to make it available for use.