Using the Oracle Service Bus Console

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Proxy Services: XQuery and XPath Editors

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.

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 20-1shows an example.

Figure 20-1 Example of Action Configuration Skeleton

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 Creating, Editing, and Viewing Message Flows and Adding and Editing Actions in Message Flows.

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 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()Example of Action Configuration Skeleton, or a fragment of the expression it is too long to fit, for example $body/urn:POSta...Example of Action Configuration Skeleton.. 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.

After you finish

Continue configuring the action, as described in Adding and Editing Actions in Message Flows.

Understanding XQuery Editor Layouts and Tasks

The XQuery Expression Editor, the XQuery Condition Editor, and the XPath Expression Editor are each composed of the following components:

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.

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.

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.

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:

  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 20-1, below.

    4. Table 20-1 Palettes 
    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 Creating Namespaces to Use in Inline Expressions.
    XQuery Functions
    Contains a set of standard XQuery functions, organized alphabetically and by type:
    • Service Bus Functions
    • Accessors
    • Error Functions
    • XML Functions
    • Constructors
    • Numerics
    • Strings
    • URIs
    • Booleans
    • Durations, Dates, and Times
    • QNames
    • Nodes
    • Sequences
    • Context Functions
    • Alphabetical
    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
    • Select the name of the structure from the drop-down 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).
    • Expand or collapse nodes in the tree by clicking 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 XQuery Transformations.

  4. Paste the desired item into the text field using any of the methods shown below in Table 20-2:

    5. Table 20-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:
    • Click Validate. A message is displayed if the expression is validated successfully.
    • Click Test to test the expression. See Performing XQuery Testing.
  8. Click Save to close the editor and insert the expression in the action.

After you finish

Continue configuring the action, as described in Adding and Editing Actions in Message Flows.

Creating Namespaces to Use in Inline Expressions

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

  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.

After you finish

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

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:

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:

  1. Select Variable Structures.
  2. In the Variable Structures palette, click Add New Structure.
  3. Continue with any of the tasks listed in Table 20-3, below.

    4. Table 20-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 run time.
    3. In the Structure Path field, enter the path of the variable structure at run time. 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 run time.
    3. In the Structure Path field, enter the path of the variable structure at run time.
    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 from the list of WSDLs, 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 run time.
    3. In the Structure Path field, enter the path of the variable structure at run time.
    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 run time.
    3. In the Structure Path field, enter the path of the variable structure at run time.
    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 from the list of WSDLs, 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 run time.
    3. In the Structure Path field, enter the path of the variable structure at run time.
    4. Under the Type field, select the type of variable you want to create:

      5. 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, or MFL, 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 run time.
    3. In the Structure Path field, enter the path of the variable structure at run time.
    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 run time.
    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.

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

    5. In the Operation field, select an operation or select None to not include an operation.
    6. 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 run time.
    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.

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.

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

    6. 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.
    • Click Validate. A message is displayed if the expression is validated successfully.
    • Click Test. See Performing XQuery Testing.
    • Save or discard your changes.

Binding External XSLT Resources to Inline XQueries

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

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

Binding Dynamic XQuery Expressions to Inline XQueries

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

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

  4. 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 Performing XQuery Testing.
    • Save or discard your changes.

Entering XQuery Comparison Expressions Using the Builder Option

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:

  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.

    4. To build the operand, you can paste XQuery functions from the XQuery Functions palette and namespaces from the Namespace Definitions palette. See step 3 and step 4 in 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.

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

    8. 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 Example of Action Configuration Skeleton Up arrow to move it up in the list of conditions or click the Example of Action Configuration Skeleton Down arrow to move it down the list of conditions. You can also click the Example of Action Configuration Skeleton Edit icon to update a condition, or click the Example of Action Configuration Skeleton 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:
    • Click Validate. A message is displayed if the expression is validated successfully.
    • Click Test to test the expression. See Performing XQuery Testing.
  9. Click Save to close the editor and insert the expression in the action.

After you finish

Continue configuring the action, as described in Adding and Editing Actions in Message Flows.

Entering Unary Expressions Using the Builder Option

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:

  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.

    5. To build the expression, you can paste XQuery functions from the XQuery Functions palette and namespaces from the Namespace Definitions palette. See step 3 and step 4 in 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.

    7. 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 Example of Action Configuration Skeleton Up arrow to move it up in the list of conditions, click the Example of Action Configuration Skeleton Down arrow to move it down the list of conditions, click the Example of Action Configuration Skeleton Edit icon to update it, or click the Example of Action Configuration Skeleton 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:
    • Click Validate. A message is displayed if the expression is validated successfully.
    • Click Test to test the expression. See Performing XQuery Testing.
  8. Click Save to close the editor and insert the expression in the action.

After you finish

Continue configuring the action, as described in Adding and Editing Actions in Message Flows.


  Back to Top       Previous  Next