1. Developing Services with Oracle Service Bus
  2. Working with Oracle Service Bus Pipelines
  3. Working With Expression Editors in Oracle Service Bus Console

15 Working With Expression Editors in Oracle Service Bus Console

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:

15.1 Creating and Editing Inline XQuery and XPath Expressions

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

Description of Figure 15-1 follows
Description of "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.

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:

  1. On the Edit Stage Configuration page, locate the place in the action where you want to add or edit the expression.
  2. 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 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.

  3. Build the expression, as described in the following topics:
  4. Optionally, do either or both of the following:
  5. Click Save to close the editor and insert the expression in the action.

15.2 Understanding XQuery Editor Layouts and Tasks

The XQuery Expression Editor, the XQuery Condition Editor, and the XPath Expression Editor are each composed of palettes, a workspace, and a property inspector.

For more information, follow the links below.

15.2.1 Palettes

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.

15.2.2 Workspace

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.

15.2.3 Property Inspector

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.

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

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:

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

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

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

    • Select the name of the structure from the list at the top of the palette. The list displays Built-in message context variables (attachments, body, header, outbound, and inbound), as well as any user-defined structures, organized by type (XML Type, Service Interface, and Simple Type).

    • To expand or collapse nodes in the tree, click the plus sign (+) or minus sign (-).

    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.

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

    1. Select the entire namespace string (or its abbreviation, if one exists) by dragging the mouse pointer over the string.

    2. Press Ctrl-C to copy the string.

    3. Click the location in the text field where you want to insert the namespace.

    4. Press Ctrl-V to paste the string.

    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

    1. Click an item in the palette. The item is displayed in the Property Inspector pane:

      Functions are displayed with placeholders for any values you have to supply.

      Variables and their attributes are displayed as XPath expressions.

    2. Click in the text field where you want to insert the item

    3. Click Copy Property to paste the item into the location selected in the text field.

    XQuery Functions palette or Variable Structures palette

    1. Click an item in the palette. The item is displayed in the Property Inspector pane.

    2. Select and copy the item in the Property Inspector, using standard keyboard or mouse actions.

    3. Select a location in the text field, and paste the item into the text field, using standard keyboard or mouse actions.

  5. Continue to drag and drop functions to build the desired expression.

  6. Edit the expression in the text field, as needed.

  7. Optionally, do either or both of the following:

  8. Click Save to close the editor and insert the expression in the action.

15.4 Creating Namespaces to Use in Inline Expressions

The Namespace Definitions palette includes a list of default namespaces, but you can also define new ones.

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:

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

  2. To define and add a user namespace,

    1. Click Add Namespace.

    2. In the Prefix field, enter a unique identifier for the namespace. You cannot use the same prefix more than once.

    3. In the URI field, enter a URL for this namespace in the format http://url/.../ or enter a URN in the format uddi:server:.

    4. Click Add to add the namespace to the User Defined Namespaces list.

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

Continue as described in Creating and Editing Inline XQuery and XPath Expressions.

15.5 Creating Variable Structures in the XQuery Editors

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.

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:

  1. Select Variable Structures.

  2. In the Variable Structures palette, click Add New Structure.

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

  1. Select XML Type at the top of the Variable Structures palette, if it is not already selected.

  2. In the Structure Label field, enter a display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at runtime.

  3. In the Structure Path field, enter the path of the variable structure at runtime. The path must begin with $.

  4. Under the Type field, select the appropriate radio button, then select Schema Type.

  5. Click Browse. The XML Schema Browser is displayed. Select an XML Schema from the list, select an XML Schema type from the Definitions pane, then click Submit.

  6. Click Add to create the variable structure.

Create a variable structure that maps a variable to a WSDL type

  1. Select XML Type at the top of the Variable Structures palette, if it is not already selected.

  2. In the Structure Label field, enter a display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at runtime.

  3. In the Structure Path field, enter the path of the variable structure at runtime.

  4. Under the Type field, select the appropriate radio button, then select WSDL Type.

  5. Click Browse. The WSDL Browser is displayed. Select a WSDL file from the list of WSDL files, select a WSDL type from the Definitions pane, then click Submit.

  6. Click Add to create the variable structure.

Create a variable structure that maps a variable to an XML Schema element

  1. At the top of the Variable Structures palette, select XML Type, if it is not already selected.

  2. In the Structure Label field, enter a display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at runtime.

  3. In the Structure Path field, enter the path of the variable structure at runtime.

  4. Under the Type field, select the appropriate radio button, then select Schema Element.

  5. Click Browse. The XML Schema Browser is displayed. Select an XML Schema from the list, select an XML Schema type from the Definitions pane, then click Submit.

  6. Click Add to create the variable structure.

Create a variable structure that maps a variable to a WSDL element

  1. At the top of the Variable Structures palette, select XML Type, if it is not already selected.

  2. In the Structure Label field, enter a display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at runtime.

  3. In the Structure Path field, enter the path of the variable structure at runtime.

  4. Under the Type field, select the appropriate radio button, then select WSDL Element.

  5. Click Browse. The WSDL Browser is displayed. Select a WSDL file from the list of WSDL files, select a WSDL element from the Definitions pane, then click Submit.

  6. Click Add to create the variable structure.

