incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Incubator Wiki] Update of "Synapse/SynapseUserGuide" by Asankha Perera
Date Thu, 07 Dec 2006 12:12:43 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Incubator Wiki" for change notification.

The following page has been changed by Asankha Perera:

The comment on the change is:
no longer relevant

+ deleted
- = User Guide =
- 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. and synapse.bat 
-   /lib
-     /endorsed - If validation mediator is used, Xerces parser JAR files should be placed
-   /samples - This directory includes several samples with varying complexity. 
-   /synapse_repository - This is the underlying Axis2 repository. Refer to Axis2 documentation
-     /conf - Contains the default synapse.xml and axis2.xml
-       /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
- {{{
- -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:
- {{{
- -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.
- ==== Log4j configuration ====
- The default 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 distribution file within target\dist
- {{{
-  maven dist-extensions
- }}}
- The dist-extensions target builds the Synapse extensions
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 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 ==
- The Synapse configuration language describes the XML syntax used to configure Synapse, and
describes the built-in mediators. Please refer to
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
- {{{
-  <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"

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message