User Guide

*** this document is being updated and the current contents are deprecated ***

Apache Synapse is a mediation framework for Web Services. Synapse allows messages flowing through, into, or out of an organization to be mediated. Refer to the project documentation for more details.

Getting started

Synapse Installation

Synapse is available in two distributions. A standalone lightweight distribution which runs on its own HTTP server, and as a WAR distribution. The WAR distribution is not currently supported for the Milestone M2 release. Hence you will need to start the lightweight version of Synapse as described below.

Synapse will always start in the SYNAPSE_HOME directory, which is where Synapse is installed. This directory has the following structure.

/synapse
	/bin			-	Contains the binaries. i.e. synapse.sh and synapse.bat
	/lib
		/endorsed		-	If validation mediator is used, Xerces parser JAR files should be placed here
	/samples			-	This directory includes several samples with varying complexity.
	/synapse_repository			-	This is the underlying Axis2 repository. Refer to Axis2 documentation for more information and structure of this.
		/conf		-	Contains the default synapse.xml configuration file and the axis2.xml configuration file for Axis
			/sample	-	Contains sample synapse XML configurations to be used with the samples
		/modules
		/services
	/xdocs			-	Contains bundled documentation

Starting Synapse through the synapse [.sh or .bat] script

The command line for synapse-lightweight takes the repository directory and listening port as optional parameters. However as these arguments are optional, if they are not specified the port will default to 8080 for http and the repository to the 'synapse_repository' directory. Execution of the script starts up synapse as follows.

C:\Java\SynapseDist\synapse>bin\synapse.bat
......
[SimpleHTTPServer] Starting
[SimpleHTTPServer] Using the Axis2 Repository C:\Java\SynapseDist\synapse\bin\..\synapse_repository
[SimpleHTTPServer] Listening on port 8080
[main] INFO SynapseAxis2Interceptor - Initializing Synapse...
[main] INFO SynapseAxis2Interceptor - System property 'synapse.xml' specifies synapse configuration as C:\Java\SynapseDist\synapse\bin\..\synapse_repository\conf\synapse.xml
[main] INFO XMLConfigurationBuilder - Generating the Synapse configuration model by parsing the XML configuration
[main] INFO SynapseConfigurationBuilder - Loaded Synapse configuration from : C:\Java\SynapseDist\synapse\bin\..\synapse_repository\conf\synapse.xml
[main] INFO SynapseAxis2Interceptor - Synapse initialized...
[SimpleHTTPServer] Started

If required the port and the Axis2 repository locations could be specified as follows

 synapse.sh -p5043 synapse_repository

A convenience method to start Synapse with sample configurations (found in synapse_repository\conf\sample) is available with the M2 release. This could be used as follows:

 synapse.sh -sample <number>

<number> could be 0, 1 or 2, and will pick up the synapse_repository\conf\sample\synapse_sample_<number>.xml file from the samples.

The default log4j.properties file found in the SYNAPSE_HOME directory sets the default Synapse log level as DEBUG. You may change this to INFO or WARN as required.

Building the Synapse source

If you have downloaded the Synapse source, and set up Maven and its dependencies, you could build the binary distribution as follows:

 maven dist-bin

This creates the Synapse-Incubating-M2-SNAPSHOT-bin.zip distribution file within target\dist

 maven dist-extensions

The dist-extensions target builds the Synapse extensions Extensions-Synapse-M2-SNAPSHOT-bin.zip into target\dist

Installing Extensions

Synapse extensions allows the core of Synapse to be kept to the minimum level, yet still allow extension. Hence the Spring and Validation support which depends on the Spring and Xerces JARs are kept outside of the core distribution as extensions. The extensions are written using the Synapse SPI and the API which allows the Synapse functionality and configuration to be enhanced. (Refer to the Extending Synapse document for more information) Hence the Spring extension source provides a good example for someone interested in using the SPI /API to extend the functionality and configuration of Synapse.

Spring extension

The Spring extension requires spring.jar to be placed on the synapse SYNAPSE_HOME/lib folder. In addition, you will need to place the synapse_extensions.jar file which could be found within the Extensions-Synapse-M2-SNAPSHOT-bin.zip distribution file to be placed into the same folder.