Create a variable structure that maps a variable to a child element

  1. At the top of the Variable Structures palette, select XML Type, if it is not already selected.

  2. In the Structure Label field, enter a display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at runtime.

  3. In the Structure Path field, enter the path of the variable structure at runtime.

  4. Under the Type field, select the type of variable you want to create:

    To create an XML Schema element or WSDL element variable, select the radio button associated with this option, then select Schema Element or WSDL Element.

    To create an MFL variable, select the radio button associated with this option, then select MFL.

  5. For the XML Schema, WSDL file, or MFL file, click Browse to select an object from the list that the browser displays, then click Submit. For example, select an MFL from a list of MFLs, then click Submit.

  6. Select the Set as child check box to set the element as a child of the structure being created.

  7. Click Add to create the variable structure.

Create a variable structure that uses an MFL resource

  1. At the top of the Variable Structures palette, select XML Type, if it is not already selected.

  2. In the Structure Label field, enter a display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at runtime.

  3. In the Structure Path field, enter the path of the variable structure at runtime.

  4. Under the Type field, select the appropriate radio button, then click Browse. The MFL Browser is displayed.

  5. Select an MFL from the list of MFLs, then click Submit.

  6. Click Add to create the variable structure.

Create a Service Interface variable structure

  1. At the top of the Variable Structures palette, select Service Interface.

  2. In the Structure Label field, enter a display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at runtime.

  3. In the Structure Path field, the default is already set as $body. You cannot change this field.

  4. In the WSDL Based Service field, select the Service Browser icon, select a service from the list of services the Service Browser displays, then click Submit.

The service you selected is displayed in the WSDL Based Service field.

  1. In the Operation field, select an operation or select None to not include an operation.

  2. Click Add to create the variable.

Create a Simple variable structure

  1. At the top of the Variable Structures palette, select Simple Type.

  2. In the Structure Label field, enter a display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at runtime.

  3. In the Structure Name field, enter a name for the variable structure you want to create.

  4. Under the Type field, select String or Any XML.

  5. Click Add to create the variable.

After you finish:

Continue as described in Creating and Editing Inline XQuery and XPath Expressions.

15.6 Creating Custom XPath Functions in the XQuery Editors

Creating custom XQuery functions is a development process that requires writing Java code.

For more information, see Creating Custom XPath Functions.

15.7 Binding External XQuery Resources to Inline XQueries

You can bind XQuery resources to inline XQuery expressions, so they will be executed inline as part of an action.

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:

  1. Click Variable Structures.
  2. In the workspace (under the button bar), select XQuery Resources.
  3. In the 1. Select an XQuery resource to execute box, click Browse.
  4. In the XQuery Browser, select the radio button associated with the XQuery you want to use, then click Submit.
  5. 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.

  6. After you finish, continue with any of the following tasks.

15.8 Binding External XSLT Resources to Inline XQueries

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

  1. Select the XSLT Resources option.
  2. Under the Select the XSLT resource to execute field, select the XSLT Browser icon.
  3. In the XSLT Browser, select the radio button associated with the XSLT you want to execute, then click Submit.
  4. 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.

  5. Continue with any of the following tasks:

15.9 Binding Dynamic XQuery Expressions to Inline XQueries

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

  1. Select the Dynamic XQuery option.
  2. 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

  3. In the Bind Variables using XQuery Template or 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
  4. After you finish, continue with any of the following tasks.

15.10 Binding Dynamic XSLT Expressions to Inline XQueries

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

  1. Select the Dynamic XSLT option.
  2. In the Enter Expression for XSLT Resource area, enter the XPath/XQuery expression that will evaluate at runtime to the name of a pre-registered XSLT resource. For example: $body/*:name/text()

    The following shows the syntax for the XSLT resource (representing the full name of the resource):

    Project/folder1/folder2/myXSLResourceName

  3. In the Bind Input area, enter an inline XQuery/XPath expression to select the XML input document. For example: $body/message.
  4. In the Bind Variables using XSLT Template or Custom Variables area, define the input parameters for the transformation.

    • Click Browse in the Select XSLT Template field to select an existing registered XSLT 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.

    • To add a variable manually, type a variable name in the Add Custom Variable field, and click Add.

    • For each variable listed under Variable Name, enter an XQuery/XPath 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
  5. After you finish, continue with any of the following tasks.

15.11 Entering XQuery Comparison Expressions Using the Builder Option

You can create comparison expressions in the XQuery Condition Editor.

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:

  1. In the XQuery Condition Editor, select Builder (located under the workspace button bar), if it is not already selected. option.
  2. In the Expression Builder box, select Comparison Expression if it is not already selected.
  3. 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 Building Expressions in the Editor Workspace Text Fields.

  4. From the Operator list, select a comparison operator.
  5. 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.

  6. Click Add. The text you entered is displayed in the Expressions pane.
  7. 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.

  8. Optionally, do either or both of the following:
  9. Click Save to close the editor and insert the expression in the action.

Continue configuring the action, as described in Adding and Editing Pipeline Actions in the Console.

15.12 Entering Unary Expressions Using the Builder Option

You can create a unary expression using the XQuery Condition Editor.

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:

  1. In the XQuery Condition Editor, select Builder (located under the workspace button bar), if it is not already selected. option.
  2. In the Expression Builder box, select Unary Expression if it is not already selected.
  3. Select the Not check box to make this a negative expression, or leave it blank.
  4. 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 Building Expressions in the Editor Workspace Text Fields.

  5. Click Add to add the text to the Expressions pane.
  6. 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.

  7. Optionally, do either or both of the following:
  8. Click Save to close the editor and insert the expression in the action.