Copyright © TIBCO Software Inc. All Rights Reserved

Specifying Generic Adapter Configurations

This section gives an overview of how you can use TIBCO Designer to specify an adapter configuration. It discusses these topics:

•	Configuring a New Adapter Instance

•	Adding Services to Your Adapter

•	Advanced Adapter Configuration

•	Adding Custom Log Sinks to Your Adapter

•	Adding Extended Properties to Your Adapter

•	Adding Custom Hawk Microagents to Your Adapter

•	A Note on Global Variables

•	Using a Message Filter

•	Testing Your Adapter Using Adapter Tester

Overview

The Generic Adapter Configuration resource and the associated Adapter Resources palette are used when developing an adapter using the TIBCO Adapter SDK API. The adapter is configured using the Generic Adapter Configuration resource and the configuration is saved to a project repository, which is used by the code you have written.

This manual discusses all resources in the Adapter Resources palette. This chapter explains how to use the resources, later chapters provide a reference to individual resources and the settings you specify in the configuration panel.

Adapters and Schema Resources

Schema used by an adapter are defined separately from the Generic Adapter Configuration. However, resources in the Generic Adapter Configuration point to adapter schema resources. For example, when you define a service such as a publication service, you need to define the schema that describes the data that will be published. When you save the project, both the adapter configuration and the corresponding schema are saved.

For information on configuring adapter schemas, see Chapter 4, Adapter Schema Palette. You can access this guide via Help > Help For > Adapter Schemas.

Configuring a New Adapter Instance

To create an adapter configuration, follow these steps:

1.	Open TIBCO Designer. In the startup window, choose New empty project or open the project to which you wish to add your adapter.

2.	Save the project. See TIBCO Designer User’s Guide, available via Help > Designer Help for information on saving projects.

3.	In the project panel of the main window, make sure the top-level (project) folder is selected.

4.	From the palette panel, drag a Generic Adapter Configuration into the design panel.

5.	In the configuration panel, specify the configuration information for the adapter. See Generic Adapter Configuration Reference.

Decide now whether you need to perform advanced logging. • If the adapter doesn’t use custom roles, use the Logging tab to specify logging information. • If the adapter uses custom roles, click the Use Advanced Logging check box, and use the Log Sinks folder later to define your sinks. See Custom Log Sink Reference.

6.	Add operations and, optionally, standard log sinks. An overview is given in this chapter:

−	Adding Services to Your Adapter

−	Adding Custom Log Sinks to Your Adapter

Adding Services to Your Adapter

Adapter services are an abstraction useful for configuration of already existing adapters and they are therefore used in the Generic Adapter Configuration. Adapter services do not map directly to any objects used by a TIBCO Adapter SDK program. Instead, an adapter service is an aggregate of an endpoint and the corresponding session and points to the schema used by the endpoint.

The easiest way to configure a new adapter is to drag a service into the design panel and configure it (and its metadata). If necessary, you can then perform additional configuration on the endpoint created by TIBCO Designer. Creating the session and endpoint explicitly is cumbersome and not recommended.

The following types of services are supported:

•	Publication service

•	Subscription service

•	Request-Response service

•	Request-Response Invocation service

To add a service to an adapter configuration:

1.	In the project tree, select the adapter, then open the Adapter Services folder.

2.	In the palette panel, select one of the services, for example, a Publication Service, and drag it into the design panel.

3.	In the configuration panel give the service a name and choose the transport type.

Figure 103 Configuration Tab

To use Enterprise Message Service as the transport, delete all extra copies of the open SSL libraries (libeay32.dll and ssleay32.dll) from the TIBCO_HOME\adapter\sdk\5.8\bin folder to start the adapter project from TIBCO Designer.

4.

To provide some additional information about the transport, click the Transport tab. What is displayed depends on the transport type you selected for the service. The screen shot below shows the options available for the default transport, a TIBCO Rendezvous Certified transport. See Services Reference for detailed information on the individual services and different Transport tab content.

Figure 104 Transport Tab

 