Validate mediator

The Validate mediator depends on the Xerces 2.8.0 parser. To properly setup the Xerces parser, you will need to place the xml-apis.jar and xercesImpl.jar JAR files of Xerces into the SYNAPSE_HOME/lib/endorsed directory. If you have already installed Xerces into your JAVA_HOME/lib/endorsed directory, you may omit the above step.

Deployment models

Synapse can intermediate in a number of different modes as listed below. Refer to the README.txt in the samples directory for examples utilizing these different models.

Transparent mode
- Synapse acts as an HTTP Proxy.
- Clients are configured with the Synapse endpoint URL as the HTTP Proxy URL.
- Synapse can work with both WS-A and non-WS-A SOAP messages.
Gateway mode
- The client explicitly sends a message to Synapse (with or without WS-A headers)
- The synapse configuration must include enough routing information to correctly set the WS-A To and then Synapse forwards the message
Smart client mode
- The client sends the message to Synapse but sets the WS-A headers to the ultimate destination

Processing model

Synapse has an overall model under which there are two ways to extend the framework. This essentially maps into the <definitions> or global Synapse configuration extension through the SPI; and the <rules> or mediator extension through the API.

Using the SPI: Developers can build Synapse configuration extensions, which extend the XML configuration of Synapse
Using the API: Developers can build Mediators, which extend the functionality of Synapse

There are also built-in mediators that do common tasks such as logging, editing etc. Typically users of Synapse extend the function using mediators, while the Synapse development teams can extend the core by building extensions.

A synapse deployment attaches to one or more transport listeners, and mediates messages from those listeners. One of the key decisions is how to "attach" mediators to messages.

Message Mediation

The Synapse configuration language describes the XML syntax used to configure Synapse, and describes the built-in mediators. Please refer to http://wiki.apache.org/incubator/Synapse/SynapseConfigurationLanguage for more information.

User Mediators

Synapse allows users to extend the built in mediators by introducing their own. The mediators use the Synapse API. The main API interfaces are described below. A user mediator implementation could be as simple as writing your own Java class implementing the org.apache.synapse.api.Mediator interface, which essentially defines one single method

public boolean mediate(MessageContext synCtx);

You may additionally define this class as a Spring bean using the Synapse Spring extension. The advanced user may want to write his own custom mediator as well as extend the XML configuration model with a custom configuration extension.

Writing a custom Class mediator implementation

A custom class mediator must extend the Mediator interface, and implement the public boolean mediate(MessageContext synCtx) method and a no argument constructor. The MessageContext allows the mediator to use message content or to modify the message as required, and hand it over to the next mediator as defined in the configuration. Class mediators could be configured as follows:

<class name="class-name">
    <property name="string" (value="literal" | expression="xpath")/>*
</class>

The class mediator is built into the core of Synapse, and creates an instance of your specified class - which must be placed into the SYNAPSE_HOME/lib folder as a JAR file. If any properties are defined in the XML configuration the setter methods are invoked. However only String properties are allowed for Class mediators at this time. Any dependent libraries use by your class mediator implementation should be placed into the same lib folder as well.

Writing a custom Spring mediator implementation

A Spring mediator implementation is a class mediator, which is managed by a given Spring configuration. The Spring configuration may be defined globally to the Synapse Configuration and reused by multiple Spring managed mediator beans or defined inline per bean. Refer to the configuration syntax for more information. As the Spring mediator implementation is distributed as an "extension" to the core Synapse distribution, you will need to manually place the extension_mediators.jar into the SYNAPSE_HOME/lib folder as well as place the spring.jar and any other dependencies into the same directory.

A reusable Spring configuration may be defined within the XML configuration file as follows within the <definitions> element:

<spring:config name="string" src="file"/>

And a Spring mediator implementation may be defined within the <rules> element as follows:

<spring bean="exampleBean1" (config="spring1" | src="spring.xml)"/>

The Spring configuration referenced by the "src" attribute will be initialized and the bean with the name given by the "bean" attribute will be looked up for mediation of the message. This bean must implement the Mediator interface. If a reusable Spring configuration was defined, the bean definition could refer to this configuration through the name given in the "config" attribute.