This chapter describes how to use XQuery and XPath expressions in pipelines, or message flows.
In the pipeline, you can assign XQuery expressions to message context variables, assign if-then actions based on the Boolean result of an XQuery expression, insert the result of an XQuery expression at an identified place relative to an XPath expression, specify the message context that you want to log through XQuery expressions on context variables, and so on.
The XQuery Expression Editor, the XQuery Condition Editor, and the XPath Expression Editor are available in the appropriate context in message flows to construct the kind of expression called for in the context.
This chapter contains the following sections:
When you add actions to stages or route nodes on the Edit Stage Configuration page, a skeleton structure is displayed on the page that prompts for configuration details. Figure 15-1 shows an example.
Figure 15-1 Example of Action Configuration Skeleton
Whenever it is appropriate for the context, the skeleton provides links for accessing the XQuery editors, where you can construct expressions that will be executed inline, as required by the context in the action.
Before you begin:
These instructions assume you are creating or editing an action in the Edit Stage Configuration page of a pipeline stage, an error handler stage, or a route node. See Viewing and Editing Pipelines in the Console. and Adding and Editing Pipeline Actions in the Console.
To create or modify an inline expression:
The XQuery Expression Editor, the XQuery Condition Editor, and the XPath Expression Editor are each composed of the following components:
The left panel of the each editor contains the palettes listed below. In any of the editors, click the name of a palette to display it. Each palette contains entities that you can insert into expressions in the editors.
The Namespace Definitions palette lists default Service Bus namespaces, variable namespaces, and user-defined namespaces. You can define new namespaces, which are then added to the list of user-defined namespaces.
For more information, see:
The XQuery Functions palette lists a set of standard XQuery functions.When you insert a function into an expression, placeholders are used for parameter values you must supply.
For more information, see:
The Variable Structures palette provides a set of tools for inserting variables and paths to the variables, using XPath expressions.
Variable structures are graphical representations of variables or variable paths that are displayed in the editor. They can help you visualize the variable structure, and you can use them to construct inline XQuery expressions that reference the content of the variable.
Note:
Variable structures do not create variables. Variables are created at runtime as the target of the Assign action in the stage.
Service Bus provides several predefined message context variables (attachments
, body
, header
, outbound
, and inbound
), whose contents you can display as variable structures. You can also define your own variable structures.
For more information, see
The right side of the page provides a workspace for constructing the XQuery expression, XQuery condition, or XPath. The workspace is different in the three editors.
In all three editors, the Property Inspector is displayed on the bottom right of the page. When you select an item from one of the palettes to add to the expression, that item appears in the Property Inspector. You can then paste the item into the workspace. See Building Expressions in the Editor Workspace Text Fields.
The XQuery Expression Editor, the XQuery Condition Editor, and the XPath Expression Editor all provide text fields in which you can build expressions by typing directly or by pasting items from the palettes.
Before you begin:
These instructions assume you are creating or editing an expression in the XQuery Expression Editor, XQuery Condition Editor, or XPath Expression Editor, as described in Creating and Editing Inline XQuery and XPath Expressions.
To build an expression in a text field:
Display the panel containing the text field. Depending on the editor, do one of the following:
In the XQuery Expression Editor, select XQuery Text (located under the workspace button bar), if it is not already selected.
In the XQuery Condition Editor, select Text (located under the workspace button bar), if it is not already selected.
In the XPath Expression Editor, you do not have to select anything, because there are no options for selecting other tools.
Note:
Selecting any of the above links displays a text field where you can create a complete expression appropriate for the context. However, the tools and techniques described in this topic can be used wherever text fields are provided in the editors, for example when binding variables from imported resources to the inline expression, as described in Binding External XQuery Resources to Inline XQueries and Binding External XSLT Resources to Inline XQueries.
If desired, type or paste an expression or expression fragment into the field. If you create the complete expression this way, skip to step 7, below. Otherwise, proceed to the next step.
Select the palette containing the item(s) you want to add to the expression, and locate the item you want to add, as described in Table 15-1, below.
Table 15-1 Palettes
Palette | Description and Use |
---|---|
Namespace Definitions |
Lists default Service Bus namespaces, variable namespaces, and user-defined namespaces. Namespace abbreviations are listed when defined. Scroll through the lists to find the desired namespace. You can also define a namespace. See Creating Namespaces to Use in Inline Expressions . |
XQuery Functions |
Contains a set of standard XQuery functions, organized alphabetically and by type, including any custom functions you have developed. To expand or collapse nodes in the tree, click the plus sign (+) or minus sign (-). See also: |
Variable Structures |
Displays variables and their contents as trees, which can help you to visualize. You can view a variable structure and its contents.
You can also define your own variable structures. See Creating Variable Structures in the XQuery Editors. Variable structures do not create variables. Variables are created at runtime as the target of the Assign action in the stage. When you insert an item from the a variable structure tree into the text field, it is inserted as an XPath expression that describes the path. See also Transforming Data with XQuery. |
Paste the desired item into the text field using any of the methods shown below in Table 15-2:
Table 15-2 Ways to Paste Items Into the Editor Text Fields
From this palette... | Do this... |
---|---|
Namespace Definitions palette |
Use standard mouse or keyboard select, copy, and paste a namespace, for example:
|
XQuery Functions palette or Variable Structures palette |
Drag an item from the palette to the text field. Note: Dragging from the palette to the workspace is supported only in Internet Explorer. |
XQuery Functions palette or Variable Structures palette |
|
XQuery Functions palette or Variable Structures palette |
|
Continue to drag and drop functions to build the desired expression.
Edit the expression in the text field, as needed.
Optionally, do either or both of the following:
Click Validate. A message is displayed if the expression is validated successfully.
Click Test to test the expression. See XQuery Transformation Testing Prerequisites and Guidelines.
Click Save to close the editor and insert the expression in the action.
The Namespace Definitions palette includes a list of default namespaces, but you can also define new ones.
Before you begin:
These instructions assume you are creating or editing an expression in the XQuery Expression Editor, XQuery Condition Editor, or XPath Expression Editor, as described in Creating and Editing Inline XQuery and XPath Expressions.
To create and use a namespace in an inline expression:
Select Namespace Definitions. The Namespace Definitions palette includes a list of default namespaces, plus lists of variable namespaces and user defined namespaces, if any exist.
To define and add a user namespace,
Click Add Namespace.
In the Prefix field, enter a unique identifier for the namespace. You cannot use the same prefix more than once.
In the URI field, enter a URL for this namespace in the format http://url/.../
or enter a URN in the format uddi:server:
.
Click Add to add the namespace to the User Defined Namespaces list.
Copy and paste the user-defined namespace into the XQuery expression, XQuery condition, or XPath, as described in Creating and Editing Inline XQuery and XPath Expressions.
After you finish:
Continue as described in Creating and Editing Inline XQuery and XPath Expressions.
The Variable Structures palette in the XQuery and XPath editors displays graphical representations of the contents of variables. It includes by default the built-in message context variables attachments
, body
, header
, outbound
, and inbound
.
Each variable structure mapping entry has a label and maps a variable or variable path to one or more structures. The scope of these mappings is a stage or a route node.
You can also declare your own variable structures, based on:
XML types, including:
Schema elements
WSDL elements
Schema types
WSDL types
MFLs
Service interfaces
Simple types (string or any XML)
You can use this feature directly for all user-defined variables, as well as $inbound
, $outbound
, and $fault
. However, you cannot use it directly to access XML attachments in $attachments
, headers in $header
, or documents and RPC parameters in $body
, with one exception— you can use it directly to access documents and parameters in $body
for request messages received by a WSDL proxy service.
Before you begin:
These instructions assume you are creating or editing an expression in the XQuery Expression Editor, XQuery Condition Editor, or XPath Expression Editor, as described in Creating and Editing Inline XQuery and XPath Expressions.
To create a variable structure:
Select Variable Structures.
In the Variable Structures palette, click Add New Structure.
Continue with any of the tasks listed in Table 15-3.
Table 15-3 Create a New Variable Structure
To... | Complete these steps... |
---|---|
Create a variable structure that maps a variable to an XML Schema type |
|
Create a variable structure that maps a variable to a WSDL type |
|
Create a variable structure that maps a variable to an XML Schema element |
|
Create a variable structure that maps a variable to a WSDL element |
|
Create a variable structure that maps a variable to a child element |
|
Create a variable structure that uses an MFL resource |
|
Create a Service Interface variable structure |
The service you selected is displayed in the WSDL Based Service field.
|
Create a Simple variable structure |
|
After you finish:
Continue as described in Creating and Editing Inline XQuery and XPath Expressions.
Creating custom XQuery functions is a development process that requires writing Java code. For more information, see Creating Custom XPath Functions.
You can bind XQuery resources to inline XQuery expressions, so they will be executed inline as part of an action.
Before you begin:
These instructions assume you are creating or editing an expression in the XQuery/XSLT Expression Editor, XQuery Condition Editor, or XPath Expression Editor, as described in Creating and Editing Inline XQuery and XPath Expressions.
To bind an XQuery Resource to an inline expression:
The XQuery/XSLT Expression Editor page allows you to select an XSLT resource for execution. To learn more about this editor, see Creating and Editing Inline XQuery and XPath Expressions.
To Select an XSLT Resource for Execution
The XQuery/XSLT Expression Editor page allows you to specify a dynamic XQuery expression that evaluates at runtime to the name of a pre-registered XQuery resource. To learn more about this editor, see Creating and Editing Inline XQuery and XPath Expressions.
To define a dynamic XQuery expression
The XQuery/XSLT Expression Editor page allows you to specify a dynamic XPath/XQuery expression that evaluates at runtime to the name of a pre-registered XSLT resource. To learn more about this editor, see Creating and Editing Inline XQuery and XPath Expressions.
To define a dynamic XSLT expression
Before you begin:
These instructions assume you are creating or editing an XQuery conditional expression in the XQuery Condition Editor, as described in Creating and Editing Inline XQuery and XPath Expressions.
To enter an XQuery comparison expression:
After you finish:
Continue configuring the action, as described in Adding and Editing Pipeline Actions in the Console.
Before you begin:
These instructions assume you are creating or editing an XQuery conditional expression in the XQuery Condition Editor, as described in Creating and Editing Inline XQuery and XPath Expressions.
To enter an XQuery comparison expression: