MQQueueManager

 



java.lang.Object
   |
   *- com.ibm.mq.MQManagedObject
           |
           *- com.ibm.mq.MQQueueManager

public class MQQueueManager
extends MQManagedObject. (See topic "MQManagedObject".)

The behavior of some of the options available in this class depends on the environment in which they are used.

 

Variables

isConnected
public boolean isConnected

True if the connection to the queue manager is still open.

 

Constructors

MQQueueManager
public MQQueueManager(String queueManagerName)

Throws MQException.

Creates a connection to the named queue manager.

When using WebSphere MQ classes for Java, the hostname, 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 machine with hostname fred.mq.com. 

MQEnvironment.hostname = "fred.mq.com";  // host to connect to
MQEnvironment.port     = 1414;           // port to connect to.
                                         // If I don't set this,
                                         // it defaults to 1414
                                         // (the default WebSphere MQ port)
MQEnvironment.channel  = "channel.name"; // the CASE-SENSITIVE
                                         //  name of the
                                         // SVR CONN channel on
                                         // the queue manager
MQQueueManager qMgr    = new MQQueueManager("MYQM");

If the queue manager name is left blank (null or ""), a connection is made to the default queue manager.

See also MQEnvironment.

MQQueueManager
public MQQueueManager(String queueManagerName, 
                      MQConnectionManager cxManager)

Throws MQException.

Connects to the specified Queue Manager, using the properties in MQEnvironment. The specified MQConnectionManager manages the connection.

MQQueueManager
public MQQueueManager(String queueManagerName, 
                      ConnectionManager cxManager)

Throws MQException.

Connects to the specified Queue Manager, using the properties in MQEnvironment. The specified ConnectionManager manages the connection.

This constructor requires a JVM at at least Java 2 v1.3, with at least JAAS 1.0 installed.

MQQueueManager
public MQQueueManager(String queueManagerName, 
                      int options)

Throws MQException.

This version of the constructor is intended for use only in bindings mode. It uses the extended connection API (MQCONNX) to connect to the queue manager. The options parameter allows you to choose fast or normal bindings. Possible values are:

  • MQC.MQCNO_FASTPATH_BINDING for fast bindings *.

  • MQC.MQCNO_STANDARD_BINDING for normal bindings.

MQQueueManager
public MQQueueManager(String queueManagerName, 
                      int options, 
                      MQConnectionManager cxManager)

Throws MQException.

Performs an MQCONNX, passing the supplied options. The specified MQConnectionManager manages the connection.

MQQueueManager
public MQQueueManager(String queueManagerName, 
                      int options, 
                      ConnectionManager cxManager)

Throws MQException.

Performs an MQCONNX, passing the supplied options. The specified ConnectionManager manages the connection.

This constructor requires a JVM at at least Java 2 v1.3, with at least JAAS 1.0 installed.

MQQueueManager
public MQQueueManager(String queueManagerName,
                      java.util.Hashtable properties)

The properties parameter takes a series of key/value pairs that describe the WebSphere MQ environment for this particular queue manager. These properties, where specified, override the values set by the MQEnvironment class, and allow the individual properties to be set on a queue manager by queue manager basis. See MQEnvironment.properties.

MQQueueManager
public MQQueueManager(String queueManagerName, 
                      Hashtable properties, 
                      MQConnectionManager cxManager)

Throws MQException.

This constructor connects to the named Queue Manager, using the supplied hash table of properties to override those in MQEnvironment. The specified MQConnectionManager manages the connection.

MQQueueManager
public MQQueueManager(String queueManagerName, 
                      Hashtable properties, 
                      ConnectionManager cxManager)

Throws MQException.

Connects to the named Queue Manager, using the supplied hash table of properties to override those in MQEnvironment. The specified ConnectionManager manages the connection.

This constructor requires a JVM at at least Java 2 v1.3, with at least JAAS 1.0 installed.

 

Methods

accessDistributionList
public synchronized MQDistributionList accessDistributionList
          (MQDistributionListItem[] litems, int openOptions,
           String alternateUserId)

Throws MQException.

Parameters

litems
The items to be included in the distribution list.

openOptions
Options that control the opening of the distribution list.

alternateUserId
If MQOO_ALTERNATE_USER_AUTHORITY is specified in the openOptions parameter, specifies the alternate user identifier that is used to check the authorization for the open. If MQOO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

Returns
A newly-created MQDistributionList, which is open and ready for put operations.

Throws MQException if the open fails.

See also MQQueueManager.accessQueue.

accessDistributionList
This is a simplified version of the AccessDistributionList method previously described. 
public synchronized MQDistributionList accessDistributionList
          (MQDistributionListItem[] litems,
           int openOptions)

Throws MQException.

Parameters

litems
The items to be included in the distribution list.

openOptions
Options that control the opening of the distribution list.

See the full description of accessDistributionList above for details of the other parameters.

alternateUserId is set to "".

accessProcess
public synchronized MQProcess accessProcess
                        (String processName,
                       int openOptions,
                       String queueManagerName,
                       String alternateUserId)

