com.ibm.mq
Class MQQueue

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

public class MQQueue
extends MQManagedObject

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

Use MQQueueManager.accessQueue() to gain access to an MQQueue object.


Field Summary
 
Fields inherited from class com.ibm.mq.MQManagedObject
alternateUserId, closeOptions, connectionReference, isOpen, name, openOptions
 
Constructor Summary
MQQueue(MQQueueManager qMgr, java.lang.String queueName, int openOptions, java.lang.String queueManagerName, java.lang.String dynamicQueueName, java.lang.String alternateUserId)
          Public constructor which allows users to create MQQueue subclasses.
 
Method Summary
 void close()
          Closes the object.
 void get(MQMessage message)
          Retrieves a message from the queue, using default get message options.
 void get(MQMessage message, MQGetMessageOptions getMessageOptions)
          Retrieves a message from the queue, regardless of the size of the message.
 void get(MQMessage message, MQGetMessageOptions getMessageOptions, int MaxMsgSize)
          Retrieves a message from the queue, up to a maximum specified message size.
 java.util.GregorianCalendar getCreationDateTime()
          Gets the date and time that this queue was created.
 int getCurrentDepth()
          Gets the number of messages currently on the queue.
 int getDefinitionType()
          Indicates how the queue was defined.
 int getInhibitGet()
          Indicates whether get operations are allowed for this queue.
 int getInhibitPut()
          Indicates whether put operations are allowed for this queue.
 int getMaximumDepth()
          Gets the maximum number of messages that can exist on the queue at any one time.
 int getMaximumMessageLength()
          Gets the maximum length of the application data of a message on this queue.
 int getOpenInputCount()
          Gets the number of currently valid handles for removing messages from the queue.
 int getOpenOutputCount()
          Gets the number of currently valid handles for adding messages to the queue.
 int getQueueType()
          Gets the type of this queue.
 int getShareability()
          Indicates whether the queue can be opened multiple times for input.
 int getTriggerControl()
          Indicates whether trigger messages are written to an initiation queue.
 java.lang.String getTriggerData()
          Gets the data for the trigger message that is written to the initiation queue.
 int getTriggerDepth()
          Gets the number of messages that have to be on the queue to generate a trigger message.
 int getTriggerMessagePriority()
          Gets the message priority below which messages do not cause trigger messages.
 int getTriggerType()
          Indicates the conditions under which trigger messages are written.
 void put(MQMessage message)
          Puts a message onto the queue using default put message options.
 void put(MQMessage message, MQPutMessageOptions putMessageOptions)
          Puts a message onto the queue.
 void setInhibitGet(int inhibit)
          Controls whether get operations are allowed for this queue.
 void setInhibitPut(int inhibit)
          Controls whether put operations are allowed for this queue.
 void setTriggerControl(int trigger)
          Controls whether trigger messages are written to an initiation queue.
 void setTriggerData(java.lang.String data)
          Sets the data for the trigger message that is written to the initiation queue.
 void setTriggerDepth(int depth)
          Sets the number of messages that have to be on the queue to generate a trigger message.
 void setTriggerMessagePriority(int priority)
          Sets the message priority below which messages do not cause trigger messages.
 void setTriggerType(int type)
          Sets the conditions under which trigger messages are written.
 
Methods inherited from class com.ibm.mq.MQManagedObject
getAttributeString, getDescription, inquire, isOpen, set, setAttributeString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MQQueue

public MQQueue(MQQueueManager qMgr,
               java.lang.String queueName,
               int openOptions,
               java.lang.String queueManagerName,
               java.lang.String dynamicQueueName,
               java.lang.String alternateUserId)
        throws MQException
Public constructor which allows users to create MQQueue subclasses.

Parameters:
qMgr - the object which represents the queue manager on which the queue resides.
queueName - name of the queue to open.
openOptions - options which control the opening of the queue. Valid options are:

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 queue is defined. If it is blank or null the queue manager to which this MQQueueManager object is connected is used.
dynamicQueueName - specifies the name of the dynamic queue to be created. It is ignored unless queueName specifies the name of a model queue, in which case it must not be blank or null. 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 - the alternative user ID used to check the authorization for the open if MQC.MQOO_ALTERNATE_USER_AUTHORITY is specified in openOptions.
Throws:
MQException - if the queue cannot be opened.
Method Detail

get

public void get(MQMessage message,
                MQGetMessageOptions getMessageOptions,
                int MaxMsgSize)
         throws MQException
