Configuration of the ResourceAdapter object

Configuration of the ResourceAdapter object

The ResourceAdapter object encapsulates the global properties of the WebSphere MQ resource adapter. The object has two sets of properties:

Properties associated with diagnostic tracing
Properties associated with the connection pool managed by the resource adapter
The way you define these properties depends on the administration interfaces provided by your application server.
Table 1 lists the properties of the ResourceAdapter object that are associated with diagnostic tracing.

Properties of the ResourceAdapter object that are associated with diagnostic tracing
Name of property Type Default value Description
traceEnabled String false A flag to enable or disable diagnostic tracing. If the value is false, tracing is turned off. If the value is true, a trace is sent to the location specified by the traceDestination property.
traceDestination String wmq_jca.trc The location to where a diagnostic trace is sent. If the value is System.err, the trace is directed to the system error stream instead of a file. Similarly, if the value is System.out, the trace is directed to the system output stream.
traceLevel String 3 The level of detail in a diagnostic trace. The value can be in the range 0, which produces no trace, to 10, which provides the most detail. See Table 2 for a description of each level.
timestampsEnabled String true A flag to enable or disable time stamps in a diagnostic trace. If the value is true, time stamps are added. If the value is false, time stamps are not added.
An application server might add time stamps to a stream automatically. In this case, set the value of the property to false to avoid the duplication of time stamps.
logWriterEnabled String true A flag to enable or disable the sending of a diagnostic trace to a LogWriter object provided by the application server. If the value is true, the trace is sent to a LogWriter object instead of the location specified by the traceDestination property. If the value is false, any LogWriter object provided by the application server is not used.

Table 2 describes the levels of detail for diagnostic tracing.

The levels of detail for diagnostic tracing
Level number Level of detail
0 No trace.
1 The trace contains error messages.
3 The trace contains error and warning messages.
6 The trace contains error, warning, and information messages.
8 The trace contains error, warning, and information messages, and entry and exit information for methods.
9 The trace contains error, warning, and information messages, entry and exit information for methods, and diagnostic data.
10 The trace contains all trace information.
Any level that is not included in this table is equivalent to the next lowest level. For example, specifying a trace level of 4 is equivalent to specifying a trace level of 3. However, the levels that are not included might be used in future releases of the WebSphere MQ resource adapter, so it is better to avoid using these levels.

If diagnostic tracing is turned off, error and warning messages are written to the system error stream. If diagnostic tracing is turned on, error messages are written to the system error stream and to the trace destination, but warning messages are written only to the trace destination. However, the trace contains warning messages only if the trace level is 3 or higher.
The resource adapter manages an internal connection pool of JMS connections that are used to deliver messages to MDBs. Table 3 lists the properties of the ResourceAdapter object that are associated with the connection pool.

Properties of the ResourceAdapter object that are associated with the connection pool
Name of property Type Default value Description
maxConnections String 10 The maximum number of connections to a WebSphere MQ queue manager.
connectionConcurrency String 5 The maximum number of MDBs that can be supplied by each connection.
reconnectionRetryCount String 5 The maximum number of attempts made by the resource adapter to reconnect to a WebSphere MQ queue manager if a connection fails.
reconnectionRetryInterval String 300 000 The time, in milliseconds, that the resource adapter waits before making another attempt to reconnect to a WebSphere MQ queue manager.

