MQQueue

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

MQQueue provides inquire, set, put, and get operations for WebSphere MQ queues. The inquire and set capabilities are inherited from MQ.MQManagedObject.

See also MQQueueManager.accessQueue.

Constructors

MQQueue

public MQQueue(MQQueueManager qMgr, String queueName, int openOptions,
               String queueManagerName, String dynamicQueueName,
               String alternateUserId ) 
               throws MQException

Access a queue on the queue manager qMgr.

See MQQueueManager.accessQueue for details of the remaining parameters.

Methods

close

public synchronized void close()

Throws MQException.

Override of MQManagedObject.close.

get

public synchronized void get(MQMessage message,
                             MQGetMessageOptions getMessageOptions,
                             int MaxMsgSize)

Throws MQException.

Retrieves a message from the queue, up to a maximum specified message size.

This method takes an MQMessage object as a parameter. It uses some of the fields in the object as input parameters - in particular the messageId and correlationId, so it is important to ensure that these are set as required. (See Message.)

If the get fails, the MQMessage object is unchanged. If it succeeds the message descriptor (member variables) and message data portions of the MQMessage are completely replaced with the message descriptor and message data from the incoming message.

Note that all calls to WebSphere MQ from a given MQQueueManager are synchronous. Therefore, if you perform a get with wait, all other threads using the same MQQueueManager are blocked from making further WebSphere MQ calls until the get completes. If you need multiple threads to access WebSphere MQ simultaneously, each thread must create its own MQQueueManager object.

Parameters

message

An input/output parameter containing the message descriptor information and the returned message data.

getMessageOptions

Options controlling the action of the get. (See MQGetMessageOptions.)

Using option MQC.MQGMO_CONVERT may result in an exception with reason code MQException.MQRC_CONVERTED_STRING_TOO_BIG when converting from single byte character codes to double byte codes. In this case, the message will be copied into the buffer but will remain encoded using its original character set.

MaxMsgSize

The largest message this call will be able to receive. If the message on the queue is larger than this size, one of two things can occur:

1. If the MQC.MQGMO_ACCEPT_TRUNCATED_MSG flag is set in the options member variable of the MQGetMessageOptions object, the message is filled with as much of the message data as will fit in the specified buffer size, and an exception is thrown with completion code MQException.MQCC_WARNING and reason code MQException.MQRC_TRUNCATED_MSG_ACCEPTED.
2. If the MQC.MQGMO_ACCEPT_TRUNCATED_MSG flag is not set, the message is left on the queue and an MQException is raised with completion code MQException.MQCC_WARNING and reason code MQException.MQRC_TRUNCATED_MSG_FAILED.

Throws MQException if the get fails.

get

public synchronized void get(MQMessage message,
                             MQGetMessageOptions getMessageOptions)

Throws MQException.

Retrieves a message from the queue, regardless of the size of the message. For large messages, the get method may have to issue two calls to WebSphere MQ on your behalf, one to establish the required buffer size and one to get the message data itself.

This method takes an MQMessage object as a parameter. It uses some of the fields in the object as input parameters - in particular the messageId and correlationId, so it is important to ensure that these are set as required. (See Message.)

If the get fails, the MQMessage object is unchanged. If it succeeds, the message descriptor (member variables) and message data portions of the MQMessage are completely replaced with the message descriptor and message data from the incoming message.

Note that all calls to WebSphere MQ from a given MQQueueManager are synchronous. Therefore, if you perform a get with wait, all other threads using the same MQQueueManager are blocked from making further WebSphere MQ calls until the get completes. If you need multiple threads to access WebSphere MQ simultaneously, each thread must create its own MQQueueManager object.

Parameters

message

An input/output parameter containing the message descriptor information and the returned message data.

getMessageOptions

Options controlling the action of the get. (See MQGetMessageOptions for details.)

Throws MQException if the get fails.

get

public synchronized void get(MQMessage message)

This is a simplified version of the get method previously described.

Parameters

MQMessage

An input/output parameter containing the message descriptor information and the returned message data.

This method uses a default instance of MQGetMessageOptions to do the get. The message option used is MQGMO_NOWAIT.

getCreationDateTime

public GregorianCalendar getCreationDateTime()

Throws MQException.

The date and time that this queue was created.

getQueueType

public int getQueueType()

Throws MQException

Returns

The type of this queue with one of the following values:

• MQC.MQQT_ALIAS
• MQC.MQQT_LOCAL
• MQC.MQQT_REMOTE
• MQC.MQQT_CLUSTER

getCurrentDepth

public int getCurrentDepth()

Throws MQException.

Get the number of messages currently on the queue. This value is incremented during a put call, and during backout of a get call. It is decremented during a non-browse get and during backout of a put call.

getDefinitionType

public int getDefinitionType()

Throws MQException.

Indicates how the queue was defined.

Returns

One of the following:

• MQC.MQQDT_PREDEFINED
• MQC.MQQDT_PERMANENT_DYNAMIC
• MQC.MQQDT_TEMPORARY_DYNAMIC

getInhibitGet

public int getInhibitGet()

Throws MQException.

Indicates whether or not get operations are allowed for this queue.

Returns

The possible values are:

• MQC.MQQA_GET_INHIBITED
• MQC.MQQA_GET_ALLOWED

getInhibitPut

public int getInhibitPut()

Throws MQException.

Indicates whether or not put operations are allowed for this queue.

Returns

One of the following:

• MQC.MQQA_PUT_INHIBITED
• MQC.MQQA_PUT_ALLOWED

getMaximumDepth

public int getMaximumDepth()

Throws MQException.

