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.

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.

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

• 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.

1. Using the SPI: Developers can build Synapse configuration extensions, which extend the XML configuration of Synapse
   

2. 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

User Mediators

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

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

Writing a custom Spring mediator implementation

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

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