When an MDB is deployed in the application server, the resource adapter attempts to use an existing JMS connection from the connection pool. Each connection can supply more than one MDB up to the maximum specified by the connectionConcurrency property. If there are no connections in the pool, or if all the connections are fully utilized, a new connection is created provided the maximum number of connections specified by the maxConnections property is not exceeded. The maximum number of MDBs that can be deployed is therefore equal to the product of the maxConnections and connectionConcurrency properties, which is 50 by default. If the number of deployed MDBs reaches the maximum, any attempt to deploy another MDB fails. If an MDB is stopped, its connection can be used by another MDB.
If MDBs are likely to receive a high volume of messages, you might need to reduce the value of the connectionConcurrency property. If we need to limit the number of connections, because of restrictions imposed by a firewall for example, you might need to increase the value of the connectionConcurrency property. In general, if many MDBs are to be deployed, increase the value of the maxConnections property.
The reconnectionRetryCount and reconnectionRetryInterval properties govern the behavior of the resource adapter when connections to a WebSphere MQ queue manager fail, because of a network failure for example. When a connection fails, the resource adapter suspends the delivery of messages to all MDBs supplied by that connection for an interval specified by the reconnectionRetryInterval property. The resource adapter then attempts to reconnect to the queue manager. If the attempt fails, the resource adapter makes further attempts to reconnect at intervals specified by the reconnectionRetryInterval property until the limit imposed by the reconnectionRetryCount property is reached. If all attempts fail, delivery is stopped permanently until the MDBs are restarted manually.
In general, the ResourceAdapter object requires no administration. However, to enable diagnostic tracing on a UNIX system for example, we can set the following properties:
traceEnabled:       true
traceDestination:   /tmp/wmq_jca.trace
traceLevel:         10
These properties have no effect if the resource adapter has not been started, which is the case, for example, when applications using WebSphere MQ resources are running only in the client container. In this situation, we can set the properties for diagnostic tracing as Java Virtual Machine (JVM) system properties. We can do this by using the -D flag on the java command, as in the following example:
java ... -DtraceEnabled=true -DtraceDestination=System.err -DtraceLevel=6
You do not need to define all the properties of the ResourceAdapter object. Any properties left unspecified take their default values. In a managed environment, it is better not to mix the two ways of specifying properties. If you do mix them, the JVM system properties take precedence over the properties of the ResourceAdapter object.

uj40190_

Name of property	Type	Default value	Description
traceEnabled	String	false	A flag to enable or disable diagnostic tracing. If the value is false, tracing is turned off. If the value is true, a trace is sent to the location specified by the traceDestination property.
traceDestination	String	wmq_jca.trc	The location to where a diagnostic trace is sent. If the value is System.err, the trace is directed to the system error stream instead of a file. Similarly, if the value is System.out, the trace is directed to the system output stream.
traceLevel	String	3	The level of detail in a diagnostic trace. The value can be in the range 0, which produces no trace, to 10, which provides the most detail. See Table 2 for a description of each level.
timestampsEnabled	String	true	A flag to enable or disable time stamps in a diagnostic trace. If the value is true, time stamps are added. If the value is false, time stamps are not added. An application server might add time stamps to a stream automatically. In this case, set the value of the property to false to avoid the duplication of time stamps.
logWriterEnabled	String	true	A flag to enable or disable the sending of a diagnostic trace to a LogWriter object provided by the application server. If the value is true, the trace is sent to a LogWriter object instead of the location specified by the traceDestination property. If the value is false, any LogWriter object provided by the application server is not used.

Level number	Level of detail
0	No trace.
1	The trace contains error messages.
3	The trace contains error and warning messages.
6	The trace contains error, warning, and information messages.
8	The trace contains error, warning, and information messages, and entry and exit information for methods.
9	The trace contains error, warning, and information messages, entry and exit information for methods, and diagnostic data.
10	The trace contains all trace information.
Any level that is not included in this table is equivalent to the next lowest level. For example, specifying a trace level of 4 is equivalent to specifying a trace level of 3. However, the levels that are not included might be used in future releases of the WebSphere MQ resource adapter, so it is better to avoid using these levels.

Name of property	Type	Default value	Description
maxConnections	String	10	The maximum number of connections to a WebSphere MQ queue manager.
connectionConcurrency	String	5	The maximum number of MDBs that can be supplied by each connection.
reconnectionRetryCount	String	5	The maximum number of attempts made by the resource adapter to reconnect to a WebSphere MQ queue manager if a connection fails.
reconnectionRetryInterval	String	300 000	The time, in milliseconds, that the resource adapter waits before making another attempt to reconnect to a WebSphere MQ queue manager.