Writing a Connector

This section walks you through the steps you need to follow when writing a connector.

Following are the high level steps you need to follow:

Create the Maven project template

To use the maven archetype to generate the Maven project template and sample connector code, run the following command in the directory where you want to create the connector on your local machine:

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.helloworld -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/

When prompted, enter a name for the connector. Specify the name in upper camel case, such as HelloWorld. Type y to confirm.

The org.wso2.carbon.esb.connector.helloworld directory is now created with a directory structure similar to the following:

The directory structure includes the following files and directories.

`pom.xml`	Contains the required dependencies for the connector core libraries, relevant Synapse libraries, and Maven repositories for a specific connector.
`assembly`	Contains files that are used at the connector build time. You do not need to modify these files.
`src/main/java` directory	Contains any Java code for the connector.
`src/main/resources` directory	Contains the configurations and definitions for the connector and its methods (referred to as operations). The `config` directory defines the initialization of the connector. You add additional directories for each category of operations (component) you want to create. In the Hello World sample, there is just one additional directory, `sample`, where the single operation for this sample connector is defined. However, in the ActiveCollab connector, for example, there are several component subdirectories such as `activecollab-people` and `activecollab-projects`, which contain the operations relevant to working with people and projects, respectively.
`component.xml`	Defines the metadata for the operations in each component. You create a `component.xml` file in each subdirectory under `src/main/resources`.
`sample-template.xml`	Defines an operation. This is the actual API operation calling configuration including the Synapse template of the sequence. It contains the steps necessary to call the API that is exposed by the third party. For example, the ActiveCollab connector has `createClient.xml` and `listCompanies.xml` in the `activecollab-people` directory to define those two operations for working with people. Each operation of the API can be written in a manner similar to `init.xml` . If there is any Java code, the code should be included under `src/main/java` (e.g., the `HelloWorldConnector.java` file), and the relevant dependencies should be added to `pom.xml`.
`init.xml`	Appears in the `config` directory under `src/main/resources`. This is mandatory for every connector and is used to initialize the connector environment. For example, if writing a Salesforce connector, include the login call here, and store the session token and API URL that are returned in the response as properties to use with other operations.
`connector.xml`	Defines the connector name and dependent modules (i.e., the metadata of the connector).
`src/test` directory	Contains integration tests. This is required for integration tests for Java-based connectors. For more information, Perform integration tests below.

After creating the Maven project template, import it to an IDE, and edit the following files.

Edit the `connector.xml` file

This connector.xml file contains the metadata for the connector. You can add any number of components inside the resources directory, and then add them as dependencies in the connector.xml file to load all operations implemented in those components. Following is a sample connector.xml file.

<connector>
   <component name="twitter" package="org.wso2.carbon.connectors">
       <dependency component="twitter-config"/>
       <dependency component="twitter-search"/>
       <description>synapse library for twitter connector</description>
   </component>
   <icon>icon/icon-twitter-small.png</icon>
</connector>

The properties of the above connector.xml file are described below.

Property	Description
`component`	Defines the name of the connector, the package, and the components inside the `resources` directory that you want the connector to expose.
`name`	A name for the connector. This connector name should be unique, as the connector methods will refer to the connector using this name as shown in the following example: `<twitter.getSearchTweets>...</twitter.getSearchTweets>`
`package`	The Java package from which connectors are implemented.
`dependency`	Each dependency points to a component in the `resources` directory. It will be used to load all operations implemented in that component into the ESB. The `component` property specifies the name of the component. For example, "`twitter-search`" is the resource name of the following dependency: `<dependency component="twitter-search"/>`
`icon`	Relative path of the connector icon.

Edit the `component.xml` file

The component.xml file defines the metadata of a component. You can add any number of components inside the resources directory, and each component can have multiple operations. You define all the operations implemented within a component as sub-components in the component.xml file as follows:

<component name="twitter-search" type="synapse/template">
   <subComponents>
       <component name="getSearchTweets">
           <file>getSearchTweets.xml</file>
           <description>
               Returns a collection of relevant Tweets matching a specified query.
           </description>
       </component>
       <component name="getSavedSearchesList">
           <file>getSavedSearchesList.xml</file>
           <description>Returns the authenticated user’s saved search queries.</description>
       </component>
   </subComponents>
</component>

The properties of the component.xml file are described below.

Property	Description
`name`	The name of the component.
`type`	The type of the Synapse component. These resources are Synapse templates, so the type is specified as `synapse/template`.
`subComponents`	Defines the operations in the component.
`file`	The name of the operation file with the extension.
`description`	A brief description about the functionality of the operation.