5.	If the schema that determines the data used by the service has already been defined, click the Schema tab, then click the browse icon (binoculars) and select the schema resource in the dialog that appears.

You must be sure to assign the appropriate schema to the service. The default, any, is only there as a placeholder.

6.	Click Apply.

TIBCO Designer creates the service instance. If you need to perform additional customizations, you can open the Advanced folder and do it there. See Advanced Adapter Configuration.

Advanced Adapter Configuration

After you have created a service, you can perform additional adapter customization as follows:

•	If information about the session and endpoint cannot be set directly in the service, you can go to the Sessions folder and configure the session and endpoint there. See Sessions Reference and Custom Log Sink Reference.

•	If you wish to add custom log sinks, click Use Advanced Logging in the Logging tab for the adapter, then add individual sinks as needed. See Custom Log Sink Reference.

•	If you are using an RVTX session, you can add transaction pools to your adapter. Regardless of the type of session, you can add advisories as needed. See Transaction Control and Advisory Reference.

•

If your adapter takes an extraordinary amount of time to load, you may specify a loadURL in the Metadata URL folder. See Metadata URLs Folder. In that case, you also need to specify the URL for the location of schema, so the adapter can load them as needed at runtime. You do that from the Adapter’s Startup tab.

Adding Custom Log Sinks to Your Adapter

If your adapter uses only file sinks and stdio sinks, you configure the sinks using the Logging tab at the adapter instance’s top level. If you want to add additional file or stdio sinks, or network sinks or TIBCO Hawk sinks, follow these steps.

1.	Select the adapter, then choose the Logging tab and click the Advanced Logging check box.

2.	Select the Log Sinks folder.

3.	Customize the existing File Sink and stdio Sink if you like. See File Sink and stdio Sink.

4.	To add more file sinks or stdio sinks:

a.	Select the Log Sinks folder in the project tree.

b.	Drag a File Sink or stdio Sink into the design panel.

c.	Specify the information, as discussed in File Sink or stdio Sink.

5.	To add Network sink, which publishes information to TIBCO Rendezvous:

a.	Select the Log Sinks folder in the project tree.

b.	Drag a Generic Log Sink into the design panel.

c.	From the pop-up, choose Network and click Apply.

d.	Specify the information, as discussed in Network Sink.

6.	To add a TIBCO Hawk sink, which publishes information to TIBCO Hawk:

a.	Select the Log Sinks folder in the project tree.

b.	Drag a Generic Log Sink into the design panel.

c.	From the pop-up, choose Hawk.

d.	Specify the information, as discussed in Hawk Sink.

Adding Extended Properties to Your Adapter

If the existing configuration GUI does not provide the resource you need for some custom configuration, you can add extended properties to your adapter. You can also remove existing attributes or properties using the Delete icon.

You have the following options, discussed in this section.

•	Specifying Values for Existing Properties

•	Adding Properties

•	Deleting Items

Terminology

Keep in mind the following terminology used to describe repository content.

•	An object contains attributes.

•	An attribute is a named association list. Inside the association lists are name:value pairs which are properties of the attribute.

•	As a result, you add an association list to an object, then name it and have an attribute.

Adding Properties

To add an extended property to your adapter, follow these steps:

1.	Select the top-level adapter configuration object.

2.	Choose Resources > Edit Extended Properties.

3.	Use the icons in the Edit Extended Properties dialog to add properties.

You can perform the following operations.

	Click this icon to add an association list. Because a named association list is called an attribute, you have, in effect, added an attribute to an object when you add an association list. Note that you can also add an association list to an attribute. This adds an extended property to the attribute.
	Click this icon to add a reference to an existing object. When you add a reference, you must then specify the global name to which the reference points. The global name specifies the location of the object inside TIBCO Repository, for example /tibco/public/endpoint/adapter/generic/Generic Adapter Configuration/RV TX Publisher
	Click this icon to add a string property to an association list. Triple-click the newly-added property to change the property name and its value.

For an example, see Adding Custom Hawk Microagents to Your Adapter.

