Create a New Connector¶

You can write a new connector for a specific requirement that cannot be addressed via any of the existing connectors that can be downloaded from the connector store.

Follow the steps given below to write a new connector to integrate with the Google Books service. You can then use the connector inside a mediation sequence to connect with Google Books and get information.

Write a new connector¶

Follow the steps given below to write the new connector.

Prerequisites¶

Download and install Apache Maven.

Step 1: Create the Maven project template¶

We will use the maven archetype to generate the Maven project template and sample connector code.

Open a terminal, navigate to the directory on your machine where you want the new connector to be created, and run the following command:

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/

2. When prompted, enter a name for the connector. For example, googleBooks.
3. When prompted for confirmation, enter y.

The org.wso2.carbon.esb.connector.googlebooks directory is now created with a directory structure consisting of a pom.xml file, src tree, and repository tree.

Step 2: Add the new connector resources¶

Now, let's configure files in the org.wso2.carbon.esb.connector.googlebooks/src/main/resources directory:

Create a directory named googlebooks_volume in the /src/main/resources directory.

Create a file named listVolume.xml with the following content in the googlebooks_volume directory:

<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 file named component.xml in the googlebooks_volume directory and add the 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>Lists volumes that satisfy the given query.</description>
        </component>
    </subComponents>
</component>

Edit the connector.xml file in the src/main/resources directory and replace the contents with the following dependency:

<?xml version="1.0" encoding="UTF-8"?>
<connector>
    <component name="googleBooks" package="org.wso2.carbon.connector" >
      <dependency component="googlebooks_volume"/>
        <description>wso2 sample connector library</description>
    </component>
</connector>

Create a folder named icon in the /src/main/resources directory and add two icons.

Tip

You can download icons from the following location: icons

You are now ready to build the connector.

Step 3: Build the connector¶

Open a terminal, navigate to the org.wso2.carbon.esb.connector.googlebooks directory and execute the following maven command:

mvn clean install

This builds the connector and generates a ZIP file named googleBooks-connector-1.0.0.zip in the target directory.

Use the new connector¶

Now, let's look at how you can use the new connector in a mediation sequence.

Step 1: Add the connector to your mediation sequence¶

Set up WSO2 Micro Integrator Visual Studio Code extension.
Create an ESB Config project and add the connector ZIP file to the directory /src/main/wso2mi/resources/connectors/ of your project.

Tip

Be sure to select the new googleBooks-connector-1.0.0.zip file from your org.wso2.carbon.esb.connector.googlebooks/target directory.
Create a custom proxy service named googlebooks_listVolume. In the graphical view, you will see that the new connector has been added to the tool palette under the Local Connectors section.

Now, update the proxy service as shown below. You will be defining a mediation logic using the Property mediator, the new googleBooks connector, and the Respond mediator.:

<?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>
   </target>
</proxy>

Step 2: Build and deploy the artifacts¶

In order to build and deploy the artifacts, refer the build and run guide.

Step 3: Test the connector¶

Post a request to the proxy service using Curl as shown below.

curl -v -X POST -d "{"searchQuery":"rabbit"}" -H "Content-Type: application/json"  http://localhost:8290/services/googlebooks_listVolume

This performs a search and displays a list of volumes that meet the specified search criteria.