Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/extending.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/extending.xml?rev=1302321&view=auto
==============================================================================
--- synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/extending.xml
(added)
+++ synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/extending.xml
Mon Mar 19 08:41:05 2012
@@ -0,0 +1,473 @@
+<!--
+~ Licensed to the Apache Software Foundation (ASF) under one
+~ or more contributor license agreements. See the NOTICE file
+~ distributed with this work for additional information
+~ regarding copyright ownership. The ASF licenses this file
+~ to you under the Apache License, Version 2.0 (the
+~ "License"); you may not use this file except in compliance
+~ with the License. You may obtain a copy of the License at
+~
+~ http://www.apache.org/licenses/LICENSE-2.0
+~
+~ Unless required by applicable law or agreed to in writing,
+~ software distributed under the License is distributed on an
+~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~ KIND, either express or implied. See the License for the
+~ specific language governing permissions and limitations
+~ under the License.
+-->
+<html>
+<head>
+ <meta content="text/html; charset=iso-8859-1" http-equiv="content-type"/>
+ <title>Extending Synapse</title>
+ <style type="text/css">
+ .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>
+<h1>Extending Synapse<br/>
+</h1>
+
+<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/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/MessageContext.java?view=markup";>MessageContext
+Interface</a></h4>
+
+<p></p>
+<pre>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/webservices/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>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/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/ListMediator.java?view=markup";>The
+ListMediator interface</a></h4>
+<pre>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/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/FilterMediator.java?view=markup";>FilterMediator
+interface</a></h4>
+<pre>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/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorFactory.java?view=markup";>The
+MediatorFactory interface</a></h4>
+<pre>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></p>
+
+<h4><a
+href="http://svn.apache.org/viewvc/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorSerializer.java?view=markup";>The
+MediatorSerializer interface</a></h4>
+<pre>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>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>
+</html>
+
+
Propchange:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/extending.xml
------------------------------------------------------------------------------
svn:executable = *
Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/quickstart.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/quickstart.xml?rev=1302321&view=auto
==============================================================================
--- synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/quickstart.xml
(added)
+++ synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/quickstart.xml
Mon Mar 19 08:41:05 2012
@@ -0,0 +1,519 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
+ <title>Apache Synapse - Quick Start Guide</title>
+ <style type="text/css">
+ .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>
+<h1>Quick Start Guide</h1>
+
+<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 http://ant.apache.org</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: http://ws.apache.org/synapse/download.cgi. 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></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></p>
+<pre>user@host:/opt/synapse-1.2-SNAPSHOT/samples/axis2Server$ cd
src/SimpleStockQuoteService/
+user@host:/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService$
ant
+Buildfile: build.xml
+
+clean:
+
+init:
+ [mkdir] Created dir:
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp
+ [mkdir] Created dir:
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
+ [mkdir] Created dir:
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/repository/services
+
+compile-all:
+ [javac] Compiling 9 source files to
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
+
+build-service:
+ [mkdir] Created dir:
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
+ [mkdir] Created dir:
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 1 file to
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 1 file to
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 9 files to
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
+ [jar] Building jar:
/opt/synapse-1.2-SNAPSHOT/samples/axis2Server/repository/services/SimpleStockQuoteService.aar
+
+BUILD SUCCESSFUL
+Total time: 2 seconds
+user@host:/opt/synapse-1.2-SNAPSHOT/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>user@host:/opt/synapse-1.2-SNAPSHOT/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.2-SNAPSHOT/samples/axis2Server/repository
+ Using AXIS2 Configuration :
/opt/synapse-1.2-SNAPSHOT/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.2-SNAPSHOT/samples/axis2Server/repository
+[SimpleAxisServer] Using the Axis2 Configuration File :
/opt/synapse-1.2-SNAPSHOT/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></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><definitions xmlns="http://ws.apache.org/ns/synapse"><br/>
<log level="full"/> <br/> <send/>
+</definitions> </pre>
+
+<p></p>
+
+<p>Go to <synapse-home>/bin directory and type the command given below.
+Synapse will be started on port 8080 (http) and 8443 (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>
+
+<p>Following messages will be displayed on the console to indicate the
+successfull startup of Synapse.</p>
+<pre>user@host:/opt/synapse-1.2-SNAPSHOT/bin$ ./synapse.sh -sample 0
+ Using Bouncy castle JAR for Java 1.5
+Starting Synapse/Java ...
+Using SYNAPSE_HOME: /opt/synapse-1.2-SNAPSHOT
+Using JAVA_HOME: /opt/jdk1.5_06
+Using SYNAPSE_XML:
-Dsynapse.xml=/opt/synapse-1.2-SNAPSHOT/repository/conf/sample/synapse_sample_0.xml
+2007-11-05 14:58:55,029 [-] [main] INFO ServerManager Using the Axis2
Repository /opt/synapse-1.2-SNAPSHOT/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 : 8443
+2007-11-05 14:58:57,040 [127.0.1.1-asankha] [main] INFO ServerManager
Starting transport https on port 8443
+2007-11-05 14:58:57,041 [127.0.1.1-asankha] [main] INFO HttpCoreNIOListener
HTTP Listener starting on port : 8080
+2007-11-05 14:58:57,041 [127.0.1.1-asankha] [main] INFO ServerManager
Starting transport http on port 8080
+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></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>user@host:/opt/synapse-1.2-SNAPSHOT/samples/axis2Client$ ant stockquote
-Daddurl=http://localhost:9000/soap/SimpleStockQuoteService
-Dtrpurl=http://localhost:8080 -Dmode=quote -Dsymbol=IBM
+Buildfile: build.xml
+
+init:
+ [mkdir] Created dir:
/opt/synapse-1.2-SNAPSHOT/samples/axis2Client/target/classes
+
+compile:
+ [javac] Compiling 10 source files to
/opt/synapse-1.2-SNAPSHOT/samples/axis2Client/target/classes
+
+stockquote:
+ [java] Standard :: Stock price = $91.09641757880443
+
+BUILD SUCCESSFUL</pre>
+
+<p></p>
+
+<p>This sends a request for a stock quote for the symbol IBM and sets the
+transport URL to Synapse (http://localhost:8080) 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 8080 to
+the Synapse instance on localhost.</p>
+<pre>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>
+
+<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>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></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></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></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><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>
+
+<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></p>
+
+<div class="command">
+<p>Linux / Unix: . synapse.sh -sample 150</p>
+
+<p>Windows: synapse.bat -sample 150</p>
+</div>
+
+<p></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:8080/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></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:8080/soap/StockQuoteProxy
+-Dmode=quote -Dsymbol=IBM</div>
+
+<p>The above command sends a stockquote request directly to the provided
+transport endpoint at: http://localhost:8080/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>
+
+<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>
+
+<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
+(http://ws.apache.org/synapse/mail-lists.html).</p>
+
+<p></p>
+
+<p></p>
+
+<p></p>
+</body>
+</html>
+
+
Propchange:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_1_1/quickstart.xml
------------------------------------------------------------------------------
svn:executable = *
