In this article:
	Introduction
	Websphere Business Integration family
	Websphere BI Connectors
	Sample application
	Development of components of Greetings Connector
	Assembly and deployment of Greetings connector
	Running the connector
	Conclusion
	Download
	Resources
	About the author
	Rate this page

Related links
	WebSphere technical library

developerWorks > WebSphere >

Developing and testing WebSphere Business Integration connectors

Document options

Document options requiring JavaScript are not displayed

Sample code

Rate this page

Help us improve this content

Level: Intermediate

Amit Tuli (tamit@in.ibm.com), Staff Software Engineer, IBM

11 Jan 2006

Do you need to integrate a variety of legacy applications without making any changes to them? Websphere Business Integration can help you do this. This article introduces you to the world of connectors, explains the Websphere Business Integration Connector Framework, and shows you how to develop and run a sample connector.

Introduction

In today's businesses, the increasing number of applications and the increasing requirements to interchange data between them has made business integration technologies essential. IBM® WebSphere® Business Integration Connectors (hereafter called Websphere BI Connectors) let you quickly exchange information between disparate ERP and CRM applications using an enterprise service bus (ESB).

This article will show you how to develop a sample Websphere BI Connectors application using the products below, which should all be installed on your machine.

Eclipse IDE
Websphere MQ
Websphere Business Integration Connector Framework (hereafter called Websphere BI Connector Framework)

Websphere Business Integration family

IBM Websphere Business Integration is a family of products that help integrate new and existing applications. These products include design and development tools, run-time servers, monitoring tools, adapters, connectors, and more. Connectors enable the loose coupling of applications by providing high-level interfaces, freeing individual clients from the need to implement the specific interface of the target application.

Websphere BI Connectors

Websphere BI Connectors are Java™ components that receive requests from an integration broker, communicate with applications, and optionally return a response to the broker. The role of the integration broker is to integrate data between heterogeneous applications. Here are the components of connectors:

Business object: Holds information about the application entities. At development time, a business object (BO) is called a BO definition. The Client Development Kit has a tool called the Business Object Designer for developing business objects. A BO is an instance of a BO definition. A BO has some application-specific attributes and an active verb that determines the kind of processing performed by the connector. The standard verbs are create, retrieve, update, and delete. BOs are designed by developers.
Connector: Sends information about an application event to the integration broker and receives information about a request from the broker. A connector sends and receives information in the form of BOs. Each connector can support one or more BO definitions. Connectors are developed by developers.
Connector framework: The run-time that supports interaction between the connector and the integration broker. Acts as a container for the connector.
Application-specific component: Contain application-specific code, including a base class to initialize the connector, a BO handler to respond to request BOs initialized by the integration broker, and an optional event notification mechanism to detect and respond to application events. Application-specific component are developed by developers.

The image below shows the relationship of the components of Websphere BI Connectors:

Figure 1. Components of Websphere BI Connectors

Connector framework

The connector framework manages the interaction between the connector and the integration broker. One subcomponent, the transport layer, defines how data is sent to and from the integration broker. Another subcomponent, called generic services, connects to custom applications using a C++ or Java API.

Sample application

The sample application, called the Greetings application, assumes that there is a simple Java program to which you pass username as a String and the program echoes back the username with greetings. For example, if you pass "Smith" it will return "Hello Smith." We will build an adapter around this application. This adapter will receive a BO and connect to the Greetings application. Since the application is not creating or updating any real entity, the active verb in the BO does not really make sense, but in any case we will use the create verb.

Here is the run-time architecture of our application:

Figure 2. Run-time architecture of Greetings Connector

Development of components of Greetings Connector

As described above, there are various components involved in connector development. We will develop some of those components here. Lets look at each of them one-by-one.

Business Object: In the Greetings application, the BO has the following attributes:

userName: Application will use this name for greeting.
response: Return greeting sent by connector to the broker.

Design the BO using the BO Designer tool:

On the Windows® menu, click Start => All Programs => IBM Websphere Business Integration Adapters => IBM Websphere Business Integration Toolset => System Manager.
In the System Manager window, click File => New => Integration Component Library.
A model window will open asking for a project name. Enter Greetings and click Finish.
Select the Greetings project and click Tools => Business Object Designer.
A new window will open and ask for the business object name. Enter GreetBO. Make sure that Greetings is selected in the Create in project drop-down. Click OK.
In the BO Designer, click the Attributes tab if it is not already selected. A blank row will be created by default.
Enter userName in the Name column.
Enter String in the Type column in the same row.
Check the Key checkbox.
In the next row, enter response in the Name column and String in the Type column.
Click File => Save to save the BO.

Here is the BO Designer with the Greetings connector:

Figure 3. Business Object Designer

