Designer > POJO and XQuery Custom Functions > Writing XQuery Functions

Writing XQuery Functions

Process Developer integrates the XQuery Development Tools (XQDT) project. Using it, you can create XQuery custom functions in your orchestration project that are automatically included in the functions list of the Expression Builder.

XQDT includes an XQuery editor with syntax highlighting, validation, content assistance, and execution support. You can easily create and test XQuery functions in the editor before using them within the Process Developer Expression Builder. Also, you can make changes to a function and save it. The updates are automatically included in your BPEL file.

Each function must be part of a library module in order for it to be included in the Expression Builder. You can create a module of functions in one XQuery file and then use the functions defined in that module in any other XQuery by using the import module directive.

XQDT supports XQuery 1.0 and many XQuery 3.0 constructs.

After you double-click in the functions section of the expression builder to add an XQuery function, the XQuery file is added as an import. You should pay attention to what XQuery files are referred to as imports in the BPEL process and make sure that there are no duplicates between that list and what they explicitly add as imports in the XQuery files that use the import module.

If you have an existing project (prior to version 9.0), right-mouse click on the project in the Project Explorer, and select Add XQuery Nature.

To get started creating an XQuery function:

1. Right-mouse click on the xquery folder (or another folder) in your orchestration project, and select New > XQuery Module.
2. Name the file with a .xq extension, such as myNewFunctionModule.xq.
3. Select one of the following:

- Main module. Contains a query body to be evaluated
- Library module. Contains a module declaration but no query body. A module declaration provides a URI that identifies the module for imports. Enter a prefix and namespace for the module declaration.

4. Select Finish, and the XQuery editor opens. Use content assist (Ctrl + spacebar) to begin a new function.

The following example shows the module declaration for a library module. This declaration is required for an XQuery function to appear in the Functions list:

(: The version declaration in line one is optional.
Version 1.0 does not allow any use of version 3.0 constructs. :)
xquery version "1.0" encoding "utf-8";
module namespace xqf= "TechSupportLevel1";
declare function xqf:pingModemResult ((: $param as type, ... :)) as item() {
insert_an_expression_here
};

Once you save your XQuery file, the function is automatically available in the Expression Builder, as shown.

As you use a function, the corresponding XQuery module is automatically added to the process's Imports node.

Tip: In the Outline view, select the function under Imports to view its properties. If you run B-unit tests, you can add the XQuery modules as a resource and specify the Type URI as shown.

Using the XQuery Editor

The XQuery Editor opens when you create or open a file with a .xq extension. Note the following features:

•The editor contains a content assist feature, allowing you to select CTRL + Space to open a list of XQuery constructs, system expressions, and your own functions that exist in modules imported into the open file.
•Syntax highlighting shows various elements of XQuery expressions
•Validation occurs automatically and errors are reported
•Run As features are available for executing local scripts to test your expressions. Refer to Testing XQuery Functions in the XQuery Editor.
•You can set preferences for syntax highlighting and other features in the XQuery section of Preferences.

Tips on Writing XQuery Functions

Process Developer supports all XQuery 1.0 constructs and some XQuery 3.0 constructs, such as:

•Group by
•Try-Catch
•Formatting functions for date, dateTime, time, and number

In order to use XQuery 3.0 constructs, be sure to add the following declaration to your files:

xquery version "3.0";

Process Developer uses Saxon as the XQuery processor. If you are in doubt about support for a particular XQuery 3.0 construct, refer to the following at the Saxon Web site, which is at http://www.saxonica.com/documentation9.3/changes/intro.xml.

Testing XQuery Functions in the XQuery Editor

You can write a test script for your functions and execute the script in the XQuery Editor. Process Developer provides a default interpreter for script execution.

For example, create a new .xq file, and write a simple test script where you hard-code a function argument as in the Kitty argument below:

xquery version "1.0" encoding "utf-8";
import module namespace xyz ="myFunctions" at "hello.xq";
xyz:sayHello('Kitty')

To run this script, right-mouse click in the editor and select Run As > XQuery.

Passing an External Value to a Test Script

If the test script has external variables defined, values for those variables can be passed as arguments from the Run As launch configuration. The following is a simple script that takes in an external variable, followed by a description of how to create the script argument:

xquery version "1.0" encoding "utf-8";
import module namespace xyz ="myFunctions" at "hello.xq";
declare variable $ip as xs:string external;
xyz:sayHello($ip)

Create a Run As Configuration:

1. Right-mouse click in the editor and select Run As > Run Configurations.
2. Select New, and add your project name and test script name on the first page.
3. On the Arguments page, add a Script Argument, such as ip="Kitty".
4. Run your named configuration.

Customizing the Interpreter Behavior

Process Developer includes a default Saxon interpreter. You can change the arguments to this interpreter by selecting Preferences > XQuery > Interpreters.

You can configure the default Process Developer interpreter by double-clicking it. Interpreter arguments can be changed based on the development needs. Documentation for the arguments can be found at http://www.saxonica.com/documentation/using-xquery/commandline.xml.

Do not change the first argument, which is the class name, org.activebpel.rt.bpel.ext.expr.impl.xquery.AeQuery.