MQQueueManager

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

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

Note:: The behavior of some of the options available in this class depends on the environment in which they are used. These elements are marked with a *. See Chapter 8, Environment-dependent behavior for details.

Variables

isConnected: public boolean isConnected
True if the connection to the queue manager is still open.

Constructors

MQQueueManager

public MQQueueManager(String queueManagerName)

Throws MQException.

Create a connection to the named queue manager.

Note:: 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.

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, 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: 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,
          )

Parameters

litems: The items to be included in the distribution list.
openOptions: Options that control the opening of the distribution list.

See accessDistributionList for details of the 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 accessProcess for details of the 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, then a dynamic local queue is created. The name of the created queue can be determined by inspecting 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 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 entirely blank, or which is 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

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

See also MQQueueManager.accessQueue.

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 and it signals to the queue manager that a new unit of work is starting.

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 of 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 hence 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 so as 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 would require the jta.jar file to be added to the classpath for programs which didn't previously require it.

Parameters

dataSource: A database-specific implementation of the XADataSource interface which 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 userid 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.

Parameters

xads: A database-specific implementation of the XADataSource interface which 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 a 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 then 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 the message should be placed.
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.

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