MQTopic.NET class
Use MQTopic to publish or subscribe messages on a topic, or to query or set attributes of a topic. Create an MQTopic object for publishing or subscribing by using a constructor or the MQQueueManager.AccessTopic method.
Class
System.Object
|
└─ IBM.WMQ.MQBase
|
└─ IBM.WMQ.MQBaseObject
|
└─ IBM.WMQ.MQManagedObject
|
└─ IBM.WMQ.MQDestination
|
└─ IBM.WMQ.MQTopic
public class IBM.WMQ.MQTopic extends IBM.WMQ.MQDestination;
Properties
Test for MQException being thrown when getting properties.
public Boolean IsDurable {get;}
- Read only property that returns
True
if the subscription is durable orFalse
otherwise. If the topic was opened for publication, the property is ignored and would always returnFalse
. public Boolean IsManaged {get;};
- Read only property that returns
True
if the subscription is managed by the queue manager, orFalse
otherwise. If the topic was opened for publication, the property is ignored and would always return False. public Boolean IsSubscribed {get;};
- Read only property that returns
True
if the topic was opened for subscription andFalse
if the topic was opened for publication. public MQSubscription SubscriptionReference {get;};
- Read only property that returns the MQSubscription object associated with a topic object opened for subscription. The reference is available if you want to modify the close options or start any of the objects methods.
public MQDestination UnmanagedDestinationReference {get;};
- Read only property that returns the MQQueue associated with an unmanaged subscription. It is the destination specified when the topic object was created. The property returns null for any topic objects opened for publication or with a managed subscription.
Methods
public void Put(MQMessage message);
public void Put(MQMessage message, MQPutMessageOptions putMessageOptions);
- Throws MQException.
Publishes a message to the topic.
Modifications to the MQMessage object after the Put call has been accomplished do not affect the actual message on the IBM MQ queue or publication topic.
Put updates the MessageId and CorrelationId properties of the MQMessage object and does not clear message data. Further Put or Get calls refer to the updated information in the MQMessage object. For example, in the following code snippet, the first message containsa
and the secondab
.msg.WriteString("a"); q.Put(msg,pmo); msg.WriteString("b"); q.Put(msg,pmo);
message
- An MQMessage object containing the message descriptor data, and message to be sent. The message descriptor can be altered as a consequence of this method. The values in the message descriptor immediately after the completion of this method are the values that were put to the queue or published to the topic.
putMessageOptions
- Options controlling the action of the put.
Note: For simplicity and performance, if you want to put a single message to a queue, use MQQueueManager.Put object. You should have an MQQueue object for this. -
public void Get(MQMessage message);
-
public void Get(MQMessage message, MQGetMessageOptions getMessageOptions);
-
public void Get(MQMessage message, MQGetMessageOptions getMessageOptions, int MaxMsgSize);
- Throws MQException.
Retrieves a message from the topic.
This method uses a default instance of MQGetMessageOptions to do the get. The message option used is
MQGMO_NOWAIT
.If the get fails, the MQMessage object is unchanged. If it succeeds, the message descriptor and message data portions of the MQMessage are replaced with the message descriptor and message data from the incoming message.
All calls to IBM MQ from a particular MQQueueManager are synchronous. Therefore, if you perform a get with wait, all other threads using the same MQQueueManager are blocked from making further IBM MQ calls until the Get call is accomplished. If you need multiple threads to access IBM MQ simultaneously, each thread must create its own MQQueueManager object.
message
- Contains the message descriptor and the returned message data. Some of the fields in the message descriptor are input parameters. It is important to ensure that the MessageId and CorrelationId input parameters are set as required.
getMessageOptions
- Options controlling the action of the get.
Using option
MQC.MQGMO_CONVERT
might result in an exception with reason codeMQC.MQRC_CONVERTED_STRING_TOO_BIG
when converting from single-byte character codes to double byte codes. In this case, the message is copied into the buffer without conversion.If
getMessageOptions
is not specified, the message option used isMQGMO_NOWAIT
.If you use the
MQGMO_LOGICAL_ORDER
option in a reconnectable client, theMQRC_RECONNECT_INCOMPATIBLE
reason code is returned. MaxMsgSize
- The largest message this message object is to receive. If the message on the queue is larger than this size, one of two things occurs:
- If the
MQGMO_ACCEPT_TRUNCATED_MSG
flag is set in the MQGetMessageOptions object, the message is filled with as much of the message data as possible. An exception is thrown with theMQCC_WARNING
completion code andMQRC_TRUNCATED_MSG_ACCEPTED
reason code. - If the
MQGMO_ACCEPT_TRUNCATED_MSG
flag is not set, the message remains on the queue. An exception is thrown with theMQCC_WARNING
completion code andMQRC_TRUNCATED_MSG_FAILED
reason code.
If
MaxMsgSize
is not specified, the whole message is retrieved. - If the
Constructors
public MQTopic(MQQueueManager queueManager, MQDestination destination, string topicName, string topicObject, int options);
public MQTopic(MQQueueManager queueManager, MQDestination destination, string topicName, string topicObject, int options, string alternateUserId);
public MQTopic(MQQueueManager queueManager, MQDestination destination, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName);
public MQTopic(MQQueueManager queueManager, MQDestination destination, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName, System.Collections.Hashtable properties);
public MQTopic(MQQueueManager queueManager, string topicName, string topicObject, int openAs, int options);
public MQTopic(MQQueueManager queueManager, string topicName, string topicObject, int openAs, int options, string alternateUserId);
public MQTopic(MQQueueManager queueManager, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName);
public MQTopic(MQQueueManager queueManager, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName, System.Collections.Hashtable properties);
-
Access a topic on
queueManager
.MQTopic objects are closely related to administrative topic objects, which are sometimes called topic objects. On input, topicObject points to an administrative topic object. The MQTopic constructor obtains a topic string from the topic object and combines it with topicName to create a topic name. Either or both topicObject or topicName can be null. The topic name is matched to the topic tree, and the name of the closest matching administrative topic object is returned in topicObject.
The topics that are associated with the MQTopic object are the result of combining two topic strings. The first topic string is defined by the administrative topic object identified by
topicObject
. The second topic string istopicString
. The resulting topic string associated with the MQTopic object can identify multiple topics by including wild cards.Depending on whether the topic is opened for publishing or subscribing, you can use the MQTopic.Put methods to publish on topics, or MQTopic.Get methods to receive publications on topics. If you want to publish and subscribe to the same topic, you must access the topic twice, once for publish and once for subscribe.
If you create an MQTopic object for subscription, without providing an MQDestination object, a managed subscription is assumed. If you pass a queue as an MQDestination object, an unmanaged subscription is assumed. You must ensure the subscription options you set are consistent with the subscription being managed or unmanaged.
queueManager
- Queue manager to access a topic on.
destination
destination
is an MQQueue instance. By providingdestination
, MQTopic is opened as an unmanaged subscription. Publications on the topic are delivered to the queue accessed asdestination
.topicName
- A topic string that is the second part of the topic name.
topicName
is concatenated with the topic string defined in thetopicObject
administrative topic object. You can settopicName
to null, in which case the topic name is defined by the topic string intopicObject
. topicObject
- On input,
topicObject
is the name of the topic object that contains the topic string that forms the first part of the topic name. The topic string intopicObject
is concatenated withtopicName
. The rules for constructing topic strings are defined in Combining topic strings. openAs
- Access the topic to publish or subscribe. The parameter can contain only one of these options:
MQC.MQTOPIC_OPEN_AS_SUBSCRIPTION
MQC.MQTOPIC_OPEN_AS_PUBLICATION
options
-
Combine the options that control the opening of the topic for either publication or subscription. Use
MQC.MQSO_*
constants to access a topic for subscription andMQC.MQOO_*
constants to access a topic for publication.If more than one option is required, add the values together, or combine the option values using the bitwise
OR
operator. alternateUserId
- Specify the alternate user ID that is used to check for the required authorization to finish the operation. You must specify
alternateUserId
, if eitherMQC.MQOO_ALTERNATE_USER_AUTHORITY
orMQC.MQSO_ALTERNATE_USER_AUTHORITY
is set in the options parameter. subscriptionName
subscriptionName
is required if the optionsMQC.MQSO_DURABLE
orMQC.MQSO_ALTER
are provided. In both cases, MQTopic is implicitly opened for subscription. An exception is thrown if theMQC.MQSO_DURABLE
is set, and the subscription exists, or ifMQC.MQSO_ALTER
is set, and the subscription does not exist.properties
- Set any of the special subscription properties listed using a hash table. Specified entries in the hash table are updated with output values. Entries are not added to the hash table to report output values.
MQC.MQSUB_PROP_ALTERNATE_SECURITY_ID
MQC.MQSUB_PROP_SUBSCRIPTION_EXPIRY
MQC.MQSUB_PROP_SUBSCRIPTION_USER_DATA
MQC.MQSUB_PROP_SUBSCRIPTION_CORRELATION_ID
MQC.MQSUB_PROP_PUBLICATION_PRIORITY
MQC.MQSUB_PROP_PUBLICATION_ACCOUNTING_TOKEN
MQC.MQSUB_PROP_PUBLICATION_APPLICATIONID_DATA
public MQTopic MQQueueManager.AccessTopic(MQDestination destination, string topicName, string topicObject, int options);
public MQTopic MQQueueManager.AccessTopic(MQDestination destination, string topicName, string topicObject, int options, string alternateUserId);
public MQTopic MQQueueManager.AccessTopic(MQDestination destination, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName);
public MQTopic MQQueueManager.AccessTopic(MQDestination destination, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName, System.Collections.Hashtable properties);
public MQTopic MQQueueManager.AccessTopic(string topicName, string topicObject, int openAs, int options);
public MQTopic MQQueueManager.AccessTopic(string topicName, string topicObject, int openAs, int options, string alternateUserId);
public MQTopic MQQueueManager.AccessTopic(string topicName, string topicObject, int options, string alternateUserId, string subscriptionName);
public MQTopic MQQueueManager.AccessTopic(string topicName, string topicObject, int options, string alternateUserId, string subscriptionName, System.Collections.Hashtable properties);
-
Access a topic on this queue manager.
MQTopic objects are closely related to administrative topic objects, which are sometimes called topic objects. On input, topicObject points to an administrative topic object. The MQTopic constructor obtains a topic string from the topic object and combines it with topicName to create a topic name. Either or both topicObject or topicName can be null. The topic name is matched to the topic tree, and the name of the closest matching administrative topic object is returned in topicObject.
The topics that are associated with the MQTopic object are the result of combining two topic strings. The first topic string is defined by the administrative topic object identified by
topicObject
. The second topic string istopicString
. The resulting topic string associated with the MQTopic object can identify multiple topics by including wild cards.Depending on whether the topic is opened for publishing or subscribing, you can use the MQTopic.Put methods to publish on topics, or MQTopic.Get methods to receive publications on topics. If you want to publish and subscribe to the same topic, you must access the topic twice, once for publish and once for subscribe.
If you create an MQTopic object for subscription, without providing an MQDestination object, a managed subscription is assumed. If you pass a queue as an MQDestination object, an unmanaged subscription is assumed. You must ensure the subscription options you set are consistent with the subscription being managed or unmanaged.
destination
destination
is an MQQueue instance. By providingdestination
, MQTopic is opened as an unmanaged subscription. Publications on the topic are delivered to the queue accessed asdestination
.topicName
- A topic string that is the second part of the topic name.
topicName
is concatenated with the topic string defined in thetopicObject
administrative topic object. You can settopicName
to null, in which case the topic name is defined by the topic string intopicObject
. topicObject
- On input,
topicObject
is the name of the topic object that contains the topic string that forms the first part of the topic name. The topic string intopicObject
is concatenated withtopicName
. The rules for constructing topic strings are defined in Combining topic strings. openAs
- Access the topic to publish or subscribe. The parameter can contain only one of these options:
MQC.MQTOPIC_OPEN_AS_SUBSCRIPTION
MQC.MQTOPIC_OPEN_AS_PUBLICATION
options
-
Combine the options that control the opening of the topic for either publication or subscription. Use
MQC.MQSO_*
constants to access a topic for subscription andMQC.MQOO_*
constants to access a topic for publication.If more than one option is required, add the values together, or combine the option values using the bitwise
OR
operator. alternateUserId
- Specify the alternate user ID that is used to check for the required authorization to finish the operation. You must specify
alternateUserId
, if eitherMQC.MQOO_ALTERNATE_USER_AUTHORITY
orMQC.MQSO_ALTERNATE_USER_AUTHORITY
is set in the options parameter. subscriptionName
subscriptionName
is required if the optionsMQC.MQSO_DURABLE
orMQC.MQSO_ALTER
are provided. In both cases, MQTopic is implicitly opened for subscription. An exception is thrown if theMQC.MQSO_DURABLE
is set, and the subscription exists, or ifMQC.MQSO_ALTER
is set, and the subscription does not exist.properties
- Set any of the special subscription properties listed using a hash table. Specified entries in the hash table are updated with output values. Entries are not added to the hash table to report output values.
MQC.MQSUB_PROP_ALTERNATE_SECURITY_ID
MQC.MQSUB_PROP_SUBSCRIPTION_EXPIRY
MQC.MQSUB_PROP_SUBSCRIPTION_USER_DATA
MQC.MQSUB_PROP_SUBSCRIPTION_CORRELATION_ID
MQC.MQSUB_PROP_PUBLICATION_PRIORITY
MQC.MQSUB_PROP_PUBLICATION_ACCOUNTING_TOKEN
MQC.MQSUB_PROP_PUBLICATION_APPLICATIONID_DATA