Added: synapse/trunk/java/src/site/xdoc/1_2/Synapse_Extending.xml URL: http://svn.apache.org/viewvc/synapse/trunk/java/src/site/xdoc/1_2/Synapse_Extending.xml?rev=998841&view=auto ============================================================================== --- synapse/trunk/java/src/site/xdoc/1_2/Synapse_Extending.xml (added) +++ synapse/trunk/java/src/site/xdoc/1_2/Synapse_Extending.xml Mon Sep 20 09:23:05 2010 @@ -0,0 +1,484 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> + +<document> + <properties> + <title>Apache Synapse - Extending...</title> + </properties> + <head> + <style type="text/css" xml:space="preserve"> + .command { + border: 1px dashed #3c78b5; + text-align: left; + background-color: #f0f0f0; + padding: 3px; + font-size: 11px; + font-family: Courier; + margin: 10px; + line-height: 13px; + } + .consoleOutput { + border: 1px dashed #3c78b5; + font-size: 11px; + font-family: Courier; + margin: 10px; + line-height: 13px; + background-color: #f0f0f0; + border-bottom: 1px dashed #3c78b5; + padding: 3px; + border-style: solid; + } + .info { + border-style: solid; + border-width: 1px; + border-color: #090; + background-color: #dfd; + text-align:left; + margin-top: 5px; + margin-bottom: 5px; + } + li { + font-family: Verdana, arial, sans-serif; + font-size: 11px; + line-height: 16px; + color: #000000; + font-weight: normal; + } + p { + font-family: Verdana, arial, sans-serif; + font-size: 11px; + line-height: 16px; + color: #000000; + font-weight: normal; + } + pre { + padding: 0px; + margin-top: 5px; + margin-left: 15px; + margin-bottom: 5px; + margin-right: 5px; + text-align: left; + background-color: #f0f0f0; + padding: 3px; + border: 1px dashed #3c78b5; + font-size: 11px; + font-family: Courier; + margin: 10px; + line-height: 13px; + } + h1 { + font-size: 24px; + line-height: normal; + font-weight: bold; + background-color: #f0f0f0; + color: #003366; + border-bottom: 1px solid #3c78b5; + padding: 2px; + margin: 36px 0px 4px 0px; + } + h2 { + font-size: 18px; + line-height: normal; + font-weight: bold; + background-color: #f0f0f0; + border-bottom: 1px solid #3c78b5; + padding: 2px; + margin: 27px 0px 4px 0px; + } + h3 { + font-size: 14px; + line-height: normal; + font-weight: bold; + background-color: #f0f0f0; + padding: 2px; + margin: 21px 0px 4px 0px; + } + h4 { + font-size: 12px; + line-height: normal; + font-weight: bold; + background-color: #f0f0f0; + padding: 2px; + margin: 18px 0px 4px 0px; + }</style> + </head> + <body> + <div style="margin-top:-40px; float:right; _margin-top:0px;"> + <img alt="Synapse logo" + src="images/synapse-logo-web2.png" width="197" + height="82"/> + </div> + <div> + <h1> + Apache Synapse ESB - Extending... + </h1> + </div> + <h2> + Writing custom Mediator implementations + </h2> + <p> + The primary interface of the Synapse API is the MessageContext interface + defined below. This essentially defines the per-message context passed + through the chain of mediators, for each and every message received and + processed by Synapse. Each message instance is wrapped within a + MessageContext instance, and the message context is set with the + references to the SynapseConfiguration and SynapseEnvironments. The + SynapseConfiguration holds the global configuration model that defines + mediation rules, local registry entries and other and configuration, while + the environment gives access to the underlying SOAP implementation used - + Axis2. A typical mediator would need to manipulate the MessageContext by + referring to the SynapseConfiguration. However it is strongly recommended + that the SynapseConfiguration is not updated by mediator instances as it + is shared by all messages, and may be updated by Synapse administration or + configuration modules. Mediator instances may store local message + properties into the MessageContext for later retrieval by successive + mediators.<br/> + </p> + <h4> + <a + href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/MessageContext.java?view=markup";>MessageContext + Interface</a> + </h4> + <p/> +<pre xml:space="preserve">package org.apache.synapse; + +import ... + +public interface MessageContext { + + /** + * Get a reference to the current SynapseConfiguration + * + * @return the current synapse configuration + */ + public SynapseConfiguration getConfiguration(); + + /** + * Set or replace the Synapse Configuration instance to be used. May be used to + * programatically change the configuration at runtime etc. + * + * @param cfg The new synapse configuration instance + */ + public void setConfiguration(SynapseConfiguration cfg); + + /** + * Returns a reference to the host Synapse Environment + * @return the Synapse Environment + */ + public SynapseEnvironment getEnvironment(); + + /** + * Sets the SynapseEnvironment reference to this context + * @param se the reference to the Synapse Environment + */ + public void setEnvironment(SynapseEnvironment se); + + /** + * Get the value of a custom (local) property set on the message instance + * @param key key to look up property + * @return value for the given key + */ + public Object getProperty(String key); + + /** + * Set a custom (local) property with the given name on the message instance + * @param key key to be used + * @param value value to be saved + */ + public void setProperty(String key, Object value); + + /** + * Returns the Set of keys over the properties on this message context + * @return a Set of keys over message properties + */ + public Set getPropertyKeySet(); + + /** + * Get the SOAP envelope of this message + * @return the SOAP envelope of the message + */ + public SOAPEnvelope getEnvelope(); + + /** + * Sets the given envelope as the current SOAPEnvelope for this message + * @param envelope the envelope to be set + * @throws org.apache.axis2.AxisFault on exception + */ + public void setEnvelope(SOAPEnvelope envelope) throws AxisFault; + + /** + * SOAP message related getters and setters + */ + public ....get/set()... + +}</pre> + <p> + The MessageContext interface is based on the Axis2 <a>MessageContext</a> + interface, and uses the Axis2 <a>EndpointReference</a> 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 + message payload is represented using the SOAP infoset. Binary messages can + be embedded in the Envelope using MTOM or SwA attachments using the AXIOM + object model. + </p> + <h4> + <a + href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/Mediator.java?view=markup";>Mediator + interface</a> + </h4> + <p> + The second key interface for mediator writers is the Mediator interface: + </p> +<pre xml:space="preserve">package org.apache.synapse; + +import org.apache.synapse.MessageContext; + +/** + * All Synapse mediators must implement this Mediator interface. As a message passes + * through the synapse system, each mediator's mediate() method is invoked in the + * sequence/order defined in the SynapseConfiguration. + */ +public interface <span style="font-weight: bold;">Mediator </span>{ + + /** + * Invokes the mediator passing the current message for mediation. Each + * mediator performs its mediation action, and returns true if mediation + * should continue, or false if further mediation should be aborted. + * + * @param synCtx the current message for mediation + * @return true if further mediation should continue + */ + public boolean mediate(MessageContext synCtx); + + /** + * This is used for debugging purposes and exposes the type of the current + * mediator for logging and debugging purposes + * @return a String representation of the mediator type + */ + public String getType(); +}</pre> + <p> + A mediator can read and/or modify the <a>SynapseMessage</a> in + any suitable manner - adjusting the routing headers or changing the + message body. If the mediate() method returns false, it signals to the + Synapse processing model to stop further processing of the message. 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. + </p> + <h3> + Leaf and Node Mediators, List mediators and Filter mediators + </h3> + <p> + Mediators may be Node mediators (i.e. these that can contain child + mediators) or Leaf mediators (mediators that does not hold any other child + mediators). A Node mediator must implement the + org.apache.synapse.api.ListMediator interface listed below, or extend from + the org.apache.synapse.mediators.AbstractListMediator. + </p> + <h4> + <a + href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/ListMediator.java?view=markup";>The + ListMediator interface</a> + </h4> +<pre xml:space="preserve">package org.apache.synapse.mediators; + +import java.util.List; + +/** +* The List mediator executes a given sequence/list of child mediators +*/ +public interface ListMediator extends Mediator { + /** + * Appends the specified mediator to the end of this mediator's (children) list + * @param m the mediator to be added + * @return true (as per the general contract of the Collection.add method) + */ + public boolean addChild(Mediator m); + + /** + * Appends all of the mediators in the specified collection to the end of this mediator's (children) + * list, in the order that they are returned by the specified collection's iterator + * @param c the list of mediators to be added + * @return true if this list changed as a result of the call + */ + public boolean addAll(List c); + + /** + * Returns the mediator at the specified position + * @param pos index of mediator to return + * @return the mediator at the specified position in this list + */ + public Mediator getChild(int pos); + + /** + * Removes the first occurrence in this list of the specified mediator + * @param m mediator to be removed from this list, if present + * @return true if this list contained the specified mediator + */ + public boolean removeChild(Mediator m); + + /** + * Removes the mediator at the specified position in this list + * @param pos the index of the mediator to remove + * @return the mediator previously at the specified position + */ + public Mediator removeChild(int pos); + + /** + * Return the list of mediators of this List mediator instance + * @return the child/sub mediator list + */ + public List getList(); +}</pre> + <p> + A ListMediator implementation should call super.mediate(synCtx) to process + its sub mediator sequence. A FilterMediator is a ListMediator which + executes its sequence of sub mediators on successful outcome of a test + condition. The Mediator instance which performs filtering should implement + the FilterMediator interface. + </p> + <h4> + <a + href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/FilterMediator.java?view=markup";>FilterMediator + interface</a> + </h4> +<pre xml:space="preserve">package org.apache.synapse.mediators; + +import org.apache.synapse.MessageContext; + +/** + * The filter mediator is a list mediator, which executes the given (sub) list of mediators + * if the specified condition is satisfied + * + * @see FilterMediator#test(org.apache.synapse.MessageContext) + */ +public interface <span style="font-weight: bold;">FilterMediator </span>extends ListMediator { + + /** + * Should return true if the sub/child mediators should execute. i.e. if the filter + * condition is satisfied + * @param synCtx + * @return true if the configured filter condition evaluates to true + */ + public boolean test(MessageContext synCtx); +}</pre> + <h2> + Writing custom Configuration implementations for mediators + </h2> + <p> + You may write your own custom configurator for the Mediator implementation + you write without relying on the Class mediator or Spring extension for + its initialization. You could thus write a MediatorFactory implementation + which defines how to digest a custom XML configuration element to be used + to create and configure the custom mediator instance. A MediatorSerializer + implementation defines how a configuration should be serialized back into + an XML configuration. The custom MediatorFactory & MediatorSerializer + implementations and the mediator class/es must be bundled in a JAR file + conforming to the J2SE Service Provider model (See the description for + Extensions below for more details and examples) and placed into the + SYNAPSE_HOME/lib folder, so that the Synapse runtime could find and load + the definition. Essentially this means that a custom JAR file must bundle + your class implementing the Mediator interface, and the MediatorFactory + implementation class and contain two text files named + "org.apache.synapse.config.xml.MediatorFactory" and + "org.apache.synapse.config.xml.MediatorSerializer" which will contain the + fully qualified name(s) of your MediatorFactory and MediatorSerializer + implementation classes. You should also place any dependency JARs into the + same lib folder so that the correct classpath references could be made. + The MediatorFactory interface listing is given below, which you should + implement, and its getTagQName() method must define the fully qualified + element of interest for custom configuration. The Synapse initialization + will call back to this MediatorFactory instance through the + createMediator(OMElement elem) method passing in this XML element, so that + an instance of the mediator could be created utilizing the custom XML + specification and returned. See the ValidateMediator and the + ValidateMediatorFactory classes under modules/extensions in the Synapse + source distribution for examples. + </p> + <h4> + <a + href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorFactory.java?view=markup";>The + MediatorFactory interface</a> + </h4> +<pre xml:space="preserve">package org.apache.synapse.config.xml; + +import ... + +/** + * A mediator factory capable of creating an instance of a mediator through a given + * XML should implement this interface + */ +public interface MediatorFactory { + /** + * Creates an instance of the mediator using the OMElement + * @param elem + * @return the created mediator + */ + public Mediator createMediator(OMElement elem); + + /** + * The QName of this mediator element in the XML config + * @return QName of the mediator element + */ + public QName getTagQName(); +}</pre> + <p/> + <h4> + <a + href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorSerializer.java?view=markup";>The + MediatorSerializer interface</a> + </h4> +<pre xml:space="preserve">package org.apache.synapse.config.xml; + +import ... + +/** + * Interface which should be implemented by mediator serializers. Does the + * reverse of the MediatorFactory + */ +public interface MediatorSerializer { + + /** + * Return the XML representation of this mediator + * @param m mediator to be serialized + * @param parent the OMElement to which the serialization should be attached + * @return the serialized mediator XML + */ + public OMElement serializeMediator(OMElement parent, Mediator m); + + /** + * Return the class name of the mediator which can be serialized + * @return the class name + */ + public String getMediatorClassName(); +}</pre> + <h2> + Configuring mediators + </h2> + <p> + Mediators could access the Synapse registry to load resources and + configure the local behaviour. Refer to the Spring mediator and Script + mediator implementations for examples on how this could be achieved. + </p> + <h4> + Loading of Extensions by the Synapse runtime + </h4> + <p> + Synapse loads available extensions from the runtime classpath using the <a + href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Service%20Provider";>J2SE + Service Provider model</a>. This essentially iterates over the + available JAR files, for a META-INF/services directory within each file, + and looks for a text file with the name + org.apache.synapse.config.xml.MediatorFactory which contains a list of + fully qualified classname that implement the above interface, listing each + class in a separate line. e.g. The built-in synapse-extensions.jar + contains the following structure + </p> +<pre xml:space="preserve">synapse-extensions.jar + /META-INF/services + org.apache.synapse.config.xml.MediatorFactory + org.apache.synapse.config.xml.MediatorSerializer + /... the implementation classes as usual...</pre> + </body> +</document> \ No newline at end of file
Added: synapse/trunk/java/src/site/xdoc/1_2/Synapse_QuickStart.xml URL: http://svn.apache.org/viewvc/synapse/trunk/java/src/site/xdoc/1_2/Synapse_QuickStart.xml?rev=998841&view=auto ============================================================================== --- synapse/trunk/java/src/site/xdoc/1_2/Synapse_QuickStart.xml (added) +++ synapse/trunk/java/src/site/xdoc/1_2/Synapse_QuickStart.xml Mon Sep 20 09:23:05 2010 @@ -0,0 +1,559 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<document> + <properties> + <title>Apache Synapse - Quick Start Guide</title> + </properties> + <head> + <style type="text/css" xml:space="preserve"> + .command { + border: 1px dashed #3c78b5; + text-align: left; + background-color: #f0f0f0; + padding: 3px; + font-size: 11px; + font-family: Courier; + margin: 10px; + line-height: 13px; + } + .consoleOutput { + border: 1px dashed #3c78b5; + font-size: 11px; + font-family: Courier; + margin: 10px; + line-height: 13px; + background-color: #f0f0f0; + border-bottom: 1px dashed #3c78b5; + padding: 3px; + border-style: solid; + } + .info { + border-style: solid; + border-width: 1px; + border-color: #090; + background-color: #dfd; + text-align:left; + margin-top: 5px; + margin-bottom: 5px; + } + li { + font-family: Verdana, arial, sans-serif; + font-size: 11px; + line-height: 16px; + color: #000000; + font-weight: normal; + } + p { + font-family: Verdana, arial, sans-serif; + font-size: 11px; + line-height: 16px; + color: #000000; + font-weight: normal; + } + pre { + padding: 0px; + margin-top: 5px; + margin-left: 15px; + margin-bottom: 5px; + margin-right: 5px; + text-align: left; + background-color: #f0f0f0; + padding: 3px; + border: 1px dashed #3c78b5; + font-size: 11px; + font-family: Courier; + margin: 10px; + line-height: 13px; + } + h1 { + font-size: 24px; + line-height: normal; + font-weight: bold; + background-color: #f0f0f0; + color: #003366; + border-bottom: 1px solid #3c78b5; + padding: 2px; + margin: 36px 0px 4px 0px; + } + h2 { + font-size: 18px; + line-height: normal; + font-weight: bold; + background-color: #f0f0f0; + border-bottom: 1px solid #3c78b5; + padding: 2px; + margin: 27px 0px 4px 0px; + } + h3 { + font-size: 14px; + line-height: normal; + font-weight: bold; + background-color: #f0f0f0; + padding: 2px; + margin: 21px 0px 4px 0px; + } + h4 { + font-size: 12px; + line-height: normal; + font-weight: bold; + background-color: #f0f0f0; + padding: 2px; + margin: 18px 0px 4px 0px; + }</style> + </head> + <body> + <div style="margin-top:-40px; float:right; _margin-top:0px;"> + <img alt="Synapse logo" + src="images/synapse-logo-web2.png" width="197" + height="82"/> + </div> + <div> + <h1> + Apache Synapse ESB - Quick Start Guide + </h1> + </div> + <p> + This guide will demonstrate two sample applications covering the basic and + the most common usage scenarios of Synapse; which is Message mediation and + Service mediation (i.e. using Proxy services). You will be guided through + a step by step approach to get a feeling about Synapse from the absolute + beginning. + </p> + <h3> + Pre-requisites + </h3> + <p> + You should have following pre-requisites installed on your system to + follow through this guide + </p> + <ul> + <li> + A Java 2 SE - JDK or JRE of version 1.5.x or higher + </li> + <li> + Apache Ant <a href="http://ant.apache.org";>http://ant.apache.org</a> + </li> + </ul> + <h2> + Message Mediation + </h2> + <p> + In this example Synapse will be used to simply log all the messages + passing through it. Although this simple scenario only performs logging, + it demonstrates the basics of message mediation, where the logging + functionality could be replaced with any combination of advanced + mediations such as transformations, content based routing as well as + bridging between different communication protocols etc. So, let's start + with the basics. + </p> + <h3> + Download + </h3> + <p> + Our first task is to download Synapse. Open a web browser and access the + following URL: + <a href="http://synapse.apache.org/download.html";>http://synapse.apache.org/download.html</a>. + You will then see the list of available releases. Click on the latest version, and you + will be directed to the Synapse release download page. Now download the + 'Standard binary distribution' ZIP or tar.gz archive compatible with your + operating system. + </p> + <h3> + Installation + </h3> + <p> + Synapse can be installed just by extracting the downloaded binary + archive.. A directory named synapse with the release number will be + created in the selected parent directory, containing all the files + required for Synapse. We will refer to this directory as <synapse-home> + from now on. + </p> + <h3> + Running the sample + </h3> + <p> + Synapse ships with a set of sample clients and services to demonstrate + some of its core capabilities. Hence, you will need to run three programs + to get an idea of message mediation. The destination server that hosts the + ultimate service to be invoked to service the client, the client itself, + and Synapse, which acts as the intermediary to bridge between the client + and the server. + </p> + <p/> + <h4> + Starting the sample Axis2 server + </h4> + <p> + In this case we are using a standalone Axis2 web services engine as the + server. You don't have to get it now, it is already bundled with your + Synapse distribution. But we have to deploy a sample service for which + client can send requests. Go to <synapse-home>/samples/axis2Server/src/SimpleStockQuoteService + directory. Run "ant" to build and deploy this service to the sample Axis2 + server. + </p> + <p/> +<pre xml:space="preserve">u...@host:/opt/synapse-1.1.1/samples/axis2Server$ cd src/SimpleStockQuoteService/ +u...@host:/opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService$ ant +Buildfile: build.xml + +clean: + +init: + [mkdir] Created dir: /opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService/temp + [mkdir] Created dir: /opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService/temp/classes + [mkdir] Created dir: /opt/synapse-1.1.1/samples/axis2Server/repository/services + +compile-all: + [javac] Compiling 9 source files to /opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService/temp/classes + +build-service: + [mkdir] Created dir: /opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote + [mkdir] Created dir: /opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF + [copy] Copying 1 file to /opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF + [copy] Copying 1 file to /opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF + [copy] Copying 9 files to /opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote + [jar] Building jar: /opt/synapse-1.1.1/samples/axis2Server/repository/services/SimpleStockQuoteService.aar + +BUILD SUCCESSFUL +Total time: 2 seconds +u...@host:/opt/synapse-1.1.1/samples/axis2Server/src/SimpleStockQuoteService$</pre> + <p> + Now go to <synapse-home>/samples/axis2Server directory and start the + server using the following command. This will start Axis2 server on port + 9000 (http). + </p> + <div class="command"> + <p> + Linux / Unix: . axis2server.sh + </p> + <p> + Windows: axis2server.bat + </p> + </div> + <p> + You will see the following messages on the console. + </p> +<pre xml:space="preserve">u...@host:/opt/synapse-1.1.1/samples/axis2Server$ ./axis2server.sh + Using Bouncy castle JAR for Java 1.5 + Using JAVA_HOME: /opt/jdk1.5_06 + Using AXIS2 Repository : /opt/synapse-1.1.1/samples/axis2Server/repository + Using AXIS2 Configuration : /opt/synapse-1.1.1/samples/axis2Server/repository/conf/axis2.xml +2007-11-05 14:36:41,462 [-] [main] INFO SimpleHTTPServer [SimpleAxisServer] Starting +[SimpleAxisServer] Using the Axis2 Repository : /opt/synapse-1.1.1/samples/axis2Server/repository +[SimpleAxisServer] Using the Axis2 Configuration File : /opt/synapse-1.1.1/samples/axis2Server/repository/conf/axis2.xml +2007-11-05 14:36:43,864 [-] [main] INFO HttpCoreNIOSender HTTPS Sender starting +2007-11-05 14:36:43,891 [-] [main] INFO HttpCoreNIOSender HTTP Sender starting +2007-11-05 14:36:44,288 [-] [main] INFO HttpCoreNIOListener HTTPS Listener starting on port : 9002 +2007-11-05 14:36:44,298 [-] [main] INFO HttpCoreNIOListener HTTP Listener starting on port : 9000 +2007-11-05 14:36:44,350 [-] [main] INFO SimpleHTTPServer [SimpleAxisServer] Started</pre> + <p/> + <h4> + Starting Synapse + </h4> + <p> + Now it's time to start Synapse. In this scenario we are starting Synapse + using the sample configuration found in synapse_sample_0.xml (i.e. in + repository/conf/sample) and listed below. It is configured to log and pass + through, all the messages. + </p> +<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse"><br/> <log level="full"/> <br/> <send/> +</definitions> </pre> + <p/> + <p> + Go to <synapse-home>/bin directory and type the command given below. + Synapse will be started on port 8280 (http) and 8243 (https - under JDK + 1.5) + </p> + <div class="command"> + <p> + Linux / Unix: . synapse.sh -sample 0 + </p> + <p> + Windows: synapse.bat -sample 0 + </p> + </div> + <p/> + <p> + Following messages will be displayed on the console to indicate the + successfull startup of Synapse. + </p> +<pre xml:space="preserve">u...@host:/opt/synapse-1.1.1/bin$ ./synapse.sh -sample 0 + Using Bouncy castle JAR for Java 1.5 +Starting Synapse/Java ... +Using SYNAPSE_HOME: /opt/synapse-1.1.1 +Using JAVA_HOME: /opt/jdk1.5_06 +Using SYNAPSE_XML: -Dsynapse.xml=/opt/synapse-1.1.1/repository/conf/sample/synapse_sample_0.xml +2007-11-05 14:58:55,029 [-] [main] INFO ServerManager Using the Axis2 Repository /opt/synapse-1.1.1/repository +2007-11-05 14:58:56,617 [-] [main] INFO SynapseInitializationModule Initializing Synapse at : Mon Nov 05 14:58:56 LKT 2007 +2007-11-05 14:58:56,618 [127.0.1.1-asankha] [main] INFO SynapseInitializationModule Loading mediator extensions... +2007-11-05 14:58:56,619 [127.0.1.1-asankha] [main] INFO SynapseInitializationModule Initializing the Synapse configuration ... +2007-11-05 14:58:56,624 [127.0.1.1-asankha] [main] INFO XMLConfigurationBuilder Generating the Synapse configuration model by parsing the XML configuration +2007-11-05 14:58:56,717 [127.0.1.1-asankha] [main] INFO SynapseConfigurationBuilder Loaded Synapse configuration from : /opt/synapse-1.1/repository/conf/sample/synapse_sample_0.xml +2007-11-05 14:58:56,724 [127.0.1.1-asankha] [main] INFO SynapseInitializationModule Deploying the Synapse service.. +2007-11-05 14:58:56,740 [127.0.1.1-asankha] [main] INFO SynapseInitializationModule Initializing Sandesha 2... +2007-11-05 14:58:56,801 [127.0.1.1-asankha] [main] INFO SynapseInitializationModule Deploying Proxy services... +2007-11-05 14:58:56,801 [127.0.1.1-asankha] [main] INFO SynapseInitializationModule Synapse initialized successfully...! +2007-11-05 14:58:56,886 [127.0.1.1-asankha] [main] INFO HttpCoreNIOSender HTTPS Sender starting +2007-11-05 14:58:56,887 [127.0.1.1-asankha] [main] INFO HttpCoreNIOSender HTTP Sender starting +2007-11-05 14:58:57,039 [127.0.1.1-asankha] [main] INFO HttpCoreNIOListener HTTPS Listener starting on port : 8243 +2007-11-05 14:58:57,040 [127.0.1.1-asankha] [main] INFO ServerManager Starting transport https on port 8243 +2007-11-05 14:58:57,041 [127.0.1.1-asankha] [main] INFO HttpCoreNIOListener HTTP Listener starting on port : 8280 +2007-11-05 14:58:57,041 [127.0.1.1-asankha] [main] INFO ServerManager Starting transport http on port 8280 +2007-11-05 14:58:57,085 [127.0.1.1-asankha] [main] INFO ServerManager Starting transport vfs +2007-11-05 14:58:57,086 [127.0.1.1-asankha] [main] INFO ServerManager Ready for processing</pre> + <p/> + <h4> + Run the client + </h4> + <p> + Now the final step, running the client. Go to <synapse-home>/samples/axis2Client + directory and type the following command + </p> +<pre xml:space="preserve">u...@host:/opt/synapse-1.1.1/samples/axis2Client$ ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dmode=quote -Dsymbol=IBM +Buildfile: build.xml + +init: + [mkdir] Created dir: /opt/synapse-1.1.1/samples/axis2Client/target/classes + +compile: + [javac] Compiling 10 source files to /opt/synapse-1.1.1/samples/axis2Client/target/classes + +stockquote: + [java] Standard :: Stock price = $91.09641757880443 + +BUILD SUCCESSFUL</pre> + <p/> + <p> + This sends a request for a stock quote for the symbol IBM and sets the + transport URL to Synapse (http://localhost:8280) and the WS-Addressing EPR + set that of the actual server + (http://localhost:9000/soap/SimpleStockQuoteService). The actual wire + level http message sent by the client is as follows, and is sent over port + 8280 to the Synapse instance on localhost. + </p> +<pre xml:space="preserve">POST / HTTP/1.1 +Content-Type: text/xml; charset=UTF-8 +SOAPAction: "urn:getQuote" +User-Agent: Axis2 +Host: 127.0.0.1 +Transfer-Encoding: chunked + +218 +<?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/soap/SimpleStockQuoteService</wsa:To> + <wsa:MessageID>urn:uuid:D538B21E30B32BB8291177589283717</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>0</pre> + <p/> + <p> + Now take a look at the console running Synapse. You will see that all the + details of the mediation are logged along with all the SOAP messages + passed through Synapse. If you execute Synapse in debug mode by editing + the lib/log4j.properties "log4j.category.org.apache.synapse" as "DEBUG" + instead of INFO, you will see more information as follows after a restart + and replay of the above scenario again. + </p> +<pre xml:space="preserve">2007-11-05 15:03:51,082 [127.0.1.1-asankha] [I/O dispatcher 3] INFO PipeImpl Using native OS Pipes for event-driven to stream IO bridging +2007-11-05 15:03:51,206 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SynapseMessageReceiver Synapse received a new message for message mediation... +2007-11-05 15:03:51,206 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SynapseMessageReceiver Received To: http://localhost:9000/soap/SimpleStockQuoteService +2007-11-05 15:03:51,206 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SynapseMessageReceiver SOAPAction: urn:getQuote +2007-11-05 15:03:51,206 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SynapseMessageReceiver WSA-Action: urn:getQuote +2007-11-05 15:03:51,206 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG Axis2SynapseEnvironment Injecting MessageContext +2007-11-05 15:03:51,207 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG Axis2SynapseEnvironment Using Main Sequence for injected message +2007-11-05 15:03:51,207 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SequenceMediator Start : Sequence <main> +2007-11-05 15:03:51,207 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SequenceMediator Sequence <SequenceMediator> :: mediate() +2007-11-05 15:03:51,207 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG LogMediator Start : Log mediator +2007-11-05 15:03:51,231 [127.0.1.1-asankha] [HttpServerWorker-1] INFO LogMediator To: http://localhost:9000/soap/SimpleStockQuoteService, WSAction: urn:getQuote, SOAPAction: urn:getQuote, ReplyTo: http://www.w3.org/2005/08/addressing/anonymous, MessageID: urn:uuid:DB76240DF26CE9AF1D1194253430879, Direction: request, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"; xmlns:wsa="http://www.w3.org/2005/08/addressing"><soapenv:Header><wsa:To>http://localhost:9000/soap/SimpleStockQuoteService</wsa:To><wsa:MessageID>urn:uuid:DB76240DF26CE9AF1D1194253430879</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> +2007-11-05 15:03:51,250 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG LogMediator End : Log mediator +2007-11-05 15:03:51,250 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SendMediator Start : Send mediator +2007-11-05 15:03:51,250 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SendMediator Sending request message using implicit message properties.. +Sending To: http://localhost:9000/soap/SimpleStockQuoteService +SOAPAction: urn:getQuote +2007-11-05 15:03:51,254 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG Axis2FlexibleMEPClient Sending [add = false] [sec = false] [rm = false] [ to Address: http://localhost:9000/soap/SimpleStockQuoteService] +2007-11-05 15:03:51,302 [127.0.1.1-asankha] [HttpServerWorker-1] INFO TimeoutHandler This engine will expire all callbacks after : 86400 seconds, irrespective of the timeout action, after the specified or optional timeout +2007-11-05 15:03:51,356 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SendMediator End : Send mediator +2007-11-05 15:03:51,356 [127.0.1.1-asankha] [HttpServerWorker-1] DEBUG SequenceMediator End : Sequence <main> +2007-11-05 15:03:51,398 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver Synapse received an asynchronous response message +2007-11-05 15:03:51,400 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver Received To: null +2007-11-05 15:03:51,400 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver SOAPAction: null +2007-11-05 15:03:51,400 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver WSA-Action: null +2007-11-05 15:03:51,402 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver Body : +<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><ns:getQuoteResponse xmlns:ns="http://services.samples/xsd"><ns:return type="samples.services.GetQuoteResponse"><ns:change>4.03627430702446</ns:change><ns:earnings>-9.467701672785129</ns:earnings><ns:high>191.83014686803938</ns:high><ns:last>185.42637586281398</ns:last><ns:lastTradeTimestamp>Mon Nov 05 15:03:51 LKT 2007</ns:lastTradeTimestamp><ns:low>193.2690208751758</ns:low><ns:marketCap>-1737393.107878862</ns:marketCap><ns:name>IBM Company</ns:name><ns:open>-183.2632780777984</ns:open><ns:peRatio>-17.430497030284027</ns:peRatio><ns:percentageChange>1.9749680728382655</ns:percentageChange><ns:prevClose>204.37162314344914</ns:prevClose><ns:symbol>IBM</ns:symbol>< ns:volume>6695</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body></soapenv:Envelope> +2007-11-05 15:03:51,404 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG Axis2SynapseEnvironment Injecting MessageContext +2007-11-05 15:03:51,404 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG Axis2SynapseEnvironment Using Main Sequence for injected message +2007-11-05 15:03:51,404 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SequenceMediator Start : Sequence <main> +2007-11-05 15:03:51,404 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SequenceMediator Sequence <SequenceMediator> :: mediate() +2007-11-05 15:03:51,404 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG LogMediator Start : Log mediator +2007-11-05 15:03:51,405 [127.0.1.1-asankha] [HttpClientWorker-1] INFO LogMediator To: http://www.w3.org/2005/08/addressing/anonymous, MessageID: urn:uuid:A6510AF6BD288D8DFB1194253431259544001-942151716, Direction: response, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><ns:getQuoteResponse xmlns:ns="http://services.samples/xsd"><ns:return type="samples.services.GetQuoteResponse"><ns:change>4.03627430702446</ns:change><ns:earnings>-9.467701672785129</ns:earnings><ns:high>191.83014686803938</ns:high><ns:last>185.42637586281398</ns:last><ns:lastTradeTimestamp>Mon Nov 05 15:03:51 LKT 2007</ns:lastTradeTimestamp><ns:low>193.2690208751758</ns:low><ns:marketCap>-1737393.107878862</ns:marketCap><ns:name>IBM Company</ns:name><ns:open>-183.2632780777984</ns:ope n><ns:peRatio>-17.430497030284027</ns:peRatio><ns:percentageChange>1.9749680728382655</ns:percentageChange><ns:prevClose>204.37162314344914</ns:prevClose><ns:symbol>IBM</ns:symbol><ns:volume>6695</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body></soapenv:Envelope> +2007-11-05 15:03:51,405 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG LogMediator End : Log mediator +2007-11-05 15:03:51,405 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SendMediator Start : Send mediator +2007-11-05 15:03:51,405 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SendMediator Sending response message using implicit message properties.. +Sending To: http://www.w3.org/2005/08/addressing/anonymous +SOAPAction: null +2007-11-05 15:03:51,408 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SendMediator End : Send mediator +2007-11-05 15:03:51,408 [127.0.1.1-asankha] [HttpClientWorker-1] DEBUG SequenceMediator End : Sequence <main></pre> + <p> + You have successfully completed the first part of this guide. Now let's + look at the next scenario, proxy services. + </p> + <p/> + <h2> + Proxy Services + </h2> + <p> + As the name implies, a proxy service acts as a service hosted in Synapse, + and typically fronts an existing service endpoint. A proxy service can be + created and exposed on a different transport, schema, WSDL, or QoS (such + as WS-Security, WS-Reliable Messaging) aspect than the real service and + could mediate the messages before being delivered to the actual endpoint, + and the responses before they reach the client. + </p> + <p> + Clients can send requests for proxy services directly to Synapse, as the + client sees as if they are hosted on it, and for example can perform ?wsdl + and view the WSDL of the virtual proxy service. But in the Synapse + configuration, such requests can be handled in anyway you like. Most + obvious thing would be to do some processing to the message and send it to + the actual service, probably running on a different computer. But it is + not necessary to always send the message to the actual service. You may + list any combination of tasks to be performed on the messages received for + the proxy service and terminate the flow or send some java back to the + client even without sending it to an actual service. Let's explore a + simple proxy services scenario step by step to get a better feeling. As + you have downloaded and installed Synapse in the previous section, now you + can start directly on the sample. + </p> + <p/> + <h3> + Running the sample + </h3> + <p> + As in the previous section, there should be three entities running to + demonstrate proxy services, the server, client and Synapse. Let's start + with the server. + </p> + <p/> + <h4> + Starting the sample Axis2 server + </h4> + <p> + As you have built and deployed the SimpleStockQuote service in the + previous section, you can simply start the server by switching to the <synapse-home>/samples/axis2Server + directory and running the following command. + </p> + <div class="command"> + <p> + Linux / Unix: . axis2server.sh + </p> + <p> + Windows: axis2server.bat + </p> + </div> + <p> + You can see the console messages as in the previous section. + </p> + <h4> + Starting Synapse + </h4> + <p> + We have to start Synapse with a configuration containing a proxy service + definition. In this case we are using the synapse_sample_150.xml, so that + you don't have to write the configuration your self. + </p> +<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse"> + <proxy name="StockQuoteProxy"> + <target> + <endpoint> + <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> + </endpoint> + <outSequence> + <send/> + </outSequence> + </target> + <publishWSDL uri="file:repository/conf/sample/resources/proxy/sample_proxy_1.wsdl"/> + </proxy> +</definitions></pre> + <p/> + <p> + The above configuration will expose a proxy service named StockQuoteProxy + and specifies an endpoint + (http://localhost:9000/soap/SimpleStockQuoteService) as the target for the + proxy service. Therefore, messages coming to the proxy service will be + directed to the address http://localhost:9000/soap/SimpleStockQuoteService + specified in the endpoint. There is also an out sequence for the proxy + service, which is applicable for response messages. In the out sequence, + we just send the messages back to the client. The publishWSDL tag + specifies an WSDL to be published for this proxy service. Let's start + Synapse with this sample configuration by running the below command from + the <synapse-home>/bin directory. It is possible to specify a + sequence of mediation for incoming messages instead of a target endpoint, + and many other possibilities and options are available to configure proxy + services. These are explained in the samples and configuration guides. + </p> + <p/> + <div class="command"> + <p> + Linux / Unix: . synapse.sh -sample 150 + </p> + <p> + Windows: synapse.bat -sample 150 + </p> + </div> + <p/> + <p> + Synapse will display a set of messages as in the previous section + describing the steps of starting procedure. Before running the client, it + is time to observe another feature of proxy services. That is displaying + the published WSDL. Just open a web browser and point it to the address + http://localhost:8280/soap/StockQuoteProxy?wsdl. You will see the + sample_proxy_1.wsdl specified in the configuration but containing the + correct EPR for the service over http/s. + </p> + <p/> + <h4> + Run the client + </h4> + <p> + Now it is time to see it in action. Go to the <synapse-home>/samples/axis2Clients + directory and type the following command: + </p> + <div class="command"> + ant stockquote -Dtrpurl=http://localhost:8280/soap/StockQuoteProxy + -Dmode=quote -Dsymbol=IBM + </div> + <p> + The above command sends a stockquote request directly to the provided + transport endpoint at: http://localhost:8280/soap/StockQuoteProxy. You + will see the response from the server displayed on the console as follows: + </p> + <div class="consoleOutput"> + Standard :: Stock price = $165.32687331383468 + </div> + <p/> + <p> + This quick guide illustrates the simple use case of proxy services. Please + refer to samples #150 and above in the Samples guide, for in depth + coverage of more advanced use cases. + </p> + <p/> + <p> + Yes, you are done with a quick look at Synapse. Now it is time to go + deeper and reveal the advanced features of Synapse. You can browse through + the samples for your interested areas. If you have any issue regarding + Synapse as a user, feel free ask it in the Synapse user mailing list + (<a href="http://synapse.apache.org/mail-lists.html";>http://synapse.apache.org/mail-lists.html</a>). + </p> + <p/> + <p/> + <p/> + </body> +</document> \ No newline at end of file
