com.ibm.mq

Class MQTopic

java.lang.Object

com.ibm.mq.jmqi.JmqiObject

com.ibm.mq.MQManagedObject

com.ibm.mq.MQDestination

com.ibm.mq.MQTopic

public class MQTopic
extends MQDestination

MQTopic is a sub class of MQDestination and provides set, inquire, put (send / publish), and get (receive / subscribe) operations for WebSphere MQ topics. The set and inquire capabilities are inherited from MQManagedObject. Whereas the put and get capabilities are inherited from MQDestination.

Use either the MQTopic constructors or the MQQueueManager#accessQueue methods to gain access to an MQTopic object. An MQTopic object can only be accessed for publication or subscription, not both simultaneously.

When used for receiving messages the MQTopic object can be created with an unmanaged or managed subscription and as a durable or non-durable subscriber - multiple overloaded constructors are provided for these differing scenarios.

See Also:

MQDestination, MQQueue, MQQueueManager

Field Summary

Fields inherited from class com.ibm.mq.MQManagedObject

alternateUserId, closeOptions, connectionReference, isOpen, name, openOptions

Fields inherited from class com.ibm.mq.jmqi.JmqiObject

COMP_JM, COMP_JN, COMP_JO

Constructor Summary

Constructors

Constructor and Description
MQTopic(MQQueueManager qMgr, MQDestination destination, java.lang.String topicName, java.lang.String topicObject, int options) Establishes access to a WebSphere MQ topic on the specified queue manager.
MQTopic(MQQueueManager qMgr, MQDestination destination, java.lang.String topicName, java.lang.String topicObject, int options, java.lang.String alternateUserId) Establishes access to a WebSphere MQ topic on the specified queue manager.
MQTopic(MQQueueManager qMgr, MQDestination destination, java.lang.String topicName, java.lang.String topicObject, int options, java.lang.String alternateUserId, java.lang.String subscriptionName) Establishes access to a WebSphere MQ topic on the specified queue manager.
MQTopic(MQQueueManager qMgr, MQDestination destination, java.lang.String topicName, java.lang.String topicObject, int options, java.lang.String alternateUserId, java.lang.String subscriptionName, java.util.Hashtable<java.lang.String,java.lang.Object> parameters) Establishes access to a WebSphere MQ topic on the specified queue manager.
MQTopic(MQQueueManager qMgr, java.lang.String topicName, java.lang.String topicObject, int openAs, int options) Establishes access to a WebSphere MQ topic on the specified queue manager.
MQTopic(MQQueueManager qMgr, java.lang.String topicName, java.lang.String topicObject, int openAs, int options, java.lang.String alternateUserId) Establishes access to a WebSphere MQ topic on the specified queue manager.
MQTopic(MQQueueManager qMgr, java.lang.String topicName, java.lang.String topicObject, int options, java.lang.String alternateUserId, java.lang.String subscriptionName) Establishes access to a WebSphere MQ topic on the specified queue manager.
MQTopic(MQQueueManager qMgr, java.lang.String topicName, java.lang.String topicObject, int options, java.lang.String alternateUserId, java.lang.String subscriptionName, java.util.Hashtable<java.lang.String,java.lang.Object> parameters) Establishes access to a WebSphere MQ topic on the specified queue manager.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes the object.
MQSubscription	getSubscriptionReference() Gets the associated MQSubscription object when the topic is opened for subscription.
MQDestination	getUnmanagedDestinationReference() Gets the MQDestination (MQQueue) associated with an unmanaged subscription.
boolean	isDurable() Gets the durable status of the subscription.
boolean	isManaged() Gets the managed status of the subscription.
boolean	isSubscribed() Gets the subscribed status of the topic.

Methods inherited from class com.ibm.mq.MQDestination

get, get, get, getCreationDateTime, getDestinationType, getQueueManagerCmdLevel, put, put, setQueueManagerCmdLevel

Methods inherited from class com.ibm.mq.MQManagedObject

getAlternateUserId, getAttributeString, getCloseOptions, getConnectionReference, getDescription, getName, getOpenOptions, getResolvedObjectString, getResolvedQName, getResolvedType, inquire, inquire, isOpen, set, setAttributeString, setCloseOptions

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MQTopic

public MQTopic(MQQueueManager qMgr,
       java.lang.String topicName,
       java.lang.String topicObject,
       int openAs,
       int options)
        throws MQException

Establishes access to a WebSphere MQ topic on the specified queue manager. The MQTopic object may be opened for either publication or subscription depending upon the value of the openAs parameter. The value dictates the use of the options parameter - this may map to the equivalent CMQC#MQOO options for publication or the equivalent CMQC#MQSO options for subscription.

The options specified allows the MQTopic object to be used to get or browse messages, put messages, inquire about the attributes of the topic, or set the attributes of the topic.

An MQTopic object cannot be used for both publication and subscription simultaneously. Therefore, the constructor creates an MQTopic object for publication OR subscription using the supplied topic name (topicName) and topic object (topicObject).

