Writing a Connector

This section walks you through the basic structure of a connector and describes

Creating the Maven project template

Execute the following command in your Command Line Interface (CLI), to generate an Apache Maven project for a sample connector code using an Maven archetype.

You may need to give a name for the connector while processing the above. E.g. you can give HelloWorldConnector as the connector name.

mvn archetype:generate -DarchetypeGroupId=org.wso2.carbon.extension.archetype -DarchetypeArtifactId=org.wso2.carbon.extension.archetype.esb.connector-archetype -DarchetypeVersion=1.0.2  -DgroupId=org.wso2.carbon.esb.connector -DartifactId=org.wso2.carbon.esb.connector.test -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/

This creates the org.wso2.carbon.esb.connector.test/ directory in the current location of your machine, with a directory structure similar to the following:

folder structure of a connector

The directory structure includes the following files and directories.

`pom.xml`	This contains the required dependencies for the connector core libraries, relevant Synapse libraries, and Maven repositories for a specific connector.
`/assemble-connector.xml/filter.properties`	These files are used at the connector build time. You do not need to modify this file.
`/HelloWorld.java`	This is required for integration tests of JAVA-based connectors. For information on editing it, see the example given below.
`/resources/config/component.xml`	This is included in each module, and defines the available methods in the module.
`/init.xml`	This is mandatory for every connector. Use this to initialize the connector environment. For example, when writing the Salesforce connector, include the login call here. You can store the `Sessiontoken` and `API UR` L returned as the response, in a property and use with other operations.
`/connector.xml`	This defines the connector name and dependent modules. (i.e. the metadata of the connector)
`/HelloWorld-template.xml`	This is the actual API operation calling configuration including the Synapse template of the sequence. This contains the steps necessary to call the API that is exposed by the third party. Each method 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 Java (e.g. `HelloWorld.java` file), and the relevant dependencies should be added to `pom.xml`

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

Editing the `connector.xml` file

This is the main component of the ESB connector, which contains the metadata of the connector. You can add any number of resources (referred to as components) inside the resource/ directory, and include all available resources, in this connector.xml file as dependencies, to load all methods 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
`name`	A name for the connector. This connector name should be unique, as t he connector methods will refer the connector using this as shown in the following example: `<twitter.getSearchTweets>...</twitter.getSearchTweets>`
`package`	The Java package, from which connectors are implemented.
`component`	The resources that are available inside the `resources/` directory of the folder structure.
`dependency`	Each dependency points to each resource/component. It will be used to load all methods implemented in the resource into the ESB. The `component` property denotes the name of the resource/component. For example, "`twitter-search`" is the resource name of the following dependency. `<dependency component="twitter-search"/>`
`icon`	Relative path of the connector icon.

Editing the `component.xml` file

This file defines the metadata of the component. You can add any number of components inside the resource/ directory, and each component can have multiple methods. You need to define all methods implemented in a component in the component.xml file as sub-components, as shown in the example below.

<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 above connector.xml file are described below.

Property	Description
`name`	A name for the resource/component.
`type`
`subComponents`	All the methods implemented in a component.
`component name`	The name of the method (i.e. ideally a sequence template).
`file`	The name of the method file with the extension.
`description`	A brief description about the functionality of the method.

Editing the sample Synapse template (`HelloWorld-template.xml` file)

You need to edit the HelloWorld-template.xml file to include the Synapse configuration for the methods as shown in the example below.

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

Sample HelloWorld.java file

A sample configuration you can use for integration testing of JAVA-based connectors is shown below.

/*
*  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.apache.abdera.Abdera;
import org.apache.abdera.model.Document;
import org.apache.abdera.protocol.client.AbderaClient;
import org.apache.synapse.MessageContext;
import org.wso2.carbon.connector.core.*;
import org.apache.abdera.model.Entry;

public class HelloWorldConnector extends AbstractConnector {

    Abdera abdera;
    AbderaClient abderaClient;

    Document<Entry> doc;
    String HostAddress;

    public void connect(MessageContext messageContext) throws ConnectException {

        try {
            /**
             * Add your connector code here
             */
            HostAddress = getParameter(messageContext, "HostAddress").toString();
            abdera = new Abdera();
            abderaClient = new AbderaClient(abdera);

                // Get the Entry from Server
                doc = abderaClient.get(HostAddress).getDocument();

        log.info(doc.getRoot());
        } catch (Exception e) {
            throw new ConnectException(e);
        }
    }
}

Adding dependencies

Add the following code to the pom.xml file, to add 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>

Building the connector

Navigate to the org.wso2.carbon.esb.connector.test/ directory using your CLI, and execute the following command to build the connector you created above: maven clean install

This generates the org.wso2.carbon.esb.connector.test/target/HelloWorldConnector.zip file.

Uploading the connector to WSO2 ESB

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

Log on to the ESB Management Console using the following URL and admin/admin credentials: https://<ESB_HOST>:<ESB_PORT>/carbon/
Click Main, click Manage, and then Click Add under the Connectors menu as shown below.
Click Choose File, browse and select the HelloWorldConnector.zip file, and click Upload as shown below.
Click OK in the message, which pops-up as shown below.
You view the new connector added to the list of all available connectors as shown below.
Click the corresponding Disbaled link of the connector, to enable it to use in WSO2 ESB as shown below. You view it being enabled as shown below.

Now that you understand the basic structure of a connector, you can start writing your own connector, which can either be a soap-based connector, REST-based connector or a JAVA API-based connector. For more information on how you can write your own connector based on the API you have decided to use, see Connector Types.