The connector configuration file contains connector-specific properties that are used by application-specific components at run time. To create the connector configuration file:

In the System Manager window, select the project Greetings and click Tools => Connector configurator.
A new window will open asking for name and other properties. Enter Greetings in the Name field.
Select WAS from the Integration Broker drop-down.
Select None for Template Name.
Click OK.
The connector configuration file has the name of the queue manager, request queue, response queue, and so on. Check the jms.MessageBrokerName entry. It specifies the queue manager name -- the default is crossworlds.queue.manager. Similarly, there are many entries, including queue names, broker type, trace level, repository directory, and so on.
Click the Supported Business Objects tab. Click on the first row and select GreetBO from the drop-down.
Click File => Save => To Project.
Close the Connector Configurator.

Figure 4 shows the Connector Configurator and some of the connector-specific properties of the Greetings connector:

Figure 4. Connector Configurator

The application-specific component contains code for connecting to and communicating with the application. To develop this component:

Open the Eclipse IDE.
Click File => New => Project.
From the modal window, select Java => Java Project and click Next
Enter Greetings in the Project Name box and click Next.
Click Add Folder. For Folder name, enter src and click OK, then click Yes. Source folders on build path should change to Greetings/src and Default output folder to Greetings/bin.
Click Finish on Java Settings.

These steps generate a blank project. Now you need to create the required classes. A typical connector needs classes for event processing, but they are not needed in this article. A few classes are required for BO handler and connector agent. Before writing connector classes, create the Greetings class, which will be called by this connector. Since it is a standalone class, create it in the same project but in a different package:

Click File => New => Class.
Enter com.greetings in the Package field and Greetings in the Name field. Click Finish.
The Greetings class will open in the editor. If it does not, then open it.

Add the method greetUser:

public String greetUser(String userName){
	return "Hello " + userName;
}

Of the required classes, first create the agent class, which is instantiated when starting the connector. It passes the BO to the appropriate BO handler on each request from the broker. Create a new class in Eclipse under the Greetings project. Name of this class com.WAS.adapters.Greetings.GreetingsAgent. This class extends from com.crossworlds.cwconnectorapi.CWConnectorAgent. Here are a few of the important methods that are implemented in typical connectors:
- public String getVersion()
- public void agentInit()
- public CWConnectorBOHandler getConnectorBOHandlerForBO(String BOName)
In our sample, we will implement only getConnectorBOHandlerForBO(). This method is called to get the appropriate BO handler for the received BO. Within this method, we return the instance of the class that handles the BO. In our case, there is a single BO, so we will not check for BO name and return the instance of com.WAS.adapters.Greetings.ReqProcessing.GreetingsBOHandler. This class is created next -- see the listing below.
return new com.WAS.adapters.Greetings.ReqProcessing.GreetingsBOHandler();

Next, create the BO Handler. Create a new class in Eclipse under the Greetings project. Name this class com.WAS.adapters.Greetings.ReqProcessing.GreetingsBOHandler. This class extends from com.crossworlds.cwconnectorapi.CWConnectorBOHandler. Here is the only required method of this class to be implemented:
public int doVerbFor(CWConnectorBusObj theBusObj)

This method is called each time the connector framework receives the supported BO from the broker. This method checks for the active verb that is passed in the BO and calls the appropriate method to serve that verb:

String verb = theBusObj.getVerb();
if("Create".equals(verb)){
	status = doCreate(theBusObj);
}
else if("Retrieve".equals(verb)){
	status = doRetrieve(theBusObj);
}
else if("Update".equals(verb)){
	status = doUpdate(theBusObj);
}
else if("Delete".equals(verb)){
	status = doDelete(theBusObj);
}
else{
	//Not a valid verb 
	return CWConnectorConstant.FAIL;
}

Complete source of above method can be found in the zip in the Downloads section.

Since we are supporting only the create verb, we need to modify corresponding method. Add a new method private int doCreate(CWConnectorBusObj theBusObj). Go to the doCreate method.

In this method, we will instantiate the com.greetings.Greetings class, retrieve the value of userName attribute from the BO, call the legacy method greetUser on the Greetings object, and set the response attribute of the BO with the response of greetUser:

Greetings gr = new Greetings();
String userName = "";
try {
	userName = theBusObj.getStringValue("userName");
} catch (WrongAttributeException e) {
	e.printStackTrace();
} catch (AttributeNotFoundException e) {
	e.printStackTrace();
}
String response = gr.greetUser(userName);
try {
	theBusObj.setStringValue("response", response);
} catch (WrongAttributeException e1) {
	e1.printStackTrace();
} catch (AttributeNotFoundException e1) {
	e1.printStackTrace();
} catch (AttributeValueException e1) {
	e1.printStackTrace();
}
return CWConnectorConstant.VALCHANGE;