Throws MQException.

Establishes access to a WebSphere MQ process on this queue manager to inquire about the process attributes.

Parameters

processName
Name of process to open.

openOptions
Options that control the opening of the process. Inquire is automatically added to the options specified, so there is no need to specify it explicitly.

Valid options are:

MQC.MQOO_ALTERNATE_USER_AUTHORITY
Validate with the specified user ID

MQC.MQOO_FAIL_IF_QUIESCING
Fail if the queue manager is quiescing

If more than one option is required, the values can be added together or combined using the bitwise OR operator. See the WebSphere MQ Application Programming Reference for a fuller description of these options.

queueManagerName
Name of the queue manager on which the process is defined. Applications should leave this parameter blank or null.

alternateUserId
If MQOO_ALTERNATE_USER_AUTHORITY is specified in the openOptions parameter, this parameter specifies the alternate user identifier that is used to check the authorization for the open. If MQOO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

accessProcess
This is a simplified version of the AccessProcess method previously described. 
public synchronized MQProcess accessProcess
                        (String processName,
                         int openOptions)

Parameters

processName
The name of the process to open.

openOptions
Options that control the opening of the process.

See the full description of accessProcess above for details of the other options.

queueManagerName and alternateUserId are set to "".

accessQueue 
public synchronized 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 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, a dynamic local queue is created. The name of the created queue can be determined from the name attribute of the returned MQQueue object.

Parameters

queueName
Name of queue to open.

openOptions
Options that control the opening of the queue. Valid options are:

MQC.MQOO_ALTERNATE_USER_AUTHORITY
Validate with the specified user identifier.

MQC.MQOO_BIND_AS_QDEF
Use default binding for queue.

MQC.MQOO_BIND_NOT_FIXED
Do not bind to a specific destination.

MQC.MQOO_BIND_ON_OPEN
Bind handle to destination when queue is opened.

MQC.MQOO_BROWSE
Open to browse message.

MQC.MQOO_FAIL_IF_QUIESCING
Fail if the queue manager is quiescing.

MQC.MQOO_INPUT_AS_Q_DEF
Open to get messages using queue-defined default.

MQC.MQOO_INPUT_SHARED
Open to get messages with shared access.

MQC.MQOO_INPUT_EXCLUSIVE
Open to get messages with exclusive access.

MQC.MQOO_INQUIRE
Open for inquiry - required if you wish to query properties.

MQC.MQOO_OUTPUT
Open to put messages.

MQC.MQOO_PASS_ALL_CONTEXT
Allow all context to be passed.

MQC.MQOO_PASS_IDENTITY_CONTEXT
Allow identity context to be passed.

MQC.MQOO_SAVE_ALL_CONTEXT
Save context when message retrieved*.

MQC.MQOO_SET
Open to set attributes.

MQC.MQOO_SET_ALL_CONTEXT
Allows all context to be set.

MQC.MQOO_SET_IDENTITY_CONTEXT
Allows identity context to be set.

If more than one option is required, the values can be added together or combined using the bitwise OR operator. See the 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 that is entirely blank or null denotes the queue manager to which this MQQueueManager object is connected.

dynamicQueueName
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 the asterisk with a string of characters that guarantees that the name generated for the queue is unique on this queue manager.

alternateUserId
If MQOO_ALTERNATE_USER_AUTHORITY is specified in the openOptions parameter, this parameter specifies the alternate user identifier that is used to check the authorization for the open. If MQOO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

Returns
MQQueue that has been successfully opened.

Throws MQException if the open fails.

accessQueue
public synchronized MQQueue accessQueue
                         (String queueName,
                          int openOptions)

Throws MQException if you call this method after disconnecting from the queue manager.

Parameters

queueName
Name of queue to open

openOptions
Options that control the opening of the queue

See the description of MQQueueManager.accessQueue for details of the parameters.

For this version of the method, queueManagerName, dynamicQueueName, and alternateUserId are set to "".

Returns
MQProcess that has been successfully opened.

Throws MQException if the open fails.

backout
public synchronized void backout()

Throws MQException.

Calling this method 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 put 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 the options field of MQGetMessageOptions) are reinstated on the queue.

See also the description of the commit method.

begin* (bindings connection only)
public synchronized void begin()

Throws MQException.

This method is supported only by the WebSphere MQ classes for Java in bindings mode. It signals to the queue manager that a new unit of work is starting. For a complete description of using this method, see JTA/JDBC coordination using WebSphere MQ base Java.

Do not use this method for applications that use local one-phase transactions.

commit
public synchronized void commit()

Throws MQException.

Calling this method indicates to the queue manager that the application has reached a syncpoint, and that all the message gets and puts that have occurred since the last syncpoint are to be made permanent. Messages put as part of a unit of work (with the MQC.MQPMO_SYNCPOINT flag set in the options field of MQPutMessageOptions) are made available to other applications. Messages retrieved as part of a unit of work (with the MQC.MQGMO_SYNCPOINT flag set in the options field of MQGetMessageOptions) are deleted.

