This guide provides information to help you get started with installing, configuring and using the IBM® Resource Adapter for Java™ Message Service (JMS) with IBM WebSphere® Application Server. The guide consists of the following sections:
The IBM Resource Adapter for Java Message Service with WebSphere Application Server is a J2EE™ Connector Architecture v1.5 compliant resource adapter that provides JMS v1.1 connections to a service integration bus messaging engine in WebSphere Application Server Version v6.0.2 (or above) or any IBM product that incorporates the service integration bus. The connection to the messaging engine can be either TCP or SSL. HTTP connectivity is not supported.
You can install the resource adapter in any supported third party (that is, non WebSphere Application Server) Java 2 Extended Edition (J2EE) v1.4 compliant application server. The resource adapter supports the following third party application servers:
To install the resource adapter use J2SE 5.0 or later and enter:
java
–jar sibra_install-<build>.jar [flags]
[positional arguments]
flags:
-text install using a command-line interface
-silent install using silent license acceptance
positional arguments:
install directory directory to install into
For example, to perform a silent install into c:\jms use:
java
–jar sibra_install-<build>.jar –silent
c:\jms
The installed directories and their contents are:
|
|
The documentation for the resource adapter |
|
../etc |
The default WebSphere Application Server client key and trust files required for SSL |
|
../license |
License files |
|
../properties |
An example sib.client.ssl.properties file |
|
|
The resource adapter |
To make the resource adapter useable in a third party application server, the resource adapter must first be deployed. The mechanism for deploying the resource adapter into a third party application server is controlled by means of an application server specific deployment process. Refer to the third party application server documentation for details of how to deploy a resource adapter. Part of the deployment step will be to configure a set of JMS resources that the deployed resource adapter instance will support.
The following outbound JMS resources that can be configured as Java Naming and Directory Interface (JNDI) accessible resources:
Inbound Message Driven Beans (MDBs) can be configured by means of activation configurations.
The tables in this section list the supported configuration properties for JMS resources.
|
Property name |
Description |
Permitted values |
Default |
|
BusName |
The name of the service integration bus to connect to |
|
|
|
ClientID |
The JMS client identifier needed for durable topic subscriptions on all connections created using this connection factory |
|
|
|
UserName |
|
|
|
|
Password |
|
|
|
|
NonPersistentMapping |
The reliability applied to nonpersistent JMS messages sent using this connection factory |
BestEffortNonPersistent ExpressNonPersistent ReliableNonPersistent |
ExpressNonPersistent |
|
PersistentMapping |
The reliability applied to persistent JMS messages sent using this connection factory |
ReliablePersistent AssuredPersistent |
ReliablePersistent |
|
DurableSubscriptionHome |
The name of the messaging engine used to store messages delivered to durable subscriptions for objects created from this JMS connection factory |
|
|
|
ReadAhead |
Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests |
AlwaysOn AlwaysOff Default |
Default |
|
Target |
The name of a target that identifies a group of messaging engines. Specify the type of target using the Target type property |
|
|
|
TargetType |
The type of target named in the Target property |
BusMember Custom ME |
BusMember |
|
TargetSignificance |
This property specifies the significance of the target group |
Required Preferred |
Required |
|
TargetTransportChain |
The name of the protocol that resolves to a group of messaging engines |
|
|
|
ProviderEndpoints |
The list of comma separated endpoints used to connect to a bootstrap server |
|
|
|
ConnectionProximity |
The proximity of messaging engines that can accept connection requests, in relation to the bootstrap messaging engine |
Server Cluster Host Bus |
Bus |
|
TemporaryQueueNamePrefix |
The prefix of up to twelve characters used for names of temporary queues created by applications that use this connection factory |
|
|
|
TemporaryTopicNamePrefix |
The prefix used at the start of temporary topics created by applications using this connection factory |
|
|
|
ShareDurableSubscriptions |
Controls whether or not durable subscriptions are shared across connections with members of a server cluster |
InCluster AlwaysShared NeverShared |
InCluster |
|
ConsumerDoesNotModifyPayloadAfterGet |
When enabled, Object Messages received by a message consuming application that has connected to this connection factory will only have their message data serialized by the system when absolutely necessary. The data obtained from these messages must be treated as readOnly by applications |
true false |
false |
|
ProducerDoesNotModifyPayloadAfterSet |
When enabled, Object/Bytes Messages sent by a message producing application that has connected to the bus using this connection factory will not have their data copied when set and the system will only serialize the message data when absolutely necessary. Applications sending such messages must not modify the data once it has been set into the message |
true false |
false |
|
Property name |
Description |
Permitted values |
Default |
|
BusName |
The name of the service integration bus to connect to |
|
|
|
UserName |
|
|
|
|
Password |
|
|
|
|
NonPersistentMapping |
The reliability applied to nonpersistent JMS messages sent using this connection factory |
BestEffortNonPersistent ExpressNonPersistent ReliableNonPersistent |
ExpressNonPersistent |
|
PersistentMapping |
The reliability applied to persistent JMS messages sent using this connection factory |
ReliablePersistent AssuredPersistent |
ReliablePersistent |
|
ReadAhead |
Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests |
AlwaysOn AlwaysOff Default |
Default |
|
Target |
The name of a target that identifies a group of messaging engines. Specify the type of target using the Target type property |
|
|
|
TargetType |
The type of target named in the Target property |
BusMember Custom ME |
BusMember |
|
TargetSignificance |
This property specifies the significance of the target group |
Required Preferred |
Required |
|
TargetTransportChain |
The name of the protocol that resolves to a group of messaging engines |
|
|
|
ProviderEndpoints |
The list of comma separated endpoints used to connect to a bootstrap server |
|
|
|
ConnectionProximity |
The proximity of messaging engines that can accept connection requests, in relation to the bootstrap messaging engine |
Server Cluster Host Bus |
Bus |
|
TemporaryQueueNamePrefix |
The prefix of up to twelve characters used for names of
temporary queues created by applications that use this connection factory |
|
|
|
ConsumerDoesNotModifyPayloadAfterGet |
When enabled, Object Messages received by a message consuming application that has connected to this connection factory will only have their message data serialized by the system when absolutely necessary. The data obtained from these messages must be treated as readOnly by applications |
true false |
false |
|
ProducerDoesNotModifyPayloadAfterSet |
When enabled, Object/Bytes Messages sent by a message producing application that has connected to the bus using this connection factory will not have their data copied when set and the system will only serialize the message data when absolutely necessary. Applications sending such messages must not modify the data once it has been set into the message |
true false |
false |
|
Property name |
Description |
Permitted values |
Default |
|
BusName |
The name of the service integration bus to connect to |
|
|
|
ClientID |
The JMS client identifier needed for durable topic subscriptions on all connections created using this connection factory |
|
|
|
UserName |
|
|
|
|
Password |
|
|
|
|
NonPersistentMapping |
The reliability applied to nonpersistent JMS messages sent using this connection factory |
BestEffortNonPersistent ExpressNonPersistent ReliableNonPersistent |
ExpressNonPersistent |
|
PersistentMapping |
The reliability applied to persistent JMS messages sent using this connection factory |
ReliablePersistent AssuredPersistent |
ReliablePersistent |
|
DurableSubscriptionHome |
The name of the messaging engine used to store messages delivered to durable subscriptions for objects created from this JMS connection factory |
|
|
|
ReadAhead |
Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests |
AlwaysOn AlwaysOff Default |
Default |
|
Target |
The name of a target that identifies a group of messaging engines. Specify the type of target using the Target type property |
|
|
|
TargetType |
The type of target named in the Target property |
BusMember Custom ME |
BusMember |
|
TargetSignificance |
This property specifies the significance of the target group |
Required Preferred |
Required |
|
TargetTransportChain |
The name of the protocol that resolves to a group of messaging engines |
|
|
|
ProviderEndpoints |
The list of comma separated endpoints used to connect to a bootstrap server |
|
|
|
ConnectionProximity |
The proximity of messaging engines that can accept connection requests, in relation to the bootstrap messaging engine |
Server Cluster Host Bus |
Bus |
|
TemporaryTopicNamePrefix |
The prefix used at
the start of temporary topics created by applications using this connection
factory |
|
|
|
ShareDurableSubscriptions |
Controls whether or not durable subscriptions are shared across connections with members of a server cluster |
InCluster AlwaysShared NeverShared |
InCluster |
|
ConsumerDoesNotModifyPayloadAfterGet |
When enabled, Object Messages received by a message consuming application that has connected to this connection factory will only have their message data serialized by the system when absolutely necessary. The data obtained from these messages must be treated as readOnly by applications |
true false |
false |
|
ProducerDoesNotModifyPayloadAfterSet |
When enabled, Object/Bytes Messages sent by a message producing application that has connected to the bus using this connection factory will not have their data copied when set and the system will only serialize the message data when absolutely necessary. Applications sending such messages must not modify the data once it has been set into the message |
true false |
false |
|
Property name |
Description |
Permitted values |
Default |
|
QueueName |
The name of the associated queue on the service
integration bus |
|
|
|
DeliveryMode |
The delivery mode for messages sent to this destination. This controls the persistence of messages on this destination |
Application Persistent NonPersistent |
|
|
TimeToLive |
The default length of time in milliseconds from its dispatch time that a message sent to this destination should be kept by the system |
|
|
|
Priority |
The relative priority for messages sent to this destination, in the range 0 to 9, with 0 as the lowest priority and 9 as the highest priority |
|
|
|
ReadAhead |
Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests |
AlwaysOn AlwaysOff AsConnection Default |
AsConnection |
|
BusName |
The name of the service integration bus to connect to |
|
|
|
Property name |
Description |
Permitted values |
Default |
|
TopicSpace |
The name of the
topic space that contains the topic, on the service integration bus defined
by the Bus name property |
|
Default.Topic.Space |
|
TopicName |
The name of the
topic that this JMS topic is assigned to, in the topic space defined by the
Topic space property |
|
|
|
DeliveryMode |
The delivery mode for messages sent to this destination. This controls the persistence of messages on this destination |
Application Persistent NonPersistent |
|
|
TimeToLive |
The default length of time in milliseconds from its dispatch time that a message sent to this destination should be kept by the system |
|
|
|
Priority |
The relative priority for messages sent to this destination, in the range 0 to 9, with 0 as the lowest priority and 9 as the highest priority |
|
|
|
ReadAhead |
Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests |
AlwaysOn AlwaysOff AsConnection Default |
AsConnection |
|
BusName |
The name of the service integration bus to connect to |
|
|
|
Property name |
Description |
Permitted values |
Default |
Required/Optional |
|
Destination |
The name of the
destination on the service integration bus |
|
|
Required |
|
ProviderEndpoints |
The list of comma
separated endpoints used to connect to a bootstrap server |
|
|
Required |
|
DestinationType |
Whether the message-driven bean uses a queue or topic destination |
javax.jms.Queue javax.jms.Topic |
|
Required |
|
BusName |
The name of the service integration bus to connect to |
|
|
Required |
|
MessageSelector |
The JMS message selector used to determine which messages the message-driven bean receives. The value is a string that is used to select a subset of the available messages. The syntax is based on a subset of the SQL 92 conditional expression syntax, as described in the JMS specification. Refer to the WebSphere Application Server InfoCenter for more information. |
|
|
Optional |
|
AcknowledgeMode |
How the session acknowledges any messages it receives |
Auto-acknowledge Dups-ok-acknowledge |
Auto-acknowledge |
Optional |
|
SubscriptionDurability |
Whether a JMS topic subscription is durable or nondurable |
Durable Nondurable |
Nondurable |
Optional |
|
SubscriptionName |
The subscription name needed for durable topic subscriptions. Required field when using a durable topic subscription |
|
|
Optional |
|
MaxBatchSize |
The maximum number of messages received from the messaging engine in a single batch. |
1
through 2147483647 |
1 |
Optional |
|
MaxConcurrency |
The maximum number of endpoints to which messages are delivered concurrently |
1
through 2147483647 |
10 |
Optional |
|
RetryInterval |
The delay (in seconds) between attempts to connect to a messaging engine |
1
through 2147483647 |
30 |
Optional |
|
UserName |
|
|
|
Optional |
|
Password |
|
|
|
Optional |
|
DurableSubscriptionHome |
The name of the messaging engine used to store messages delivered to durable subscriptions for objects created from this JMS connection factory |
|
|
Optional |
|
ShareDurableSubscriptions |
Controls whether or not durable subscriptions are shared across connections with members of a server cluster |
InCluster AlwaysShared NeverShared |
InCluster |
Optional |
|
ClientID |
The JMS client identifier needed for durable topic subscriptions on all connections created using this connection factory |
|
|
Optional |
|
TargetTransportChain |
The name of the protocol that resolves to a group of messaging engines |
|
|
Optional |
|
ReadAhead |
Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests |
AlwaysOn AlwaysOff Default |
Default |
Optional |
|
Target |
The name of a target that identifies a group of messaging engines. Specify the type of target using the Target type property |
|
|
Optional |
|
TargetType |
The type of target named in the Target property |
BusMember Custom ME |
BusMember |
Optional |
|
TargetSignificance |
This property specifies the significance of the target group |
Required Preferred |
Required |
Optional |
|
TopicSpace |
The name of the
topic space that contains the topic, on the service integration bus defined
by the Bus name property |
|
Default.Topic.Space |
Optional |
|
ConsumerDoesNotModifyPayloadAfterGet |
When enabled, Object Messages received by a message consuming application that has connected to this connection factory will only have their message data serialized by the system when absolutely necessary. The data obtained from these messages must be treated as readOnly by applications |
true false |
false |
Optional |
|
ForwarderDoesNotModifyPayloadAfterSet |
When enabled, Object/Bytes Messages forwarded through this
activation spec that have their payload modified will not have the data
copied when it is set into the message and the system will only serialize the
message data when absolutely necessary. Applications sending such messages
must not modify the data once it has been set into the message. |
true false |
false |
Optional |
In order to permit the recovery of indoubt transactions, all connection factories and activation configurations that specify an XA connection must always connect to a specific messaging engine. A specific messaging engine can be configured as the only suitable target for a connection factory or activation configuration by setting the appropriate connection properties:
TargetSignificance = Required
TargetType = ME
Target = <name of messaging
engine>
If an insufficiently specific set of connection factory or activation configuration properties is configured and an XA connection is requested, an exception is thrown during the connection attempt.
There are two approaches to
configuring SSL for the resource adapter: shared approach and private approach.
Both methods reply on system properties.
This approach uses JVM wide javax.net.ssl system properties.
The minimum javax.net.ssl
system properties that need to be configured are:
javax.net.ssl.keyStore
javax.net.ssl.keyStorePassword
javax.net.ssl.trustStore
javax.net.ssl.trustStorePassword
This approach allows the
configuration of resource adapter specific SSL properties.
A system property com.ibm.ws.sib.client.ssl.properties
is used to specify the properties file that contains the SSL properties, as
shown in the following example:
-Dcom.ibm.ws.sib.client.ssl.properties=c:\ssl.properties
If this system property is
configured, the resource adapter attempts to load SSL properties from the
configured file. If the system property is not configured, the resource adapter
attempts to load the file sib.client.ssl.properties from the classpath.
The value used for any particular
SSL property is obtained by first looking in the loaded SSL properties for com.ibm.*, if no value is found in the loaded SSL
properties then a suitable value is looked for in the associated javax.net.ssl.* system properties, finally a default value
will be used.
The following table shows the SSL
property keys that can be configured inside the SSL properties file, the
associated backup javax.net.ssl.* system property
keys and the defaults.
|
IBM |
Sun |
Default |
|
com.ibm.ssl.keyStoreType |
javax.net.ssl.keyStoreType |
JKS |
|
com.ibm.ssl.keyStore |
javax.net.ssl.keyStore |
|
|
com.ibm.ssl.keyManager |
javax.net.ssl.keyStoreProvider |
IbmX509 |
|
com.ibm.ssl.trustManager |
javax.net.ssl.trustStoreProvider |
IbmX509 |
|
com.ibm.ssl.keyStorePassword |
javax.net.ssl.keyStorePassword |
|
|
com.ibm.ssl.protocol |
|
SSL |
|
com.ibm.ssl.contextProvider |
|
IBMJSSE2 |
|
com.ibm.ws.sib.jsseProvider |
|
com.ibm.jsse2.IBMJSSEProvider2 |
|
com.ibm.ssl.trustStore |
javax.net.ssl.trustStore |
|
|
com.ibm.ssl.trustStoreType |
javax.net.ssl.trustStoreType |
JKS |
|
com.ibm.ssl.trustStorePassword |
javax.net.ssl.trustStorePassword |
|
There are two methods of enabling trace, both of which reply on system properties. These two methods are system property long form and system property short form. The long form takes priority over the short form and uses system properties that are unique to the resource adapter. The short form also uses a system property but, because it is un-qualified, it may clash with other third party technologies running in the same environment.
Long form system properties are:
|
Property |
Description |
|
com.ibm.ejs.ras.lite.traceSpecification |
The trace specification string |
|
com.ibm.ejs.ras.lite.traceFileName |
The trace destination (<file>, stdout, stderr, java,util.logging) |
|
com.ibm.ejs.ras.lite.maxFileSize |
The maximum trace file size in mb (if the trace destination is a file) |
|
com.ibm.ejs.ras.lite.maxFiles |
The maximum number of trace files kept (if the trace destination is a file) |
|
com.ibm.ejs.ras.lite.traceFormat |
The trace output format, basic or advanced (the default is basic) |
An example of long form is:
-Dcom.ibm.ejs.ras.lite.traceSpecification=SIB*=all
-Dcom.ibm.ejs.ras.lite.traceFileName=c:\trace.log
-Dcom.ibm.ejs.ras.lite.maxFileSize=20
-Dcom.ibm.ejs.ras.lite.maxFiles=8
The short form system property is:
traceSettingsFile
which must specify a loadable properties file which can contain the following properties:
|
Property |
Description |
|
traceFileName |
The trace destination (file, stdout, stderr, java.util.logging) |
|
maxFilesSize |
The maximim trace file size in mb (if the trace destination is a file) |
|
maxFiles |
The maximum number of trace files kept (if the trace destination is a file) |
|
<traceSpec> |
The trace specification |
|
traceFormat |
The trace output format, basic or advanced (the default is basic) |
An example of a short form properties file is:
SIBTrm=all:SIBMfp=all
traceFileName=c:\trace.log
Note: Some traceFileName property values have special meanings:
stdout - means write trace
records to stdout
stderr - means write trace
records to stderr
java.util.logging - means write trace
records to java.util.logging
Any other name means write trace records to a file of that name.
There are two methods of enabling FFDC output, both of which reply on system properties. These two methods are system property long form and system property short form. The long form takes priority over the short form and uses system properties that are unique to the resource adapter.
Long form system property:
com.ibm.ejs.ras.lite.ffdcLogFile
An example of long form is:
-Dcom.ibm.ejs.ras.lite.ffdcLogFile=c:\ffdc.log
Short form system property:
ffdcLogFile
An example of short form is:
-DffdcLogFile=c:\ffdc.log
For further information on how to configure service
integration bus connections, refer to the
http://www.ibm.com/software/webservers/appserv/was/library/
IBM and WebSphere are trademarks of IBM Corporation.
Java and all Java-based trademarks are trademarks of Sun
Microsystems, Inc. in the
Other company, product and service names may be trademarks or service marks of others.
© Copyright IBM Corporation 2007. All Rights Reserved.
US
Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA
ADP Schedule Contract with IBM Corp.