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:

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 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.

Example: oraext:lookup-table('employee','id','1234','last_name','jdbc:oracle:thin:xyz/xyz@localhost:1521:ORCL')

Signature:

oraext:lookup-table(table, inputColumn, key, outputColumn, data source)

Arguments:

  • table - The table from which to draw the data.

  • inputColumn - The column within the table.

  • key - The key value of the input column.

  • outputColumn - The column to output the data.

  • data source - The source of the data.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.1.2 query-database

This function returns a node set by executing the SQL query against the specified database.

Signature:

oraext:query-database(sqlquery as string, rowset as boolean, row as boolean, data source as string)

Arguments:

  • sqlquery - The SQL query to perform.

  • rowset - Indicates if the rows should be enclosed in an element.

  • row - Indicates if each row should be enclosed in an element.

  • data source - Either a JDBC connect string (jdbc:oracle:thin:username/password@host:port:sid) or a JNDI name for the database.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

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.

Example: oraext:sequence-next-val('employee_id_sequence','jdbc:oracle:thin:xyz/xyz@localhost:1521:ORCL')

Signature:

oraext:sequence-next-val(sequence as string, data source as string)

Arguments:

  • sequence - The sequence number in the database.

  • data source - Either a JDBC connect string or a data source JNDI identifier.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.2 Date Functions

This section describes the following functions:

B.1.2.1 add-dayTimeDuration-to-dateTime

This function returns a new date time value adding dateTime to the given duration.

If the duration value is negative, then the resulting value precedes dateTime.

Signature:

xpath20:add-dayTimeDuration-from-dateTime(dateTime as string, duration as string)

Arguments:

  • dateTime as string - The dateTime to which the function adds the duration, in string format.

  • duration as string - The duration to add to the dateTime, or subtract if the duration is negative, in string format.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.2 current-date

This function returns the current date in the ISO format of YYYY-MM-DD.

Signature:

xpath20:current-date(object)

Arguments:

  • Object - The time in standard format.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.3 current-dateTime

This function returns the current datetime value in the ISO format of CCYY-MM-DDThh:mm:ssTZD.

Signature:

xpath20:current-dateTime(object)

Arguments:

  • object - The time in standard format.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.4 current-time

This function returns the current time in ISO format. The format is hh:mm:ssTZD.

Signature:

xpath20:current-time(object)

Arguments:

  • object - The time in standard format.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.5 day-from-dateTime

This function returns the day from dateTime. The default day is 1.

Signature:

xpath20:day-from-dateTime(object)

Arguments:

  • object - The time in standard format as a string.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.6 format-dateTime

This function returns the formatted string of dateTime using the format provided.

Signature:

xpath20:format-dateTime(dateTime as string, format as string)

Arguments:

  • dateTime - The dateTime to be formatted.

  • format - The format for the output.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.7 hours-from-dateTime

This function returns the hour from dateTime. The default hour is 0.

Signature:

xpath20:hours-from-dateTime(dateTime as string)

Arguments:

  • dateTime - The string with the date and time.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.8 implicit-timezone

This function returns the current time zone in the ISO format of +/- hh:mm, indicating a deviation from Coordinated Universal Timezone (UTC).

Signature:

xpath20:implicit-timezone(object)

Arguments:

  • object - The time in standard format.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.9 minutes-from-dateTime

This function returns the minute from dateTime. The default minute is 0.

Signature:

xpath20:minutes-from-dateTime(dateTime as string)

Arguments:

  • dateTime as string - The date and time.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.10 month-from-dateTime

This function returns the month from dateTime. The default month is 1 (January).

Signature:

xpath20:month-from-dateTime(dateTime as string)

Arguments:

  • dateTime as string - The dateTime to be formatted.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.11 seconds-from-dateTime

This function returns the second from dateTime. The default second is 0.

Signature:

xpath20:seconds-from-dateTime(dateTime as string)

Arguments:

  • dateTime as a string - The dateTime as a string.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.12 subtract-dayTimeDuration-from-dateTime

This function returns a new dateTime value after subtracting the duration from dateTime.

If the duration value is negative, then the resulting dateTime value follows input-dateTime value.

Signature:

xpath20:subtract-dayTimeDuration-from-dateTime(dateTime as string, duration as string)

Arguments:

  • dateTime as string - The dateTime from which the function subtracts the duration, in string format.

  • duration as string - The duration to subtract from the dateTime, or to add if the duration is negative, in string format.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xp20

B.1.2.13 timezone-from-dateTime

This function returns the time zone from dateTime. The default time zone is GMT+00:00.

Signature:

xpath20:timezone-from-dateTime(dateTime as string)

Arguments:

  • dateTime as string - The dateTime for which this function returns a time zone.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.2.14 year-from-dateTime

This function returns the year from dateTime.

Signature:

xpath20:year-from-dateTime(dateTime as string)

Arguments:

  • dateTime - The dateTime as a string.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.3 Mathematical Functions

This section describes the following function.

B.1.3.1 abs

This function returns the absolute value of inputNumber.If the inputNumber is not negative, the inputNumber 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.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.4 String Functions

This section describes the string functions.

B.1.4.1 compare

This function returns the lexicographical difference between inputString and compareString by comparing the unicode value of each character of both the strings.

This function returns -1 if inputString lexicographically precedes the compareString.

This function returns 0 if both inputString and compareString are equal.

This function returns 1 if inputString lexicographically follows the compareString.

Example: xpath20:compare('Audi', 'BMW') returns -1

Signature:

xpath20:compare(inputString as string, compareString as string)

Arguments:

  • variableName - The source variable for the data.

  • propertyName - The qualified name (QName) of the property.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.4.2 compare-ignore-case

This function returns the lexicographical difference between inputString and compareString while ignoring case and comparing the unicode value of each character of both the strings.

This function returns -1 if inputString lexicographically precedes the compareString.

This function returns 0 if both inputString and compareString are equal.

This function returns 1 if inputString lexicographically follows the compareString.

Example: xpath20:compare-ignore-case('Audi','bmw') returns -1

Signature:

xp:compare-ignore-case(inputString as string, compareString as string)

Arguments:

  • inputString - The string of data to be searched.

  • CompareString - The string to compare against the input string.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.4.3 create-delimited-string

This function returns a delimited string created from nodeSet delimited by a delimiter.

Signature:

oraext:create-delimited-string(nodeSet as node-set, delimiter as string)

Arguments:

  • nodeSet - The node set to convert into a delimited string.

  • delimiter - The character that separates the items in the output string; for example, a comma or a semicolon.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.4.4 ends-with

This function returns true if inputString ends with searchString.

Example: xpath20:ends-with('XSL Map','Map') returns true

Signature:

xpath20:ends-with(inputString as string, searchString as string)

Arguments:

  • inputString - The string of data to be searched.

  • searchString - The string for which the function searches.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.4.5 format-string

This function returns the message formatted with the arguments passed. At least one argument is required and supports up to a maximum of 10 arguments.

Example: oraext:format-string('{0} + {1} = {2}','2','2','4') returns '2 + 2 = 4'

Signature:

oraext:format-string(string,string,string...)

Arguments:

  • string - One of the strings to be used in the formatted output.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.4.6 get-content-as-string

This function returns the XML representation of the input element.

Signature:

oraext:get-content-as-string(element as node-set)

Arguments:

  • element as node-set - The input element that the function returns as an XML representation.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.4.7 get-content-from-file-function

This function returns the content of the file.

Signature:

oraext:get-content-from-file-function(object)

Arguments:

  • object: The object.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

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

Signature:

oraext:get-localized-string(resourceURL,resourceLocation,resourceBundleName,language,country,variant,messageKey)

Arguments:

  • resourceURL - The URL of the resource.

  • resourceLocation - The subdirectory location of the resource.

  • resourceBundleName - The name of the ZIP file containing the resource bundle.

  • language - The language of the localized output.

  • country - The country of the localized output.

  • variant - The language variant of the localized output.

  • messageKey - The message key in the resource bundle.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.4.9 index-within-string

