Writing a WSO2 ESB Mediator

Mediators provide an easy way of extending the ESB functionalities. WSO2 ESB is based on 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 see the detailed information of 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 wrote the mediator you need to build it with WSO2 ESB. You have to make your mediator an OSGI bundle in order to make it work with ESB.

Easier Way

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

Harder Way

If you want control the way of your mediator creation as an OSGI bundle, you have to write the POM files. This way you can export the packages you want, you can import packages you want etc.

Tip

It is available if your mediator uses some versioned JAR files.

Note

Both POM files are created for the ESB 2.1 release. If you want to use them for another release, make sure you change the versions accordingly.

A POM file to create 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>1.3.0.wso2v1</version>
        </dependency>
    </dependencies>
</project>

Tip

The maven bundle plug-in was used for creating the OSGI bundle here. Make sure you export the correct package which contains the mediator code. Unless you do this, your mediator will not work.

A POM file to create the mediator with its own XML configuration using 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>1.3.0.wso2v1</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 created the mediator, drop the JAR file in to the {ESB HOME}\repository\components\dropins folder.