The full topic name is given by the concatenation of the preceding two parts. A part exists if the first character of the field is neither a blank nor a null character. If both parts exist a '/' character is inserted between them in the resultant combined topic. If only one of these parts exist it is used unchanged as the topic. These parts are concatenated in the order they are listed below.

• The value of the TOPICSTR parameter of the topic object named in topicObject.
• topicName, if the length provided for that string is non-zero.

If there are wildcards in the topicName, the interpretation of those wildcards can be controlled using the wildcard options specified in the options parameter.

When creating an MQTopic for subscriptions, the store (MQQueue) will be managed and owned by the queue manager. This constructor can therefore only be used to create a managed subscription.

Parameters:

qMgr - The object that represents the queue manager on which the topic resides.

topicName - The topic string to publish or subscribe against. The topicName parameter directly maps to the ObjectString field of the MQSD (see MQSD.getObjectString(). The full topic name used is the combination of the topicObject and topicName parameters.

topicObject - The name of the topic object as defined on the local queue manager. If this property is specified in combination with a non-zero length topicName, then the specified topicName is appended to the topic string contained in the topic object with a separator character. It is the full topic string which is published or subscribed against.

The parameter is both an input and output parameter. Upon successful completion of the method the closest matching administrative node is located within the topic hierarchy and returned. The contained topic object may therefore differ to that originally specified.

openAs - Indicates whether the topic is being opened for either publication or subscription. The parameter may contain one of the following valid options:

• CMQC.MQTOPIC_OPEN_AS_SUBSCRIPTION
• CMQC.MQTOPIC_OPEN_AS_PUBLICATION

The topic object may only be opened for either publication or subscription. Specifying more than a single option will result in an error condition.

options - Options that control the opening of the topic for either publication or subscription. The following options are valid:

• CMQC.MQOO_ALTERNATE_USER_AUTHORITY
• CMQC.MQOO_BIND_AS_Q_DEF
• CMQC.MQOO_FAIL_IF_QUIESCING
• CMQC.MQOO_OUTPUT
• CMQC.MQOO_PASS_ALL_CONTEXT
• CMQC.MQOO_PASS_IDENTITY_CONTEXT
• CMQC.MQOO_SET_ALL_CONTEXT
• CMQC.MQOO_SET_IDENTITY_CONTEXT

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.

However, upon opening the topic for subscription the following valid options are shown below. If more than one option is required, the values can be added together or combined using the bitwise OR operator.

• CMQC.MQSO_CREATE
• CMQC.MQSO_RESUME
• CMQC.MQSO_ALTER

If none of these options are specified, then CMQC.MQSO_CREATE + CMQC.MQSO_ALTER is assumed. Other valid options are also available.

Upon opening a topic for subscription, the constructor can only cater for a managed, non-durable subscription. The following options are therefore enforced:

• CMQC.MQSO_NON_DURABLE
• CMQC.MQSO_MANAGED

Throws:

MQException - If the call fails.

See Also:

MQQueueManager.accessTopic(String, String, int, int)

MQTopic

public MQTopic(MQQueueManager qMgr,
       java.lang.String topicName,
       java.lang.String topicObject,
       int openAs,
       int options,
       java.lang.String alternateUserId)
        throws MQException

Establishes access to a WebSphere MQ topic on the specified queue manager. The MQTopic object may be opened for either publication or subscription depending upon the value of the openAs parameter. The value dictates the use of the options parameter - this may map to the equivalent CMQC#MQOO options for publication or the equivalent CMQCMQSO options for subscription.

If either CMQC.MQOO_ALTERNATE_USER_AUTHORITY or CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, the alternateUserId parameter is used to check for the necessary authorization.

The options specified allows the MQTopic object to be used to get or browse messages, put messages, inquire about the attributes of the topic, or set the attributes of the topic.

An MQTopic object cannot be used for both publication and subscription simultaneously. Therefore, the constructor creates an MQTopic object for publication OR subscription using the supplied topic name (topicName) and topic object (topicObject).

The full topic name is given by the concatenation of the preceding two parts. A part exists if the first character of the field is neither a blank nor a null character. If both parts exist a '/' character is inserted between them in the resultant combined topic. If only one of these parts exist it is used unchanged as the topic. These parts are concatenated in the order they are listed below.

• The value of the TOPICSTR parameter of the topic object named in topicObject.
• topicName, if the length provided for that string is non-zero.

If there are wildcards in the topicName, the interpretation of those wildcards can be controlled using the wildcard options specified in the options parameter.

When creating an MQTopic for subscriptions, the store (MQQueue) will be managed and owned by the queue manager. This constructor can therefore only be used to create a managed subscription.

Parameters:

qMgr - The object that represents the queue manager on which the topic resides.

topicName - The topic string to publish or subscribe against. The topicName parameter directly maps to the ObjectString field of the MQSD (see MQSD.getObjectString(). The full topic name used is the combination of the topicObject and topicName parameters.

topicObject - The name of the topic object as defined on the local queue manager. If this property is specified in combination with a non-zero length topicName, then the specified topicName is appended to the topic string contained in the topic object with a separator character. It is the full topic string which is published or subscribed against.

The parameter is both an input and output parameter. Upon successful completion of the method the closest matching administrative node is located within the topic hierarchy and returned. The contained topic object may therefore differ to that originally specified.

openAs - Indicates whether the topic is being opened for either publication or subscription. The parameter may contain one of the following valid options:

• CMQC.MQTOPIC_OPEN_AS_SUBSCRIPTION
• CMQC.MQTOPIC_OPEN_AS_PUBLICATION

The topic object may only be opened for either publication or subscription. Specifying more than a single option will result in an error condition.

options - Options that control the opening of the topic for either publication or subscription. The following options are valid:

• CMQC.MQOO_ALTERNATE_USER_AUTHORITY
• CMQC.MQOO_BIND_AS_Q_DEF
• CMQC.MQOO_FAIL_IF_QUIESCING
• CMQC.MQOO_OUTPUT
• CMQC.MQOO_PASS_ALL_CONTEXT
• CMQC.MQOO_PASS_IDENTITY_CONTEXT
• CMQC.MQOO_SET_ALL_CONTEXT
• CMQC.MQOO_SET_IDENTITY_CONTEXT

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.

However, upon opening the topic for subscription the following valid options are shown below. If more than one option is required, the values can be added together or combined using the bitwise OR operator.

• CMQC.MQSO_CREATE
• CMQC.MQSO_RESUME
• CMQC.MQSO_ALTER

If none of these options are specified, then CMQC.MQSO_CREATE + CMQC.MQSO_ALTER is assumed. Other valid options are also available.

Upon opening a topic for subscription, the constructor can only cater for a managed, non-durable subscription. The following options are therefore enforced:

• CMQC.MQSO_NON_DURABLE
• CMQC.MQSO_MANAGED

alternateUserId - If either CMQC.MQOO_ALTERNATE_USER_AUTHORITY or CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, this parameter specifies the alternate user identifier that is used to check for the required authorization to complete the operation.

If either CMQC.MQOO_ALTERNATE_USER_AUTHORITY or CMQC.MQSO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

Throws:

MQException - If the call fails.

See Also:

MQQueueManager.accessTopic(String, String, int, int, String)

MQTopic

public MQTopic(MQQueueManager qMgr,
       java.lang.String topicName,
       java.lang.String topicObject,
       int options,
       java.lang.String alternateUserId,
       java.lang.String subscriptionName)
        throws MQException

Establishes access to a WebSphere MQ topic on the specified queue manager. The presence of the subscriptionName parameter indicates that this constructor may be used for opening the topic for subscriptions only. The options parameter therefore always maps to the equivalent CMQC#MQSO values.

If the CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, the alternateUserId parameter is used to check for the necessary authorization.

The options specified allows the MQTopic object to be used to get or browse messages, inquire about the attributes of the topic, or set the attributes of the topic.

The constructor creates an MQTopic object for subscription using the supplied topic name ( topicName) and topic object (topicObject).

The full topic name is given by the concatenation of the preceding two parts. A part exists if the first character of the field is neither a blank nor a null character. If both parts exist a '/' character is inserted between them in the resultant combined topic. If only one of these parts exist it is used unchanged as the topic. These parts are concatenated in the order they are listed below.

• The value of the TOPICSTR parameter of the topic object named in topicObject.
• topicName, if the length provided for that string is non-zero.

If there are wildcards in the topicName, the interpretation of those wildcards can be controlled using the wildcard options specified in the options parameter.

When creating an MQTopic for subscriptions, the store (MQQueue) will be managed and owned by the queue manager. This constructor can therefore only be used to create a managed subscription.

Parameters:

qMgr - The object that represents the queue manager on which the topic resides.

topicName - The topic string to publish or subscribe against. The topicName parameter directly maps to the ObjectString field of the MQSD (see MQSD.getObjectString(). The full topic name used is the combination of the topicObject and topicName parameters.

topicObject - The name of the topic object as defined on the local queue manager. If this property is specified in combination with a non-zero length topicName, then the specified topicName is appended to the topic string contained in the topic object with a separator character. It is the full topic string which is published or subscribed against.

The parameter is both an input and output parameter. Upon successful completion of the method the closest matching administrative node is located within the topic hierarchy and returned. The contained topic object may therefore differ to that originally specified.

options - Upon opening the topic for subscription the following valid options are shown below. If more than one option is required, the values can be added together or combined using the bitwise OR operator.

• CMQC.MQSO_CREATE
• CMQC.MQSO_RESUME
• CMQC.MQSO_ALTER

If none of these options are specified, then CMQC.MQSO_CREATE + CMQC.MQSO_ALTER is assumed. Other valid options are also available.

The constructor can only cater for managed subscriptions. The following options are therefore enforced:

• CMQC.MQSO_MANAGED

alternateUserId - If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, this parameter specifies the alternate user identifier that is used to check for the required authorization to complete the operation.

If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

subscriptionName - This field is only required if the options parameter specified CMQC.MQSO_DURABLE, but if provided will be used by the queue manager for CMQC.MQSO_NON_DURABLE as well.

For a CMQC.MQSO_DURABLE subscription it is the means by which you identify a subscription to resume it after it has been created, if you have either closed the handle to the subscription or have been disconnected from the queue manager.

If altering an existing subscription using the CMQC.MQSO_ALTER option, the subscription name cannot be changed

Throws:

MQException - If the call fails.

See Also:

MQQueueManager.accessTopic(String, String, int, String, String)

MQTopic

public MQTopic(MQQueueManager qMgr,
       java.lang.String topicName,
       java.lang.String topicObject,
       int options,
       java.lang.String alternateUserId,
       java.lang.String subscriptionName,
       java.util.Hashtable<java.lang.String,java.lang.Object> parameters)
        throws MQException

Establishes access to a WebSphere MQ topic on the specified queue manager. The presence of the subscriptionName parameter indicates that this constructor may be used for opening the topic for subscriptions only. The options parameter therefore always maps to the equivalent CMQC#MQSO values.

If the CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, the alternateUserId parameter is used to check for the necessary authorization.

The options specified allows the MQTopic object to be used to get or browse messages, inquire about the attributes of the topic, or set the attributes of the topic.

The constructor creates an MQTopic object for subscription using the supplied topic name ( topicName) and topic object (topicObject).

The full topic name is given by the concatenation of the preceding two parts. A part exists if the first character of the field is neither a blank nor a null character. If both parts exist a '/' character is inserted between them in the resultant combined topic. If only one of these parts exist it is used unchanged as the topic. These parts are concatenated in the order they are listed below.

• The value of the TOPICSTR parameter of the topic object named in topicObject.
• topicName, if the length provided for that string is non-zero.

If there are wildcards in the topicName, the interpretation of those wildcards can be controlled using the wildcard options specified in the options parameter.

When creating an MQTopic for subscriptions, the store (MQQueue) will be managed and owned by the queue manager. This constructor can therefore only be used to create a managed subscription.

Extra non-standard input and output parameters can also be specified using the parameters hash table. If a property is an output field it will only be populated within the hash table if it was originally specified on input. Essentially, no new key/value pairs will be added to the hash table - only existing ones updated.

Parameters:

qMgr - The object that represents the queue manager on which the topic resides.

topicName - The topic string to publish or subscribe against. The topicName parameter directly maps to the ObjectString field of the MQSD (see MQSD.getObjectString(). The full topic name used is the combination of the topicObject and topicName parameters.

topicObject - The name of the topic object as defined on the local queue manager. If this property is specified in combination with a non-zero length topicName, then the specified topicName is appended to the topic string contained in the topic object with a separator character. It is the full topic string which is published or subscribed against.

The parameter is both an input and output parameter. Upon successful completion of the method the closest matching administrative node is located within the topic hierarchy and returned. The contained topic object may therefore differ to that originally specified.

options - Upon opening the topic for subscription the following valid options are shown below. If more than one option is required, the values can be added together or combined using the bitwise OR operator.

• CMQC.MQSO_CREATE
• CMQC.MQSO_RESUME
• CMQC.MQSO_ALTER

If none of these options are specified, then CMQC.MQSO_CREATE + CMQC.MQSO_ALTER is assumed. Other valid options are also available.

The constructor can only cater for managed subscriptions. The following options are therefore enforced:

• CMQC.MQSO_MANAGED

alternateUserId - If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, this parameter specifies the alternate user identifier that is used to check for the required authorization to complete the operation.

If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

subscriptionName - This field is only required if the options parameter specified CMQC.MQSO_DURABLE, but if provided will be used by the queue manager for CMQC.MQSO_NON_DURABLE as well.

For a CMQC.MQSO_DURABLE subscription it is the means by which you identify a subscription to resume it after it has been created, if you have either closed the handle to the subscription or have been disconnected from the queue manager.

If altering an existing subscription using the CMQC.MQSO_ALTER option, the subscription name cannot be changed

parameters - The hash table can be used to specify non-standard input and output parameters to the subscription request. If a property is an output field it will only be populated within the hash table if it was originally specified on input. Consequently, no new key / value pairs will be added to the hash table - only existing ones updated. The following key names are valid and may be specified:

• CMQC.MQSUB_PROP_ALTERNATE_SECURITY_ID
• CMQC.MQSUB_PROP_SUBSCRIPTION_EXPIRY
• CMQC.MQSUB_PROP_SUBSCRIPTION_USER_DATA
• CMQC.MQSUB_PROP_SUBSCRIPTION_CORRELATION_ID
• CMQC.MQSUB_PROP_PUBLICATION_PRIORITY
• CMQC.MQSUB_PROP_PUBLICATION_ACCOUNTING_TOKEN
• CMQC.MQSUB_PROP_PUBLICATION_APPLICATIONID_DATA

All are specified as String type properties. The corresponding language conversion routines can be used to convert the values to the relevant types.

Throws:

MQException - If the call fails.

See Also:

MQQueueManager.accessTopic(String, String, int, String, String, Hashtable)

MQTopic

public MQTopic(MQQueueManager qMgr,
       MQDestination destination,
       java.lang.String topicName,
       java.lang.String topicObject,
       int options)
        throws MQException

Establishes access to a WebSphere MQ topic on the specified queue manager. The presence of the destination parameter indicates that this constructor may be used for opening the topic for subscriptions only. The options parameter therefore always maps to the equivalent CMQC#MQSO values.

The options specified allows the MQTopic object to be used to get or browse messages, inquire about the attributes of the topic, or set the attributes of the topic.

The constructor creates an MQTopic object for subscription using the supplied topic name ( topicName) and topic object (topicObject).

The full topic name is given by the concatenation of the preceding two parts. A part exists if the first character of the field is neither a blank nor a null character. If both parts exist a '/' character is inserted between them in the resultant combined topic. If only one of these parts exist it is used unchanged as the topic. These parts are concatenated in the order they are listed below.

• The value of the TOPICSTR parameter of the topic object named in topicObject.
• topicName, if the length provided for that string is non-zero.

If there are wildcards in the topicName, the interpretation of those wildcards can be controlled using the wildcard options specified in the options parameter.

When creating an MQTopic for subscription, the subscription store (destination) is provided, managed and owned by the user. The queue manager takes no responsibility for this object and it is left to the user to correctly dispose of it. Any messages available for this subscription will be delivered to the specified destination.

The destination parameter must be valid and cannot be left blank or null. Consequently, this constructor can therefore only be used to create an unmanaged, non-durable subscription.

Parameters:

qMgr - The object that represents the queue manager on which the topic resides.

destination - An existing MQDestination object which should receive the publications. For WebSphere MQ v7.0 this will always map to an MQQueue object. However, other destination types may exist in future.

The MQDestination (MQQueue) object can be created by calling an MQQueueManager #accessQueue method or an MQQueue constructor.

The corresponding destination is held as a reference within the MQTopic object as the UnmanagedDestinationReference property (see getUnmanagedDestinationReference().

topicName - The topic string to publish or subscribe against. The topicName parameter directly maps to the ObjectString field of the MQSD (see MQSD.getObjectString(). The full topic name used is the combination of the topicObject and topicName parameters.

topicObject - The name of the topic object as defined on the local queue manager. If this property is specified in combination with a non-zero length topicName, then the specified topicName is appended to the topic string contained in the topic object with a separator character. It is the full topic string which is published or subscribed against.

The parameter is both an input and output parameter. Upon successful completion of the method the closest matching administrative node is located within the topic hierarchy and returned. The contained topic object may therefore differ to that originally specified.

options - Upon opening the topic for subscription the following valid options are shown below. If more than one option is required, the values can be added together or combined using the bitwise OR operator.

• CMQC.MQSO_CREATE
• CMQC.MQSO_RESUME
• CMQC.MQSO_ALTER

If none of these options are specified, then CMQC.MQSO_CREATE + CMQC.MQSO_ALTER is assumed. Other valid options are also available.

The constructor can only cater for unmanaged, non-durable subscriptions. The following options are therefore enforced:

• CMQC.MQSO_NON_DURABLE
• ~CMQC.MQSO_MANAGED

Throws:

MQException - If the call fails.

See Also:

MQQueueManager.accessTopic(MQDestination, String, String, int)

MQTopic

public MQTopic(MQQueueManager qMgr,
       MQDestination destination,
       java.lang.String topicName,
       java.lang.String topicObject,
       int options,
       java.lang.String alternateUserId)
        throws MQException

Establishes access to a WebSphere MQ topic on the specified queue manager. The presence of the destination parameter indicates that this constructor may be used for opening the topic for subscriptions only. The options parameter therefore always maps to the equivalent CMQC#MQSO values.

If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, the alternateUserId parameter is used to check for the necessary authorization.

The options specified allows the MQTopic object to be used to get or browse messages, inquire about the attributes of the topic, or set the attributes of the topic.

The constructor creates an MQTopic object for subscription using the supplied topic name ( topicName) and topic object (topicObject).

The full topic name is given by the concatenation of the preceding two parts. A part exists if the first character of the field is neither a blank nor a null character. If both parts exist a '/' character is inserted between them in the resultant combined topic. If only one of these parts exist it is used unchanged as the topic. These parts are concatenated in the order they are listed below.

• The value of the TOPICSTR parameter of the topic object named in topicObject.
• topicName, if the length provided for that string is non-zero.

If there are wildcards in the topicName, the interpretation of those wildcards can be controlled using the wildcard options specified in the options parameter.

When creating an MQTopic for subscription, the subscription store (destination) is provided, managed and owned by the user. The queue manager takes no responsibility for this object and it is left to the user to correctly dispose of it. Any messages available for this subscription will be delivered to the specified destination.

The destination parameter must be valid and cannot be left blank or null. Consequently, this constructor can therefore only be used to create an unmanaged, non-durable subscription.

Parameters:

qMgr - The object that represents the queue manager on which the topic resides.

destination - An existing MQDestination object which should receive the publications. For WebSphere MQ v7.0 this will always map to an MQQueue object. However, other destination types may exist in future.

The MQDestination(MQQueue) object can be created by calling an MQQueueManager #accessQueue method or an MQQueue constructor.

The corresponding destination is held as a reference within the MQTopic object as the UnmanagedDestinationReference property (see getUnmanagedDestinationReference().

topicName - The topic string to publish or subscribe against. The topicName parameter directly maps to the ObjectString field of the MQSD (see MQSD.getObjectString(). The full topic name used is the combination of the topicObject and topicName parameters.

topicObject - The name of the topic object as defined on the local queue manager. If this property is specified in combination with a non-zero length topicName, then the specified topicName is appended to the topic string contained in the topic object with a separator character. It is the full topic string which is published or subscribed against.

The parameter is both an input and output parameter. Upon successful completion of the method the closest matching administrative node is located within the topic hierarchy and returned. The contained topic object may therefore differ to that originally specified.

options - Upon opening the topic for subscription the following valid options are shown below. If more than one option is required, the values can be added together or combined using the bitwise OR operator.

• CMQC.MQSO_CREATE
• CMQC.MQSO_RESUME
• CMQC.MQSO_ALTER

If none of these options are specified, then CMQC.MQSO_CREATE + CMQC.MQSO_ALTER is assumed. Other valid options are also available.

The constructor can only cater for unmanaged, non-durable subscriptions. The following options are therefore enforced:

• CMQC.MQSO_NON_DURABLE
• ~CMQC.MQSO_MANAGED

alternateUserId - If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, this parameter specifies the alternate user identifier that is used to check for the required authorization to complete the operation.

If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

Throws:

MQException - If the call fails.

See Also:

MQQueueManager.accessTopic(MQDestination, String, String, int, String)

MQTopic

public MQTopic(MQQueueManager qMgr,
       MQDestination destination,
       java.lang.String topicName,
       java.lang.String topicObject,
       int options,
       java.lang.String alternateUserId,
       java.lang.String subscriptionName)
        throws MQException

Establishes access to a WebSphere MQ topic on the specified queue manager. The presence of the destination and subscriptionName parameters indicates that this constructor may be used for opening the topic for subscriptions only. The options parameter therefore always maps to the equivalent MQSO values.

If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, the alternateUserId parameter is used to check for the necessary authorization.

The options specified allows the MQTopic object to be used to get or browse messages, inquire about the attributes of the topic, or set the attributes of the topic.

The constructor creates an MQTopic object for subscription using the supplied topic name ( topicName) and topic object (topicObject).

The full topic name is given by the concatenation of the preceding two parts. A part exists if the first character of the field is neither a blank nor a null character. If both parts exist a '/' character is inserted between them in the resultant combined topic. If only one of these parts exist it is used unchanged as the topic. These parts are concatenated in the order they are listed below.

• The value of the TOPICSTR parameter of the topic object named in topicObject.
• topicName, if the length provided for that string is non-zero.

If there are wildcards in the topicName, the interpretation of those wildcards can be controlled using the wildcard options specified in the options parameter.

When creating an MQTopic for subscription, the subscription store (destination) is provided, managed and owned by the user. The queue manager takes no responsibility for this object and it is left to the user to correctly dispose of it. Any messages available for this subscription will be delivered to the specified destination.

The destination parameter must be valid and cannot be left blank or null. Consequently, this constructor can therefore only be used to create an unmanaged subscription.

Parameters:

qMgr - The object that represents the queue manager on which the topic resides.

destination - An existing MQDestination object which should receive the publications. For WebSphere MQ v7.0 this will always map to an MQQueue object. However, other destination types may exist in future.

The MQDestination(MQQueue) object can be created by calling an MQQueueManager #accessQueue method or an MQQueue constructor.

The corresponding destination is held as a reference within the MQTopic object as the UnmanagedDestinationReference property (see getUnmanagedDestinationReference().

topicName - The topic string to publish or subscribe against. The topicName parameter directly maps to the ObjectString field of the MQSD (see MQSD.getObjectString(). The full topic name used is the combination of the topicObject and topicName parameters.

topicObject - The name of the topic object as defined on the local queue manager. If this property is specified in combination with a non-zero length topicName, then the specified topicName is appended to the topic string contained in the topic object with a separator character. It is the full topic string which is published or subscribed against.

The parameter is both an input and output parameter. Upon successful completion of the method the closest matching administrative node is located within the topic hierarchy and returned. The contained topic object may therefore differ to that originally specified.

options - Upon opening the topic for subscription the following valid options are shown below. If more than one option is required, the values can be added together or combined using the bitwise OR operator.

• CMQC.MQSO_CREATE
• CMQC.MQSO_RESUME
• CMQC.MQSO_ALTER

If none of these options are specified, then CMQC.MQSO_CREATE + CMQC.MQSO_ALTER is assumed. Other valid options are:

• CMQC.MQSO_DURABLE
• CMQC.MQSO_GROUP_SUB
• CMQC.MQSO_MANAGED
• CMQC.MQSO_SET_IDENTITY_CONTEXT
• CMQC.MQSO_FIXED_USERID
• CMQC.MQSO_ANY_USERID
• CMQC.MQSO_PUBLICATIONS_ON_REQUEST
• CMQC.MQSO_NEW_PUBLICATIONS_ONLY
• CMQC.MQSO_FAIL_IF_QUIESCING
• CMQC.MQSO_ALTERNATE_USER_AUTHORITY
• CMQC.MQSO_WILDCARD_CHAR
• CMQC.MQSO_WILDCARD_TOPIC
• CMQC.MQSO_SET_CORREL_ID
• CMQC.MQSO_SCOPE_QMGR
• CMQC.MQSO_NO_READ_AHEAD
• CMQC.MQSO_READ_AHEAD

The constructor can only cater for unmanaged subscriptions. The following options are therefore enforced:

• ~CMQC.MQSO_MANAGED

alternateUserId - If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, this parameter specifies the alternate user identifier that is used to check for the required authorization to complete the operation.

If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

subscriptionName - This field is only required if the options parameter specified CMQC.MQSO_DURABLE, but if provided will be used by the queue manager for CMQC.MQSO_NON_DURABLE as well.

For a CMQC.MQSO_DURABLE subscription it is the means by which you identify a subscription to resume it after it has been created, if you have either closed the handle to the subscription or have been disconnected from the queue manager.

If altering an existing subscription using the CMQC.MQSO_ALTER option, the subscription name cannot be changed

Throws:

MQException - If the call fails.

See Also:

MQQueueManager.accessTopic(MQDestination, String, String, int, String, String)

MQTopic

public MQTopic(MQQueueManager qMgr,
       MQDestination destination,
       java.lang.String topicName,
       java.lang.String topicObject,
       int options,
       java.lang.String alternateUserId,
       java.lang.String subscriptionName,
       java.util.Hashtable<java.lang.String,java.lang.Object> parameters)
        throws MQException

Establishes access to a WebSphere MQ topic on the specified queue manager. The presence of the destination and subscriptionName parameters indicates that this constructor may be used for opening the topic for subscriptions only. The options parameter therefore always maps to the equivalent CMQC#MQSO values.

If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, the alternateUserId parameter is used to check for the necessary authorization.

The options specified allows the MQTopic object to be used to get or browse messages, inquire about the attributes of the topic, or set the attributes of the topic.

The constructor creates an MQTopic object for subscription using the supplied topic name ( topicName) and topic object (topicObject).

The full topic name is given by the concatenation of the preceding two parts. A part exists if the first character of the field is neither a blank nor a null character. If both parts exist a '/' character is inserted between them in the resultant combined topic. If only one of these parts exist it is used unchanged as the topic. These parts are concatenated in the order they are listed below.

• The value of the TOPICSTR parameter of the topic object named in topicObject.
• topicName, if the length provided for that string is non-zero.

If there are wildcards in the topicName, the interpretation of those wildcards can be controlled using the wildcard options specified in the options parameter.

When creating an MQTopic for subscription, the subscription store (destination) is provided, managed and owned by the user. The queue manager takes no responsibility for this object and it is left to the user to correctly dispose of it. Any messages available for this subscription will be delivered to the specified destination.

The destination parameter must be valid and cannot be left blank or null. Consequently, this constructor can therefore only be used to create an unmanaged subscription.

Extra non-standard input and output parameters can also be specified using the parameters hash table. If a property is an output field it will only be populated within the hash table if it was originally specified on input. Essentially, no new key/value pairs will be added to the hash table - only existing ones updated.

Parameters:

qMgr - The object that represents the queue manager on which the topic resides.

destination - An existing MQDestination object which should receive the publications. For WebSphere MQ v7.0 this will always map to an MQQueue object. However, other destination types may exist in future.

The MQDestination(MQQueue) object can be created by calling an MQQueueManager #accessQueue method or an MQQueue constructor.

The corresponding destination is held as a reference within the MQTopic object as the UnmanagedDestinationReference property (see getUnmanagedDestinationReference().

topicName - The topic string to publish or subscribe against. The topicName parameter directly maps to the ObjectString field of the MQSD (see MQSD.getObjectString(). The full topic name used is the combination of the topicObject and topicName parameters.

topicObject - The name of the topic object as defined on the local queue manager. If this property is specified in combination with a non-zero length topicName, then the specified topicName is appended to the topic string contained in the topic object with a separator character. It is the full topic string which is published or subscribed against.

The parameter is both an input and output parameter. Upon successful completion of the method the closest matching administrative node is located within the topic hierarchy and returned. The contained topic object may therefore differ to that originally specified.

options - Upon opening the topic for subscription the following valid options are shown below. If more than one option is required, the values can be added together or combined using the bitwise OR operator.

• CMQC.MQSO_CREATE
• CMQC.MQSO_RESUME
• CMQC.MQSO_ALTER

If none of these options are specified, then CMQC.MQSO_CREATE + CMQC.MQSO_ALTER is assumed. Other valid options are:

• CMQC.MQSO_DURABLE
• CMQC.MQSO_GROUP_SUB
• CMQC.MQSO_MANAGED
• CMQC.MQSO_SET_IDENTITY_CONTEXT
• CMQC.MQSO_FIXED_USERID
• CMQC.MQSO_ANY_USERID
• CMQC.MQSO_PUBLICATIONS_ON_REQUEST
• CMQC.MQSO_NEW_PUBLICATIONS_ONLY
• CMQC.MQSO_FAIL_IF_QUIESCING
• CMQC.MQSO_ALTERNATE_USER_AUTHORITY
• CMQC.MQSO_WILDCARD_CHAR
• CMQC.MQSO_WILDCARD_TOPIC
• CMQC.MQSO_SET_CORREL_ID
• CMQC.MQSO_SCOPE_QMGR
• CMQC.MQSO_NO_READ_AHEAD
• CMQC.MQSO_READ_AHEAD

The constructor can only cater for unmanaged subscriptions. The following options are therefore enforced:

• ~CMQC.MQSO_MANAGED

alternateUserId - If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is specified in the options parameter, this parameter specifies the alternate user identifier that is used to check for the required authorization to complete the operation.

If CMQC.MQSO_ALTERNATE_USER_AUTHORITY is not specified, this parameter can be left blank (or null).

subscriptionName - This field is only required if the options parameter specified CMQC.MQSO_DURABLE, but if provided will be used by the queue manager for CMQC.MQSO_NON_DURABLE as well.

For a CMQC.MQSO_DURABLE subscription it is the means by which you identify a subscription to resume it after it has been created, if you have either closed the handle to the subscription or have been disconnected from the queue manager.

If altering an existing subscription using the CMQC.MQSO_ALTER option, the subscription name cannot be changed

parameters - The hash table can be used to specify non-standard input and output parameters to the subscription request. If a property is an output field it will only be populated within the hash table if it was originally specified on input. Consequently, no new key / value pairs will be added to the hash table - only existing ones updated. The following key names are valid and may be specified:

• CMQC.MQSUB_PROP_ALTERNATE_SECURITY_ID
• CMQC.MQSUB_PROP_SUBSCRIPTION_EXPIRY
• CMQC.MQSUB_PROP_SUBSCRIPTION_USER_DATA
• CMQC.MQSUB_PROP_SUBSCRIPTION_CORRELATION_ID
• CMQC.MQSUB_PROP_PUBLICATION_PRIORITY
• CMQC.MQSUB_PROP_PUBLICATION_ACCOUNTING_TOKEN
• CMQC.MQSUB_PROP_PUBLICATION_APPLICATIONID_DATA

All are specified as String type properties. The corresponding language conversion routines can be used to convert the values to the relevant types.

Throws:

MQException - If the call fails.

See Also:

MQQueueManager.accessTopic(MQDestination, String, String, int, String, String, Hashtable)

Method Detail

isDurable

public boolean isDurable()
                  throws MQException

Gets the durable status of the subscription. If the topic was opened for output - i.e. publication, the property is ignored and will always be false.

Returns:

true if the subscription is durable, false otherwise

Throws:

MQException - If the call fails.

isManaged

public boolean isManaged()
                  throws MQException

Gets the managed status of the subscription. If the topic was opened for output - i.e. publication, the property is ignored and will always be false.

Returns:

true if the subscription is managed by the queue manager, false otherwise

Throws:

MQException - If the call fails.

isSubscribed

public boolean isSubscribed()
                     throws MQException

Gets the subscribed status of the topic.

Returns:

true if the topic was opened for subscription, false if the topic was opened for publication

Throws:

MQException - If the call fails.

getSubscriptionReference

public MQSubscription getSubscriptionReference()
                                        throws MQException

Gets the associated MQSubscription object when the topic is opened for subscription.

The user should never need to manually create an MQSubscription object and should only be created by the underlying API once the topic has been successfully subscribed to.

The reference is available to users should they wish to modify the close options or invoke any of the objects methods.

Returns:

the associated MQSubscription object if the topic was opened for subscription

Throws:

MQException - If the call fails.

getUnmanagedDestinationReference

public MQDestination getUnmanagedDestinationReference()
                                               throws MQException

Gets the MQDestination (MQQueue) associated with an unmanaged subscription. This is the destination specified when the topic was created.

Returns:

the associated MQDestination or null if the topic was opened for publication or with a managed subscription

Throws:

MQException - If the call fails.

See Also:

MQTopic(MQQueueManager, MQDestination, String, String, int), MQTopic(MQQueueManager, MQDestination, String, String, int, String), MQTopic(MQQueueManager, MQDestination, String, String, int, String, String), MQTopic(MQQueueManager, MQDestination, String, String, int, String, String, Hashtable)

close

public void close()
           throws MQException

Description copied from class: MQManagedObject

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.

See Also:

MQManagedObject.close()