Class MQEnvironment
- java.lang.Object
-
- com.ibm.mq.jmqi.JmqiObject
-
- com.ibm.mq.MQEnvironment
-
public class MQEnvironment extends com.ibm.mq.jmqi.JmqiObject
MQEnvironment contains static fields that control the environment in which an MQQueueManager object (and its corresponding connection to IBM 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 IBM MQ classes for Java client connections, but only enableTracing(), disableTracing(), properties, version_notice, userID, connOptions and connTag apply to bindings connections.
-
-
Field Summary
Fields Modifier and Type Field and Description static java.net.URL
ccdtUrlProperty
A URL specifying the location of a Client Channel Definition Table (CCDT) to define the connection properties.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 java.lang.Object
channelReceiveExit
The receive exit used when receiving messages from a queue manager.static java.lang.String
channelReceiveExitUserData
static java.lang.Object
channelSecurityExit
The security exit used when connecting to a queue manager.static java.lang.String
channelSecurityExitUserData
static java.lang.Object
channelSendExit
The send exit used when sending messages to a queue manager.static java.lang.String
channelSendExitUserData
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.lang.String
exitClasspath
When defining Java security, send or receive exit as strings to be loaded by the class loader, the path that has the class or jar that contains the class has to be known to the loader.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 IBM MQ server resides.static java.lang.String
localAddressSetting
The local address, including a range of ports, used when connecting to an IBM 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 IBM MQ Client.static int
port
The port to be used.static java.util.Hashtable
properties
A Hashtable which defines the IBM MQ environment.static MQReceiveExit
receiveExit
Deprecated.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.
static java.lang.String
receiveExitUserData
Deprecated.static MQSecurityExit
securityExit
Deprecated.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.
static java.lang.String
securityExitUserData
Deprecated.static MQSendExit
sendExit
Deprecated.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.
static java.lang.String
sendExitUserData
Deprecated.static int
sharingConversations
The number of conversations per connection.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 IBM MQ client.static java.lang.String
version_notice
The current version of the IBM MQ Java Classes.
-
Constructor Summary
Constructors Constructor and Description MQEnvironment()
Constructor
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method and Description 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 IBM MQ Client for Java trace facility.static void
enableTracing(int level)
static void
enableTracing(int level, java.io.OutputStream stream)
Turns on tracing to console & (default) filestatic com.ibm.mq.MQConnectionManager
getDefaultConnectionManager()
Gets the default ConnectionManager.static MQQueueManager
getQueueManagerReference(int scope)
Deprecated.This method and MQC.MQ_QMGR_ASSOCIATION_PROPERTY are deprecated, as they generally provide no particular value.static MQQueueManager
getQueueManagerReference(int scope, java.lang.Object context)
Deprecated.This method and MQC.MQ_QMGR_ASSOCIATION_PROPERTY are deprecated, as they generally provide no particular value.static java.lang.String
getVersionNotice()
Gets the current version of the IBM MQ Java Classes.static void
removeConnectionPoolToken(MQPoolToken token)
Removes a token from the connection pool.static void
setDefaultConnectionManager(com.ibm.mq.MQConnectionManager mqCxMan)
Sets the default MQConnectionManager, and empties the set of MQPoolTokens.
-
-
-
Field Detail
-
version_notice
public static final java.lang.String version_notice
The current version of the IBM MQ Java Classes.- See Also:
- Constant Field Values
-
securityExit
public static MQSecurityExit securityExit
Deprecated. 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.
-
securityExitUserData
public static java.lang.String securityExitUserData
Deprecated.
-
channelSecurityExit
public static java.lang.Object channelSecurityExit
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 either:- MQSecurityExit, WMQSecurityExit interface or String and assign securityExit to an instance of that class or the class definition to the string.
If you set this field to null no security exit is called.
-
channelSecurityExitUserData
public static java.lang.String channelSecurityExitUserData
-
sendExit
public static MQSendExit sendExit
Deprecated. 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.
-
sendExitUserData
public static java.lang.String sendExitUserData
Deprecated.
-
channelSendExit
public static java.lang.Object channelSendExit
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 either:- MQSendExit, WMQSendExit interface or List or String and assign sendExit to an instance of that class or the class definition to the string.
If you set this field to null no send exit is called.
-
channelSendExitUserData
public static java.lang.String channelSendExitUserData
-
receiveExit
public static MQReceiveExit receiveExit
Deprecated. 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.
-
receiveExitUserData
public static java.lang.String receiveExitUserData
Deprecated.
-
channelReceiveExit
public static java.lang.Object channelReceiveExit
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 send exit, define a class that implements either:- MQReceiveExit, WMQReceiveExit interface or List ro String and assign receiveExit to an instance of that class or the class definition to the string.
If you set this field to null no receive exit is called.
-
channelReceiveExitUserData
public static java.lang.String channelReceiveExitUserData
-
exitClasspath
public static java.lang.String exitClasspath
When defining Java security, send or receive exit as strings to be loaded by the class loader, the path that has the class or jar that contains the class has to be known to the loader. The loader uses the system property com.ibm.mq.exitClasspath to find the classes. This property can be used by the client application to add the path of the class that will be dynamically loaded.
-
hostname
public static java.lang.String hostname
The TCP/IP hostname of the machine on which the IBM 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 IBM 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 IBM 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 IBM MQ client. It is equivalent to the IBM MQ environment variable MQ_USER_ID.
The default value is null.
If no security exit is defined for this client and userID is set to null or the empty string "" the IBM MQ classes for Java will query the Java System Property "user.name" and transmit this to the server.
If no security exit is defined for this client and userID has been set to a value other than null and the empty string "", then this value will be transmitted to the server.
If a security exit is defined for this client, then it is the responsibility of the exit to apply any application specific security logic. The value of userID is not made available to the exit and is not transmitted to the server.
-
password
public static java.lang.String password
The password used to verify the identity of the IBM 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 null.
-
ccdtUrlProperty
public static java.net.URL ccdtUrlProperty
A URL specifying the location of a Client Channel Definition Table (CCDT) to define the connection properties.
-
CCSID
public static int CCSID
The CCSID used by the client. It does not apply when connecting directly to IBM MQ in bindings mode.Changing this value affects the way that the queue manager you connect to translates information in the IBM MQ headers. All data in IBM MQ headers is drawn from the invariant part of the ASCII codeset, except for the data in the
MQMessage.applicationIdData
andMQMessage.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. For the reasons outlined above, this only applies to ASCII codesets - you must not set the CCSID to an EBCDIC-based value when communicating with a queue manager using EBCDIC.
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 IBM 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 an IBM 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 ifconnOptions
is not set.
-
connOptions
public static int connOptions
The queue manager connection options. Possible values are:MQConstants.MQCNO_STANDARD_BINDING
MQConstants.MQCNO_FASTPATH_BINDING
MQConstants.MQCNO_ISOLATED_BINDING
MQConstants.MQCNO_SHARED_BINDING
MQConstants.MQCNO_RESTRICT_CONN_TAG_Q_MGR
MQConstants.MQCNO_RESTRICT_CONN_TAG_QSG
MQConstants.MQCNO_SERIALIZE_CONN_TAG_Q_MGR
MQConstants.MQCNO_SERIALIZE_CONN_TAG_QSG
-
sharingConversations
public static int sharingConversations
The number of conversations per connection. Allows user to turn multiplexing ON or OFF. A value of 0 turns multiplexing off.
-
properties
public static java.util.Hashtable properties
A Hashtable which defines the IBM 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:- properties parameter on MQQueueManager constructor
- MQEnvironment.properties
- Other MQEnvironment variables
- Constant default values
The property key names are:
MQC.CCDT_URL_PROPERTY
- overrides
ccdtUrlProperty
. MQConstants.CCSID_PROPERTY
- overrides
CCSID
. MQConstants.CHANNEL_PROPERTY
- overrides
channel
. MQConstants.CONNECT_OPTIONS_PROPERTY
- overrides
connOptions
. MQConstants.CONNTAG_PROPERTY
- overrides
connTag
. MQC.HEADER_COMPRESSION_PROPERTY
- overrides
hdrCompList
. MQC.MESSAGE_COMPRESSION_PROPERTY
- overrides
msgCompList
. MQConstants.HOST_NAME_PROPERTY
- overrides
hostname
. MQConstants.LOCAL_ADDRESS_PROPERTY
- overrides
localAddressSetting
. MQConstants.PASSWORD_PROPERTY
- overrides
password
. MQConstants.PORT_PROPERTY
- overrides
port
. The next three warnings are unavoidable I fear... - The deprecated property MQConstants.RECEIVE_EXIT_PROPERTY
- overrides
receiveExit
. - The deprecated property MQConstants.SECURITY_EXIT_PROPERTY
- overrides
securityExit
. - The deprecated property MQConstants.SEND_EXIT_PROPERTY
- overrides
sendExit
. MQConstants.SSL_CERT_STORE_PROPERTY
- overrides
sslCertStores
. MQConstants.SSL_CIPHER_SUITE_PROPERTY
- overrides
sslCipherSuite
. MQConstants.SSL_FIPS_REQUIRED
- overrides
sslFipsRequired
. MQConstants.SSL_RESET_COUNT_PROPERTY
.- overrides
sslResetCount
. MQConstants.SSL_PEER_NAME_PROPERTY
.- overrides
sslPeerName
. MQConstants.SSL_SOCKET_FACTORY_PROPERTY
- overrides
sslSocketFactory
. MQConstants.TRANSPORT_PROPERTY
- forces
MQConstants.TRANSPORT_MQSERIES_BINDINGS
orMQConstants.TRANSPORT_MQSERIES_CLIENT
. MQConstants.USER_ID_PROPERTY
- overrides
userID
. MQC.SHARING_CONVERSATIONS_PROPERTY
- overrides
sharingConversations
.
-
-
Method Detail
-
getVersionNotice
public static final java.lang.String getVersionNotice()
Gets the current version of the IBM MQ Java Classes.- Returns:
- the version.
-
enableTracing
public static void enableTracing(int level)
- Parameters:
level
- ignored at this version
-
enableTracing
public static void enableTracing(int level, java.io.OutputStream stream)
Turns on tracing to console & (default) file- Parameters:
level
- ignored at this versionstream
- ignored (unfortunately) at present
-
disableTracing
public static void disableTracing()
This method turns off the IBM 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.
-
getDefaultConnectionManager
public static com.ibm.mq.MQConnectionManager 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 theremoveConnectionPoolToken()
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)
Deprecated. This method and MQC.MQ_QMGR_ASSOCIATION_PROPERTY are deprecated, as they generally provide no particular value.Returns anMQQueueManager
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 the MQC.MQ_QMGR_ASSOCIATION_PROPERTY 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)
Deprecated. This method and MQC.MQ_QMGR_ASSOCIATION_PROPERTY are deprecated, as they generally provide no particular value.Returns anMQQueueManager
object reference if one is available within the specified scope. The scope must be one ofMQC.ASSOCIATE_ALL
orMQC.ASSOCIATE_THREAD
, and a queue manager must already have been created withMQC.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 MQConstants.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 IBM MQ coordinated JDBC transactions by using
MQQueueManager.getJDBCConnection(XADataSource)
on the appropriate queue manager.- Parameters:
scope
- the association scopecontext
- an object containing context. Currently this must be a String specifying an IBM MQ queue manager name- Returns:
- MQQueueManager, or null if no reference is available.
-
-