com.ibm.mq
Class MQEnvironment

java.lang.Object
  |
  +--com.ibm.mq.MQEnvironment

public class MQEnvironment
extends java.lang.Object

MQEnvironment contains static fields that control the environment in which an MQQueueManager object (and its corresponding connection to WebSphere MQ) is constructed. As values set in the MQEnvironment class take effect when the MQQueueManager constructor is called, you must set the values in the MQEnvironment class before you construct an MQQueueManager object.

Note: All the methods and attributes of this class apply to the WebSphere MQ classes for Java client connections, but only enableTracing(), disableTracing(), properties and version_notice apply to bindings connections.


Field Summary
static int CCSID
          The CCSID used by the client.
static java.lang.String channel
          The name of the channel to connect to on the target queue manager.
static int connOptions
          The queue manager connection options.
static byte[] connTag
          The connection tag which allows users to serialize access to the resources they are using on a z/OS queue manager.
static java.util.Collection hdrCompList
          The list of supported compressors for header compression.
static java.lang.String hostname
          The TCP/IP hostname of the machine on which the WebSphere MQ server resides.
static java.lang.String localAddressSetting
          The local address, including a range of ports, used when connecting to a WebSphere MQ queue manager through a firewall.
static java.util.Collection msgCompList
          The list of supported compressors for message compression.
static java.lang.String password
          The password used to verify the identity of the WebSphere MQ Client.
static int port
          The port to be used.
static java.util.Hashtable properties
          A Hashtable which defines the WebSphere MQ environment.
static MQReceiveExit receiveExit
          The receive exit used when receiving messages from a queue manager.
static MQSecurityExit securityExit
          The security exit used when connecting to a queue manager.
static MQSendExit sendExit
          The send exit used when sending messages to a queue manager.
static java.util.Collection sslCertStores
          Collection of SSL CertStores.
static java.lang.String sslCipherSuite
          The name of the Cipher Suite to be used by SSL.
static boolean sslFipsRequired
          When this is set to true, the only Cipher Suites that can be used on an SSL connection from this client process are those which are FIPS-enabled.
static java.lang.String sslPeerName
          The Distinguished Name (DN) of the queue manager to be used by SSL.
static int sslResetCount
          The total number of unencrypted bytes that are sent and received by the initiating channel MCA before the secret key is reset.
static java.lang.Object sslSocketFactory
          The factory to use when connecting with SSL encryption.
static java.lang.String userID
          The ID used to identify the WebSphere MQ client.
static java.lang.String version_notice
          The current version of the Websphere MQ Java Classes.
static boolean xaClientEnabled
           
 
Constructor Summary
MQEnvironment()
           
 
Method Summary
static MQPoolToken addConnectionPoolToken()
          Constructs an MQPoolToken and adds it to the set of tokens.
static void addConnectionPoolToken(MQPoolToken token)
          Adds a given MQPoolToken to the connection pool.
static void disableTracing()
          This method turns off the WebSphere MQ Client for Java trace facility.
static void enableTracing(int level)
          Turns on tracing at the specified trace level (traces to system.err).
static void enableTracing(int level, java.io.OutputStream stream)
          This method turns on tracing at the specified trace level.
static javax.resource.spi.ConnectionManager getDefaultConnectionManager()
          Gets the default ConnectionManager.
static MQQueueManager getQueueManagerReference(int scope)
          Returns an MQQueueManager object reference if one is available within the specified scope.
static MQQueueManager getQueueManagerReference(int scope, java.lang.Object context)
          Returns an MQQueueManager object reference if one is available within the specified scope.
static java.lang.String getVersionNotice()
          Gets the current version of the Websphere MQ Java Classes.
static void removeConnectionPoolToken(MQPoolToken token)
          Removes a token from the connection pool.
static void setDefaultConnectionManager(javax.resource.spi.ConnectionManager cxMan)
          Sets the default ConnectionManager, and empties the set of MQPoolTokens.
static void setDefaultConnectionManager(com.ibm.mq.MQConnectionManager mqCxMan)
          Sets the default MQConnectionManager, and empties the set of MQPoolTokens.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

version_notice

public static final java.lang.String version_notice
The current version of the Websphere MQ Java Classes.

See Also:
Constant Field Values

securityExit

public static MQSecurityExit securityExit
The security exit used when connecting to a queue manager. It allows you to customise the security flows that occur when an attempt is made to connect to a queue manager.

If you want to provide your own security exit, define a class that implements the MQSecurityExit interface and assign securityExit to an instance of that class.

