---------------------------------------------------

Solace
Messaging API for JMS Version 10.3.0
Release Notes
January 2018
---------------------------------------------------

© Copyright 2004-2017 Solace Corporation

All rights reserved.

Thank you for your interest in the Solace Messaging APIs

for SolOS Version 10.3. This file contains the following information:

* Release Contents
* Release Compatibility
* Features and Changes Introduced by Messaging API for JMS - Version
10.3
* Supported Environments
* Resolved Issues
* Known Issues
* How to Contact Solace

Release Contents
----------------

This release contains the following items:

./doc Online documentation

./samples Sample application
./licenses Software licenses
./lib Libraries

Release Compatibility
-------------------

The Messaging API for JMS - Version 10.3.0 is compatible with:

- Solace appliances running SolOS-Topic Routing (TR) Version 7.1 and above.
The Messaging API for JMS supports JMS 1.1, which is backward compatible
with JMS 1.0.2b. It also supports Java applications in standalone mode only. It
does not support Applet environments.

NOTE: Using undocumented parts of the API, such as internal methods or classes,
is not supported. These undocumented parts of the API are subject to change
without notice.

Features and Changes Introduced by Messaging API for JMS - Version

10.3
---------------------------------------------------------------------
The following new features and changes are added to Messaging API for JMS -
Version 10.3:

#71288 The MD5.encodeHex method has been removed from the API.

Supported Environments for JMS

------------------------------
The Messaging API for JMS - Version 10.3.0 is compatible with Java
version 1.5 and above on the Sun Java Virtual Machine (JVM).

Supported Environments for JMSRA

--------------------------------
JBOSS EAP: 6.1+
Oracle WebLogic: 11gR1 (10.3.6)+
IBM WebSphere: 8.5+

Resolved Issues
---------------
The following known issues are resolved by Messaging API for JMS- Version
10.3.0:
#71085 The Solace JMS Resource Adapter leaks memory when MessageProducers
are repeatedly created/closed in the same Session.

#70330 If using more than one MessageProducer on a connection the producers

may block indefinitely in send() if a reconnect fails.

The following known issues are resolved by version 10.2.2 and are included in
version 10.3.0:
#71088 A consumer using guaranteed transport, with a receive window size of 1,
and allowing multiple threads to write to the socket, may stop receiving messages
in rare cases

The following known issues are resolved by version 10.2.1 and are included in
version 10.3.0:

#69354 The API allocates more memory than required to store message headers and
maps.

#64727 Added a zero argument constructor to SolConnectionFactoryImpl as a

workaround to allow for integration with Apache NiFi. The
SolConnectionFactoryImpl interface as a whole is not a supported interface,
but this workaround is provided for use until NiFi JIRA 2701 is resolved.

#65576 A consumer using guaranteed transport and a small receive window size
may stop receiving messages if the Solace API's I/O "reactor" thread is delayed
from running for approximately the configured receive AD acknowledgement time.

#65726 The JMS API can deadlock after failing to reconnect to the Solace router.
This is commonly seen when using the same ExceptionListener object for multiple
Connection objects, with the ExceptionListener for one Connection operating
on a different Connection.

The following known issues are resolved by version 10.0.2 and are included in
version 10.3.0:

#63833 The API should scan the host list during the initial connection and
log, at WARN level, any unresolvable host names. The connection should still
succeed provided there is at least one reachable Solace host configured in the
list.

#64581 An application can become deadlocked when it is removing a subscription

concurrently with an in progress asynchronous cache request.

The following known issues are resolved by version 10.0.1 and are included in
version 10.3.0:

#62814 The JMS distribution ZIP file should extract its contents to a root
folder with a name that includes the version.

#62878 The API does not explicitly close streams after accessing the keystore
or truststore files in all scenarios. This can prevent the clean-up of these files

The following known issues are resolved by version 10.0.0 and are included in
version 10.3.0:

#41445 Queue and durable subscriber consumers created on transacted sessions do not
unbind from their respective queue or durable subscriber when the consumer is
closed until commit() or rollback() is next called for the session.

#57564 SolConnectionFactory.setHost() currently requires a protocol specified in

