This blog is an updated version of a previous blog for the WSO2 Enterprise Service Bus 5.0.0.
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 org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeGroupId=org.wso2.carbon.extension.archetype -DarchetypeArtifactId=org.wso2.carbon.extension.esb.connector-archetype -DarchetypeVersion=2.0.4 -DgroupId=org.wso2.carbon.esb.connector -DartifactId=org.wso2.carbon.esb.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″}
Connectors are an easy way to make a connection to an external service. Using an existing connector from WSO2 will save you a lot of time figuring out how to connect and work with the online service. In case your favorite online service does not have a connector you can build one yourself. In case you are an online service provider and would like to have your service available to users as a connector it is good to know that you can submit the connector to WSO2 for review and potential addition to the WSO2 store.
Any questions regarding this blog? Please leave a comment. Do you want to learn more about WSO2? Sign up for one of our trainings by clicking the button below!
{{cta(‘d96cddee-168c-42a5-a0b6-00a670e766b7’)}}
