Getting Started with WSO2 ESB Connectors

Enterprise Service Bus (ESB) is the infrastructure which provides the implementation of the concept of Service Oriented Architecture (SOA). The connectors are the new concept coming with the wso2 ESB version 4.8.0 and above. Connector is an intermediate API layer, which will represent a real world developer API, while being in the ESB itself. With this post, the initial steps to create a connector will be described.

Download Maven Dependencies:
You need to checkout the source code from here and run maven install command on it. It will download set of required dependencies to your local maven repository. Following are the commands if you have a command line SVN and maven client.

$svn co https://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/components/mediation/mediation-library/connector-template-utils/org.wso2.carbon.mediation.library.connectors.connector-archetype/
$cd org.wso2.carbon.connector/
$mvn clean install

Generate Connector Folder Structure:
Run the following maven command to generate maven project sample connector code.

$mvn archetype:generate -DarchetypeGroupId=org.wso2.carbon -DarchetypeArtifactId=org.wso2.carbon.mediation.library.connectors.connector-archetype -DarchetypeVersion=4.2.0 -DgroupId=org.wso2.carbon.connector -DartifactId=org.wso2.carbon.connector -Dversion=4.2.0

You may need give a name for the connector while processing the above process. (Let's proceed with entering googlebooks as connector name.) If the project creation success, you are ready to develop a connector with the following directory structure.

Fig. 1 : Connector Directory Structure

Before developing, there are some main components which you need to know.

Synapse Template : This is the component which calling to actual end point with the given request data. This will be placed in resources directory.

Proxy : This will handle the request coming inside to the ESB and response coming from the actual end point. This is not a part of connector, but need to invoke the connector.

Request : The request which follows the API published from the connector. This request can be REST or SOAP.

Connector for which API ?
There are large number of services which is provide in the world wide web to do a specific functions. In order to use these for developers, there will be one or several web service APIs  like REST, SOAP or a client libraries in one or several languages are provided by the service provider. Out of these, REST will be the simplest one that others since it has less work. Here we are using Google Book REST API which does not need authentication for some of services like volume search.

First we'll go the Google Books REST API documentation and identify the categorization of the services in GoogleBooks API. The services are categories like Bookshelf, Volume, Bookshelf.volumes etc. So we'll create new directory "volume" under resources directory, to place services in the Volume category.

Writing Synapse Template :
You can have a look on the sample Synapse template generated at helloWorld directory. Following synapse template is providing the service at list volume. This should be placed under "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 following content.

<?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 conector.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="helloWorld"/>
         <dependency component="googlebooks_volume"/>
         <description>wso2 sample connector library</description>
     </component>
</connector>

Now you can build the connector code and test the implemented service foe volume search method. To build the connector, run maven clean install command from the org.wso2.carbon.connector directory.

$mvn clean install

This will generate googlebooks.zip file in the target directory. You can upload this zip file through the ESB interface under connector category. Make sure you enabled the connector after uploading.

Writing Proxy :
Now you can invoke the implemented service for search volumes, by writing a proxy through ESB server interface. (Home>Manage>Services>Add>Proxy Service>Custom Proxy>switch to source view)

<?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>

Request :
Using a REST client, send following request, (you can use POSTMAN)

POST /services/googlebooks_listVolume HTTP/1.1
{
    "searchQuery":"aladin"
}

Hope you get the correct response ;)