addition to host, although the API documentation states that protocol is optional.
Workaround: Specify a protocol when using SolConnectionFactory.setHost().

#59943 JMS Message.getPropertyNames returns properties that cannot be set.

#62568 "Unresolved requirement" error when deploying an app in the OSGi container,
due to some internal methods being incorrectly exposed.

#62655 The display-name in ra.xml in the Solace JMS Resource Adapter has changed
to "Solace JMS RA". Any provisioning scripts that depend on this may need to be
updated.

The following known issues are resolved by version 7.2.2.100 and are included in
version 10.3.0:

#59909 JMS Javadoc incorrectly states that SOLACE_JMS_PROP_IS_REPLY_MESSAGE

is a String. It's actually a Boolean.

#60456 Update JMS javadocs to indicate that leading/trailing whitepaces

in SOLACE_JMS_SSL_TRUSTED_COMMON_NAME_LIST will be used to validate the
common name

The following known issues are resolved by version 7.2.1.148 and are included in
version 10.3.0:

#59794 JMS QueueBrowser waits to send Transport Acknowledgement for message

receipt until after its timer expires rather than immediately, which under
certain configurations may result in poor message browsing rates.

The following known issues are resolved by version 7.2.0.557 and are included in
version 10.3.0:

#58909 When using the JMS resource adapter in JBoss, an MDB may stop receiving
messages after a replication failover.

#58765 In WildFly (formerly JBoss Application Server), a benign warning about

an invalid archive occurs when starting an application that uses the JMS
resource adapter.

#59102 A failed XA transaction due to EXTRA_PUBLISHER_MSGS will be erroneously

reported by the API as MISSING_PUBLISHER_MSGS_RETRY. An INVALID_PUBLISHER_FLOW
will be reported by the API as EXTRA_PUBLISHER_MSGS.

#59202 An xaSessionStart can get blocked at reconnect if there is another

message waiting to be sent while the client is in CONNECTING state.

The following known issues are resolved by version 7.2.0.544 and are included in
version 10.3.0:

#51739 In the JMS resource adapter, the outbound connection factory for publishing

messages cannot connect when there is no username/password specified when using

client certificate authentication.

#58373 When using the JMS Resource Adapter, the client is incorrectly referenced
as a non-ACC client.

The following known issues are resolved by version 7.1.2.248 and are included
in version 10.3.0:

#58550 An application may exit after extended running when using Spring and
creating numerous MessageConsumers with transacted sessions.

The following known issues are resolved by version 7.1.2.240 and are included
in version 10.3.0:
#58130 Kerberos Token sizes larger than 4K will cause the application to exit.

The following known issues are resolved by version 7.1.2.230 and are included in
version 10.3.0:

#56982 The WebLogic Messaging Bridge will not work because the JMS API
cannot convert WebLogic messages to Solace messages

#57012 Calling close on a flow consumer may block indefinitely if the

underlying session is closed concurrently.

#43197 Under high network delay or latency, the retransmission of a guaranteed

message can cause the API and appliance to get out-of-sync with respect to message
IDs, causing the appliance to reject published messages as duplicates.
Workaround: Disconnect and reconnect the publishing client to resynchronize the
message IDs.

The following known issues are resolved by version 7.1.2.226 and are included in
version 10.3.0:

#54368 When using the JMS resource adapter, a large burst of messages that arrive
faster
than the MDB can process them can cause inbound message processing on the queue
associated
with that particular pool instance to halt.

#54157 The API does not explicitly close streams after accessing the keystore
or truststore files. This can prevent the clean-up of these files.
The following known issues are resolved by version 7.1.1.169 and are included in
version 10.3.0:

#54658 When using SSL, the API may fail to connect to the router, especially when
the API is connecting through an intermediate device that proxies its TCP
connection.

The following known issues are resolved by version 7.1.1.148 and are included in
version 10.3.0:

#52310 When using the JMS resource adapter in JBoss, the reconnect attempts
cannot be set to infinite (-1).

#52970 When using the JMS resource adapter, password values in ExtendedProps
property
are included in the server log.

#53003 When the Solace JCA Resource Adapter is started by the WebSphere
Application
Server version 7, a configured Queue or Topic destination (J2C Administered Object)
fails
to bind. This problem does not occur in WebSphere version 8.5.

