<?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>Upgrade guide</title>
    </properties>
    <body>
        <section name="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>
                <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 1.3">
          <subsection name="Endpoint URLs for proxy services">
            <p>In release 1.3 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">
            <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 startups and defined a new archive format (XAR) that allows to bundle these extensions
            together with their dependency JARs (see
            <a 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>
<pre>
&lt;deployer extension="jar" directory="mediators" class="org.apache.synapse.core.axis2.MediatorDeployer"/>
</pre>
            <p>In 1.3 the suggested configuration is:</p>
<pre>
&lt;deployer extension="xar" directory="extensions" class="org.apache.synapse.deployers.ExtensionDeployer"/>
</pre>
            <p>Note that the XAR format is compatible with simple JAR files and that the
            <code>MediatorDeployer</code> class still exists in 1.3. Therefore the old configuration will
            still work. However you are strongly advised to replace references to the <code>MediatorDeployer</code>
            class as it will disappear in later releases.</p>
            <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>
<pre>
&lt;deployer extension="jar" directory="mediators" class="org.apache.synapse.deployers.ExtensionDeployer"/>
&lt;deployer extension="xar" directory="extensions" class="org.apache.synapse.deployers.ExtensionDeployer"/>
</pre>
          </subsection>
          <subsection name="JMS transport">
            <p>The way the JMS transport determines the content type of incoming messages has slightly changed
            between Synapse 1.2 and 1.3. The mechanism is also more flexible. See SYNAPSE-304 and SYNAPSE-424
            for the reasons of this change and refer to the
            <a href="http://ws.apache.org/commons/transport/">WS-Commons Transport project</a> for
            documentation.</p>
          </subsection>
        </section>
    </body>
</document>