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>
