Stepping into Apache Synapse – Part I
Introduction
Apache Synapse is a mediation framework for Web services, based on the Apache Axis2 project, a set of XML, security, and Web services related projects and standards. Synapse provides a lightweight service bus and the basic infrastructure for the implementation of a Service Oriented Architecture (commonly known as SOA). In this article, you will learn the basic architecture of Synapse and how to configure it. In later parts you will be able to see some sample configurations with real world scenarios.
Applies To
| Apache Synapse | Version 1.0 |
Service Bus and Mediation
Let us first focus on the meaning of the terms 'Service Bus' and 'Mediation' in the context of messaging, before we dive-in deeper into Synapse. When it comes to enterprise application communication, Service Bus is the common communication channel that is used by all the parties in messaging. Mediation is the process of facilitated communication between parties by providing intermediary conflict resolutions.
Synapse supports most of the tasks of a service bus in a service oriented infrastructure. Synapse is inherently extensible even though it is designed to support a large set of useful functions out-of-the-box. The main functions of Synapse can be divided into three major areas:
- Connect - Connecting systems
- Manage - Managing interactions
- Transform - Transforming messages
Connect
Synapse is designed to support connecting systems with different transports with different protocols and Quality of Service (QoS). The protocols/transports that Synapse currently supports include SOAP/HTTP,SOAP/HTTPS, SOAP/JMS, SOAP/SMTP, XML/HTTP, XML/JMS and many more. Synapse offers termination and initiation of QoS tasks like Reliable Messaging and WS Security. Synapse can route messages based on XPath expressions or Regular expressions applied over the message header or content to an endpoint reference. Virtualization is achieved by routing the messages from virtual/logical URIs to real EPRs.
Manage
Synapse supports Failover and Load-balancing to multiple endpoints. In the failover case, there are several sets of endpoints grouped as a failover group. When a particular endpoint fails to deliver the message, Synapse will try to deliver the message to other endpoints in the group. During load-balancing, Synapse will balance the load among the load-balancing endpoint group depending on the algorithm provided for load-balancing.
Synapse also lets you trace the messages flowing in the enterprise by enabling tracing in the mediation. Authorization and authentication tasks for an organization can be delegated to Synapse through mediation, by using WS Security. Synapse lets you collect and monitor the statistics for components such as proxy services in Synapse. The validation of messages using schemas is also very simple with Synapse.
Transform
Synapse can be used for message transformations through mediation with various languages, including most of the scripting languages, with the Bean Scripting Framework (BSF) and most importantly with XSLT. Apart from that, Synapse offers protocol switching, example - SOAP to JMS or XML/HTTP to SOAP.
Mediation inside Synapse is designed with care, and there are two possible types of mediations that can happen inside Synapse. They are:
- Message Mediation - Managing and transforming the messages flowing between the client and a service in an enterprise.
- Service Mediation - Mediating messages coming into a specific service by specifying the target URI as a Synapse mediation service.
In message mediation, the client does not know about the mediation of the message in the middle of transmission. When it comes to service mediation, the client directly speaks to Synapse and specifies the address of the service to which the message should go for mediation. Inside these services, it is not required to check the transport headers and take the routing decision because the messages are already filtered. Whereas in message mediation, most of the time Synapse will have to check the transport headers to take the routing decision. These services are called Proxy Services in Synapse.
All these features make Synapse an attractive open source mediation framework for you to try under Apache Software License version 2.0.
Architecture of Synapse
The high level architecture of Synapse is fairly simple. The Synapse engine applies the rules specified to it through the Synapse configuration language on the messages it receives via configured transports. The following diagram depicts an abstract view of Synapse.
There are three message receivers (MRs) in Synapse,
- Synapse Message Receiver - Receives messages from the underlying Axis2 transports for message mediation.
- Proxy Service Message Receiver- Receives messages for service mediation.
- Synapse Callback Receiver - Receives responses for outgoing messages through Synapse.
The Callback Receiver ties the responses with the requests made so that the out flow mediation can execute within the proper context. Proxy services will be introduced in the next section of this article.
When a message is received by the message receivers, Synapse will inject these messages into the Synapse environment. The mediation takes place here through a Synapse Message Context (SMC) created for each message through a set of mediators. This context holds the message, message context properties, and parameters for the environment. Similar to Axis2, Synapse is also stateless, and if the mediators want to share any data between them, they will have to use the Synapse Message Context properties.
While in the process of mediation, if a message should be sent to a particular endpoint, then the Send mediator sets the relevant properties on the SMC and delegates the sending of the message to an Endpoint. This is a logical representation of an actual endpoint, or else a collection of endpoints wrapped within some logic. (For example, Load Balanced endpoints) The endpoint will then apply additional modifications to the SMC and then hand over the SMC to the Sender (which is an Axis2Sender) for sending the message.
If this message is not a response, the Axis2Sender will send the message to the specified endpoint given by the endpoint, or if not provided, to the endpoint resolved from the implicit parameters in the MC. If it is a response, the Axis2Sender will use the implicit parameters to send the message back, by looking at its message properties that were set when the message was received. (A detailed architectural view of Synapse will be presented in a subsequent article.)
Before we dig into the command/control language of Synapse, that is the Synapse Configuration Language, Let's look at a usage sample for the better understanding of Synapse.
Getting Your Hands Dirty with Synapse
This section describes how you can get Synapse and run it. First, download the latest release of Synapse from its official web site which is http://ws.apache.org/synapse and uncompress the distribution. You will be able to see the following structure in the extracted folder;
The bin directory in the uncompressed root folder contains the synapse.sh and synapse.bat scripts which are used to start Synapse in the Unix and Windows based environments respectively. Synapse has a set of samples that consists of a built-in Axis2 Server and a set of Axis2 clients and corresponding services, bundled with a set of Synapse configurations that lets you try different features of Synapse out of the box.
Extract the binary distribution archive. In the samples/axis2server/src/SimpleStockQuoteService directory, run 'ant' in a console (you need Apache Ant to accomplish this task) which will build and deploy the axis2 service archive for you to test a trivial example of Synapse. Now from the axis2Server folder, run the axis2Server.sh or axis2Server.bat script. After that, start Synapse with the first sample configuration using the synapse.sh or synapse.bat with the arguments “-sample 0”. The complete command to be executed is as follows.
[SYNAPSE]/bin$ ./synapse.sh -sample 0
[SYNAPSE]\bin> synapse.bat -sample 0
The following log depicts the console output after synapse is started successfully.
Starting Synapse/Java ...
Using SYNAPSE_HOME: /home/ruwan/dev/syn/trunk/java/synapse-1.0-RC1-SNAPSHOT
Using JAVA_HOME: /opt/software/java/jdk1.5_06
Using SYNAPSE_XML: -Dsynapse.xml=/home/ruwan/dev/syn/trunk/java/synapse-1.0-RC1-SNAPSHOT/repository/conf/sample/synapse_sample_0.xml
[SynapseServer] Using the Axis2 Repository /home/ruwan/dev/syn/trunk/java/synapse-1.0-RC1-SNAPSHOT/repository
[main] INFO SynapseModule - Initializing the Synapse configuration ...
[main] INFO SynapseModule - System property 'synapse.xml' specifies synapse configuration as /home/ruwan/dev/syn/trunk/java/synapse-1.0-RC1-SNAPSHOT/repository/conf/sample/synapse_sample_0.xml
[main] INFO XMLConfigurationBuilder - Generating the Synapse configuration model by parsing the XML configuration
[main] DEBUG MediatorFactoryFinder - Added MediatorFactory class org.apache.synapse.mediators.spring.SpringMediatorFactory to handle {http://ws.apache.org/ns/synapse/spring}spring
[main] DEBUG MediatorFactoryFinder - Added MediatorFactory class org.apache.synapse.mediators.bsf.ScriptMediatorFactory to handle {http://ws.apache.org/ns/synapse}script
[main] DEBUG MediatorFactoryFinder - Added MediatorFactory class org.apache.synapse.mediators.attachment.AttachmentMediatorFactory to handle {http://ws.apache.org/ns/synapse}attachments
[main] DEBUG MediatorFactoryFinder - Added MediatorFactory class org.apache.synapse.mediators.throttle.ThrottleMediatorFactory to handle {http://ws.apache.org/ns/synapse/throttle}throttle
[main] DEBUG MediatorFactoryFinder - getMediator({http://ws.apache.org/ns/synapse}log)
[main] DEBUG MediatorFactoryFinder - getMediator({http://ws.apache.org/ns/synapse}send)
[main] DEBUG MediatorFactoryFinder - getMediator({http://ws.apache.org/ns/synapse}log)
[main] INFO SynapseConfigurationBuilder - Loaded Synapse configuration from : /home/ruwan/dev/syn/trunk/java/synapse-1.0-RC1-SNAPSHOT/repository/conf/sample/synapse_sample_0.xml
[main] INFO SynapseModule - Deploying the Synapse service..
[main] INFO SynapseModule - Deploying Proxy services...
[main] INFO SynapseModule - Synapse initialized successfully...!
[main] INFO HttpCoreNIOSender - HTTPS Sender starting
[main] INFO HttpCoreNIOSender - HTTP Sender starting
[main] INFO HttpCoreNIOListener - HTTPS Listener starting on port : 8443
[SynapseServer] Starting transport https on port 8443
[main] INFO HttpCoreNIOListener - HTTP Listener starting on port : 8080
[SynapseServer] Starting transport http on port 8080
[SynapseServer] Ready
The configuration of Synapse which is used to start Synapse is as follows. This will be explained later in the Synapse Configuration Language section;
You can try out Synapse by using the sample clients available in the axis2Client folder as follows. You can execute the stockquote client that will send a message through Synapse to the Axis2 service deployed on the sample server.
$ ant stockquote
This will compile the StockQuoteClient in the src/samples/userguide folder and run it to invoke the service. This client will send a message specifying the WSA-To address as SimpleStockQuoteService deployed on the axis2 server running on port 9000, and specify the transport URL as Synapse running on port 8080. Thus the message reaches Synapse through the transport and allows Synapse to mediate the message flow.
[I/O reactor worker thread 5] INFO PipeImpl - Using native OS Pipes for event-driven to stream IO bridging
[HttpServerWorker-1] DEBUG SynapseMessageReceiver - Synapse received a new message for message mediation...
[HttpServerWorker-1] DEBUG SynapseMessageReceiver - Received To: http://localhost:9000/axis2/services/SimpleStockQuoteService
[HttpServerWorker-1] DEBUG SynapseMessageReceiver - SOAPAction: urn:getQuote
[HttpServerWorker-1] DEBUG SynapseMessageReceiver - Body :
<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Header> <wsa:To>http://localhost:9000/axis2/services/SimpleStockQuoteService</wsa:To> <wsa:MessageID>urn:uuid:D57514D7EA959684321175764218397</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action> </soapenv:Header><soapenv:Body><m0:getQuote xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol></m0:request> </m0:getQuote></soapenv:Body></soapenv:Envelope>
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <main> :: mediate()
[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
[HttpServerWorker-1] INFO LogMediator - To : http://localhost:9000/axis2/services/SimpleStockQuoteService, MessageID : urn:uuid:D57514D7EA959684321175764218397, Action : urn:getQuote, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Header> <wsa:To>http://localhost:9000/axis2/services/SimpleStockQuoteService</wsa:To> <wsa:MessageID>urn:uuid:D57514D7EA959684321175764218397</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action> </soapenv:Header><soapenv:Body><m0:getQuote xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol></m0:request> </m0:getQuote></soapenv:Body></soapenv:Envelope>
[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
[HttpServerWorker-1] DEBUG SendMediator - Sending message using implicit message properties..
[HttpServerWorker-1] DEBUG SendMediator - Sending To: http://localhost:9000/axis2/services/SimpleStockQuoteService
[HttpServerWorker-1] DEBUG SendMediator - SOAPAction: urn:getQuote
[HttpServerWorker-1] DEBUG SendMediator - Body :
<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Header><wsa:To> http://localhost:9000/axis2/services/SimpleStockQuoteService</wsa:To><wsa:MessageID> urn:uuid:D57514D7EA959684321175764218397</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action></soapenv:Header> <soapenv:Body><m0:getQuote xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol></m0:request> </m0:getQuote></soapenv:Body></soapenv:Envelope>
In this case, a send mediator followed by the log mediator. Executing these two mediators, first it logs the full message because the configuration says the log level is full and then sends the message onwards to the actual service running on port 9000 using the implicit To header in the message. The response from the server comes to Synapse and it will decide the response message's destination from its implicit parameters. It then sends the response to the client after logging the message by executing the main rule again. For help on running samples in Synapse please refer to the Synapse Samples Guide .
Now we will look into the configuration language, from which you can control synapse.
Synapse Configuration Language
Synapse at runtime is configured via an XML configuration file. It is written using the Synapse configuration language which is defined in the Synapse Configuration Language. Let us examine the sample configuration we used above to gain a better understanding of the syntax.
This is a basic configuration of Synapse. If we take the elements in this configuration one by one, first the root element named definitions holds all the sub definitions of Synapse. All the configuration elements belong to the Synapse namespace "http://ws.apache.org/ns/synapse". However all the attributes remain un-qualified by default.
Within these definitions, we can have several declarations in the following categories;
- Sequence declarations
- Endpoint declarations
- Local Registry Entry declarations
- The Registry declaration
- Proxy Service declarations
Sequences
Sequence declarations can contain any number of sequences with a name. There are two mandatory sequences that should be present for Synapse to start properly. They are: main and fault. The Main sequence is the sequence where the mediation starts in Synapse when a message has arrived, where as the Fault sequence will be executed if there is an internal error in Synapse while doing the mediation.
Even though these two sequences are mandatory, Synapse does not rely on the administrator to provide them in the configuration, instead it creates two default sequences in the absence of one of these sequences. The default sequence for main will be a Send mediator, where as the default sequence for fault will be a Log mediator. In the above sample configuration, even though there was no fault sequence, Synapse will create its own default fault sequence with the Log mediator.
This is another sample sequence named "sample_sequence";
If you have specified a set of mediators inside a definitions tag, then
Synapse will consider that collection of mediators in the order of the
declaration as the main mediator. It is obvious that you cannot have the
sequence and a set of mediators with the name “main” in the root level,
which will be an erroneous configuration. Unlike presenting a main sequence,
in this case Synapse will not start and will throw a Runtime Exception.
Endpoints
An endpoint requires a name to be present when declaring at the definitions level. It can be one of the following four categories:
- Address Endpoint
- WSDL Endpoint
- Load-balancing Endpoint
- Failover Endpoint
Address endpoint is the one defined with the address binding of the actual endpoint, where as WSDL endpoint will be defined by giving the WSDL of the actual endpoint, so that Synapse is able to extract the relevant information from the WSDL. For example,
The remaining two endpoints do not represent actual endpoints, but they are a representation of a particular logic like load balancing or failover as shown below;
Local Entries
If you have a resource that will be used several times (for example an XSLT), you can define an entry for that resource and reuse the defined entry rather than stating the resource itself each time. In entry declaration as well, it is required to provide a name, so that when it is needed you can just refer to the defined resource by referring to that name.
Registry
Currently Synapse only supports a single registry per configuration, and it should be declared inside the definitions tag. If you have declared a registry, then you have access to the resources that are available in the registry by referring to the registry key of a particular resource.
The main advantage of using a registry is that, these registry entries can be used to change the behaviour of Synapse at runtime. For example, if you have placed your main sequence in a registry and just refer to that registry entry in the configuration giving the key, then you can change that registry entry and expect Synapse to change its behaviour accordingly.
Proxy Services
Proxy service definitions can contain any number of proxy services with a name. There are some more parameters that you can provide when defining a proxy service which includes the following;
- Transports on which the service is exposed
- WSDL under which the proxy is exposed
- Incoming mediation sequence, out going mediation sequence and fault sequence
- Target endpoint
- Policy elements for QoS
- Service parameters
You may have noticed that except for proxy services, it is possible to use all the other declarations inline whenever needed, without a name.
Conclusion
Apache Synapse is a lightweight mediation framework which is very useful in providing the infrastructure for SOA. Synapse is inherently architected in a way to provide most of the functionalities of an ESB, and can be easily configurable through the Synapse Configuration Language. In the next article, you will learn how to carry out basic mediation with Synapse, an introduction to Synapse proxy services, advanced mediation tasks of Synapse and extending Synapse.
References/Resources
1. Synapse Home Page
2. Synapse
Samples Guide
3. Synapse
Configuration Language
