This documentation applies to older versions of WSO2 ESB connectors. To find the documentation relevant to the version you are using, select the connector from the WSO2 Connector Store and click Documentation.

All docs This doc
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 44 Next »

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

You can create the required template using the maven archetype, and then run the following command to generate the maven project sample connector code:

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 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 upper camel case. For example, HelloWorld.

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

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.
/HelloWorldConnector.javaThis 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.xmlThis defines the connector name and dependent modules. (i.e. the metadata of the connector)
/sample-template.xmlThis 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. HelloWorldConnector.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.

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

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

packageThe Java package, from which connectors are implemented.
componentThe 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"/>

iconRelative path of the connector icon.

Edit the component.xml file

The component.xml 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 the methods 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.

PropertyDescription
name

The name of the resource/component.

typeThe type of the synapse component.
These resources are synapse templates. Therefore, the type is specified as synapse/template.
subComponents

The name of the method, which is ideally a sequence template.

file

The name of the method file with the extension.

description

A brief description about the functionality of the method.

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

You need to edit the sample-template.xml file to include the Synapse configuration for the methods 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 a 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 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 need to 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.

  1. Open the ESB Management Console, and in the Main tab under Connectors click Add. The Add Connector page opens.
  2. On the Add Connector page, click Choose File.
  3. Browse and select the HelloWorld-connector-1.0.0.zip file, and then click Upload. The following message will be displayed.
    browse and upload file
  4. On successful upload, you will see the following message.
    pop up 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.

 

  • No labels