Added: incubator/synapse/tags/M2/xdocs/svn.html URL: http://svn.apache.org/viewvc/incubator/synapse/tags/M2/xdocs/svn.html?rev=410809&view=auto ============================================================================== --- incubator/synapse/tags/M2/xdocs/svn.html (added) +++ incubator/synapse/tags/M2/xdocs/svn.html Thu Jun 1 02:28:13 2006 @@ -0,0 +1,67 @@ +<html> +<head> + <meta http-equiv="content-type" content=""> + <title></title> +</head> + +<body> +<h1>Developing Apache Synapse</h1> + +<h2>Working with Subversion</h2> + +<p>The Synapse development uses Subversion for source control. To learn +more about Subversion or to download the latest distribution, visit the <a +href="http:///subversion.tigris.org";>Subversion project site</a>. If you are +looking for guidance on setting up and installing Subversion, please read the +ASF <a href="http://www.apache.org/dev/version-control.html";>Source Code +Repositories page</a>.</p> + +<h2>Checkout</h2> + +<p>Use the following URL to download latest source code of Synapse:</p> +<ul> + <li><b>Use</b> <a + href="https://svn.apache.org/repos/asf/incubator/synapse/trunk/java";> + https://svn.apache.org/repos/asf/incubator/synapse/trunk/java</a></li> +</ul> + +<p>Once you have successfully installed Subversion, you can check out Synapse +trunk by following these steps:</p> +<ol type="1"> + <li>Run <strong>svn co <repository URL> synapse</strong> where + repository URL is one of the URLs from the previous list.</li> + <li>This step will check out the latest version of the Synapse Java codebase + to a directory named "synapse". The second parameter to the svn co selects + a directory to create on your local machine. If you want to checkout + Synapse to a different directory, feel free to change synapse to any other + directory name.</li> + <li>To update your working copy to the latest version from the repository. + Execute the <strong>svn update</strong> command.</li> + <li>If you would like to submit a patch, you can execute <strong>svn + diff</strong> to create a unified diff for submission to the Synapse JIRA + issue tracker.</li> +</ol> + +<h2>Installing Maven 1</h2> + +<p>Synapse build is based on Maven 1. Maven is a build system that allows +for the reuse of common build projects across multiple projects. For +information about obtaining, installing, and configuring Maven 1, please see +the <a href="http://maven.apache.org";>Maven project page</a>. To use Maven +to build the Synapse project, follow these simple steps:</p> +<ol type="1"> + <li>Install <a href="http://maven.apache.org/";>Maven</a>. See <a + href="http://maven.apache.org/start/install.html";>here</a> for + instructions. + <ul> + <li>Create a MAVEN_HOME environment variable.</li> + <li>Add MAVEN_HOME/bin to your PATH</li> + </ul> + </li> + <li>Go to the synapse folder in the command prompt and type + <strong>maven<strong>.</strong></strong></li> + <li>Maven will then automatically download all the jars, compile, test and + build the Synapse deliverables.</li> +</ol> +</body> +</html>
Added: incubator/synapse/tags/M2/xdocs/userguide.html URL: http://svn.apache.org/viewvc/incubator/synapse/tags/M2/xdocs/userguide.html?rev=410809&view=auto ============================================================================== --- incubator/synapse/tags/M2/xdocs/userguide.html (added) +++ incubator/synapse/tags/M2/xdocs/userguide.html Thu Jun 1 02:28:13 2006 @@ -0,0 +1,428 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "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> +</head> +<body> +<h1>User Guide</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. Refer to the project documentation for more details.<br> +</p> +<h2>Getting started</h2> +<h3>Synapse Installation<br> +</h3> +<p>Synapse is available in two distributions. A standalone lightweight +distribution which runs on its own HTTP server, and as a WAR +distribution. +The WAR distribution is not currently supported for the Milestone M2 +release. Hence you will need to start the lightweight version of +Synapse as described below.<br> +</p> +<p>Synapse will always start in the SYNAPSE_HOME directory, which is +where Synapse is installed. This directory has the following structure.<br> +</p> +<table style="width: 80%; text-align: left;" border="0" cellpadding="2" + cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;">/synapse<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/bin<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">-<br> + </td> + <td style="vertical-align: top;">Contains the binaries. i.e. +synapse.sh and synapse.bat</td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/lib<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/endorsed<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">-<br> + </td> + <td style="vertical-align: top;">If validation mediator is used, +Xerces parser JAR files should be placed here</td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/samples<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">-<br> + </td> + <td style="vertical-align: top;">This directory includes several +samples +with varying complexity.</td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/synapse_repository</td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">-<br> + </td> + <td style="vertical-align: top;">This is the underlying Axis2 +repository. +Refer to Axis2 documentation for more information and structure of this.<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/conf<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">-<br> + </td> + <td style="vertical-align: top;">Contains the default synapse.xml +configuration file and the axis2.xml configuration file for Axis<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/sample<br> + </td> + <td style="vertical-align: top;">-<br> + </td> + <td style="vertical-align: top;">Contains sample synapse XML +configurations to be used with the samples<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/modules<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/services<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">/xdocs<br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">-<br> + </td> + <td style="vertical-align: top;">Contains bundled documentation<br> + </td> + </tr> + </tbody> +</table> +<br> +<br> +<h3>Starting Synapse through the <span style="font-family: monospace;"></span>synapse +[.sh or .bat] script</h3> +<p>The command line for synapse-lightweight takes the repository +directory and listening port as optional parameters. However as these +arguments are optional, if they are not specified the port will default +to 8080 for http and the repository to the 'synapse_repository' +directory. Execution of the script starts up synapse as follows.<br> +</p> +<table + style="width: 905px; height: 33px; text-align: left; margin-left: auto; margin-right: auto;" + border="1" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td + style="background-color: rgb(255, 255, 204); vertical-align: top;">C:\Java\SynapseDist\synapse>bin\synapse.bat<br> +......<br> +[SimpleHTTPServer] Starting<br> +[SimpleHTTPServer] Using the Axis2 Repository +C:\Java\SynapseDist\synapse\bin\..\synapse_repository<br> +[SimpleHTTPServer] Listening on port 8080<br> +[main] INFO SynapseAxis2Interceptor - Initializing Synapse...<br> +[main] INFO SynapseAxis2Interceptor - System property +'synapse.xml' specifies synapse configuration as +C:\Java\SynapseDist\synapse\bin\..\synapse_repository\conf\synapse.xml<br> +[main] INFO XMLConfigurationBuilder - Generating the Synapse +configuration model by parsing the XML configuration<br> +[main] INFO SynapseConfigurationBuilder - Loaded Synapse +configuration from : +C:\Java\SynapseDist\synapse\bin\..\synapse_repository\conf\synapse.xml<br> +[main] INFO SynapseAxis2Interceptor - Synapse initialized...<br> +[SimpleHTTPServer] Started<br> + </td> + </tr> + </tbody> +</table> +<br> +<p>If required the port and the Axis2 repository locations could be +specified as follows<br> +</p> +<pre> synapse.sh -p5043 synapse_repository</pre> +<p>A convenience method to start Synapse with sample configurations +(found in synapse_repository\conf\sample) is +available with the M2 release. This could be used as follows:</p> +<pre> synapse.sh -sample <number></pre> +<p><number> could be 0, 1 or 2, and will pick up the +synapse_repository\conf\sample\synapse_sample_<number>.xml file +from the samples.<br> +</p> +<p>The default log4j.properties file found in the SYNAPSE_HOME +directory sets the default Synapse log level as DEBUG. You may change +this to INFO or WARN as required.<br> +</p> +<h3>Building the Synapse source</h3> +<p>If you have downloaded the Synapse source, and set up Maven and its +dependencies, you could build the binary distribution as follows:<br> +</p> +<pre> maven dist-bin</pre> +<p>This creates the Synapse-Incubating-M2-SNAPSHOT-bin.zip distribution +file within target\dist<br> +</p> +<pre> maven dist-extensions<br></pre> +<p>The dist-extensions target builds the Synapse extensions +Extensions-Synapse-M2-SNAPSHOT-bin.zip into target\dist<br> +</p> +<h3>Installing Extensions</h3> +Synapse extensions allows the core of Synapse to be kept to the minimum +level, yet still allow extension. Hence the Spring and Validation +support which depends +on the Spring and Xerces JARs are kept outside of the core distribution +as extensions. The extensions are written using the Synapse SPI and the +API which allows the Synapse functionality and configuration to be +enhanced. (Refer to the Extending Synapse document for more +information) Hence the Spring extension source provides a good example +for +someone interested in using the SPI /API to extend the functionality +and +configuration of Synapse.<br> +<ul> + <li>Spring extension</li> +</ul> +<p style="margin-left: 40px;">The Spring extension requires spring.jar +to be placed on the synapse SYNAPSE_HOME/lib folder. In addition, you +will need to +place the synapse_extensions.jar file which could be found within the +Extensions-Synapse-M2-SNAPSHOT-bin.zip distribution file to be placed +into the same folder.<br> +</p> +<ul> + <li>Validate mediator<br> + </li> +</ul> +<p style="margin-left: 40px;">The Validate mediator depends on the +Xerces 2.8.0 parser. To properly setup the Xerces parser, you will need +to place the xml-apis.jar and xercesImpl.jar JAR files of Xerces into +the SYNAPSE_HOME/lib/endorsed directory. If you have already installed +Xerces into +your JAVA_HOME/lib/endorsed directory, you may omit the above step.<br> +<br> +</p> +<h2>Deployment models</h2> +<p>Synapse can intermediate in a number of different modes as listed +below. Refer to the README.txt in the samples directory for examples +utilizing these different models.<br> +</p> +<ul> + <li>Transparent mode + <ol> + </ol> + <ul> + <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> + </ul> + <ol> + </ol> + </li> + <li>Gateway mode + <ol> + </ol> + <ul> + <li>The client explicitly sends a message to Synapse (with or +without WS-A headers)</li> + <li>The synapse configuration must include enough routing +information to +correctly set the WS-A To and then Synapse forwards the message</li> + </ul> + <ol> + </ol> + </li> + <li>Smart client mode + <ol> + </ol> + <ul> + <li>The client sends the message to Synapse but sets the WS-A +headers to the ultimate destination</li> + </ul> + </li> +</ul> +<h2>Processing model</h2> +<p>Synapse has an overall model under which there are two ways to +extend the framework. This essentially maps into the +<definitions> or global Synapse configuration extension through +the SPI; and the <rules> or mediator extension through the API.<br> +</p> +<ol> + <li> + <p>Using the SPI: Developers can build Synapse configuration +extensions, which +extend the XML configuration of Synapse<br> + </p> + </li> + <li> + <p>Using the API: Developers can build Mediators, which extend the +functionality of Synapse<br> + </p> + </li> +</ol> +<p>There are also built-in mediators that do common tasks such as +logging, +editing etc. Typically users of Synapse extend the function using +mediators, while the Synapse development teams 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.<br> +</p> +<h2>Message Mediation</h2> +The Synapse configuration language describes the XML syntax used to +configure Synapse, and describes the built-in mediators. Please refer +to <a + href="http://wiki.apache.org/incubator/Synapse/SynapseConfigurationLanguage";>http://wiki.apache.org/incubator/Synapse/SynapseConfigurationLanguage</a> +for more information.<br> +<br> +<h3>User Mediators</h3> +Synapse allows users to extend the built in mediators by introducing +their +own. The mediators use the Synapse API. The main API interfaces are +described below. A user mediator implementation could be as simple as +writing your own Java class implementing the +org.apache.synapse.api.Mediator interface, which essentially defines +one single method <br> +<pre>public boolean mediate(MessageContext synCtx);<br></pre> +<p>You may additionally define this class as a Spring bean using the +Synapse +Spring extension. The advanced user may want to write his own custom +mediator as well as extend the XML configuration model with a custom +configuration extension.<br> +<br> +</p> +<h3>Writing a custom Class mediator implementation</h3> +A custom class mediator must extend the Mediator interface, and +implement the public boolean mediate(MessageContext synCtx) method and +a no argument constructor. The MessageContext allows the mediator to +use message content or to modify the message as required, and hand it +over to the next mediator as defined in the configuration. Class +mediators could be configured as follows:<br> +<pre><class name="class-name"><br> <property name="string" (value="literal" | expression="xpath")/>*<br></class><br></pre> +The class mediator is built into the core of Synapse, and creates an +instance of your specified class - which must be placed into the +SYNAPSE_HOME/lib folder as a JAR file. If any properties are defined in +the XML configuration the setter methods are invoked. However only +String properties are allowed for Class mediators at this time. Any +dependent libraries use by your class mediator implementation should be +placed into the same lib folder as well.<br> +<br> +<h3>Writing a custom Spring mediator implementation</h3> +A Spring mediator implementation is a class mediator, which is managed +by a given Spring configuration. The Spring configuration may be +defined globally to the Synapse Configuration and reused by multiple +Spring managed mediator beans or defined inline per bean. Refer to the +configuration syntax for more information. As the Spring mediator +implementation is distributed as an "extension" to the core Synapse +distribution, you will need to manually place the +extension_mediators.jar into the SYNAPSE_HOME/lib folder as well as +place the spring.jar and any other dependencies into the same directory.<br> +<br> +A reusable Spring configuration may be defined within the XML +configuration file as follows within the <definitions> element:<br> +<br> +<pre><spring:config name="string" src="file"/></pre> +<br> +And a Spring mediator implementation may be defined within the +<rules> element as follows:<br> +<br> +<pre><spring bean="exampleBean1" (config="spring1" | src="spring.xml)"/></pre> +<br> +The Spring configuration referenced by the "src" attribute will be +initialized and the bean with the name given by the "bean" attribute +will be looked up for mediation of the message. This bean must +implement the Mediator interface. If a reusable Spring configuration +was defined, the bean definition could refer to this configuration +through the name given in the "config" attribute.<br> +<span style="font-family: monospace;"><br> +</span><br> +<!-- end page --> +</body> +</html> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