This function returns the zero-based index of the first occurrence of searchString within the inputString.

This function returns -1 if searchString is not found.

Example: oraext:index-within-string('ABCABC, 'B') returns 1

Signature:

oraext:index-within-string(inputString as string, searchString as string)

Arguments:

  • inputString - The string of data to be searched.

  • searchString - The string for which the function searches in inputString.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.4.10 last-index-within-string

This function returns the zero-based index of the last occurrence of searchString within inputString.

This function returns -1 if searchString is not found.

Example: oraext:last-index-within-string('ABCABC', 'B') returns 4

Signature:

oraext:last-index-within-string(inputString as string, searchString as string)

Arguments:

  • inputString - The string of data to be searched.

  • searchString - The string for which the function searches in the inputString.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.4.11 left-trim

This function returns the value of inputString after removing all the leading white spaces.

Example: oraext:left-trim(' account ') returns 'account '

Signature:

oraext:left-trim(inputString)

Arguments:

  • inputString - The string to be left-trimmed.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.4.12 lower-case

This function returns the value of inputString after translating every character to its lower-case correspondent.

Example: xpath20:lower-case('ABc!D') returns 'abc!d'

Signature:

xpath20:lower-case(inputString)

Arguments:

  • inputString - The string of data that is in lowercase.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.4.13 matches

This function returns true if intputString matches the regular expression pattern regexPattern.

Example: xpath20:matches('abracadabra', '^a.*a$') returns true

Signature:

xpath20:matches(intputString, regexPattern)

Arguments:

  • inputString - The string of data that must be matched.

  • regexPattern - The regular expression pattern.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.1.4.14 right-trim

This function returns the value inputString after removing all the trailing white spaces.

Example: oraext:right-trim(' account ') returns ' account'

Signature:

oraext:right-trim(inputString as string)

Arguments:

  • inputString - The input string to be right-trimmed.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.1.4.15 upper-case

This function returns the value of inputString after translating every character to its uppercase correspondent.

Example: xpath20:upper-case('abCd0') returns 'ABCD0'

Signature:

xpath20:upper-case(inputString as string)

Arguments:

  • inputString - The string of data that is in uppercase.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20

  • namespace-prefix: xpath20

B.2 BPEL XPath Extension Functions

This section describes the following BPEL XPath extension functions.

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 appendToList

Note:

The appendToList function is deprecated. Oracle recommends that you use the bpelx: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.

Signature:

ora:appendToList('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, 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.

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

  • namespace-prefix: ora

B.2.3 copyList

Note:

While the copyList function is still available for use, Oracle recommends that you use the bpelx:copyList extension to copy a node list or a node. For more information, see Section 6.14.6, "How to Use bpelx:copyList."

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.4 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.5 doc

This function returns the content of an XML file.

Signature:

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

Arguments:

  • fileName - The name of the XML file.

  • xpath - The path to the file.

Property IDs:

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

  • namespace-prefix: ora

B.2.6 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.

Signature:

ora:doStreamingTranslate('input SDOM or attachment element', 'streaming xpath context', 'SDOM or ATTACHMENT', 'attachment element?')

Arguments:

  • input SDOM or attachment element

  • streaming xpath context

  • SDOM or ATTACHMENT

  • attachment element

Property IDs:

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

  • namespace-prefix: ora

B.2.7 doTranslateFromNative

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

Signature:

ora:doTranslateFromNative('input','nxsdTemplate','nxsdRoot','targetType','attachment element?')

Arguments:

  • input - The input data of the XPath function.

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

  • nxsdRoot - The root element in the native XSD (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.8 doTranslateToNative

This function translates the input DOM to a string or attachment. The targetType can be STRING or ATTACHMENT

Signature:

ora:doTranslateToNative('input','nxsdTemplate','nxsdRoot','targetType','attachment element?')

Arguments:

  • input - The input data of the XPath function. The data can either be DOM or SDOM data that must be translated to a native format such as comma-separated values (CSV).

    The input node is usually the root element of the incoming DOM. Example B-1 provides details.

    Example B-1 doTranslateToNative Function

    med:doTranslateToNative($in.request/inp1:Root-Element, 'xsd/address_csv.xsd', 
    @ 'Root-Element','STRING')" 
    

    However, the input node can be a subelement and not the root element of the incoming DOM. Example B-2 provides details.

    Example B-2 doTranslateToNative Function

    med:doTranslateToNative($in.request/inp1:requestToNative/ns1:Root-Element, 
     'xsd/address_csv.xsd', 'Root-Element','ATTACHMENT', 
     $in.request/inp1:requestToNative/inp1: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" 
    

    Note that 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.9 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.10 doXSLTransformForDoc

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

Example B-3 shows the doXSLTransformForDoc function.

Example B-3 doXSLTransformForDoc Functions

<function name="ora:doXSLTransformForDoc">
  <className>com.collaxa.cube.xml.xpath.functions.xml.DoXSLTransformForDocument
  </className>
  <return type="node-set"/>
  <params>
   <param name="template" type="string"/>
   <param name="input" type="string"/>
   <param name="properties" type="string" minOccurs="0" maxOccurs="unbounded"/>
  </params>
  <desc resourceKey="PI_FUNCTION_DESC_DOXSLTRANSFORM_FOR_DOC"></desc>
  <detail resourceKey="PI_FUNCTION_DESC_LONG_DOXSLTRANSFORM_FOR_DOC">
        This function is a complement xpath function to doXSLTransform(). It aims
 to do the transformation when the xslt template matching the
document. The signature of this function is <i>ora:doXSLTransformForDoc('url_to_
xslt',input,['paramQname',paramValue]*)</i>.
        </detail>
  <group>BPEL XPath Extension Functions</group>
 </function>

Signature:

ora:doXSLTransformForDoc('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

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.

For more information, see Section 43.1.3.7, "Using XPath Functions to Write Large XSLT/XQuery Output to a File System."

B.2.11 formatDate

This function converts standard XSD date formats to characters suitable for output.

Signature:

ora:formatDate('dateTime','format')

Arguments:

  • 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.12 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.13 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.14 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.

Property IDs:

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

  • namespace-prefix: ora

B.2.15 getComponentName

This function returns the component name.

Signature:

ora:getComponentName()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.16 getComponentInstanceID

This function returns the component instance ID.

Signature:

ora:getComponentInstanceID()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.17 getCompositeName

This function returns the composite name.

Signature:

ora:getCompositeName()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.18 getCompositeInstanceID

This function returns the BPEL process composite instance ID.

Signature:

ora:getCompositeInstanceID()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.19 getCompositeURL

This function returns the composite URL.

Signature:

ora:getCompositeURL()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.20 getContentAsString

This function returns the content of an element as an XML string.

Signature:

ora:getContentAsString(element elementAsNodeList)

Arguments:

  • element - The element (source of the data).

  • elementAsNodeList - The element as the node list.

Property IDs:

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

  • namespace-prefix: ora

B.2.21 getConversationId

This function returns the conversation ID.

Signature:

ora:getConversationId()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.22 getCreator

This function returns the instance creator.

Signature:

ora:getCreator()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.23 getCurrentDate

This function returns the current date as a string.

Signature:

ora:getCurrentDate('format'?)

Argument:

  • format - (Optional) Specifies a string formatted according to java.text.SimpleDateFormat format (optional).

Property IDs:

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

  • namespace-prefix: ora

For more information, see Section 6.12.1, "How to Assign a Date or Time."

B.2.24 getCurrentDateTime

This function returns the current date time as a string.

Signature:

ora:getCurrentDateTime('format'?)

Argument:

  • format - (Optional) Specifies a string formatted according to java.text.SimpleDateFormat format (optional).

Property IDs:

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

  • namespace-prefix: ora

B.2.25 getCurrentTime

This function returns the current time as a string.

Signature:

ora:getCurrentTime('format'?)

Argument:

  • format - (Optional) Specifies a string formatted according to java.text.SimpleDateFormat format (optional).

Property IDs:

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

  • namespace-prefix: ora

B.2.26 getDomainId

This function returns the current domain ID.

Signature:

ora:getDomainId()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.27 getECID

This function returns the execution context ID (ECID).

Signature:

ora:getECID()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

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

Property IDs:

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

  • namespace-prefix: ora

B.2.35 getOwnerDocument

This function returns the document object associated with the node.

Signature:

ora:getOwnerDocument(node)

Arguments:

  • node - Specifies the XML node.

Property IDs:

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

  • namespace-prefix: ora

B.2.36 getParentComponentInstanceID

This function returns the BPEL process instance parent component instance ID.

Signature:

ora:getParentComponentInstanceID()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.37 getPreference

This function returns the value of a property specified in the preferences section of the BPEL suitcase descriptor.

Signature:

ora:getPreference(preferenceName)

Arguments:

  • preferenceName - The name of the preference as specified in the BPEL suitcase descriptor.

Property IDs:

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

  • namespace-prefix: ora

B.2.38 getProcessId

This function returns the ID of the current BPEL process.

Signature:

ora:getProcessId()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.39 getProcessOwnerId

This function returns the ID of the user who owns the process, if specified in the TaskServiceAliases section of the BPEL suitcase descriptor.

Signature:

ora:getProcessOwnerId()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.40 getProcessURL

This function returns the root URL of the current BPEL process.

Signature:

ora:getProcessURL()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.41 getProcessVersion

This function returns the current process version.

Signature:

ora:getProcessVersion()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: ora

B.2.42 getUserAliasId

This function returns the user ID for an alias specified in the TaskServiceAliases section of the BPEL suitcase descriptor.

Signature:

ora:getUserAliasId (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.43 getUserIdsFromGroupAlias

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

Signature:

ora:getUserIdsFromGroupAlias( String aliasName )

Arguments:

  • aliasName - Alias name of the group.

Property IDs:

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

  • namespace-prefix: ora

B.2.44 setCompositeInstanceTitle

This function sets a title to the composite instance that can later be used as one of the criteria in searching 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 the message payload.

Property IDs:

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

  • namespace-prefix: ora

B.2.45 instanceOf

This function extracts arbitrary values from BPEL variables.

Signature:

ora:instanceOf(an_xpath_expression, 'typeQName')

Arguments:

  • an_xpath_expression - An XPath expression that returns an element.

  • typeQName - The QName of a globally-declared XSD type.

Property IDs:

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

  • namespace-prefix: ora

B.2.46 integer

This function returns the content of the node as an integer.

Signature:

ora:integer(node)

Arguments:

  • node - The input node.

Property IDs:

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

  • namespace-prefix: ora

B.2.47 parseEscapedXML

This function parses a string to DOM.

Signature:

oratext:parseEscapedXML(contentString)

Arguments:

  • contentString - The string that this function parses to a DOM.

Property IDs:

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

  • namespace-prefix: oratext

B.2.48 parseXML

This function parses a string to a DOM element.

Signature:

oratext:parseXML(contentString)

Arguments:

  • contentString - The string that this function parses to a DOM element.

Property IDs:

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

  • namespace-prefix: oratext

B.2.49 processXQuery

This function returns the result of an XQuery transformation.

Signature:

ora:processXQuery('template','context'?)

Arguments:

  • template - The XSLT template.

  • input - The input data to be transformed.

Property IDs:

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

  • namespace-prefix: ora

B.2.50 processXSLT

This function returns the result of an XSLT transformation using the Oracle XDK XSLT processor.

Example B-4 shows the 11g version of processXSLT.

Example B-4 11g Version of processXSLT

<function name="ora:processXSLT">
 <className>com.collaxa.cube.xml.xpath.functions.xml.GetElementFromXDKXSLTFunction
 </className>
  <return type="node-set"/>
  <params>
   <param name="template" type="string"/>
   <param name="input" type="string"/>
   <param name="properties" type="string" minOccurs="0" maxOccurs="unbounded"/>
  </params>
  <desc resourceKey="PI_FUNCTION_DESC_PROCESSXSLT"></desc>
  <detail resourceKey="PI_FUNCTION_DESC_LONG_PROCESSXSLT">
        This function returns result of XSLT transformation by using Oracle XDK
        XSLT processor. 
        </detail>
  <group>BPEL XPath Extension Functions</group>
 </function>

Example B-5 shows the 10g version of processXSLT, which is provided for backward compatiblity.

Example B-5 10g Version of processXSLT

<function name="xdk:processXSLT">
 <className>com.collaxa.cube.xml.xpath.functions.xml.GetElementFromXDKXSLTFunction
 </className>
  <return type="node-set"/>
  <params>
   <param name="template" type="string"/>
   <param name="input" type="string"/>
   <param name="properties" type="string" minOccurs="0" maxOccurs="unbounded"/>
  </params>
  <desc resourceKey="PI_FUNCTION_DESC_PROCESSXSLT"></desc>
  <detail resourceKey="PI_FUNCTION_DESC_LONG_PROCESSXSLT">
   This is same as 11g, for backward compatiablity this function uses the
   old 10.1.2 namespace. This function returns the result of XSLT transformation
   by using Oracle XDK XSLT processor. 
            </detail>
  <group>BPEL XPath Extension Functions</group>
 </function>

Signature:

11g version of the signature:

ora:processXSLT('template','input','properties'?)

10g version of the signature:

xdk:processXSLT('template','input','properties'?)

Arguments:

  • template - The XSLT template. Both HTTP and file URLs are supported.

  • input - The input data to be transformed.

  • properties - The properties that translate to XSL parameters that can be accessed within the XSL map using the construct <xsl:param name="paramName"/>. The properties are defined as follows:

    1. Create a params.xsd file to define the name-value pair (every property is a name-value pair). For example:

      <?xml version="1.0" encoding="windows-1252" ?>
      <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns="http://schemas.oracle.com/service/bpel/common"
                  targetNamespace="http://schemas.oracle.com/service/bpel/common"
                  elementFormDefault="qualified">
        <!-- Root Element for Parameters -->
        <xsd:element name="parameters">
          <xsd:complexType>
            <xsd:sequence>
              <!-- Each Parameter is represented by an "item" node that contains
                   one unique name and a string value
              -->
              <xsd:element name="item" minOccurs="1" maxOccurs="unbounded">
                <xsd:complexType>
                  <xsd:sequence>
                    <xsd:element name="name" type="xsd:string"/>
                    <xsd:element name="value" type="xsd:string"/>
                  </xsd:sequence>
                </xsd:complexType>
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:schema>
      
    2. 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.

      <?xml version="1.0" encoding="UTF-8" ?>
      <?oracle-xsl-mapper
        <mapSources>
          <source type="XSD">
            <schema location="TestXSLParams.xsd"/>
            <rootElement name="TestXSLParamsProcessRequest"
       namespace="http://xmlns.oracle.com/TestXSLParams"/>
          </source>
        </mapSources>
        <mapTargets>
          <target type="XSD">
            <schema location="params.xsd"/>
            <rootElement name="ArrayOfNameAnyTypePairType"
       namespace="http://schemas.oracle.com/service/bpel/common"/>
          </target>
        </mapTargets>
        <!-- GENERATED BY ORACLE XSL MAPPER 10.1.3.1.0(build 061009.0802) AT [WED
       APR 18 14:35:04 PDT 2007]. -->
      ?>
      <xsl:stylesheet version="1.0"
                      xmlns:ns2="http://schemas.oracle.com/service/bpel/common"
      xmlns:xp20="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services
      .functions.Xpath20"
      
                      xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
                      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                      xmlns:ora="http://schemas.oracle.com/xpath/extension"
      xmlns:ehdr="http://www.oracle.com/XSL/Transform/java/oracle.tip.esb.server.
      headers.ESBHeaderFunctions"
                      xmlns:ns0="http://www.w3.org/2001/XMLSchema"
                      xmlns:orcl="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services
      .functions.ExtFunc"
                      xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath"
                      xmlns:hwf="http://xmlns.oracle.com/bpel/workflow/xpath"
                      xmlns:ns1="http://xmlns.oracle.com/TestXSLParams"
                      exclude-result-prefixes="xsl ns0 ns1 ns2 xp20 bpws ora ehdr
       orcl ids hwf">
        <xsl:template match="/">
          <ns2:parameters>
            <ns2:item>
              <ns2:name>
                <xsl:value-of select="'userName'"/>
              </ns2:name>
              <ns2:value>
                <xsl:value-of select="'jsmith'"/>
              </ns2:value>
            </ns2:item>
            <ns2:item>
              <ns2:name>
                <xsl:value-of select="'location'"/>
              </ns2:name>
              <ns2:value>
                <xsl:value-of select="'CA'"/>
              </ns2:value>
            </ns2:item>
          </ns2:parameters>
        </xsl:template>
      </xsl:stylesheet>
      
    3. Invoke SetParams.xsl from the .bpel file. For example:

      • Within assign activity initializeXSLParameters, you initialize the parameter variable from the specific BPEL variable whose information you want to access from within the XSLT.

      • Within assign activity executeXSLT, you invoke the XSLT with the parameters as the properties (third) argument of the function processXSLT.

      For example:

      <process name="TestXSLParams"
       . . .
       . . .
         <sequence name="main">
            <receive name="receiveInput" partnerLink="client"
               portType="client:TestXSLParams" operation="initiate"
               variable="inputVariable" createInstance="yes"/>
            <assign name="initializeXSLParameters">
               <bpelx:annotation>
                  <bpelx:pattern>transformation</bpelx:pattern>
               </bpelx:annotation>
               <copy>
                  <from expression="ora:processXSLT ('SetParams.xsl',
                     bpws:getVariableData('inputVariable','payload'))"/>
                  <to variable="propertiesXMLVar"/>
                  </copy>
            </assign>
            <assign name="executeXSLT">
               <bpelx:annotation>
                   <bpelx:pattern>transformation</bpelx:pattern>
               </bpelx:annotation>
      
               <copy>
                  <from expression="ora:processXSLT('TestXSLParams.xsl',
                     bpws:getVariableData('inputVariable','payload'),
                     bpws:getVariableData('propertiesXMLVar'))"/>
                   <to variable="outputVariable" part="payload"/>
               </copy>
            </assign>
            <invoke name="callbackClient" partnerLink="client"
               portType="client:TestXSLParamsCallback"
               operation="onResult"
               inputVariable="outputVariable"/>
         </sequence>
      </process>
      
    4. In BPEL, you use the properties to process the XSLT function.

Property IDs:

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

  • namespace-prefix: ora (for 11g)

  • namespace-prefix: xdk (for 10g)

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.

For more information, see Section 43.1.3.7, "Using XPath Functions to Write Large XSLT/XQuery Output to a File System."

B.2.51 processXSLTAttachment

This function returns the results of XSLT transformation by using the Oracle XDK XSLT processor. This function also supports transformations from and to XML attachments.

Signature:

ora:processXSLTAttachment('template','input','href'?,'properties'?)

Example B-6 provides an example of signature use.

Example B-6 Signature

<function name="ora:processXSLTAttachment">
<className>com.collaxa.cube.xml.xpath.functions.xml.
 GetElementFromXSLTAttachmentFunction</className>
  <return type="node-set"/>
  <params>
   <param name="template" type="string"/>
   <param name="input" type="string"/>
   <param name="href" type="string" minOccurs="0"/>
   <param name="properties" type="string" minOccurs="0" maxOccurs="unbounded"/>
  </params>
  <desc resourceKey="PI_FUNCTION_DESC_processXSLTAttachment"></desc>
  <detail resourceKey="PI_FUNCTION_DESC_LONG_processXSLTAttachment">

Arguments:

  • template - The XSLT template.

  • input - The input data to be transformed.

  • href - The location of the actual data.

  • properties - The properties that translate to XSL parameters that can be accessed within the XSL map using the construct <xsl:param name="paramName"/>. See Section B.2.50, "processXSLT" for information on defining this argument.

Property IDs:

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

  • namespace-prefix: ora

B.2.52 processXSQL

This function returns the result of the XSQL request.

Signature:

ora:processXSQL('template','input','properties'?)

Arguments:

  • template - The XSLT template.

  • input - The input data to be transformed.

  • properties - The properties that translate to XSL parameters that can be accessed within the XSL map using the construct <xsl:param name="paramName"/>. See Section B.2.50, "processXSLT" for information on defining this argument.

Property IDs:

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

  • namespace-prefix: ora

B.2.53 readBinaryFromFile

This function reads data from a file.

Signature:

ora:readBinaryFromFile(fileName)

Arguments:

  • fileName - The file name from which to read data.

Property IDs:

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

  • namespace-prefix: ora

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-7:

    Example B-7 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 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.56 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.56.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.

Signature:

bpws:getLinkStatus ('linkName')

Arguments:

  • variableName - The source variable for the data.

  • propertyName - The QName of the property.

Property IDs:

  • namespace-uri: http://schemas.xmlsoap.org/ws/2003/03/business-process/

  • namespace-prefix: bpws

B.2.56.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).

Property IDs:

  • namespace-uri: http://schemas.xmlsoap.org/ws/2003/03/business-process/

  • namespace-prefix: bpws

B.2.56.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:selectionFailure must be thrown by a compliant implementation.

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

Example B-8 count() Function Error

count(bpws:getVariableData('inputVariable',
 'payload','/ns2:StoreRequest/ns2:product'))

To make this work, change the syntax to the following:

"count($inputVariable.payload/ns2:product)"

B.2.56.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.

Signature:

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

Arguments:

  • variableName - The source variable for the data.

  • propertyName - The QName of the property.

Property IDs:

  • namespace-uri: http://schemas.xmlsoap.org/ws/2003/03/business-process/

  • namespace-prefix: bpws

B.2.56.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.

Property IDs:

  • namespace-uri: http://schemas.xmlsoap.org/ws/2003/03/business-process/

  • namespace-prefix: bpel

B.2.57 Utility Functions

This section describes the utility functions.

B.2.57.1 batchProcessActive

This function returns the number of active processes in the batch.

Signature:

ora:batchProcessActive(String batchId, String processId)

Arguments:

  • batchId - The ID of the batch.

  • processId - The ID of the process.

Property IDs:

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

  • namespace-prefix: ora

B.2.57.2 batchProcessCompleted

This function returns the number of completed processes in the batch.

Signature:

ora:batchProcessCompleted(String batchId, String processId)

Arguments:

  • batchId - The ID of the batch.

  • processId - The ID of the process.

Property IDs:

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

  • namespace-prefix: ora

B.2.57.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.57.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.

Property IDs:

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

  • namespace-prefix: ora

B.2.57.5 getChildElement

This function gets a child element for the given element.

Signature:

ora:getChildElement(element, index)

Arguments:

  • element - The source for the data.

  • index - The integer value of the child element index.

Property IDs:

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

  • namespace-prefix: ora

B.2.57.6 getMessage

This function gets a message based on the arguments.

Signature:

ora:getMessage(locale, relativeLocation, resourceName, resourceKey, resourceLocation?)

Arguments:

  • locale - The locale of the message.

  • relativeLocation - The subdirectory or message.

  • resourceName - The name of the message resource.

  • resourceKey - The key of the resource.

  • resourceLocation - The location of the resource.

Property IDs:

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

  • namespace-prefix: ora

B.2.57.7 max-value-among-nodeset

This function returns the maximum value from a list of input numbers, the node set inputNumber.

The node set inputNumber 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.

Signature:

oraext:max-value-among-nodeset(inputNumber as node-set)

Arguments:

  • inputNumber - The node set of input numbers.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.2.57.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.

Signature:

oraext:min-value-among-nodeset(inputNumbers as node-set)

Arguments:

  • inputNumber - The node set of input numbers.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.2.57.9 square-root

This function returns the square root of inputNumber.

Example: oraext:square-root(25) returns 5

Signature:

oraext:square-root(inputNumber as number)

Arguments:

  • inputNumber - The input number for which the function calculates the square root.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.2.57.10 translateFromNative

This function translates the input stream to an XML file.

Signature:

ora:translateFromNative('string','nxsdTemplate'?,'nxsdRoot'?)

Arguments:

  • string - The data to convert into an XML file.

  • nxsdTemplate - The XSD file used to define how the translation is performed.

  • nxsdRoot - The root element defined in the XSD file.

Property IDs:

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

  • namespace-prefix: ora

B.2.57.11 translateToNative

Translates the XML to the native data.

Signature:

ora:translateFromNative('string','nxsdTemplate'?,'nxsdRoot'?)

Arguments:

  • string - The XML file to convert into a string.

  • nxsdTemplate - The XSD file used to define how the translation is performed.

  • nxsdRoot -The root element defined in the XSD file.

Property IDs:

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

  • namespace-prefix: ora

B.2.57.12 translateFromNativeAttachment

This function translates the input stream to XML.

Signature:

ora:translateFromNativeAttachment('string','nxsdTemplate'?,'nxsRoot'?)

Arguments:

  • string - The data to convert into an XML file.

  • nxsdTemplate - The XSD file used to define how the translation is performed.

  • nxsdRoot - The root element defined in the XSD file.

Property IDs:

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

  • namespace-prefix: ora

B.2.57.13 translateToNativeAttachment

This function translates XML to the native data.

Signature:

ora:translateFromNativeAttachment('string','nxsdTemplate'?,'nxsRoot'?)

Arguments:

  • string - The data to convert into an XML file.

  • nxsdTemplate - The XSD file used to define how the translation is performed.

  • nxsdRoot - The root element defined in the XSD file.

Property IDs:

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

  • namespace-prefix: ora

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.

Signature:

med:doStreamingTranslate('input','streaming xpath context','targetType','attachment element'?)

Arguments:

  • input - The input data of the XPath function. This can be an SDOM or attachment element.

  • streaming xpath context

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

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

Property IDs:

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

  • namespace-prefix: med

Example:

med.doStreamingTranslate($in.request/inp1:request/inp1:sourceAttachmentElement,$in.request/inp1:request/inp1:streamingcontext, 'ATTACHMENT', $in.request/inp1:request/inp1:targetAttachmentElement)

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.

Signature:

med:doTranslateFromNative('input','nxsdTemplate','nxsdRoot','targetType','attachment element'?)

Arguments:

  • input - The input data of the XPath function. The data is in a native format, such as comma-separated values (CSV).

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

  • nxsdRoot - The root element in the NXSD schema.

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

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

Property IDs:

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

  • namespace-prefix: med

Example:

med:doTranslateFromNative(string($in.request/inp1:request/inp1:source),'xsd/address_csv.xsd','Root-Element','DOM')

B.3.3 doTranslateToNative

This function translates the input DOM to a string or attachment. The targetType can be STRING or ATTACHMENT.

Signature:

med:doTranslateToNative('input','nxsdTemplate','nxsdRoot','targetType','attachment element'?)

Arguments:

  • input - The input data of the XPath function. The data can either be DOM or SDOM data that must be translated to a native format such as comma-separated values (CSV).

    The input node is usually the root element of the incoming DOM, as shown in Example B-9.

    Example B-9 Input Node as Root Element in doTranslateToNative Function

    med:doTranslateToNative($in.request/inp1:Root-Element, 'xsd/address_csv.xsd', 
     @ 'Root-Element','STRING')" 
    

    However, the input node can also be a subelement and not the root element of the incoming DOM, as shown in Example B-10.

    Example B-10 Input Node as Subelement in doTranslateToNative Function

    med:doTranslateToNative($in.request/inp1:requestToNative/ns1:Root-Element,
     'xsd/address_csv.xsd', 'Root-Element','ATTACHMENT', 
     $in.request/inp1:requestToNative/inp1:attachment)
    

    In this case, you must set the useArrayIdenitifer property to true in the schema node of the NXSD, as shown below.

    nxsd:useArrayIdentifiers="true" 
    

    This setting can adversely impact the performance of this function for very large inputs. You can use the dostreamingxlate function in this case.

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

  • nxsdRoot - The root element in the NXSD schema.

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

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

Property IDs::

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

  • namespace-prefix: med

Example:

med:doTranslateToNative($in.request/inp1:Root-Element,'xsd/address_csv.xsd','Root-Element','STRING')

B.3.4 getAttachmentContent

This function gets the attachment content and encodes the data into Base64 format.

Signature:

med:getAttachmentContent(xpathExpr)

Arguments:

  • xpathExpr - The XPath expression that references the incoming attachment.

Property IDs::

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

  • namespace-prefix: med

Example:

med:getAttachmentContent($in.bin/bin)

B.3.5 getComponentInstanceID

This function returns the component instance ID.

Signature:

mdhr:getComponentInstanceId()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: mdhr

B.3.6 getComponentName

This function returns the component name.

Signature:

mdhr:getComponentName()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: mdhr

B.3.7 getCompositeInstanceID

This function returns the composite instance ID.

Signature:

mdhr:getComponentInstanceId()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: mdhr

B.3.8 getCompositeName

This function returns the composite name.

Signature:

mdhr:getCompositeName()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: mdhr

B.3.9 getHeader

This function returns the value of an XPath expression from the Oracle Mediator message header.

Note:

The getHeader function works only when both parameters are specified.

Signature:

mdhr:getHeader(xpath as string, namespaces as string)

Arguments:

  • xpath: Refers to the path you traverse from the schema.

  • namespaces: Refers to the abstract container that contains the context of the XPath expression. This argument is not optional. Namespace declarations are in the following form:

    'prefix=namespace;
    

    Note the semicolon after the namespace declaration. For example:

    getHeader("in.header.ns9_name/ns9:name/ns9:first","ns9=http//exmaple.com;")
    

    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.

Property IDs:

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

  • namespace-prefix:mdhr

B.3.10 getECID

This function returns the ECID.

Signature:

mdhr:getECID()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: mdhr

B.3.11 getParentComponentInstanceID

This function returns the Oracle Mediator instance parent component instance ID.

Signature:

mdhr:getParentComponentInstanceId()

Arguments: There are no arguments for this function.

Property IDs:

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

  • namespace-prefix: mdhr

B.3.12 setCompositeInstanceTitle

This function sets a title to the composite instance that can later be used as one of the criteria in searching 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 message payload.

Property IDs:

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

  • namespace-prefix: mdhr

B.3.13 translateFromNativeAttachment

This function translates the input stream to XML.

Signature:

med:translateFromNativeAttachment('input','nxsdTemplate', 'href'?,'nxsdRoot'?)

Arguments:

  • input - The data to convert into an XML file. This can be an attachment or a string.

  • nxsdTemplate - The XSD file used to define how the translation is performed.

  • href - The location of the actual data. This is optional.

  • nxsdRoot - The root element defined in the XSD file. This is optional. If the root is not provided, the root element of the template file specified above is considered; otherwise, the subelement from the template is retrieved.

Property IDs:

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

  • namespace-prefix: med

Example:

med:translateFromNativeAttachment($in.bin/bin, 'xsd/address_csv.xsd', 'myhref-id', 'Root-Element')

B.3.14 translateToNativeAttachment

This function translates XML to the native data.

Signature:

med:translateToNativeAttachment('input','nxsdTemplate','href'?, 'nxsdRoot'?)

Arguments:

  • input - The data to convert into an XML file. The input can be an attachment or a string.

  • nxsdTemplate - The XSD file used to define how the translation is performed.

  • href - The actual location of the data. This is optional.

  • nxsdRoot - The root element defined in the XSD file. This is optional. If the root is not provided, the root element of the template file specified above is considered; otherwise, the subelement from the template is retrieved.

Property IDs:

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

  • namespace-prefix: med

Example:

med:translateToNativeAttachment($in.bin/bin,'xsd/address_csv.xsd','myhref-id','Root-Element')

B.4 Advanced Functions

This section describes the advanced functions.

B.4.1 create-nodeset-from-delimited-string

This function takes a delimited string and returns a nodeSet.

Signature:

oraext:create-nodeset-from-delimited-string(qname, delimited-string, delimiter)

Arguments:

  • qname - The qualified name in which each node in the node set must be created. The QName can be represented in two forms:

    • task:assignee

    • {http://mytask/task}assignee

  • delimited-string - The sting of elements separated by the delimiter.

  • delimiter - The character that separates the items in the input string; for example, a comma or a semicolon.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.4.2 generate-guid

This function generates a unique GUID.

Signature:

oraext:generate-guid()

Arguments: There are no arguments for this function.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.4.3 lookupPopulatedColumns

This function looks up a cross-reference column for a single value or multiple values corresponding to a value in a reference column.

Signature:

xref:lookupPopulatedColumns(tableName,columnName,value,needAnException)

Arguments:

  • xrefTableName: The name of the reference table.

  • xrefColumnName: The name of the reference column.

  • xrefValue: The value corresponding to the reference column name.

  • needAnException: If this value is set to true, then an exception is thrown when no value is found in the referenced column. Otherwise, an empty node set is returned.

Property IDs:

  • namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRefXPathFunctions

  • namespace-prefix: xref

B.4.4 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.

Signature:

dvm:lookupValue(dvmLocation,sourceColumnName,sourceValue,targetColumnName,defaultValue)

Arguments:

  • dvmLocation: The domain value map URI.

  • sourceColumnName: The source column name.

  • sourceValue: The source value (an XPath expression bound to the source document of the XSLT transformation).

  • targetColumnName: The target column name.

  • defaultValue: If the value is not found, then the default value is returned.

  • QualifierSourceColumn: The name of the qualifier column.

  • QualifierSourceValue: The value of the qualifier.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.LookupValue

  • namespace-prefix: dvm

For more information, see Section 44.4.1.1, "dvm:lookupValue."

B.4.5 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 equals the source value.

Signature:

dvm:lookupValue1M(dvmLocation,sourceColumnName,sourceValue,targetColumnName1,targetColumnName2...)

Arguments:

  • dvmMetadataURI - The domain value map URI.

  • SourceColumnName - The source column name.

  • SourceValue - The source value (an XPath expression bound to the source document of the XSLT transformation).

  • TargetColumnName - The name of the target columns. You must specify at least one column name. The question mark symbol (?) indicates that you can specify multiple target column names.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.LookupValue

  • namespace-prefix:dvm

For more information, see Section 44.4.1.2, "dvm:lookupValue1M."

B.4.6 lookupXRef

This function looks up a cross-reference column for a value that corresponds to a value in a reference column.

Signature:

xref:lookupXRef(tableName,referenceColumnName,referenceValue,columnName,needAnException)

Arguments:

  • xrefLocation: The cross-reference URI.

  • xrefReferenceColumnName: The name of the reference column.

  • xrefReferenceValue: The value corresponding to the reference column name.

  • xrefColumnName: The name of the column to be looked up for the value.

  • needAnException: When the value is set to true, an exception is thrown if the value is not found. Otherwise, an empty value is returned.

Property IDs:

  • namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRefXPathFunctions

  • namespace-prefix: xref

For more information, see Section 46.5.1, "About the xref:lookupXRef Function."

B.4.7 lookupXRef1M

This function looks up a cross-reference column for multiple values corresponding to a value in a reference column.

Signature:

xref:lookupXRef1M(tableName,referenceColumnName,referenceValue,columnName,needAnException)

Arguments:

  • xrefLocation: The cross-reference URI.

  • xrefReferenceColumnName: The name of the reference column.

  • xrefReferenceValue: The value corresponding to the reference column name.

  • xrefColumnName: The name of the column to be looked up for the value.

  • needAnException: If this value is set to true, then an exception is thrown when the referenced value is not found. Otherwise, an empty node set is returned.

Property IDs:

  • namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRefXPathFunctions

  • namespace-prefix: xref

For more information, see Section 46.5.2, "About the xref:lookupXRef1M Function."

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.

Signature:

oraext:lookup-xml(docURL, parentXPath, keyXPath, lookupXPath, key)

Arguments:

  • docURL - The XML file.

  • parentXPath - The parent XPath.

  • keyXPath - The key XPath.

  • lookupXPath - The lookup XPath.

  • key - The key value.

Property IDs:

  • namespace-uri: http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc

  • namespace-prefix: oraext

B.4.9 markForDelete

This function deletes a value in a cross-reference table. The value in the column is marked as deleted. This function returns true if the deletion is successful. Otherwise, it 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.

  • xrefValueToDelete: The value to be deleted.

Property IDs:

  • namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRefXPathFunctions

  • namespace-prefix: xref

For more information, see Section 46.6.1, "How to Delete a Cross Reference Table Value."

B.4.10 populateXRefRow

This function populates the column name in the cross-reference table (XREF) in which the reference column has the reference value.

Signature:

xref:populateXRefRow(tableName,referenceColumnName,referenceValue,columnName,value,mode)

Arguments:

  • xrefLocation: The cross-reference URI.

  • xrefReferenceColumnName: The name of the reference column.

  • xrefReferenceValue: The value corresponding to the reference column name.

  • xrefColumnName: The name of the column to be looked up for the value.

  • xrefvalue: The value corresponding to the reference column name.

  • xrefmode: The name of the XREF population mode.

Property IDs:

  • namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRefXPathFunctions

  • namespace-prefix: xref

For more information, see Section 46.4.1, "About the xref:populateXRefRow Function."

B.4.11 populateXRefRow1M

This function populates the column with multiple values in the cross-reference table (XREF) in which the reference column has the reference value.

Signature:

xref:populateXRefRow1M(tableName,referenceColumnName,referenceValue,columnName,value,mode)

Arguments:

  • xrefLocation: The cross-reference URI.

  • xrefReferenceColumnName: The name of the reference column.

  • xrefReferenceValue: The value corresponding to the reference column name.

  • xrefColumnName: The name of the column to be looked up for the value.

  • xrefvalue: The value corresponding to the reference column name.

  • xrefmode: The name of the XREF population mode.

Property IDs:

  • namespace-uri:http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRefXPathFunctions

  • namespace-prefix: xref

For more information, see Section 46.4.2, "About the xref:populateXRefRow1M Function."

B.5 Workflow Service Functions

This section describes the workflow service functions.

B.5.1 clearTaskAssignees

This function clears the current task assignees.

Signature:

hwf:clearTaskAssignees(taskID)

Arguments:

  • task - The task ID of the task.

Property IDs:

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

  • namespace-prefix: hwf

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.

There are two signatures of this function.

Signature 1:

hwf:wfDynamicGroupAssign('patternName','groupName','realmName'?,'patternParam1'?,'patternParam2'?,...,'patternParamN'?)

Argument 1:

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

  • groupName - The name of the group from which to select a subordinate group.

  • realmName - The name of the identity service realm to which the group belongs.

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

Signature 2:

hwf:wfDynamicGroupAssign('patternName','groupList','realmName'?,'patternParam1'?,'patternParam2'?,...,'patternParamN'?)

Argument 2:

  • 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.

There are two signatures for this function.

Signature 1:

hwf:wfDynamicUserAssign('patternName','groupName','realmName'?,'patternParam1'?,....,'patternParam2'?,...,'patternParamN'?)

Arguments 1:

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

  • groupName - The name of the group from which to select a subordinate user.

  • realmName - The name of the identity service realm to which the group belongs.

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

Signature 2:

hwf:wfDynamicUserAssign(patternName,userList,realmName?,patternParam1?,patternParam2?,...,patternParamN?)

Arguments 2:

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

  • userList - The list of users from which to select a user.

  • realmName - The name of the identity service realm to which the users 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.13 Identity Service Functions

This section describes the identity service functions.

B.5.13.1 getDefaultRealmName

This function returns the default realm name.

Signature:

ids:getDefaultRealmName()

Arguments: There are no arguments for this function.

Property IDs:

  • namespace-uri: http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

B.5.13.2 getGroupProperty

This function returns the property value for the given group. If the group or attribute does not exist, it returns null.

Signature:

ids:getGroupProperty(groupName, attributeName, realmName)

Arguments:

  • groupName - String or element containing the group whose attribute must be retrieved.

  • attributeName - String or element containing the name of the group attribute. The name is one of the following values:

    1. displayName

    2. email

    If the identity service uses the LDAP providerType or JAZN LDAP-based providers, configure the LDAP server to enable searching by those attributes.

  • realmName - The realm name. This is optional. If not specified, the default realm is assumed.

Property IDs:

  • namespace-uri: http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

B.5.13.3 getManager

This function gets the manager of a given user. If the user does not exist or there is no manager for this user, it returns null.

Signature:

ids:getManager(userName, realmName)

Arguments:

  • userName - The user name.

  • realmName - The realm name. This is optional. If not specified, the default realm is assumed.

Property IDs:

  • namespace-uri:http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

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.

Property IDs:

  • namespace-uri:http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

B.5.13.5 getSupportedRealmNames

This function returns the supported realm names.

Signature:

ids:getSupportedRealms()

Property IDs:

  • namespace-uri: http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

B.5.13.6 getUserProperty

This function returns the property of the user. If the user or attribute does not exist, it returns null.

Signature:

ids:getUserProperty(userName, attributeName, realmName)

Arguments:

  • userName - String or element containing the user whose attribute must be retrieved.

  • attributeName - The name of the user attribute. The attribute name is one of the following values:

    1. givenName

    2. middleName

    3. sn

    4. displayName

    5. mail

    6. telephoneNumber

    7. homephone

    8. mobile

    9. facsimile

    10. pager

    11. preferredlanguage

    12. title

    13. manager

    If the identity service uses the LDAP providerType or JAZN LDAP-based providers, configure the LDAP server to enable searching by those attributes.

  • realmName - The realm name. This is optional. If not specified, the default realm name is assumed.

Property IDs:

  • namespace-uri: http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

B.5.13.7 getUserRoles

This function gets the user roles. This function returns a list of objects, either application roles or groups, 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.

Property IDs:

  • namespace-uri:http://xmlns.oracle.com/bpel/services/IdentityService

  • namespace-prefix: ids

B.5.13.8 getUsersInGroup

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

Signature:

ids:getUsersInGroup(groupName, direct, realmName)

Arguments:

  • groupName - The group name.

  • direct - A boolean flag. If true, this function returns direct user grantees; otherwise, all user grantees are returned. It can be either an element with value xsd:boolean or string 'true'/'false'.

  • realmName - The realm name. This is optional. If not specified, the default realm name is assumed.

Property IDs:

  • namespace-uri: http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

B.5.13.9 isUserInRole

This function verifies if a user has a given role.

Signature:

ids:isUserInRole(userID, roleName, realmName)

Arguments:

  • userID - A string or element containing the user whose participation in the role must be verified.

  • roleName - The role name.

  • realmName - The realm name. This is optional. If not specified, the default realm name is assumed.

Property IDs:

  • namespace-uri:http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

B.5.13.10 lookupGroup

This function gets the group. If the group does not exist, it returns null.

Signature:

ids:lookupGroup(groupName, realmName)

Arguments:

  • groupName - The group name.

  • realmName - The realm name. This is optional. If not specified, the default realm name is assumed.

Property IDs:

  • namespace-uri:http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

B.5.13.11 lookupUser

This function gets the user object. If the user does not exist, it returns null.

Signature:

ids:lookupUser(userName, realmName)

Arguments:

  • userName - The user name.

  • realmName - The realm name. This is optional. If not specified, the default realm name is assumed.

Property IDs:

  • namespace-uri: http://xmlns.oracle.com/bpel/services/IdentityService/xpath

  • namespace-prefix: ids

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:

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

  2. Select the function (for example, getManager).

  3. Click Insert Into Expression, as shown in Figure B-1.

    Figure B-1 Expression Builder Dialog

    Description of Figure B-1 follows
    Description of "Figure B-1 Expression Builder Dialog"

    This inserts the function into the Expression field at the top.

  4. In the Expression field, place the cursor between the parentheses of the function, as shown in Figure B-2.

    Figure B-2 Placement of Cursor

    Description of Figure B-2 follows
    Description of "Figure B-2 Placement of Cursor"

  5. In the Schema section, expand the schema path to make your selection, as shown in Figure B-3.

    Figure B-3 Selection of Schema

    Description of Figure B-3 follows
    Description of "Figure B-3 Selection of Schema"

  6. Click Insert Into Expression.

    The expression is inserted into the function, as shown in Figure B-4.

    Figure B-4 XPath Expression Creation

    Description of Figure B-4 follows
    Description of "Figure B-4 XPath Expression Creation"

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:

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

  2. 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.

    Figure B-5 provides details.

    Figure B-5 List of Values for Building an Expression

    Description of Figure B-5 follows
    Description of "Figure B-5 List of Values for Building an Expression"

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

  3. Select and double-click the next portion. Figure B-6 provides details.

    Figure B-6 Invocation of Next Portion of Function

    Description of Figure B-6 follows
    Description of "Figure B-6 Invocation of Next Portion of Function"

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

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

  5. Manually add text as appropriate. Figure B-7 provides details.

    Figure B-7 Manual Addition of Text

    Description of Figure B-7 follows
    Description of "Figure B-7 Manual Addition of Text"

Note:

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:

  1. Go to the XSLT Mapper.

  2. From the Component Palette list, select Advanced Functions.

  3. Scroll down the list to the xpath-expression function.

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

    Figure B-8 xpath-expression

    Description of Figure B-8 follows
    Description of "Figure B-8 xpath-expression"

  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, as shown in Figure B-9.

    Figure B-9 List of Values for Building an Expression

    Description of Figure B-9 follows
    Description of "Figure B-9 List of Values for Building an Expression"

  8. Make a selection from the list (for this example, concat(String) as String) in either of the following ways:

    • Scroll down the list and double-click concat(String) as String.

    • Enter the letter c to display only items starting with that letter, then select and double-click concat(String) as String.

    Figure B-10 provides details.

    Figure B-10 Expression List Selection

    Description of Figure B-10 follows
    Description of "Figure B-10 Expression List Selection"

    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.

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

  10. 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.

Figure B-11 Current Argument Name of the Function

Description of Figure B-11 follows
Description of "Figure B-11 Current Argument Name of the Function"

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.

Figure B-12 Syntactically Incorrect XPaths

Description of Figure B-12 follows
Description of "Figure B-12 Syntactically Incorrect XPaths"

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.

Figure B-13 Semantically Incorrect XPaths

Description of Figure B-13 follows
Description of "Figure B-13 Semantically Incorrect XPaths"

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. Figure B-14 provides details.

    Figure B-14 Functionality Description Menu

    Description of Figure B-14 follows
    Description of "Figure B-14 Functionality Description Menu"

  2. Enter free form text (in this example, 'Hello, your telephone number'). Figure B-15 provides details.

    Figure B-15 Free Form Text

    Description of Figure B-15 follows
    Description of "Figure B-15 Free Form Text"

  3. Enter <% when you are ready to invoke the XPath Building Assistant. Figure B-16 provides details.

    Figure B-16 XPath Building Assistant Invocation Preparation

    Description of Figure B-16 follows
    Description of "Figure B-16 XPath Building Assistant Invocation Preparation"

    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. Figure B-17 provides details.

    Figure B-17 XPath Building Assistant Invocation

    Description of Figure B-17 follows
    Description of "Figure B-17 XPath Building Assistant Invocation"

  5. Scroll down the list and double-click the value you want.

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

B.7 Creating User-Defined XPath Extension Functions

You can create user-defined (custom) XPath extension functions for use in Oracle SOA Suite. These functions 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-defined functions.

  • 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 configuration files.

  • A repository hosts user-defined function implementation JAR files and automatically makes them available 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 all components can be created in a configuration file named ext-soa-xpath-functions-config.xml. Note that you must implement XSLT Mapper functions differently than Oracle BPEL Process Manager, Oracle Mediator, and human workflow functions.

    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 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-11 shows the function schema used by system and user-defined functions.

Example B-11 Function Schema

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
 xmlns:tns="http://xmlns.oracle.com/soa/config/xpath" 
 targetNamespace="http://xmlns.oracle.com/soa/config/xpath"
 elementFormDefault="qualified">
      <element name="soa-xpath-functions" type="tns:XpathFunctionsConfig"/>
      <element name="function" type="tns:XpathFunction"/>
      <complexType name="XpathFunctionsConfig">
            <sequence>
               <element ref="tns:function" minOccurs="1" maxOccurs="unbounded"/>
            </sequence>
            <attribute name="resourceBundle" type="string"/>
            <attribute name="version" type="string"/>
      </complexType>

      <complexType name="XpathFunction">
            <sequence>
                 <element name="className" type="string"/>
                 <element name="return">
                         <complexType>
                                 <attribute name="type" type="tns:XpathType"
                                     use="required"/>
                         </complexType>
                 </element>
                 <element name="params" type="tns:Params" minOccurs="0"
                         maxOccurs="1"/>
                 <element name="desc">
                         <complexType>
                                 <simpleContent>
                                         <extension base="string">
                                                 <attribute name="resourceKey"
                                                     type="string"/>
                                         </extension>
                                 </simpleContent>
                         </complexType>
                 </element>
                 <element name="detail" minOccurs="0">
                         <complexType>
                                 <simpleContent>
                                         <extension base="string">
                                                 <attribute name="resourceKey"
                                                      type="string"/>
                                         </extension>
                                 </simpleContent>
                         </complexType>
                 </element>
                 <element name="icon" minOccurs="0">
            <complexType>
                     <simpleContent>
                              <extension base="string">
                                    <attribute name="resourceKey"
                                       type="string"/>
                              </extension>
                     </simpleContent>
             </complexType>
        </element>
                      <element name="helpURL" minOccurs="0">
             <complexType>
                      <simpleContent>
                              <extension base="string">
                                    <attribute name="resourceKey"  
                                       type="string"/>
                              </extension>
                      </simpleContent>
              </complexType>
        </element>
        <element name="group" minOccurs="0">
              <complexType>
                      <simpleContent>
                              <extension base="string">
                                   <attribute name="resourceKey" type="string"/>
                              </extension>
                      </simpleContent>
              </complexType>
        </element>
        <element name="wizardClass" type="string" minOccurs="0"/> 
</sequence>
<attribute name="name" type="string" use="required"/>
               <attribute name="deprecated" type="boolean" use="optional"/>
</complexType>

      <complexType name="Params">
      <sequence>
              <element name="param" minOccurs="1" maxOccurs="unbounded">
                      <complexType>
                           <attribute name="name" type="string" use="required"/>
                           <attribute name="type" type="tns:XpathType"
                                 use="required"/>
                           <attribute name="minOccurs" type="string"
                                 default="1"/>
                           <attribute name="maxOccurs" type="string"
                                 default="1"/>
                           <attribute name="wizardEnabled" type="boolean"
                                 default="false"/>
                      </complexType>
              </element>
       </sequence>
  </complexType>
  <simpleType name="XpathType">
       <restriction base="string">
               <enumeration value="string"/>
               <enumeration value="boolean"/>
               <enumeration value="number"/>
               <enumeration value="node-set"/>
               <enumeration value="tree"/>
       </restriction>
  </simpleType>
</schema>

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 Suite components.

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.

For additional details about creating a user-defined XPath extension function for the XSLT Mapper, see Section 38.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 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:

  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 shown in Example B-12:

    Example B-12 Implementation of oracle.fabric.common.xml.xpath.IXPathFunction

     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-13, a function named getNodeValue(arg1) is implemented that gets a value of w3c node:

    Example B-13 Implementation of getNodeValue(arg1) Function

    package com.collaxa.cube.xml.xpath.dom.functions;
     import oracle.fabric.common.xml.xpath.IXPathFunction;
     import oracle.fabric.common.xml.xpath.IXPathFunction
     . . .
    
     public class GetNodeValue implements IXPathFunction {
        Object call(IXPathContext context, List args) throws XPathFunctionException
     {
            org.w3c.dom.Node node = (org.w3c.dom.Node) args.get(0);
            return node.getNodeValue()
        }
     }
    

B.7.2 How to Configure User-Defined XPath Extension Functions

This section describes how to configure user-defined XPath extension functions.

To configure user-defined XPath extension functions:

  1. Create an XPath extension configuration file in which to define the function. Example B-14 shows a sample configuration file that follows the function schema shown in Example B-11 of Section B.7, "Creating User-Defined XPath Extension Functions." In this example, two functions are created: mf:myFunction1 and mf:myFunction2.

    Example B-14 Sample XML Extension Configuration File

    <?xml version="1.0" encoding="UTF-8"?>
    <soa-xpath-functions resourceBundle="myPackage.myResourceBundle"
     xmlns="http://xmlns.oracle.com/soa/config/xpath"
     xmlns:mf="http://www.my-functions.com">
      <function name="mf:myFunction1">
        <className>myPackage.myFunctionClass1</className>
        <return type="node-set"/>
        <params>
          <param name="p1" type="node-set" wizardEnabled="true"/>
          <param name="p2" type="string"/>
          <param name="p3" type="number" minOccurs="0"/>
          <param name="p4" type="boolean" minOccurs="0"  maxOccurs="3"/>
        </params>
        <desc resourceKey="func1-desc-key">this is my first function</desc>
        <detail resourceKey="func2-long-desc-key">my first function does ... </detail>
        <icon>myPackage/resource/image/myFunction1.png</icon>
        <group resourceKey="func-group-key">My Function Group</group>
        <wizardClass>myPackage.myWizardClass1</wizardClass>
      </function>
      <function name="mf:myFunction2">
        <className>myPackage.myFunctionClass2</className>
        <return type="string"/>
        <params>
          <param name="p1" type="node-set" wizardEnabled="true"/>
          <param name="p2" type="string"/>
          <param name="p3" type="number" minOccurs="0"/>
          <param name="p4" type="boolean" minOccurs="0"  maxOccurs="unbounded"/>
        </params>
        <desc resourceKey="func2-desc-key">this is my second function</desc>
        <detail resourceKey="func2-long-desc-key">my second function does ...</detail>
        <icon>myPackage/resource/image/myFunction2.png</icon>
        <group resourceKey="func-group-key">My Function Group</group>
        <wizardClass>myPackage.myWizardClass2</wizardClass>
      </function>
    </soa-xpath-functions>
    

    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.


  2. 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


  3. 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.
  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

The soa/modules/oracle.soa.ext_11.1.1 directory is provided for adding custom JAR files and classes. For information, see Section 13.3, "Adding Custom Classes and JAR Files."