Developer Guide

Welcome to Apache Synapse Developer Guide. This document is a starting point for anyone who's willing to write code for Synapse and make contributions. We welcome several different types of contributions such as ideas, new features, bug fixes, documentation and samples. This guide strives to provide information on how you can get the Synapse source code, how to setup the development environment and how to make contributions. Further it provides instructions on how to get in touch with the other developers, how to report issues and how to keep track of development activities.

If you are an experienced Synapse developer or already a committer for Synapse, this document might still contain useful information on setting up your working copy of the source code and committing code changes. So, feel free to read all the way through.

Interacting with the Code Base Using Git

Synapse code base is maintained in a Github repository. Therefore, anyone willing to go through the Synapse source code and make contributions should use a Git client to interact with the Synapse code base.

Some useful information on using the Apache Software Foundation's source code repositories can be found among the ASF developer documentation.

Checking Out the Source

Master branch of the Synapse Github repository is where all the latest development work takes place. This is located at Any developer with a Git client should be able to checkout the latest source from this location, but only Synapse committers are allowed to merge Pull Requests to the source code. Please see the Making Contributions section for more information on how developers can make an contribution.

Interacting with the Build System Using Apache Maven

Synapse build system is based on Apache Maven. Either Maven2 or Maven3 can be used to build Apache Synapse from source. For information about downloading, installing, and configuring Maven, please go through Maven project website.

Building from Source

To build all the modules and the Synapse binary distribution, go to the root of the Synapse source tree and execute the following Maven command.

mvn clean install

This will fetch all the required dependencies, compile the source, run the tests and build the Synapse modules and the binary pack. Please note that building with tests takes time. To build without the tests, use the following Maven command.

mvn clean install -Dmaven.test.skip=true

Developers and committers making changes to the Synapse code base are highly recommended to always build the source 'WITH' the tests. This will ensure that changes do not introduce any obvious regression errors. However, running all the tests does not guarantee that a particular change will not introduce any regressions. Therefore, care must be exercised whenever making changes to the existing code.

Synapse source tree is organized into several modules. If required, you can build only a selected module by going into the appropriate module and executing one of the above build commands.

Setting Up the Development Environment

Apache Synapse development can be based on a number of tools ranging from simple command line tools like Vim and Emacs to full fledged Java IDEs like Eclipse, IntelliJ Idea and Netbeans. If Eclipse or Idea is used to develop code for Synapse, Maven can be used to build the necessary project artifacts.

Simply run the following commands to generate the project artifacts and then use your IDE to open up the Synapse code base as a Java project.

For Idea: mvn idea:idea For Eclipse: mvn eclipse:eclipse

Integration Tests

Starting from Synapse 2.1, a suite of integration tests are included in the Synapse code base. These tests automate various samples included in the Synapse binary distribution and provide a convenient way to sanity check a Synapse distribution and find any regressions. If you build the source tree from the root without skipping the test cases, these integration tests will be executed by Maven as a part of the build process. If you just need to run the integration tests simply go into the modules/integration directory in the source tree and run the usual Maven build command.

Synapse integration test suite uses the Maven Surefire plugin. Therefore, all tests will generate a report which will be available in the modules/integration/target/surefire-reports directory. If you ever encounter a failure while running the integration tests, this is the first place to check.

You can pass additional parameters to the Synapse integration test framework and limit the number of tests executed by Maven. For an example if you simply want to run sample 10 in the integration test framework, run the following command.

mvn clean install -Dtests=10

You can also run a list of known samples as an integration test.

mvn clean install -Dtests=10,11,12

Synapse samples are categorized into several sections. If needed you can run all the samples in a particular section.

mvn clean install -Dsuite=proxy
mvn clean install -Dsuite=endpoint

Following values can be passed in as the value of the 'suite' parameter.

  • message
  • endpoint
  • qos
  • proxy
  • tasks
  • advanced

Debugging Tests

Maven allows you to remote debug tests at build time. To make use of this feature simply run the Maven build command with the -Dmaven.surefire.debug flag.

mvn clean install -Dmaven.surefire.debug

This will open up port 5005 for remote debugging and you can use your IDE to connect to that port and remote debug the test source (or even Synapse source).

Debugging the Synapse Server

If you are running the Synapse binary distribution and wants to debug the server to fix some issue, simply start the server with the -xdebug option.

sh -xdebug

This will open up port 8000 for remote debugging. Now you can connect to the server from your IDE and remote debug it against the source code. If you want to debug a message flow in Synapse, it's recommended to place some break points in the org.apache.synapse.core.axis2.SynapseMessageReceiver and org.apache.synapse.core.axis2.ProxyServiceMessageReceiver classes.

Reporting Issues

Please report all issues in the Synapse JIRA. You can also create JIRA issues for any suggestions, improvements and new features you have in mind. If you wish to further discuss some idea with the rest of the Synapse community, please write to the appropriate mailing lists.

You are also encouraged to comment on other issues in the Synapse JIRA, ask questions and if possible make code/documentation contributions.

Making Contributions

If you have implemented a new feature, fixed some bug in the code or written a new sample, we'll be more than happy to review it and include it in the Synapse code base for everyone's benefit. If you are interested in contributing your work to Synapse, please create an issue in the JIRA system first. Then you can send a Github Pull Request contains the fixes to the Synapse Github master branch.

To create a pull request follow the following approach,

  • Fork the Synapse Github repositoty
  • Take a checkout of your forked Github repository into local file system
  • Switch to a new branch
  • Do required code fixes
  • Commit the fixes and push them together with the new branch to the remote origin Github repository
  • Using the Github web UI, create a Pull Request from the branch that contains fixes of forked Github repository to master branch of Synapse Github repository

Once the Pull Request has been created, put a comment to the relevant JIRA. One of the committers will review your work and provide feedback through the Github Pull Request itself. If all is well, the Pull Request will eventually get merged into the Synapse development branch.

Same process applies even for committers.

It is recommended to submit a Pull Request for review rather than directly committing to the code base.