If you set this field to null no security exit is called.


sendExit

public static MQSendExit sendExit
The send exit used when sending messages to a queue manager. It allows you to examine, and possibly alter, data and is normally used in conjunction with a corresponding receive exit at the queue manager.

If you want to provide your own send exit, define a class that implements the MQSendExit interface, and assign sendExit to an instance of that class.

If you set this field to null no send exit is called.


receiveExit

public static MQReceiveExit receiveExit
The receive exit used when receiving messages from a queue manager. It allows you to examine, and possibly alter, data and is normally used in conjunction with a corresponding send exit at the queue manager.

If you want to provide your own receive exit, define a class that implements the MQReceiveExit interface, and assign receiveExit to an instance of that class.

If you set this field to null no receive exit is called.


hostname

public static java.lang.String hostname
The TCP/IP hostname of the machine on which the WebSphere MQ server resides. If the hostname is not set, and no overriding properties are set, bindings mode is used to connect to the local queue manager.


port

public static int port
The port to be used. This is the port on which Websphere MQ listens for connection requests.

The default value is 1414.


channel

public static java.lang.String channel
The name of the channel to connect to on the target queue manager. It does not apply when connecting directly to WebSphere MQ in bindings mode. You must set this field, or the corresponding property, before constructing an MQQueueManager instance for use in client mode.


userID

public static java.lang.String userID
The ID used to identify the WebSphere MQ client. It is equivalent to the WebSphere MQ environment variable MQ_USER_ID.

If no security exit is defined for this client, the value of userID is transmitted to the server and is available for use by the server security exit.

The default value is "" (empty string).


password

public static java.lang.String password
The password used to verify the identity of the WebSphere MQ Client. It is equivalent to the MQ environment variable MQ_PASSWORD.

If a security exit is not defined for this client, the value of password is transmitted to the server and is available to the server security exit when it is invoked.

The default value is "" (empty string).


CCSID

public static int CCSID
The CCSID used by the client. It does not apply when connecting directly to WebSphere MQ in bindings mode.

Changing this value affects the way that the queue manager you connect to translates information in the WebSphere MQ headers. All data in WebSphere MQ headers is drawn from the invariant part of the ASCII codeset, except for the data in the MQMessage.applicationIdData and MQMessage.putApplicationName fields.

If you avoid using characters from the variant part of the ASCII codeset for these two fields, then the CCSID can be changed from 819 to any other ASCII codeset.

If you change the client CCSID to be the same as that of the queue manager to which you are connecting, you gain a performance benefit at the queue manager because it does not attempt to translate the message headers.

The default value is 819.

See Also:
MQMessage

hdrCompList

public static java.util.Collection hdrCompList
The list of supported compressors for header compression. Possible values are:


msgCompList

public static java.util.Collection msgCompList
The list of supported compressors for message compression. Possible values are:


sslCipherSuite

public static java.lang.String sslCipherSuite
The name of the Cipher Suite to be used by SSL. SSL is only valid for a client connection and is triggered by setting sslCipherSuite. If sslCipherSuite is not set, all of the other values are irrelevant and a standard non-SSL connection is used to connect to the server.

See Also:
sslCertStores, sslPeerName

sslPeerName

public static java.lang.String sslPeerName
The Distinguished Name (DN) of the queue manager to be used by SSL. The peer name is set to indicate that connections should only be allowed where the server is successfully authenticated as a specific DN.

See Also:
sslCipherSuite, sslCertStores

sslCertStores

public static java.util.Collection sslCertStores
Collection of SSL CertStores. The collection of CertStores (J2SE 1.4 only) is used to enable WebSphere MQ Java clients to check certificates for revocation in a Certificate Revocation List (CRL).

See Also:
sslCipherSuite, sslPeerName

sslSocketFactory

public static java.lang.Object sslSocketFactory
The factory to use when connecting with SSL encryption. If sslCipherSuite is set, this variable can be used to customize all aspects of the SSL connection.

For more information on constructing and customizing SSLSocketFactory instances, refer to your JSSE provider.

If set to null (default) and SSL encryption is requested, the default SSLSocketFactory is used.

This variable is ignored if sslCipherSuite is null.


sslResetCount

public static int sslResetCount
The total number of unencrypted bytes that are sent and received by the initiating channel MCA before the secret key is reset. The number of bytes includes control information sent by the message channel agent. A value of 0 disables secret key reset from occurring.


sslFipsRequired

