<?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 - Upgrading to the Latest Version</title>
    </properties>
	<body>
        <section name="Upgrading to the Latest Version">
            <p>
                If you are using an older version of Synapse (1.x) and now looking to migrate to
                the latest versions (2.x) this document would be a good starting point. This
                article provides information on steps that need to be carried out to smoothly
                migrate from an older release of Synapse to the latest version.
            </p>
        </section>
		<section name="Contents">
				<ul>
					<li>
						<a href="#General_comments">General comments</a>
					</li>
					<li>
						<a href="#Upgrading_from_1.2_to_2.1">Upgrading from 1.2 to 2.1</a>
						<ul>
							<li>
								<a href="#Configuration_file_vs_multi_XML_configuration">Configuration file vs multi XML configuration</a>
							</li>
							<li>
								<a href="#Endpoint_URLs_for_proxy_services">Endpoint URLs for proxy services</a>
							</li>
							<li>
								<a href="#Mediator_Deployer">Mediator Deployer</a>
							</li>
							<li>
								<a href="#Main_Sequence">Main Sequence</a>
							</li>
							<li>
								<a href="#Filter_Mediator">Filter Mediator</a>
							</li>
							<li>
								<a href="#Migration_Tool">Migration Tool</a>
							</li>
							<li>
								<a href="#Custom_Extensions_and_API_changes">Custom Extensions and API changes</a>
							</li>
						</ul>
					</li>
				</ul>
		</section>
		<section name="General comments" id="General_comments">
			<p>
                If you are using custom extensions (mediators, startups, etc.) implemented in Java and
				depending on Synapse APIs, you should go through the following process before upgrading
				to a new release:
			</p>
			<ol type="1">
				<li>
                    Compile the extension with the libraries from the Synapse release you are
					currently using and check for any deprecation warnings. You should change your
                    code to eliminate all those warnings. In general the Javadoc of the
					deprecated class or method gives you a hint on how to change your code. Test all
                    your changes with your current Synapse release.
				</li>
				<li>
                    Recompile and test the extension with the libraries from the new Synapse release.
					We try to avoid to introduce incompatible changes to Synapse's core APIs between
					releases (except if the related classes or methods were deprecated in the previous
					release). However, it is not always possible to maintain compatibility. In addition
					your code might depend on features that are not part of the core API. Therefore,
                    even if you don't use deprecated methods and classes, there is no guarantee that
                    your code will not break when upgrading to a new release and you always need to
                    recompile and test them before deploying to the new release.
				</li>
				<li>
                    Upgrade your Synapse installation and deploy the new version of your extensions.
                </li>
			</ol>
			<p>
                If you are skipping releases when upgrading your installation, you might nevertheless
                want to go through the first step for all the intermediate releases. This will make
                the migration easier.
			</p>
		</section>
		
		<section name="Upgrading from 1.2 to 2.1" id="Upgrading_from_1.2_to_2.1">
			<subsection name="Configuration file vs multi XML configuration" id="Configuration_file_vs_multi_XML_configuration">
				<p>
                    In 1.2 you have been using a single synapse.xml file which resides on the
                    repository/conf directory of the distribution, where as on 2.1 we have structured
                    this into a configuration repository with multiple directories to have different
                    artifact types and each and every artifact configuration to reside on a different
                    files inside the desired repository directory. This repository directory on the 2.1
					release resides in the repository/conf directory too, and named as synapse-config.
					The repository directory structure inside the synapse-config directory
					looks like follows;
				</p>
				<div class="xmlConf">synapse-config
  /api
  /endpoints
  /event-sources
  /local-entries
  /priority-executors
  /proxy-services
  /sequences
	 main.xml
	 fault.xml
  /tasks
  /templates
	 registry.xml
	 synapse.xml</div>
				<p>
                    As you can see in the above sketch of the repository though it is a repository based
					configuration, it also supports the old style single flat synapse.xml file in which
                    case it has to reside inside the root of the repository.
				</p>
				<p>
					So the easiest way to migrate the configuration is to move your already existing
                    synapse.xml file in repository/conf directory in 1.2 version into the
                    repository/conf/synapse-config directory of the 2.x version. <em>Note: When doing this
                    migration you should also delete the main.xml and fault.xml files which are there on the
                    sequences directory of the repository, otherwise there will be 2 main and fault
                    sequences one coming from the sequences directory and the other coming from your just
                    copied synapse.xml file.</em>
				</p>
			</subsection>
			<subsection name="Endpoint URLs for proxy services" id="Endpoint_URLs_for_proxy_services">
				<p>
					In release 2.1 the endpoint URLs for proxy services have changed from
					<tt>/soap</tt> to <tt>/services</tt>. E.g. <tt>http://localhost:8280/services/StockQuote</tt>
					should be used instead of <tt>http://localhost:8280/soap/StockQuote</tt>.
				</p>
			</subsection>
			<subsection name="MediatorDeployer" id="Mediator_Deployer">
				<p>
					Release 1.3 has enhanced capabilities for extension deployment. While in 1.2 extension
					deployment was limited to mediators bundled as simple JAR files, 1.3 extended this
                    support to tasks and defined a new archive format (XAR) that allows to bundle
                    these extensions together with their dependency JARs (see
					<a class="externalLink" href="http://issues.apache.org/jira/browse/SYNAPSE-377">SYNAPSE-377</a>
					for more details). Enabling these features requires changes to the <tt>axis2.xml</tt>
					configuration file. In 1.2 the deployer was configured as follows:
				</p>
				<div class="xmlConf">&lt;deployer extension=&quot;jar&quot; directory=&quot;mediators&quot;
        class=&quot;org.apache.synapse.core.axis2.MediatorDeployer&quot;/&gt;</div>
				<p>
                    In 2.1 the suggested configuration is:
                </p>
				<div class="xmlConf">&lt;deployer extension=&quot;xar&quot; directory=&quot;extensions&quot;
        class=&quot;org.apache.synapse.deployers.ExtensionDeployer&quot;/&gt; </div>
				<p>
                    It is possible to have multiple configuration entries for the extension deployer
                    with different settings. For example, if you used the deployer in 1.2 you might
                    want to have the following configuration:
				</p>
				<div class="xmlConf">&lt;deployer extension=&quot;jar&quot; directory=&quot;mediators&quot;
        class=&quot;org.apache.synapse.deployers.ExtensionDeployer&quot;/&gt;
