Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite 11g Release 1 (11.1.1) Part Number E10224-03 Home Book List Contents Index Contact Us Previous Next View PDF B XPath Extension Functions This appendix describes the XPath extension functions. Oracle provides XPath functions that use the capabilities built into Oracle SOA Suite and XPath standards for adding new functions. This appendix includes the following sections: Section B.1, "SOA XPath Extension Functions" Section B.2, "BPEL XPath Extension Functions" Section B.3, "Mediator XPath Extension Functions" Section B.4, "Advanced Functions" Section B.5, "Workflow Service Functions" Section B.6, "Using the XPath Building Assistant" Section B.7, "Creating User-Defined XPath Extension Functions" For additional information about XPath functions, visit the following URL: http://www.w3.org B.1 SOA XPath Extension Functions This section describes the following SOA XPath extension functions: Section B.1.1, "Database Functions" Section B.1.2, "Date Functions" Section B.1.3, "Mathematical Functions" Section B.1.4, "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. 14/05/2010 XPath Extension Functions …oracle.com/docs/…/bp_appx_functs.htm 1/69
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1)
Part Number E10224-03 Home Book
List
Contents Index Contact
Us
Previous Next
View PDF
B XPath Extension Functions
This appendix describes the XPath extension functions. Oracle provides XPath functions that use thecapabilities built into Oracle SOA Suite and XPath standards for adding new functions.
For additional information about XPath functions, visit the following URL:
http://www.w3.org
B.1 SOA XPath Extension Functions
This section describes the following SOA XPath extension functions:
Section B.1.1, "Database Functions"
Section B.1.2, "Date Functions"
Section B.1.3, "Mathematical Functions"
Section B.1.4, "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.
This function returns the absolute value of inputNumber.If inputNumber is not negative, theinputNumber is returned. If the inputNumber is negative, the negation of inputNumber is returned.
Example: abs(-1) returns 1.
Signature:
xpath20:abs(inputNumber as number)
Arguments:
inputNumber as number - The number for which the function returns an absolute value.
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.
The resource bundle in 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
Note:The appendToList function is deprecated. Oracle recommends that you use thebpelx:copyList extension of an assign activity to append data to a node list.
This function appends to a node list. The node list with which to append should not be null or empty.
This function translates using the streaming XPath APIs. It uses a unique concept called batching sothat 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 handle onlyforward-only XSL constructs such as for-each. The targetType can be SDOM or ATTACHMENT.
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 16/69
Signature:
ora:doStreamingTranslate('input SDOM or attachment element', 'streaming xpath
context', 'SDOM or ATTACHMENT', 'attachment element?')
This function translates the input data to XML, where the input can be a string, attachment, or elementthat contains Base64-encoded data. The targetType can be DOM, ATTACHMENT or SDOM.
This function sets a title to the composite instance which can later be used as one of the criteria insearching the instances. This function returns the same string that is passed as the argument.
Signature:
med:setCompositeInstanceTitle(title)
Arguments:
title - Specifies the composite instance title. This can be specified as an XPath expression on
This function returns the results of XSLT transformation by using the Oracle XDK XSLT processor. Thisfunction also supports transformations from and to XML attachments.
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 toread 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 the following:
XPath expression failed to execute.
Error while processing xpath expression,
the expression is "ora:readFile("file://c:/temp/test.doc")",
This function returns a boolean value indicating the status of the link. If the status of the link is positivethe 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
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 thiscase must be defined using an XML schema simple type or element. Otherwise, the return value of thisfunction is a node set containing the single node representing either an entire part of a message type (ifthe second argument is present and the third argument is absent) or the result of the selection basedon the locationPath (if both optional arguments are present). If the given locationPath selects a
node set of a size other than one during execution, the standard fault bpws:selectionFailure is
This function sets a title to the composite instance that can be later used as one of the criteria insearching the instances. This function returns the same string that is passed as the argument.
Signature:
mdhr:setCompositeInstanceTitle(title)
Arguments:
title - Specifies the composite instance title. This can be specified as an XPath expression on
The 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.
The function returns an XML document fragment containing values for multiple target columns of adomain value map, where the value for source column equals the source value.
'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.
The function is used to delete a value in a cross-reference table. The value in the column is marked asdeleted. This function returns true if deletion is successful else returns false.
Signature:
xref:markForDelete(tableName,columnName,value)
Arguments:
xrefTableName: The cross-reference table name.
xrefColumnName: The name of the column from which you want to delete a value.
This function retrieves a notification property. The function evaluates to corresponding values for eachnotification. Only use this function in the notification content XPath expression. If used elsewhere, itreturns 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.
attachmentIndex - The index of the attachment. The index begins from 1. TheattachmentIndex 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'.
locale - (Optional) The locale. This value defaults to system locale. This returns aresourceString XML element in the namespacehttp://xmlns.oracle.com/bpel/services/taskService, which contains the string from the
This function gets the name of an identity service group, selected according to the specified assignmentpattern. The group is selected from either the subordinate groups of the specified group (if a singlegroup name is supplied), or from the list of groups (if a list of user names is supplied). If the identityservice is configured with multiple realms, the realm name for the group and groups must also be
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 49/69
supplied. Additional assignment pattern specific parameters can be supplied. These additionalparameters are optional, depending on the details of the specific assignment pattern used.
This function returns the name of an identity service user, selected according to the specifiedassignment pattern. The user is selected from either the subordinate users of the specified group (if asingle group name is supplied), or from the list of users (if a list of user names is supplied). If theidentity service is configured with multiple realms, the realm name for the group and users must also besupplied. Additional assignment pattern specific parameters can be supplied. These additionalparameters are optional, depending on the details of the specific assignment pattern used.
This function gets the user roles. This function returns a list of objects, either application roles orgroups, depending on the roleType. If the user or role does not exist, it returns null.
Signature:
ids:getUserRoles(userName, roleType, direct)
Arguments:
userName - String or element containing the user whose roles are to be retrieved.
roleType - The role type that takes one of three values: ApplicationRole, EnterpriseRole,
or AnyRole.
direct - A string or element indicating if direct or indirect roles must be fetched. This is optional.
If not specified, only direct roles are fetched. This is either xsd:boolean or string true/false.
You can use the XPath Building Assistant to create XPath expressions.
B.6.1 XPath Building Assistant Description
Several dialogs enable you to specify XPath expressions at several places, including:
Expression field of the XPath Expression Builder
Expression field of an operation created under the Copy Operation tab of assign activities
Expression field of the while, wait, switch, and pick (onAlarm branch) activities
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 thisprocess:
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.2 Starting the XPath Building Assistant
Start the XPath Building Assistant by clicking inside the Expression field and pressing Ctrl and then thespace bar. The XPath Building Assistant is available within all fields of the Oracle JDeveloper and XSLTMapper function dialogs that require XPath expressions.
Description of the illustration xbuild2.gif
B.6.3 Using the XPath Building Assistant in Oracle JDeveloper: Step-By-StepExample
This section provides an example of using the XPath Building Assistant to build an expression in theFrom section of the Expression field of the Create Copy Operation dialog. This example models anXPath Expression that appends a string value to OrderComments within a purchase order. Thepurchase order element is part of one of the available BPEL variables.
1. Place the cursor inside the Expression field.
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 56/69
Description of the illustration xba1.gif
2. Press Ctrl and then the space bar to display a list of values for building an expression.
Description of the illustration xba2.gif
3. Make a selection from the list (for this example, concat(String) as String) in either of thefollowing ways:
Scroll down the list and double-click concat(String) as String.
Enter the letter c to display only items starting with that letter and double-click
concat(String) as String.
This value is added to the Expression field. The list automatically displays again with differentoptions and prompts you to enter the next portion of the XPath expression.
4. Select and double-click the next portion (for this example, the second entry for bpws):
Description of the illustration xba3.gif
This value is added to the Expression field. The list automatically displays again and promptsyou to enter the next portion of the XPath expression.
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 57/69
5. Select and double-click inputVariable.
Description of the illustration xba4.gif
6. Continue this process to build the remaining parts of the XPath expression (for this example,double-click payload > ns1:/PurchaseOrder > ns1:/OrderInfo > ns1:OrderCommentsas they appear).
Description of the illustration xba5.gif
7. Manually add text as appropriate (for this example, ,',Selected: Select Manufacturing'). Ifneeded, you can also manually enter logical operators (such as >, <, and so on).
Description of the illustration xba6.gif
Note:Instead of using double-clicks on the XPath Building Assistant popups, you canalso use the Enter key to make the selection. If your expression is complete, butyou 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 EditXPath Expression dialog of the XSLT Mapper.
1. Go to the transformation dialog.
2. Select Advanced Functions from the Component Palette list.
3. Scroll down the list to the xpath-expression.
4. Drag and drop the xpath-expression into the transformation dialog.
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 58/69
Description of the illustration xbuild20.gif
5. Double-click the function to display the Edit XPath Expression dialog.
6. Click the cursor inside the XPath Expression field.
7. Press Ctrl and then the space bar to display a list of values for building an expression.
Description of the illustration xbuild21.gif
8. Make a selection from the list (for this example, concat(String) as String) in either of thefollowing ways:
Scroll down the list and double-click concat(String) as String.
Enter the letter c to display only items starting with that letter and double-click
concat(String) as String.
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 59/69
Description of the illustration xbuild21b.gif
This selection is added to the XPath Expression field. The list automatically displays again withdifferent options and prompts you to enter the next portion of the XPath expression.
9. Continue this process to build the remaining parts of the XPath expression (for this example,double-click po:PurchaseOrder > po:ShipTo > po:Name > po:First as they appear).
10. Continue this process to build the remaining parts of the expression.
11. 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.
Description of the illustration xbuild23.gif
Once you finish specifying one argument, and enter a comma to move to the next argument, the tooltip updates itself to highlight the second argument name in bold, and so on. While editing existingXPaths that contain functions, you can re-invoke parameter tool tips by positioning the cursor within thefunction 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 theXPath 1.0 specification. The XPath Building Assistant warns you about syntactically incorrect XPaths (forexample, a missing parenthesis or apostrophe) by underlining the erroneous area in red. Drag themouse pointer over this area. The error message displays as a tool tip. The red underlining errordisappears after you make corrections.
Description of the illustration xbuild12.gif
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 60/69
Syntactically valid XPaths may be semantically invalid. This can cause unexpected errors at runtime. Forexample, you can misspell the name of an element, variable, function, or part. The XPath BuildingAssistant warns you about semantic errors by underlining the erroneous area in blue. Drag the mousepointer over this area. The error message displays as a tool tip. The blue underlining error disappearsafter you make corrections.
Description of the illustration xbuild24.gif
B.6.7 Creating Expressions with Free Form Text and XPath Expressions
You can mix free form text with XPath expressions in some dialogs.
1. Place your cursor over the field to display a popup message that describes this functionality.
Description of the illustration xbuild16.gif
2. Enter free form text (in this example, 'Hello, your telephone number').
Description of the illustration xbuild25.gif
3. Enter <% when you are ready to invoke the XPath Building Assistant.
Description of the illustration xbuild26.gif
A red underline appears, which indicates that you are being prompted to add information.
4. Press Ctrl and then the space bar to invoke the XPath Building Assistant.
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 61/69
Description of the illustration xbuild27.gif
5. Scroll down the list and double-click the value you want.
6. Continue this process to build the remaining parts of the expression.
You can create user-defined (custom) XPath extension functions for use in Oracle SOA Suite. Thesefunctions can be created for the following components:
Oracle BPEL Process Manager
Oracle Mediator
XSLT Mapper
Human workflow
Shared by all of these components
XPath extension functions in Oracle SOA Suite adhere to the following standards:
A single schema defines the configuration syntax for both system functions and user-definedfunctions.
XPath functions are categorized based on usage (Oracle BPEL Process Manager, Oracle Mediator,human workflow, XSLT Mapper, and those commonly used by all).
System functions are separated from user-defined functions.
A repository hosts both system function configuration files and user-defined function configurationfiles.
A repository hosts user-defined function implementation JAR files and automatically makes themavailable for the Java Virtual Machine (JVM) (class loaders).
As a best practice, follow these conventions for creating functions:
If possible, write functions that can be shared across all components. Functions shared by allcomponents can be created in a configuration file named ext-soa-xpath-functions-
config.xml. Note that you must implement XSLT Mapper functions differently than functions for
Oracle BPEL Process Manager, Oracle Mediator, and human workflow.
For more information about description of these implementation differences, see Section B.7.1,"How to Implement User-Defined XPath Extension Functions".
If you create a function for one component that cannot be used by others (for example, a
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 62/69
function for Oracle BPEL Process Manager that cannot be used by Oracle Mediator or humanworkflow), then create that function in the configuration file specific to that component. For thisexample, the Oracle BPEL Process Manager function must be created in a configuration filenamed ext-bpel-xpath-functions-config.xml.
Example B-1 shows the function schema used by system and user-defined functions.
B.7.1 How to Implement User-Defined XPath Extension Functions
This section describes how to implement user-defined XPath extension functions for Oracle SOA Suitecomponents.
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 forother components:
Each XSLT Mapper function requires a corresponding public static method from a public static
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 64/69
class. The function name and method name must match.
XSLT Mapper function namespaces must take the formhttp://www.oracle.com/XSL/Transform/java/mypackage.MyFunctionClass, wheremypackage.MyFunctionClass is the fully qualified class name of the public static class containing
the public static methods for the functions.
For additional details about creating a user-defined XPath extension function for the XSLT Mapper, seeSection 35.3.4.4, "Importing User-Defined 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 mustimplement either the oracle.fabric.common.xml.xpath.IXPathFunction interface (defined in thefabric-runtime.jar file) or javax.xml.xpath.XPathFunction.
To implement functions for all other components:
1. 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 follows:
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 following example, a function named getNodeValue(arg1) is implemented that gets a
B.7.2 How to Configure User-Defined XPath Extension Functions
This section describes how to configure user-defined XPath extension functions.
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 65/69
To configure user-defined xpath extension functions:
1. Create an XPath extension configuration file in which to define the function. Example B-2 shows asample configuration file that follows the function schema shown in Example B-1. In this example,two functions are created: mf:myFunction1 and mf:myFunction2.
Example B-2 Sample XML Extension Configuration File
Table B-1 describes the elements of the configuration file. Each function configuration file usessoa-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 classproviding NLS support for all function configurations.
Table B-1 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.
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 66/69
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 functionconcat(), 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 enterthe parameter value. The wizard class must be specified later. The default value isfalse 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 auser 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 nowizard-enabled parameter, this element must be absent.
Note: This element is not supported for user-defined functions. Only system functions
currently support this feature.
2. Name your user-defined XPath extension configuration file based on the component type withwhich to use the function. Table B-2 describes the naming conventions to use for user-definedconfiguration files.
Table B-2 User-Defined Configuration Files
14/05/2010 XPath Extension Functions
…oracle.com/docs/…/bp_appx_functs.htm 67/69
To Use with This Component... Use This Configuration File Name...
Oracle BPEL Process Manager ext-bpel-xpath-functions-config.xml
3. Place the configuration file inside a JAR file along with the compiled classes. Within the JAR file, theconfiguration 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.
4. In Oracle JDeveloper, go to Tools > Preferences > SOA.
5. Click the Add button and select your JAR file.
6. 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.
B.7.3 How to Deploy User-Defined Functions to Runtime
You can deploy user-defined functions to the runtime environment.
To deploy user-defined functions to runtime:
1. Copy the user-defined function JAR files toBEA_Home/user_projects/domains/domain_name/lib or a subdirectory of lib.
where domain_name is the name of the Oracle WebLogic Server domain (for example,soainfra).
2. Restart the Oracle WebLogic Server.
Note:As an alternative, you can add theBEA_Home/user_projects/domains/domain_name/lib directory into the
class loader. This prevents you from having to restart the Oracle WebLogicServer.