Retrieves a message from the queue, up to a maximum specified message size.

If the call fails, the MQMessage object is unchanged. If it succeeds, the message descriptor fields and message data portions of the MQMessage are completely overwritten by the fields and data from the incoming message.

If you perform a get with wait, all other threads using the same MQQueueManager are blocked until the call completes. If you need multiple threads to access WebSphere MQ simultaneously, then each thread must create its own MQQueueManager object.

Parameters:
message - an input/output parameter that contains the message descriptor information and the returned message data. On input, some of the fields are used as input parameters, in particular messageId and correlationId. It is important to ensure that these are set as required.
getMessageOptions - options that control the action of the get. See MQGetMessageOptions.options for details.
MaxMsgSize - the largest message this call can receive. If the message on the queue is larger than this, the result depends on whether the MQC.MQGMO_ACCEPT_TRUNCATED_MSG flag has been selected in MQGetMessageOptions.options.

If the flag has been set, the message is filled with as much of the message data as will fit in the specified buffer size, and an MQException is thrown with completion code MQCC_WARNING and reason code MQRC_TRUNCATED_MSG_ACCEPTED.

If the flag has not been set, the message is left on the queue and an MQException is thrown with completion code MQCC_FAILED and reason code MQRC_TRUNCATED_MSG_FAILED.

Throws:
MQException - if the get fails or the received message is truncated.

get

public void get(MQMessage message,
                MQGetMessageOptions getMessageOptions)
         throws MQException
Retrieves a message from the queue, regardless of the size of the message. For large messages, this might require two calls to WeSphere MQ, One to establish the required buffer size and one to get the message data itself.

If the call fails, the MQMessage object is unchanged. If it succeeds, the message descriptor fields and message data portions of the MQMessage are completely overwritten by the fields and data from the incoming message.

Note that if you perform a get with wait, all other threads using the same MQQueueManager are blocked until the call completes. If you need multiple threads to access MQ simultaneously, then each thread must create its own MQQueueManager object.

Parameters:
message - an input/output parameter that contains the message descriptor information and the returned message data. On input some of the fields are used as input parameters, in particular messageId and correlationId. It is important to ensure that these are set as required.
getMessageOptions - options that control the action of the get. See MQGetMessageOptions.options for details.
Throws:
MQException - if the get fails.

get

public void get(MQMessage message)
         throws MQException
Retrieves a message from the queue, using default get message options. It uses an option setting of MQC.MQGMO_NO_WAIT.

Parameters:
message - an input/output parameter that contains the message descriptor information and the returned message data. On input, some of the fields are used as input parameters, in particular messageId and correlationId. It is important to ensure that these are set as required.
Throws:
MQException - if the get fails.
See Also:
get(MQMessage,MQGetMessageOptions)

put

public void put(MQMessage message,
                MQPutMessageOptions putMessageOptions)
         throws MQException
Puts a message onto the queue.

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

If you use the same MQMessage object to make further calls, then performing a put updates MQMessage.messageId and MQMessage.correlationId.

Note also that calling put() does not clear the message data. For example:


 msg.writeString("a");
 q.put(msg,pmo);
 msg.writeString("b");
 q.put(msg,pmo);
 
results in "ab" being put by the second call.

Parameters:
message - an object which contains the message descriptor data and the message data to be sent. On completion the values are set to those of the message which was put on the queue.
putMessageOptions - Options controlling the action of the put. See MQPutMessageOptions.options for details.
Throws:
MQException - if the put fails.

put

public void put(MQMessage message)
         throws MQException
Puts a message onto the queue using default put message options.

Parameters:
message - an object which contains the message descriptor data and the message data to be sent.
Throws:
MQException - if the put fails.
See Also:
put(MQMessage,MQPutMessageOptions)

close

public void close()
           throws MQException
Closes the object. No further operations on this object are permitted after it is closed. The behaviour of the close method can be altered by setting closeOptions.

Overrides:
close in class MQManagedObject
Throws:
MQException - if the WebSphere MQ call fails.

getCreationDateTime

public java.util.GregorianCalendar getCreationDateTime()
                                                throws MQException
Gets the date and time that this queue was created.

Returns:
the date and time.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getQueueType

public int getQueueType()
                 throws MQException
Gets the type of this queue.

Returns:
one of the following:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getCurrentDepth

public int getCurrentDepth()
                    throws MQException