&lt;deployer extension=&quot;xar&quot; directory=&quot;extensions&quot;
	    class=&quot;org.apache.synapse.deployers.ExtensionDeployer&quot;/&gt;</div>
			</subsection>
			<subsection name="JMS transport" id="JMS_transport">
				<p>
					The way the JMS transport determines the content type of incoming messages has
                    slightly changed between Synapse 1.2 and 2.x. The mechanism is also more flexible.
                    See SYNAPSE-304 and SYNAPSE-424 for the reasons of this change and refer to the
					<a class="externalLink" href="http://ws.apache.org/commons/transport/">WS-Commons Transport project</a>
					for documentation.
				</p>
			</subsection>
			<subsection name="Main Sequence" id="Main_Sequence">
				<p>
					On Synapse 1.2 you could have mediator configuration on the top level definitions
                    tag and they were treated as the <strong>main</strong> sequence if there is no
                    main sequence defined in the configuration. How ever removing the conflict of having
                    top level mediators and a main sequence leading the synapse to fail to start on
                    2.x Synapse configuration builder simply ignores the top level mediators. So you
                    need to wrap the top level mediators, if there are any, with the sequence named
					<strong>main</strong> on the new 2.1 version.
				</p>
				<p>
					To further explain this lets have a look at the following valid configuration bit
					(this is the sample 0 configuration) on the 1.2;
					<div class="xmlConf">&lt;definitions xmlns=&quot;http://ws.apache.org/ns/synapse&quot;&gt;
    &lt;!-- log all attributes of messages passing through --&gt;
    &lt;log level=&quot;full&quot;/&gt;

    &lt;!-- Send the message to implicit destination --&gt;
    &lt;send/&gt;
&lt;/definitions&gt;</div>
					which needs to be changed to the following configuration on 2.1
					<div class="xmlConf">&lt;definitions xmlns=&quot;http://ws.apache.org/ns/synapse&quot;&gt;

    &lt;sequence name=&quot;main&quot;&gt;
        &lt;!-- log all attributes of messages passing through --&gt;
        &lt;log level=&quot;full&quot;/&gt;

        &lt;!-- Send the message to implicit destination --&gt;
        &lt;send/&gt;
    &lt;sequence/&gt;

&lt;/definitions&gt;</div>
				</p>
			</subsection>
			<subsection name="Filter Mediator" id="Filter_Mediator">
				<p>
                    From 2.1 onwards Synapse filter mediator supports the else close as well, and hence
					the filter matching set of mediators has to be enclosed within a &lt;then&gt; element.
                </p>
				<p>
					If we consider the following sample from the 1.2 version of synapse;
					<div class="xmlConf">&lt;filter source=&quot;get-property('To')&quot; regex=&quot;.*/StockQuote.*&quot;&gt;
    &lt;send&gt;
        &lt;endpoint&gt;
            &lt;address uri=&quot;http://localhost:9000/soap/SimpleStockQuoteService&quot;/&gt;
        &lt;/endpoint&gt;
    &lt;/send&gt;
    &lt;drop/&gt;
&lt;/filter&gt;</div>
					the equivalent configuration for the 2.1 release is going to be;
					<div class="xmlConf">&lt;filter source=&quot;get-property('To')&quot; regex=&quot;.*/StockQuote.*&quot;&gt;
    &lt;then&gt;
        &lt;send&gt;
            &lt;endpoint&gt;
                &lt;address uri=&quot;http://localhost:9000/soap/SimpleStockQuoteService&quot;/&gt;
            &lt;/endpoint&gt;
        &lt;/send&gt;
        &lt;drop/&gt;
    &lt;then/&gt;