See also the description of the backout method.

disconnect
public synchronized void disconnect()

Throws MQException.

Terminates the connection to the queue manager. All open queues and processes accessed by this queue manager are closed, and become unusable. When you have disconnected from a queue manager, the only way to reconnect is to create a new MQQueueManager object.

Normally, any work performed as part of a unit of work is committed. However, if this connection is managed by a ConnectionManager, rather than an MQConnectionManager, the unit of work might be rolled back.

getCharacterSet
public int getCharacterSet()

Throws MQException.

Returns 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.

Throws MQException if you call this method after disconnecting from the queue manager.

getCommandInputQueueName
public String getCommandInputQueueName()

Throws MQException.

Returns 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.

Throws MQException if you call this method after disconnecting from the queue manager.

getCommandLevel
public int getCommandLevel()

Throws MQException.

Indicates the level of system control commands supported by the queue manager. The set of system control commands that correspond to a particular command level varies according to the architecture of the platform on which the queue manager is running. See the WebSphere MQ documentation for your platform for further details.

Throws MQException if you call this method after disconnecting from the queue manager.

Returns
One of the MQC.MQCMDL_LEVEL_xxx constants

getDistributionListCapable
public boolean getDistributionListCapable()

Indicates whether the queue manager supports distribution lists.

getJDBCConnection
  public java.sql.Connection getJDBCConnection(XADataSource dataSource,
                                          String userid, String password)
    throws MQException, SQLException, Exception

Returns a Connection object for use with the JTA-JDBC support.

This method declares Exception in its throws clause 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.

Parameters

dataSource
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 getJDBCConnection.

userid
The user ID to use for this connection to the database. This is passed to the underlying XADataSource.getXAConnection method.

password
The password to use for this connection to the database. This is passed to the underlying XADataSource.getXAConnection method.

getJDBCConnection
  public java.sql.Connection getJDBCConnection javax.sql.XADataSource(xads)
    throws MQException, SQLException, Exception

Returns a Connection object for use with the JTA-JDBC support.

This method declares Exception in its throws clause 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.

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 getJDBCConnection.

getMaximumMessageLength
public int getMaximumMessageLength()

Throws MQException.

Returns the maximum length of a message (in bytes) that can be handled by the queue manager. No queue can be defined with a maximum message length greater than this.

Throws MQException if you call this method after disconnecting from the queue manager.

getMaximumPriority
public int getMaximumPriority()

Throws MQException.

Returns the maximum message priority supported by the queue manager. Priorities range from zero (lowest) to this value.

Throws MQException if you call this method after disconnecting from the queue manager.

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.

  • MQC.MQSP_NOT_AVAILABLE if syncpointing is not available.

Throws MQException if you call this method after disconnecting from the queue manager.

isConnected
public boolean isConnected()

Returns the value of the isConnected variable.

put
public synchronized void put(String qName,
                            String qmName,
                            MQMessage msg,
                            MQPutMessageOptions pmo,
                            String altUserId)

Throws MQException.

Places a single message onto a queue without having to create an MQQueue object first.

The qName (queue name) and qmName (queue manager name) parameters identify where the message is placed. If the queue is a model queue, an MQException is thrown.

In other respects, this method behaves like the put method on the MQQueue object. It is an implementation of the MQPUT1 MQI call. See MQQueue.put.

Parameters

qName
The name of the queue onto which to place the message.

qmName
The name of the queue manager on which the queue is defined.

msg
The message to send.

pmo
Options controlling the actions of the put. See MQPutMessageOptions for more details.

altUserid
Specifies an alternative user identifier used to check authorization when placing the message on a queue. If you do not specify MQPMO_ALTERNATE_USER, this parameter is ignored.

put
public synchronized void put(String qName,
                            String qmName,
                            MQMessage msg,
                            MQPutMessageOptions pmo)

Throws MQException.

Places a single message onto a queue without having to create an MQQueue object first.

This version of the method allows you to omit the altUserid parameter. See the fully-specified method (MQQueueManager.put) for details of the parameters.

put
public synchronized void put(String qName,
                            String qmName,
                            MQMessage msg)

Throws MQException.

Places a single message onto a queue without having to create an MQQueue object first.

This version of the method allows you to omit the put message options (pmo) and altUserid parameters. See the fully-specified method (MQQueueManager.put) for details of the parameters.

put
public synchronized void put(String qName,
                            MQMessage msg,
                            MQPutMessageOptions pmo)

Throws MQException.

Places a single message onto a queue without having to create an MQQueue object first.

This version of the method allows you to omit the qmName and altUserid parameters. See the fully-specified method (MQQueueManager.put) for details of the parameters.

put
 public synchronized void put(String qName,
                            MQMessage msg)

Throws MQException.

Places a single message onto a queue without having to create an MQQueue object first.

This version of the method allows you to omit the qmName, put message options (pmo), and altUserid parameters. See the fully-specified method (MQQueueManager.put) for details of the parameters.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.