Troubleshooting
Problem
WebSphere MQ offers two APIs for use in Java™ applications: - WebSphere MQ classes for Java Message Service - WebSphere MQ classes for Java. This technote explains why "WebSphere MQ classes for Java Message Service" is the API best suited for use in J2EE/JEE environments. It also describes the restrictions and design considerations that must be taken into account before using "WebSphere MQ classes for Java" in J2EE/JEE.
Resolving The Problem
WebSphere MQ has two alternative APIs for use in Java applications:
The WebSphere MQ JMS API is the WebSphere MQ API best suited for use in J2EE/JEE environments.
The JMS and J2EE/JEE specifications have been developed together specifically to allow JMS-based messaging to fully interact with a J2EE/JEE environment, and the WebSphere MQ JMS API has been designed and implemented with this in mind. The JMS 1.02 and 1.1 specifications have specific integration points as part of the J2EE/JEE specifications (such as message-driven beans) , and the WebSphere MQ JMS API implementation of these features has required specific testing with specific releases of application servers. Therefore, the WebSphere MQ JMS API is only supported in those application servers releases in which it has been tested. A list of these application servers can be found in the WebSphere MQ statement of supported environment.
From WebSphere MQ Version 6.0.2.1 onwards, a JCA Resource Adapter has been added to the WebSphere MQ JMS API. Because JCA resource adapters are part of the J2EE/JEE specification, which extends the set of application servers that are supported by the WebSphere MQ JMS API. (See the WebSphere MQ JCA Resource Adapter support statement for the list of supported environments )
The WebSphere MQ JMS API can also be used in J2SE/JSE environments.
The WebSphere MQ base Java API was designed primarily for J2SE/JSE environments, and is not well integrated with J2EE/JEE, so IBM does not recommend the use of the WebSphere MQ base Java API in J2EE and JEE environments. We identify particular releases of tested Java environments and application servers within our supported operating environment for the WebSphere MQ base Java API, and limit our support to these environments.
Additional considerations for the use of the WebSphere MQ base Java API when running within J2EE/JEE environments - application owners must take account of these
One of the intended benefits of running applications within a J2EE/JEE environment is that of application isolation. Changes to one application should not adversely affect others running in the same application server. The design and implementation of the WebSphere MQ base Java API predate the J2EE/JEE environment, and can be used in a manner which does not readily support this concept of application isolation. Specific examples of considerations in this area include:
- WebSphere MQ classes for Java Message Service (henceforth referred to as WebSphere MQ JMS)
- WebSphere MQ classes for Java (henceforth referred to as WebSphere MQ base Java)
The WebSphere MQ JMS API is the WebSphere MQ API best suited for use in J2EE/JEE environments.
The JMS and J2EE/JEE specifications have been developed together specifically to allow JMS-based messaging to fully interact with a J2EE/JEE environment, and the WebSphere MQ JMS API has been designed and implemented with this in mind. The JMS 1.02 and 1.1 specifications have specific integration points as part of the J2EE/JEE specifications (such as message-driven beans) , and the WebSphere MQ JMS API implementation of these features has required specific testing with specific releases of application servers. Therefore, the WebSphere MQ JMS API is only supported in those application servers releases in which it has been tested. A list of these application servers can be found in the WebSphere MQ statement of supported environment.
From WebSphere MQ Version 6.0.2.1 onwards, a JCA Resource Adapter has been added to the WebSphere MQ JMS API. Because JCA resource adapters are part of the J2EE/JEE specification, which extends the set of application servers that are supported by the WebSphere MQ JMS API. (See the WebSphere MQ JCA Resource Adapter support statement for the list of supported environments )
The WebSphere MQ JMS API can also be used in J2SE/JSE environments.
The WebSphere MQ base Java API was designed primarily for J2SE/JSE environments, and is not well integrated with J2EE/JEE, so IBM does not recommend the use of the WebSphere MQ base Java API in J2EE and JEE environments. We identify particular releases of tested Java environments and application servers within our supported operating environment for the WebSphere MQ base Java API, and limit our support to these environments.
The WebSphere MQ base Java API is not supported within WebSphere Liberty.
For other J2EE/JEE environments, such as WebSphere Application Server, there are a number of restrictions when using the WebSphere MQ base Java API . There are also additional considerations that should be taken into account when designing, implementing and managing a WebSphere MQ base Java API application that runs inside of a J2EE/JEE environment. The restrictions and considerations are outlined in the statements below.
IBM will accept Cases for problems encountered when using the WebSphere MQ base Java API in J2EE/JEE environments and will work with customers to determine the root cause. If a Case reports an existing restriction, or uncovers a new restriction, IBM will work with the customer to attempt to identify ways that the restriction can be avoided.
Restrictions on using the WebSphere MQ base Java API within J2EE/JEE
IBM will accept Cases for problems encountered when using the WebSphere MQ base Java API in J2EE/JEE environments and will work with customers to determine the root cause. If a Case reports an existing restriction, or uncovers a new restriction, IBM will work with the customer to attempt to identify ways that the restriction can be avoided.
Restrictions on using the WebSphere MQ base Java API within J2EE/JEE
- JTA Transactions restrictions
The only supported transaction manager for applications using the WebSphere MQ base Java API is WebSphere MQ itself. While an application under JTA control can make calls to the WebSphere MQ base Java API, any work performed through these calls will not be controlled by the JTA units of work. They will instead form local units of work separate from those managed by the application server through the JTA interfaces. In particular, any rollback of the JTA transaction will not result in a rollback of any sent or received messages. This restriction applies equally to application/bean managed transactions as to container managed transactions, and all J2EE/JEE containers. In order to perform messaging work directly with WebSphere MQ inside application server-coordinated transactions, the WebSphere MQ JMS API must be used instead.
- Thread Creation
The WebSphere MQ base Java API internally spawns threads for various operations. For example, when running in BINDINGS mode to make calls directly on a local queue manager, the calls are made on a 'worker' thread created internally by the WebSphere MQ base Java API. Other 'clean-up' threads may be spawned internally, for example to clear unused connections from a connection pool or to remove subscriptions for terminated publish/subscribe applications.
Certain J2EE/JEE applications (for instance those running in EJB and Web containers) must not spawn new threads; instead all work should be performed on the main application threads managed by the application server. When applications use the WebSphere MQ base Java API the application server may not be able to distinguish between application code and the WebSphere MQ base Java API code, so the worker and clean-up threads described above will cause the application to be non-compliant with the container specification. The WebSphere MQ JMS API does not break these J2EE/JEE specifications and so should be used instead.
- Security restrictions
Security policies implemented by an application server may prevent certain operations that are undertaken by the WebSphere MQ base Java API, such as creating and operating new threads of control (as described above).
For instance, application servers typically run with Java 2 Security disabled by default, and allow it to be enabled through some application server-specific configuration (some application servers also allow more detailed configuration of the policies used within Java 2 Security). When Java 2 Security is enabled, the WebSphere MQ base Java API may break the Java 2 Security policy threading rules defined for the application server, and the API might not be able to create all the threads that it needs in order to function. To prevent problems with thread management, the use of the WebSphere MQ base Java API is not supported in environments where Java 2 Security is enabled. - Bindings mode restrictions
It is possible for WebSphere MQ and WebSphere Application Server to be installed on the same machine such that the major versions of the queue manager and of the WebSphere MQ resource adapter (RA), or WebSphere MQ base Java classes, shipped in WebSphere Application Server are different. For instance WebSphere Application Server v7, which ships an MQ RA level of 7.0.1, can be installed on the same machine as a V6 queue manager.
If the queue manager and resource adapter (or WebSphere MQ classes for Java) major versions are different, bindings connections can not be used when using the WebSphere MQ base Java API. Any connections from WAS to the queue manager must use client type connections. Bindings connections can be used if the versions are the same.
Additional considerations for the use of the WebSphere MQ base Java API when running within J2EE/JEE environments - application owners must take account of these
One of the intended benefits of running applications within a J2EE/JEE environment is that of application isolation. Changes to one application should not adversely affect others running in the same application server. The design and implementation of the WebSphere MQ base Java API predate the J2EE/JEE environment, and can be used in a manner which does not readily support this concept of application isolation. Specific examples of considerations in this area include:
- The use of static (JVM process-wide) settings within the MQEnvironment class, such as:
-
- the userid and password to be used for connection identification and authentication
- the hostname, port and channel used for client connections
- SSL configuration for secured client connections
- Modifying any of the MQ Environment properties for the benefit of one application will also impact other applications making use of the same properties. When running in a multi-application environment such as J2EE or JEE, it is strongly recommended that each application uses its own distinct configuration through the creation of MQQueueManager objects with a specific set of properties, rather than defaulting to the properties configured in the process-wide MQEnvironment class.
- Similarly, the MQEnvironment class introduces a number of static methods which act globally on all applications using the WebSphere MQ base Java API within the same JVM process, and there is no way to override this behavior for particular applications. Examples include:
- the configuration of SSL properties, such as the location of the key store
- the configuration of client channel exits
- enabling or disabling diagnostic tracing
- managing the default connection pool used to optimize the use of connections to Queue Managers
- Application owners must be aware that invoking such methods will affect all applications running in the same J2EE/JEE environment.
- Connection pooling is enabled to optimize the process of making multiple connections to the same queue manager. The default connection pool manager is process-wide, and shared by multiple applications. Changes to connection pool configuration, such as replacing the default connection manager for one application using the MQEnvironment.setDefaultConnectionManager() method will therefore affect other applications running in the same J2EE/JEE application server.
- Much of the WebSphere MQ JMS API implementation depends on the WebSphere MQ base Java API for its internal operations. Therefore, mixing WebSphere MQ JMS API and WebSphere MQ base Java API applications within the same application server can lead to the same application isolation issues as are evident above when running multiple WebSphere MQ base Java API applications in the same J2EE/JEE application server. This particularly applies to the SSL configuration, connection pooling and diagnostic tracing managed through the MQEnvironment class.
- SSL configuration for applications using the WebSphere MQ base Java API is performed by way of the MQEnvironment class and MQQueueManager object properties, and is not integrated with the managed security configuration of the application server itself. Application owners must ensure that they perform the necessary WebSphere MQ base Java API configuration to provide their required level of security, and not use the application server configuration.
- The trace mechanism provided by the WebSphere MQ base Java API is not integrated with those of the application server. Please refer to the Tracing IBM MQ classes for Java applications topic in the MQ sections of IBM Knowledge Center for details on how to collect trace for applications using this API.
Related Information
[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSFKSJ","label":"WebSphere MQ"},"Component":"Java","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"9.1;9.0;8.0;7.5;7.1;7.0.1;7.0;6.0;5.3","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]
Product Synonym
WMQ MQ
Was this topic helpful?
Document Information
Modified date:
15 March 2021
UID
swg21266535