Edit the sample Synapse template (`sample-template.xml` file)

Each Synapse template file defines an operation. For the Hello World sample, edit the sample-template.xml file to include the Synapse configuration for the operation as follows:

<template xmlns="http://ws.apache.org/ns/synapse" name="helloworldconnector-operation">
    <parameter name="HostAddress"/>
    <sequence>
        <log level="full">
            <property name="HostAddress" expression="$func:HostAddress" />
        </log>
        <class name="org.wso2.carbon.connector.HelloWorldConnector" />
    </sequence>
</template>

Perform integration tests

Following is sample code to perform integration tests. You can write the test methods for each connector operation in this class.

/*
*  Copyright (c) 2005-2010, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
*
*  WSO2 Inc. licenses this file to you under the Apache License,
*  Version 2.0 (the "License"); you may not use this file except
*  in compliance with the License.
*  You may obtain a copy of the License at
*
*    http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied.  See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.wso2.carbon.connector;

import org.json.JSONObject;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.Test;
import org.wso2.connector.integration.test.base.ConnectorIntegrationTestBase;
import org.wso2.connector.integration.test.base.RestResponse;

import java.util.HashMap;
import java.util.Map;

/**
 * Sample integration test
 */
public class HelloWorldConnectorIntegrationTest extends ConnectorIntegrationTestBase {

    private Map<String, String> esbRequestHeadersMap = new HashMap<String, String>();
    private Map<String, String> apiRequestHeadersMap = new HashMap<String, String>();

    @BeforeClass(alwaysRun = true)
    public void setEnvironment() throws Exception {
        init("HelloWorld-connector-1.0.0");
        esbRequestHeadersMap.put("Accept-Charset", "UTF-8");
        esbRequestHeadersMap.put("Content-Type", "application/json");
    }

    @Test(enabled = true, groups = {"wso2.esb"}, description = "HelloWorld test case")
    public void testSample() throws Exception {
        log.info("Successfully tested");
        RestResponse<JSONObject> esbRestResponse =
                sendJsonRestRequest(proxyUrl, "POST", esbRequestHeadersMap, "sampleRequest.json");
    }
}

Add dependencies

Add the following code to the pom.xml file to add the dependencies.

<dependencies>
    <dependency>
        <groupId>org.apache.synapse</groupId>
        <artifactId>synapse-core</artifactId>
        <version>2.1.7-wso2v3-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>org.wso2.carbon</groupId>
        <artifactId>org.wso2.carbon.mediation.library.connectors.core</artifactId>
        <version>4.1.0</version>
    </dependency>
</dependencies>
<pluginRepositories>
    <pluginRepository>
        <id>wso2.releases</id>
        <name>WSO2 internal Repository</name>
        <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </pluginRepository>
    <pluginRepository>
        <id>wso2.snapshots</id>
        <name>Apache Snapshot Repository</name>
        <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
        </snapshots>
        <releases>
            <enabled>false</enabled>
        </releases>
    </pluginRepository>
    <pluginRepository>
        <id>wso2-nexus</id>
        <name>WSO2 internal Repository</name>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </pluginRepository>
</pluginRepositories>
<repositories>
    <repository>
        <id>wso2-nexus</id>
        <name>WSO2 internal Repository</name>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </repository>
    <repository>
        <id>wso2.releases</id>
        <name>WSO2 internal Repository</name>
        <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </repository>
    <repository>
        <id>wso2.snapshots</id>
        <name>Apache Snapshot Repository</name>
        <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
        </snapshots>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
</repositories>

Build the connector

Navigate to the org.wso2.carbon.connector.helloworld directory, and execute the maven clean install command to build the connector you created.

This generates the org.wso2.carbon.connector.helloworld/target/HelloWorld-connector-1.0.0.zip file.

Upload the connector to WSO2 ESB

Follow the steps below to upload the connector you created to WSO2 ESB.

You must have WSO2 ESB installed to upload a connector to WSO2 ESB via the Management Console. For information on installing WSO2 ESB, see the Installation Guide.

Open the ESB Management Console, and in the Main tab under Connectors click Add. The Add Connector page opens.
On the Add Connector page, click Choose File.
Browse and select the HelloWorld-connector-1.0.0.zip file, and then click Upload. The following message will be displayed.
On successful upload, you will see the following message.

Click OK. You will see that the connector is added to the list of all available connectors.

For detailed information on working with connectors via the the ESB Management Console, see Working with Connectors via the Management Console.