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 21:37:59 UTC
svn commit: r1222433 - in /synapse/branches/2.1/src/site: ./
resources/images/ xdoc/ xdoc/dev/ xdoc/userguide/ xdoc/userguide/samples/
Author: hiranya
Date: Thu Dec 22 20:37:58 2011
New Revision: 1222433
URL: http://svn.apache.org/viewvc?rev=1222433&view=rev
Log:
Documentation update
Added:
synapse/branches/2.1/src/site/resources/images/synapse-arch.png (with props)
synapse/branches/2.1/src/site/resources/images/synapse-flow.png (with props)
synapse/branches/2.1/src/site/xdoc/dev/release-process.xml
Modified:
synapse/branches/2.1/src/site/site.xml
synapse/branches/2.1/src/site/xdoc/index.xml
synapse/branches/2.1/src/site/xdoc/userguide/config.xml
synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml
synapse/branches/2.1/src/site/xdoc/userguide/samples.xml
synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml
Added: synapse/branches/2.1/src/site/resources/images/synapse-arch.png
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/resources/images/synapse-arch.png?rev=1222433&view=auto
==============================================================================
Binary file - no diff available.
Propchange: synapse/branches/2.1/src/site/resources/images/synapse-arch.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: synapse/branches/2.1/src/site/resources/images/synapse-flow.png
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/resources/images/synapse-flow.png?rev=1222433&view=auto
==============================================================================
Binary file - no diff available.
Propchange: synapse/branches/2.1/src/site/resources/images/synapse-flow.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: synapse/branches/2.1/src/site/site.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/site.xml?rev=1222433&r1=1222432&r2=1222433&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/site.xml (original)
+++ synapse/branches/2.1/src/site/site.xml Thu Dec 22 20:37:58 2011
@@ -52,7 +52,7 @@
<menu name="Developer Resources">
<item name="Developer Guide " href="dev/developer-guide.html"/>
<item name="Developer Best Practices"/>
- <item name="Release Process"/>
+ <item name="Release Process" href="dev/release-process.html"/>
<item name="How to Contribute"/>
</menu>
<menu name="Project Details">
Added: synapse/branches/2.1/src/site/xdoc/dev/release-process.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/dev/release-process.xml?rev=1222433&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/dev/release-process.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/dev/release-process.xml Thu Dec 22 20:37:58 2011
@@ -0,0 +1,53 @@
+<?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 - Release Process</title>
+ </properties>
+ <body>
+ <section name="Release Process">
+ <p>
+ We follow the standard <a href="http://www.apache.org/dev/release-publishing.html">ASF release process</a>.
+ One of the committers would volunteer to play the release manager role for a given
+ release. A few days will be spent on stabilizing the Synapse development trunk,
+ improving its documentation and test coverage. When the code base is in a satisfactory
+ state a release branch would be created under
+ <a href="https://svn.apache.org/repos/asf/synapse/branches">https://svn.apache.org/repos/asf/synapse/branches</a>.
+ </p>
+ <p>
+ From this point onwards all committers will switch to the newly created development
+ branch. It is highly recommended to ensure that all the changes done on the development
+ branch are also checked into the main development branch. Open JIRA issues will be
+ reviewed and rearranged accordingly. Many of the issues will get resolved during this
+ process and the remaining few will be accordingly prioritized and scheduled for a
+ future release. The unit tests and integration tests will be used extensively during
+ this critical period to keep the development branch in its most stable form.
+ </p>
+ <p>
+ Finally the release manager would trigger the release build, sign the generated artifacts
+ and host them on people.apache.org for review. A release vote will be called urging
+ all those interested to review the packs and provide feedback. Upon receiving the
+ necessary number of votes, a release tag will be created and the release artifacts will
+ be uploaded to the appropriate servers for distribution.
+ </p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Modified: synapse/branches/2.1/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/index.xml?rev=1222433&r1=1222432&r2=1222433&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/index.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/index.xml Thu Dec 22 20:37:58 2011
@@ -37,25 +37,37 @@
<p>
Apache Synapse is free and open source software distributed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License 2.0</a>.
- The latest version of Synaspe is <a href="download/2.0/download.cgi">v2.0</a>.
+ The latest version of Synaspe is <a href="download/2.1/download.cgi">v2.1</a>.
This release comes with a horde of new features, bug fixes, performance and
stability improvements.
</p>
</section>
- <section name="New in Version 2.0">
+ <section name="New in Version 2.1">
<ul>
- <li>New, fine-grained configuration model</li>
- <li>Hot deployment and hot update support for configuration artifacts</li>
- <li>Priority based mediation support</li>
- <li>Comprehensive eventing capabilities with WS-Eventing support</li>
- <li>Secure vault for encrypting passwords in configuration files</li>
- <li>File locking support in the VFS transport for concurrent polling</li>
- <li>URLRewrite medaitor for fast and simple URL rewriting</li>
- <li>Synapse configuration observer API</li>
- <li>Multiple identity support in the HTTPS transport</li>
- <li>Enhanced JMX monitoring support for the NHTTP transport</li>
- <li>Dead letter channel implementation (experimental)</li>
- <li>Synapse XAR Maven plugin for generating configuration artifacts</li>
+ <li>
+ Support for creating and managing REST APIs with URL patterns and URI templates
+ </li>
+ <li>
+ Define sequences and endpoints as templates and reuse seamlessly across the
+ whole configuration
+ </li>
+ <li>
+ Payload factory mediator for constructing custom XML payloads
+ </li>
+ <li>
+ Recipient list endpoint
+ </li>
+ <li>
+ HTTPD like access logging capability in the NHTTP transport
+ </li>
+ <li>
+ Message stores and message processors for implementing complex integration
+ patterns and advanced messaging scenarios
+ </li>
+ <li>
+ Receiving sequence support in the send mediator to make service chaining
+ easier
+ </li>
</ul>
</section>
<section name="Key Features">
@@ -88,5 +100,34 @@
Ruby, Groovy, etc.)</li>
</ul>
</section>
+ <section name="High Level Architecture">
+ <p>
+ Apache Synapse is designed to be lightweight and fast. The non-blocking HTTP
+ transport, the multi-threaded mediation engine and the streaming XML infoset combine
+ to ensure that Synapse can mediate very high volumes of messages through the service
+ bus with minimum delay and resource usage. Synapse also comes with comprehensive
+ logging capabilities, statistics collection and JMX monitoring support which are
+ crucial in production deployments.
+ </p>
+ <img src="images/synapse-arch.png"/>
+ <p>
+ Synapse uses the Apache Axis2 as the underlying Web Services engine. Therefore it
+ has outstanding support for Web Services and related standards such as SOAP and
+ WSDL. Tried and tested Axis2 modules like Apache Rampart and Apache Sandesha2 can be
+ used with Synapse with no configuration overhead. Using such external modules,
+ Apache Synapse supports a range of Web Services standards including WS-Security and
+ WS-Reliable Messaging. Synapse also makes use of the Axis2 clustering framework to
+ provide enterprise grade clustering support.
+ </p>
+ <p>
+ Synapse is configured using a simple, XML-based configuration language. The
+ configuration language and the related functional components are designed with SOA
+ best practices in mind. It is trivial to store configuration fragments in an external
+ SOA registry and import them to the mediation engine on demand. Synapse ships with a
+ large collection of mediators that can be used to implement even the most complex
+ enterprise integration scenarios. If necessary, the mediation engine can be extended
+ by developing custom mediators using Java or your favorite scripting language.
+ </p>
+ </section>
</body>
</document>
Modified: synapse/branches/2.1/src/site/xdoc/userguide/config.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/config.xml?rev=1222433&r1=1222432&r2=1222433&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/config.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/userguide/config.xml Thu Dec 22 20:37:58 2011
@@ -107,7 +107,7 @@
diagram illustrates different functional components of Synapse and how they interact
with each other.
</p>
- <!-- Image goes here -->
+ <img src="../images/synapse-flow.png"/>
<p>
All the functional components of the Synapse configuration are configured through
XML files. The Synapse configuration language governs the XML syntax used to define
Modified: 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=1222433&r1=1222432&r2=1222433&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/userguide/mediators.xml Thu Dec 22 20:37:58 2011
@@ -57,7 +57,12 @@
<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="#DBLookup">DBLookup Mediator</a></li>
+ <li><a href="#DBReport">DBReport Mediator</a></li>
<li><a href="#Iterate">Iterate Mediator</a></li>
+ <li><a href="#RMSequence">RMSequence Mediator</a></li>
+ <li><a href="#Store">Store Mediator</a></li>
+ <li><a href="#Throttle">Throttle Mediator</a></li>
<li><a href="#Transaction">Transaction Mediator</a></li>
</ul>
</li>
@@ -817,7 +822,7 @@
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.
+ specified otherwise inside the 'configuration' sub-element.
</p>
</subsection>
<subsection name="Clone Mediator" id="Clone">
@@ -848,6 +853,125 @@
mediators.
</p>
</subsection>
+ <subsection name="DBLookup" id="DBLookup">
+ <p>
+ DB Lookup mediator is capable of executing an arbitrary SQL SELECT statement,
+ and then set some resulting values as local message properties on the message
+ context. The DB connection used maybe looked up from an external DataSource or
+ specified in-line, in which case an Apache DBCP connection pool is established
+ and used.
+ </p>
+ <div class="xmlConf"><dblookup>
+ <connection>
+ <pool>
+ (
+ <driver/>
+ <url/>
+ <user/>
+ <password/>
+ <property name="name" value="value"/>*
+ |
+ <dsName/>
+ <inClass/>
+ <url/>
+ <user/>
+ <password/>
+ )
+ </pool>
+ </connection>
+ <statement>
+ <sql>SELECT something FROM table WHERE something_else = ?</sql>
+ <parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>*
+ <result name="string" column="int|string"/>*
+ </statement>+
+</dblookup></div>
+ <p>
+ For in-lined data sources the following parameters have to be specified.
+ </p>
+ <ul>
+ <li>driver: Fully qualified class name of the database driver.</li>
+ <li>url: Database URL.</li>
+ <li>user: Username for database access.</li>
+ <li>password: Password for database access.</li>
+ </ul>
+ <p>
+ This new data source is based on Apache DBCP connection pools. This connection
+ pool support the following configuration properties:
+ </p>
+ <ul>
+ <li>autocommit = true | false</li>
+ <li>isolation = Connection.TRANSACTION_NONE | Connection.TRANSACTION_READ_COMMITTED | Connection.TRANSACTION_READ_UNCOMMITTED |
+ Connection.TRANSACTION_REPEATABLE_READ | Connection.TRANSACTION_SERIALIZABLE</li>
+ <li>initialsize = int</li>
+ <li>maxactive = int</li>
+ <li>maxidle = int</li>
+ <li>maxopenstatements = int</li>
+ <li>maxwait = long</li>
+ <li>minidle = int</li>
+ <li>poolstatements = true | false</li>
+ <li>testonborrow = true | false</li>
+ <li>testonreturn = true | false</li>
+ <li>testwhileidle = true | false</li>
+ <li>validationquery = String</li>
+ </ul>
+ <p/>
+ <p>
+ When an external data source is used the following parameters have to be
+ specified.
+ </p>
+ <ul>
+ <li>dsName: The name of the data source to be looked up.</li>
+ <li>icClass: Initial context factory class. The corresponding Java environment property is java.naming.factory.initial</li>
+ <li>url: The naming service provider URL. The corresponding Java environment property is java.naming.provider.url</li>
+ <li>user: Username corresponding to the Java environment property java.naming.security.principal</li>
+ <li>password: Password corresponding to the Java environment property java.naming.security.credentials</li>
+ </ul>
+ <p>
+ More than one statement can be included in the mediator configuration. SQL
+ statement may specify parameters which could be specified as values or XPath
+ expressions. The type of a parameter could be any valid SQL type. 'result'
+ sub-element contains 'name' and 'column' attributes which define the name
+ under which the result is stored in the Synapse message context, and a column
+ number or name respectively.
+ </p>
+ </subsection>
+ <subsection name="DBReport" id="DBReport">
+ <p>
+ DB Report mediator is quite similar to the
+ <a href="#DBReport">DB Lookup</a>
+ mediator, but writes data into a database instead of reading data from a
+ database.
+ </p>
+ <div class="xmlConf"><dbreport useTransaction=(true|false)>
+ <connection>
+ <pool>
+ (
+ <driver/>
+ <url/>
+ <user/>
+ <password/>
+ <property name="name" value="value"/>*
+ |
+ <dsName/>
+ <icClass/>
+ <url/>
+ <user/>
+ <password/>
+ )
+ </pool>
+ </connection>
+ <statement>
+ <sql>INSERT INTO table VALUES (?, ?, ?, ?)</sql>
+ <parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>*
+ </statement>+
+</dblreport></div>
+
+ <p>
+ This mediator executes the specified SQL INSERT on the database specified
+ in-line or as an external data source. For information on configuring database
+ related mediators, refer<a href="#DBReport">DB Lookup mediator guide</a>.
+ </p>
+ </subsection>
<subsection name="Iterate Mediator" id="Iterate">
<p>
Iterate mediator splits the message into number of different messages
@@ -879,6 +1003,58 @@
responses of messages that are created using nested iterate mediators.
</p>
</subsection>
+ <subsection name="RMSequence" id="RMSequence">
+ <p>
+ RM Sequence mediator can be used to create a sequence of messages to communicate
+ via WS-Reliable Messaging with a WS-RM enabled endpoint.
+ </p>
+ <div class="xmlConf"><RMSequence (correlation="xpath" [last-message="xpath"]) | single="true" [version="1.0|1.1"]/></div>
+ <p>
+ The simplest use case of this mediator sets 'single' attribute to "true",
+ which means that only one message is involved in the same sequence. However, if
+ multiple messages should be sent in the same sequence, 'correlation' attribute
+ should be used with an XPath expression that selects a unique element value from
+ the incoming message. With the result of the XPath expression, Synapse can group
+ messages together that belong to the same sequence. To close the sequence
+ neatly, an XPath expression should be specified for the last message of the
+ sequence as well. The optional 'version' attribute, which specifies the WS-RM
+ specification version as 1.0 or 1.1, defaults to 1.0.
+ </p>
+ </subsection>
+ <subsection name="Store" id="Store">
+ <p>
+ Store mediator can be used to store the current message in a specific message
+ store.
+ </p>
+ <div class="xmlConf"><store messageStore="string" [sequence="sequence-ref"]></div>
+ <p>
+ In the mediator configuration 'messageStore' attribute is used to specify the
+ message store to store the message in. The optional 'sequence' attribute
+ specifies a sequence through which the message is sent before storing it.
+ </p>
+ </subsection>
+ <subsection name="Throttle Mediator" id="Throttle">
+ <p>
+ Throttle mediator can be used for rate limiting as well as concurrency based
+ limiting. A WS-Policy dictates the throttling configuration and can be
+ specified inline or loaded from the registry. Please refer to the samples
+ document for sample throttling policies.
+ </p>
+ <div class="xmlConf"><throttle [onReject="string"] [onAccept="string"] id="string">
+ (<policy key="string"/> | <policy>..</policy>)
+ <onReject>..</onReject>?
+ <onAccept>..</onAccept>?
+</throttle></div>
+ <p>
+ The throttle mediator could be used in the request path for rate limiting and
+ concurrent access limiting. When it's used for concurrent access limitation,
+ the same throttle mediator 'id' must be triggered on the response flow so that
+ completed responses are deducted from the available limit. (i.e. two instances
+ of the throttle mediator with the same 'id' attribute in the request and
+ response flows). 'onReject' and 'onAccept' sequence references or inline
+ sequences define how accepted and rejected messages are handled.
+ </p>
+ </subsection>
<subsection name="Transaction Mediator" id="Transaction">
<p>
Transaction mediator can provide transaction facility for a set of mediators
@@ -891,14 +1067,14 @@
</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>
+ <li>new: Initiate a new transaction.</li>
+ <li>use-existing-or-new: If a transaction already exists
+ continue it, otherwise create a new transaction.</li>
+ <li>fault-if-no-tx: Go to the error handler if no transaction exists.</li>
+ <li>commit: End the transaction.</li>
+ <li>rollback: Rollback a transaction.</li>
+ <li>suspend: Pause a transaction.</li>
+ <li>resume: Resume a paused transaction.</li>
</ul>
</subsection>
</section>
Modified: synapse/branches/2.1/src/site/xdoc/userguide/samples.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples.xml?rev=1222433&r1=1222432&r2=1222433&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples.xml Thu Dec 22 20:37:58 2011
@@ -247,7 +247,7 @@
<subsection name="REST API">
<p>
<ul>
- <li><a href="samples/sample800.html">Sample 800: Introduction to REST API</a></li>
+ <li><a href="samples/sample800.html">Sample 800: Introduction to REST APIs</a></li>
</ul>
</p>
</subsection>
Modified: synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml?rev=1222433&r1=1222432&r2=1222433&view=diff
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml (original)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml Thu Dec 22 20:37:58 2011
@@ -23,11 +23,8 @@
<title>Apache Synapse - Sample 800</title>
</properties>
<body>
- <section name="Sample 800: Introduction to REST API">
+ <section name="Sample 800: Introduction to REST APIs">
<div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse">
-
- <!-- You can add any flat sequences, endpoints, etc.. to this synapse.xml file if you do
- *not* want to keep the artifacts in several files -->
<api name="StockQuoteAPI" context="/stockquote">
<resource uri-template="/view/{symbol}" methods="GET">
<inSequence>
@@ -68,7 +65,11 @@
</definitions></div>
<subsection name="Objective">
<p>
- Objective: Introduction to REST API
+ APIs in Synapse provide a convenient approach for receiving and processing
+ REST traffic through the service bus. APIs can be used to receive specific
+ types of RESTful invocations and then process them through a set of user
+ defined resources. This sample is aimed at introducing the basic capabilities
+ of APIs and how they are configured to front existing services.
</p>
</subsection>
<subsection name="Pre-requisites">