The maximum number of messages that can exist on the queue at any one time. An attempt to put a message to a queue that already contains this many messages fails with reason code MQException.MQRC_Q_FULL.

getMaximumMessageLength

public int getMaximumMessageLength()

Throws MQException.

This is the maximum length of the application data that can exist in each message on this queue. An attempt to put a message larger than this value fails with reason code MQException.MQRC_MSG_TOO_BIG_FOR_Q.

getOpenInputCount

public int getOpenInputCount()

Throws MQException.

The number of handles that are currently valid for removing messages from the queue. This is the total number of such handles known to the local queue manager, not just those created by the WebSphere MQ classes for Java (using accessQueue).

getOpenOutputCount

public int getOpenOutputCount()

Throws MQException.

The number of handles that are currently valid for adding messages to the queue. This is the total number of such handles known to the local queue manager, not just those created by the WebSphere MQ classes for Java (using accessQueue).

getShareability

public int getShareability()

Throws MQException.

Indicates whether the queue can be opened for input multiple times.

Returns

One of the following:

• MQC.MQQA_SHAREABLE
• MQC.MQQA_NOT_SHAREABLE

getTriggerControl

public int getTriggerControl()

Throws MQException.

Indicates whether or not trigger messages are written to an initiation queue, in order to cause an application to be started to service the queue.

Returns

The possible values are:

• MQC.MQTC_OFF
• MQC.MQTC_ON

getTriggerData

public String getTriggerData()

Throws MQException.

The free-format data that the queue manager inserts into the trigger message when a message arriving on this queue causes a trigger message to be written to the initiation queue.

getTriggerDepth

public int getTriggerDepth()

Throws MQException.

The number of messages that have to be on the queue before a trigger message is written when trigger type is set to MQC.MQTT_DEPTH.

getTriggerMessagePriority

public int getTriggerMessagePriority()

Throws MQException.

This is the message priority below which messages do not contribute to the generation of trigger messages (that is, the queue manager ignores these messages when deciding whether a trigger should be generated). A value of zero causes all messages to contribute to the generation of trigger messages.

getTriggerType

public int getTriggerType()

Throws MQException.

The conditions under which trigger messages are written as a result of messages arriving on this queue.

Returns

The possible values are:

• MQC.MQTT_NONE
• MQC.MQTT_FIRST
• MQC.MQTT_EVERY
• MQC.MQTT_DEPTH

put

public synchronized void put(MQMessage message,
                             MQPutMessageOptions putMessageOptions)

Throws MQException.

Places a message onto the queue.

Note:

For simplicity and performance, if you want to put just a single message to a queue, use the put() method on your MQQueueManager object. For this you do not need to have an MQQueue object. See MQQueueManager.put.

This method takes an MQMessage object as a parameter. The message descriptor properties of this object may be altered as a result of this method. The values they have immediately after the completion of this method are the values that were put onto the WebSphere MQ queue.

Modifications to the MQMessage object after the put has completed do not affect the actual message on the WebSphere MQ queue.

A put updates the messageId and correlationId. This must be considered when making further calls to put/get using the same MQMessage object. Also, calling put does not clear the message data, so:

msg.writeString("a");
q.put(msg,pmo);
msg.writeString("b");
q.put(msg,pmo);

puts two messages. The first contains "a" and the second "ab".

Parameters

message

Message Buffer containing the Message Descriptor data and message to be sent.

putMessageOptions

Options controlling the action of the put. (See MQPutMessageOptions)

Throws MQException if the put fails.

put

public synchronized void put(MQMessage message)

This is a simplified version of the put method previously described.

Parameters

MQMessage

Message Buffer containing the Message Descriptor data and message to be sent.

This method uses a default instance of MQPutMessageOptions to do the put.

setInhibitGet

public void setInhibitGet(int inhibit)

Throws MQException.

Controls whether or not get operations are allowed for this queue. The permissible values are:

• MQC.MQQA_GET_INHIBITED
• MQC.MQQA_GET_ALLOWED

setInhibitPut

public void setInhibitPut(int inhibit)

Throws MQException.

Controls whether or not put operations are allowed for this queue. The permissible values are:

• MQC.MQQA_PUT_INHIBITED
• MQC.MQQA_PUT_ALLOWED

setTriggerControl

public void setTriggerControl(int trigger)

Throws MQException.

Controls whether or not trigger messages are written to an initiation queue, in order to cause an application to be started to service the queue. The permissible values are:

• MQC.MQTC_OFF
• MQC.MQTC_ON

setTriggerData

public void setTriggerData(String data)

Throws MQException.

Sets the free-format data that the queue manager inserts into the trigger message when a message arriving on this queue causes a trigger message to be written to the initiation queue. The maximum permissible length of the string is given by MQC.MQ_TRIGGER_DATA_LENGTH.

setTriggerDepth

public void setTriggerDepth(int depth)

Throws MQException.

Sets the number of messages that have to be on the queue before a trigger message is written when trigger type is set to MQC.MQTT_DEPTH.

setTriggerMessagePriority

public void setTriggerMessagePriority(int priority)

Throws MQException.

Sets the message priority below which messages do not contribute to the generation of trigger messages (that is, the queue manager ignores these messages when deciding whether a trigger should be generated). A value of zero causes all messages to contribute to the generation of trigger messages.

setTriggerType

public void setTriggerType(int type)

Throws MQException.

Sets the conditions under which trigger messages are written as a result of messages arriving on this queue. The possible values are:

• MQC.MQTT_NONE
• MQC.MQTT_FIRST
• MQC.MQTT_EVERY
• MQC.MQTT_DEPTH