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.
Synapse code base is maintained in a Subversion repository. Therefore, anyone willing to go through the Synapse source code in the development trunk and make contributions should use a Subversion client to interact with the Synapse code base. To learn more about using Subversion or to download the latest client distributions, please visit the Apache Subversion project website. Developers on Unix/Linux based systems may use the command line based SVN client, while the developers on Windows platform can use an appropriate client application like TortoiseSVN.
Some useful information on using the Apache Software Foundation's source code repositories can be found among the ASF developer documentation.
Synapse development trunk is where all the latest development work takes place. This is located at http://svn.apache.org/repos/asf/synapse/trunk/java/. Any developer with a Subversion client should be able to checkout the latest source from this SVN location but only Synapse committers are allowed to actually commit source code. Synapse committers should access the above SVN location over HTTPS and provide the ASF committer credentials to checkout and commit source code. Please refer the source repository guide for more details on checking out the source code from the above repository.
Once you have checked out the source code, you can update your working copy by running the 'svn update' command. This will checkout the modifications since the last checkout/update and bring your local working copy to the latest revision.
If you want to browse the source code of an older release of Synapse or want to implement a patch for a past release, you may checkout the relevant source tree from one of the available SVN tags.
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.
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.
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.
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.
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.
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.
You can also run a list of known samples as an integration test.
Synapse samples are categorized into several sections. If needed you can run all the samples in a particular section.
Following values can be passed in as the value of the 'suite' parameter.
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.
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).
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.
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.
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.
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 attach your workings to the JIRA issue as a patch.
To create a patch file out of your work simply run the 'svn diff' command.
If you added any new files as a part of your work you should first run the 'svn add' command on them before creating the patch file. Otherwise they won't be included in the generated patch.
Once the patch file has been created, attach it to the relevant JIRA issue and make sure to grant the ASF permission to use your patch in ASF development activities. One of the committers will review your work and provide feedback through the JIRA. If all is well, the patch will eventually go into the Synapse development trunk.