Writing a WSO2 ESB Mediator

Mediators provide an easy way of extending the ESB functionalities. WSO2 ESB is based on the WSO2 Carbon platform, which uses OSGI as the underlying technology. It implies everything that runs inside the WSO2 ESB to be OSGI bundles.

There are two ways of writing the ESB mediator:

Using Class Mediator - does not allow mediator specific XML configurations.
Writing the mediator with Factory and Serialize methods - allows mediator to have its own XML configuration.

Writing the mediator is straightforward in any of these cases. The easiest way to write the mediator is to extend your mediator class from org.apache.synapse.mediators.AbstractMediator class.

You can use the Class mediator and custom mediators for user-specific, custom developments when there isn't a built-in mediator that already provides the required functionality. However, there is a very high maintenance overhead in Class and custom mediators. Custom mediators in particular might introduce some version migration complications when upgrading the ESB. Therefore, avoid using them unless the scenario is frequently re-used and heavily user-specific. For best results, use WSO2 Developer Studio for debugging Class and custom mediators.

You can see detailed information on how to write the mediator here:

1. Writing a Mediator in WSO2 ESB - Part 1

2. Writing a Mediator in WSO2 ESB - Part 2

After you write the mediator, you must build it with WSO2 ESB and make it an OSGI bundle so that it will work with the ESB.

Basic approach

Simply create a regular JAR that links to the Synpase core JAR and put it in the repository/components/lib directory. The platform will automatically make it an OSGI bundle and deploy it to the server.

Advanced approach

If you want to control the way your mediator is created as an OSGI bundle, you must write the POM files so that you can export and import the packages you need, as shown in the examples below.

Following is a POM file that creates the mediator using Class Mediator.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>org.test</groupId>
    <artifactId>org.test</artifactId>
    <version>1.0.0</version>
    <packaging>bundle</packaging>
    <name>My Samples - Test mediator</name>
    <url>http://www.test.com</url>

    <repositories>
        <repository>
            <id>wso2-maven2-repository</id>
            <url>http://dist.wso2.org/maven2</url>
        </repository>
        <repository>
            <id>apache-Incubating-repo</id>
            <name>Maven Incubating Repository</name>
            <url>http://people.apache.org/repo/m2-incubating-repository</url>
        </repository>
        <repository>
            <id>apache-maven2-repo</id>
            <name>Apache Maven2 Repository</name>
            <url>http://repo1.maven.org/maven2/</url>
        </repository>
    </repositories>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.0</version>
                <configuration>
                    <source>1.5</source>
                    <target>1.5</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>1.4.0</version>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        <Bundle-SymbolicName>org.test</Bundle-SymbolicName>
                        <Bundle-Name>org.test</Bundle-Name>
                        <Export-Package>
                            org.test.mediator.*,
                        </Export-Package>
                        <Import-Package>
                            *; resolution:=optional
                        </Import-Package>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>
        <dependency>
            <groupId>org.apache.synapse</groupId>
            <artifactId>synapse-core</artifactId>
            <version>2.1.1-wso2v5</version>
        </dependency>
    </dependencies>
</project>

The Maven bundle plug-in was used for creating the OSGI bundle here. Make sure you export the correct package that contains the mediator code. Otherwise, your mediator will not work.

Following is a POM file that creates the mediator with its own XML configuration using the Serialize and Factory classes.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>org.test</groupId>
    <artifactId>org.test</artifactId>
    <version>1.0.0</version>
    <packaging>bundle</packaging>
    <name>My Samples - Test mediator</name>
    <url>http://www.test.com</url>

    <repositories>
        <repository>
            <id>wso2-maven2-repository</id>
            <url>http://dist.wso2.org/maven2</url>
        </repository>
        <repository>
            <id>apache-Incubating-repo</id>
            <name>Maven Incubating Repository</name>
            <url>http://people.apache.org/repo/m2-incubating-repository</url>
        </repository>
        <repository>
            <id>apache-maven2-repo</id>
            <name>Apache Maven2 Repository</name>
            <url>http://repo1.maven.org/maven2/</url>
        </repository>
    </repositories>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.0</version>
                <configuration>
                    <source>1.5</source>
                    <target>1.5</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>1.4.0</version>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        <Bundle-SymbolicName>org.test</Bundle-SymbolicName>
                        <Bundle-Name>org.test</Bundle-Name>
                        <Export-Package>
                            org.test.mediator.*,
                        </Export-Package>
                        <Import-Package>
                            *; resolution:=optional
                        </Import-Package>
                        <Fragment-Host>synapse-core</Fragment-Host>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>
        <dependency>
            <groupId>org.apache.synapse</groupId>
            <artifactId>synapse-core</artifactId>
            <version>2.1.1-wso2v5</version>
        </dependency>
    </dependencies>
</project>

In this case, it is necessary to make the mediator an OSGI fragment of the synapse-core bundler. To achieve this, use the <Fragment-Host>synapse-core</Fragment-Host>.

Create <PROJECT_HOME>/main/resources/META-INF.services/org.apache.synapse.config.xml.MediatorFactory and <PROJECT_HOME>/main/resources/META-INF.services/org.apache.synapse.config.xml.MediatorSerializer files with the following content as shown below, to add service provider definitions to your Maven project.

create the 2 text files

Content of the org.apache.synapse.config.xml.MediatorFactory file

org.wso2.carbon.mediator.cache.config.xml.CacheMediatorFactory

Content of the org.apache.synapse.config.xml.MediatorSerializer file

org.wso2.carbon.mediator.cache.config.xml.CacheMediatorSerializer

After you create the mediator, drop the JAR file into the {ESB_HOME}\repository\components\dropins folder.

Because a mediator is an extension of the server and not an application, do not deploy a mediator as a Carbon application (CAR file).