Deleting Items

You can delete an object, association list, or attribute by selecting it, then clicking the delete icon.

Specifying Values for Existing Properties

To specify a value for an existing property:

1.	Select the property by triple-clicking it.

2.	Enter a value of your choice. Note that double-quotes are automatically added when you press Return.

Adding Custom Hawk Microagents to Your Adapter

To add a custom Hawk Microagent to your adapter, you must edit the adapter’s XML file.

The following example shows the elements and attributes required for a custom Hawk Microagent. See the sdk/pubsub example for the actual XML:

 

+ hawk

- help=Java SDK Example pubsub

- microAgentName=hawkagent

- sessionName = hawkSession

+ method

- help = Retrieve Color Information

- name = getColor (this must match the method name in code)

- type = INFO

+ outputParameter

- help = Color Information

- name = color

- type = string (this must match the method's return

            type in code)

+ method

- help = Set Color Information

- name = setColor (this must match the method name in code)

- type = ACTION

+ inputParameter

- help = set color Information

- name = color

- type = string (this must match the method parameter

            type in code)

A Note on Global Variables

In many fields in the configuration panel, global variables surrounded by %% are used. In most cases, you can change these global variables using the Global Variables tab in the project panel. See TIBCO Designer User’s Guide for information.

Do not set values for the %%InstanceId%% and %%AppName%% global variables. The variables are set at runtime by run-time adapters.

Using a Message Filter

The Message Filter resource allows developers to transform inbound and/or outbound messages for any adapter built with the Adapter SDK. It could be used, for example, for performing localized transformations using XSLT.

The programming for the Message Filter is performed with the Adapter SDK and discussed in the Adapter SDK Programmer’s Guide. This resource only allows you to hook in the resource.

Usage Scenarios

•	The adapter wants to transform all outbound XML with XSLT

The application to which the adapter connects understands XML natively. The adapter code retrieves messages and makes use of the MData::toXML() methods. The corresponding XSD is available in-memory and on disk if you have exported it. To achieve local transformations to a “canonical format”, XSLT is the logical choice. These transformations can be applied to all outbound endpoints. Inbound transformations most likely don’t make sense.

•	Arbitrary custom data manipulation is desired (not XSLT)

Some custom code is required to manipulate messages before sending them to a third-party application. For example, a legacy TIBCO Rendezvous application expects its data in a particular format. The only solution today is to write an intervening adapter between packaged adapters and the TIBCO Rendezvous application to do TIBCO Rendezvous transformations, or to use other TIBCO products (TIBCO IntegrationManager, TIBCO ActiveMatrix BusinessWorks).

Implementation

The low-level callout behavior is made available by an MTransformationPlugin class that is part of the API (both C++ and Java). See the reference documentation for TIBCO Adapter SDK for additional information.

You specify the low-level callout in TIBCO Designer as follows:

1.	With the top level project selected, drag a Message Filter resource into the design panel. Name it appropriately for clarity.

2.	Specify the name of the implementing class in the Implementation field.

3.	In the design panel, add or remove attributes as follows:

a.	In the toolbar, click the Add Attribute icon.

Figure 105 Add Attribute Icon

b.	Specify the name of the attribute and the value you wish to use for this adapter instance.

c.	Click Is Reference if the attribute is also another object.

4.	Click Apply.

You associate the callout with your adapter as follows:

1.	Select the Generic Adapter Configuration resource and choose the Configuration tab.

2.	Click the Browse button next to the Message Filter field and select the Message Filter you defined earlier.

You can now access the attributes set in your configuration from your adapter code. Here is an example for accessing an attribute test with value teststring.

In C++:

pMProperties->getValue( pMApp->getAppName() +

"/deployment/transformationPlugin/attributes/test", myMStringProp);

In Java:

myStringProp =

mapp.getConfigProperties().getString(app.getAppParameters().getAppName() + "/deployment/transformationPlugin/attributes/test");

The transformation plugins are applied only to services with subscriber, publisher, client, and server endpoints.

