Apache Synapse is a mediation framework for Web Services. Synapse allows messages flowing through, into, or out of an organization to be mediated, including aspects such as:
Logging, service lookup, performance mediation
Versioning, failover, monitoring
Fault management, tracing
Although there is a clearly defined division between Synapse and Axis2, the Synapse system relies on Axis2 to run. Firstly, it uses the AXIOM object model, and secondly it uses Axis2 as a listener and sender for Web service requests. There are two ways to set up the Synapse server.
synapse.war : Deploy the WAR file into your favorite servlet container. Once it's expanded, you will see in WEB-INF the axis2.xml which has been configured to execute Synapse properly and synapse.xml, which will hold the rules pertaining to messages passing through Synapse.
A lightweight server which runs with its own HTTP server : This uses Axis2's SimpleHTTPServer which is a simple lightweight HTTP server option that does not require a Servlet Engine. First unzip the Synapse-M1.zip. In the bin directory you will find scripts called:
synapse [.sh or .bat]
You should also see a directory called synapse-repository. There you will find the axis2.xml and synapse.xml config files. The axis2.xml need not be modified, but you can do so if you want to.
The command line for synapse-lightweight takes the repository directory and listening port. Change directory to bin/
sh synapse.sh ../synapse-repository -p [Linux]
synapse ../synapse-repository -p [Win]
which will start the SimpleHTTPServer at port 8080. If it's needed to be started at any other port use -p[port_number]. Ex:
./synapse.sh ../synapse-repository -p5043
Note that you can also build them using Maven: Build the WAR file by using the command,
maven dist-bin
This creates both the WAR and binary distribution JARs.
Synapse can intermediate in a number of different modes:
Synapse has an overall model under which there are two ways to extend the framework.
Using the SPI: Developers can build Synapse Extensions, which extend both the functionality and the XML configuration syntax of Synapse.
Using the API: Developers can build Mediators, which extend the functionality of Synapse but use the existing XML syntax.
There are also built-in mediators that do common tasks like logging, redirection etc. Typically users of Synapse extend the function using mediators, while the Synapse development team 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.
By default Synapse will execute all defined mediators against a given message, but this can be affected by using simple rules. Synapse has two predefined rules: <xpath> and <regex>. xpath evaluates a XPath expression against the message, while regex matches a regular expression against one of the message headers (such as the wsa:To address).
Synapse also has two simple rules <in> and <out> which process only request or response messages (as seen by the target service).
As a message goes through the Synapse engine, it can pass through multiple stages. Each stage is a way of grouping and organizing mediators and rules. A stage simply gives the group a name.
<stage name="stage1-all">
<!--This enables the addressing module which looks at wsa headers -->
<engage-addressing-in/>
<!--Logs the message -->
<log/>
</stage>
<stage name="stage2-service-specific" >
<regex message-address="to" pattern="http://xmethods.*">
<header type="to" value="http://64.124.140.30:9090/soap"/>
</regex>
</stage>
<stage name="stage3-send-all">
<send/>
</stage>
This example demonstrates stage, regex and some built in mediators: log, addressing and header. It does not demonstrate the xpath, in or out rules.
Every stage will be executed for each message. The first stage does initial processing including parsing the addressing headers and logging the message.
The next stage is using a regex rule to redirect every message addresses to xmethods.com and xmethods.net to the real SOAP address of the XMethods quote service.
Finally the last stage sends the message on. For responses, the messages come back through the same stages. This time the message will not be redirected because the "to" address on the response will not match xmethods.
Synapse allows users to extend the built in mediators and add their own. The mediators use the Synapse API. The API has three interfaces.
The primary interface is the SynapseMessage interface:
public interface SynapseMessage {
public SOAPEnvelope getEnvelope();
public void setEnvelope(SOAPEnvelope envelope) throws AxisFault;
public EndpointReference getTo();
public void setTo(EndpointReference reference);
// lots more header get/setters not shown
// and a few other things ... see the real code
public Object getProperty(String key);
public void setProperty(String key, Object value);
public void setResponse(boolean b);
public boolean isResponse();
}
The SynapseMessage interface is based on the Axis2 MessageContext interface. It uses the Axis2 EndpointReference and SOAPEnvelope classes/interfaces.
The purpose of this interface is to capture a message as it flows through the system. As you will see the messages are represented using the SOAP infoset. Binary messages can be embedded in the Envelope using the MTOM support built into Axis2's AXIOM object model.
The second key interface for mediator writers is the Mediator interface:
package org.apache.synapse.api;
import org.apache.synapse.SynapseMessage;
public interface Mediator {
public boolean mediate(SynapseMessage sm);
}
The mediator can modify the SynapseMessage in any way it likes - adjusting the routing headers or changing the message. If it returns false, that signals to the Synapse processing model to stop processing further. For example, if the mediator is a security agent it may decide that this message is dangerous and should not be processed further. This is generally the exception as mediators are usually designed to co-operate to process the message onwards.
The final aspect of the API is the EnvironmentAware interface. If the mediator implements this, then it will have the SynapseEnvironment injected into it:
package org.apache.synapse.api;
import org.apache.synapse.SynapseEnvironment;
public interface EnvironmentAware {
public void setSynapseEnvironment(SynapseEnvironment se);
public void setClassLoader(ClassLoader cl);
}
The SynapseEnvironment allows the mediator access to the underlying engine:
package org.apache.synapse;
public interface SynapseEnvironment {
public void injectMessage(SynapseMessage smc);
public ClassLoader getClassLoader();
public void send(SynapseMessage smc);
public Processor lookupProcessor(String name);
public void addProcessor(Processor p);
public Processor getMasterProcessor();
public void setMasterProcessor(Processor p);
}
Mediators can be configured in different ways which include
<classmediator name="optional-name"
class="org.apache.sample.MyLogger"/>
This will load a class named org.apache.sample.MyLogger and use it to mediate messages.
<servicemediator name="optional-name" service="service-name"/>
<synapse-spring:springmediator name="optional-name"
bean="name-of-bean-which-implements-mediator">
<beans>
<bean .... spring bean assembly configuration goes here >
</beans>
</synapse-spring:springmediator>
Redirection is only designed to apply to "in" messages by using the <in> rule. If we use <out> then you have to explictley use the <in> rule.
<stage name="stage1-all">
...
</stage>
<in name="stage2-service-specific" >
<regex message-address="to" pattern="http://xmethods.*">
...
</in>
<stage name="stage3-send-all">
...
</stage>
There is a corresponding <out> rule.
In order to make the configuration more re-usable, every rule, stage or mediator can be named:
<stage name="thisname">
The name can then be used to "refer" to the mediator.
So
<ref ref="thisname"/>
will cause the same processing to happen as if the stage had been included at that point.
For example:
<in>
<stage name="both">
. . .
</stage>
<stage name="inonly"> ...</stage>
</in>
<out>
<ref ref="both"/>
</out>
Please note this is one area where we expect to do considerable work
This is a stage where none of the children get executed. Its purpose is to allow you to place rules and mediations and have them not executed but instead refer to them from one or more other places.
So the following may be deemed equivalent to the previous example
<in>
<ref ref="both"/>
<stage name="inonly"> ...</stage>
</in>
<out>
<ref ref="both"/>
<out>
<never>
<stage name="both"> ...</stage>
</never>
We can further improve our example by adding some "content-based" routing. Using an <xpath> rule we can make tests within the XML. For example, we could decide not to allow stock ticker queries against certain companies whose share prices we were jealous of - MSFT say :-).
To do this we can add a rule:
<xpath expr="//*[Symbol='MSFT']">
<fault/>
</xpath>
This rule identifies any messages with a tag Symbol whose content is MSFT. The <fault> mediator returns a fault to the client.
We can place this rule under the regex rule, so it only applies to requests aimed at xmethods.*:
<regex message-address="to" pattern="http://xmethods.*">
<header type="to" value="http://64.124.140.30:9090/soap"/>
<xpath expr="//*[Symbol='MSFT']">
<fault/>
</xpath>
</regex>
Note that the rules, like the stages, can have more than one child. While it isn't fixed in Synapse, the built-in rules and mediators all use the same "plan" to execute their children, which involves executing in the lexical order that they occur in the synapse.xml.
Every element in the Synapse configuration file maps to a instance of a Processor. There are two types of elements - nodes that "contain" sub-elements (ex: <regex/>, <stage/> and <xpath/>) and leaves which only contain configuration for that element or have no xml children (ex: <engage-addressing-in/>).
<stage/>
<in/>
<out/>
<never/>
<ref/>
<regex/>
<xpath/>
<engage-addressing-in/>
<log/>
<fault/>
<send/>
<header/>
<xslt/>
<servicemediator/>
<classmediator/>
If you are running the samples using 0.94 distributions, please follow this before running the samples.
The system ships with a couple of samples. These include sample clients and appropriate synapse.xml intermediary configurations.
The first sample demonstrates the logging facility. Here is a simple synapse.xml:
<synapse xmlns="http://ws.apache.org/ns/synapse">
<engage-addressing-in/>
<log/>
<send/>
</synapse>
The logging uses the Log4J/Commons Logging support in Apache. You can configure it using log4j.properties.
The sample client is a standard Axis2 client built to run against the XMethods Quote Service. However, it has been modified to use a different transport address from the Web Services Addressing TO header. In other words, the SOAP envelope is addressed to the XMethods service, but the actual HTTP request goes to Synapse. The sample client has three (optional) parameters:
StockQuoteClient SYMBOL webservicexURL TransportURL
e.g.
StockQuoteClient IBM http://www.webservicex.net/stockquote.asmx
http://localhost:8080
The sample synapse.xml can be used to demonstrate a few simple behaviours. 1) Firstly try this:
StockQuoteClient IBM http://www.webservicex.net/stockquote.asmx
http://www.webservicex.net/stockquote.asmx
This will bypass Synapse and simply call XMethods.
2) Now start Synapse on port 8080 and try
StockQuoteClient
on its own. You should see the messages being logged as they pass through Synapse.
3) This time try
StockQuoteClient IBM urn:xmethods-delayed-quotes
This should hit a regex rule which replaces the "virtual URI" that is in the wsa:To header with the real URL.
4) Now try
StockQuoteClient MSFT
which should hit a "content-based" xpath rule.
ProxyStockQuoteClient illutstrates how Synapse working as Proxy