| <?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 2.0.0"> |
| <subsection name="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.0.0 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.0.0 |
| 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> |
| <pre>synapse-config |
| /endpoints |
| /event-sources |
| /local-entries |
| /priority-executors |
| /proxy-services |
| /sequences |
| main.xml |
| fault.xml |
| /tasks |
| registry.xml |
| synapse.xml |
| </pre> |
| <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.0.0 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"> |
| <p>In release 2.0.0 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> |
| <deployer extension="jar" directory="mediators" class="org.apache.synapse.core.axis2.MediatorDeployer"/> |
| </pre> |
| <p>In 2.0.0 the suggested configuration is:</p> |
| <pre> |
| <deployer extension="xar" directory="extensions" class="org.apache.synapse.deployers.ExtensionDeployer"/> |
| </pre> |
| |
| <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> |
| <deployer extension="jar" directory="mediators" class="org.apache.synapse.deployers.ExtensionDeployer"/> |
| <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 2.0.0. 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> |
| <subsection name="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.0.0 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.0.0 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; |
| <pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse"> |
| <!-- log all attributes of messages passing through --> |
| <log level="full"/> |
| |
| <!-- Send the message to implicit destination --> |
| <send/> |
| </definitions></pre> |
| which needs to be changed to the following configuration on 2.0.0 |
| <pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse"> |
| |
| <sequence name="main"> |
| <!-- log all attributes of messages passing through --> |
| <log level="full"/> |
| |
| <!-- Send the message to implicit destination --> |
| <send/> |
| <sequence/> |
| |
| </definitions></pre></p> |
| </subsection> |
| <subsection name="Filter Mediator"> |
| <p>From 2.0.0 onwards Synapse filter mediator supports the else close as well, and hence |
| the filter matching set of mediators has to be enclosed within a <then> element.</p> |
| <p>If we consider the following sample from the 1.2 version of synapse; |
| <pre xml:space="preserve"><filter source="get-property('To')" regex=".*/StockQuote.*"> |
| <send> |
| <endpoint> |
| <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> |
| </endpoint> |
| </send> |
| <drop/> |
| </filter></pre> |
| the equivalent configuration for the 2.0.0 release is going to be; |
| <pre xml:space="preserve"><filter source="get-property('To')" regex=".*/StockQuote.*"> |
| <then> |
| <send> |
| <endpoint> |
| <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> |
| </endpoint> |
| </send> |
| <drop/> |
| <then/> |
| </filter></pre> |
| You could also add an else close to this conditional statement as follows on 2.0.0 which |
| is not possible on 1.2 |
| <pre xml:space="preserve"><filter source="get-property('To')" regex=".*/StockQuote.*"> |
| <then> |
| <send> |
| <endpoint> |
| <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> |
| </endpoint> |
| </send> |
| <drop/> |
| <then/> |
| <else/> |
| <log/> |
| <else/> |
| </filter></pre></p> |
| </subsection> |
| <subsection name="Migration Tool"> |
| <p>In general it is recommended to run the configuration through the migration tool |
| provided with the Synapse 2.0.0 release, on your synapse 1.2 configuration before using |
| it with the 2.0.0.</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.0.0 |
| compatible configuration with the .new suffix. For example; |
| <pre>sh bin/synapse-config-migrator.sh synapse-1.2/repository/conf/synapse.xml</pre></p> |
| </subsection> |
| <subsection name="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> |
| <tr> |
| <th>Class</th> |
| <th>Method</th> |
| <th>Change Description</th> |
| </tr> |
| <tr> |
| <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.0.0 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> |
| <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.0.0 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> |