You can use the transformation plugin to stop the message flow. You can either throw an exception or return FALSE to stop message flow.

A programming example is included in the TIBCO Adapter SDK Programmer’s Guide.

Testing Your Adapter Using Adapter Tester

The adapter tester is a tool that can be used for testing adapters.

It is highly recommended you validate the project before starting adapter tester.

All adapters you wish to test, must have their runtime installed in your machine. Because the setup differs depending on the type of adapter you are testing, this section explains how to use the tool in three sections:

•	Setup for Testing TIBCO Adapters

•	Setup for Testing Custom Adapters

•	Using Adapter Tester

When you set up an adapter tester, configuration for the tester is saved for each adapter in the project. You may, however, have to change some of the settings if you wish to run the tester on a different machine as the directories may not be valid.

Setup for Testing TIBCO Adapters

If the adapter you are trying to test is a TIBCO adapter, the adapter tester simplifies the configuration required from you to run the adapter. Provide the following information:

Table 41 Testing TIBCO Adapters

Working directory

Click Browse to supply the directory. The tester creates the necessary run-time and support files required by the adapter in this directory. All files created by the Adapter Tester are temporary and will be deleted when you exit TIBCO Designer. It is recommended that you do not edit the files in the working directory. Ensure that the disk where the working directory is located contains enough space to save multiple copies of your project.

Adapter executable

Choose the adapter from the pop-up. Make sure that the version of the run-time matches the version of the configuration. The adapter executable to run your 'packaged adapter' will be shown from a list of choices (each matching a particular installation). If the adapter supports multiple executables (one for a publisher, the other for a subscriber) be sure to select the correct one for the configuration you want to test.

A TRA template and other adapter arguments will be provided automatically by the tester tool.

If the adapter specifies global variables, you can enter values in the window that is displayed.

Setup for Testing Custom Adapters

Adapter Tester may work with GAC and other custom type adapters, however, TIBCO only supports this feature on packaged adapters.

If your adapter is an adapter configured using Generic Adapter Configuration GAC or a custom adapter that the TIBCO installer does not recognize, you need to provide the following information:

Table 42 Testing Custom Adapters

Working Directory	Working directory from which to execute the adapter. Click Browse to select the directory. See Setup for Testing TIBCO Adapters for more information.
Adapter Executable	Name of the executable for the adapter. Click Browse to select the executable. See Setup for Testing TIBCO Adapters for more information.
Arguments	Arguments passed to the adapter executable. The last argument should be '--propFile', the TRA template file containing information necessary for startup of the adapter will be the last argument provided to the operating systems shell.
TRA template	TRA template to use for the adapter. The tester tool will copy values in the template and perform any necessary variable expansions as well as add additional entries pointing to the project file, etc.

If the adapter specifies global variables, you can enter values in the window that is displayed.

If your GAC or custom adapters cannot be successfully run by providing the above values, you can check the Custom Shell Command check box.

This allows you to enter the working directory and shell command to execute. The shell command should include all arguments necessary to run the adapter. Note that in this mode, the project is not exported. You have to perform the export yourself. You may also need to create your own TRA file.

See the TIBCO Adapter SDK Programmer’s Guide more information on the available arguments and options for custom adapters.

Using Adapter Tester

To use Adapter Tester, follow these steps:

1.	Choose Tools> Show Adapter Tester

All adapter instances configured in the project are displayed.

2.	Select the adapter instance to test and provide the appropriate information in the Run Settings tab. See Setup for Testing TIBCO Adapters and Setup for Testing Custom Adapters for information.

3.	Click Start.

When the adapter is started, a green dot highlights the running adapter. The display changes to the Console tab. You can now observe the adapter as it executes. The Start button becomes a Stop button.

4.	Click Stop when you wish to stop adapter.

The button changes its name to Start and the green dot disappears.

Note under Java 1.3.x on windows you may see a Command Prompt window. This is normal. If you close the window, the adapter process will be terminated.

Copyright © TIBCO Software Inc. All Rights Reserved