• Composite Development describes how to create service assemblies for deployment and execution.
• Administration describes how to deploy and run your project.
Before you package and deploy your project, ensure that all validation errors are handled. For mediation interfaces that have errors, an error icon appears on the operation name. Errors occur because of an invalid configuration and each error is logged on the Problems tab of the mediation flow.
|
15bas
Chapter 2 Working with Mediation Flows
This chapter describes how to create and manipulate mediation flows. This chapter also describes how to work with mediation components in the Component Editor.
Topics
• Creating Mediation Flows, page 16
• Mediation Flow Properties, page 21
• Working with Interfaces, page 23
• Working with Paths, page 27
• Working with Message Context Properties, page 28
• Working with Exchange Variables, page 35
• Working with Tasks, page 40
• Mediation Components, page 42
Creating Mediation Flows
You create mediation flows using the mediation flow wizard. You access the mediation flow wizard from the Mediation Flows folder in the Project Explorer, as described in Creating a New, Empty Mediation Flow on page 16 and Creating New Mediation Flows From Existing Web Services on page 17.
For more information about folders in ActiveMatrix SOA projects, see the Installation.
Before creating mediation flows, you should have at least one WSDL file that defines the target interface that you plan to mediate.
Creating a New, Empty Mediation Flow
Creating a new, empty mediation flow enables you to start a mediation flow from scratch. You should at least have one WSDL file that describes the interface that you plan to mediate, but you can have zero or more target interfaces.
To create a new empty mediation flow:
1. Start the mediation flow wizard—right-click the Mediation Flows folder in the Project Explorer, then choose New > Mediation Flow from the popup menu.
The Create Mediation Flow dialog opens.
The default option is to create an empty mediation flow. You can also select the Create Composite checkbox if you want to create a corresponding
Creating Mediation Flows
|
17composite for this mediation flow. See Mediation Components on page 42 for more information about working with components and composites.
2. Click Next.
3. Supply a name in the Mediation Flow Name field.
If you chose to create a composite to correspond to the mediation flow, you can also name the composite in the Composite Name field.
You can also specify a different folder in the project for the mediation flow (and composite if one is created).
4. Click Finish.
The Mediation Flow Editor opens, and you can begin to add interfaces and configure your mediation flow.
Creating New Mediation Flows From Existing Web Services
If you have existing web services that you want to mediate, you can create new mediation flows for each interface. This is useful if you have many services and you want to create one mediation flow for each service.
Before creating mediation flows, ensure that the WSDL files that describe the interfaces have been imported into the project. See Composite Development for more information about importing WSDL files.
To create mediation flows from existing services:
1. Start the mediation flow wizard—right-click the Mediation Flows folder in the Project Explorer, then choose New > Mediation Flow from the popup menu.
2. Select the option Multiple Mediation Flows Using Existing Web Services.
You can also select the Create Composite checkbox if you want to create a corresponding composite for the mediation flow(s). See Mediation Components on page 42 for more information about working with components and composites.
3. Click Next to select the interfaces for the mediation flow.
4. Select the WSDL files to use when you create mediation flows.
You can select and add WSDL files individually, or you click the Add All>>
button to add all files to the Selected Interfaces list. You can remove one or more WSDL files using the <Remove and <<Remove All buttons.
A mediation flow is created for each WSDL file. The target interface(s) and mediation interface(s) are the same, and a path is automatically created between operations of the same name. If a WSDL file includes more than one port type, each port type is added to the mediation flow created for the file.
The name of each mediation flow is based on the name of the WSDL file. If there are conflicts in mediation flow names, a numbering scheme ensures that each newly created mediation flow has a unique name.
Creating Mediation Flows
|
195. The next step depends on whether you checked the Create Composite option:
a. If you did not check the Create Composite option, click Finish to create the mediation flows and composite.
b. If you checked the option to create a composite, click Next to specify the binding type— JMS, SOAP/HTTP, SOAP/JMS.
If you select SOAP/HTTP, additionally specify the Connector.
Click Finish to create the mediation flows and composite.
Editing Preferences of the Mediation Flow Editor
You can edit some Mediation Flow Editor preferences. To access the Preferences, choose Window > Preferences.
You can change the following preferences:
• Mediation Flow Name in Wizard The default name of mediation flows that you create with the Single Empty Mediation Flow option in the wizard.
• Mediation Flow Folder Name The name of the folder in which to store mediation flows.
• Show Diagram Tooltips Uncheck this checkbox if you want to turn off the tooltips.
• Mediation Task Icon Size You can specify whether you want small icons or large icons to be used in mediation flows and in the palette.
• Mediation Task Mapper Tree Expansion Level The default depth to which you can expand the left and right sides of the mapper.
• Live Database Validation for Query Database Task
— Validate Query Database Task Data Check this checkbox to connect to the database during validation to determine if the Query Database task configuration is correct. The information being queried is the structure (tables and columns) of the database.
— Validation Timeout The timeout (in seconds) for the validation task.
— Reload Database Data When Validation Checkthis checkbox to if the database structure is changing and the database will be queried each time the validation process is run.
Mediation Flow Properties
|
21Mediation Flow Properties
You can define mediation flow properties to store information. For example, you might want to store values for current price markups, or currency rates, or user names. The properties you create are stored in the mediation exchange, and they can be used by tasks in a mediation flow. Properties are defined on the Properties view of the mediation flow.
Figure 6 The mediation flow Properties view
To add a property, click the ellipsis (...) in the Name field, or click the Add button to the right of the table, and specify a name, datatype, and value for the property.
Properties can be one of these types:
• String
• Integer
• Boolean
• JDBC Resource Template
To delete a property, select the property row in the table and either press the Delete key or click the Delete button to the right of the table.
Properties can also be specified when you create a mediation component.
Component-level properties override the values of properties with the same name specified on the mediation flow.
Validation
When a mediation flow is created a property, VALIDATE_MESSAGE_DATA, is added by default.
• At design time, a property VALIDATE_MESSAGE_DATA is defined in the mediation flow implementation. When set to true, this property is used to validate the incoming message. This property is accessed by the mediation component in the composite is exposed at the composite level as
Add a property
MEDIATE_VALIDATE_MESSAGE_DATA.Having this property at the mediation component level allows for fine grained control compared to defining it at the mediation implementation level.
• A property VALIDATE_MESSAGE_DATA is available at the mediation
implementation level when viewed using the Administrator UI. The default value of this property is false. Set this property to true to enable validation of message data received by the mediation component. Validation of message data happens for both the component service and reference. Setting this property to true at the mediation implementation level enables validation on every mediation component on that particular node.
The value of the property set at the mediation component level takes precedence over the value set at the mediation implementation level. At runtime, when the incoming message (either a request message on the mediation interface or a reply message on the target interface) into mediation fails validation, an undeclared fault is returned to the consumer. The fault message will only indicate that a validation failure has occurred with no details provided. For more details about the cause of the validation failure will be contained in the log files.
Working with Interfaces
|
23Working with Interfaces
Interfaces are collections of operations that are defined in WSDL files. WSDL files are typically contained in the Service Descriptors special folder in a project. You can obtain interfaces in a variety of ways, usually by importing WSDL files into a project or by using a UDDI registry service.
Composite Development describes the folders in an ActiveMatrix SOA project and how to obtain WSDL files and use UDDI registry services.
Adding Interfaces to Mediation Flows
Before you add interfaces to your mediation flow, plan the needs of your
application and determine which target and mediation interfaces you need. Some planning considerations are discussed in Planning Target and Mediation
Interfaces on page 6.
There are a variety of ways to add interfaces to a mediation flow, and the method you use depends upon the requirements of your application. If you plan to have a one-to-one relationship between target and mediation interfaces, you might use the technique described in Creating New Mediation Flows From Existing Web Services on page 17.
If a WSDL file contains more than one port type, you can expand the WSDL file in the project tree and select only the interface you want to drag and drop into the mediation flow. You can also drag and drop the top-level WSDL file to add all interfaces within the WSDL file to the mediation flow.
If your target interfaces and mediation interfaces have different operations and schemas, drag and drop each interface from the Project Explorer into the appropriate area of the mediation flow.
Dragging and dropping an interface onto the mediation side of a flow creates an untargeted flow for each operation. When you select the mediation operation for an untargeted flow, the flow appears as a line ending in a question mark. You can then use a Generate Reply, Throw Fault, or End Mediation task on the flow without having to add a target interface. You can also drag and drop an untargeted flow to a target interface and mediate that interface.
Another way to add an interface to the target or mediation interface list is to use the menu icon at the top of the Mediation Interfaces area and Target Interfaces area of the mediation flow. The menu contains an Add Mediation Interface or Add Target Endpoint item, depending upon which side of the mediation flow you use. The Add menu opens a Select WSDL Port Type dialog where you can choose an interface to add.
AutoMediate ™
The Mediation Flow Editor provides mechanisms for quickly adding identical interfaces to both the target and mediation interface sides of the mediation flow with corresponding mediation paths between operations of the same name. These mechanisms are known as AutoMediate.
You can AutoMediate an interface in one of these ways:
• Drag and drop an interface to either the target or mediation interface area.
Select the interface you have added to the mediation flow, then click and drag it to the opposite side of the mediation flow.
• Drag and drop an interface to the target interface area. Then, click the projection icon in the title bar of the interface.
• Drag and drop an interface onto the mediation paths area (the center area) of a mediation flow.
All mediation operations are connected to their corresponding target operations.
You can add more than one copy of the same interface to the mediation interfaces side of the mediation flow, so that you can specify different business logic for the same interface. You can then expose each implementation of the interface to different clients. For example, you could use this functionality to offer different qualities of service to different clients.
You can use the TIBCO AutoMediate Command Line tool to use existing services as input to create a fully functional composite application that generates a DAA that you can deploy into an ActiveMatrix runtime environment. See TIBCO AutoMediate Command Line Tool on page 215 for detailed information.
Working with Interfaces
|
25Deleting Interfaces
You can delete interfaces from either side of the mediation flow by clicking the interface menu icon in the title bar of each interface and selecting Delete from the popup menu
Moving Interfaces
To move interfaces within the target and mediation interface list:
1. Click the header of the interface you want to move.
2. Drag and drop the interface to the new location in the list of interfaces.
Creating Local WSDL Files
If you automatically create mediation interfaces, you might want to create local copies of the WSDL files—this enables you to make changes to the copies without affecting other services or clients that might use those WSDL files.
To create a local copy of the WSDL file for your mediation interfaces:
1. In your mediation flow, locate the mediation interface you want to include in the local WSDL file.
2. Click the menu icon in the title bar of the interface and choose Copy Interface from the pop-up menu. The Mediation Flow Editor creates a local WSDL file, placing it in the same folder as the mediation flow. The name of the file is the same as the name of the mediation flow, with the file extension .wsdl.
3. To include additional mediation interfaces in the local WSDL file, repeat step 2 for each interface. Each interface you copy is placed into the same local WSDL file. You can then edit the file using the standard WSDL editor.
Policies
The following intents are supported by Mediation interfaces:
• At least once
Specifies that the provider must receive every message sent to it by consumers at least once.
Deleting a target interface that has one or more operations for which there are paths from mediation operations results in undefined destinations for the paths. It is necessary to fix the destinations by directing them to other operations or to Throw Fault tasks.
• Transacted one way
Specifies that references must send all out-only messages within a global transaction, and the ActiveMatrix framework must deliver the message only after the transaction commits.
See Composite Development for more information on intents and policies.
Working with Paths
|
27Working with Paths
Paths are created by dragging and dropping a mediation operation onto a target operation. Paths can be automatically created in mediation flows, as described in Adding Interfaces to Mediation Flows on page 23.
Creating an input path also creates the corresponding output and fault paths. You can click on the Input, Output, and Fault icons at the top of the mediation paths area to view the corresponding path for each mediation operation.
The path for only one mediation operation appears in the mediation paths area.
Select a mediation operation to view its path.
On the input path is a small circle next to the directional arrow of the path . To modify the target operation, click and drag this circle to move the path to a different target operation. You can also change the target operation on an output path by clicking and dragging the circle next to the target operation , and the input and fault paths are automatically updated.
To delete a path, select the path then either press the Delete key, or right-click while hovering over the path and choose Delete from the popup menu.
Route tasks create sub-paths and have some additional characteristics. See Chapter 5, Routing Messages in a Mediation Flow, on page 57 for more information about working with route tasks.
Mediation operations must have an input path. Typically the input path leads to a target operation, but there can also be a route task that splits the path into more than one destination, or the path can lead to a Throw Fault task, a Generate Reply task, or an End Mediation task.
If a mediation operation is not implemented—that is, if it does not have an input path—an error icon appears in the bottom left corner of the operation’s icon.
You must implement all mediation operations in a mediation flow before deploying the project.
Working with Message Context Properties
In a mediation exchange, the context of the message sent to the mediation operation includes information about the message. This message context includes information about the message transport (for example, HTTP headers or JMS message headers/properties) and security information about the message.
ActiveMatrix provides a way for the mediation flow to receive message context information and access its values in the mediation path. It also provides a mechanism for setting the message context data for the input message of the target operation and the output message of the mediation operation.
The Mediation Flow also allows you to configure an additional type of context parameter called Mediation. This type provides the security context, endpoint reference, and request message mechanisms.
Adding Context Parameters
Context parameters can be configured at a mediation interface level, target interface level, or for an operation contained in the interfaces. Parameters added at the interface level are available for use by all the containing operations.
Parameters added at the operation level can be used by those operations only.
Context parameters for the Mediation and Target interfaces are independent of each other. The Set Context mediation task is used to map values of the defined context parameters.
To add context parameters:
1. Choose the interface or operation.
The Operation Context Parameters table is initially empty.
2. Select the General tab from the Properties view.
3. Click the button located on the right side of the table.
4. Specify
— Name: Name of the parameter.
— Direction: Choose between Input, Output, and Fault.
— Type: Choose between Basic, Message, Bag, Mediation.
— Definition: This is the definition mechanism. If you chose Mediation as the context parameter type, the available definitions are Security Context, Endpoint Reference, and Request Message Context.
Working with Message Context Properties
|
29If the Direction is Fault and the Type is Mediation, the Definition mechanism is set to Undeclared Fault Context. See Undeclared Fault Headers, page 33 for more information.
The context parameter is added to the chosen interface or operation.
Deleting Context Parameters
To delete context parameters from the Mediation or Target interface, choose the context parameter and click the button.
Context parameters can be deleted at either the interface level or the operation level.
If the context parameter is deleted at the interface level, the parameter is deleted
If the context parameter is deleted at the interface level, the parameter is deleted