18 Working with Pipeline Templates

This chapter describes designing prototype message flows using pipeline templates. It also describes how to use Oracle JDeveloper to design and configure pipeline templates and concrete pipelines.

Note:

You cannot create a pipeline template in Oracle Service Bus Console. However, you can see existing template resources in the Project Navigator and view template properties like binding type and message handling options. You can also delete a template, rename a template, and move the template into a different folder or project.

Use pipeline templates to design prototype message flows for proxy services. A pipeline template defines the general shape or pattern of the message flow. Concrete pipelines can then be generated out of the pipeline template. All concrete pipelines use the message flow defined by the pipeline template with designated places where custom logic can be inserted.

The following sections describe working with pipeline templates in Oracle JDeveloper:

• Adding a Pipeline Template

• Editing a Pipeline Template

• Adding Placeholder Blocks to a Pipeline Template Message Flow

• Locking an Action in a Pipeline Template

• Creating a Concrete Pipeline from a Pipeline Template

• Editing the Message Flow for a Concrete Pipeline

• Converting a Concrete Pipeline in to a Regular Pipeline

18.1 Adding a Pipeline Template

Use pipeline templates to design prototype message flows for proxy services. A pipeline template defines the general shape or pattern of the message flow.

18.1.1 How to Add a Pipeline Template

You can add a pipeline template to an open Service Bus project in Oracle JDeveloper.

To add a pipeline template:

1. Make sure you have the Service Bus project open in Oracle JDeveloper.
2. Use one of the following methods to add a new pipeline template:

   • In the Application Navigator, right-click the Service Bus project icon and select New > Pipeline Template from the context menu.

   • From the File menu, select New > Pipeline Template.

   The Create Pipeline Template wizard appears.

3. Under Service Name, enter a name for the pipeline template.
4. Click the Browse icon to the right of the Location field to specify a directory for the pipeline template. The default directory is the Service Bus project folder.
5. Optionally, enter a Description for the pipeline template.
6. If you wish to use an existing pipeline to define the template, select From Pipeline. Click the Browse icon to select a pipeline file.
7. Click Next. The Service Type page appears.
8. Select a Service Type for the pipeline template. All concrete pipelines created from this template would use the same service type.

   Select Any if you wish to have the option of selecting the service type when creating a concrete pipeline.

9. Click Finish to create the pipeline template. The pipeline template (.ptx) opens in the Template Designer. The pipeline template also appears in the Application Navigator.
10. In the Template Designer, select the Configuration tab at the bottom left. The Configuration tab is used to specify message handling configuration settings and other general settings.
11. Click General to specify an optional Description for the pipeline template.

18.2 Editing a Pipeline Template

After creating a pipeline template, you can edit it using the Template Designer. You can specify settings like message handling configuration settings for the template, and edit the message flow for the template.

18.2.1 How to Edit a Pipeline Template

Use the Template Designer to configure the settings and message flow for a pipeline template.

To edit a pipeline template:

1. In the Application Navigator, double-click the pipeline template to open it in the Template Designer.
2. Click the Configuration tab at the bottom left to specify General configuration settings, like Description, and message handling settings, like content streaming and transaction settings. Press F1 to get help related to the settings.
3. Click the Design tab at the bottom left to edit the message flow for the pipeline template.

   If no message flow has yet been created for the pipeline template, the Template Designer Design view shows a single icon on the page, the Proxy Service icon. This is the starting node for the message flow.

4. Use one of the following methods to add a message flow component (node) to the message flow:

   • Right-click the start node (proxy service icon) to get options for message flow components that you can add.

     Figure 18-1 shows the options available for the start node. You can add nodes like the PipelinePair node and Conditional Branch. You can also add template placeholders like Nodes, Route, and Conditional Template. Template placeholders are placeholders for actual nodes that you can add when creating concrete pipelines.

     Figure 18-1 Right-Clicking a Node to Add a Message Flow Component

     
     Description of "Figure 18-1 Right-Clicking a Node to Add a Message Flow Component"

   • Alternatively, select the message flow component to add from the Components window, and drag the component to the Template Designer window. Yellow circles appear indicating valid places to drop the component in the message flow. Drag the component to a yellow circle. The yellow circle turns green. Release the component to add it. Figure 18-2 shows a Pipeline Pair node being added to a start node.

   Figure 18-2 Adding a Pipeline Pair to the Start Node

   
   Description of "Figure 18-2 Adding a Pipeline Pair to the Start Node"

   When you add components to the Template Designer, corresponding icons are displayed on the Template Designer to represent the components. The relationships among the components are shown with lines and bounding boxes.

   Figure 18-3 shows a message flow where a Pipeline Pair node has been added to the flow. The Pipeline Pair comprises of a Request Pipeline and a Response Pipeline. The Request and Response pipelines have stages that can contain action nodes.

   Figure 18-3 Message Flow with a Pipeline Pair Node

   
   Description of "Figure 18-3 Message Flow with a Pipeline Pair Node"