&lt;/filter&gt;</div>
					You could also add an else close to this conditional statement as follows on 2.x
                    which is not possible on 1.2
					<div class="xmlConf">&lt;filter source=&quot;get-property('To')&quot; regex=&quot;.*/StockQuote.*&quot;&gt;
    &lt;then&gt;
        &lt;send&gt;
            &lt;endpoint&gt;
                &lt;address uri=&quot;http://localhost:9000/soap/SimpleStockQuoteService&quot;/&gt;
            &lt;/endpoint&gt;
        &lt;/send&gt;
        &lt;drop/&gt;
    &lt;then/&gt;
    &lt;else/&gt;
        &lt;log/&gt;
    &lt;else/&gt;
&lt;/filter&gt;</div>
				</p>
			</subsection>
			<subsection name="Migration Tool" id="Migration_Tool">
				<p>
                    In general it is recommended to run the configuration through the migration tool
					provided with the Synapse 2.x release, on your synapse 1.2 configuration before
                    using it with the 2.1.
				</p>
				<p>
					To run the migration tool execute the synapse-config-migrator.sh by passing the
					synapse.xml file location of the
					1.2 configuration. Which will create the 2.1
					compatible configuration with the .new suffix. For example;
					<pre>sh bin/synapse-config-migrator.sh synapse-i1.2/repository/conf/synapse.xml</pre>
				</p>
			</subsection>
			<subsection name="Custom Extensions and API changes" id="Custom_Extensions_and_API_changes">
				<p>
                    Even though there is a migration tool it just takes care of your configuration and not
					custom extensions that you have done for example like CustomMediators or Tasks
                    and so forth. There are some API changes that affect your custom extensions
                    unfortunately. This section tries to list all the public API changes which affects
                    the backward compatibility of the custom extensions that you have been running
                    with the 1.2 version of Synapse.
				</p>
				<table class="bodyTable">
					<tr class="a">
						<th>Class</th>
						<th>Method</th>
						<th>Change Description</th>
					</tr>
					<tr class="b">
						<td>
							<a href="../apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html">AbstractMediatorFactory</a>
						</td>
						<td>createMediator(OMElement)</td>
						<td>
							This was the method that you have been overwriting on the 1.2 version to
							implement a new custom mediator factory to build the mediator by looking at
							the XML configuration. On the 2.1 version you should be extending the
							<a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html#createSpecificMediator(org.apache.axiom.om.OMElement,%20java.util.Properties)">createSpecificMediator(OMElement, Properties)</a>
							. Note that in the process of changing the method to be extended, the method
							<a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html#createMediator(org.apache.axiom.om.OMElement,%20java.util.Properties)">createMediator</a>
							method has been changed to be final. From a users point of view of this
                            interface he/she should be using the createMediator method which is what
                            Synapse does.
						</td>
					</tr>
					<tr class="a">
						<td>
							<a href="../apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html">AbstractMediatorSerializer</a>
						</td>
						<td>serializeMediator(Mediator)</td>
						<td>
							This was the method that you have been overwriting on the 1.2 version to
							implement a new custom mediator serializer to serialize to the XML
                            Configuration by walking through the mediator properties. On the 2.1
                            version you should be extending the
							<a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html#serializeSpecificMediator(org.apache.synapse.Mediator)">serializeSpecificMediator(Mediator)</a>
							. Note that in the process of changing the method to be extended, the method
							<a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html#serializeMediator(org.apache.axiom.om.OMElement,%20org.apache.synapse.Mediator)">serializeMediator</a>
							method has been changed to be final. From a users point of view of this
                            interface he/she should be using the serializeMediator method which is
                            what Synapse does.
						</td>
					</tr>
				</table>
				<p>
					Further to that if you have been using
					<a href="../apidocs/org/apache/synapse/ServerManager.html">ServerManager</a>
					class you may have noticed that the class is no more a singleton and doesn't have
                    the static getInstance method. Also note that the common utilities like data
                    sources JMX and RMI registration stuff have been moved to a new module with
                    org.apache.synapse.commons package name.
				</p>
				<p>
					On the configuration building front all entities are given a properties map to
                    construct its instance and that has been used to pass in any additional information
                    required like RESOLVE_ROOT, or SYNAPSE_HOME startup parameters. For example if you
                    look at the
					<a href="../apidocs/org/apache/synapse/config/xml/MediatorFactoryFinder.html">MediatorFactoryFinder</a>
					class the
					<a href="../apidocs/org/apache/synapse/config/xml/MediatorFactoryFinder.html#getMediator(org.apache.axiom.om.OMElement,%20java.util.Properties)">getMediator</a>
					method is expecting a properties map apart from the OMElement argument.
					It is safe to pass in a empty properties map if you are using these methods for
                    any testing purposes or even in cases where you do not resolve dependencies.
				</p>
			</subsection>
		</section>
	</body>
</document>