You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@synapse.apache.org by sa...@apache.org on 2006/01/09 09:42:41 UTC
svn commit: r367247 - in /incubator/synapse/trunk/java/xdocs:
extension_processor_writing.html userguide.html
Author: saminda
Date: Mon Jan 9 00:42:34 2006
New Revision: 367247
URL: http://svn.apache.org/viewcvs?rev=367247&view=rev
Log:
More imporve docs. Thanks Hasmin
Modified:
incubator/synapse/trunk/java/xdocs/extension_processor_writing.html
incubator/synapse/trunk/java/xdocs/userguide.html
Modified: incubator/synapse/trunk/java/xdocs/extension_processor_writing.html
URL: http://svn.apache.org/viewcvs/incubator/synapse/trunk/java/xdocs/extension_processor_writing.html?rev=367247&r1=367246&r2=367247&view=diff
==============================================================================
--- incubator/synapse/trunk/java/xdocs/extension_processor_writing.html (original)
+++ incubator/synapse/trunk/java/xdocs/extension_processor_writing.html Mon Jan 9 00:42:34 2006
@@ -1,189 +1,192 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
+<html>
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>Writing Processors</title>
- <meta name="generator" content="amaya 8.5, see http://www.w3.org/Amaya/" />
+ <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/"
+ />
</head>
<body>
-<p></p>
-
-<H1>Writing a Processor</H1>
-
-<p>This section of the guide covers the aspect of SPI.</p>
-
-<p>There are two types of Processors exist in Synapse, namely,
-
-<ol><li>Node Processors</li>
-<li>Leaf Processors</li></ol>
-
-</p>
+<h1>Writing a Processor</h1>
-<p>
-Node processors can contain sub-processors in its processor map. Ex: RegexProcessor, XpathProcessor etc.
+<p>This section of the guide covers aspects of SPI.</p>
-Leaf Processors do not contain any sub-processors and their soul purpose is to contain configuration infromation. Ex: AddressinInProcessor
-
-Core of Synapse contain Group and Referencing Processors, Rule Processors, Built-in Processors and User Mediator Type Processors. Apart from prior, Synapse consider all other processors as extensions. Ex: SpringMediator etc. As mentioned in Userguide every element in synapse.xml maps to a Processor. Every Processor has its ProcessorConfigurator.
-
-ProcessorConfigurator is the one who decide whether the corresponding Processor is a Node/Leaf Processor.
-
-So any Processor that has written to Synapse should come as âextensionsâ and should go under the SVN folder âextensionsâ.
-</p>
+<p>There are two types of Processors in Synapse: </p>
+<ol>
+ <li>Node Processors
+ <p>These can contain sub-processors in its processor map. Ex:
+ RegexProcessor, XpathProcessor etc.</p>
+ </li>
+ <li>Leaf Processors
+ <p>This does not contain any sub-processors. Their soul purpose is to
+ contain configuration infromation. Ex: AddressinInProcessor Core of
+ Synapse contain Group and Referencing Processors, Rule Processors,
+ Built-in Processors and User Mediator Type Processors.</p>
+ </li>
+</ol>
+
+<p> Apart from the above, Synapse considers all other processors as
+extensions. Ex: SpringMediator etc. As mentioned in the Userguide every
+element in synapse.xml maps to a Processor. Every Processor has its
+ProcessorConfigurator. ProcessorConfigurator is the one which decides whether
+the corresponding Processor is a Node or Leaf Processor. So any Processor
+that has been written to Synapse should come as a extension and should go
+under the SVN folder "extensions". </p>
<h2>Writing a Node Processor</h2>
-<p>
-Following XML shows the semantics of a Node Processor. </p>
-<pre>
-<foo attr=âvalueâ>
+
+<p>Following XML shows the semantics of a Node Processor.</p>
+<pre><foo attr="value">
<bar/>
<car/>
</foo>
-</pre>
-<p>
-<foo/> should map to FooProcessor which is a Node and there should be corresponding FooProcessorConfiguratator. So FooProcessor should contain a map to hold down the other Processors coming under it (BarProcessor and CarProcessor, these will be explain momentarly).
-
-To be a Node, FooProcessorConfigurator should extend from abstract AbstractListProcessorConfigurator.
-
-FooProcessorConfigurator contains all the configuration information of the Processor. It will hold the QName of element. All elements comes under the namespace of http://ws.apache.org/ns/synapse. If there are other attributes pertaining to the elements they should also come under the prior namespace and it should be define in the ProcesssorConfigurator.
+</pre>
-Ultimately you will have following code. </p>
+<p><foo/> should map to FooProcessor which is a Node and there should
+be corresponding FooProcessorConfiguratator. So FooProcessor should contain a
+map to hold down the other Processors coming under it (BarProcessor and
+CarProcessor, these will be explained later on). To be a Node,
+FooProcessorConfigurator should extend from abstract
+AbstractListProcessorConfigurator. FooProcessorConfigurator contains all the
+configuration information of the Processor. It will hold the QName of
+element. All elements comes under the namespace of
+http://ws.apache.org/ns/synapse. If there are other attributes pertaining to
+the elements they should also come under the prior namespace and it should be
+defined in the ProcesssorConfigurator. Ultimately you will have following
+code.</p>
<pre><source>
public class FooProcessorConfigurator extends AbstractListProcessorConfigurator {
private static final String FOO = "foo";
private static final QName FOO_Q = new QN'ame (http://ws.apache.org/ns/synapse , FOO);
private static final QName ATTR = new QName("attr");
-
+
...
}</source></pre>
-<p>
-Now you have to implement the following methods,</p>
-<pre>
-public Processor createProcessor(SynapseEnvironment se, OMElement el);public QName getTagQName();</pre><p></p>
-<pre>
-public Processor createProcessor(SynapseEnvironment se, OMElement el),</pre> <p>will deal with the FooProcessor creation. There's a specific way to full this method, so let's have a look at it.
+<p>Now you have to implement the following methods,</p>
+<pre>public Processor createProcessor(SynapseEnvironment se, OMElement el);public QName getTagQName();</pre>
+
+<p></p>
+<pre>public Processor createProcessor(SynapseEnvironment se, OMElement el),</pre>
+<p>This will deal with the FooProcessor creation. The following is a specific
+way to write this method</p>
<pre><source>
public class FooProcessorConfigurator extends AbstractListProcessorConfigurator {
...
public Processor createProcessor(SynapseEnvironment se, OMElement el) {
- FooProcessor fooProcessor = new FooProcessor();
- super.addChildrenAndSetName(se, el, fooProcessor);
+ FooProcessor fooProcessor = new FooProcessor();
+ super.addChildrenAndSetName(se, el, fooProcessor);
- OMAttribute attr= el.getAttribute(ATTR);
- if (patt == null) {
- throw new SynapseException(FOO + " must have "
- + ATTR+ " attribute: " + el.toString());
- }
-
- fooProcessor.setAttr(attr.getAttributeValue());
- return fooProcessor;
- }
-
- public QName getTagQName() {
- return FOO_Q;
- }
+ OMAttribute attr= el.getAttribute(ATTR);
+ if (patt == null) {
+ throw new SynapseException(FOO + " must have "
+ + ATTR+ " attribute: " + el.toString());
+ }
+
+ fooProcessor.setAttr(attr.getAttributeValue());
+ return fooProcessor;
+ }
+
+ public QName getTagQName() {
+ return FOO_Q;
+ }
} </source></pre>
-<p>
-Now lets look at the FooProcessor implementation. Remember it's a Node, and it should contain a place to hold the value of âattrâ.
-As this is a Node, it should extend from ListProcessor.</p>
+<p>Now lets look at the FooProcessor implementation. Remember it's a Node,
+and it should contain a place to hold the value of "attr". As this is a Node,
+it should extend from ListProcessor.</p>
<pre><source>
public class RegexProcessor extends ListProcessor {
-
- private Log log = LogFactory.getLog(getClass());
+
+ private Log log = LogFactory.getLog(getClass());
- private String attr = null;
+ private String attr = null;
- public void setAttr(String attr) {
- this.attr = attr;
- }
+ public void setAttr(String attr) {
+ this.attr = attr;
+ }
- public String getAttr() {
- return this.attr;
- }
+ public String getAttr() {
+ return this.attr;
+ }
-
- public boolean process(SynapseEnvironment se, SynapseMessage smc) {
+
+ public boolean process(SynapseEnvironment se, SynapseMessage smc) {
// Processing logic goes here
- // there be any processing condition, at the you should call
- return super.process(se, smc);
- // or
- return true;
- }
+ // there be any processing condition, at the you should call
+ return super.process(se, smc);
+ // or
+ return true;
+ }
}</source></pre>
-<pre>
-public boolean process(SynapseEnvironment se, SynapseMessage smc) </pre> <p> handle the processing logic. So there be any condition, and if the logic is âtrueâ call âsuper.process(se, smc)â. If the processing logic is fault through make sure that you will call âreturn tureâ.
+<pre>public boolean process(SynapseEnvironment se, SynapseMessage smc) </pre>
-So writing a extension is as easy as prior. </p>
+<p>handle the processing logic. So there be any condition, and if the logic
+is "true" call "super.process(se, smc)" . If the processing logic is fault
+through make sure that you will call "return true". So writing a extension is
+as easy as prior. </p>
<h2>Writing a Leaf Processor</h2>
-<p><bar/> is leaf element and it will map to a Leaf Node. So let the mapping be BarProcessor and their should be the corresponding BarProcessorConfigurator.
-
-So the symetics of BarProcessorConfigurator as follows,</p>
-
+<p><bar/> is leaf element and it will map to a Leaf Node. So let the
+mapping be BarProcessor and there should be the corresponding
+BarProcessorConfigurator. So the symantics of BarProcessorConfigurator is as
+follows,</p>
<pre><source>
public class BarProcessorConfigurator extends AbstractProcessorConfigurator {
- private static final QName BAR_Q = new QName(http://ws.apache.org/ns/synapse,"bar");
+ private static final QName BAR_Q = new QName(http://ws.apache.org/ns/synapse,"bar");
- public QName getTagQName() {
- return BAR_Q;
- }
+ public QName getTagQName() {
+ return BAR_Q;
+ }
- public Processor createProcessor(SynapseEnvironment se, OMElement el) {
- BarProcessor barProcessor = new BarProcessor();
- super.setNameOnProcessor(se,el,barProcessor);
- return barProcessor;
- }
+ public Processor createProcessor(SynapseEnvironment se, OMElement el) {
+ BarProcessor barProcessor = new BarProcessor();
+ super.setNameOnProcessor(se,el,barProcessor);
+ return barProcessor;
+ }
} </source></pre>
-<p>
-If there are attributes, let them be handle as shown in âWriting a Node Processorâ. Leaf ProcessorConfigurators should extend from AbstractProcessorConfigurator.
-
-Now lets see the semantics of BarProcessor. </p>
+<p>If there are attributes, let them be handle as shown in "Writing a Node
+Processor" . Leaf ProcessorConfigurators should extend from
+AbstractProcessorConfigurator. Now lets see the semantics of BarProcessor.
+</p>
<pre><source>
public class BarProcessor extends AbstractProcessor {
-
- private Log log = LogFactory.getLog(getClass());
+
+ private Log log = LogFactory.getLog(getClass());
- public boolean process(SynapseEnvironment se, SynapseMessage smc) {
- // Processing logic goes here
- return true;
- }
+ public boolean process(SynapseEnvironment se, SynapseMessage smc) {
+ // Processing logic goes here
+ return true;
+ }
} </source></pre>
-<p>
-Leaf Processors should extend from AbstractProcessor.
+<p>Leaf Processors should extend from AbstractProcessor. So "Let there be
+Processors". But we are not quite there. We need to do one more
+configuration, Plunging the extension to the core. Go to the class -</p>
+<pre>org.apache.synapse.xml.ProcessorConfiguratorFinder </pre>
-So âLet there be Processorsâ. But we are not quite there. We need to do one more configuration, Plunging the extension to the core.
+<p> there one will find the following static variable. </p>
+<pre>private static Class[] processorConfigurators = {...}</pre>
-Go to <p><pre>org.apache.synapse.xml.ProcessorConfiguratorFinder </p></pre> class. There one will find the following static variable.
-</p>
-<pre>
-private static Class[] processorConfigurators = {...}
-</pre>
-<p>
-So you have to fill it with your extensions as follows,
-</p>
-<pre>
-private static Class[] processorConfigurators = {..., FooProcessorConfigurator.class,BarProcessorConfigurator.class}
-</pre>
-<p>Now you have successfully plugged your processor into Synapse. Finally âLet there be Processorsâ.
-</p>
+<p>You have to fill it with your extensions as follows,</p>
+<pre>private static Class[] processorConfigurators = {..., FooProcessorConfigurator.class,BarProcessorConfigurator.class} </pre>
+<p>Now you have successfully plugged your processor into Synapse. Finally
+"Let there be Processors". </p>
<p></p>
</body>
Modified: incubator/synapse/trunk/java/xdocs/userguide.html
URL: http://svn.apache.org/viewcvs/incubator/synapse/trunk/java/xdocs/userguide.html?rev=367247&r1=367246&r2=367247&view=diff
==============================================================================
--- incubator/synapse/trunk/java/xdocs/userguide.html (original)
+++ incubator/synapse/trunk/java/xdocs/userguide.html Mon Jan 9 00:42:34 2006
@@ -1,118 +1,138 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
- "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html>
<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title>Synapse Userguide</title>
+ <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+ <title>Synapse Userguide</title>
</head>
<body>
-<h1>UserGuide</a></h1>
+<h1>UserGuide</h1>
-<p>Apache Synapse is a mediation framework for Web Services. Synapse allows messages flowing through, into, or out of an organization to be mediated, including aspects such as: </p>
+<p>Apache Synapse is a mediation framework for Web Services. Synapse allows
+messages flowing through, into, or out of an organization to be mediated,
+including aspects such as:</p>
<ul>
-<li><p> Logging, service lookup, performance mediation </p>
-</li>
-<li><p> Versioning, failover, monitoring </p>
-</li>
-<li><p> Fault management, tracing </p>
-
-</li>
+ <li><p>Logging, service lookup, performance mediation</p>
+ </li>
+ <li><p>Versioning, failover, monitoring</p>
+ </li>
+ <li><p>Fault management, tracing</p>
+ </li>
</ul>
<h3>Getting started</h3>
-<p>Although there is a cleanly defined division between Synapse and Axis2, the Synapse system relies on Axis2 to run. Firstly, it uses the AXIOM object model, and secondly it uses Axis2 as a listener and sender for Web service requests. There are two ways to set up the Synapse server. </p>
+<p>Although there is a clearly defined division between Synapse and Axis2,
+the Synapse system relies on Axis2 to run. Firstly, it uses the AXIOM object
+model, and secondly it uses Axis2 as a listener and sender for Web service
+requests. There are two ways to set up the Synapse server.</p>
<ol>
-<li><p> synapse.war which can be deployed in a servlet container. </p>
-</li>
-<li><p> A lightweight server which runs with its own HTTP server (it uses Axis2's SimpleHTTPServer which is a simple lightweight HTTP server option that does not require a Servlet Engine) </p>
+ <li><p>synapse.war : Deploy the WAR file into your favorite servlet
+ container. Once it's expanded, you will see in <tt>WEB-INF</tt> the
+ axis2.xml which has been configured to execute Synapse properly and
+ synapse.xml, which will hold the rules pertaining to messages passing
+ through Synapse.</p>
+ </li>
+ <li><p>A lightweight server which runs with its own HTTP server : This uses
+ Axis2's SimpleHTTPServer which is a simple lightweight HTTP server option
+ that does not require a Servlet Engine. First unzip the
+ Synapse-M1-SNAPSHOT.zip. In the bin directory you will find a script
+ called:</p>
+ <pre>synapse [.sh or .bat]</pre>
+ <p>You should also see a directory called <tt>synapse-repository</tt>.
+ There you will find the axis2.xml and synapse.xml config files. The
+ axis2.xml need not be modified, but you can do so if you want to.</p>
+ <p>The command line for synapse-lightweight takes the repository
+ directory and listening port:</p>
+ <pre>sh bin/synapse.sh synapse-repository 8080 [Linux]
-</li>
+bin\synapse synapse-repository 8080 [Win]</pre>
+ </li>
</ol>
-<p>You can either download these or build them using Maven. </p>
-<p>You can build the war file by using the command:
-</p>
-<pre>
- maven dist-bin
-</pre>
-<p>which creates both the WAR and binary distribution JARs. </p>
-<p>If you to use synapse.war, deploy it in into your favorite servlet container. </p>
-<p>Once it's exploded, you will see in <tt>WEB-INF</tt> the axis2.xml which has been configured to execute Synapse properly and synapse.xml, which will hold the rules pertaining to messages passing through Synapse. </p>
-
-<p>If you wish to use the standalone server, unzip the Synapse-M1-SNAPSHOT.zip. In the bin directory you will find a script called: </p>
-
-<pre>
-synapse [.sh or .bat]
-</pre>
-<p>You should also see a directory called <tt>synapse-repository</tt>. In there you should find the axis2.xml and synapse.xml config files. The axis2.xml should not need to be modified, but if you know what you are doing you can of course! </p>
-<p>The command line for synapse-lightweight takes the repository directory and listening port, so:
-</p>
-<pre>
-sh bin/synapse.sh synapse-repository 8080 [Linux]
-bin\synapse synapse-repository 8080 [Win]
+<p>Note that you can also build them using Maven: Build the WAR file by using
+the command,</p>
+<pre> maven dist-bin</pre>
-</pre>
+<p>This creates both the WAR and binary distribution JARs.</p>
-<h3>Deployment models</h3>
+<p></p>
-<p>Synapse can intermediate in a number of different models: </p>
+<h3>Deployment models</h3>
+<p>Synapse can intermediate in a number of different modes:</p>
<ul>
+ <li>Transparent mode
+ <ol>
+ <li>Synapse acts as an HTTP Proxy.</li>
+ <li>Clients are configured with the Synapse endpoint URL as the HTTP
+ Proxy URL.</li>
+ <li>Synapse can work with both WS-A and non-WS-A SOAP messages.</li>
+ </ol>
+ </li>
+ <li>Gateway mode
+ <ol>
+ <li>The client explicitly sends a message to Synapse (with or without
+ WS-A headers)</li>
+ <li>The synapse.xml must include enough routing information to
+ correctly set the WS-A To and then Synapse forwards the message</li>
+ </ol>
+ </li>
+ <li>Smart client mode
+ <ol>
+ <li>The client sends the message to Synapse but sets the WSA headers to
+ the ultimate destination</li>
+ </ol>
+ </li>
+</ul>
-<li>Transparent mode
-<ol>
-<li>In this mode, Synapse acts as an HTTP Proxy. </li>
-<li>Clients are configured with the Synapse endpoint URL as the HTTP Proxy URL.</li>
-<li>Synapse can work with both WS-A and non-WS-A SOAP messages in this model. </li>
-</ol>
-</li>
-<li>Gateway mode
-<ol>
-<li> In this mode, the client explicitly sends a message to Synapse (with or without WS-A headers) </li>
-<li> The synapse.xml must include enough routing information to correctly set the WS-A To and then Synapse forwards the message </li>
-</ol>
-
-<li >Smart client mode</li>
+<h3>Processing model</h3>
+<p>Synapse has an overall model under which there are two ways to extend the
+framework.</p>
<ol>
-<li >In this mode, the client sends the message to Synapse but sets the WSA headers to the ultimate destination </li>
-</ol></ul>
-
-<h3 >Processing model</h3>
-
-<p>Synapse has an overall model under which there are two ways to extend the framework. </p>
-<ol >
-<li><p> Using the SPI, developers can build Synapse Extensions, which extend both the functionality and the XML configuration syntax of Synapse. </p>
-</li>
-<li><p> Using the API, developers can build Mediators, which extend the functionality of Synapse but use the existing XML syntax. </p>
-
-</li>
-<li><p> There are also built-in mediators that do common tasks like logging, redirection etc. </p>
-</li>
+ <li><p>Using the SPI: Developers can build Synapse Extensions, which extend
+ both the functionality and the XML configuration syntax of Synapse.</p>
+ </li>
+ <li><p>Using the API: Developers can build Mediators, which extend the
+ functionality of Synapse but use the existing XML syntax.</p>
+ </li>
</ol>
-</ul>
-<p>Typically users of Synapse extend the function using mediators, while the Synapse development team can extend the core by building extensions. </p>
-<p>A synapse deployment attaches to one or more transport listeners, and mediates messages from those listeners. One of the key decisions is how to "attach" mediators to messages. </p>
-
-<h4 >Rules</h4>
-
-<p>By default Synapse will execute all defined mediators against a given message, but this can be affected by using simple rules. Synapse has two predefined rules: <tt><xpath></tt> and <tt><regex></tt>. xpath evaluates and XPath expression against the message, while regex matches a regular expression against one of the message headers (such as the <tt>wsa:To</tt> address). </p>
-<p>Synapse also has two simple rules <tt><in></tt> and <tt><out></tt> which process only request or response messages (as seen by the target service). </p>
+<p>There are also built-in mediators that do common tasks like logging,
+redirection etc. Typically users of Synapse extend the function using
+mediators, while the Synapse development team can extend the core by building
+extensions.</p>
+
+<p>A synapse deployment attaches to one or more transport listeners, and
+mediates messages from those listeners. One of the key decisions is how to
+"attach" mediators to messages.</p>
+
+<h4>Rules</h4>
+
+<p>By default Synapse will execute all defined mediators against a given
+message, but this can be affected by using simple rules. Synapse has two
+predefined rules: <tt><xpath></tt> and <tt><regex></tt>. xpath
+evaluates a XPath expression against the message, while regex matches a
+regular expression against one of the message headers (such as the
+<tt>wsa:To</tt> address).</p>
+
+<p>Synapse also has two simple rules <tt><in></tt> and
+<tt><out></tt> which process only request or response messages (as seen
+by the target service).</p>
+
+<h4>Stages</h4>
+
+<p>As a message goes through the Synapse engine, it can pass through multiple
+stages. Each stage is a way of grouping and organizing mediators and rules. A
+stage simply gives the group a name.</p>
-<h4 >Stages</h4>
+<h4>An example</h4>
-<p>As a message goes through the Synapse engine, it can pass through multiple stages. Each stage is a way of grouping and organizing mediators and rules. A stage simply gives the group a name. </p>
-
-<h4 >An example</h4>
-
-<p>At this point an example would be useful. </p>
-
-<pre>
-<stage name="stage1-all">
+<p></p>
+<pre><stage name="stage1-all">
<!--This enables the addressing module which looks at wsa headers -->
<engage-addressing-in/>
@@ -129,25 +149,34 @@
<stage name="stage3-send-all">
<send/>
-</stage>
-</pre>
-<p>This example demonstrates <em>stage</em>, <em>regex</em> and some built in mediators: <em>log</em>, <em>addressing</em> and <em>header</em>. It does not demonstrate the <em>xpath</em>, <em>in</em> or <em>out</em> rules. </p>
+</stage></pre>
-<p>Every stage will be executed for each message. The first stage does initial processing including parsing the addressing headers and logging the message. </p>
-<p>The next stage is using a regex rule to redirect every message addresses to xmethods.com and xmethods.net to the real SOAP address of the XMethods quote service. </p>
-<p>Finally the last stage sends the message on. For responses, the messages come back through the same stages. This time the message will not be redirected because the "to" address on the response will not match xmethods. </p>
+<p>This example demonstrates <em>stage</em>, <em>regex</em> and some built in
+mediators: <em>log</em>, <em>addressing</em> and <em>header</em>. It does not
+demonstrate the <em>xpath</em>, <em>in</em> or <em>out</em> rules.</p>
-<h4 >User Mediators</h4>
+<p>Every stage will be executed for each message. The first stage does
+initial processing including parsing the addressing headers and logging the
+message.</p>
-<p>Synapse allows users to extend the built in mediators and add their own. The mediators use the Synapse API. The API has three interfaces. </p>
+<p>The next stage is using a regex rule to redirect every message addresses
+to xmethods.com and xmethods.net to the real SOAP address of the XMethods
+quote service.</p>
-<h4 >SynapseMessage</h4>
+<p>Finally the last stage sends the message on. For responses, the messages
+come back through the same stages. This time the message will not be
+redirected because the "to" address on the response will not match
+xmethods.</p>
+<h4>User Mediators</h4>
-<p>The primary interface is the <a >SynapseMessage</a> interface: </p>
+<p>Synapse allows users to extend the built in mediators and add their own.
+The mediators use the Synapse API. The API has three interfaces.</p>
-<pre>
-public interface SynapseMessage {
+<h4>SynapseMessage</h4>
+
+<p>The primary interface is the <a>SynapseMessage</a> interface:</p>
+<pre>public interface SynapseMessage {
public SOAPEnvelope getEnvelope();
public void setEnvelope(SOAPEnvelope envelope) throws AxisFault;
@@ -162,35 +191,43 @@
public void setResponse(boolean b);
public boolean isResponse();
-}
-</pre>
-<p>The <a >SynapseMessage</a> interface is based on the Axis2 <a >MessageContext</a> interface. It uses the Axis2 <a >EndpointReference</a> and SOAPEnvelope classes/interfaces. </p>
-<p>The purpose of this interface is to capture a message as it flows through the system. As you will see the messages are represented using the SOAP infoset. Binary messages can be embedded in the Envelope using the MTOM support built into Axis2's AXIOM object model. </p>
-
-<h4 >Mediator interface</h4>
-
+}</pre>
-<p>The second key interface for mediator writers is the Mediator interface: </p>
-
-<pre>
-package org.apache.synapse.api;
+<p>The <a>SynapseMessage</a> interface is based on the Axis2
+<a>MessageContext</a> interface. It uses the Axis2 <a>EndpointReference</a>
+and SOAPEnvelope classes/interfaces.</p>
+
+<p>The purpose of this interface is to capture a message as it flows through
+the system. As you will see the messages are represented using the SOAP
+infoset. Binary messages can be embedded in the Envelope using the MTOM
+support built into Axis2's AXIOM object model.</p>
+
+<h4>Mediator interface</h4>
+
+<p>The second key interface for mediator writers is the Mediator
+interface:</p>
+<pre>package org.apache.synapse.api;
import org.apache.synapse.SynapseMessage;
public interface Mediator {
public boolean mediate(SynapseMessage sm);
-}
-
-</pre>
-<p>The mediator can modify the <a >SynapseMessage</a> in any way it likes - adjusting the routing headers or changing the message. If it returns false, that signals to the Synapse processing model to stop processing further. 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>
+}</pre>
-<h4 >EnvironmentAware</h4>
-
-
-<p>The final aspect of the API is the <a >EnvironmentAware</a> interface. If the mediator implements this, then it will have the <a >SynapseEnvironment</a> injected into it: </p>
-
-<pre>
-package org.apache.synapse.api;
+<p>The mediator can modify the <a>SynapseMessage</a> in any way it likes -
+adjusting the routing headers or changing the message. If it returns false,
+that signals to the Synapse processing model to stop processing further. 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>
+
+<h4>EnvironmentAware</h4>
+
+<p>The final aspect of the API is the <a>EnvironmentAware</a> interface. If
+the mediator implements this, then it will have the <a>SynapseEnvironment</a>
+injected into it:</p>
+<pre>package org.apache.synapse.api;
import org.apache.synapse.SynapseEnvironment;
@@ -198,12 +235,11 @@
public void setSynapseEnvironment(SynapseEnvironment se);
public void setClassLoader(ClassLoader cl);
-}
-</pre>
-<p>The <a >SynapseEnvironment</a> allows the mediator access to the underlying engine: </p>
+}</pre>
-<pre>
-package org.apache.synapse;
+<p>The <a>SynapseEnvironment</a> allows the mediator access to the underlying
+engine:</p>
+<pre>package org.apache.synapse;
public interface SynapseEnvironment {
@@ -214,57 +250,46 @@
public void addProcessor(Processor p);
public Processor getMasterProcessor();
public void setMasterProcessor(Processor p);
-}
-</pre>
-
-<h4 >Mediator configuration</h4>
-
-<p>Mediators can be configured in a few ways, including as classes, using IoC containers such as Spring, and as deployed Axis2 Services. </p>
-
-<h4 >ClassMediator</h4>
-
-
-<ul>
-<li ><p>Firstly, they can be loaded as simple classes: </p>
-
-</li>
-</ul>
-
-<pre>
-<classmediator name="optional-name" class="org.apache.sample.MyLogger"/>
-</pre>
-<p>This will load a class named <tt>org.apache.sample.MyLogger</tt> and use it to mediate messages. </p>
+}</pre>
-<h4 >ServiceMediator</h4>
+<h4>Mediator configuration</h4>
-
-<p>This will direct the message through a deployed Axis2 service which implements the mediate interface: </p>
-
-<pre>
-<servicemediator name="optional-name" service="service-name"/>
-</pre>
-
-<h4 >SpringMediator</h4>
-
-<p>This model is supported by an optional extension, and requires that you have the <tt>spring-core</tt>, <tt>spring-context</tt> and <tt>spring-beans</tt> libraries from the <a href="http://www.springframework.org"> Spring framework</a> website, as well as the <tt>springmediator.jar</tt> in your classpath. </p>
-
-<p>The Spring mediator model uses a spring assembly to configure an assembly of beans. The bean assembly must produce at one bean which implements the mediator interface. </p>
-
-<pre>
+<p>Mediators can be configured in different ways which include</p>
+<ol>
+ <li>They can be loaded as simple classes:
+ <pre><classmediator name="optional-name" class="org.apache.sample.MyLogger"/></pre>
+ <p>This will load a class named <tt>org.apache.sample.MyLogger</tt> and
+ use it to mediate messages.</p>
+ </li>
+ <li>As deployed Axis2 Services: This will direct the message through a
+ deployed Axis2 service which implements the mediate interface:
+ <pre><servicemediator name="optional-name" service="service-name"/>
+ </pre>
+ </li>
+ <li>Using IoC containers such as Spring: This model is supported by an
+ optional extension, and requires that you have the <tt>spring-core</tt>,
+ <tt>spring-context</tt> and <tt>spring-beans</tt> libraries from the <a
+ href="http://www.springframework.org/">Spring framework</a> website, as
+ well as the <tt>springmediator.jar</tt> in your classpath. The Spring
+ mediator model uses a spring assembly to configure an assembly of beans.
+ The bean assembly must produce as one bean which implements the mediator
+ interface.
+ <pre>
<synapse-spring:springmediator name="optional-name" bean="name-of-bean-which-implements-mediator">
<beans>
<bean .... spring bean assembly configuration goes here >
</beans>
</synapse-spring:springmediator>
+ </pre>
+ </li>
+</ol>
-</pre>
-
-<h3 >In and Out</h3>
-
-<p>We could have been more explicit that the redirection is only designed to apply to "in" messages by using the <in> rule. </p>
+<h3>In and Out </h3>
-<pre>
-<stage name="stage1-all">
+<p>Redirection is only designed to apply to "in" messages by using the
+<in> rule. If we use <out> then you have to explictley use the
+<in> rule. </p>
+<pre><stage name="stage1-all">
...
</stage>
@@ -275,30 +300,26 @@
<stage name="stage3-send-all">
...
-</stage>
+</stage></pre>
+
+<p>There is a corresponding <tt><out></tt> rule.</p>
+
+<h4>References</h4>
+
+<p>In order to make the configuration more re-usable, every rule, stage or
+mediator can be named:</p>
+<pre> <stage name="thisname"></pre>
-</pre>
-<p>There is a corresponding <tt><out></tt> rule. </p>
+<p>The name can then be used to "refer" to the mediator.</p>
-<h4 >References</h4>
+<p>So</p>
+<pre><ref ref="thisname"/></pre>
-<p>In order to make the configuration more re-usable, every rule, stage or mediator can be named:
-</p>
-<pre>
- <stage name="thisname">
-</pre>
-
-<p>The name can then be used to "refer" to the mediator. </p>
-<p>So
-</p>
-<pre>
-<ref ref="thisname"/>
-</pre>
-<p>will cause the same processing to happen as if the stage had been included at that point. </p>
-<p>For example:
-</p>
-<pre>
-<in>
+<p>will cause the same processing to happen as if the stage had been included
+at that point.</p>
+
+<p>For example:</p>
+<pre><in>
<stage name="both">
. . .
@@ -308,18 +329,18 @@
<out>
<ref ref="both"/>
-</out>
-</pre>
-<p>Please note this is one area where we expect to do considerable work </p>
-
-<h4 >Never</h4>
+</out></pre>
+
+<p>Please note this is one area where we expect to do considerable work</p>
+<h4>Never</h4>
-<p>This is a stage where none of the children get executed. Its purpose is to allow you to place rules and mediations and have them not executed but instead refer to them from one or more other places. </p>
-<p>So the following may be deemed equivalent to the previous example
-</p>
-<pre>
-<in>
+<p>This is a stage where none of the children get executed. Its purpose is to
+allow you to place rules and mediations and have them not executed but
+instead refer to them from one or more other places.</p>
+
+<p>So the following may be deemed equivalent to the previous example</p>
+<pre><in>
<ref ref="both"/>
<stage name="inonly"> ...</stage>
@@ -330,149 +351,144 @@
<never>
<stage name="both"> ...</stage>
-</never>
-</pre>
+</never></pre>
-<h4 >Content based routing</h4>
+<h4>Content based routing</h4>
-<p>We can further improve our example by adding some "content-based" routing. Using an <xpath> rule we can make tests within the XML. For example, we could decide not to allow stock ticker queries against certain companies whose share prices we were jealous of - MSFT say :-). </p>
+<p>We can further improve our example by adding some "content-based" routing.
+Using an <xpath> rule we can make tests within the XML. For example, we
+could decide not to allow stock ticker queries against certain companies
+whose share prices we were jealous of - MSFT say :-).</p>
-<p>To do this we can add a rule:
-</p>
-<pre>
-<xpath expr="//*[Symbol='MSFT']">
+<p>To do this we can add a rule:</p>
+<pre><xpath expr="//*[Symbol='MSFT']">
<fault/>
-</xpath>
-</pre>
-<p>This rule identifies any messages with a tag <tt>Symbol</tt> whose content is MSFT. The <tt><fault></tt> mediator returns a fault to the client. </p>
-
-<p>We can place this rule under the regex rule, so it only applies to requests aimed at xmethods.*:
-</p>
-<pre>
-<regex message-address="to" pattern="http://xmethods.*">
+</xpath></pre>
+
+<p>This rule identifies any messages with a tag <tt>Symbol</tt> whose content
+is MSFT. The <tt><fault></tt> mediator returns a fault to the
+client.</p>
+
+<p>We can place this rule under the regex rule, so it only applies to
+requests aimed at xmethods.*:</p>
+<pre><regex message-address="to" pattern="http://xmethods.*">
<header type="to" value="http://64.124.140.30:9090/soap"/>
<xpath expr="//*[Symbol='MSFT']">
<fault/>
</xpath>
-</regex>
-</pre>
-<p>Note that the rules, like the stages, can have more than one child. While it isn't fixed in Synapse, the built-in rules and mediators all use the same "plan" to execute their children, which involves executing in the lexical order that they occur in the synapse.xml. </p>
+</regex></pre>
-<h3 >XML Configuration Elements</h3>
+<p>Note that the rules, like the stages, can have more than one child. While
+it isn't fixed in Synapse, the built-in rules and mediators all use the same
+"plan" to execute their children, which involves executing in the lexical
+order that they occur in the synapse.xml.</p>
+
+<h3>XML Configuration Elements</h3>
+
+<p>Every element in the Synapse configuration file maps to a instance of a
+Processor. There are two types of elements - <strong>nodes</strong> that
+"contain" sub-elements (ex: <tt><regex/></tt>, <tt><stage/></tt>
+and <tt><xpath/></tt>) and <strong>leaves</strong> which only contain
+configuration for that element or have no xml children (ex:
+<tt><engage-addressing-in/></tt>).</p>
-<p>Every element in the Synapse configuration file maps to a instance of a Processor. There are two types of element - <strong>nodes</strong> that "contain" sub-elements (ex: <tt><regex/></tt>, <tt><stage/></tt> and <tt><xpath/></tt>) and <strong>leaves</strong> others which only contain configuration for that element or have no xml children (ex: <tt><engage-addressing-in/></tt>). </p>
-
-<h4 >Grouping and Referencing elements</h4>
+<h4>Grouping and Referencing elements</h4>
+<ol>
+ <li><p><tt><stage/></tt></p>
+ </li>
+ <li><p><tt><in/></tt></p>
+ </li>
+ <li><p><tt><out/></tt></p>
+ </li>
+ <li><p><tt><never/></tt></p>
+ </li>
+ <li><p><tt><ref/></tt></p>
+ </li>
+</ol>
+<h4>Rule elements</h4>
+<ol>
+ <li><p><tt><regex/></tt></p>
+ </li>
+ <li><p><tt><xpath/></tt></p>
+ </li>
+</ol>
-<ol t>
-<li><p><tt><stage/></tt> </p>
-</li>
-<li ><p><tt><in/></tt> </p>
-</li>
-<li ><p><tt><out/></tt> </p>
-</li>
+<h4>Built-in mediators</h4>
+<ol>
+ <li><p><tt><engage-addressing-in/></tt></p>
+ </li>
+ <li><p><tt><log/></tt></p>
+ </li>
+ <li><p><tt><fault/></tt></p>
+ </li>
+ <li><p><tt><send/></tt></p>
+ </li>
+ <li><p><tt><header/></tt></p>
+ </li>
+</ol>
-<li ><p><tt><never/></tt> </p>
-</li>
-<li ><p><tt><ref/></tt> </p>
-</li>
+<h4>User mediator types</h4>
+<ol>
+ <li><p><tt><servicemediator/></tt></p>
+ </li>
+ <li><p><tt><classmediator/></tt></p>
+ </li>
</ol>
-<h4 >Rule elements</h4>
+<h3>Samples</h3>
+<h4>Logging</h4>
-<ol >
-<li><p><tt><regex/></tt> </p>
+<p>The system ships with a couple of samples. These include sample clients
+and appropriate synapse.xml intermediary configurations.</p>
-</li>
-<li ><p><tt><xpath/></tt> </p>
-</li>
-</ol>
+<p>The first sample demonstrates the logging facility. Here is a simple
+synapse.xml:</p>
+<pre><synapse xmlns="http://ws.apache.org/ns/synapse">
+ <engage-addressing-in/>
+ <log/>
+ <send/>
-<h4 >Built-in mediators</h4>
+</synapse></pre>
+<p>The logging uses the Log4J/Commons Logging support in Apache. You can
+configure it using <tt>log4j.properties</tt>.</p>
-<ol >
-<li><p><tt><engage-addressing-in/></tt> </p>
-</li>
-<li ><p><tt><log/></tt> </p>
-
-</li>
-<li ><p><tt><fault/></tt> </p>
-</li>
-<li ><p><tt><send/></tt> </p>
-</li>
-<li ><p><tt><header/></tt> </p>
-</li>
-</ol>
+<p>The sample client is a standard Axis2 client built to run against the
+XMethods Quote Service. However, it has been modified to use a different
+transport address from the Web Services Addressing TO header. In other words,
+the SOAP envelope is addressed to the XMethods service, but the actual HTTP
+request goes to Synapse. The sample client has three (optional)
+parameters:</p>
+<pre>StockQuoteClient SYMBOL XmethodsURL TransportURL</pre>
-<h4 >User mediator types</h4>
+<p>e.g.</p>
+<pre>StockQuoteClient IBM http://64.124.140.30:9090/soap http://localhost:8080</pre>
+<p>The sample synapse.xml can be used to demonstrate a few simple behaviours.
+1) Firstly try this:</p>
+<pre>StockQuoteClient IBM http://64.124.140.30:9090/soap http://64.124.140.30:9090/soap</pre>
-<ol >
-<li><p><tt><servicemediator/></tt> </p>
-</li>
-<li ><p><tt><classmediator/></tt> </p>
-</li>
-</ol>
+<p>This will bypass Synapse and simply call XMethods.</p>
-<h3 >Samples</h3>
+<p>2) Now start Synapse on port 8080 and try</p>
+<pre>StockQuoteClient</pre>
+<p>on its own. You should see the messages being logged as they pass through
+Synapse.</p>
-<h4 >Logging</h4>
+<p>3) This time try</p>
+<pre>StockQuoteClient IBM urn:xmethods-delayed-quotes</pre>
-<p>The system ships with a couple of samples. These include sample clients and appropriate synapse.xml intermediary configurations. </p>
-<p>The first sample demonstrates the logging facility. Here is a simple synapse.xml:
-</p>
-<pre>
-<synapse xmlns="http://ws.apache.org/ns/synapse">
- <engage-addressing-in/>
- <log/>
- <send/>
+<p>This should hit a regex rule which replaces the "virtual URI" that is in
+the wsa:To header with the real URL.</p>
-</synapse>
-</pre>
-<p>The logging uses the Log4J/Commons Logging support in Apache. You can configure it using <tt>log4j.properties</tt>. </p>
-<p>The sample client is a standard Axis2 client built to run against the XMethods Quote Service. However, it has been modified to use a different transport address from the Web Services Addressing TO header. In other words, the SOAP envelope is addressed to the XMethods service, but the actual HTTP request goes to Synapse. The sample client has three (optional) parameters: </p>
-
-<pre>
-StockQuoteClient SYMBOL XmethodsURL TransportURL
-</pre>
-<p>e.g.
-</p>
-<pre>
-StockQuoteClient IBM http://64.124.140.30:9090/soap http://localhost:8080
-
-</pre>
-<p>The sample synapse.xml can be used to demonstrate a few simple behaviours. 1) Firstly try this:
-</p>
-<pre>
-StockQuoteClient IBM http://64.124.140.30:9090/soap http://64.124.140.30:9090/soap
-</pre>
-<p>This will bypass Synapse and simply call XMethods. </p>
-<p>2) Now start Synapse on port 8080 and try
-</p>
-<pre>
-StockQuoteClient
-</pre>
-<p>on its own. You should see the messages being logged as they pass through Synapse. </p>
-<p>3) This time try
-</p>
-
-<pre>
-StockQuoteClient IBM urn:xmethods-delayed-quotes
-</pre>
-<p>This should hit a regex rule which replaces the "virtual URI" that is in the wsa:To header with the real URL. </p>
-<p>4) Now try
-</p>
-<pre>
-StockQuoteClient MSFT
-</pre>
-<p>which should hit a "content-based" xpath rule. </p>
-<a ></a>
+<p>4) Now try</p>
+<pre>StockQuoteClient MSFT </pre>
-<!-- end page -->
+<p>which should hit a "content-based" xpath rule.</p>
+<a></a> <!-- end page -->
</body>
</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: synapse-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: synapse-dev-help@ws.apache.org