Gets 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.

Returns:
the number of messages.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getDefinitionType

public int getDefinitionType()
                      throws MQException
Indicates how the queue was defined.

Returns:
one of the following:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getMaximumDepth

public int getMaximumDepth()
                    throws MQException
Gets 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.

Returns:
the maximum number of messages.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getMaximumMessageLength

public int getMaximumMessageLength()
                            throws MQException
Gets the maximum length of the application data of a 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.

Returns:
the maximum length.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getOpenInputCount

public int getOpenInputCount()
                      throws MQException
Gets the number of currently valid handles for removing messages from the queue.

Returns:
the total number of valid handles known to the local queue manager, not just those created by the WebSphere MQ Client for Java (using accessQueue()).
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getOpenOutputCount

public int getOpenOutputCount()
                       throws MQException
Gets the number of currently valid handles for adding messages to the queue.

Returns:
the total number of valid handles known to the local queue manager, not just those created by the WebSphere MQ Client for Java (using accessQueue()).
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getShareability

public int getShareability()
                    throws MQException
Indicates whether the queue can be opened multiple times for input.

Returns:
one of the following:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getInhibitPut

public int getInhibitPut()
                  throws MQException
Indicates whether put operations are allowed for this queue.

Returns:
one of the following:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

setInhibitPut

public void setInhibitPut(int inhibit)
                   throws MQException
Controls whether put operations are allowed for this queue.

Parameters:
inhibit - the permissible values are:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getInhibitGet

public int getInhibitGet()
                  throws MQException
Indicates whether get operations are allowed for this queue.

Returns:
one of the following:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

setInhibitGet

public void setInhibitGet(int inhibit)
                   throws MQException
Controls whether get operations are allowed for this queue.

Parameters:
inhibit - the permissible values are:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getTriggerControl

public int getTriggerControl()
                      throws MQException
Indicates whether trigger messages are written to an initiation queue. This starts an application to service the queue.

Returns:
the possible values are:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

setTriggerControl

public void setTriggerControl(int trigger)
                       throws MQException
Controls whether trigger messages are written to an initiation queue. This starts an application to service the queue.

Parameters:
trigger - the permissible values are:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getTriggerData

public java.lang.String getTriggerData()
                                throws MQException
Gets the data for the trigger message that is written to the initiation queue. The trigger message is written to the initiation queue when a message arrives on this one.

Returns:
the data in free format.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

setTriggerData

public void setTriggerData(java.lang.String data)
                    throws MQException
Sets the data for the trigger message that is written to the initiation queue. The trigger message is written to the initiation queue when a message arrives on this one.

Parameters:
data - sets the data in free-format. The maximum permissible length of the string is given by MQC.MQ_TRIGGER_DATA_LENGTH.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getTriggerDepth

public int getTriggerDepth()
                    throws MQException
Gets the number of messages that have to be on the queue to generate a trigger message. This applies when the trigger type is MQC.MQTT_DEPTH.

Returns:
the number of messages.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

setTriggerDepth

public void setTriggerDepth(int depth)
                     throws MQException
Sets the number of messages that have to be on the queue to generate a trigger message. This applies when trigger type is MQC.MQTT_DEPTH.

Parameters:
depth - the number of messages.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getTriggerMessagePriority

public int getTriggerMessagePriority()
                              throws MQException
Gets the message priority below which messages do not cause trigger messages. That is, the queue manager ignores these messages when deciding whether to generate a trigger.

Returns:
the message priority. 0 means that all messages contribute to the generation of trigger messages.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

setTriggerMessagePriority

public void setTriggerMessagePriority(int priority)
                               throws MQException
Sets the message priority below which messages do not cause trigger messages. That is, the queue manager ignores these messages when deciding whether to generate a trigger.

Parameters:
priority - the message priority. 0 means that all messages contribute to the generation of trigger messages.
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

getTriggerType

public int getTriggerType()
                   throws MQException
Indicates the conditions under which trigger messages are written. Trigger messages are written as a result of messages arriving on this queue.

Returns:
the possible values are:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

setTriggerType

public void setTriggerType(int type)
                    throws MQException
Sets the conditions under which trigger messages are written. Trigger messages are written as a result of messages arriving on this queue.

Parameters:
type - the possible values are:
Throws:
MQException - if you call this method after you have closed the queue, to indicate that the queue is no longer accessible.

(c) Copyright IBM Corp. 2005. All Rights Reserved.