Code for other methods such as doUpdate(), doRetreive(), and so on are in the zip file that you can download below.

The code for one more class, com.WAS.adapters.Greetings.utilities.GreetingsUtils, which has methods for logging and tracing, is also in the zip file.

To resolve the compilation errors:

Right-click on the Greetings project and select Properties.
In the left panel, click Java Build Path and in the right panel select the Libraries tab.
Click Add External JARs. Browse to the <CONNECTOR_HOME>/lib directory, select WBIA.jar, and click Open. Similarly, from the <CONNECTOR_HOME>/wbiart directory, add wbiart.jar.
Click OK to close the window.

You have finished the development stage of the connector and can continue with the assembly, deployment, and testing stages.

Assembly and deployment of Greetings connector

This section shows you how to assemble components of the connector and how to deploy the connector with the connector framework.

Assembling the connector

Bundle the compiled connector code in a JAR file:

Open a command window and go to the <ECLIPSE_WORKSPACE>/Greetings/bin folder.
Execute the command jar cvfM BIA_Greetings.jar com to create BIA_Greetings.jar for deployment.

Deploying the connector

Deployment involves a number of steps: updating the connector framework for this new connector, creating the required queue manager and queues, setting the classpath, and more.

Open Windows Explorer and in the <CONNECTOR_HOME>/connectors folder, create a new folder called Greetings.
Copy <ECLIPSE_WORKSPACE>/Greetings/bin/BIA_Greetings.jar into the <CONNECTOR_HOME>/connectors/Greetings folder.
Copy configure_mq.bat, crossworlds_mq.tst, start_connName.bat, and start_mq.bat from the <CONNECTOR_HOME>/templates folder into the <CONNECTOR_HOME>/connectors/Greetings folder.
Go to the <CONNECTOR_HOME>/connectors/Greetings folder.
Open crossworlds_mq.tst in a text editor. Ignore the commented lines at the top of the file and remove the first two un-commented lines. The first one starts with DEFINE QLOCAL(IC/SERVER_NAME. Scroll down and change 8 instances of AdapterName to Greetings. Ignore the entries in comments. Save and close the file.
Rename start_connName.bat to start_Greetings.bat. Open this file in a text editor and add the following line just before the setlocal statement: set CONNDIR="%WBIA_RUNTIME%"\connectors\Greetings.
Continuing with start_Greetings.bat, remove rem from the statements that are setting JVMArgs, JCLASSES, LibPath, and ExtDirs. Also, set JCLASSES to %CONNDIR%\BIA_Greetings.jar.
Go to the statement that starts the Java connector, which is just before the endlocal statement. Replace connName with Greetings, serverName with WAS, connectorSpecificClasses with com.WAS.adapters.Greetings.GreetingsAgent, ... after -f with no, ... after -p with null, and ... after -c with %CONNDIR%\Greetings.cfg. Remove the last .... Save and close start_Greetings.bat.
Open the Connector Configurator as you did when creating the connector configuration file. Click File => Save. Select the <CONNECTOR_HOME>/connectors/Greetings folder. Make sure that File Name is Greetings; if not, enter it and click Save. Close the Connector Configurator.
Open the System Manager as you did when creating business a object. Click Greetings => Business Objects => GreetBO. Double click on GreetBO to open the BO Designer. Click File => Save Copy To File. In the window that opens, browse to the folder <CONNECTOR_HOME>/repository. which is the same path as given in the connector configuration file for RepositoryDirectory. Enter the name as GreetBO if it is not already filled and click Save. Close the BO Designer.
As the last step of deployment, create the required queue manager and queues.
Open a command window and execute the command crtmqm crossworlds.queue.manager to create the queue manager.
In the command window, go to <CONNECTOR_HOME>/connectors/Greetings and execute the command configure_mq.bat crossworlds.queue.manager crossworlds_mq.tst. After the script executes, you will see the message 9 MQSC commands read, which means queues have been created successfully. Queue names are taken from crossworlds_mq.tst, which is passed as second argument to the batch file.

You have finished deployment of the connector and are ready to run it.

Running the connector

Several applications are involved in running the connector. You use Visual Test Connector to create a BO, and Websphere MQ to run the queues so that the connector framework can receive messages from the broker. The MQ utility Rfhutil.exe is required to manipulate queues, store response messages, retrieve request messages from files, and so on.

Open a command window and go to <CONNECTOR_HOME>/connectors/Greetings. Execute the command start_mq.bat crossworlds.queue.manager. Leave this command window open.
Open a new command window and go to <CONNECTOR_HOME>/connectors/Greetings. Execute the command start_Greetings.bat. It will start the Greetings connector. Watch for the message Click q to quit connector at the end of the log in this window. It means that connector was started successfully.
Go to <CONNECTOR_HOME> and delete the file Greetings.lock. This file was generated by the previous command starting the connector. Since you are going to start the Visual Test Connector and it also tries to start the connector, there will be a conflict. Removing this file does not harm the normal execution of the connector.
Click Start => All Programs => IBM Websphere Business Integration Adapters => IBM Websphere Business Integration Toolset => Visual Test Connector. The Test Connector window will open.
In the Test Connector window, click File => Create/Select Profile. In the new window, click File => New Profile. In the New Profile window, browse to <CONNECTOR_HOME>/connectors/Greetings and select Greetings.cfg. Click Open, enter Greetings as Connector Name and select WAS from Broker Type. Click OK. Select Greetings from the list and click OK again.
Now click File => Connect. In the bottom pane of this window, the message Greetings Ready will be displayed. If the window closes, remove Greetings.lock from <CONNECTOR_HOME> and restart the Visual Test Connector again. This time, the profile will already be there, so just select from the list and continue.
Select GreetBO from Business Object Type and click Create. Enter greet in the new window and click OK.
Enter Amit in the Value column against userName. We are sending the BO with just userName set. The received BO would have response field set also with the greetings.
Click Request => Send. This will send the BO to the GREETINGS/DELIVERYQUEUE. Your test connector window will look like this:

Figure 5. Visual Test Connector
Close the Test Connector, as we no longer need it. The BO has already been sent and the remaining tasks will be done with the help of Rfhutil.exe. The Test Connector will listen to GREETINGS/REQUESTQUEUE, and the connector that we started is also listening to the same queue. Therefore, the connector may not work properly, which is one more reason to close the Test Connector.
Execute Rfhutil.exe from <CONNECTOR_HOME>/connectors/Greetings. Select crossworlds.queue.manager from Queue Manager Name. Select GREETINGS/DELIVERYQUEUE from Queue Name and click Read Q. Then click Write File. Go to <CONNECTOR_HOME>/connectors/Greetings and name the file greetings_request.bo. We have saved the BO for future use. Now we can modify the BO in a text editor and send it to the connector for processing. Visual Test Connector is no longer required.
Open <CONNECTOR_HOME>/connectors/Greetings/greetings_request.bo in a text editor. If you want to make any changes to the userName attribute, do so here, then save the changes and close the file. Otherwise, leave the file as-is.
In the Rfhutil window, select GREETINGS/REQUESTQUEUE from Queue Name. At bottom right, check the box Set User/App Id. Click on the MQMD tab and enter crossworlds.queue.manager in Reply to Queue Manager and GREETINGS/RESPONSEQUEUE in Reply To Queue. Go back to the Main tab.
Click Read File and select greetings_request.bo. Click Write Q.
Select GREETINGS/RESPONSEQUEUE from Queue Name and click Read Q. Now click Write File and enter the filename as greetings_response.bo. Make sure the folder selected was <CONNECTOR_HOME>/connectors/Greetings.
Open greetings_response.bo in a text editor. Note that an element like <Q1:response> has the value Hello Amit, which is the response sent by the greetUser method of the Greetings application.

Figure 6. Rfhutil Utility

Conclusion

This article demonstrated a simple connector which supports the Create verb but does not actually create or update any real entity or do any event notification. You can extend this sample and use other connector features such as event notification, connection to applications, multiple verbs in a BO, multiple BOs for a connector, multiple BO handlers, and so on.

Back to top

Download

Description	Name	Size	Download method
Code samples in zip format	j-adaptersample.zip	4 KB	FTP\|HTTP


	Information about download methods

Resources

WebSphere Business Integration products page
For both business and technical users, a handy overview of all WebSphere Business Integration products
developerWorks WebSphere Business Integration zone
For developers, access to WebSphere Business Integration how-to articles, downloads, tutorials, education, product info, and more.
Trial downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
Safari Bookshelf: e-library designed for developers
Complete search and download access to thousands of technical books for a one-time subscription fee. Free trial for new subscribers.
WebSphere forums
Product-specific forums where you can ask questions and share your opinions with other WebSphere users.
developerWorks blogs
Ongoing, free-form columns by software experts, to which you can add your comments. Check out Grady Booch's blog on software architecture.

About the author


		Amit Tuli is a staff software engineer with IBM India Software Labs. He is currently working on IBM WebSphere Business Integration for a telecom project in the Solutions Group of ISL. He has five years of technical experience in Java and server-side programming on multiple platforms. He has also worked with India Research Lab on the IBM WebFountain SDK project. His areas of expertise include designing and developing stand-alone to n-tier distributed applications.

Rate this page

Share this....

Digg this story

del.icio.us

Slashdot it!

Back to top