-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat Fuse
Migration Guide
Red Hat JBoss Fuse
Migrating to Red Hat JBoss Fuse 6.2
Red Hat
Version 6.2
Copyright © 2011-2015 Red Hat, Inc. and/or its affiliates.
27 Sep 2017
Abstract
This guide lays out the issues a user will encounter when upgrading to the latest version of Red Hat JBoss Fuse.
Chapter 1. Migration Overview
Abstract
This chapter highlights some of the key points that might affect your applications, when migrating from JBoss Fuse 6.1 to JBoss Fuse 6.2. For a detailed description of the changes made to each of the components, see the relevant chapters for Apache ActiveMQ, Apache Camel, and Apache CXF.
1.1. Upgraded Components
Version upgrades
Many of the major components in JBoss Fuse and JBoss A-MQ 6.2 have been upgraded. The following versions are used in JBoss Fuse:
Table 1.1. Component Versions
| Component | Version for 6.1 | Version for 6.2 |
|---|---|---|
| Apache ActiveMQ | 5.9.0 | 5.11.0 |
| Apache Camel | 2.12.0 | 2.15.1 |
| Apache CXF | 2.7.0 | 3.0.4 |
| Apache Karaf | 2.3.x | 2.4.0 |
| Fabric8 (was Fuse Fabric) | 1.0.0 | 1.2.0 |
| Spring framework | 3.2.x | 3.2.x |
XA transactions
If you have deployed any transaction code that relies on the Apache Aries auto-enlisting XA wrapper, you should note that this feature is no longer installed by default. To enable the Aries XA wrapper service, you must now install the
connector features, as follows:
JBossFuse:karaf@root> features:install connector
Apache ActiveMQ changes
The changes resulting from the upgrade to version 5.11.0 are detailed in Chapter 5, Apache ActiveMQ Issues.
Apache Camel changes
The changes resulting from the upgrade to version 2.15.1 are detailed in Chapter 6, Apache Camel Issues.
The most important changes are:
- The Camel SAP component has been refactored into ten separate sub-components and now also supports sending and receiving IDoc documents. For details, see chapter "SAP Component" in "Apache Camel Component Reference".
- Camel supports a new REST DSL, which makes it easy to define REST services in a Camel route. For details, see chapter "Defining REST Services" in "Apache Camel Development Guide".
Apache CXF changes
The changes resulting from the upgrade to version 3.0.4 are detailed in Chapter 7, Apache CXF Issues.
The most important changes are:
- The
cxf-apibundle and thecxf-rt-corebundle are no longer available in Apache CXF 3.0.x. For details, see Section 7.3, “Packaging of Bundles/JARs”. - The
http://cxf.apache.org/jaxrsnamespace has been changed tohttp://cxf.apache.org/jaxrs-clientin Apache CXF 3.0.x. For details, see Section 7.4, “XML Schema Namespaces”.
1.2. New Role-Based Access Control
Overview
JBoss Fuse 6.2 has a new role-based access control (RBAC) feature, which is enabled by default in the container. The new RBAC system offers differentiated access to the container, depending on which roles have been assigned to a user. The RBAC imposes access controls on the Karaf console (so that only administrators can access the full range of commands and command options) and imposes access controls on the JMX protocol (so that access control is applied to the Fuse Management Console).
Standardized roles
Table 1.2, “Standard Roles for Access Control” lists and describes the standard roles that are used throughout the JMX ACLs and the command console ACLs.
Table 1.2. Standard Roles for Access Control
| Roles | Description |
|---|---|
Monitor, Operator, Maintainer | Grants read-only access to the container. |
Deployer, Auditor | Grants read-write access at the appropriate level for ordinary users, who want to deploy and run applications. But blocks access to sensitive container configuration settings. |
Administrator, SuperUser | Grants unrestricted access to the container. |
Migrating user data for RBAC
When migrating to JBoss Fuse 6.2, you must modify your user data, so that users are assigned one of the standard roles from Table 1.2, “Standard Roles for Access Control”.
Reference
For more details about role-based access control, see section "Role-Based Access Control" in "Security Guide".
1.3. Security Changes
Overriding the default JAAS realm in Fabric
In JBoss Fuse 6.2, the rank of the default
ZookeeperLoginModule JAAS module (which is installed by default in a Fabric container) has changed to 99, and the name of the default realm is karaf. In previous releases, the rank of ZookeeperLoginModule realm was just 1.
Hence, if you want to override the default
karaf in the context of Fabric, you must define a new realm named karaf, with a rank attribute that is greater than or equal to 100.
Enabling LDAP authentication in a Fabric
In particular, this change affects the configuration needed to enable LDAP authentication in a Fabric. In this case, the
rank attribute of the jaas:config element in the JAAS realm configuration file must be increased to at least 100 (recommended is 200). For details, see section "Procedure for a Fabric" in "Security Guide".
1.4. Migrating Maven Projects
Overview
JBoss Fuse 6.1 now has a JBoss Fuse BOM (Bill of Materials), which defines the versions of all the JBoss Fuse Maven artifacts. You can use the BOM to simplify migration of your Maven POM files. Instead of updating the
version elements on each Maven dependency, all you need to do is to import the latest JBoss Fuse BOM, which defines default versions for all of the dependencies provided by JBoss Fuse.
JBoss Fuse BOM
The JBoss Fuse BOM is a parent POM that defines the versions for all of the Maven artifacts provided by JBoss Fuse. The JBoss Fuse BOM exploits Maven's dependency management mechanism to specify default versions for the Maven artifacts, so that it is no longer necessary to specify the artifact versions explicitly in your POM.
Current version of the JBoss Fuse BOM
The easiest way to discover the current version of the JBoss Fuse BOM is to examine one of the sample
pom.xml files from the quickstarts examples. For example, in the InstallDir/quickstarts/eip/pom.xml file, you can find a line that defines the JBoss Fuse BOM version, as follows:
<project ...>
...
<properties>
...
<!-- the version of the JBoss Fuse BOM, defining all the dependency versions -->
<jboss.fuse.bom.version>6.2.0.redhat-133</jboss.fuse.bom.version>
</properties>
...
</project>How to migrate Maven dependencies using the JBoss Fuse BOM
To migrate Maven dependencies using the JBoss Fuse BOM, open the Maven
pom.xml file for your project and edit it as follows:
- Define the JBoss Fuse BOM version as a property in your
pom.xmlfile, using the current BOM version. For example:<project ...> ... <properties> ... <jboss.fuse.bom.version>6.2.0.redhat-133</jboss.fuse.bom.version> </properties> ... </project> - Reference the JBoss Fuse BOM parent POM in a
dependencyManagementelement, so that it defines default versions for the artifacts provided by JBoss Fuse. Add the followingdependencyManagementelement to yourpom.xmlfile:<project ...> ... <dependencyManagement> <dependencies> <dependency> <groupId>org.jboss.fuse.bom</groupId> <artifactId>jboss-fuse-parent</artifactId> <version>${jboss.fuse.bom.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> ... </project> - Now delete all of the
versionelements in your JBoss Fuse dependencies. All of the versions defined in the JBoss Fuse BOM will be applied automatically to your dependencies (through the Maven dependency management mechanism). For example, if you already had some Apache Camel dependencies, as follows:<dependencies> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-core</artifactId> <version>2.15.1.redhat-620133</version> </dependency> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-blueprint</artifactId> <version>2.15.1.redhat-620133</version> </dependency> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jetty</artifactId> <version>2.15.1.redhat-620133</version> </dependency> ... </dependencies>You would delete the version elements, so that the dependencies are specified as follows:<dependencies> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-core</artifactId> </dependency> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-blueprint</artifactId> </dependency> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jetty</artifactId> </dependency> ... </dependencies> - In future, when you migrate to a later version of JBoss Fuse, all that you need to do to upgrade your
pom.xmlfile is to edit thejboss.fuse.bom.versionproperty, so that it references the new version of the JBoss Fuse BOM.
Chapter 2. Upgrading to a Pre-Patched Distribution
What is a pre-patched distribution?
For version 6.2.0 of JBoss Fuse, pre-patched distributions are made available for the first time. A pre-patched distribution is an installation of the 6.2.0 GA version which has had the specified patch applied to it. This pre-patched installation is then re-packaged as an archive and made available for download.
For example, the following pre-patched distribution, which incorporates patch P1, is currently available for download:
Red Hat JBoss Fuse Pre-patched 6.2.0 P1
Installing a pre-patched distribution
To install a pre-patched distribution, extract the downloaded archive file into a directory on your file system. The distribution is now ready for use as a standalone container (but not as a Fabric container—see the notes and limitations).
Important notes and limitations
The pre-patched distribution is not equivalent to a complete rebuild of the product. This has some important implications, as follows:
- A pre-patched distribution is intended primarily to be used as a standalone container (that is, non-Fabric).
- If you do create a fabric using the pre-patched distribution (for example, using
fabric:create), the Fabric container reverts to the unpatched, GA version of the product. - From version 6.2.1 of JBoss Fuse, the patching process will be improved so that pre-patched distributions can also be used to create properly patched Fabric containers.
Chapter 3. Deprecated and Removed Features
ServiceMix Maven archetypes not supported
The ServiceMix Maven archetypes (with a
groupId of org.apache.servicemix.tooling) are no longer supported and are not available in 6.2. You can use the fabric8 Maven archetypes instead (which provide similar functionality). The fabric8 archetypes have a groupId of io.fabric8.archetypes and the following fabric8 archetypes are available:
karaf-camel-amq-archetype karaf-camel-cbr-archetype karaf-camel-cxf-code-first-archetype karaf-camel-cxf-contract-first-archetype karaf-camel-dozer-wiki-archetype karaf-camel-drools-archetype karaf-camel-eips-archetype karaf-camel-errorhandler-archetype karaf-camel-log-archetype karaf-camel-log-wiki-archetype karaf-camel-webservice-archetype karaf-rest-archetype karaf-secure-rest-archetype karaf-secure-soap-archetype karaf-soap-archetype
Fuse Application Bundles
Fuse Application Bundles (FABs) are no longer supported and are not available in 6.2. Instead of using FABs, it is recommended that you repackage your code as an OSGi bundle, for deployment into the JBoss Fuse container.
JBI container
The Java Business Integration (JBI) container has been removed from JBoss Fuse 6.2.
Apache OpenJPA is deprecated
The Apache OpenJPA implementation of the Java Persistence API (JPA) is deprecated in 6.2. It is recommended that you use the Hibernate implementation instead.
Spring Dynamic Modules (Spring-DM) is deprecated
Spring-DM (which integrates Spring XML with the OSGi service layer) is deprecated in 6.2 and you should use the Blueprint framework instead. Using Blueprint does not prevent you from using the Spring framework: the latest version of Spring is compatible with Blueprint.
The camel-infinispan component has been removed from JBoss Fuse 6.2
The
camel-infinispan component is not included in JBoss Fuse 6.2. It is recommended that you use the camel-jbossdatagrid component instead. For details on how to install it, see Red Hat JBoss Data Grid and Red Hat JBoss Fuse in the Red Hat JBoss Data Grid Getting Started guide.
You can use any supported combination of JBoss Data Grid in a given container, where the list of certified versions is listed in the JBoss Data Grid support matrix. For some examples of how to use JBoss Data Grid with JBoss Fuse, see https://github.com/jbossdemocentral/jdg-fuse-demos.
Chapter 4. Console Changes
fabric:mq-create command
The following argument names have changed in JBoss Fuse 6.2:
--portsto--port--networksto--network
fabric:profile-create command
The following argument names have changed in JBoss Fuse 6.2:
--parentsto--parent
fabric:profile-edit command
The following argument names have changed in JBoss Fuse 6.2:
--repositoriesto--repository--featuresto--feature--libsto--lib--bundlesto--bundle
fabric:export and fabric:import commands
The
fabric:export and fabric:import commands have been removed in JBoss Fuse 6.2, and are now replaced by the corresponding zk:export and zk:import commands. To gain access to these Zookeeper commands, you must install the fabric-zookeeper-commands feature.
Note
The
zk:export and zk:import commands interact purely with the Zookeeper registry. For example, you cannot use these commands to export or import Fabric profile data, which is now stored in the container's Git repository.
Chapter 5. Apache ActiveMQ Issues
Abstract
JBoss Fuse 6.2 uses Apache ActiveMQ 5.11.0. Since the last release, Apache ActiveMQ has been upgraded from version 5.9.0 to version 5.11.0. This introduces a few migration issues.
5.1. Migrating Clients
Migrating Apache ActiveMQ clients
In general, it is recommended that you update your Apache ActiveMQ clients at the same time that you update the brokers, in order to guarantee compatibility between clients and brokers.
It is possible, in some cases, that older client versions might be interoperable with later broker versions. The Openwire protocol supports version negotiation, such that an old client can negotiate the lowest common version with its peer and use that version. But JBoss Fuse does not have a comprehensive test suite for testing compatibility between all of the different versions of Apache ActiveMQ. Hence, to be sure of compatibility, it is recommended that you upgrade your clients along with your brokers to use the same version.
5.2. New Features
ActiveMQ 5.10.0
In ActiveMQ 5.10.0, the following new features have been introduced:
- Hardened MQTT support
- Hardened AMQP support
- Hardened LevelDB store
- Improved RAR/JCA adapter
- Improved Runtime configuration plugin
ActiveMQ 5.11.0
In ActiveMQ 5.11.0, the following new features have been introduced:
- Destination import/export for lock down mode. Use the
destinationsPluginon the broker to import/export broker destinations to s a specified location. For example:<plugins> <destinationsPlugin location="/workspace/destinations"/> </plugins> - Dynamic Camel root loading. Allows routes to modified on the fly without restarting the broker. To take advantage of this feature, you must define a
camelroutesBrokerPluginplug-in in the broker configuration, as follows:<plugins> <camelroutesBrokerPlugin routesFile="routes.xml" /> </plugins>Where theroutes.xmlfile must be in the same location as the broker configuration file. - MQTT: QOS2 mapped to virtual topics. Can be enabled using the transport option,
?transport.subscriptionStrategy="mqtt-virtual-topic-subscriptions". - Start scripts simplification
- Recover scheduler database option
5.3. Dependency Upgrades
Spring framework
JBoss Fuse and JBoss Fuse use Spring framework version 3.2.
Apache Karaf
JBoss Fuse and JBoss Fuse use Apache Karaf version 2.4.0.
5.4. API Changes
JMS streams
JMS streams are now deprecated. If you need to send very large messages, it is recommended that you use an out-of-bounds transport, such as FTP, instead. In particular, the
org.apache.activemq.ActiveMQInputStreamand ActiveMQOutputStream classes are deprecated, as are the ActiveMQConnection.createInputStream and ActiveMQConnection.createOutputStream methods.
Camel ActiveMQ component
Removed the
org.apache.activemq.camel.converter.IdentityMessageReuseConverter class from the Camel ActiveMQ component (activemq-camel).
Chapter 6. Apache Camel Issues
6.1. Summary of Apache Camel 2.12 to Apache Camel 2.15.1 Migration
Overview
Red Hat JBoss Fuse 6.2.0.redhat-133 uses Apache Camel 2.15.1. Since the last release, Apache Camel has been upgraded from version 2.12 to version 2.15.1. This introduces a few migration issues.
Spring framework
Spring 3.0.x and Spring 3.1.x are no longer supported. You must use Spring 3.2.x.
The camel-infinispan component has been removed from JBoss Fuse 6.2
The
camel-infinispan component is not included in JBoss Fuse 6.2. It is recommended that you use the camel-jbossdatagrid component instead. For details on how to install it, see Red Hat JBoss Data Grid and Red Hat JBoss Fuse in the Red Hat JBoss Data Grid Getting Started guide.
You can use any supported combination of JBoss Data Grid in a given container, where the list of certified versions is listed in the JBoss Data Grid support matrix. For some examples of how to use JBoss Data Grid with JBoss Fuse, see https://github.com/jbossdemocentral/jdg-fuse-demos.
New Camel components
The following new Camel components have been added in Apache Camel version 2.13:
- HDFS2 component
- Integration with HDFS using Hadoop 2.x client
- JGroups component
- provides exchange of messages between Camel infrastructure and JGroups clusters.
- Apache Kafka component
- Integration with Apache Kafka
- OptaPlanner component
- To use OptaPlanner for problem solving plans.
- Splunk component
- Enables you to publish and search for events in Splunk.
- Amazon SWF component
- For managing workflows running on Amazon's Simple Workflow Service.
The following new Camel components have been added in Apache Camel version 2.14:
- AHC-WS component
- Provides Websocket based endpoints for a client communicating with external servers over Websocket.
- Atmosphere Websocket component
- Provides Websocket based endpoints for a servlet communicating with external clients over Websocket (as a servlet accepting websocket connections from external clients).
- Box component
- Provides access to all of the Box.com APIs accessible using box-java-sdk-v2.
- Dropbox component
- Enables you to treat Dropbox remote folders as a producer or consumer of messages.
- Metrics component
- Enables you to collect various metrics directly from Camel routes (using Metrics).
- Netty4 component
- A socket communication component, based on the Netty project version 4.
- Netty4-HTTP component
- An extension to Netty4 component to facilitate HTTP transport.
- Olingo2 component
- Uses Apache Olingo version 2.0 APIs to interact with OData 2.0 and 3.0 compliant services.
- Openshift component
- A component for managing your OpenShift applications.
- Google Drive component
- Provides access to the Google Drive file storage service via the Google Drive Web APIs.
- Gora component
- Enables you to work with NoSQL databases using the Apache Gora framework.
- REST component
- Enables you to define REST endpoints using the Rest DSL and plug-in to other Camel components as the REST transport.
- Spark-REST component
- Enables you to define REST endpoints using the Spark REST Java library using the Rest DSL.
- Schematron component
- An XML-based language for validating XML instance documents.
- Swagger component
- Enables users to create API docs for any REST-defined routes and endpoints in a CamelContext file.
The following new Camel components have been added in Apache Camel version 2.15:
- Beanstalk component
- For working with Amazon Beanstalk jobs.
- Cassandra component
- Cassandra CQL3 support.
- Chunk component
- For templating with Chunk engine.
- Docker component
- To communicate with Docker.
- Dozer component
- Now also as a component to convert messages using the Dozer type conversion framework.
- GitHub component
- For integrating with github.
- Google Calendar component
- Provides access to Google Calendar through the Google Calendar Web APIs.
- Google Mail component
- Provides access to Gmail via the Google Mail Web APIs.
- Hipchat component
- To integrate with the Hipchat service.
- PGEvent component
- For sending/receiving notifications in PostgreSQL via the pgjdbc-ng driver.
- JIRA component
- For integrating with JIRA issue tracker.
- Kura component
- For deploying Camel OSGi routes into Eclipse Kura M2M container.
- SCR component
- For using Camel with SCR (OSGi declarative services) on OSGi containers such as Apache Karaf.
- Spring Boot component
- For using Camel with Spring Boot.
- Test-Spring40 component
- For testing with Spring 4.0.x.
camel-test-springis for Spring 4.1.x onwards. - Scheduler component
- For timer based scheduler using a scheduled thread pool and with more functionality.
New languages
The following new expression languages have been added in Apache Camel version 2.13:
- JSonPath
- A language syntax (similar to XPath) for extracting parts of JSon messages.
The following new expression languages have been added in Apache Camel version 2.14:
- XMLTokenizer
- A truly XML-aware tokenizer that can be used with the Splitter as the conventional Tokenizer to efficiently and effectively tokenize XML documents.
New DSL
The following new DSL commands have been added in Apache Camel version 2.15:
removeProperties- A DSL command to remove exchange properties.
New Maven archetypes
The following new Apache Camel Maven archetypes have been added in Apache Camel versions 2.13, 2.14, and 2.15:
camel-archetype-cxf-code-first-blueprintcamel-archetype-cxf-contract-first-blueprint
6.2. Spring Framework
Spring version
Since Apache Camel 2.13, the version of Spring that you can use with Apache Camel must be 3.2 (or later). Spring 3.0.x and 3.1.x are not supported.
New schema location
If you explicitly specify the location of the Spring schema in your Spring configuration files, you must change the schema location to point at the 3.2 Spring schema.
The Spring 3.2 schema is located at the following Web page:
http://www.springframework.org/schema/beans/spring-beans-3.2.xsd
For example, assuming your schema locations are specified in the root
beans element, you could specify the new Spring schema location as follows:
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.2.xsd">Spring 3.2 new features
For a summary of the new features in Spring 3.2, see New Features and Enhancements in Spring 3.2.
Using the Spring registry in Apache Camel
Since Apache Camel 2.11, when using Spring's bean registry with Camel, Camel also looks up Spring's ancestor application contexts.
6.3. Product Dependencies
Apache CXF version
Since Apache Camel 2.12, the CXF component requires Apache CXF 2.7.x.
Jetty version
Since Apache Camel 2.13, the Jetty component is updated to Jetty 8.1.12.
Component dependencies
In Apache Camel 2.13, 2.14, and 2.15 some components have had their third party dependencies upgraded, as follows:
- ActiveMQ 5.8.0 to 5.11.0
- AHC 1.7.20 to 1.8.3
- APNS 0.1.6 to 0.2.3
- Atomikos 3.8.0 to 3.9.3
- AWS-SDK 1.5.1 to 1.8.9.1
- Avro 1.7.3 to 1.7.5
- BeanIO 2.0.6 to 2.0.7
- Classmate from 0.8.0 to 1.0.0
- Codehale Metrics 3.0 to 3.1
- Commons Codec 1.8 to 1.9
- Commons Httpclient 4.2.5 to 4.3.3
- Commons Httpcore 4.2.4 to 4.3.2
- CXF 2.7.6 to 3.0.4
- Deltaspike 0.7 to 1.0.1
- Disruptor 3.3.0 to 3.3.2
- Dozer 5.4.0 to 5.5.1
- Ehcache 2.7.2 to 2.8.3
- Elasticsearch 0.20.6 to 1.0.0
- FOP 1.0 to 1.1
- Groovy 2.2.2 to 2.3.4
- Guava 14.0.1 to 18.0
- Hadoop 1.2.0 to 1.2.1. Hadoop 2.3.0 supported by camel-hdfs2 component.
- Hapi 2.1 to 2.2
- Hazelcast 2.6 to 3.4
- Hibernate Validator 5.0.1.Final to 5.0.3.Final
- ICal4j 1.0.4 to 1.0.5.2
- Jackson 2.2.2 to 2.3.2
- JAX-B 2.2.7 to 2.2.11
- Jclouds 1.6.2-incubating to 1.7.0
- Jettison 1.3.4 to 1.3.5
- Jetty 7.6.9 to 8.1.12
- JLine 0.9.94 to 2.11
- Joda time 2.1 to 2.3
- JRuby 1.7.4 to 1.7.18
- JSCH 0.1.49 to 0.1.51
- JsonPath 1.1.0 to 1.2.0
- LevelDb JNI 1.7 to 1.8.
- Lucene 3.6.0 to 4.6.1
- MongoDB Java Driver 2.11.2 to 2.12.0
- Mustache 0.8.12 to 0.8.13
- MVEL 2.1.6.Final to 2.1.7.Final
- MyBatis 3.2.2 to 3.2.5
- Netty3 3.8.0.Final to 3.9.0.Final
- OGNL 3.0.6 to 3.0.8
- Pax Logging 1.6.10 to 1.7.1
- Protobuf 2.3 to 2.5
- Qpid 0.20 to 0.26
- Quartz 2.2.0 to 2.2.1
- RabbitMQ amqp Java Client 3.1.3 to 3.3.0
- Restlet 2.0.15 to 2.2.1
- RxJava 0.11.1 to 1.0.5
- Saxon 9.5.0.2 to 9.5.1-4
- Scala 2.10.2 to 2.11.2
- Servlet API 2.5 to 3.0
- Shiro to 1.2.3.
- Slf4j 1.7.5 to 1.7.6
- Snappy 1.0.4.1 to 1.1.0.1
- SNMP4J 2.2.2 to 2.3.0
- SolrJ 3.6.2 to 4.6.1
- Spring Batch 2.2.1.RELEASE to 2.2.2.RELEASE
- Spring Integration 2.2.4.RELEASE to 2.2.6.RELEASE
- Spring Redis 1.0.4.RELEASE to 1.3.4.RELEASE
- Spring Security 3.1.7.RELEASE to 3.2.5.RELEASE
- Spring WS 2.1.3.RELEASE to 2.1.4.RELEASE
- SSHD 0.8.0 to 0.11.0
- StompJMS 1.17 to 1.19
- TestNG 6.8.5 to 6.8.7
- Twitter4j 3.0.3 to 4.0.1
- Weld 1.1.5.Final to 1.1.18.Final
- XBean Spring 3.14 to 3.16
- XmlSec 1.5.5 to 1.5.6
- XStream 1.4.4 to 1.4.7
6.4. API Changes
API changes
The following changes have been made to the Java API:
- CamelContext
- Since Apache Camel 2.13, added
getRegistry(T)method toorg.apache.camel.CamelContextclass.Since Apache Camel 2.14, addedstartAllRoutesmethod toorg.apache.camel.CamelContextclass. - HttpClientConfigurer
- Since Apache Camel 2.13, the signature of the
configureHttpClient(HttpClient client)method from theorg.apache.camel.component.http4.HttpClientConfigurerinterface has been changed toconfigureHttpClient(HttpClientBuilder clientBuilder). - ManagedCamelContextMBean
- Since Apache Camel 2.14, the duplicate
getMessageHistorymethod has been removed from theorg.apache.camel.api.management.mbean.ManagedCamelContextMBeaninterface. Use theisMessageHistorymethod instead. - SynchronizationRouteAware
- Since Apache Camel 2.14, added the
org.apache.camel.spi.SynchronizationRouteAwareclass. - UnitOfWork
- Since Apache Camel 2.14, added the
beforeRouteand theafterRoutemethods to theorg.apache.camel.spi.UnitOfWorkinterface.
Moved classes
Since Apache Camel version 2.14, the following classes have moved to a different package or renamed:
- Renamed
org.apache.camel.component.syslog.Rfc3164SyslogDataFormattoorg.apache.camel.component.syslog.SyslogDataFormat
6.5. Component Updates
Jetty component
Since Apache Camel version 2.13.0, upgraded from 7.6.x to 8.1.x.
Hazelcast component
Since Apache Camel version 2.13.0, the Hazelcast component uses
Object instead of String as the key type.
Since Apache Camel version 2.13.0, the atomic number producer uses a different atomic number name. This is due to the bug fix, CAMEL-6833 (previously, the wrong atomic number name was used).
Since Apache Camel version 2.13.0, the instance consumer writes headers to the in message (previously, the instance consumer was incorrectly writing headers to the out message instead of the in message).
Since Apache Camel version 2.13.0, the erroneous header value,
envict, sent by the map/multimap consumer has now been corrected to evicted.
APNS component
Since Apache Camel version 2.13.0, the
NON_BLOCKING enum value has been removed from the APNS component, because it is no longer support in APNS itself.
Language component
Since Apache Camel version 2.13.0, the Language component no longer caches the compiled script, because that could cause unwanted side-effects. You can set
cacheScript=true to enable the previous behaviour, if you are sure that your script does not cause such side-effects.
Netty HTTP
Since Apache Camel version 2.13.0, the default value of the
urlDecodeHeaders option on the Netty HTTP component has been changed from true to false.
Since Apache Camel version 2.14, Netty HTTP now removes the
headerFilterStrategy option after resolving it.
Cache component
Since Apache Camel version 2.13.0, the Cache component no longer includes the
ehcache.xml configuration file. The default EHCache configuration is used instead, if you do not specify a configuration file explicitly.
CDI component
Since Apache Camel version 2.13.0, the CDI component has been upgraded from DeltaSpike 0.3 to 0.5, which may affect upgrades.
SJMS component
Since Apache Camel version 2.13.0, when creating a consumer, the default value of
NoLocal has changed from true to false.
ServletListener component
Since Apache Camel version 2.13.0, added
beforeAddRoutes and afterAddRoutes methods to org.apache.camel.component.servletlistener.CamelContextLifecycle class.
Twitter component
Since Apache Camel version 2.14, the
useSsl option has been removed, because SSL/TLS is now always enabled (this is enforced by Twitter).
Restlet component
Since Apache Camel version 2.14, the Restlet component has been fixed to return error code 405 (instead of 404), if a HTTP method is not allowed.
JMS and ActiveMQ components
Since Apache Camel version 2.14, routes starting with a JMS endpoint will now shut down the consumer (implemented by
MessageListenerContainer) quicker when CamelContext is being stopped. This can help to achieve a cleaner shutdown, as otherwise some JMS clients might attempt to re-connect or fail over during the shutdown . If you want to disable this behaviour, so that the routes keep accepting messages during Camel shutdown, set acceptMessagesWhileStopping=true.
Bean component
Since Apache Camel version 2.14, this component caches the bean by default (that is, a single instance of the bean is used and re-used). This behaviour can be turned off by setting
cache=false, which implies that a new instance of the bean is created for every method invocation (that is, there is no re-use).
XSLT component
Since Apache Camel version 2.15, the
transformerFactory option now uses the with the #BeanID syntax to reference a bean instance.
Metrics component
Since Apache Camel version 2.15, Java endpoint API has been refactored somewhat.
CSV component
Since Apache Camel version 2.15, upgraded to Apache Commons CSV version 1.x, which has a different API to the 0.x version.
SJMS component
Since Apache Camel version 2.15, the API has been refactored.
Swagger component
Since Apache Camel version 2.15, the need for runtime-specific servlets in Swagger has been eliminated. You can just use the default servlet, which is provided out of the box.
Mail component
Since Apache Camel version 2.15, no longer sends headers whose key starts with
Camel, as those are consider internal headers and should not be included in the sent emails.
SNMP component
Since Apache Camel version 2.15, the
delay option has changed from using seconds to milliseconds as the time unit.
Bean component
Since Apache Camel version 2.15, you cannot use the Bean component as a consumer endpoint (
from, at the start of a route). To get the same effect, you can start the route with a scheduler endpoint and send to a bean instance (using to("bean:BeanID") or beanRef("BeanID")).
6.6. Miscellaneous Changes
DefaultTimeoutMap class
Since Apache Camel version 2.13.0, you must call the start method on the
org.apache.camel.support.DefaultTimeoutMap<K,V> class to initialize the map before use.
@ExcludeRoutes annotation
Since Apache Camel version 2.13.0, the
@ExcludeRoutes test annotation now accepts only classes implementing the RoutesBuilder interface.
MBean naming
Since Apache Camel version 2.13.0, the MBean names registered by Camel JMX no longer include the hostname in the context part. For example, in previous versions the context name would have the format,
context=myHost/myCamelId, whereas now it has the format, context=myCamelId. Having the hostname in the MBean name makes things more complicated, because the MBean name changes depending on the host. The option, includeHostName, can be set to true in order to restore the old behaviour.
Since Apache Camel version 2.13.0, MBean naming in OSGi has been cleaned up to use simpler naming, with the MBean name now set to the OSGi
symbolicName by default. In previous versions, it was possible for MBean names to have repeated bundle IDs—for example, context=114-114-camel-6.
jmxAgent element
Since Apache Camel version 2.13.0, the default value of the
jmxAgent element's createConnector attribute has changed from true to false.
Since Apache Camel version 2.13.0, JMX Load statistics have been disabled by default. You can now explicitly enable statistics by setting
loadStatisticsEnabled=true on the jmxAgent element.
onException Java DSL command
Since Apache Camel version 2.13.0, when using the
onException.backOffMultiplier or collisionAvoidancePercent or collisionAvoidanceFactor options, back-off or collision avoidance is automatically enabled. In previous versions, it was also necessary to call useExponentialBackOff or useCollisionAvoidance as well. The errorHandler DSL command has the same behaviour.
Spring XML shutting down beans
Since Apache Camel version 2.13.0, the
camelContext bean will, by default, shut down before all other beans in Spring XML. This ensures a cleaner shutdown of the Camel context. If you prefer to revert to the old behaviour, you can set the new camelContext attribute, shutdownEager, to false.
onCompletion DSL command
Since Apache Camel version 2.14, now runs without a thread pool by default. To restore the old behaviour, set the
paralllelProcessing option to true.
startAllRoutes method
Since Apache Camel version 2.14, setting
autoStartup to false, and starting a CamelContext for the second time does not start the routes. Instead use the new startAllRoutes method on CamelContext to start all the routes.
Unit testing with Spring
Since Apache Camel version 2.15, unit testing with Spring 3.x now requires the
camel-test-spring3 component. The camel-test-spring40 component is for testing with Spring 4.0.x and the camel-test-spring component is for testing with Spring 4.1.
Jetty 7.x
Since Apache Camel version 2.15, Jetty 7 has been dropped and is no longer supported.
Simple language and properties syntax
Since Apache Camel version 2.15, the property placeholder syntax has changed. It is now possible to specify a default value, using the syntax
${properties:Key:DefaultVal}. Also, the syntax for overriding the properties file location has been changed from ${properties:Location:Key} to ${properties-location:Location:Key} (to avoid clashing with the new syntax for specifying default values).
Karaf camel:backlog-tracer-* commands
Since Apache Camel version 2.15, the Karaf console commands for the Camel backlog tracer (
backlog-tracer-dump, backlog-tracer-info, backlog-tracer-start, backlog-tracer-stop) have been removed, because they are not suitable for a command-line environment.
InflightRepository interface
Since Apache Camel version 2.15, the
org.apache.camel.spi.InflightRepository interface now includes additional methods for browsing in-flight exchanges.
exchangePattern URI option
Since Apache Camel version 2.15, when using the
to DSL command or the recipientList DSL command, the exchange pattern specified by adding ?exchangePattern=Pattern to the endpoint URI now takes precedence as the pattern that is used for invoking the endpoint.
Default class loader in CamelContext
Since Apache Camel version 2.15, the class loader,
DefaultClassLoader, now falls back to use the application context classloader that may have been set on CamelContext to better be able to load classes/resources from the classpath in different runtime environments.
Removing a route
Since Apache Camel version 2.15, removing a route now also remove its static endpoints from the
EndpointRegistry (if those endpoints are not shared and used by other routes). Note, however, that any dynamic endpoints created as a result of using dynamic Enterprise Integration Patterns such as recipient list, routing slip, dynamic router or similar, are not removed from the EndpointRegistry when the route is removed.
Model classes
Since Apache Camel version 2.15, all boolean
isProperty methods on the model classes have been removed, in order to ensure the model has consistent Java bean getter/setter style, with exactly one getter and one setter of each type.
Stream caching
Since Apache Camel version 2.15, added the
copy method to StreamCache API for stream caching
@UriEndpoint annotation
Since Apache Camel version 2.15, if you use the
@UriEndpoint annotation when implementing a custom Camel component, you must now also specify the syntax attribute to document the URI syntax of the endpoint.
ScalaRouteBuilder class
Since Apache Camel version 2.15, Scala developers should use the
ScalaRouteBuilder class instead of the RouteBuilder class.
Exchange property language
The exchange property language has been renamed from
property to exchangeProperty, in order to avoid ambiguity and confusion with properties as a general term.
Chapter 7. Apache CXF Issues
7.1. Summary of Apache CXF 2.7.0 to 3.0.x Migration
Overview
JBoss Fuse uses Apache CXF 3.0.x. Since the last release, Apache CXF has been upgraded from version 2.7.0 to version 3.0.x. This introduces a few migration issues.
7.2. New Features
Client proxy support for java.io.Closeable interface
When you close a client proxy using the java.io.Closeable interface (which is supported, for example, by the
JaxWsClientProxy class), any open request/response sequences are now terminated. For example, if proxy is an instance of JaxWsClientProxy, you can close the proxy as follows:
((java.io.Closeable)proxy).close()
7.3. Packaging of Bundles/JARs
Refactored cxf-api and cxf-rt-core bundles
The
cxf-api bundle and the cxf-rt-core bundle are no longer available in Apache CXF 3.0.x. These bundles have been refactored as follows: the cxf-api bundle content has been split up, with the Java API moving to the new cxf-core bundle and the WSDL interfaces moving to the new cxf-rt-wsdl bundle; the cxf-rt-core bundle content is now provided in the new cxf-core bundle (which also now incorporates the Java API).
These changes are summarized in Table 7.1, “Equivalent bundles for cxf-api and cxf-rt-core”.
Table 7.1. Equivalent bundles for cxf-api and cxf-rt-core
| 2.7.0 Bundles | 3.0.x Bundles (equivalent) |
|---|---|
cxf-api | cxf-rt-wsdl
cxf-core
|
cxf-rt-core | cxf-core |
DynamicClientFactory class
The
DynamicClientFactory has been moved from the JAXB data binding bundle, cxf-rt-databinding-jaxb, to the Simple frontend bundle, cxf-rt-frontend-simple.
Note
You are strongly encouraged to use the
JaxWsDynamicClientFactory subclass instead of DynamicClientFactory.
New cxf-rt-rs-client bundle
JAX-RS 2.0 Client API and CXF specific
WebClient and proxy client code is now made available in the new cxf-rt-rs-client bundle. See also the section called “http://cxf.apache.org/jaxrs namespace”.
7.4. XML Schema Namespaces
http://cxf.apache.org/jaxrs namespace
For JAX-RS client endpoints, the
http://cxf.apache.org/jaxrs namespace has been changed to http://cxf.apache.org/jaxrs-client in Apache CXF 3.0.x. This namespace change affects the jaxrs:client element, but the jaxrs:server and jaxrs:model continue to use the http://cxf.apache.org/jaxrs namespace, as before.
7.5. API Changes
Removed classes
The following classes and interfaces have been removed in Apache CXF 3.0.x:
org.apache.cxf.bus.CXFBusImpl org.apache.cxf.databinding.BaseDataReader org.apache.cxf.databinding.BaseDataWriter org.apache.cxf.transports.http.QueryHandler org.apache.cxf.transports.http.StemMatchingQueryHandler org.apache.cxf.transports.http.internal.QueryHandlerRegistryImpl org.apache.cxf.helpers.XMLUtils org.apache.cxf.ws.addressing.impl.AddressingPropertiesImpl org.apache.cxf.common.xmlschema.XmlSchemaConstants org.apache.cxf.common.util.SOAPConstants org.apache.cxf.frontend.MethodDispatcher org.apache.cxf.jaxb.JAXBToStringBuilder org.apache.cxf.jaxb.JAXBToStringStyle org.apache.cxf.interceptor.URIMappingInterceptor org.apache.cxf.jaxrs.ext.form.Form org.apache.cxf.jaxrs.ext.ParameterHandler org.apache.cxf.jaxrs.ext.RequestHandler org.apache.cxf.jaxrs.ext.ResponseHandler
org.apache.cxf.Bus.run() method
The
org.apache.cxf.Bus.run() method has been removed, because it is no longer used.
org.apache.cxf.transport.Destination.getBackChannel method
The two unused parameters of the
org.apache.cxf.transport.Destination.getBackChannel method (normally passed as null) have been removed. That is, in previous versions, the getBackChannel method had the following signature:
Conduit getBackChannel(Message inMessage, Message unused1, EndpointReferenceType unused2)
In version 3.0.x, the
getBackChannel method now has the following signature:
Conduit getBackChannel(Message inMessage)
Spring XML files
All files of the form
/META-INF/cxf/cxf-extension-ExtensionName.xml have been removed in version 3.0.x. At one time, it was necessary to xi:include such files into your Spring XML file, in order to use a particular extension feature. These files have not been needed and have been deprecated for a long time.
org.apache.cxf.transport.ConduitInitiator and DestinationFactory interfaces
Some of the methods of the
org.apache.cxf.transport.ConduitInitiator and DestinationFactory interfaces now take an additional parameter of type, org.apache.cxf.Bus. In particular, ConduitInitiator defines the following method signatures in version 3.0.x:
Conduit getConduit(EndpointInfo targetInfo, Bus bus)
throws IOException;
Conduit getConduit(EndpointInfo localInfo, EndpointReferenceType target, Bus bus)
throws IOException;
Set<String> getUriPrefixes();
List<String> getTransportIds();
And
DestinationFactory defines the following method signatures in version 3.0.x:
Destination getDestination(EndpointInfo ei, Bus bus) throws IOException; Set<String> getUriPrefixes(); List<String> getTransportIds();
bus-extensions.xml file
When implementing an extension to the CXF Bus, the
bus-extensions.xml file is no longer supported. Instead, use the approach of defining a bus-extensions.txt file. In the JAR file that implements your Bus extension, create the file, META-INF/cxf/bus-extensions.txt, and in this file list the classname of the class that implements the extension. The CXF Bus will automatically instantiate your extension class when it is needed.
Refactored XML parsing utilities
All code for StAX-based XML parsing and writing has been moved into the
org.apache.cxf.staxutils.StaxUtils class and DOM-based utility code to the org.apache.cxf.helpers.DOMUtils class. The org.apache.cxf.helpers.XMLUtils class has been eliminated.
AddressingProperties interface is now a class
The
org.apache.cxf.ws.addressing.AddressingProperties interface has been turned into a concrete class, which can be created directly using new. The AddressingPropertiesImpl class has been removed.
Policy classes in the org.apache.cxf.ws.policy package
Many of the classes in the
org.apache.cxf.ws.policy package, such as AlternativeSelector and PolicyEngine, have modified method signatures, which now pass the current Message as an additional parameter (where appropriate). This makes it possible to use the message context to select a policy alternative. However, you must keep in mind that the selected alternative is probably cached and therefore, if the contextual information changes, the alternative might not be recalculated.
New supportNotAvailableErrorsOnly property on FailoverTargetSelector
By default, the
org.apache.cxf.clustering.FailoverTargetSelector class triggers failover only for HTTP 404 and HTTP 503 status errors. If you would prefer to fail over for all HTTP errors, set the new supportNotAvailableErrorsOnly property to false.
ServletController not overriding endpoint addresses by default
The
org.apache.cxf.transport.servlet.ServletController class does not override endpoint addresses by default, because this would have unwanted side-effects, if an endpoint is accessed through multiple paths. If you would like to revert to the old behaviour, set disable-address-updates parameter to false on the CXFServlet class.
SchemaValidation annotation
The
enabled property (previously deprecated) has been removed from the org.apache.cxf.annotations.@SchemaValidation annotation. Use the @SchemaValidation.type property to control the validation instead.
FactoryType annotation
In the
org.apache.cxf.annotations.@FactoryType annotation, the FactoryType.Type enumeration no longer includes the value, Spring. In version 3.0.x, to select Spring, set factoryClass=SpringBeanFactory.class.
org.apache.cxf.jaxrs.ext.form.Form class
The
org.apache.cxf.jaxrs.ext.form.Form has been removed in version 3.0.x. Use the JAX-RS 2.0 org.apache.cxf.jaxrs.ext.form.Form class instead. For example, you would replace the following (obsolete) JAX-RS 1.0 code:
// JAX-RS 1.0 (obsolete)
import org.apache.cxf.jaxrs.ext.form.Form;
...
Form form = new Form().set("a", "b");
With the following JAX-RS 2.0 compliant code:
// JAX-RS 2.0
import javax.ws.rs.core.Form;
...
Form form = new Form().param("a", "b");org.apache.cxf.jaxrs.ext.ParameterHandler<T> interface
The
org.apache.cxf.jaxrs.ext.ParameterHandler<T> interface has been removed in Apache CXF 3.0.x. Use the javax.ws.rs.ext.ParamConverterProvider class instead, which can be used both on the client side and on the server side.
org.apache.cxf.jaxrs.ext.RequestHandler and ResponseHandler interfaces
The
org.apache.cxf.jaxrs.ext.RequestHandler and ResponseHandler filters have been removed in Apache CXF 3.0.x. Use the javax.ws.rs.container.ContainerRequestFilter and ContainerResponseFilter interfaces instead.
For example, to define your own
CustomerRequestFilter and CustomResponseFilter filter classes, you could write code like the following:
// Java
import javax.ws.rs.container.ContainerRequestFilter;
import javax.ws.rs.container.ContainerResponseFilter;
...
public class CustomRequestFilter implements ContainerRequestFilter {
public void filter(ContainerRequestContext context) {
...
}
}
public class CustomResponseFilter implements ContainerResponseFilter {
public void filter(ContainerRequestContext inContext, ContainerResponseContext outContext) {
...
}
}JaxWsClientProxy.getClient(proxy) and ClientProxy.getClient(proxy)
It is no longer necessary to call the
getClient(proxy) method on the org.apache.cxf.jaxws.JaxWsClientProxy class (for the JAX-WS front-end) or the org.apache.cxf.frontend.ClientProxy class (for the simple front-end) in order to convert a proxy object to a org.apache.cxf.endpoint.Client object. Because the proxies now implement the Client interface directly, you can simply cast a proxy object directly to a Client object.
javax.annotation.Resource annotation
The
javax.annotation.Resource annotation can no longer be used to annotate JAX-RS context properties. For the JAX-RS binding, only the javax.ws.rs.core.Context annotation is supported from now on.
7.6. Dependencies
javax.mail dependency
The direct dependency on a
javax.mail implementation has been removed and the Apache CXF Maven POM files do not pull one in transitively in version 3.0.x. For most users, this will not be a problem. However, if your application uses MTOM or Soap with Attachments (or similar feature) that requires some of the DataContentHandler classes from the mail implementations, you might need to add the dependency to your classpath or Maven POM file.
cxf-bundle no longer supported
In the Apache CXF versions prior to 2.6, it was possible to include all of the Apache CXF modules in your application by adding a dependency on the
cxf-bundle artifact to your Maven pom.xml file—for example:
<project>
...
<dependencies>
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-bundle</artifactId>
<version>...</version>
</dependency>
...
</dependencies>
</project>
From Apache CXF 2.6 onwards, however, the
cxf-bundle artifact is no longer available. Instead of adding a single dependency on the cxf-bundle artifact, it is now necessary to add dependencies for each of the individual Apache CXF modules that your application depends on. For example, the basic set of Maven dependencies you would need for a simple JAX-WS Java application is as follows:
<project>
...
<dependencies>
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxws</artifactId>
<version>3.0.4.redhat-620133</version>
</dependency>
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-transports-http</artifactId>
<version>3.0.4.redhat-620133</version>
</dependency>
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-transports-http-jetty</artifactId>
<version>3.0.4.redhat-620133</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
<version>3.0.6.RELEASE</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
</project>7.7. Miscellaneous Changes
Changed behaviour when providing WSDL location
If the WSDL location passed into Apache CXF is not valid (through the Java API or the XML API), previous versions of Apache CXF could in some cases ignore the error and proceed as if
null was passed for the WSDL location. Apache CXF 3.0 now always throws an exception, if the WSDL location is invalid.
Legal Notice
Trademark Disclaimer
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Apache, ServiceMix, Camel, CXF, and ActiveMQ are trademarks of Apache Software Foundation. Any other names contained herein may be trademarks of their respective owners.