MQQueueManager
public class MQQueueManager
extends MQManagedObject
java.lang.Object
|
+----com.ibm.mq.MQManagedObject
|
+----com.ibm.mq.MQQueueManager
The MQQueueManager class provides a connection to a WebSphere
MQ queue manager.
An MQQueueManager object (and any queues or processes accessed
through it) can be shared between multiple threads, but be aware that access
to the WebSphere MQ queue manager itself is synchronized, so that
only one thread can communicate with it at any one time. A call to
MQQueue.get() specifying MQC.MQGMO_WAIT (for example) will
therefore block any other threads attempting to make WebSphere MQ calls using
the same MQQueueManager until the get completes.
Constructors
MQQueueManager
public MQQueueManager(String queueManagerName) throws MQException;
Creates a connection to the named queue manager.
The host name, channel name and port to use during the connection request
are specified in the MQEnvironment class. This must be
done before calling this constructor.
The following example shows a connection to a queue manager "MYQM", running
on a system with host name "fred.mq.com".
MQEnvironment.hostname = "fred.mq.com"; // host to connect to
MQEnvironment.port = -1 ; // port to connect to. If not set,
// this defaults to 1414 for WebSphere MQ
// client connections.
MQEnvironment.channel = "channel.name"; // the CASE-SENSITIVE name of the SVRCONN
// channel on the queue manager
MQQueueManager qMgr = new MQQueueManager("MYQM");
If the queue manager name is null or blank, then a connection is made to
the default queue manager.
- Parameters
-
- queueManagerName - the name of the queue manager to which to connect.
- Exceptions
-
- MQException - if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName,
ConnectionManager connectionManager)
throws MQException;
Creates a connection to the named queue manager specifying a connection
manager.
- Parameters
-
- queueManagerName - the name of the queue manager.
- connectionManager - the connection manager which will handle this connection.
- Exceptions
-
- MQException - if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, Hashtable properties)
throws MQException;
Creates a connection to the named queue manager using a
Hashtable. The Hashtable overrides the specification
held in MQEnvironment.
- Parameters
-
- queueManagerName - the name of the queue manager.
- properties - connection properties.
- Exceptions
-
- MQException - if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, Hashtable properties,
ConnectionManager connectionManager)
throws MQException;
Creates a connection to the named queue manager using given Hashtable and
connection manager. The given properties override those held in
MQEnvironment.
- Parameters
-
- queueManagerName - the name of the queue manager.
- properties - connection properties.
- connectionManager - the ConnectionManager which handles this connection.
- Exceptions
-
- MQException - if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, Hashtable properties,
MQConnectionManager connectionManager)
throws MQException;
Creates a connection to a queue manager which overrides the settings in
MQEnvironment class with those in the given
Hashtable.
- Parameters
-
- queueManagerName - the name of the queue manager.
- properties - connection properties.
- connectionManager - the connection manager which will handle this connection.
- Exceptions
-
- MQException - raised if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, Hashtable properties,
URL url) throws MQException;
Creates a connection to the named queue manager using a channel definition
table. Using a client channel definition table enables alternative channel
definitions to be defined. The constructor selects a set of definitions from
the table and these are used instead of any settings held in
MQEnvironment class when opening a channel. Properties other than
those defined by the client channel definition table can be supplied with
this constructor.
- Parameters
-
- queueManagerName - the queue manager which is used when selecting a channel
definition. This can be in of the following forms:
- "qMgrName", where the actual name of the required queue manager is passed
in. The channel must connect to a queue manager of this name.
- "*qMgrName", where "*" followed by the actual name of the required queue
manager is passed in. The channel definition that is used must specify this
queue manager name. This full name is passed onto the queueManager during
a connect, but the queue manager that is ultimately connected to might not
have the same name as specified here after the '*'.
- "*" or "" or a name which consists entirely of blanks is passed in. The
actual queue manager name is disregarded when a channel definition is being
selected.
- properties - A Hashtable of properties to be used to establish the connection
with those defined in the client channel definition that is actually used.
Any properties that are not valid for this type of connection will be ignored.
- url - the URL which specifies the channel definition file to be used in
connecting to the queue manager.
- Exceptions
-
- MQException - raised if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, int options)
throws MQException;
Creates a connection to the named queue manager specifying binding options.
- Parameters
-
- queueManagerName - the name of the queue manager.
- options - binding options. Possible values are:
- MQC.MQCNO_FASTPATH_BINDING
- MQC.MQCNO_STANDARD_BINDING
- MQC.MQCNO_SHARED_BINDING
- MQC.MQCNO_ISOLATED_BINDING
- Exceptions
-
- MQException - if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, int options,
ConnectionManager connectionManager)
throws MQException;
Creates a connection to the named queue manager specifying bindings options
and a connection manager.
- Parameters
-
- queueManagerName - the name of the queue manager.
- options - binding options. Possible values are:
- MQC.MQCNO_FASTPATH_BINDING
- MQC.MQCNO_STANDARD_BINDING
- MQC.MQCNO_SHARED_BINDING
- MQC.MQCNO_ISOLATED_BINDING
- connectionManager - the Connection manager which handles this connection
- Exceptions
-
- MQException - if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, int options,
MQConnectionManager connectionManager)
throws MQException;
Creates a connection to a queue manager allowing binding options to be
specified. It also allows a connection manager to be specified.
- Parameters
-
- queueManagerName - the name of the queue manager.
- options - binding options. Possible values are:
- MQC.MQCNO_FASTPATH_BINDING
- MQC.MQCNO_STANDARD_BINDING
- MQC.MQCNO_SHARED_BINDING
- MQC.MQCNO_ISOLATED_BINDING
- connectionManager - the connection manager which will handle this connection.
- Exceptions
-
- MQException - if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName,
MQConnectionManager connectionManager)
throws MQException;
Creates a connection to a named queue manager using a connection manager.
- Parameters
-
- queueManagerName - the name of the queue manager.
- connectionManager - the connection manager which will handle this connection.
- Exceptions
-
- MQException - if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, URL url)
throws MQException;
Creates a connection to the named queue manager using a channel definition
table. Using a client channel definition table enables alternative channel
definitions to be defined. The constructor selects a set of definitions from
the table and these are used instead of any settings held in
MQEnvironment class when opening a channel.
- Parameters
-
- queueManagerName - the queue manager which is used when selecting a channel
definition. This can be in of the following forms:
- "qMgrName", where the actual name of the required queue manager is passed
in. The channel must connect to a queue manager of this name.
- "*qMgrName", where "*" followed by the actual name of the required queue
manager is passed in. The channel definition that is used must specify this
queue manager name. This full name is passed onto the queue manager during
a connect, but the queue manager that is ultimately connected to might not
have the same name as specified here after the '*'.
- "*" or "" or a name which consists entirely of blanks is passed in. The
actual queue manager name is disregarded when a channel definition is being
selected.
- url - the URL which specifies the channel definition file to be used in
connecting to the queue manager.
- Exceptions
-
- MQException - raised if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, URL url,
ConnectionManager connectionManager)
throws MQException;
Creates a connection to the named queue manager using a client channel
definition table. Using a client channel definition table enables alternative
channel definitions to be defined. The constructor selects a set of definitions
from the table and these are used instead of any settings held in
MQEnvironment class when opening a channel. The channel definition
that is used must specify this queue manager name. This full name is passed
onto the queue manager during a connect, but the queue manager that is ultimately
connected to might not have the same name as specified here after the "*"
"*" or "" or a name which consists entirely of blanks is passed in. The actual
queue manager name is disregarded when a channel definition is being selected.
- Parameters
-
- queueManagerName - the queue manager which is used when selecting a channel
definition. This can be in of the following forms:
- "qMgrName", where the actual name of the required queue manager is passed
in. The channel must connect to a queue manager of this name.
- "*qMgrName", where "*" followed by the actual name of the required queue
manager is passed in. The channel definition that is used must specify this
queue manager name. This full name is passed onto the queue manager during
a connect, but the queue manager that is ultimately connected to might not
have the same name as specified here after the "*".
- "*" or "" or a name which consists entirely of blanks is passed in. The
actual queue manager name is disregarded when a channel definition is being
selected.
- url - the URL which specifies the channel definition table to be used
in connecting to the queue manager.
- connectionManager - the connection manager.
- Exceptions
-
- MQException - raised if there are connection problems.
MQQueueManager
public MQQueueManager(String queueManagerName, URL url,
MQConnectionManager connectionManager)
throws MQException;
Creates a connection to the named queue manager using a client channel
definition table. Using a client channel definition table enables alternative
channel definitions to be defined. The constructor selects a set of definitions
from the table and these are used instead of any settings held in
MQEnvironment class when opening a channel.
- Parameters
-
- queueManagerName - the queue manager which is used when selecting a channel
definition. This can be in of the following forms:
- "qMgrName", where the actual name of the required queue manager is passed
in. The channel must connect to a queue manager of this name.
- "*qMgrName", where "*" followed by the actual name of the required queue
manager is passed in. The channel definition that is used must specify this
queue manager name. This full name is passed onto the queue manager during
a connect, but the queue manager that is ultimately connected to might not
have the same name as specified here after the "*".
- "*" or "" or a name which consists entirely of blanks is passed in. The
actual queue manager name is disregarded when a channel definition is being
selected.
- url - the URL which specifies the channel definition file to be used in
connecting to the queue manager.
- connectionManager - the connection manager.
- Exceptions
-
- MQException - raised if there are connection problems.
Fields
isConnected
public boolean
Deprecated
Use the isConnected() method instead.
Indicates whether this MQQueueManager object is currently
connected to a WebSphere MQ queue manager. Use the disconnect
method to disconnect from a queue manager.
Methods
accessDistributionList
public MQDistributionList accessDistributionList(MQDistributionListItem[] items,
int options)
throws MQException;
Creates a distribution list using the default alternative user ID.
- Parameters
-
- items - the elements of the distribution list.
- options - the open options for the distribution list.
- Returns
-
- Exceptions
-
- MQException - if there is a problem opening the distribution list.
accessDistributionList
public MQDistributionList accessDistributionList(MQDistributionListItem[] items,
int options,
String id)
throws MQException;
Creates a distribution list.
- Parameters
-
- items - the elements of the distribution list.
- options - the open options for the distribution list.
- id - the alternative user ID.
- Returns
-
- Exceptions
-
- MQException - if there is a problem opening the distribution list.
accessProcess
public MQProcess accessProcess(String processName, int openOptions)
throws MQException;
Accesses a WebSphere MQ process on this queue manager using default queue
manager name and alternative user ID values.
- Parameters
-
- processName - name of process to open.
- openOptions - see openOptions for details.
- Returns
-
- MQProcess which has been successfully opened.
- Exceptions
-
- MQException - if the open fails.
accessProcess
public MQProcess accessProcess(String processName, int openOptions,
String queueManagerName,
String alternateUserId)
throws MQException;
Establishes access to a WebSphere MQ process on this queue manager in order
to inquire about the process attributes.
- Parameters
-
- processName - name of process to open
- openOptions - options which control the opening of the process. As inquire
is automatically added to the options specified there is no need to specify
it explicitly. Valid options are:
- MQC.MQOO_ALTERNATE_USER_AUTHORITY
- MQC.MQOO_FAIL_IF_QUIESCING
If more than one option is required the values can be combined using
either the '+' or '|' operator.
- queueManagerName - name of the queue manager on which the process is defined.
A name which is entirely blank or null denotes the queue manager to which
this object is connected.
- alternateUserId - if MQC.MQOO_ALTERNATE_USER_AUTHORITY
is specified in the openOptions parameter, this
parameter specifies the alternative user ID to be used to check the authorization
for the open. Otherwise this parameter can be blank or null.
- Returns
-
- MQProcess which has been successfully opened.
- Exceptions
-
- MQException - if the open fails.
accessQueue
public MQQueue accessQueue(String queueName, int openOptions)
throws MQException;
Establishes access to an WebSphere MQ queue on this queue manager using
default queue manager name and alternative user ID values.
- Parameters
-
- queueName - name of queue to open.
- openOptions - options which control the opening of the queue. See
accessQueue(String, int, String, String, String)
for more information.
- Returns
-
- MQQueue which has been successfully opened.
- Exceptions
-
- MQException - if the open fails.
accessQueue
public MQQueue accessQueue(String queueName, int openOptions,
String queueManagerName,
String dynamicQueueName,
String alternateUserId)
throws MQException;
Establishes access to a WebSphere MQ queue on this queue manager in order
to get or browse messages, put messages, inquire about the attributes of the
queue, or set the attributes of the queue.
If the queue named is a model queue, then a dynamic local queue is created.
The name of the created queue is held in the name field of the returned MQQueue object.
- Parameters
-
- queueName - name of queue to open.
- openOptions - options which control the opening of the queue. As inquire
and set options are automatically added to the options provided, there is
no need to specify these explicitly. The valid options are:
- MQC.MQOO_BROWSE
- MQC.MQOO_INPUT_AS_Q_DEF
- MQC.MQOO_INPUT_SHARED
- MQC.MQOO_INPUT_EXCLUSIVE
- MQC.MQOO_OUTPUT
- MQC.MQOO_SAVE_ALL_CONTEXT
- MQC.MQOO_PASS_IDENTITY_CONTEXT
- MQC.MQOO_PASS_ALL_CONTEXT
- MQC.MQOO_SET_IDENTITY_CONTEXT
- MQC.MQOO_SET_ALL_CONTEXT
- MQC.MQOO_ALTERNATE_USER_AUTHORITY
- MQC.MQOO_FAIL_IF_QUIESCING
If more than one option is required the values can be combined using
either the '+' or '|' operator. See WebSphere MQ Application
Programming Reference for a fuller description of these options.
- queueManagerName - name of the queue manager on which the queue is defined.
A name which is blank, or which is null, denotes the queue manager to which
this object is connected.
- dynamicQueueName - name of the dynamic queue to be created. This parameter
is ignored unless queueName specifies the name
of a model queue. If it does, this parameter specifies the name of the dynamic
queue to be created. A blank or null name is not valid if
queueName specifies the name of a model queue. If the last non-blank
character in the name is an asterisk (*), the queue manager replaces it with
a string of characters which guarantees that the name generated for the queue
is unique at the local queue manager. Asterisk is only valid in positions
1 to 33 of the dynamicQueueName parameter.
- alternateUserId - if MQC.MQOO_ALTERNATE_USER_AUTHORITY
is specified in the openOptions parameter this parameter specifies the alternate
user ID to be used to check the authorization for the open. If
MQC.MQOO_ALTERNATE_USER_AUTHORITY is not specified, this
parameter can be left blank (or null).
- Returns
-
- the MQQueue which has been successfully opened.
- Exceptions
-
- MQException - if the open fails.
backout
public void backout() throws MQException;
Indicates to the queue manager that all the message gets and puts that
have occurred since the last syncpoint are to be backed out. Messages sent
as part of a unit of work (with the MQC.MQPMO_SYNCPOINT
flag set in the options field of MQPutMessageOptions)
are deleted. Messages retrieved as part of a unit of work (with the
MQC.MQGMO_SYNCPOINT flag set in MQGetMessageOptions.options)
are reinstated on the queue.
- Exceptions
-
- MQException - if the call fails.
begin
public void begin() throws MQException;
Begins a new unit of work. This method is only supported by WebSphere MQ
in a bindings connection. It signals to the queue manager that a new unit
of work is to begin.
- Exceptions
-
- MQException - if the call fails
commit
public void commit() throws MQException;
Indicates to the queue manager that the application has reached a syncpoint.
All the message gets and puts that have occurred since the last syncpoint
are to be made permanent. Messages sent as part of a unit of work (with the
MQC.MQPMO_SYNCPOINT flag set in MQPutMessageOptions.options)
are made available to other applications. Messages retrieved as part of a
unit of work (with the MQC.MQGMO_SYNCPOINT flag set in
MQGetMessageOptions.options) are deleted.
- Exceptions
-
- MQException - if the call fails.
disconnect
public void disconnect() throws MQException;
Ends the connection to the queue manager. All open queues and processes
accessed through this queue manager are closed and become unusable. The only
way to reconnect is to create a new MQQueueManager object.
- Exceptions
-
- MQException - if the MQ disconnect call fails.
getCCDTURL
public URL getCCDTURL();
Returns the URL of the channel definition file, or null if it does not
exist. Java URLs support various protocols, which normally include file, HTTP,
FTP and LDAP. The URL class has several constructors,
one of which is: URL(String spec).
- Returns
-
- The URL of the channel definition file.
getCharacterSet
public int getCharacterSet() throws MQException;
Gets the CCSID (Coded Character Set Identifier) of the queue manager's
codeset. This defines the character set used by the queue manager for all
character string fields in the application programming interface.
- Returns
-
- Exceptions
-
- MQException - if you call this method after disconnecting from the queue
manager to indicate that the connection is no longer valid.
getCommandInputQueueName
public String getCommandInputQueueName() throws MQException;
Gets the name of the command input queue defined on the queue manager.
This is a queue to which applications can send commands, if authorized to
do so.
- Returns
-
- the name of the command input queue.
- Exceptions
-
- MQException - if you call this method after disconnecting from the queue
manager to indicate that the connection is no longer valid.
getCommandLevel
public int getCommandLevel() throws MQException;
Indicates the level of system control commands supported by the queue manager.
The set of system control commands corresponding to a particular command level
varies according to the platform on which the queue manager is running. See WebSphere MQ Application Programming Reference.
- Returns
-
- values between MQC.MQCMDL_LEVEL_1 and
MQC.MQCMDL_LEVEL_600.
- Exceptions
-
- MQException - if you call this method after disconnecting from the queue
manager to indicate that the connection is no longer valid.
getDistributionListCapable
public boolean getDistributionListCapable();
Indicates whether the queue manager supports distribution lists.
- Returns
-
- trueif distribution lists are supported.
getJDBCConnection
public Connection getJDBCConnection(XADataSource xads) throws MQException,
SQLException, Exception;
Returns a Connection object for use with the JTA-JDBC
support.
- Parameters
-
- xads - A database-specific implementation of the
XADataSource interface that defines the details of the database to
connect to. See the documentation for your database to determine how to create
an appropriate XADataSource object to pass into
this method.
- Returns
-
- A connection for use with the JTA-JDBC support.
- Exceptions
-
- MQException - if there is a WebSphere MQ failure.
- SQLException - if there are problems getting the
Connection object.
- Exception - thrown to avoid problems with the JVM verifier for customers
who are not using the JTA functionality. The actual exception thrown is
javax.transaction.xa.XAException, which requires
the jta.jar file to be added to the CLASSPATH for programs that did not previously
require it.
getJDBCConnection
public Connection getJDBCConnection(XADataSource xads, String userid,
String password)
throws MQException, SQLException, Exception;
Registers a database for coordination. Used to create a JDBC
Connection which is coordinated by the queue manager after a call
to begin.
- Parameters
-
- xads - database-specific implementation of the
XADataSource interface that defines the details of the database. See
the documentation for your database to determine how to create an appropriate
XADataSource object to pass into this method.
- userid - the user ID for connecting to the database.
- password - the password for connecting to the database.
- Returns
-
- connection for use with the JTA-JDBC support.
- Exceptions
-
- MQException - if there is a WebSphere MQ failure.
- SQLException - if there are problems getting the
Connection object.
- Exception - thrown to avoid problems with the JVM verifier for customers
who are not using the JTA functionality. The actual exception thrown is
javax.transaction.xa.XAException, which requires
the jta.jar file to be added to the CLASSPATH for programs that did not previously
require it.
getMaximumMessageLength
public int getMaximumMessageLength() throws MQException;
Gets the maximum length of a message that the queue manager can handle.
No queue can be defined with a maximum message length greater than this.
- Returns
-
- The maximum message length in bytes.
- Exceptions
-
- MQException - if you call this method after disconnecting from the queue
manager to indicate that the connection is no longer valid.
getMaximumPriority
public int getMaximumPriority() throws MQException;
Gets the maximum message priority supported by the queue manager. Priorities
range from zero (lowest) to this value.
- Returns
-
- the maximum message priority.
- Exceptions
-
- MQException - if you call this method after disconnecting from the queue
manager to indicate that the connection is no longer valid.
getProperties
public static Hashtable getProperties(Object key, MQChannelHeader header,
URL url) throws IOException,
MQException;
Reads properties concerning a channel in the channel definition table.
- Parameters
-
- key - the name of the channel.
- header - helps to find the channel information in the table.
- url - the URL of the channel definition table.
- Returns
-
- the relevant properties in a Hashtable.
- Exceptions
-
- IOException - raised if there are connection problems.
- MQException - raised if there are WebSphere MQ problems.
getSyncpointAvailability
public int getSyncpointAvailability() throws MQException;
Indicates whether the queue manager supports units of work and syncpointing
with the MQQueue.get() and MQQueue.put()
methods.
- Returns
-
- MQC.MQSP_AVAILABLE if syncpointing is available,
or MQC.MQSP_NOT_AVAILABLE if not.
- Exceptions
-
- MQException - if you call this method after disconnecting from the queue
manager to indicate that the connection is no longer valid.
isConnected
public boolean isConnected();
Indicates whether this object is currently connected to a WebSphere MQ
queue manager. Use disconnect() to disconnect from a
queue manager.
- Returns
-
put
public void put(String qName, MQMessage msg) throws MQException;
Puts a single message on to a (possibly unopened) queue. If a send exit
has been specified it processes the message before it is sent.
- Parameters
-
- qName - the name of the queue to which the message is put.
- msg - the message to be sent.
- Exceptions
-
- MQException - if the WebSphere MQ put call fails.
put
public void put(String qName, MQMessage msg, MQPutMessageOptions pmo)
throws MQException;
Puts a single message on to a (possibly unopened) queue. If a send exit
has been specified it processes the message before it is sent.
- Parameters
-
- qName - the name of the queue to which the message is put.
- msg - the message to be sent.
- pmo - the put message options to use.
- Exceptions
-
- MQException - if the WebSphere MQ put call fails.
put
public void put(String qName, String qmName, MQMessage msg)
throws MQException;
Puts a single message on to a (possibly unopened) queue. If a send exit
has been specified it processes the message before it is sent.
- Parameters
-
- qName - the name of the queue to which the message is put.
- qmName - the name of the queue manager which holds the queue.
- msg - the message to be sent.
- Exceptions
-
- MQException - if the WebSphere MQ put call fails.
put
public void put(String qName, String qmName, MQMessage msg,
MQPutMessageOptions pmo) throws MQException;
Puts a single message on to a (possibly unopened) queue. If a send exit
has been specified it processes the message before it is sent.
- Parameters
-
- qName - the name of the queue to which the message is put.
- qmName - the name of the queue manager which holds the queue.
- msg - the message to be sent.
- pmo - the put message options to use.
- Exceptions
-
- MQException - if the WebSphere MQ put call fails.
put
public void put(String qName, String qmName, MQMessage msg,
MQPutMessageOptions pmo, String altUserId)
throws MQException;
Puts a single message onto a (possibly unopened) queue. If a send exit
has been specified, it processes the message before it is sent. See the description
of MQPUT1 in WebSphere MQ Application Programming Reference for more information.
- Parameters
-
- qName - the name of the queue to which the message is put.
- qmName - the name of the queue manager which holds the queue.
- msg - the message to be sent.
- pmo - the put message options to use.
- altUserId - alternative user ID to use when putting the message.
- Exceptions
-
- MQException - if the WebSphere MQ put call fails.