public static boolean sslFipsRequired
When this is set to true, the only Cipher Suites that can be used on an SSL connection from this client process are those which are FIPS-enabled. In this case, if and a customized sslSocketFactory has been specified the customized sslSocketFactory will not be used, as it cannot be guaranteed that the sslSocketFactory is FIPS compliant.


localAddressSetting

public static java.lang.String localAddressSetting
The local address, including a range of ports, used when connecting to a WebSphere MQ queue manager through a firewall. The format is [ip-addr][(low-port[,high-port])].

Here are some examples:

9.20.4.98
The channel binds to address 9.20.4.98 locally
9.20.4.98(1000)
The channel binds to address 9.20.4.98 locally and uses port 1000
9.20.4.98(1000,2000)
The channel binds to address 9.20.4.98 locally and uses a port in the range 1000 to 2000
(1000)
The channel binds to port 1000 locally
(1000,2000)
The channel binds to a port in the range 1000 to 2000 locally

You can specify a host name instead of an IP address. The variable is initialized from system property com.ibm.mq.localAddress when you start the JVM. The default value is null.


connTag

public static byte[] connTag
The connection tag which allows users to serialize access to the resources they are using on a z/OS queue manager. The connTag String is truncated to 128 bytes. connTag is ignored if connOptions is not set.


connOptions

public static int connOptions
The queue manager connection options. Possible values are:


properties

public static java.util.Hashtable properties
A Hashtable which defines the WebSphere MQ environment.

This Hashtable allows you to set environment properties as key/value pairs rather than as individual variables.

The properties can also be passed as a Hashtable in a parameter on the MQQueueManager constructor. Properties passed on the constructor take precedence over values set with this properties variable, but they are otherwise interchangeable. The order of precedence of finding properties is:

  1. properties parameter on MQQueueManager constructor
  2. MQEnvironment.properties
  3. Other MQEnvironment variables
  4. Constant default values

The property key names are:

MQC.CCSID_PROPERTY
overrides CCSID.
MQC.CHANNEL_PROPERTY
overrides channel.
MQC.CONNECT_OPTIONS_PROPERTY
overrides connOptions.
MQC.CONNTAG_PROPERTY
overrides connTag.
MQC.HEADER_COMPRESSION_PROPERTY
overrides hdrCompList.
MQC.MESSAGE_COMPRESSION_PROPERTY
overrides msgCompList.
MQC.HOST_NAME_PROPERTY
overrides hostname.
MQC.LOCAL_ADDRESS_PROPERTY
overrides localAddressSetting.
MQC.PASSWORD_PROPERTY
overrides password.
MQC.PORT_PROPERTY
overrides port.
MQC.RECEIVE_EXIT_PROPERTY
overrides receiveExit.
MQC.SECURITY_EXIT_PROPERTY
overrides securityExit.
MQC.SEND_EXIT_PROPERTY
overrides sendExit.
MQC.SSL_CERT_STORE_PROPERTY
overrides sslCertStores.
MQC.SSL_CIPHER_SUITE_PROPERTY
overrides sslCipherSuite.
MQC.SSL_FIPS_REQUIRED
overrides sslFipsRequired.
MQC.SSL_RESET_COUNT_PROPERTY.
overrides sslResetCount.
MQC.SSL_PEER_NAME_PROPERTY.
overrides sslPeerName.
MQC.SSL_SOCKET_FACTORY_PROPERTY
overrides sslSocketFactory.
MQC.TRANSPORT_PROPERTY
forces MQC.TRANSPORT_MQSERIES_BINDINGS or MQC.TRANSPORT_MQSERIES_CLIENT.
MQC.USER_ID_PROPERTY
overrides userID.


xaClientEnabled

public static boolean xaClientEnabled
Constructor Detail

MQEnvironment

public MQEnvironment()
Method Detail

getVersionNotice

public static final java.lang.String getVersionNotice()
Gets the current version of the Websphere MQ Java Classes.

Returns:
the version.

enableTracing

public static void enableTracing(int level)
Turns on tracing at the specified trace level (traces to system.err). Levels are:
0
entry/exit
1
as above plus error and exceptions
2
as above plus some parameter and flow information.
3
as above plus data trace for headers flowing between client and queue manager.
4
as above plus full data trace of all data sent between client and queue manager.
5
as above plus Java VM method tracing.

Parameters:
level - the level of trace.

enableTracing

public static void enableTracing(int level,
                                 java.io.OutputStream stream)
This method turns on tracing at the specified trace level. See enableTracing(int) for details of levels.