#53420 The API does not allow null values to be set in String and Object Message
properties, which violates the JMS specification.

#53439 If a transacted session is experiencing congestion, the router and the API
may become out of sync and progress on consumer transactions may get stalled
until the session disconnects and reconnects.

#54279 The order of preference for the property source of the SSL Trust Store,
Format,
and Password and SSL Key Store, Format, and Password properties (in descending
priority)
is not (1) Initial Context, (2) JNDI Properties File, (3) System, as documented.

The following known issues are resolved by version 7.1.0.240 and are included in
version 10.3.0:

#53598 If a WebLogic application throws an exception from the onMessage() method

of an MDB,
WebLogic attempts to recover the session. This may lead to a deadlock if Solace JMS

is integrated as the foreign JMS provider.

The following known issues are resolved by version 7.1.0.233 and are included in
version 10.3.0:

#52759 The API will fail to start due to NoSuchMethodError when using Java 1.5.

#53100 When using the Solace JCA Resource Adapter in JBoss, during XA Recovery a
ClassNotFoundException occurs for SolJNDIInitialContextFactory unless a JTS
module dependency is configured.
#53289 The text message encoder and decoder used by the JCSMP and JMS APIs handle
UTF-8 characters with more than 2 bytes differently than the other Solace APIs.
This
prevents interoperability of JCSMP and JMS with the other Solace APIs for text
messages containing these characters. Versions of JCSMP and JMS that include this
fix are not interoperable for text messages containing these characters with
versions
of JCSMP and JMS that do not include the fix.

The following known issues are resolved by version 7.1.0.220 and are included in
version 10.3.0:

#51568 When using the JMS resource adapter in JBoss, a new client connection is
opened each
time periodic XA recovery occurs. These clients do not get cleaned up regularly, so
a
large number of unused clients can accumulate.

The following known issues are resolved by version 7.1.0.207 and are included in
version 10.3.0:

#29879 If flow.close() is called while the channel is in the process of

rebinding its Flows after a reconnect, a Flow could get rebound even though
it has been closed.

#46156 If a BytesMessage is write-only, calling getBodyLength() returns 0 instead

of throwing
MessageNotReadableException.

#47147 When multiple instances of the API are running in the same JVM, client
names generated
by the API are not always unique. To make the client names unique, they need to
include the
thread ID of the context's reactor thread in the generated client name.

#48534 When the application is congested and unable to process new messages, the
API does not
signal the congestion back to the appliance, so the messages do not properly queue
on the appliance.

Changed Functionality for Messaging API for JMS - Version 10.3.0

-----------------------------------------------------------------
The following functionality changed in Messaging API for JMS - Version
10.3.0.
No new changed functionality.

The following functionality changed in Messaging API for JMS - Version

10.1.0 and is included in 10.3.0:

#69908 A new WARN log has been added to raise the visibility of transaction commit
failures
in frameworks that would otherwise hide the failure. The logging framework, such as
log4j,
can be used to suppress the new log if required.
#65444 The pom.xml file now contains dependencies for commons-lang and
commons-logging. The sol-jcsmp and sol-common dependencies have been removed.
If using the JMS Resource Adapter with JBoss, the sol-jcsmp and sol-common
dependency must be removed from module.xml.

The following functionality changed in Messaging API for JMS - Version

7.2.2.100 and is included in 10.3.0:

#60659 The API now allows negative XID formatIDs.

Note that applications must not set the formatID to -1 (0xFFFFFFFF),
as it means that the XID is null.

#60877 Solace dependencies are now included inside of sol-jms-<version>.jar

#61185 The following exports in JMS have been removed:

com.solacesystems.common,
com.solacesystems.common.protocol,
com.solacesystems.common.util,
com.solacesystems.common.xpe
Following classes and interfaces have been removed from JavaDocs packaged with
JMS:
com.solacesystems.common.ChainedException
com.solacesystems.common.config.Version
com.solacesystems.common.config.VersionBean
com.solacesystems.common.protocol.ProtocolMessage
com.solacesystems.common.protocol.ProtocolRequest
com.solacesystems.common.protocol.ProtocolResponse
com.solacesystems.common.util.TopicSubscription
com.solacesystems.common.util.expression.ExpressionArgument
com.solacesystems.common.util.expression.AndOperator
com.solacesystems.common.util.expression.BooleanExpressionArgument
com.solacesystems.common.util.expression.Expression
com.solacesystems.common.util.expression.NotOperator
com.solacesystems.common.util.expression.OrOperator
com.solacesystems.common.xpe.DurableXpe
com.solacesystems.common.xpe.PriorityXpe
com.solacesystems.common.xpe.SubscriptionXpe
com.solacesystems.common.xpe.Xpe

The following functionality changed in Messaging API for JMS - Version

7.2.0.557 and is included in 10.3.0:

#59558 If there are issues with the default format, the type of the internal
normalized keystore used for processing the keys from the SSL Key Store can
be overridden using the KeyStoreNormalizedFormat property.

The following functionality changed in Messaging API for JMS - Version

7.2.0.544 and is included in 10.3.0:

#59779 When an unsolicited unbind request is received due to shutdown or

de-provisioning, the following JMSException is no longer delivered to the
ExceptionListener:
Exception: javax.jms.JMSException: Error receiving message - internal error
(Flow inactive due to receiving unsolicited unbind from the appliance, the
required resource was either shutdown or de-provisioned)
Instead a SolConsumerEvent is raised when an consumer SolConsumerEventListener
is registered.
#58247 Classes ManagedQueueConnectionFactory and ManagedTopicConnectionFactory
need to be specified in the Resource Adapter configuration for the use of
QueueConnectionFactory and TopicConnectionFactory and Connection object types
in the application, respectively, and ManagedJMSConnectionFactory for
ConnectionFactory and Connection objects. In previous releases, the Resource
Adapter accepted the use of ManagedJMSConnectionFactory for all objects.

The following functionality changed in Messaging API for JMS - Version

7.1.2.248 and is included in 10.3.0:

#58273 The length of the automatically generated JMSMessageID can now be

limited to 23 characters. This may improve interoperability with other
messaging systems. See the property SOLACE_JMS_JMS_MESSAGE_ID_MODE in the
documentation for more details.

The following functionality changed in Messaging API for JMS - Version

7.1.0.226 and is included in 10.3.0:

#46255 "Max resends" properties don't always notify or close the session
during failover scenarios, which can lead to the application becoming
blocked forever. As a result, the following two methods of the interface
'SolConnectionFactory' are deprecated: java.lang.Integer getSendADMaxResends()
and void setSendADMaxResends(java.lang.Integer sendADMaxResends). The value
of the property has no effect. The JNDI connection factory ad-property
'send-max-resends' is also deprecated.

The following functionality changed in Messaging API for JMS - Version

7.1.0.207 and is included in Version 10.3.0:

#48421 URIs passed to the API that contain underscores are now accepted as valid.

#49972 The j2ee.jar distributed with JMS has changed to the Apache Geronimo
implementation.

Known Issues for Messaging API for JMS - Version 10.3.0

--------------------------------------------------------
The following issues exist for Messaging API for JMS - Version 10.3.0. When
appropriate, workarounds for correcting them are provided.

#61389 A temporary queue it is not provisioned until the consumer is created.

Workaround: In applications, create the consumer immediately after the queue.
For example:
Queue queue = session.createTemporaryQueue();
// temporary queue not yet provisioned
MessageConsumer consumer = session.createConsumer(queue);
// temporary queue only provisioned now

#52977 Sending a message from a producer callback is not supported and may cause
a deadlock, but this is not prevented by the API. The send() method should throw an

exception in this case.

#54280 The API checks system-specified key store format even if SSL connections
are
not used. This will cause an exception if the format is unsupported.

How to Contact Solace

-----------------------------
Contact Solace at:

Solace Corporation
535 Legget Drive
Third Floor
Ottawa, Ontario
Canada
K2K 3B8

Voice: +1 613 271 1010

Fax: +1 613 271 2844
E-mail: info@solace.com
Web site: www.solace.com

For customer support, contact:

North America Toll Free: +1 866 SOLACE1 (+1 866 765 2231)
International: +1 613 270 8404
E-mail: support@solace.com