In the message flow of a proxy service, 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.
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 22-1 shows an example.
Figure 22-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 Section 20.1, "Viewing and Editing Message Flows." and Section 21.1, "Adding and Editing Actions in Message Flows."
To create or modify an inline expression
On the Edit Stage Configuration page, locate the place in the action where you want to add or edit the expression.
Click the expression link to open the editor that is appropriate for the context. When an expression has not yet been defined, the link tells what kind of expression you can use in that position:
Click Expression to create an XQuery expression.You can also import an XQuery or XSLT resource created outside Oracle Service Bus, then bind it to the inline XQuery.
Click Condition to create an XQuery conditional expression for an if..then... action.
Click XPath to create an XPath expression for a message context variable.
When an expression has already been defined in a position, the Expression, Condition, or XPath link is replaced by a link that shows expression itself, for example true()
icon, or a fragment of the expression it is too long to fit, for example $body/urn:POSta...
icon. Click the expression (or expression fragment) to open the expression in the appropriate editor.
Build the expression, as described in the following topics:
Section 22.3, "Building Expressions in the Editor Workspace Text Fields"
Section 22.4, "Creating Namespaces to Use in Inline Expressions"
Section 22.5, "Creating Variable Structures in the XQuery Editors"
Section 22.6, "Creating Custom XPath Functions in the XQuery Editors"
Section 22.7, "Binding External XQuery Resources to Inline XQueries"
Section 22.8, "Binding External XSLT Resources to Inline XQueries"
Section 22.9, "Binding Dynamic XQuery Expressions to Inline XQueries"
Section 22.10, "Entering XQuery Comparison Expressions Using the Builder Option"
Section 22.11, "Entering Unary Expressions Using the Builder Option"
Optionally, do either or both of the following:
Click Validate to validate the expression.
Click Test to test the expression. See Section 32.3, "Performing XQuery Testing."
Click Save to close the editor and insert the expression in the action.
After you finish
Continue configuring the action, as described in Section 21.1, "Adding and Editing Actions in Message Flows."
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 Oracle 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.Oracle 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 Section 22.3, "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 Section 22.1, "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 Section 22.7, "Binding External XQuery Resources to Inline XQueries" and Section 22.8, "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 22-1, below.
Palette | Description and Use |
---|---|
Namespace Definitions |
Lists default Oracle 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 Section 22.4, "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. Expand or collapse nodes in the tree by clicking the plus sign (+) or minus sign (-). See also:
|
Variable Structures |
Displays variables and their contents as trees, which can help you to visualize. To display a variable structure and its contents
You can also define your own variable structures. See Section 22.5, "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. |
Paste the desired item into the text field using any of the methods shown below in Table 22-2:
Table 22-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 Section 32.3, "Performing XQuery Testing."
Click Save to close the editor and insert the expression in the action.
After you finish
Continue configuring the action, as described in Section 21.1, "Adding and Editing Actions in Message Flows."
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 Section 22.1, "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 Section 22.1, "Creating and Editing Inline XQuery and XPath Expressions."
After you finish
Continue as described in Section 22.1, "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 Section 22.1, "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 22-3.
Table 22-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 Section 22.1, "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 and Using Custom XPath Functions" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.
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 Expression Editor, XQuery Condition Editor, or XPath Expression Editor, as described in Section 22.1, "Creating and Editing Inline XQuery and XPath Expressions."
To bind an XQuery Resource to an inline expression:
Click Variable Structures.
In the workspace (under the button bar), select XQuery Resources.
In the 1. Select an XQuery resource to execute box, click Browse.
In the XQuery Browser, select the radio button associated with the XQuery you want to use, then click Submit.
In the 2. Bind Variables box, define the input parameters for the transformation. For each variable listed under Variable Name enter an XQuery expression to be mapped to it. You must define a mapping for each parameter. For example, if an XQuery transformation has two input parameters named one and two, the Variable Name field has two labels—one and two. A text box, into which the XQuery expression is entered, is associated with each label.
The following XQuery expressions are examples of valid input to this field:
$body/*[1] $body/po:PurchaseOrder
Note:
The following variable name is not a valid entry for this field and results in an exception:body
.After you finish, continue with any of the following tasks.
Click Validate. A message is displayed if the expression is validated successfully.
Click Test. See Section 32.3, "Performing XQuery Testing."
Save or discard your changes.
The XQuery Expression Editor page allows you to select an XSLT resource for execution. To learn more about this editor, see Section 22.1, "Creating and Editing Inline XQuery and XPath Expressions."
To Select an XSLT Resource for Execution
Select the XSLT Resources option.
Under the Select the XSLT resource to execute field, select the XSLT Browser icon.
In the XSLT Browser, select the radio button associated with the XSLT you want to execute, then click Submit.
Under the Bind Variables field, a label and a corresponding text box is displayed for each input parameter of the transformation. Each label corresponds to the name of a parameter, and each text box is for defining an XQuery expression to be mapped to the parameter. You must define a mapping for each parameter. For example, if an XSL transformation has two input parameters named one and two, the Variable Mapping field has two labels—one and two—with a text box associated with each into which the XQuery expression is entered. In addition to the mapping for any input variables, you must also specify an XQuery expression for the Input Document to the transformation. The mapping is specified in the text box with the label Input Document.
The following XQuery expressions are examples of valid input to this field:
$body/*[1] $body/po:PurchaseOrder
Note:
The following variable name is not a valid entry for this field and results in an exception:body
.Continue with any of the following tasks:
Section 22.4, "Creating Namespaces to Use in Inline Expressions"
Section 22.5, "Creating Variable Structures in the XQuery Editors"
Section 22.3, "Building Expressions in the Editor Workspace Text Fields"
Section 22.7, "Binding External XQuery Resources to Inline XQueries"
Click Validate. A message is displayed if the expression is validated successfully.
Click Test. See Section 32.3, "Performing XQuery Testing."
The XQuery 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 Section 22.1, "Creating and Editing Inline XQuery and XPath Expressions."
To define a dynamic XQuery expression
Select the Dynamic XQuery option.
In the Enter Expression for XQuery Resource area, enter the XQuery expression that will evaluate at runtime to the name of a pre-registered XQuery resource.
The following shows the syntax for the XQuery resource (representing the full name of the resource):
Project/folder1/folder2/XQueryResourceName
In the Bind Variables using XQuery Template of Custom Variables area, define the input parameters for the transformation.
Click Browse in the Select XQuery Template field to select an existing registered resource to serve as a template for the shape of the query (the number and names of the variables). After selecting a template, the variables appear in the Bind Variables area. Note that the template is not persisted with the configuration. Instead, the template serves as a quick start to help you specify the variables for the query.
Type a variable name in the Add Custom Variable field, and click Add. For each variable listed under Variable Name, enter an XQuery expression to be mapped to it. You must define a mapping for each parameter. For example, if an XQuery transformation has two input parameters named one and two, the Variable Name field has two labels—one and two. A text box, into which the XQuery expression is entered, is associated with each label.
The following XQuery expressions are examples of valid input to the variable fields:
$body/*[1] $body/po:PurchaseOrder
After you finish, continue with any of the following tasks.
Click Validate. A message is displayed if the expression is validated successfully.
Click Test. See Section 32.3, "Performing XQuery Testing."
Save or discard your changes.
Before you begin
These instructions assume you are creating or editing an XQuery conditional expression in the XQuery Condition Editor, as described in Section 22.1, "Creating and Editing Inline XQuery and XPath Expressions."
To enter an XQuery comparison expression:
In the XQuery Condition Editor, select Builder (located under the workspace button bar), if it is not already selected. option.
In the Expression Builder box, select Comparison Expression if it is not already selected.
In the Operand field, enter a context variable, namespace definition, or XQuery function.
To build the operand, you can paste XQuery functions from the XQuery Functions palette and namespaces from the Namespace Definitions palette. See Section 22.3, "Building Expressions in the Editor Workspace Text Fields."
From the Operator list, select a comparison operator.
In the Value field, enter text or enter a context variable.
You must enter text in quotations—for example, "true"
is valid; true
is not.
Click Add. The text you entered is displayed in the Expressions pane.
Repeat steps 3-6 to build additional conditions. Each condition is added to the end of the list of conditions.
Consider the following when using multiple conditions:
When you build additional expressions, make sure to select the And or the Or options in the Conjunction field.
You can select a condition and click the Up arrow to move it up in the list of conditions or click the Down arrow to move it down the list of conditions. You can also click the Edit icon to update a condition, or click the Delete icon to delete it.
Unary expressions may be intermixed with Comparison expressions in the overall definition of a condition.
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 Section 32.3, "Performing XQuery Testing."
Click Save to close the editor and insert the expression in the action.
After you finish
Continue configuring the action, as described in Section 21.1, "Adding and Editing Actions in Message Flows."
Before you begin
These instructions assume you are creating or editing an XQuery conditional expression in the XQuery Condition Editor, as described in Section 22.1, "Creating and Editing Inline XQuery and XPath Expressions."
To enter an XQuery comparison expression:
In the XQuery Condition Editor, select Builder (located under the workspace button bar), if it is not already selected. option.
In the Expression Builder box, select Unary Expression if it is not already selected.
Select the Not check box to make this a negative expression, or leave it blank.
Enter a context variable, namespace definition or XQuery function in the Expression field.
To build the expression, you can paste XQuery functions from the XQuery Functions palette and namespaces from the Namespace Definitions palette. See Section 22.3, "Building Expressions in the Editor Workspace Text Fields."
Click Add to add the text to the Expressions pane.
Repeat steps 3-5 to build additional conditions. Each condition is added to the end of the list of conditions.
Consider the following when building unary expressions.
When you build additional expressions, make sure to select the And or the Or options in the Conjunction field.
You can select a condition and click the Up arrow to move it up in the list of conditions, click the Down arrow to move it down the list of conditions, click the Edit icon to update it, or click the Delete icon to delete it.
Unary expressions may be intermixed with Comparison expressions in the overall definition of a condition.
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 Section 32.3, "Performing XQuery Testing."
Click Save to close the editor and insert the expression in the action.
After you finish
Continue configuring the action, as described in Section 21.1, "Adding and Editing Actions in Message Flows."