Specifying a FileOutputStream means that in a WebSphere Application Server version 5 environment, the WebSphere MQ Base Java classes trace is not redirected to the WebSphere Application Server trace adapter, which expects a JMS context.

If the trace string JMSApi=all=enabled is specified within the WebSphere Application Server version 5 environment at the same time as this is run, it takes priority and this tracing is disabled.

Parameters:
level - the level of trace.
stream - the stream to which output is sent.

disableTracing

public static void disableTracing()
This method turns off the WebSphere MQ Client for Java trace facility.


setDefaultConnectionManager

public static void setDefaultConnectionManager(com.ibm.mq.MQConnectionManager mqCxMan)
Sets the default MQConnectionManager, and empties the set of MQPoolTokens. The default ConnectionManager is used when no ConnectionManager is specified on the MQQueueManager constructor.

Parameters:
mqCxMan - the supplied MQConnectionManager.

setDefaultConnectionManager

public static void setDefaultConnectionManager(javax.resource.spi.ConnectionManager cxMan)
Sets the default ConnectionManager, and empties the set of MQPoolTokens. The default ConnectionManager is used when no ConnectionManager is specified on the MQQueueManager constructor. This method requires a JVM at Java 2 v1.3 or later, with JAAS 1.0 or later installed.

Parameters:
cxMan - the supplied ConnectionManager.

getDefaultConnectionManager

public static javax.resource.spi.ConnectionManager getDefaultConnectionManager()
Gets the default ConnectionManager.

Returns:
the ConnectionManager, or null if the default connection manager is an MQConnectionManager rather than a ConnectionManager.

addConnectionPoolToken

public static void addConnectionPoolToken(MQPoolToken token)
Adds a given MQPoolToken to the connection pool. A default ConnectionManager can use this as a hint; typically, it is enabled only while there is at least one token in the connection pool.

Parameters:
token - the token to be added.

addConnectionPoolToken

public static MQPoolToken addConnectionPoolToken()
Constructs an MQPoolToken and adds it to the set of tokens. The token is returned to the application to be passed later into the removeConnectionPoolToken() method.

Returns:
the token that has been added.

removeConnectionPoolToken

public static void removeConnectionPoolToken(MQPoolToken token)
Removes a token from the connection pool.

Parameters:
token - the token to be removed.

getQueueManagerReference

public static MQQueueManager getQueueManagerReference(int scope)
Returns an MQQueueManager object reference if one is available within the specified scope. The scope must be one of MQC.ASSOCIATE_ALL or MQC.ASSOCIATE_THREAD, and a queue manager must already have been created with MQC.MQ_QMGR_ASSOCIATION_PROPERTY set to the scope requested.

If no queue manager has been created within the specified scope, or if MQC.ASSOCIATE_NONE is specified, this method will return null.

A call to this method is the same as calling MQEnvironment.getQueueManagerReference(int, Object) with a null Object.

Parameters:
scope - the association scope
Returns:
MQQueueManager, or null if no reference is available.
See Also:
getQueueManagerReference(int, Object)

getQueueManagerReference

public static MQQueueManager getQueueManagerReference(int scope,
                                                      java.lang.Object context)
Returns an MQQueueManager object reference if one is available within the specified scope. The scope must be one of MQC.ASSOCIATE_ALL or MQC.ASSOCIATE_THREAD, and a queue manager must already have been created with MQC.MQ_QMGR_ASSOCIATION_PROPERTY set to the scope requested. The supplied Object gives information necessary to identify the MQQueueManager within the scope; for MQC.ASSOCIATE_ALL and MQC.ASSOCIATE_THREAD this Object must be a String containing the name of the queue manager.

If no queue manager identified by the supplied Object has been created within the specified scope, or if MQC.ASSOCIATE_NONE is specified, this method will return null.

An MQQueueManager object returned by this method will refer to the same underlying HConn as the MQQueueManager created with MQC.MQ_QMGR_ASSOCIATION_PROPERTY set, and both will therefore share the same transaction context. If an attempt is made to create a second MQQueueManager object on the same context to a different queue manager, then a separate HConn will be made, and the first and second object will have independent transaction contexts. These contexts will extend to WebSphere MQ coordinated JDBC transactions by using MQQueueManager.getJDBCConnection(XADataSource) on the appropriate queue manager.

Parameters:
scope - the association scope
context - an object containing context. Currently this must be a String specifying a WebSphere MQ queue manager name
Returns:
MQQueueManager, or null if no reference is available.

(c) Copyright IBM Corp. 2005. All Rights Reserved.