5. Continue to build the message flow by adding more components. For example, to add an Actions placeholder to the stage node, you can drag the Actions component from the Components window to the stage node in the editor. Alternatively, you can right-click the Stage node to get options for message flow components that you can add to the Stage node. The options available for each component may differ, depending on context.
6. Click Save in the Oracle JDeveloper toolbar.

18.2.1.1 How to View External Services

The external services listed in the Start Node are those invoked outside the context of the pipeline. They are specified in an Invoke Service node but are listed here for convenience.

To view external services:

To view external services, click the left-arrow button on the Start Node. The External Services box appears to the left of the Start Node. Hover your mouse over an external service to view the complete path of the service resource.

18.2.1.2 How to View Shared Variables

The shared variables listed in the Start Node are the variables that the pipeline can share with other pipelines in the same call chain.

Note:

If two pipelines in a single call chain declare the same shared variable, then they read and modify the same variable in the scope of the invocation call chain. In other words, if pipeline P1 declares a shared variable var, and pipeline P1 invokes pipeline P2, which also declares a shared variable var, then any changes to var in P1 are visible in P2, and vice versa. A shared variable must be of the String, Boolean, or XML data type.

To view external services:

To view shared variables, click the left-arrow button on the Start Node. The Shared Variables box appears to the left of the Start Node. You can right-click the Shared Variables box to get a context menu. The context menu enables you to perform tasks like add or delete shared variables.

18.3 Adding Placeholder Blocks to a Pipeline Template Message Flow

When a pipeline template defines a template placeholder of a particular type, a concrete pipeline can add zero or more nodes of the same type to the template placeholder. For example, the actions template placeholder can contain zero or more action nodes in the concrete pipeline.

Template placeholders can be of the following types:

• Nodes: A nodes template placeholder can contain the following nodes:

  • Concrete pipeline pair nodes that contain stages/actions

  • Conditional branch nodes

  • Operational branch nodes

  • REST branch nodes

  • Route node

  For example, a node placeholder block may contain a pipeline pair node followed by a route node in the concrete pipeline.

• Stages: A stages template placeholder can contain zero or more stages in the concrete pipeline. Each stage can in turn contain actions.

• Actions: An actions template placeholder can contain zero or more actions in the concrete pipeline.

• Route: A route template placeholder is a placeholder for routing actions in the concrete pipeline.

• Conditional: A conditional template placeholder enables you to specify a conditional branch node for the concrete pipeline.

• Operational: An operational template placeholder enables you to specify an operational branch node for the concrete pipeline when using WSDL SOAP binding.

• REST: A REST template placeholder enables you to specify a REST branch node for the concrete pipeline when using the REST binding.

18.4 Locking an Action in a Pipeline Template

If you have specified all required properties for an action added to a pipeline template message flow, and you wish all concrete pipelines to use the same values for the properties, then you can lock the action in the pipeline template message flow.

A locked action cannot be edited in the concrete pipeline. You must make sure that you have specified all the required properties, and any optional properties, in the pipeline template.

18.4.1 How to Lock an Action in a Pipeline Template

You can lock an action from the Properties window in Template Designer.

Before you begin:

Make sure you are editing the message flow in the Template Designer, as described in Editing a Pipeline Template

To lock an action:

1. Select the action in the Template Designer. The properties for the action appear in the Properties window.
2. Make sure you have specified all the required properties specific to the selected action.
3. In the Properties window, click the Lock icon to lock the action.

   Figure 18-4 Locking an Action in a Pipeline Template

   
   Description of "Figure 18-4 Locking an Action in a Pipeline Template"

18.5 Creating a Concrete Pipeline from a Pipeline Template

Concrete pipelines implement the message flow pattern defined by the pipeline template. You can customize the message flow for the concrete pipeline at designated places.

18.5.1 How to Create a Concrete Pipeline

You can use the pipeline creation wizard to create a concrete pipeline based on a pipeline template.

To create a concrete pipeline:

1. Make sure that the service bus project is open in Oracle JDeveloper.
2. Use one of the following methods to create a new pipeline:

   • Under the File menu, click New > Pipeline. The Create Pipeline Service wizard appears.

   • In Application Navigator, right-click the service bus project icon. Select New > Pipeline. The Create Pipeline Service wizard appears.

   • In Application Navigator, right-click the pipeline template from which you wish to create the new pipeline. Select Service Bus > Generate Pipeline.

     The Create Pipeline Service wizard appears. The name of the pipeline template is already populated in the From Template field.

3. Under Service Name, enter a name for the new concrete pipeline.
4. Click the Browse icon to the right of the Location field to select the location for the concrete pipeline resource. The default location is the service bus project folder.
5. Specify an optional Description for the concrete pipeline.
6. If not already selected, select From Template to specify the pipeline template. Click the Browse icon to the right of the From Template field to select the pipeline template. Select the pipeline template file and click OK.
7. Click Next.
8. Select the Service Type for the concrete pipeline. The options available depend on the service type specified for the underlying template.
9. Click Finish to create the concrete pipeline.

18.6 Editing the Message Flow for a Concrete Pipeline

The concrete pipeline inherits its message flow form the pipeline template. You can complete the message flow in the Pipeline Editor. You can add nodes and actions to template placeholders in the message flow. In addition, you can edit or complete the properties for other unlocked actions defined in the pipeline template. You cannot edit locked actions in the concrete pipeline.

18.6.1 How to Edit the Message Flow for a Concrete Pipeline

Use the Pipeline Editor to edit the message flow for a concrete pipeline. You can add nodes and actions to template placeholders, and edit other unlocked actions defined in the pipeline template.

To edit the message flow for a concrete pipeline:

1. Make sure you have the Service Bus project open in Oracle JDeveloper.

2. Use one of the following methods to edit the message flow for a pipeline:

   • In Application Navigator, locate the pipeline node. Right-click the pipeline node and select Open. You can alternatively double-click the pipeline node to open it.

   • In Application Navigator, click the project node (or overview.xml) to open the Overview Editor.

     In the Overview Editor, double-click the pipeline component to open the Pipeline Editor.

   The Pipeline Editor appears. Ensure that the Design tab is selected at the bottom left corner of the editor.

   The Pipeline Editor shows the message flow designed in the pipeline template.

3. To edit the property for an unlocked action:

   1. Select the action in the Pipeline Editor message flow by clicking on it. The Properties window displays the properties for the selected action.

      Note:

      If the Properties window is not visible, select Properties from the Window main menu.

   2. Edit the properties in the Properties window.

4. Use one of the following methods to edit a template placeholder:

   • Right-click the template placeholder icon to get options for message flow components that you can add. Click Insert Into from the context menu that appears.

     Figure 18-5 shows the options available for the actions template placeholder.

     Figure 18-5 Adding a Node to a Template Placeholder

     
     Description of "Figure 18-5 Adding a Node to a Template Placeholder"

   • Drag the desired component from the Components window to the template placeholder in the Pipeline Editor.

     As you drag the component to the editor window, yellow circles appear to indicate the valid places where you can drop the component. When you drag the component to one of the yellow circles, the circle changes to green indicating that you can drop the component there. Release the mouse button to drop the component.

5. Continue to build the message flow by editing more actions, or dropping more nodes into template placeholders.

6. Click Save in the Oracle JDeveloper toolbar.

18.7 Converting a Concrete Pipeline in to a Regular Pipeline

If you no longer need a concrete pipeline to be associated with a pipeline template, you can break the template link to convert the pipeline in to a regular pipeline. The regular pipeline can be edited without the restrictions applicable to concrete pipelines.

18.7.1 How to Break a Template Link for a Concrete Pipeline

You can use the Configuration tab of the Pipeline Editor to break its link with the associated template.

To break the template link for a concrete pipeline:

1. Make sure you have the Service Bus project open in Oracle JDeveloper.
2. Use one of the following methods to open the Pipeline Editor:

   • In Application Navigator, locate the concrete pipeline node. Right-click the pipeline node and select Open. You can alternatively double-click the pipeline node to open it.

   • In Application Navigator, click the project node (or overview.xml) to open the Overview Editor.

     In the Overview Editor, double-click the concrete pipeline component to open the Pipeline Editor.

   The Pipeline Editor appears. Ensure that the Configuration tab is selected at the bottom left corner of the editor.

3. Click General to display the General Configuration page.
4. Under Template, click the Break Template Link icon. Figure 18-6 shows the Break Template Link icon.

   Figure 18-6 Breaking a Template Link

   
   Description of "Figure 18-6 Breaking a Template Link"