You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2011/12/22 17:16:05 UTC
svn commit: r1222320 [4/13] - in /synapse/branches/2.1/src: ./ site/
site/resources/ site/resources/css/ site/resources/images/ site/xdoc/
site/xdoc/userguide/ site/xdoc/userguide/samples/
site/xdoc/userguide/samples/setup/
Added: synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,906 @@
+<document>
+ <properties>
+ <title>Apache Synapse - Mediators Catalog</title>
+ </properties>
+ <body>
+ <section name="Mediators Catalog">
+ <p>
+ This document lists all the built-in mediators of Synapse and describes their
+ usage, functionality and configuration syntax.
+ </p>
+ </section>
+ <section name="Contents">
+ <ul>
+ <li><a href="#Intro">Introduction</a></li>
+ <li><a href="#Categories">Mediator Categories</a></li>
+ <li>
+ <a href="#CoreMediators">Core Mediators</a>
+ <ul>
+ <li><a href="#Drop">Drop Mediator</a></li>
+ <li><a href="#Log">Log Mediator</a></li>
+ <li><a href="#Property">Property Mediator</a></li>
+ <li><a href="#Send">Send Mediator</a></li>
+ </ul>
+ </li>
+ <li>
+ <a href="#FilterMediators">Filter Mediators</a>
+ <ul>
+ <li><a href="#Filter">Filter Mediator</a></li>
+ <li><a href="#InOut">In/Out Mediator</a></li>
+ <li><a href="#Switch">Switch Mediator</a></li>
+ </ul>
+ </li>
+ <li>
+ <a href="#TransformationMediators">Transformation Mediators</a>
+ <ul>
+ <li><a href="#Header">Header Mediator</a></li>
+ <li><a href="#MakeFault">MakeFault Mediator</a></li>
+ <li><a href="#PayloadFactory">Payload Factory Mediator</a></li>
+ <li><a href="#URLRewrite">URL Rewrite Mediator</a></li>
+ <li><a href="#XSLT">XSLT Mediator</a></li>
+ <li><a href="#XQuery">XQuery Mediator</a></li>
+ </ul>
+ </li>
+ <li>
+ <a href="#ExtensionMediators">Extension Mediators</a>
+ <ul>
+ <li><a href="#Clazz">Class Mediator</a></li>
+ <li><a href="#POJOCommand">POJO Command Mediator</a></li>
+ <li><a href="#Script">Script Mediator</a></li>
+ <li><a href="#Spring">Spring Mediator</a></li>
+ </ul>
+ </li>
+ <li>
+ <a href="#AdvancedMediators">Advanced Mediators</a>
+ <ul>
+ <li><a href="#Aggregate">Aggregate Mediator</a></li>
+ <li><a href="#Cache">Cache Mediator</a></li>
+ <li><a href="#Callout">Callout Mediator</a></li>
+ <li><a href="#Clone">Clone Mediator</a></li>
+ <li><a href="#Iterate">Iterate Mediator</a></li>
+ <li><a href="#Transaction">Transaction Mediator</a></li>
+ </ul>
+ </li>
+ </ul>
+ </section>
+ <section name="Introduction" id="Intro">
+ <p>
+ Mediator is the basic message processing unit in Synapse. A mediator takes an
+ input message, carries out some processing on it, and provides an output message.
+ Mediators can be linked up and arranged into chains to implement complex message
+ flows (sequences). Mediators can manipulate message content (payload), properties,
+ headers and if needed can also execute additional tasks such as database lookup,
+ service invocation and script execution.
+ </p>
+ <p>
+ Apache Synapse ships with an array of useful mediators that can be used out of the
+ box to implement message flows, services and integration patterns. Rest of this
+ article describes these mediators in detail, along with their use cases and
+ configuration syntax.
+ </p>
+ </section>
+ <section name="Mediator Categories" id="Categories">
+ <p>
+ Built-in mediators of Synapse can be classified into several groups depending
+ on the nature of their functionality and use cases.
+ </p>
+ <ul>
+ <li>
+ Core mediators - Utility mediators that are useful in a variety of scenarios
+ </li>
+ <li>
+ Filter mediators - Mediators used to filter out messages
+ </li>
+ <li>
+ Transform mediators - Mediators used to transform message content, headers and
+ attributes
+ </li>
+ <li>
+ Extension mediators - Mediators used to extend the Synapse mediation engine by
+ plugging in custom developed code
+ </li>
+ <li>
+ Advanced mediators - Mediators used to implement advanced integration scenarios
+ and patterns
+ </li>
+ </ul>
+ <p>
+ Rest of this article is structured according to the above classification. Mediators
+ in each section are arranged in the alphabetical order.
+ </p>
+ </section>
+ <section name="Core Mediators" id="CoreMediators">
+ <subsection name="Drop Mediator" id="Drop">
+ <p>
+ Drop mediator can be used to drop the current message being processed and
+ terminate a message flow. This mediator is configured as follows and it
+ does not take any additional parameters or arguments.
+ </p>
+ <div class="xmlConf"><drop/></div>
+ </subsection>
+ <subsection name="Log Mediator" id="Log">
+ <p>
+ Log mediator can be used in any sequence or proxy service to log the messages
+ being mediated. Log entries generated by the log mediator will go into the
+ standard Synapse log files. This can be further configured using the
+ log4j.properties file.
+ </p>
+ <p>
+ By default the log mediator only logs a minimalistic set of details to avoid
+ the message content being parsed. But if needed it can be configured to log the
+ full message payload, headers and even custom user defined properties. The log
+ mediator configuration takes the following general form.
+ </p>
+ <div class="xmlConf"><log [level="simple|full|headers|custom"] [separator="string"]
+ [category="INFO|DEBUG|WARN|ERROR|TRACE|FATAL"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+</log></div>
+ <p>
+ The 'level' attribute is used to specify how much information should be logged
+ by the log mediator. This attribute can take one of following four values.
+ </p>
+ <ul>
+ <li>
+ simple - Logs a set of standard headers (To, From, WSAction, SOAPAction,
+ ReplyTo and MessageID). If no log level is specified, this level will be
+ used by default.
+ </li>
+ <li>
+ full - Logs all standard headers logged in the log level 'simple' and also
+ the full payload of the message. This log level causes the message content
+ to be parsed and hence incurs a performance overhead.
+ </li>
+ <li>
+ headers - Logs all SOAP header blocks
+ </li>
+ <li>
+ custom - Only logs the user defined properties (see the next section)
+ </li>
+ </ul>
+ <p>
+ Users can define custom attributes and properties to be logged by the log mediator
+ by specifying some 'property' elements. Each property must be named, and can
+ have a constant value or an XPath expression. If a constant value is specified,
+ that value will be logged with each and every entry logged by the mediator. If
+ an XPath is specified instead, that XPath will be evaluated on the message being
+ mediated and the outcome will be included in the generated log entry.
+ </p>
+ <p>
+ By default all properties and attributes logged by the log mediator are separated
+ by commas (,). This can be configured using the 'separator' attribute. Further
+ all logs generated by the mediator are logged at log4j log level 'INFO' by default.
+ This behavior can also be configured using the 'category' attribute.
+ </p>
+ </subsection>
+ <subsection name="Property Mediator" id="Property">
+ <p>
+ Every message mediated through Synapse can have a set of associated properties.
+ Synapse engine and the underlying transports set a number of properties on
+ each message processed which can be manipulated by the user to modify the
+ runtime behavior of the message flows. In addition, user can set his/her own
+ properties on the message which is very helpful when it comes to managing
+ message flow state and storing scenario specific variables. For an example in
+ some situations a user might want to access a particular value in the request
+ payload while processing a response. This can be easily achieved by setting the
+ required value to a property in the request (in) sequence and then later accessing
+ that property in the response (out) sequence.
+ </p>
+ <p>
+ Property mediator is used to manipulate the properties of a message. This
+ mediator can be used to set and remove property values. When it comes to setting
+ property values, the input could be a constant or a variable value generated
+ by an XPath expression. The syntax for configuring the property mediator is as
+ follows.
+ </p>
+ <div class="xmlConf"><property name="string" [action=set|remove] [type="string"] (value="literal" | expression="xpath") [scope=default|transport|axis2|axis2-client] [pattern="regex" [group="integer"]]>
+ <xml-element/>?
+</property></div>
+ <p>
+ The 'name' attribute specifies the name of the property which needs to be either
+ set or removed while the 'action' attribute specifies the exact action that needs
+ to be carried out by the mediator. If not specified action will default to 'set'.
+ </p>
+ <p>
+ When setting a property value, either the 'value' or the 'expression' attribute
+ must be specified. The 'value' attribute can be used to set a constant as
+ the property value whereas the 'expression' attribute can be used to specify an
+ XPath expression. If an XPath expression is specified, Synapse will evaluate that
+ on the message to determine the value that needs to be assigned to the property.
+ </p>
+ <p>
+ Synapse properties are scoped. Therefore when using this mediator the user should
+ specify the scope at which the property will be set or removed from. If not
+ specified, property mediator will work at the 'default' scope. Properties set in
+ this scope last as long as the transaction (request-response) exists. Properties
+ set on scope 'axis2' has a shorter life span and it's mainly used for passing
+ parameters to the underlying Axis2 engine. Properties set in the 'transport'
+ scope will be treated as transport headers. For an example if it is required to
+ send an HTTP header named 'CustomHeader' with an outgoing request, one may use
+ the property mediator configuration.
+ </p>
+ <div class="xmlConf"><property name="CustomHeader" value="some value" scope="transport" type="type name"/></div>
+ <p>
+ This will force Synapse to send a transport header named 'CustomHeader' along
+ with the outgoing message. Property mediator also supports a scope named
+ 'axis2-client'. Properties set in this scope will be treated as Axis2 client
+ options.
+ </p>
+ <p>
+ When using properties to store user or scenario specific information it is
+ recommended to always use the 'default' scope. Other scopes should not be used
+ for custom development or mediation work since they have the potential to
+ alter the behavior of the underlying Axis2 engine and transports framework.
+ </p>
+ <p>
+ By default property mediator sets all property values as strings. It is possible
+ to set properties in other types by specifying the 'type' attribute. This attribute
+ can accept one of following values.
+ </p>
+ <ul>
+ <li>STRING</li>
+ <li>BOOLEAN</li>
+ <li>DOUBLE</li>
+ <li>FLOAT</li>
+ <li>INTEGER</li>
+ <li>LONG</li>
+ <li>SHORT</li>
+ <li>OM</li>
+ </ul>
+ <p>
+ The type names are case sensitive. Type 'OM' can be used to set XML property
+ values on the message context. This becomes useful when the expression associated
+ with the property mediator evaluates to an XML node during mediation. With the
+ type attribute set to 'OM' the resulting XML will be converted to an AXIOM
+ OMElement before assigning it to a property.
+ </p>
+ <p>
+ It is also possible to use the property mediator to set some static XML content
+ as a property value. To do this specify the static XML content as a child node
+ of the 'property' element instead of using the 'value' attribute.
+ </p>
+ </subsection>
+ <subsection name="Send Mediator" id="Send">
+ <p>
+ Send mediator is used to send requests to endpoints. The same can be used
+ to send response messages back to clients. The send mediator is configured using
+ the following XML syntax.
+ </p>
+ <div class="xmlConf"><send [receive="string"]>
+ (endpointref | endpoint)?
+</send></div>
+ <p>
+ Messages are sent to the endpoint specified as the child of the
+ 'send' element. An optional receiving sequence can be configured using the
+ 'receive' attribute. When specified, response messages from the endpoint will
+ be dispatched to the referred sequence. This makes it easier to implement
+ complex service chaining scenarios, where the response from one service needs
+ to be processed and directed to another service.
+ </p>
+ <p>
+ The send mediator can be configured without any child endpoints. For an example
+ following is a perfectly valid send mediator configuration.
+ </p>
+ <div class="xmlConf"><send/></div>
+ <p>
+ In this case the messages will be sent to an implicit endpoint. If the message
+ is a request from a client, Synapse will lookup the 'To' header of the request and
+ simply forward it to the service addressed by that header. If it is a response
+ from a back-end service, Synapse will simply send it back to the original
+ client who initiated the original message flow.
+ </p>
+ <p>
+ The service invocations done by the send mediator may or may not be
+ synchronous based on the underlying transport used. If the default non-blocking
+ HTTP transport is used, the send mediator will make an asynchronous invocation
+ and release the calling thread as soon as possible. Synapse will asynchronously
+ handle the response from the endpoint while the giving the illusion that Synapse
+ is making blocking service calls.
+ </p>
+ </subsection>
+ </section>
+ <section name="Filter Mediators" id="Filter Mediators">
+ <subsection name="Filter Mediator" id="Filter">
+ <p>
+ Filter mediator adds 'if-else' like semantics to the Synapse configuration language.
+ It can be used to evaluate a condition on a message and take some action
+ based on the outcome. The configuration of the filter mediator takes the
+ following form.
+ </p>
+ <div class="xmlConf"><filter (source="xpath" regex="string") | xpath="xpath">
+ mediator+
+</filter></div>
+ <p>
+ The filter mediator either tests the given XPath expression as a boolean
+ expression, or matches the result of the source XPath expression as a string
+ against the given regular expression. If the condition evaluates to true, the
+ filter mediator will execute the enclosed child mediators.
+ </p>
+ <p>
+ Alternatively one can use the following syntax to configure the filter mediator.
+ </p>
+ <div class="xmlConf"><filter (source="xpath" regex="string") | xpath="xpath">
+ <then [sequence="string"]>
+ mediator+
+ </then>
+ <else [sequence="string"]>
+ mediator+
+ </else>
+</filter></div>
+ <p>
+ In this case too the filter condition is evaluated in the same manner as
+ described above. Messages for which the condition evaluates to true will be
+ mediated through the mediators enclosed by the 'then' element. Failed messages
+ will be mediated through the mediators enclosed by the 'else' element.
+ </p>
+ </subsection>
+ <subsection name="In/Out Mediators" id="InOut">
+ <p>
+ In mediator and Out mediator are used to filter out traffic based on the
+ direction of the messages. As their names imply, In mediator processes only
+ the requests (in messages) while ignoring the responses (out messages). The
+ out mediator does the exact opposite by processing only the responses while
+ ignoring the requests. In many occasions these two mediators are deployed
+ together to create separate flows for requests and responses. The syntax
+ outline for the two mediators is given below.
+ </p>
+ <div class="xmlConf"><in>
+ mediator+
+</in>
+
+<out>
+ mediator+
+</out></div>
+ <p>
+ In mediator will process requests through the child mediators anf the Out
+ mediator will process responses through the child mediators.
+ </p>
+ </subsection>
+ <subsection name="Switch Mediator" id="Switch">
+ <p>
+ Switch mediator provides switch-case semantics in the Synapse configuration
+ language.
+ </p>
+ <div class="xmlConf"><switch source="xpath">
+ <case regex="string">
+ mediator+
+ </case>+
+ <default>
+ mediator+
+ </default>?
+</switch></div>
+ <p>
+ The source XPath is executed on the messages. The resulting value is then
+ tested against the regular expressions defined in each 'case' element. When
+ a matching case is found the message will be mediated through its child
+ mediators. If none of the cases match, the message will handed to the 'default'
+ case (if available).
+ </p>
+ </subsection>
+ </section>
+ <section name="Transformation Mediators" id="TransformationMediators">
+ <subsection name="Header Mediator" id="Header">
+ <p>
+ Header mediator sets or removes a specified header from the current SOAP
+ infoset. The optional 'action' attribute specifies whether the mediator should
+ set or remove the header. If omitted, it defaults to 'set' action.
+ </p>
+ <div class="xmlConf"><header name="qname" (value="literal" | expression="xpath") [action="set"]/>
+<header name="qname" action="remove"/></div>
+ <p>
+ The value of the 'name' attribute must be one of the following aliases or
+ a valid QName with a namespace prefix. In the latter case the namespace prefix
+ must be mapped to a valid namespace URI using the standard 'xmlns' attribute.
+ </p>
+ <ul>
+ <li>To</li>
+ <li>From</li>
+ <li>Action</li>
+ <li>FaultTo</li>
+ <li>ReplyTo</li>
+ <li>RelatesTo</li>
+ </ul>
+ </subsection>
+ <subsection name="MakeFault Mediator" id="MakeFault">
+ <p>
+ MakeFault mediator transforms the current message into a fault message.
+ It should be noted that makeFault mediator does NOT send the message after
+ transforming it. A send mediator needs to be invoked separately to send
+ a fault message created by this mediator.
+ </p>
+ <div class="xmlConf"><makefault [version="soap11|soap12|pox"] [response="true|false"]>
+ <code (value="literal" | expression="xpath")/>
+ <reason (value="literal" | expression="xpath")/>
+ <node>...</node>?
+ <role>...</role>?
+ (<detail expression="xpath"/> | <detail>...</detail>)?
+</makefault></div>
+ <p>
+ The To header of the fault message is set to the 'Fault-To' of the original message
+ if such a header exists on the original message. Depending on the 'version'
+ attribute, the fault message is created as a SOAP 1.1, SOAP 1.2
+ or POX fault. If the optional response attribute value is set as 'true',
+ makefault mediator marks the message as a response. Optional 'node',
+ 'role' and 'detail' sub-elements in the mediator configuration can
+ be used to set the corresponding elements in the resulting SOAP fault.
+ </p>
+ </subsection>
+ <subsection name="Payload Factory Mediator" id="PayloadFactory">
+ <p>
+ Payload-factory mediator creates a new SOAP payload for the message, replacing
+ the existing one. <tt>printf()</tt> style formatting is used to configure the
+ transformation performed by this mediator.
+ </p>
+ <div class="xmlConf"><payloadFactory>
+ <format>"xmlstring"</format>
+ <args>
+ <arg (value="literal" | expression="xpath")/>*
+ </args>
+</payloadFactory></div>
+
+ <p>
+ 'format' sub-element of the mediator configuration specifies the format of the
+ new payload. All $n occurrences in the format will be replaced by the value of
+ the n th argument at runtime. Each argument in the mediator configuration could
+ be a static value or an XPath expression. When an expression is used, value is
+ fetched at runtime by evaluating the provided XPath expression against the
+ existing SOAP message/message context.
+ </p>
+ </subsection>
+ <subsection name="URL Rewrite Mediator" id="URLRewrite">
+ <p>
+ URL Rewrite mediator can be used to modify and transform the URL values
+ available in the message. By default, this mediator takes the 'To' header of the
+ message and apples the provided rewrite rules on it. Alternatively, one can
+ specify a property name in the 'inProperty' attribute, in which case the
+ mediator takes the value of the specified property as the input URL.
+ </p>
+ <p>
+ Similarly the mediator by default sets the transformed URL as the 'To' header of
+ the message and alternatively you can use the 'outProperty' attribute to
+ instruct the mediator to set the resulting URL as a property.
+ </p>
+ <div class="xmlConf"><rewrite [inProperty="string"] [outProperty="string"]>
+ <rewriterule>
+ <condition>
+ ...
+ </condition>?
+ <action [type="append|prepend|replace|remove|set"] [value="string"]
+ [xpath="xpath"] [fragment="protocol|host|port|path|query|ref|user|full"] [regex="regex"]>+
+ </rewriterule>+
+</rewrite></div>
+ <p>
+ The mediator applies URL transformations by evaluating a set of rules on
+ the message. Rules are specified using the 'rewriterule' element. Rules are
+ evaluated in the order in which they are specified. A rule can consist of an
+ optional condition and one or more rewrite actions. If the condition is provided,
+ it is evaluated first and specified rewrite actions are executed only if the
+ condition evaluates to true. If no condition is specified, the provided rewrite
+ actions will be always executed. The condition should be wrapped in a 'condition'
+ element within the 'rewriterule' element. Rewrite actions are specified using
+ 'action' elements.
+ </p>
+ </subsection>
+ <subsection name="XQuery Mediator" id="XQuery">
+ <p>
+ The XQuery mediator can be used to perform an XQuery transformation. 'key'
+ attribute specifies the XQuery transformation, and the optional 'target'
+ attribute specifies the node of the message that should be transformed.
+ This defaults to the first child of the SOAP body of the payload. 'variable'
+ element defines a variable that could be bound to the dynamic context of the
+ XQuery engine in order to access those variables through the XQuery script.
+ </p>
+ <div class="xmlConf"><xquery key="string" [target="xpath"]>
+ <variable name="string" type="string" [key="string"] [expression="xpath"] [value="string"]/>?
+</xquery></div>
+ <p>
+ It is possible to specify just a literal 'value', or an XPath expression
+ over the payload, or even specify a registry key or a registry key
+ combined with an XPath expression that selects the variable. The name of
+ the variable corresponds to the name of variable declaration in the XQuery
+ script. The 'type' of the variable must be a valid type defined by the
+ JSR-000225 (XQJ API).
+ </p>
+ <p>
+ The supported types are:
+ </p>
+ <ul>
+ <li>
+ XQItemType.XQBASETYPE_INT -> INT
+ </li>
+ <li>
+ XQItemType.XQBASETYPE_INTEGER -> INTEGER
+ </li>
+ <li>
+ XQItemType.XQBASETYPE_BOOLEAN -> BOOLEAN
+ </li>
+ <li>
+ XQItemType.XQBASETYPE_BYTE - > BYTE
+ </li>
+ <li>
+ XQItemType.XQBASETYPE_DOUBLE -> DOUBLE
+ </li>
+ <li>
+ XQItemType.XQBASETYPE_SHORT -> SHORT
+ </li>
+ <li>
+ XQItemType.XQBASETYPE_LONG -> LONG
+ </li>
+ <li>
+ XQItemType.XQBASETYPE_FLOAT -> FLOAT
+ </li>
+ <li>
+ XQItemType.XQBASETYPE_STRING -> STRING
+ </li>
+ <li>
+ XQItemType.XQITEMKIND_DOCUMENT -> DOCUMENT
+ </li>
+ <li>
+ XQItemType.XQITEMKIND_DOCUMENT_ELEMENT -> DOCUMENT_ELEMENT
+ </li>
+ <li>
+ XQItemType.XQITEMKIND_ELEMENT -> ELEMENT
+ </li>
+ </ul>
+ </subsection>
+ <subsection name="XSLT Mediator" id="XSLT">
+ <p>
+ XSLT mediator applies the specified XSLT transformation to the selected
+ element of the current message payload. 'source' attribute selects the source
+ element to apply the transformation on. Where not specified, it defaults to the
+ first child of the SOAP body. Output of the transformation replaces the source
+ element when 'target' attribute is not specified. Otherwise, the output is
+ stored in the property specified by the 'target' attribute.
+ </p>
+ <div class="xmlConf"><xslt key="string" [source="xpath"] [target="string"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+ <feature name="string" value="true | false" />*
+ <attribute name="string" value="string" />*
+ <resource location="..." key="..."/>*
+</xslt></div>
+ <p>
+ If the output method specified by the stylesheet is text (i.e. the stylesheet
+ has the <tt><xsl:output method="text"/></tt> directive),
+ then the output of the transformation is wrapped in an element with name
+ <tt>{http://ws.apache.org/commons/ns/payload}text</tt>. Note that when an
+ element with this name is present as the first child of the SOAP body of an
+ outgoing message, JMS and VFS transports automatically unwrap the
+ content and send it out as plain text. XSLT mediator can therefore be used for
+ integration with systems relying on plain text messages.
+ </p>
+ <p>
+ Usage of sub-elements of XSLT mediator configuration is as follows:
+ </p>
+ <ul>
+ <li>
+ property - Stylesheet parameters can be passed into the transformations
+ using 'property' elements.
+ </li>
+ <li>
+ feature - Defines any features which should be explicitly set to the
+ TransformerFactory. For example,
+ <tt>'http://ws.apache.org/ns/synapse/transform/feature/dom'</tt> feature
+ enables DOM based transformations instead of serializing elements into byte
+ streams and/or temporary files. Although enabling this feature could improve
+ performance of the transformation, it might not work for all transformations.
+ </li>
+ <li>
+ attribute - Defines attributes which should be explicitly set on the
+ TransformerFactory.
+ </li>
+ <li>
+ resource - Can be used to resolve XSLT imports and includes from the
+ repository. It works in exactly the same way as the corresponding element in
+ a <proxy> definition.
+ </li>
+ </ul>
+ </subsection>
+ </section>
+ <section name="Extension Mediators" id="ExtensionMediators">
+ <subsection name="Class Mediator" id="Clazz">
+ <p>
+ The class mediator makes it possible to use a custom class as a mediator. The
+ class must implement the org.apache.synapse.api.Mediator interface. If any properties are
+ specified, the corresponding setter methods are invoked on the class,
+ once, during initialization.
+ </p>
+ <div class="xmlConf"><class name="class-name">
+ <property name="string" value="literal">
+ (either literal or XML child)
+ </property>
+</class></div>
+ <p>
+ This mediator creates an instance of a specified class and sets it as a
+ mediator. If any properties are specified, the corresponding setter methods are
+ invoked on the class with the given values, once, during initialization.
+ </p>
+ </subsection>
+ <subsection name="POJO Command Mediator" id="POJOCommand">
+ <p>
+ POJO Command mediator implements the popular Command design pattern and can be
+ used to invoke an object which encapsulates a method call.
+ </p>
+ <div class="xmlConf"><pojoCommand name="class-name">
+ (
+ <property name="string" value="string"/> |
+ <property name="string" context-name="literal" [action=(ReadContext | UpdateContext | ReadAndUpdateContext)]>
+ (either literal or XML child)
+ </property> |
+ <property name="string" expression="xpath" [action=(ReadMessage | UpdateMessage | ReadAndUpdateMessage)]/>
+ )*
+</pojoCommand></div>
+ <p>
+ POJO Command mediator creates an instance of the specified command class,
+ which may implement the org.apache.synapse.Command interface or should have a
+ method with "public void execute()" signature. If any properties are specified,
+ the corresponding setter methods are invoked on the class before each message is
+ executed. It should be noted that a new instance of the POJO Command class is
+ created to process each message processed. After execution of the POJO Command
+ mediator, depending on the 'action' attribute of the property, the new value
+ returned by a call to the corresponding getter method is stored back to the
+ message or to the context. The 'action' attribute may specify whether this
+ behaviour is expected or not via the Read, Update and ReadAndUpdate values.
+ </p>
+ </subsection>
+ <subsection name="Script Mediator" id="Script">
+ <p>
+ Synapse supports mediators implemented in a variety of scripting languages such
+ as JavaScript, Python and Ruby. There are two ways of defining a script mediator,
+ either with the script program statements stored in a separate file which is
+ referenced via the local or remote registry entry, or with the script program
+ statements embedded in-line within the Synapse configuration. A script mediator
+ using a script off the registry (local or remote) is defined as follows:
+ </p>
+ <div class="xmlConf"><script key="string" language="string" [function="script-function-name"]/></div>
+ <p>
+ The property key is the registry key to load the script. The language
+ attribute specifies the scripting language of the script code (e.g. "js"
+ for Javascript, "rb" for ruby, "groovy" for Groovy, "py" for Python..).
+ The function is an optional attribute defining the name of the script
+ function to invoke, if not specified it defaults to a function named
+ 'mediate'. The function is passed a single parameter - which is the
+ Synapse MessageContext. The function may return a boolean, if it does not,
+ then true is assumed, and the script mediator returns this value. An
+ inline script mediator has the script source embedded in the configuration
+ as follows:
+ </p>
+ <div class="xmlConf"><script language="string">...script source code...<script/></div>
+ <p>
+ If the specified script calls a function defined in another script, then the
+ latter script should also be included in the script mediator configuration.
+ It's done using the 'include' sub-element of the mediator configuration. The key
+ attribute of the 'include' element should point to the script which has to be
+ included. The included script could be stored as a local entry or in the remote
+ registry. Script includes are defined as follows:
+ </p>
+ <div class="xmlConf"><script key="string" language="string" [function="script-function-name"]>
+ <include key="string"/>
+</script></div>
+ <p>
+ The execution context environment of the script has access to the Synapse
+ MessageContext predefined in a script variable named 'mc' . An example of
+ an inline mediator using JavaScript/E4X which returns false if the SOAP
+ message body contains an element named 'symbol' which has a value of 'IBM'
+ would be:
+ </p>
+ <div class="xmlConf"><script language="js">mc.getPayloadXML()..symbol != "IBM";<script/></div>
+ <p>
+ Synapse uses the Apache
+ <a href="http://jakarta.apache.org/bsf/">Bean Scripting Framework</a>
+ for the scripting language support, any script language supported by BSF may be
+ used to implement a Synapse mediator.
+ </p>
+ <p>
+ Implementing a mediator with a script language can have advantages over
+ using the built in Synapse mediator types or implementing a custom Java
+ class mediator. Script mediators have all the flexibility of a class
+ mediator with access to the Synapse MessageContext and SynapseEnvironment
+ APIs, and the ease of use and dynamic nature of scripting languages allows
+ rapid development and prototyping of custom mediators. An additional
+ benefit of some scripting languages is that they have very simple and
+ elegant XML manipulation capabilities, for example JavaScript E4X or Ruby
+ REXML, so this makes them well suited for use in the Synapse mediation
+ environment. For both types of script mediator definition the
+ MessageContext passed into the script has additional methods over the
+ standard Synapse MessageContext to enable working with the XML in a way
+ natural to the scripting language. For example when using JavaScript
+ getPayloadXML and setPayloadXML, E4X XML objects, and when using Ruby,
+ REXML documents.
+ </p>
+ <p>
+ The complete list of available methods can be found in the
+ <a href="apidocs/org/apache/synapse/mediators/bsf/ScriptMessageContext.html">
+ ScriptMessageContext Javadoc</a>.
+ </p>
+ </subsection>
+ <subsection name="Spring Mediator" id="Spring">
+ <p>
+ The Spring mediator exposes a spring bean as a mediator. In other terms, it
+ creates an instance of a mediator, which is managed by Spring. This Spring bean
+ must implement org.apache.synapse.api.Mediator interface.
+ </p>
+ <div class="xmlConf"><spring:spring bean="string" key="string" xmlns:spring="http://ws.apache.org/ns/synapse/spring"/></div>
+ <p>
+ 'key' attribute refers to the Spring ApplicationContext/Configuration
+ (i.e. spring configuration XML) used for the bean. This key can be a registry
+ key or local entry key. The bean attribute is used for looking up a Spring bean
+ from the spring Application Context. Therefore, a bean with same name must be in
+ the given spring configuration. In addition to that, that bean must implement
+ the Mediator interface.
+ </p>
+ </subsection>
+ </section>
+ <section name="Advanced Mediators" id="AdvancedMediators">
+ <subsection name="Aggregate Mediator" id="Aggregate">
+ <p>
+ Aggregate mediator implements the Message Aggregator EIP by aggregating the
+ messages or responses for split messages generated using either the clone or
+ iterate mediator.
+ </p>
+ <div class="xmlConf"><aggregate [id="string"]>
+ <correlateOn expression="xpath"/>?
+ <completeCondition [timeout="time-in-seconds"]>
+ <messageCount min="int-min" max="int-max"/>?
+ </completeCondition>?
+ <onComplete expression="xpath" [sequence="sequence-ref"]>
+ (mediator +)?
+ </onComplete>
+</aggregate></div>
+ <p>
+ This mediator can also aggregate messages on the presence of matching elements
+ specified by the correlateOn XPath expression. Aggregate will collect the
+ messages coming into it until the messages collected on the aggregation
+ satisfies the complete condition. The completion condition can specify a minimum
+ or maximum number of messages to be collected, or a timeout value in seconds,
+ after which the aggregation terminates. On completion of the aggregation it will
+ merge all of the collected messages and invoke the onComplete sequence on it.
+ The merged message would be created using the XPath expression specified by the
+ attribute 'expression' on the 'onComplete' element.
+ </p>
+ </subsection>
+ <subsection name="Cache Mediator" id="Cache">
+ <p>
+ Cache mediator is used for simple response message caching in Synapse. When a
+ message reaches the cache mediator, it checks weather an equivalent message is
+ already cached using a hash value.
+ </p>
+ <p>
+ When the cache mediator detects that the message is a cached message, it fetches
+ the cached response and prepares Synapse for sending the response. If a sequence
+ is specified for a cache hit, user can send back the response message within
+ this sequence using a send mediator. If a sequence is not specified, then cached
+ response is sent back to the client.
+ </p>
+ <div class="xmlConf"><cache [id="string"] [hashGenerator="class"] [timeout="seconds"] [scope=(per-host | per-mediator)]
+ collector=(true | false) [maxMessageSize="in-bytes"]>
+ <onCacheHit [sequence="key"]>
+ (mediator)+
+ </onCacheHit>?
+ <implementation type=(memory | disk) maxSize="int"/>
+</cache></div>
+ <p>
+ This mediator will evaluate the hash value of an incoming message as described
+ in the optional hash generator implementation (which should be a class
+ implementing the org.wso2.caching.digest.DigestGenerator interface). The default
+ hash generator is 'org.wso2.caching.digest.DOMHashGenerator'. If the generated
+ hash value has been found in the cache then the cache mediator will execute the
+ onCacheHit sequence which can be specified inline or referenced. The cache
+ mediator must be specified with an 'id' and two instances with this same 'id'
+ that correlates the response message into the cache for the request message
+ hash. The optional 'timeout' specifies the valid duration for cached elements,
+ and the scope defines if mediator instances share a common cache per every host
+ instance, or per every cache mediator pair (i.e. 'id') instance. 'collector'
+ attribute value 'true' specifies that the mediator instance is a response
+ collection instance, and 'false' specifies that its a cache serving instance.
+ The maximum size of a message to be cached could be specified with the optional
+ 'maxMessageSize' attributes in bytes and defaults to unlimited. Finally,
+ 'implementation' element may define if the cache is disk or memory based, and
+ 'maxSize' attribute defines the maximum number of elements to be cached.
+ </p>
+ </subsection>
+ <subsection name="Callout Mediator" id="Callout">
+ <p>
+ Callout mediator performs a blocking external service invocation during
+ mediation. 'serviceURL' and optional 'action' attributes specify the parameters
+ for the external service call. The source element specifies the payload for the
+ request message using an XPath expression; or a registry key. The target element
+ specifies a node, at which the response payload will be attached into the
+ current message, or the name of a key/property using which the response would be
+ attached to the current message context as a property.
+ </p>
+ <div class="xmlConf"><callout serviceURL="string" [action="string"]>
+ <configuration [axis2xml="string"] [repository="string"]/>?
+ <source xpath="expression" | key="string">
+ <target xpath="expression" | key="string"/>
+</callout></div>
+ <p>
+ Since the callout mediator performs a blocking call, it cannot use the default
+ non-blocking http/s transports based on Java NIO, and thus defaults to using the
+ samples/axis2Client/client_repo/conf/axis2.xml as the Axis2 configuration, and
+ samples/axis2Client/client_repo as the client repository unless these are
+ specified otherwise inside the 'configuration' subelement.
+ </p>
+ </subsection>
+ <subsection name="Clone Mediator" id="Clone">
+ <p>
+ Clone mediator can be used to create several clones or copies of a message. This
+ mediator implements the Message Splitter EIP by splitting the message into
+ number of identical messages which will be processed in parallel. They can also
+ be set to process sequentially by setting the value of the optional 'sequential'
+ attribute to 'true'.
+ </p>
+ <div class="xmlConf"><clone [id="string"] [sequential=(true | false)] [continueParent=(true | false)]>
+ <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]>
+ <sequence>
+ (mediator)+
+ </sequence>?
+ <endpoint>
+ endpoint
+ </endpoint>?
+ </target>+
+</clone></div>
+ <p>
+ The original message can be continued or dropped depending on the boolean value
+ of the optional 'continueParent' attribute. Optionally a custom 'To' address
+ and/or a 'Action' may be specified for cloned messages. The optional 'id'
+ attribute can be used to identify the clone mediator which created a particular
+ split message when nested clone mediators are used. This is particularly useful
+ when aggregating responses of messages that were created using nested clone
+ mediators.
+ </p>
+ </subsection>
+ <subsection name="Iterate Mediator" id="Iterate">
+ <p>
+ Iterate mediator splits the message into number of different messages
+ derived from the parent message by finding matching elements for the XPath
+ expression specified. New messages will be created for each matching element and
+ processed in parallel (default behavior) using either the specified sequence or
+ endpoint.
+ </p>
+ <div class="xmlConf"><iterate [id="string"] [continueParent=(true | false)] [preservePayload=(true | false)] [sequential=(true | false)]
+ (attachPath="xpath")? expression="xpath">
+ <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]>
+ <sequence>
+ (mediator)+
+ </sequence>?
+ <endpoint>
+ endpoint
+ </endpoint>?
+ </target>+
+ </iterate></div>
+ <p>
+ Created messages can also be set to process sequentially by setting the optional
+ 'sequential' attribute to 'true'. Parent message can be continued or dropped in
+ the same way as in the clone mediator. The 'preservePayload' attribute specifies
+ if the original message should be used as a template when creating the split
+ messages, and defaults to 'false', in which case the split messages would
+ contain the split elements as the SOAP body. The optional 'id' attribute can be
+ used to identify the iterator which created a particular split message when
+ nested iterate mediators are used. This is particularly useful when aggregating
+ responses of messages that are created using nested iterate mediators.
+ </p>
+ </subsection>
+ <subsection name="Transaction Mediator" id="Transaction">
+ <p>
+ Transaction mediator can provide transaction facility for a set of mediators
+ defined as its child mediators. A transaction mediator with the action "new"
+ indicates the entry point for the transaction. A transaction is marked completed
+ by a transaction mediator with the action "commit". The suspend and resume
+ actions are used to pause a transaction at some point and start it again later.
+ Additionally, the transaction mediator supports three other actions, i.e.
+ use-existing-or-new, fault-if-no-tx, rollback.
+ </p>
+ <div class="xmlConf"><transaction action="new|use-existing-or-new|fault-if-no-tx|commit|rollback|suspend|resume"/></div>
+ <ul>
+ <li>Commit transaction: End the transaction</li>
+ <li>Fault if no transaction: Go to error handler if no transaction</li>
+ <li>Initiate new transaction: Entry point for new transaction</li>
+ <li>Resume transaction: Resume a puased transaction</li>
+ <li>Suspend transaction: Puase a transaction</li>
+ <li>Rollback transaction: Rollback a transaction</li>
+ <li>Use existing or initiate transaction: If a transaction already exists
+ continue it or create a new transaction</li>
+ </ul>
+ </subsection>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/quick_start.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/quick_start.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/quick_start.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/quick_start.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,417 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!--
+ ~ 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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Quick Start Guide</title>
+ </properties>
+ <body>
+ <section name="Apache Synapse Quick Start Guide">
+ <p>
+ Welcome to Apache Synapse quick start guide. This tutorial demonstrates two
+ sample applications covering the fundamental usage scenarios of Synapse, namely
+ message mediation and service mediation. It starts from the absolute begining and
+ walks you through a series of steps while giving a firm grasp on the Synapse
+ messaging model.
+ </p>
+ </section>
+
+ <section name="Pre-requisites">
+ <p>
+ You should have following pre-requisites installed on your system to
+ follow this tutorial.
+ </p>
+ <ul>
+ <li>
+ A Java 2 SE - JDK or JRE of version 1.5.x or higher (JDK 1.6.0_21 recommended)
+ </li>
+ <li>
+ Apache Ant <a href="http://ant.apache.org">http://ant.apache.org</a>
+ </li>
+ </ul>
+ </section>
+
+ <section name="Installing Synapse">
+ <p>
+ Let's start by downloading Apache Synapse. Launch a web browser and navigate to
+ the <a href="">Synapse Downloads</a> page. Download the binary distribution
+ of the latest release. Binary distributions are available in standard zip
+ format and Unix tar ball format.
+ </p>
+ <p>
+ Once downloaded you can install Synapse by simply extracting the archive to
+ a suitable location on your local disk. When extracted, a directory named
+ synapse with the corresponding version number will be created. This directory
+ houses all the libraries, configuration files, scripts and other artifacts
+ used by the Synapse runtime. From now on we will refer to this directory as
+ {SYNAPSE_HOME}. So for an example {SYNAPSE_HOME}/bin refers to the subdirectory
+ named 'bin' which is generally available in the Synapse installation.
+ </p>
+ </section>
+
+ <section name="Running the Axis2 Server">
+ <p>
+ Samples described in this tutorial involve routing messages to a Web Service
+ through the Synapse ESB. In real world applications, these Web Services could be
+ hosted in a web server in your organization, or practiacally anywhere in the
+ Internet. In this tutorial we will be using a sample Web Service that ships with
+ Synapse and we will deploy it in the sample Axis2 server that comes bundled with
+ Synapse.
+ </p>
+ <p>
+ To deploy the sample service in the Axis2 server, go to
+ {SYNAPSE_HOME}/samples/axis2Server/src/SimpleStockQuoteService directory and run
+ 'ant'. You will see an output similar to the following as the service is built
+ and deployed to the sample Axis2 server.
+ </p>
+ <div class="consoleOutput">user@domain:/opt/synapse-2.0.0/samples/axis2Server/src/SimpleStockQuoteService$ ant
+Buildfile: build.xml
+
+clean:
+
+init:
+[mkdir] Created dir: /opt/synapse-2.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp
+[mkdir] Created dir: /opt/synapse-2.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
+[mkdir] Created dir: /opt/synapse-2.0.0/samples/axis2Server/repository/services
+
+compile-all:
+[javac] Compiling 9 source files to /opt/synapse-2.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
+
+build-service:
+[mkdir] Created dir: /opt/synapse-2.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
+[mkdir] Created dir: /opt/synapse-2.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+[copy] Copying 1 file to /opt/synapse-2.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
+[copy] Copying 9 files to /opt/synapse-2.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
+[jar] Building jar: /opt/synapse-2.0.0/samples/axis2Server/repository/services/SimpleStockQuoteService.aar
+
+BUILD SUCCESSFUL
+Total time: 1 second</div>
+ <p>
+ Now go to {SYNAPSE_HOME}/samples/axis2Server directory and start the sample server
+ by executing the following command.
+ </p>
+ <div class="command">
+ Linux / Unix: . axis2server.sh<br/>
+ Windows: axis2server.bat
+ </div>
+ <p>
+ This will start the Axis2 server on HTTP port 9000. You can see the WSDL of the
+ sample service by launching your web browser and navigating to the URL
+ http://localhost:9000/services/SimpleStockQuoteService?wsdl.
+ </p>
+ </section>
+
+ <section name="Message Mediation">
+ <p>
+ Now we are all set to try our first scenario with Synapse. We will be starting
+ Synapse using the sample configuration found in synapse_sample_0.xml file which
+ resides in {SYNAPSE_HOME}/repository/conf/sample directory. This configuration
+ enables Synapse to log all the messages passing through the service bus:
+ </p>
+ <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <sequence name="main">
+ <log level="full"/>
+ <send/>
+ </sequence>
+</definitions></div>
+ <p>
+ To start the ESB with the above configuration go the {SYNAPSE_HOME}/bin directory
+ and execute the following command.
+ </p>
+ <div class="command">
+ Linux / Unix: . synapse.sh -sample 0<br/>
+ Windows: synapse.bat -sample 0
+ </div>
+ <p>
+ Following messages will be displayed on the console as Synapse boots up with the
+ above configuration.
+ </p>
+ <div class="consoleOutput">Starting Synapse/Java ...
+Using SYNAPSE_HOME: /opt/synapse-2.0.0
+Using JAVA_HOME: /opt/jdk1.6.0_16
+Using SYNAPSE_XML: /opt/synapse-2.0.0/repository/conf/sample/synapse_sample_0.xml
+2010-11-26 01:33:03,651 [-] [main] INFO SynapseServer Starting Apache Synapse...
+2010-11-26 01:33:03,683 [-] [main] INFO SynapseControllerFactory Using Synapse home : /opt/synapse-2.0.0
+2010-11-26 01:33:03,683 [-] [main] INFO SynapseControllerFactory Using Axis2 repository : /opt/synapse-2.0.0/repository
+2010-11-26 01:33:03,683 [-] [main] INFO SynapseControllerFactory Using axis2.xml location : /opt/synapse-2.0.0/repository/conf/axis2.xml
+2010-11-26 01:33:03,683 [-] [main] INFO SynapseControllerFactory Using synapse.xml location : /opt/synapse-2.0.0/repository/conf/sample/synapse_sample_0.xml
+2010-11-26 01:33:03,683 [-] [main] INFO SynapseControllerFactory Using server name : localhost
+2010-11-26 01:33:03,698 [-] [main] INFO SynapseControllerFactory The timeout handler will run every : 15s
+2010-11-26 01:33:03,808 [-] [main] INFO Axis2SynapseController Initializing Synapse at : Fri Nov 26 01:33:03 IST 2010
+2010-11-26 01:33:04,536 [-] [main] ERROR SandeshaModule Could not load module policies. Using default values.
+2010-11-26 01:33:04,560 [-] [main] INFO HttpCoreNIOSSLSender Loading Identity Keystore from : lib/identity.jks
+2010-11-26 01:33:04,576 [-] [main] INFO HttpCoreNIOSSLSender Loading Trust Keystore from : lib/trust.jks
+2010-11-26 01:33:04,668 [-] [main] INFO HttpCoreNIOSender HTTPS Sender starting
+2010-11-26 01:33:04,674 [-] [main] INFO HttpCoreNIOSender HTTP Sender starting
+2010-11-26 01:33:04,675 [-] [main] INFO JMSSender JMS Sender started
+2010-11-26 01:33:04,677 [-] [main] INFO JMSSender JMS Transport Sender initialized...
+2010-11-26 01:33:04,681 [-] [main] INFO VFSTransportSender VFS Sender started
+2010-11-26 01:33:04,828 [-] [main] WARN JmxAdapter Using unsecured JMX remote access!
+2010-11-26 01:33:04,959 [-] [main] INFO HttpCoreNIOSSLListener Loading Identity Keystore from : lib/identity.jks
+2010-11-26 01:33:04,961 [-] [main] INFO HttpCoreNIOSSLListener Loading Trust Keystore from : lib/trust.jks
+2010-11-26 01:33:04,976 [-] [main] INFO Axis2SynapseController Loading mediator extensions...
+2010-11-26 01:33:05,013 [-] [main] INFO XMLConfigurationBuilder Generating the Synapse configuration model by parsing the XML configuration
+2010-11-26 01:33:05,114 [-] [main] INFO SynapseConfigurationBuilder Loaded Synapse configuration from : /opt/synapse-2.0.0/repository/conf/sample/synapse_sample_0.xml
+2010-11-26 01:33:05,158 [-] [main] INFO Axis2SynapseController Deploying the Synapse service...
+2010-11-26 01:33:05,175 [-] [main] INFO Axis2SynapseController Deploying Proxy services...
+2010-11-26 01:33:05,175 [-] [main] INFO Axis2SynapseController Deploying EventSources...
+2010-11-26 01:33:05,190 [-] [main] INFO MailTransportListener MAILTO Listener started
+2010-11-26 01:33:05,212 [-] [main] INFO HttpCoreNIOListener HTTPS Listener started on port : 8243
+2010-11-26 01:33:05,215 [-] [main] INFO HttpCoreNIOListener HTTP Listener started on port : 8280
+2010-11-26 01:33:05,215 [-] [main] INFO VFSTransportListener VFS Listener started
+2010-11-26 01:33:05,215 [-] [main] INFO Axis2SynapseController Management using JMX available via: service:jmx:rmi:///jndi/rmi://hiranya.wso2.com:1099/synapse
+2010-11-26 01:33:05,215 [-] [main] INFO ServerManager Server ready for processing...
+2010-11-26 01:33:05,216 [-] [main] INFO SynapseServer Apache Synapse started successfully</div>
+ <p>
+ Note that by default Synapse listens for HTTP requests on port 8280.
+ </p>
+ <subsection name="Executing the Sample Client">
+ <p>
+ Now we have a Web Service hosted in Axis2 and a Synapse ESB instance which
+ is configured to log and route messages. All that is left is to send some requests
+ to Synapse and see the magic happen. Synapse comes bundled with a sample
+ Web Service client that can be used to send different kinds of requests. Go to
+ {SYNAPSE_HOME}/samples/axis2Client directory and execute the following command
+ to send a request to Synapse.
+ </p>
+ <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dmode=quote -Dsymbol=IBM</div>
+ <p>
+ You should get the following output on the conosle.
+ </p>
+ <div class="consoleOutput">Buildfile: build.xml
+
+init:
+ [mkdir] Created dir: /opt/synapse-2.0.0/samples/axis2Client/target/classes
+
+compile:
+ [javac] Compiling 22 source files to /opt/synapse-2.0.0/samples/axis2Client/target/classes
+ [javac] Note: /opt/synapse-2.0.0/samples/axis2Client/src/samples/userguide/PWCallback.java uses or overrides a deprecated API.
+ [javac] Note: Recompile with -Xlint:deprecation for details.
+ [javac] Note: /opt/synapse-2.0.0/samples/axis2Client/src/samples/userguide/LoadbalanceFailoverClient.java uses unchecked or unsafe operations.
+ [javac] Note: Recompile with -Xlint:unchecked for details.
+
+stockquote:
+ [java] 2010-11-26 01:35:16,414 [-] [main] ERROR SandeshaModule Could not load module policies. Using default values.
+ [java] 2010-11-26 01:35:16,485 [-] [main] INFO MailTransportSender MAILTO Sender started
+ [java] 2010-11-26 01:35:16,496 [-] [main] INFO JMSSender JMS Sender started
+ [java] 2010-11-26 01:35:16,497 [-] [main] INFO JMSSender JMS Transport Sender initialized...
+ [java] Standard :: Stock price = $99.14593325984416
+
+BUILD SUCCESSFUL
+Total time: 5 seconds</div>
+ <p>
+ This sends a stock quote request for the symbol 'IBM' with the transport URL set
+ to http://localhost:8280 (Synapse) and the WS-Addressing EPR set to
+ http://localhost:9000/services/SimpleStockQuoteService (Axis2). Synapse first
+ logs the message and then forwards it to the URL given in the WS-Addressing
+ headers. The actual message sent by the client is as follows.
+ </p>
+ <div class="consoleOutput">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/services/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">
+ <m0:request>
+ <m0:symbol>IBM</m0:symbol>
+ </m0:request>
+ </m0:getQuote>
+ </soapenv:Body>
+ </soapenv:Envelope>0</div>
+ <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 file and setting "log4j.category.org.apache.synapse"
+ as "DEBUG" instead of INFO, you will see even more information as follows after
+ a restart and on replay of the above scenario.
+ </p>
+ <div class="consoleOutput">2010-11-26 01:39:42,958 [-] [HttpServerWorker-1] DEBUG SynapseMessageReceiver Synapse received a new message for message mediation...
+2010-11-26 01:39:42,959 [-] [HttpServerWorker-1] DEBUG SynapseMessageReceiver Received To: http://localhost:9000/services/SimpleStockQuoteService
+2010-11-26 01:39:42,959 [-] [HttpServerWorker-1] DEBUG SynapseMessageReceiver SOAPAction: urn:getQuote
+2010-11-26 01:39:42,959 [-] [HttpServerWorker-1] DEBUG SynapseMessageReceiver WSA-Action: urn:getQuote
+2010-11-26 01:39:42,960 [-] [HttpServerWorker-1] DEBUG Axis2SynapseEnvironment Injecting MessageContext
+2010-11-26 01:39:42,960 [-] [HttpServerWorker-1] DEBUG Axis2SynapseEnvironment Using Main Sequence for injected message
+2010-11-26 01:39:42,961 [-] [HttpServerWorker-1] DEBUG SequenceMediator Start : Sequence <main>
+2010-11-26 01:39:42,961 [-] [HttpServerWorker-1] DEBUG SequenceMediator Sequence <SequenceMediator> :: mediate()
+2010-11-26 01:39:42,961 [-] [HttpServerWorker-1] DEBUG LogMediator Start : Log mediator
+2010-11-26 01:39:42,989 [-] [HttpServerWorker-1] INFO LogMediator To: http://localhost:9000/services/SimpleStockQuoteService, WSAction: urn:getQuote, SOAPAction: urn:getQuote, ReplyTo: http://www.w3.org/2005/08/addressing/anonymous, MessageID: urn:uuid:881AF81981B97048961290715782743, Direction: request, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"><wsa:To>http://localhost:9000/services/SimpleStockQuoteService</wsa:To><wsa:MessageID>urn:uuid:881AF81981B97048961290715782743</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action></soapenv:Header><soapenv:Body><m0:getQuote xmlns:m0="http://services.samples"><m0:request><m0:symbol>IBM</m0:symbol></m0:request></m0:getQuote></soapenv:Body></soapenv:Envelope>
+2010-11-26 01:39:42,990 [-] [HttpServerWorker-1] DEBUG LogMediator End : Log mediator
+2010-11-26 01:39:42,990 [-] [HttpServerWorker-1] DEBUG SendMediator Start : Send mediator
+2010-11-26 01:39:42,990 [-] [HttpServerWorker-1] DEBUG SendMediator Sending request message using implicit message properties..
+Sending To: http://localhost:9000/services/SimpleStockQuoteService
+SOAPAction: urn:getQuote
+2010-11-26 01:39:42,993 [-] [HttpServerWorker-1] DEBUG Axis2FlexibleMEPClient Sending [add = false] [sec = false] [rm = false] [to=Address: http://localhost:9000/services/SimpleStockQuoteService]
+2010-11-26 01:39:42,997 [-] [HttpServerWorker-1] DEBUG Axis2FlexibleMEPClient Message [Original Request Message ID : urn:uuid:881AF81981B97048961290715782743] [New Cloned Request Message ID : urn:uuid:5e919190-98a9-4441-8bb0-d09271c2758a]
+2010-11-26 01:39:43,003 [-] [HttpServerWorker-1] DEBUG SynapsePropertiesLoader Retrieving synapse properties from the cache
+2010-11-26 01:39:43,003 [-] [HttpServerWorker-1] DEBUG MiscellaneousUtil The name with 'synapse.global_timeout_interval' cannot be found. Using default value : 86400000
+2010-11-26 01:39:43,004 [-] [HttpServerWorker-1] INFO TimeoutHandler This engine will expire all callbacks after : 86400 seconds, irrespective of the timeout action, after the specified or optional timeout
+2010-11-26 01:39:43,004 [-] [HttpServerWorker-1] DEBUG SynapsePropertiesLoader Retrieving synapse properties from the cache
+2010-11-26 01:39:43,004 [-] [HttpServerWorker-1] DEBUG MiscellaneousUtil The name with 'synapse.timeout_handler_interval' cannot be found. Using default value : 15000
+2010-11-26 01:39:43,039 [-] [HttpServerWorker-1] DEBUG SynapseCallbackReceiver Callback added. Total callbacks waiting for : 1
+2010-11-26 01:39:43,144 [-] [HttpServerWorker-1] DEBUG SendMediator End : Send mediator
+2010-11-26 01:39:43,145 [-] [HttpServerWorker-1] DEBUG SequenceMediator End : Sequence <main>
+2010-11-26 01:39:43,271 [-] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver Callback removed for request message id : urn:uuid:5e919190-98a9-4441-8bb0-d09271c2758a. Pending callbacks count : 0
+2010-11-26 01:39:43,271 [-] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver Synapse received an asynchronous response message
+2010-11-26 01:39:43,271 [-] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver Received To: null
+2010-11-26 01:39:43,271 [-] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver SOAPAction:
+2010-11-26 01:39:43,271 [-] [HttpClientWorker-1] DEBUG SynapseCallbackReceiver WSA-Action:
+2010-11-26 01:39:43,272 [-] [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"><ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse"><ax21:change>-2.533440547346707</ax21:change><ax21:earnings>12.865664096815566</ax21:earnings><ax21:high>-62.37116432061533</ax21:high><ax21:last>63.140427676860845</ax21:last><ax21:lastTradeTimestamp>Fri Nov 26 01:39:43 IST 2010</ax21:lastTradeTimestamp><ax21:low>65.32586424659065</ax21:low><ax21:marketCap>3.6215661345786005E7</ax21:marketCap><ax21:name>IBM Company</ax21:name><ax21:open>64.94029146457328</ax21:open><ax21:peRatio>23.84144924463005</ax21:peRatio><ax21:percentageChange>-3.6037604984655096&l
t;/ax21:percentageChange><ax21:prevClose>70.29991444840613</ax21:prevClose><ax21:symbol>IBM</ax21:symbol><ax21:volume>9723</ax21:volume></ns:return></ns:getQuoteResponse></soapenv:Body></soapenv:Envelope>
+2010-11-26 01:39:43,274 [-] [HttpClientWorker-1] DEBUG Axis2SynapseEnvironment Injecting MessageContext
+2010-11-26 01:39:43,274 [-] [HttpClientWorker-1] DEBUG Axis2SynapseEnvironment Using Main Sequence for injected message
+2010-11-26 01:39:43,274 [-] [HttpClientWorker-1] DEBUG SequenceMediator Start : Sequence <main>
+2010-11-26 01:39:43,275 [-] [HttpClientWorker-1] DEBUG SequenceMediator Sequence <SequenceMediator> :: mediate()
+2010-11-26 01:39:43,275 [-] [HttpClientWorker-1] DEBUG LogMediator Start : Log mediator
+2010-11-26 01:39:43,275 [-] [HttpClientWorker-1] INFO LogMediator To: http://www.w3.org/2005/08/addressing/anonymous, WSAction: , SOAPAction: , ReplyTo: http://www.w3.org/2005/08/addressing/anonymous, MessageID: urn:uuid:5e919190-98a9-4441-8bb0-d09271c2758a, 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"><ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse"><ax21:change>-2.533440547346707</ax21:change><ax21:earnings>12.865664096815566</ax21:earnings><ax21:high>-62.37116432061533</ax21:high><ax21:last>63.140427676860845</ax21:last><ax21:lastTradeTimestamp>Fri Nov 26 01:39:43 IST 2010</ax21:lastTradeTimestamp><ax21:low>65.32586424659
065</ax21:low><ax21:marketCap>3.6215661345786005E7</ax21:marketCap><ax21:name>IBM Company</ax21:name><ax21:open>64.94029146457328</ax21:open><ax21:peRatio>23.84144924463005</ax21:peRatio><ax21:percentageChange>-3.6037604984655096</ax21:percentageChange><ax21:prevClose>70.29991444840613</ax21:prevClose><ax21:symbol>IBM</ax21:symbol><ax21:volume>9723</ax21:volume></ns:return></ns:getQuoteResponse></soapenv:Body></soapenv:Envelope>
+2010-11-26 01:39:43,275 [-] [HttpClientWorker-1] DEBUG LogMediator End : Log mediator
+2010-11-26 01:39:43,275 [-] [HttpClientWorker-1] DEBUG SendMediator Start : Send mediator
+2010-11-26 01:39:43,275 [-] [HttpClientWorker-1] DEBUG SendMediator Sending response message using implicit message properties..
+Sending To: http://www.w3.org/2005/08/addressing/anonymous
+SOAPAction:
+2010-11-26 01:39:43,282 [-] [HttpClientWorker-1] DEBUG SendMediator End : Send mediator
+2010-11-26 01:39:43,282 [-] [HttpClientWorker-1] DEBUG SequenceMediator End : Sequence <main></div>
+ <p>
+ And with that you have successfully completed the first part of this guide. Now let's
+ look at the next scenario, service mediation with proxy services.
+ </p>
+ </subsection>
+ </section>
+ <section name="Service Mediation (Proxy Services)">
+ <p>
+ As the name implies, a proxy service acts as an intermediary 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 setup (such
+ as WS-Security, WS-Reliable Messaging) than the real service. Proxy services
+ are capable of mediating requests before they are delivered to the actual
+ endpoint. Similarly responses from the actual service can be mediated before
+ they are sent back to the client.
+ </p>
+ <p>
+ Clients can send proxy service requests directly to Synapse. From the client's
+ perspective, proxy services are simply Web Services hosted on Synapse. They can
+ append the '?wsdl' suffix to the proxy service endpoints to get the WSDLs of these
+ virtual services. But in the Synapse configuration, service requests can be handled
+ in anyway you like. Most obvious thing would be to do some processing on the
+ message and send it to the actual service, which could be running on a different host.
+ But it is not necessary to always send the messages to an actual service. You may
+ list any combination of tasks to be performed on the messages received by
+ the proxy service and terminate the flow or send some response back to the
+ client even without sending it to any service.
+ </p>
+ <p>
+ 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
+ just run the scenario straightaway. This scenario also requires the same stock
+ quote service we used in the previous example. So have it deployed in Axis2 and make
+ sure Axis2 server is up and running.
+ </p>
+ <p>
+ We are going to start Synapse with a configuration which contains a proxy service.
+ The configuration in synapse_sample_150.xml file in repository/conf/sample directory
+ matches well with the scope of this tutorial.
+ </p>
+ <div class="xmlConf"><definitions xmlns="http://synapse.apache.org/ns/2010/04/configuraiton">
+ <proxy name="StockQuoteProxy">
+ <target>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ <outSequence>
+ <send/>
+ </outSequence>
+ </target>
+ <publishWSDL uri="file:repository/conf/sample/resources/proxy/sample_proxy_1.wsdl"/>
+ </proxy>
+</definitions></div>
+ <p>
+ The above configuration exposes a proxy service named StockQuoteProxy
+ and specifies an endpoint
+ (http://localhost:9000/services/SimpleStockQuoteService) as the target for the
+ proxy service. Therefore, messages coming to the proxy service will be
+ directed to the address http://localhost:9000/services/SimpleStockQuoteService
+ specified in the endpoint. There is also an out sequence for the proxy
+ service, which will be executed 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.
+ </p>
+ <div class="command">
+ Linux / Unix: . synapse.sh -sample 150<br/>
+ Windows: synapse.bat -sample 150
+ </div>
+ <p>
+ Synapse will display a set of messages as it boots up just like in the previous
+ section describing the start-up 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 URL
+ http://localhost:8280/services/StockQuoteProxy?wsdl. You will see the
+ sample_proxy_1.wsdl specified in the configuration but containing the
+ correct EPRs for the service over HTTP/S.
+ </p>
+ <subsection name="Executing the Sample Client">
+ <p>
+ Now we can invoke the proxy service by sending a request from our sample Axis2
+ client. Go to the {SYNAPSE_HOME}/samples/axis2Client directory and run the
+ following command.
+ </p>
+ <div class="command">ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dmode=quote -Dsymbol=IBM</div>
+ <p>
+ The above command sends a stock quote request directly to the provided
+ transport endpoint at http://localhost:8280/services/StockQuoteProxy. The
+ proxy service will forward the message to the Axis2 server and route the
+ response from Axis2 back to the client. You will see the response from the
+ server displayed on the console as follows:
+ </p>
+ <div class="consoleOutput">Standard :: Stock price = $165.32687331383468</div>
+ </subsection>
+ <subsection name="More on Proxy Services">
+ <p>
+ Proxy services are among the most powerful functional components of Apache
+ Synapse. They can be used to perform transport switching, message format
+ switching and lot more. This quick start tutorial only covers the simple
+ usecases of proxy services. Please refer samples #150 and above in the
+ Synapse samples catalog, for in depth coverage on more advanced use cases.
+ </p>
+ </subsection>
+ </section>
+ <section name="Conclusion">
+ <p>
+ This brings the Synapse quick start guide to an end. Now it is time to go
+ deeper and discover the advanced features of Synapse. You can browse through
+ the array of samples for your interested areas. If you have any issue regarding
+ Synapse as a user, feel free write to the Synapse user mailing list
+ (<a href="http://synapse.apache.org/mail-lists.html">http://synapse.apache.org/mail-lists.html</a>).
+ </p>
+ </section>
+ </body>
+</document>
\ No newline at end of file