| <?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/2.x) and now looking to migrate to |
| the latest versions (3.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. If you are migrating from 1.x version |
| to 3.x we recommend you follow the 1.x -> 2.x migration followed by the 2.x -> 3.x. |
| </p> |
| </section> |
| <section name="Contents"> |
| <ul> |
| <li> |
| <a href="#General_comments">General comments</a> |
| </li> |
| <li> |
| <a href="#Upgrading_from_2.1_to_3.0">Upgrading from 2.1 to 3.0</a> |
| <ul> |
| <li> |
| <a href="#Custom_Extensions_3.0">Custom Extensions</a> |
| </li> |
| <li> |
| <a href="#New_mediators_3.0">Respond and Loopback Mediators</a> |
| </li> |
| </ul> |
| </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 introducing 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 2.1 to 3.0" id="Upgrading_from_2.1_to_3.0"> |
| <subsection name="Custom Extensions" id="Custom_Extensions_3.0"> |
| <p> |
| Synapse 3.0 introduces the PassThrough HTTP Transport which improves HTTP transport performance by removing |
| intermediary buffer use when there is no requirement to read an HTTP payload (i.e. message is merely passed |
| through). If you have custom extensions that depend on accessing or reading buffers directly, you |
| may require to change your code to trigger the PassThrough transport to build the payload. This can |
| be done using the <a href="../apidocs/org/apache/synapse/transport/passthru/util/RelayUtils.html">RelayUtils#buildMessage()</a> |
| static methods. |
| </p> |
| </subsection> |
| <subsection name="Respond and Loopback Mediators" id="New_mediators_3.0"> |
| <p> |
| <a href="mediators.html#Respond">Respond</a> and <a href="mediators.html#Loopback">Loopback</a> |
| are new mediators introduced in Apache Synapse 3.0. <a href="mediators.html#Respond">Respond</a> provides |
| a mechanism to send a message back to the client as a response. In older versions of Apache Synapse |
| we would use the <a href="mediators.html#Send">Send</a> mediator to respond back to a client either |
| after a message is received from a backend in an out sequence or force a response back to the client |
| using a series of mediators as follows: |
| </p> |
| <div class="xmlConf"> |
| <header name="To" action="remove"/> |
| <property name="RESPONSE" value="true" scope="default" type="STRING"/> |
| <property name="NO_ENTITY_BODY" scope="axis2" action="remove"/> |
| <send/> |
| </div> |
| <p> |
| We can replace above methods with the <a href="mediators.html#Respond">Respond</a> mediator anywhere |
| in the mediation flow to respond back to the client with the current message. Any mediators residing |
| after the <a href="mediators.html#Respond">Respond</a> mediator will be ignored. |
| </p> |
| |
| <p>Similarly the <a href="mediators.html#Loopback">Loopback</a> mediator is used to jump the flow from |
| an in sequence to the out sequence ignoring any mediators residing after the |
| <a href="mediators.html#Loopback">Loopback</a> mediator. <a href="mediators.html#Loopback">Loopback</a> |
| mediator has no effect from inside an out sequence. |
| </p> |
| </subsection> |
| </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"><deployer extension="jar" directory="mediators" |
| class="org.apache.synapse.core.axis2.MediatorDeployer"/></div> |
| <p> |
| In 2.1 the suggested configuration is: |
| </p> |
| <div class="xmlConf"><deployer extension="xar" directory="extensions" |
| class="org.apache.synapse.deployers.ExtensionDeployer"/> </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"><deployer extension="jar" directory="mediators" |
| class="org.apache.synapse.deployers.ExtensionDeployer"/> |
| <deployer extension="xar" directory="extensions" |
| class="org.apache.synapse.deployers.ExtensionDeployer"/></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"><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></div> |
| which needs to be changed to the following configuration on 2.1 |
| <div class="xmlConf"><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></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 <then> element. |
| </p> |
| <p> |
| If we consider the following sample from the 1.2 version of synapse; |
| <div class="xmlConf"><filter source="get-property('To')" regex=".*/StockQuote.*"> |
| <send> |
| <endpoint> |
| <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> |
| </endpoint> |
| </send> |
| <drop/> |
| </filter></div> |
| the equivalent configuration for the 2.1 release is going to be; |
| <div class="xmlConf"><filter source="get-property('To')" regex=".*/StockQuote.*"> |
| <then> |
| <send> |
| <endpoint> |
| <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> |
| </endpoint> |
| </send> |
| <drop/> |
| <then/> |
| </filter></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"><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></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> |
