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 ofMQDestination
and provides set, inquire, put (send / publish), and get (receive / subscribe) operations for WebSphere MQ topics. The set and inquire capabilities are inherited fromMQManagedObject
. 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
-
-
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 associatedMQSubscription
object when the topic is opened for subscription.MQDestination
getUnmanagedDestinationReference()
Gets theMQDestination
(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
-
-
-
-
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 theopenAs
parameter. The value dictates the use of theoptions
parameter - this may map to the equivalentCMQC
#MQOO
options for publication or the equivalentCMQC
#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 intopicObject
. topicName
, if the length provided for that string is non-zero.
topicName
, the interpretation of those wildcards can be controlled using the wildcard options specified in theoptions
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. ThetopicName
parameter directly maps to the ObjectString field of theMQSD
(seeMQSD.getObjectString()
. The full topic name used is the combination of thetopicObject
andtopicName
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 lengthtopicName
, then the specifiedtopicName
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: 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
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.
If none of these options are specified, thenCMQC.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:
- Throws:
MQException
- If the call fails.- See Also:
MQQueueManager.accessTopic(String, String, int, int)
- The value of the
-
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 theopenAs
parameter. The value dictates the use of theoptions
parameter - this may map to the equivalentCMQC
#MQOO
options for publication or the equivalentCMQC
MQSO
options for subscription.If either
CMQC.MQOO_ALTERNATE_USER_AUTHORITY
orCMQC.MQSO_ALTERNATE_USER_AUTHORITY
is specified in theoptions
parameter, thealternateUserId
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 intopicObject
. topicName
, if the length provided for that string is non-zero.
topicName
, the interpretation of those wildcards can be controlled using the wildcard options specified in theoptions
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. ThetopicName
parameter directly maps to the ObjectString field of theMQSD
(seeMQSD.getObjectString()
. The full topic name used is the combination of thetopicObject
andtopicName
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 lengthtopicName
, then the specifiedtopicName
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: 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
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.
If none of these options are specified, thenCMQC.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:
alternateUserId
- If eitherCMQC.MQOO_ALTERNATE_USER_AUTHORITY
orCMQC.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
orCMQC.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)
- The value of the
-
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 thesubscriptionName
parameter indicates that this constructor may be used for opening the topic for subscriptions only. Theoptions
parameter therefore always maps to the equivalentCMQC
#MQSO
values.If the
CMQC.MQSO_ALTERNATE_USER_AUTHORITY
is specified in theoptions
parameter, thealternateUserId
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 intopicObject
. topicName
, if the length provided for that string is non-zero.
topicName
, the interpretation of those wildcards can be controlled using the wildcard options specified in theoptions
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. ThetopicName
parameter directly maps to the ObjectString field of theMQSD
(seeMQSD.getObjectString()
. The full topic name used is the combination of thetopicObject
andtopicName
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 lengthtopicName
, then the specifiedtopicName
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. If none of these options are specified, thenCMQC.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:
alternateUserId
- IfCMQC.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 theoptions
parameter specifiedCMQC.MQSO_DURABLE
, but if provided will be used by the queue manager forCMQC.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)
- The value of the
-
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 thesubscriptionName
parameter indicates that this constructor may be used for opening the topic for subscriptions only. Theoptions
parameter therefore always maps to the equivalentCMQC
#MQSO
values.If the
CMQC.MQSO_ALTERNATE_USER_AUTHORITY
is specified in theoptions
parameter, thealternateUserId
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 intopicObject
. topicName
, if the length provided for that string is non-zero.
topicName
, the interpretation of those wildcards can be controlled using the wildcard options specified in theoptions
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. ThetopicName
parameter directly maps to the ObjectString field of theMQSD
(seeMQSD.getObjectString()
. The full topic name used is the combination of thetopicObject
andtopicName
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 lengthtopicName
, then the specifiedtopicName
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. If none of these options are specified, thenCMQC.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:
alternateUserId
- IfCMQC.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 theoptions
parameter specifiedCMQC.MQSO_DURABLE
, but if provided will be used by the queue manager forCMQC.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 changedparameters
- 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
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)
- The value of the
-
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 thedestination
parameter indicates that this constructor may be used for opening the topic for subscriptions only. Theoptions
parameter therefore always maps to the equivalentCMQC
#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 intopicObject
. topicName
, if the length provided for that string is non-zero.
topicName
, the interpretation of those wildcards can be controlled using the wildcard options specified in theoptions
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 existingMQDestination
object which should receive the publications. For WebSphere MQ v7.0 this will always map to anMQQueue
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. ThetopicName
parameter directly maps to the ObjectString field of theMQSD
(seeMQSD.getObjectString()
. The full topic name used is the combination of thetopicObject
andtopicName
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 lengthtopicName
, then the specifiedtopicName
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. If none of these options are specified, thenCMQC.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:
- Throws:
MQException
- If the call fails.- See Also:
MQQueueManager.accessTopic(MQDestination, String, String, int)
- The value of the
-
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 thedestination
parameter indicates that this constructor may be used for opening the topic for subscriptions only. Theoptions
parameter therefore always maps to the equivalentCMQC
#MQSO
values.If
CMQC.MQSO_ALTERNATE_USER_AUTHORITY
is specified in theoptions
parameter, thealternateUserId
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 intopicObject
. topicName
, if the length provided for that string is non-zero.
topicName
, the interpretation of those wildcards can be controlled using the wildcard options specified in theoptions
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 existingMQDestination
object which should receive the publications. For WebSphere MQ v7.0 this will always map to anMQQueue
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. ThetopicName
parameter directly maps to the ObjectString field of theMQSD
(seeMQSD.getObjectString()
. The full topic name used is the combination of thetopicObject
andtopicName
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 lengthtopicName
, then the specifiedtopicName
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. If none of these options are specified, thenCMQC.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:
alternateUserId
- IfCMQC.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)
- The value of the
-
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 thedestination
andsubscriptionName
parameters indicates that this constructor may be used for opening the topic for subscriptions only. Theoptions
parameter therefore always maps to the equivalentMQSO
values.If
CMQC.MQSO_ALTERNATE_USER_AUTHORITY
is specified in theoptions
parameter, thealternateUserId
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 intopicObject
. topicName
, if the length provided for that string is non-zero.
topicName
, the interpretation of those wildcards can be controlled using the wildcard options specified in theoptions
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 existingMQDestination
object which should receive the publications. For WebSphere MQ v7.0 this will always map to anMQQueue
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. ThetopicName
parameter directly maps to the ObjectString field of theMQSD
(seeMQSD.getObjectString()
. The full topic name used is the combination of thetopicObject
andtopicName
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 lengthtopicName
, then the specifiedtopicName
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. If none of these options are specified, thenCMQC.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:
alternateUserId
- IfCMQC.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 theoptions
parameter specifiedCMQC.MQSO_DURABLE
, but if provided will be used by the queue manager forCMQC.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)
- The value of the
-
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 thedestination
andsubscriptionName
parameters indicates that this constructor may be used for opening the topic for subscriptions only. Theoptions
parameter therefore always maps to the equivalentCMQC
#MQSO
values.If
CMQC.MQSO_ALTERNATE_USER_AUTHORITY
is specified in theoptions
parameter, thealternateUserId
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 intopicObject
. topicName
, if the length provided for that string is non-zero.
topicName
, the interpretation of those wildcards can be controlled using the wildcard options specified in theoptions
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 existingMQDestination
object which should receive the publications. For WebSphere MQ v7.0 this will always map to anMQQueue
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. ThetopicName
parameter directly maps to the ObjectString field of theMQSD
(seeMQSD.getObjectString()
. The full topic name used is the combination of thetopicObject
andtopicName
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 lengthtopicName
, then the specifiedtopicName
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. If none of these options are specified, thenCMQC.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:
alternateUserId
- IfCMQC.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 theoptions
parameter specifiedCMQC.MQSO_DURABLE
, but if provided will be used by the queue manager forCMQC.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 changedparameters
- 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
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)
- The value of the
-
-
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 befalse
.- 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 befalse
.- 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 associatedMQSubscription
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 theMQDestination
(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 settingcloseOptions
.- Overrides:
close
in classMQManagedObject
- Throws:
MQException
- if the WebSphere MQ call fails.- See Also:
MQManagedObject.close()
-
-