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 [3/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/deployment.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/deployment.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/deployment.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/deployment.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,346 @@
+<?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 - Deployment Guide</title>
+ </properties>
+ <body>
+ <section name="Contents">
+ <ul>
+ <li>
+ <a href="#Platform_requirements">Platform requirements</a>
+ </li>
+ <li>
+ <a href="#Overview_of_available_deployment_options">Overview of available deployment options</a>
+ </li>
+ <li>
+ <a href="#Stand-alone_deployment">Stand-alone deployment</a>
+ <ul>
+ <li>
+ <a href="#Using_the_standard_binary_distribution">Using the standard binary distribution</a>
+ </li>
+ <li>
+ <a href="#Using_Maven_to_build_a_custom_distribution">Using Maven to build a custom distribution</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#WAR_deployment">WAR deployment</a>
+ </li>
+ </ul>
+ </section>
+ <section name="Platform requirements" id="Platform_requirements">
+
+ <p>
+ Synapse requires Java 1.5 or higher and has been tested on Java runtime environments
+ from Sun, IBM and Apple. Note that the recommended Java version is 1.6. Synapse is
+ used on various operation systems, including Linux, Mac OS X, Solaris, Windows and AIX,
+ as well as mainframe environments. The recommended operation system for production use
+ is Linux since it offers a wider range of options to tune the TCP/IP stack. This is
+ important to optimize the performance of the NIO HTTP transport.
+ </p>
+ <p>
+ When selecting the environment for deployment, the following known issues should be taken into account:
+ </p>
+ <ul>
+ <li>
+ The <tt>synapse.bat</tt> and <tt>synapse.sh</tt> scripts included in the binary
+ distribution use the <tt>-server</tt> option which is not supported by IBM's JRE.
+ This problem can be easily solved by manually editing these scripts to
+ remove the unsupported <tt>-server</tt> option. See
+ <a class="externalLink" href="https://issues.apache.org/jira/browse/SYNAPSE-454">SYNAPSE-454</a>
+ .
+ </li>
+ <li>
+ In the past several issues related to subtle concurrency problems have been reported
+ with the non-blocking HTTP transport (which is the recommended HTTP implementation
+ for Synapse) when used on more "exotic" platforms. While this has been
+ improved it is recommended to thoroughly test the HTTP transport before deploying
+ Synapse in a production environment based on these platforms. Please don't hesitate
+ to report any issues using JIRA or by posting a message on the mailing list.
+ </li>
+ </ul>
+ </section>
+
+ <section name="Overview of available deployment options" id="Overview_of_available_deployment_options">
+
+ <p>Synapse can be deployed in two different ways:</p>
+ <ul>
+ <li>Stand-alone, i.e. as an independently managed Java process.</li>
+ <li>
+ As a J2EE application (WAR) deployed into a simple servlet container (e.g. Tomcat)
+ or a full-featured J2EE application server.
+ </li>
+ </ul>
+ <p>
+ Since Synapse doesn't rely on any container API, the features offered are the same in
+ both deployment scenarios, with very few exceptions:
+ </p>
+ <ul>
+ <li>
+ There is a minor issue that prevents classpath resources from being used in a
+ WAR deployment. See <a class="externalLink" href="https://issues.apache.org/jira/browse/SYNAPSE-207">SYNAPSE-207</a>
+ .
+ </li>
+ <li>
+ When deployed as a WAR file, Synapse can be configured with the standard Axis2
+ servlet based HTTP transport: while the recommended HTTP implementation for Synapse
+ is the NIO HTTP transport, there might be situations where it is preferable or
+ mandatory to use the HTTP protocol implementation of the application server.
+ </li>
+ </ul>
+ <p>
+ In some scenarios Synapse is used to proxy services that are deployed themselves on
+ an application server. In these cases it would be interesting to deploy Synapse on
+ the same application server and use an in-VM transport instead of HTTP to communicate
+ with these services. Note that for the moment no production-grade implementation of
+ this type of transport exists yet for Axis2, but this might change in the future.
+ </p>
+ <p>
+ Since the features offered are almost the same, the differences between the two
+ deployment options are mainly related to packaging and operational considerations:
+ </p>
+ <ul>
+ <li>
+ Many IT departments prefer deploying J2EE applications than managing stand-alone
+ Java processes, because this allows them to leverage the management and monitoring
+ facilities offered by the application server.
+ </li>
+ <li>
+ If the use case relies on JNDI resources such as JMS connection factories,
+ JDBC data source and transactions it might be easier to set up and configure these
+ resources when Synapse is deployed directly on the application
+ server that hosts these resources.
+ </li>
+ </ul>
+ </section>
+
+ <section name="Stand-alone deployment" id="Stand-alone_deployment">
+ <subsection name="Using the standard binary distribution" id="Using_the_standard_binary_distribution">
+ <p>
+ The easiest way to get started with a stand-alone deployment is using the standard
+ binary distribution ZIP or tarball (see <a href="download.html">download.html</a>).
+ It already contains everything that is needed to run Synapse stand-alone and you
+ only need to customize it according to your requirements:
+ </p>
+ <ul>
+ <li>
+ Place your mediation configuration in <tt>repository/conf/synapse-config</tt>
+ directory.
+ </li>
+ <li>
+ Place any additional files such as WSDL files, endpoint definitions, etc.
+ referenced by your configuration in the <tt>repository</tt> directory.
+ </li>
+ <li>
+ Customize <tt>repository/conf/axis2.xml</tt>
+ to enable and disable transports according to your needs.
+ </li>
+ <li>
+ Add any additional libraries required by your mediation to the
+ <tt>lib</tt>directory. Alternatively modify <tt>repository/conf/wrapper.conf</tt>
+ to add directories and JAR files to the classpath.
+ </li>
+ <li>
+ Add any required modules to <tt>repository/modules</tt>.
+ </li>
+ <li>
+ If necessary, modify <tt>lib/log4j.properties</tt> to configure logging.
+ </li>
+ </ul>
+ <p>
+ Since the standard binary distribution also contains samples and documentation,
+ you might want to remove the following folders:
+ </p>
+ <ul>
+ <li>
+ <tt>docs</tt>
+ </li>
+ <li>
+ <tt>repository/conf/sample</tt>
+ </li>
+ <li>
+ <tt>samples</tt>
+ </li>
+ </ul>
+ <p>
+ The <tt>bin</tt> directory contains Unix and Windows scripts to run Synapse:
+ </p>
+ <ul>
+ <li>
+ <tt>synapse.sh</tt> and <tt>synapse.bat</tt> allow to run Synapse in non
+ daemon mode.
+ </li>
+ <li>
+ <tt>synapse-daemon.sh</tt> is a Sys V init script that can be used on Unix
+ systems to start and stop Synapse in daemon mode.
+ </li>
+ <li>
+ <tt>install-synapse-service.bat</tt> and <tt>uninstall-synapse-service.bat</tt>
+ can be used on Windows to install Synapse as an NT service.
+ </li>
+ </ul>
+ </subsection>
+ <subsection name="Using Maven to build a custom distribution" id="Using_Maven_to_build_a_custom_distribution">
+ <p>
+ Building a custom Synapse package based on the standard binary distribution is a
+ manual process and this has some drawbacks:
+ </p>
+ <ul>
+ <li>
+ The JAR files required to run Synapse must be selected manually and it is not easy to identify unused JARs
+ that could be safely removed.
+ </li>
+ <li>
+ The process is not suitable if there is a requirement for strict configuration management. In particular:
+ <ul>
+ <li>
+ Because of the large number of JAR files, managing the artifacts using
+ a source control repository is not practical.
+ </li>
+ <li>
+ The process is not repeatable and there is no way to go back to a
+ previous version of the artifacts.
+ </li>
+ </ul>
+ </li>
+ <li>
+ When upgrading to a newer version of Synapse (or when working with snapshot
+ versions), it is necessary either to manually replace the JARs in the current
+ package or to start again from a new version of the standard binary
+ distribution.
+ </li>
+ <li>
+ If Synapse needs to be deployed with slightly different configurations in
+ multiple environments (e.g. test and production), the corresponding packages
+ need to be prepared manually.
+ </li>
+ </ul>
+ <p>
+ Note that these problems not only arise in the development and maintenance phases
+ of a project, but also when doing proof of concepts that you want to keep in a safe
+ place for later reuse. One approach to overcome these difficulties is to use Maven
+ to assemble a custom package. When used correctly, this approach solves all of the
+ issues identified above. In particular Maven's dependency management together with
+ the excellent <a class="externalLink" href="http://maven.apache.org/plugins/maven-assembly-plugin/">assembly plugin</a>
+ can be used to automatically select the relevant JARs to include and pull them
+ from Maven repositories. The remaining artifacts required to assemble the package
+ can then be easily stored in a source control repository.
+ </p>
+ <p>
+ Synapse provides a Maven archetype that allows to set up this kind of project in
+ only a few simple steps. To begin with, change to the directory where you want to
+ create the project and issue the following command:
+ </p>
+ <div class="command">mvn archetype:generate -DarchetypeCatalog=http://synapse.apache.org</div>
+ <p>
+ In case of problems, you can try to use the latest version of the archetype catalog:
+ </p>
+ <div class="command">mvn archetype:generate -DarchetypeCatalog=http://svn.apache.org/repos/asf/synapse/trunk/java/src/site/resources</div>
+ <p>
+ Finally, if you have build Synapse from sources, you don't need to specify a
+ catalog at all: the archetype is added automatically to the local catalog during
+ the build.
+ </p>
+ <p>
+ In any case, when prompted by Maven, select <tt>synapse-package-archetype</tt>
+ for the Synapse version you want to use. In the next step enter the values for
+ <tt>groupId</tt>, <tt>artifactId</tt> and <tt>version</tt> for your project. You
+ will also be prompted for a package name. Since the archetype doesn't contain any source
+ code, this value is irrelevant and you can continue with the default value.
+ </p>
+ <p>
+ At this stage a Maven project has been created in a sub-directory with the same
+ name as the <tt>artifactId</tt> specified previously. You should now customize this
+ projects according to your needs:
+ </p>
+ <ul>
+ <li>
+ Add your mediation configuration to <tt>repository/conf/synapse-config</tt>
+ directory.
+ </li>
+ <li>
+ Customize the dependencies in <tt>pom.xml</tt>. In particular if additional
+ transports such as JMS are needed, add the required dependencies here. Additional
+ Axis2 modules should also be added here.
+ </li>
+ <li>
+ Enable and configure additional transports in <tt>repository/conf/axis2.xml</tt>.
+ </li>
+ <li>
+ Place any other files referenced by mediation configuration into the
+ <tt>repository</tt> directory.
+ </li>
+ </ul>
+ <p>
+ The project is built as usual with the following command:
+ </p>
+ <div class="command">mvn package</div>
+ <p>
+ This will create a ZIP file (in the <tt>target</tt> directory) containing
+ everything that is needed to run your custom Synapse configuration. You only
+ need to extract it and use the appropriate script in the <tt>bin</tt>
+ directory to start Synapse.
+ </p>
+ </subsection>
+ </section>
+ <section name="WAR deployment" id="WAR_deployment">
+ <p>
+ Synapse provides a standard WAR file that can be used to deploy mediation on a servlet
+ container or on a J2EE application server. Note that this WAR file is not part of the
+ downloadable distributions. It can be retrieved from the following location:
+ </p>
+ <ul>
+ <li>
+ <a class="externalLink" href="http://repo1.maven.org/maven2/org/apache/synapse/synapse-war/">http://repo1.maven.org/maven2/org/apache/synapse/synapse-war/</a>
+ for released versions.
+ </li>
+ <li>
+ <a class="externalLink" href="http://hudson.zones.apache.org/hudson/job/Synapse%20-%20Trunk/org.apache.synapse$synapse-war/">http://hudson.zones.apache.org/hudson/job/Synapse%20-%20Trunk/org.apache.synapse$synapse-war/
+ </a>
+ for snapshot versions.
+ </li>
+ </ul>
+ <p>
+ Customization of the Web application is similar to the stand-alone option, but the
+ default directory structure is different:
+ </p>
+ <ul>
+ <li>
+ <tt>synapse.xml</tt> and <tt>axis2.xml</tt> are placed into the <tt>WEB-INF/conf</tt>
+ directory. All other files referenced by your mediation should go to the
+ <tt>WEB-INF/repository</tt>
+ directory.
+ </li>
+ <li>
+ Additional libraries must be placed into the standard <tt>WEB-INF/lib</tt>
+ directory.
+ </li>
+ <li>
+ Axis2 modules are located in <tt>repository/modules</tt>.
+ </li>
+ <li>
+ <tt>log4j.properties</tt> is located in <tt>WEB-INF/classes</tt>.
+ </li>
+ </ul>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/extending.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/extending.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/extending.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/extending.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,485 @@
+<?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 - Extending Synapse</title>
+ </properties>
+ <body>
+ <div id="contentBox">
+ <section name="Apache Synapse ESB - Extending Synapse">
+ <p>
+ Apache Synapse provides a number of extension points so that
+ users can plug-in custom developed code to extend the
+ functionality of the ESB. While the built-in mediators are sufficient to implement
+ most integration scenarios, sometimes it is very helpful to be able to deploy some custom code into the
+ service bus and make the solution simpler. Most Synapse APIs are in Java and
+ therefore the users looking to extend Synapse are expected to have a
+ decent knowledge and experience in Java programming.
+ </p>
+ </section>
+ <section name="Writing custom Mediator implementations">
+
+ <p>
+ The primary interface of the Synapse API is the MessageContext
+ interface defined below. This essentially defines the per-message
+ context passed through the chain of mediators, for each and every
+ message received and processed by Synapse. Each message instance is
+ wrapped within a MessageContext instance, and the message context
+ is set with the references to the SynapseConfiguration and
+ SynapseEnvironment objects. The
+ <a href="apidocs/org/apache/synapse/config/SynapseConfiguration.html">SynapseConfiguration</a>
+
+ object holds the global configuration model that defines
+ mediation rules, local registry entries and other and configuration, while
+ the
+ <a href="apidocs/org/apache/synapse/core/SynapseEnvironment.html">SynapseEnvironment</a>
+
+ object gives access to the underlying SOAP implementation used -
+ Axis2. A typical mediator would need to manipulate the
+ MessageContext by referring to the SynapseConfiguration. However it
+ is strongly recommended that the SynapseConfiguration is not
+ updated by mediator instances as it is shared by all messages, and
+ may be updated by Synapse administration or configuration modules.
+ Mediator instances may store local message properties into the
+ MessageContext for later retrieval by successive mediators.
+ <br />
+ </p>
+ <h4>
+ <a class="externalLink"
+ href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/MessageContext.java?view=markup">MessageContext
+ Interface
+ </a>
+ </h4>
+ <div class="xmlConf">package org.apache.synapse;
+
+import ...
+
+public interface MessageContext {
+
+ /**
+ * Get a reference to the current SynapseConfiguration
+ *
+ * @return the current synapse configuration
+ */
+ public SynapseConfiguration getConfiguration();
+
+ /**
+ * Set or replace the Synapse Configuration instance to be used. May be used to
+ * programatically change the configuration at runtime etc.
+ *
+ * @param cfg The new synapse configuration instance
+ */
+ public void setConfiguration(SynapseConfiguration cfg);
+
+ /**
+ * Returns a reference to the host Synapse Environment
+ * @return the Synapse Environment
+ */
+ public SynapseEnvironment getEnvironment();
+
+ /**
+ * Sets the SynapseEnvironment reference to this context
+ * @param se the reference to the Synapse Environment
+ */
+ public void setEnvironment(SynapseEnvironment se);
+
+ /**
+ * Get the value of a custom (local) property set on the message instance
+ * @param key key to look up property
+ * @return value for the given key
+ */
+ public Object getProperty(String key);
+
+ /**
+ * Set a custom (local) property with the given name on the message instance
+ * @param key key to be used
+ * @param value value to be saved
+ */
+ public void setProperty(String key, Object value);
+
+ /**
+ * Returns the Set of keys over the properties on this message context
+ * @return a Set of keys over message properties
+ */
+ public Set getPropertyKeySet();
+
+ /**
+ * Get the SOAP envelope of this message
+ * @return the SOAP envelope of the message
+ */
+ public SOAPEnvelope getEnvelope();
+
+ /**
+ * Sets the given envelope as the current SOAPEnvelope for this message
+ * @param envelope the envelope to be set
+ * @throws org.apache.axis2.AxisFault on exception
+ */
+ public void setEnvelope(SOAPEnvelope envelope) throws AxisFault;
+
+ /**
+ * SOAP message related getters and setters
+ */
+ public ....get/set()...
+
+}</div>
+ <p>
+ The MessageContext interface is based on the Axis2
+ MessageContext interface, and uses the Axis2 EndpointReference and
+ SOAPEnvelope classes/interfaces. The purpose of this interface is
+ to capture a message as it flows through the system. As you will
+ see the message payload is represented using the SOAP infoset.
+ Binary messages can be embedded in the Envelope using MTOM or SwA
+ attachments using the AXIOM object model.
+ </p>
+ <h4>
+ <a class="externalLink"
+ href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/Mediator.java?view=markup">Mediator
+ interface
+ </a>
+ </h4>
+ <p>
+ The second key interface for mediator writers is the Mediator
+ interface:
+ </p>
+ <div class="xmlConf">package org.apache.synapse;
+
+import org.apache.synapse.MessageContext;
+
+/**
+ * All Synapse mediators must implement this Mediator interface. As a message passes
+ * through the synapse system, each mediator's mediate() method is invoked in the
+ * sequence/order defined in the SynapseConfiguration.
+ */
+public interface <span style="font-weight: bold;">Mediator </span>{
+
+ /**
+ * Invokes the mediator passing the current message for mediation. Each
+ * mediator performs its mediation action, and returns true if mediation
+ * should continue, or false if further mediation should be aborted.
+ *
+ * @param synCtx the current message for mediation
+ * @return true if further mediation should continue
+ */
+ public boolean mediate(MessageContext synCtx);
+
+ /**
+ * This is used for debugging purposes and exposes the type of the current
+ * mediator for logging and debugging purposes
+ * @return a String representation of the mediator type
+ */
+ public String getType();
+}</div>
+ <p>
+ A mediator can read and/or modify the message encapsulated in
+ the MessageContext in any suitable manner - adjusting the routing
+ headers or changing the message body. If the mediate() method
+ returns false, it signals to the Synapse processing model to stop
+ further processing of the message. For example, if the mediator is
+ a security agent it may decide that this message is dangerous and
+ should not be processed further. This is generally the exception as
+ mediators are usually designed to co-operate to rocess the message
+ onwards.
+ </p>
+ </section>
+
+ <h3>
+ Leaf and Node Mediators, List mediators and Filter mediators
+ </h3>
+ <p>
+ Mediators may be Node mediators (i.e. these that can contain
+ child mediators) or Leaf mediators (mediators that does not hold
+ any other child mediators). A Node mediator must implement the
+ org.apache.synapse.mediators.ListMediator interface listed below,
+ or extend from the
+ org.apache.synapse.mediators.AbstractListMediator.
+ </p>
+ <h4>
+ <a class="externalLink"
+ href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/ListMediator.java?view=markup">The
+ ListMediator interface
+ </a>
+ </h4>
+ <div class="xmlConf">package org.apache.synapse.mediators;
+
+import java.util.List;
+
+/**
+* The List mediator executes a given sequence/list of child mediators
+*/
+public interface ListMediator extends Mediator {
+ /**
+ * Appends the specified mediator to the end of this mediator's (children) list
+ * @param m the mediator to be added
+ * @return true (as per the general contract of the Collection.add method)
+ */
+ public boolean addChild(Mediator m);
+
+ /**
+ * Appends all of the mediators in the specified collection to the end of this mediator's (children)
+ * list, in the order that they are returned by the specified collection's iterator
+ * @param c the list of mediators to be added
+ * @return true if this list changed as a result of the call
+ */
+ public boolean addAll(List c);
+
+ /**
+ * Returns the mediator at the specified position
+ * @param pos index of mediator to return
+ * @return the mediator at the specified position in this list
+ */
+ public Mediator getChild(int pos);
+
+ /**
+ * Removes the first occurrence in this list of the specified mediator
+ * @param m mediator to be removed from this list, if present
+ * @return true if this list contained the specified mediator
+ */
+ public boolean removeChild(Mediator m);
+
+ /**
+ * Removes the mediator at the specified position in this list
+ * @param pos the index of the mediator to remove
+ * @return the mediator previously at the specified position
+ */
+ public Mediator removeChild(int pos);
+
+ /**
+ * Return the list of mediators of this List mediator instance
+ * @return the child/sub mediator list
+ */
+ public List getList();
+}</div>
+ <p>
+ A ListMediator implementation should call super.mediate(synCtx)
+ to process its sub mediator sequence. A FilterMediator is a
+ ListMediator which executes its sequence of sub mediators on
+ successful outcome of a test condition. The Mediator instance which
+ performs filtering should implement the FilterMediator interface.
+ </p>
+ <h4>
+ <a class="externalLink"
+ href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/FilterMediator.java?view=markup">FilterMediator
+ interface
+ </a>
+ </h4>
+ <div class="xmlConf">package org.apache.synapse.mediators;
+
+import org.apache.synapse.MessageContext;
+
+/**
+ * The filter mediator is a list mediator, which executes the given (sub) list of mediators
+ * if the specified condition is satisfied
+ *
+ * @see FilterMediator#test(org.apache.synapse.MessageContext)
+ */
+public interface <span style="font-weight: bold;">FilterMediator </span>extends ListMediator {
+
+ /**
+ * Should return true if the sub/child mediators should execute. i.e. if the filter
+ * condition is satisfied
+ * @param synCtx
+ * @return true if the configured filter condition evaluates to true
+ */
+ public boolean test(MessageContext synCtx);
+}</div>
+ </div>
+ <section name="Writing custom Configuration implementations for mediators">
+ <p>
+ You may write your own custom configurator for the Mediator
+ implementation you write without relying on the Class mediator or
+ Spring extension for its initialization. You could thus write a
+ MediatorFactory implementation which defines how to digest a custom
+ XML configuration element to be used to create and configure the
+ custom mediator instance. A MediatorSerializer implementation
+ defines how a configuration should be serialized back into
+ an XML configuration. The custom MediatorFactory &
+ MediatorSerializer implementations and the mediator class/es must be bundled in a JAR
+ file conforming to the J2SE Service Provider model (See the
+ description for Extensions below for more details and examples) and
+ placed into the SYNAPSE_HOME/lib folder, so that the Synapse
+ runtime could find and load the definition. Essentially this means
+ that a custom JAR file must bundle your class implementing the
+ Mediator interface, and the MediatorFactory implementation class and
+ contain two text files named
+ "org.apache.synapse.config.xml.MediatorFactory" and
+ "org.apache.synapse.config.xml.MediatorSerializer" which
+ will contain the fully qualified name(s) of your MediatorFactory
+ and MediatorSerializer implementation classes. You should also
+ place any dependency JARs into the same lib folder so that the
+ correct classpath references could be made.
+ The MediatorFactory interface listing is given below, which you
+ should implement, and its getTagQName() method must define the fully qualified
+ element of interest for custom configuration. The Synapse
+ initialization will call back to this MediatorFactory instance through the
+ createMediator(OMElement elem) method passing in this XML element,
+ so that an instance of the mediator could be created utilizing the
+ custom XML specification and returned. See the ValidateMediator and
+ the ValidateMediatorFactory classes under modules/extensions in the
+ Synapse source distribution for examples.
+ </p>
+ <h4>
+ <a class="externalLink"
+ href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorFactory.java?view=markup">The
+ MediatorFactory interface
+ </a>
+ </h4>
+ <div class="xmlConf">package org.apache.synapse.config.xml;
+
+import ...
+
+/**
+ * A mediator factory capable of creating an instance of a mediator through a given
+ * XML should implement this interface
+ */
+public interface MediatorFactory {
+ /**
+ * Creates an instance of the mediator using the OMElement
+ * @param elem
+ * @return the created mediator
+ */
+ public Mediator createMediator(OMElement elem);
+
+ /**
+ * The QName of this mediator element in the XML config
+ * @return QName of the mediator element
+ */
+ public QName getTagQName();
+}</div>
+ <h4>
+ <a class="externalLink"
+ href="http://svn.apache.org/viewvc/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorSerializer.java?view=markup">The
+ MediatorSerializer interface
+ </a>
+ </h4>
+ <div class="xmlConf">package org.apache.synapse.config.xml;
+
+import ...
+
+/**
+ * Interface which should be implemented by mediator serializers. Does the
+ * reverse of the MediatorFactory
+ */
+public interface MediatorSerializer {
+
+ /**
+ * Return the XML representation of this mediator
+ * @param m mediator to be serialized
+ * @param parent the OMElement to which the serialization should be attached
+ * @return the serialized mediator XML
+ */
+ public OMElement serializeMediator(OMElement parent, Mediator m);
+
+ /**
+ * Return the class name of the mediator which can be serialized
+ * @return the class name
+ */
+ public String getMediatorClassName();
+}</div>
+ </section>
+ <section name="Configuring mediators">
+ <p>
+ Mediators could access the Synapse registry to load resources
+ and configure the local behaviour. Refer to the Spring mediator and
+ Script mediator implementations for examples on how this could be
+ achieved.
+ </p>
+ <h4>
+ Loading of Extensions by the Synapse runtime
+ </h4>
+ <p>
+ Synapse loads available extensions from the runtime classpath
+ using the
+ <a class="externalLink"
+ href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Service%20Provider">J2SE
+ Service Provider model
+ </a>
+ . This essentially iterates over the available JAR files, for a META-INF/services directory within each file,
+ and looks for a text file with the name org.apache.synapse.config.xml.MediatorFactory
+ which contains a list of fully qualified classname that implement
+ the above interface, listing each class in a separate line. e.g. The
+ built-in synapse-extensions.jar contains the following structure
+ </p>
+ <div class="xmlConf">synapse-extensions.jar
+ /META-INF/services
+ org.apache.synapse.config.xml.MediatorFactory
+ org.apache.synapse.config.xml.MediatorSerializer
+ /... the implementation classes as usual...</div>
+ </section>
+
+
+ <section name="Writing Synapse Observers">
+ <p>
+ A Synapse observer is developed by either implementing the
+ org.apache.synapse.config.SynapseObserver interface or by
+ extending the org.apache.synapse.config.AbstractSynapseObserver
+ class. A Synapse observer is notified by the Synapse configuration
+ when new elements are added to the configuration and
+ when existing elements are removed from the configuration. The
+ following event handlers are available to the Synapse observer implementations.
+ </p>
+ <div class="xmlConf"> public void sequenceAdded(Mediator sequence);
+ public void sequenceRemoved(Mediator sequence);
+ public void entryAdded(Entry entry);
+ public void entryRemoved(Entry entry);
+ public void endpointAdded(Endpoint endpoint);
+ public void endpointRemoved(Endpoint endpoint);
+ public void proxyServiceAdded(ProxyService proxy);
+ public void proxyServiceRemoved(ProxyService proxy);
+ public void startupAdded(Startup startup);
+ public void startupRemoved(Startup startup);
+ public void eventSourceAdded(SynapseEventSource eventSource);
+ public void eventSourceRemoved(SynapseEventSource eventSource);</div>
+ <p>
+ The AbstractSynapseObserver provides default implementations to
+ all these event handlers. It simply logs any received events.
+ </p>
+ <p>
+ In situations where the custom code has access to the
+ SynapseConfiguration class observers can be directly registered
+ with the SynapseConfiguration by using
+ the registerObserver(SynapseObserver o) method. Otherwise
+ SynapseObserver implementations
+ can be defined in the synapse.properties file which resides in the
+ SYNAPSE_HOME/lib directory. The following example shows how two observers are
+ registered with the Synapse configuration using the
+ synapse.properties file.
+ </p>
+ <div class="xmlConf">synapse.observers=test.LoggingObserverImpl, test.SimpleObserverImpl</div>
+ </section>
+
+ <section name="Scheduled Tasks">
+ <p>
+ A scheduled task is a custom developed piece of Java code that
+ is scheduled in the ESB to execute periodically. A scheduled task
+ must implement the org.apache.synapse.task.Task
+ interface. This interface has a single 'execute' method. Once scheduled the
+ execute method is called by Synapse periodically.
+ </p>
+ <p>
+ Synapse also comes with a built-in task implementation known as
+ the MessageInjector.This task can be used to inject messages into
+ the service bus periodically. Refer sample 300 to see how to use the
+ MessageInjector task.
+ </p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/faq.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/faq.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/faq.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/faq.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,65 @@
+<?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>FAQ</title>
+ </properties>
+ <body>
+ <section name="Apache Synapse FAQs">
+ <p>
+ Welcome to Apache Synapse FAQs.
+ </p>
+ </section>
+
+
+
+ <section name="General(GeneralApache Synapse questions - Non technical)">
+
+ <ol>
+ <li>
+ What is Apache Synapse?
+ <ul>
+ <li>
+ Apache Synapse is a lightweight and high-performance Enterprise Service Bus (ESB).
+ </li>
+ </ul>
+ </li>
+ <p/>
+
+ <li>
+ What makes Apache Synapse unique?
+ <ul>
+ <li>
+ Apache Synapse is fast and able to handle thousands of concurrent connections
+ with constant memory usage. It comes with a rich set of mediators to
+ support almost any integration scenario out of the box. It is also easily
+ extensible and highly customizable.
+ </li>
+ </ul>
+ </li>
+ <p/>
+
+ </ol>
+ </section>
+
+
+
+ </body>
+</document>
Added: synapse/branches/2.1/src/site/xdoc/userguide/installation.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/installation.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/installation.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/installation.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,245 @@
+<?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 - Installation Guide</title>
+ </properties>
+ <body>
+ <section name="Apache Synapse Installation Guide">
+ <p>
+ Welcome to Apache Synapse Installation Guide. This guide provides information on,
+ </p>
+ <ul>
+ <li>
+ <a href="#Prerequisites">Prerequisites for Installing Apache Synapse</a>
+ </li>
+ <li>
+ <a href="#Distribution">Distribution Packages</a>
+ </li>
+ <li>
+ <a href="#Installing">Installing Synapse</a>
+ <ul>
+ <li>
+ <a href="#InstallingLinux">Installing on Linux/Unix</a>
+ </li>
+ <li>
+ <a href="#InstallingWin">Installing on MS Windows</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Building">Building Synapse Using the Source Distribution</a>
+ </li>
+ </ul>
+ </section>
+
+ <section name="Prerequisites for Installing Apache Synapse" id="Prerequisites">
+ <p>
+ You should have following pre-requisites installed on your system to run Apache
+ Synapse.
+ </p>
+ <table border="2">
+ <tbody>
+ <tr>
+ <td>
+ <a href="http://java.sun.com/javase/downloads/index.jsp">Java SE
+ Development Kit
+ </a>
+ </td>
+ <td>
+ 1.6.0_23 or higher (For instructions on setting up the JDK on different
+ operating systems, visit<a
+ href="http://www.oracle.com/technetwork/java/index.html">
+ Java homepage.
+ </a>)
+ <p/>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://ant.apache.org/">Apache Ant</a> - To run Synapse samples
+ </td>
+ <td>
+ <p>
+ To compile and run the sample clients, an Ant installation is
+ required.
+ Ant 1.7.0 version or higher is recommended.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://maven.apache.org/">Apache Maven</a> - To
+ build Synapse from the source
+ </td>
+ <td>
+ To build Apache Synapse from its source distribution, you will need
+ Maven 2.2.0 or later.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Memory
+ </td>
+ <td>
+ No minimum requirement - A heap size of 1GB is generally
+ sufficient to process typical SOAP messages. Requirements may vary
+ with larger message size and on the number of messages processed
+ concurrently.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Disk
+ </td>
+ <td>
+ No minimum requirement. The installation will require ~75 MB
+ excluding space allocated for log files and databases.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Operating System
+ </td>
+ <td>
+ Linux, Solaris, MS Windows - XP/2003/2008 (Not fully tested on Windows
+ Vista or Windows 7). Since Apache Synapse is a Java application, it will
+ generally be possible to run it on other operating systems with a
+ JDK 1.6.x runtime. Linux/Solaris is recommended for production
+ deployments.
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
+
+ <section name="Distribution Packages" id="Distribution">
+ <p>
+ The following distribution packages are available for <a
+ href="http://synapse.apache.org/download.html">download</a>.
+ </p>
+ <ol>
+ <li>
+ Binary Distribution: Includes binary files for both Linux and
+ MS Windows operating systems, compressed into a single a zip file. Recommended
+ for normal users.
+ </li>
+ <p/>
+ <li>
+ Source Distribution: Includes the source code for both Linux and MS Windows
+ operating systems, compressed into a single zip file which can be used to build
+ the binaries. Recommended for advanced users.
+ </li>
+ </ol>
+ </section>
+
+ <section name="Installing Synapse" id="Installing">
+ <p>
+ The following guide will take you through the binary distribution installation
+ on different platforms.
+ </p>
+ <subsection name="Installing on Linux/Unix" id="InstallingLinux">
+ <ol>
+ <li>
+ <a href="http://synapse.apache.org/download.html">Download</a> Apache
+ Synapse binary distribution.
+ </li>
+ <li>
+ Extract the downloaded zip archive to where you want Synapse installed
+ (e.g. into /opt).
+ </li>
+ <li>
+ Set the JAVA_HOME environment variable to your Java home using the export
+ command or by editing /etc/profile, and add the JAVA_HOME/bin
+ directory to your PATH.
+ </li>
+ <li>
+ Execute the Synapse start script or the daemon script from the bin
+ directory of your Synapse installation.
+ <br/>
+ i.e., ./synapse.sh OR ./synapse-daemon.sh start
+ </li>
+ <li>
+ Synapse is now ready to accept messages for mediation.
+ </li>
+ </ol>
+ </subsection>
+
+ <subsection name="Installing on MS Windows" id="InstallingWin">
+ <ol>
+ <li>
+ <a href="http://synapse.apache.org/download.html">Download</a> Apache
+ Synapse binary distribution.
+ </li>
+ <li>
+ Extract the downloaded zip archive to where you want Synapse installed
+ (e.g. into C:\Synapse).
+ </li>
+ <li>
+ Set the JAVA_HOME environment variable to your Java home using the set
+ command or Windows System Properties dialog, and add the JAVA_HOME\bin
+ directory to your PATH.
+ </li>
+ <li>
+ Execute the Synapse start script or the service installation script from
+ the bin directory of your Synapse installation.
+ <br/>
+ i.e., synapse.bat OR install-synapse-service.bat
+ </li>
+ <li>
+ Synapse is now ready to accept messages for mediation.
+ </li>
+ </ol>
+
+ </subsection>
+ </section>
+
+ <section name="Building Synapse Using the Source Distribution" id="Building">
+ <p>
+ Apache Synapse build is based on <a href="http://maven.apache.org/"> Apache
+ Maven 2</a>. Hence, it is a prerequisite to have Maven (version 2.2.0 or later)
+ installed in order to build Synapse from the source distribution. Instructions on
+ installing Maven 2 are available on the <a href="http://maven.apache.org/"> Maven
+ website</a>. Follow these steps to build Synapse after setting up Maven 2.
+ </p>
+ <ol>
+ <li>
+ <a href="http://synapse.apache.org/download.html">Download</a>
+ the source
+ distribution, which is available as a zip archive. All the necessary
+ build scripts are included with this distribution.
+ </li>
+ <li>
+ Extract the source archive to a directory of your choice.
+ </li>
+ <li>
+ Run <strong>mvn clean install</strong> command inside that directory to build
+ Synapse. Note that you will require a connection to the Internet for the Maven
+ build to download dependencies required for the build.
+ </li>
+ </ol>
+ <p>
+ This will create the complete set of release artifacts including the binary
+ distribution in the modules/distribution/target/ directory which can be installed
+ using the above instructions.
+ </p>
+ </section>
+ </body>
+</document>