Added: synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/extending.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/extending.xml?rev=1302321&view=auto
==============================================================================
--- synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/extending.xml
(added)
+++ synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/extending.xml
Mon Mar 19 08:41:05 2012
@@ -0,0 +1,482 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"; >
+
+<html xmlns="http://www.w3.org/1999/xhtml";>
+ <head>
+ <meta content="text/html; charset=iso-8859-1" http-equiv="content-type"/>
+ <title>
+ Extending Synapse
+ </title>
+ <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>
+ <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/>
+<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/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 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/webservices/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/webservices/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/webservices/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/webservices/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>
+</html>
\ No newline at end of file
Propchange:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/extending.xml
------------------------------------------------------------------------------
svn:executable = *
Added: synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/quickstart.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/quickstart.xml?rev=1302321&view=auto
==============================================================================
--- synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/quickstart.xml
(added)
+++ synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/quickstart.xml
Mon Mar 19 08:41:05 2012
@@ -0,0 +1,553 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"; >
+
+<html xmlns="http://www.w3.org/1999/xhtml";>
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
+ <title>
+ Apache Synapse - Quick Start Guide
+ </title>
+ <meta name="generator" content="Amaya 9.54, see http://www.w3.org/Amaya/"/>
+ <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>
+ <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.4.2 or higher
+ </li>
+ <li>
+ Apache Ant http://ant.apache.org
+ </li>
+ </ul>
+ <p>
+ Note: To use the bundled https transport, you will need a Java 2 SE
+ runtime of version 1.5 or later. If you are using a J2SE below 1.5 and
+ does not require the https transport, you may comment out the following
+ section from your repository/conf/axis2.xml and
+ samples/axis2Server/repository/conf/axis2.xml configuration files.
+ </p>
+<pre xml:space="preserve">...
+ <transportReceiver name="https"...<br/> ...<br/>
</transportReceiver>
+ ...
+ <transportSender name="https"...<br/> ...<br/>
</transportSender>
+....</pre>
+ <p/>
+ <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 1.0 version, and you
will
+ be directed to the Synapse 1.0 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-1.0 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">user@host:/opt/synapse/samples/axis2Server$ cd
src/SimpleStockQuoteService/
+user@host:/opt/synapse/samples/axis2Server/src/SimpleStockQuoteService$ ant
+Buildfile: build.xml
+
+clean:
+ [delete] Deleting directory
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp
+
+init:
+ [mkdir] Created dir:
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp
+ [mkdir] Created dir:
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
+
+compile-all:
+ [javac] Compiling 9 source files to
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
+
+build-service:
+ [mkdir] Created dir:
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
+ [mkdir] Created dir:
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 1 file to
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 1 file to
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+ [copy] Copying 9 files to
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
+ [jar] Building jar:
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository/services/SimpleStockQuoteService.aar
+
+BUILD SUCCESSFUL
+Total time: 1 second</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">user@host:/opt/synapse/samples/axis2Server$
./axis2server.sh
+ Using JAVA_HOME: /opt/jdk1.5_06
+ Using AXIS2 Repository :
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository
+ Using AXIS2 Configuration :
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository/conf/axis2.xml
+[SimpleAxisServer] Using the Axis2 Repository :
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository
+[SimpleAxisServer] Using the Axis2 Configuration File :
/home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository/conf/axis2.xml
+[main] INFO HttpCoreNIOSender - HTTPS Sender starting
+[main] INFO HttpCoreNIOSender - HTTP Sender starting
+[main] INFO HttpCoreNIOListener - HTTPS Listener starting on port : 9002
+[main] INFO HttpCoreNIOListener - HTTP Listener starting on port : 9000 </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 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>
+ Following messages will be displayed on the console to indicate the
+ successfull startup of Synapse.
+ </p>
+<pre xml:space="preserve">user@host:/opt/synapse/bin$ ./synapse.sh -sample 0
+Starting Synapse/Java ...
+Using SYNAPSE_HOME: /opt/synapse
+Using JAVA_HOME: /opt/jdk1.5_06
+Using SYNAPSE_XML:
-Dsynapse.xml=/opt/synapse/repository/conf/sample/synapse_sample_0.xml
+[SynapseServer] Using the Axis2 Repository /opt/synapse/repository
+[main] INFO SynapseModule - Initializing the Synapse configuration ...
+...
+[main] INFO SynapseConfigurationBuilder - Loaded Synapse configuration from :
/opt/synapse/repository/conf/sample/synapse_sample_0.xml
+[main] INFO SynapseModule - Deploying the Synapse service..
+[main] INFO SynapseModule - Deploying Proxy services...
+[main] INFO SynapseModule - Synapse initialized successfully...!
+[main] ERROR SandeshaModule - Could not load module policies. Using default
values.
+[main] INFO HttpCoreNIOSender - HTTPS Sender starting
+[main] INFO HttpCoreNIOSender - HTTP Sender starting
+[main] INFO HttpCoreNIOListener - HTTPS Listener starting on port : 8443
+[SynapseServer] Starting transport https on port 8443
+[main] INFO HttpCoreNIOListener - HTTP Listener starting on port : 8080
+[SynapseServer] Starting transport http on port 8080
+[SynapseServer] Ready</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">user@host:/opt/synapse/samples/axis2Client$ ant
stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService
-Dtrpurl=http://localhost:8080 -Dmode=quote -Dsymbol=IBM
+Buildfile: build.xml
+
+init:
+
+compile:
+
+stockquote:
+ [java] Standard :: Stock price = $175.56196739870038
+
+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: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 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 - as Synapse is running on debug mode by default.
+ </p>
+<pre xml:space="preserve">[I/O reactor worker thread 5] INFO PipeImpl - Using
native OS Pipes for event-driven to stream IO bridging
+[HttpServerWorker-1] DEBUG SynapseMessageReceiver - Synapse received a new
message for message mediation...
+[HttpServerWorker-1] DEBUG SynapseMessageReceiver - Received To:
http://localhost:9000/soap/SimpleStockQuoteService
+[HttpServerWorker-1] DEBUG SynapseMessageReceiver - SOAPAction: urn:getQuote
+[HttpServerWorker-1] DEBUG SynapseMessageReceiver - WSA-Action: urn:getQuote
+[HttpServerWorker-1] DEBUG SynapseMessageReceiver - Body :
+<?xml version='1.0' encoding='utf-8'?><br/><soapenv:Envelope
xmlns:wsa="http://www.w3.org/2005/08/addressing";
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><br/><soapenv:Header><br/><wsa:To>http://localhost:9000/soap/SimpleStockQuoteService</wsa:To><br/><wsa:MessageID>urn:uuid:32748ED82860C9DBDE1177504004875</wsa:MessageID><br/><wsa:Action>urn:getQuote</wsa:Action></soapenv:Header><br/><soapenv:Body><m0:getQuote
xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol></m0:request><br/></m0:getQuote></soapenv:Body></soapenv:Envelope>
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <main>
:: mediate()
+[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence
<SequenceMediator> :: mediate()
+[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
+[HttpServerWorker-1] INFO LogMediator - To :
http://localhost:9000/soap/SimpleStockQuoteService, <br/>MessageID :
urn:uuid:32748ED82860C9DBDE1177504004875, Action : urn:getQuote, Envelope:
<br/><?xml version='1.0' encoding='utf-8'?><br/><soapenv:Envelope
xmlns:wsa="http://www.w3.org/2005/08/addressing";
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><br/><soapenv:Header><br/><wsa:To>http://localhost:9000/soap/SimpleStockQuoteService</wsa:To><br/><wsa:MessageID>urn:uuid:32748ED82860C9DBDE1177504004875</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action><br/></soapenv:Header><soapenv:Body><m0:getQuote
xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol><br/></m0:request></m0:getQuote></soapenv:Body></soapenv:Envelope>
+[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
+[HttpServerWorker-1] DEBUG SendMediator - Sending message using implicit
message properties..
+[HttpServerWorker-1] DEBUG SendMediator - Sending To:
http://localhost:9000/soap/SimpleStockQuoteService
+[HttpServerWorker-1] DEBUG SendMediator - SOAPAction: urn:getQuote
+[HttpServerWorker-1] DEBUG SendMediator - Body :
+<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope
xmlns:wsa="http://www.w3.org/2005/08/addressing";
<br/>xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Header><br/><wsa:To>http://localhost:9000/soap/SimpleStockQuoteService</wsa:To><br/><wsa:MessageID>urn:uuid:32748ED82860C9DBDE1177504004875</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action></soapenv:Header><br/><soapenv:Body><m0:getQuote
xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol></m0:request><br/></m0:getQuote></soapenv:Body></soapenv:Envelope>
+[HttpServerWorker-1] DEBUG Axis2FlexibleMEPClient - sending [add = false] [sec
= false] [rm = false] <br/>[ to Address:
http://localhost:9000/soap/SimpleStockQuoteService]
+[HttpClientWorker-1] DEBUG SynapseCallbackReceiver - Synapse received an
asynchronous response message
+[HttpClientWorker-1] DEBUG SynapseCallbackReceiver - Received To: null
+[HttpClientWorker-1] DEBUG SynapseCallbackReceiver - SOAPAction: null
+[HttpClientWorker-1] DEBUG SynapseCallbackReceiver - WSA-Action: null
+[HttpClientWorker-1] DEBUG SynapseCallbackReceiver - Body :
+<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><br/><soapenv:Body><soapenv:Envelope><soapenv:Body><ns:getQuoteResponse
xmlns:ns="http://services.samples/xsd"><br/><ns:return><ns:change>3.9759712191629117</ns:change><ns:earnings>-9.463240695957264</ns:earnings><br/><ns:high>97.0893936590198</ns:high><ns:last>93.87052890651084</ns:last><br/><ns:lastTradeTimestamp>Wed
Apr 25 18:26:46 LKT
2007</ns:lastTradeTimestamp><ns:low>96.4856592398509</ns:low><br/><ns:marketCap>5.572519121414568E7</ns:marketCap><ns:name>IBM
Company</ns:name><ns:open>-92.43795414108462</ns:open><br/><ns:peRatio>-18.381880013551893</ns:peRatio><br/><ns:percentageChange>-4.5174961332793435</ns:percentageChange><ns:prevClose>-88.01271991962221</ns:prevClose><br/
><ns:symbol>IBM</ns:symbol><ns:volume>15381</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body><br/></soapenv:Envelope></soapenv:Body></soapenv:Envelope>
+[HttpClientWorker-1] DEBUG SequenceMediator - Sequence mediator <main>
:: mediate()
+[HttpClientWorker-1] DEBUG AbstractListMediator - Implicit Sequence
<SequenceMediator> :: mediate()
+[HttpClientWorker-1] DEBUG LogMediator - Log mediator :: mediate()
+[HttpClientWorker-1] INFO LogMediator - Envelope: <?xml version='1.0'
encoding='utf-8'?><br/><soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><soapenv:Envelope><soapenv:Body><br/><ns:getQuoteResponse
xmlns:ns="http://services.samples/xsd"><ns:return><ns:change>3.9759712191629117</ns:change><br/><ns:earnings>-9.463240695957264</ns:earnings><ns:high>97.0893936590198</ns:high><ns:last>93.87052890651084</ns:last><br/><ns:lastTradeTimestamp>Wed
Apr 25 18:26:46 LKT
2007</ns:lastTradeTimestamp><ns:low>96.4856592398509</ns:low><br/><ns:marketCap>5.572519121414568E7</ns:marketCap><ns:name>IBM
Company</ns:name><ns:open>-92.43795414108462</ns:open><br/><ns:peRatio>-18.381880013551893</ns:peRatio><br/><ns:percentageChange>-4.5174961332793435</ns:percentageChange><ns:prevC
lose>-88.01271991962221</ns:prevClose><br/><ns:symbol>IBM</ns:symbol><ns:volume>15381</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body></soapenv:Envelope><br/></soapenv:Body></soapenv:Envelope>
+[HttpClientWorker-1] DEBUG SendMediator - Send mediator :: mediate()
+[HttpClientWorker-1] DEBUG SendMediator - Sending message using implicit
message properties..
+[HttpClientWorker-1] DEBUG SendMediator - Sending To: null
+[HttpClientWorker-1] DEBUG SendMediator - SOAPAction: null
+[HttpClientWorker-1] DEBUG SendMediator - Body :
+<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><br/><soapenv:Body><soapenv:Envelope><soapenv:Body><ns:getQuoteResponse
xmlns:ns="http://services.samples/xsd"><br/><ns:return><ns:change>3.9759712191629117</ns:change><ns:earnings>-9.463240695957264</ns:earnings><br/><ns:high>97.0893936590198</ns:high><ns:last>93.87052890651084</ns:last><br/><ns:lastTradeTimestamp>Wed
Apr 25 18:26:46 LKT
2007</ns:lastTradeTimestamp><ns:low>96.4856592398509</ns:low><br/><ns:marketCap>5.572519121414568E7</ns:marketCap><ns:name>IBM
Company</ns:name><ns:open>-92.43795414108462</ns:open><br/><ns:peRatio>-18.381880013551893</ns:peRatio><br/><ns:percentageChange>-4.5174961332793435</ns:percentageChange><ns:prevClose>-88.01271991962221</ns:prevClose><br/
><ns:symbol>IBM</ns:symbol><ns:volume>15381</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body><br/></soapenv:Envelope></soapenv:Body></soapenv:Envelope></pre>
+ <p/>
+ <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 neccessary 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 messge 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_100.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 100
+ </p>
+ <p>
+ Windows: synapse.bat -sample 100
+ </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 diplaying
+ 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/>
+ <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>
+ This quick guide illustrates the simple use case of proxy services.
Please
+ refer to samples #100 and above in the Samples guide, for indepth
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
+ (http://ws.apache.org/synapse/mail-lists.html).
+ </p>
+ <p/>
+ <p/>
+ <p/>
+ </body>
+</html>
\ No newline at end of file
Propchange:
synapse/trunk/java/modules/documentation/src/site/xdoc/1_0/quickstart.xml
------------------------------------------------------------------------------
svn:executable = *
