Connectors are becoming more and more important in the WSO2 ESB. It started with the creation of the WSO2 Store for ESB connectors (store.wso2.com) where you can find more and more connectors (over 150 at this moment) that will allow you to easily connect to a 3rd party system online (or if you prefer, in the cloud).
What is a connector?
A connector is, at a high level, a bundling of interface descriptions that will allow you to access a third party system. API’s are the most common incarnation of connectors but Java and SOAP are alternatives that can be used in a connector.
The mechanism behind it is simple: a structure that functionally bundles a number of specific interfaces (stored in directories) and an XML file structure (connectors and components) to make it machine readable.
How do you create a custom connector?
To create a custom connector you need to do the following:
- Research the APIs provided by the service for which you want to create a connector.
- Decide which API you are going to use to write the connector. For example, JIRA provides a REST API and Java API. If you choose the REST API, you can create your connector and operations entirely from XML configuration files. If you choose a Java API, you create XML configuration files that define your connector and point to your Java classes that define the operations.
- Use the connector core libraries to write your connector.
- After you create the files, you package them in a ZIP file, which you can then add to an ESB instance.
Detailed instructions
We will create the connector on the desktop without using Eclipse / Developer Studio. We assume a Linux based environment but for Windows it is basically the same. We create a simple Google Books API.
Open a terminal session, for instance on the desktop.
We create the required template using the maven archetype, and run the following command to generate the maven project sample connector code:
mvn archetype:generate -DarchetypeGroupId=org.wso2.carbon.extension.archetype -DarchetypeArtifactId=org.wso2.carbon.extension.esb.connector-archetype -DarchetypeVersion=2.0.0 -DgroupId=org.wso2.carbon.connector -DartifactId=org.wso2.carbon.connector.googlebooks -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/
| We have put googlebooks in RED since it indicates the name of the directory that is created. |
When you are generate the maven project sample connector code, it will prompt for a name for the connector. Specify the name of the connector in lower case. For example, googlebooks.
This creates within the org.wso2.carbon.esb.connector.googlebooks directory a number of artifacts for the in the current location of your machine.
In this example we will use Google Books API so specify connector name as googlebooks when asked. Enter Y to confirm.
The structure is now created and by default will create a tree structure with a pom.xml, src tree and repository tree. We will add and configure files in the /src/main/resources directory.
Start by removing the sample directory
Create a volume directory in /resources. Here we will place two files
Following Synapse template is providing the service at list volume.
This should be placed under /src/main/resources/volume directory as listVolume.xml.
<template name="listVolume" xmlns="http://ws.apache.org/ns/synapse">
<parameter name="searchQuery" description="Full-text search query string." />
<sequence>
<property name="uri.var.searchQuery" expression="$func:searchQuery" />
<call>
<endpoint>
<http method="get"
uri-template="https://www.googleapis.com/books/v1/volumes?q={uri.var.searchQuery}" />
</endpoint>
</call>
</sequence>
</template>
Create a component.xml file in volume directory with the following content. This file contains information about the operations in one category.
<?xml version="1.0" encoding="UTF-8"?>
<component name="googlebooks_volume" type="synapse/template">
<subComponents>
<component name="listVolume">
<file>listVolume.xml</file>
<description>List volumes matching for the given query.</description>
</component>
</subComponents>
</component>
Modify the connector.xml file by adding new dependency as below.
<?xml version="1.0" encoding="UTF-8"?>
<connector>
<component name="googlebooks" package="org.wso2.carbon.connector">
<dependency component="config" />
<dependency component="googlebooks_volume" />
<description>wso2 sample connector library</description>
</component>
</connector>
The config directory can stay as is since we do not need to login to the service in this example.
Build the code
We can now build the connector code using Maven.
run mvn clean install
from org.wso2.carbon.connector.googlebooks directory
Upload googlebooks.zip file from the target directory. You can upload this zip file through the ESB interface under connector category. Enable the connector after uploading.
Now you can define proxy service to invoke implemented connector.
Go to Home>Manage>Services>Add>Proxy Service>Custom Proxy>switch to source view and paste the following:
<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse" name="googlebooks_listVolume"
transports="https,http" statistics="disable" trace="disable"
startOnLoad="true">
<target>
<inSequence>
<property name="searchQuery" expression="json-eval($.searchQuery)" />
<googlebooks.listVolume>
<searchQuery>{$ctx:searchQuery}</searchQuery>
</googlebooks.listVolume>
<respond />
</inSequence>
<outSequence>
<log />
<send />
</outSequence>
</target>
<description />
</proxy>
Using a REST client (e.g. Advanced Rest Client), POST the following request body at http://localhost:8280/services/googlebooks_listVolume. Also, set the Content-Type to application/json. { “searchQuery”:”wso2″}
Read also our other WSO2 tutorials and blogs, written by our WSO2 Gurus. In case you need WSO2 support, contact the Yenlo WSO2 Guru team to get WSO2 Development Support or WSO2 Operational Support. Of course we do deliver excellent WSO2 training services as well, based on reallife WSO2 tutorials.
