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
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.
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
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 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 parameters)
Establishes access to a WebSphere MQ topic on the specified queue manager.
|
Method Summary
Modifier and Type | Method and Description |
---|---|
|
close()
|
getSubscriptionReference()
Gets the associated
MQSubscription object when the topic is opened for subscription.
|
|
getUnmanagedDestinationReference()
Gets the
MQDestination ( MQQueue ) associated with an unmanaged subscription.
|
|
|
isDurable()
Gets the durable status of the subscription.
|
|
isManaged()
Gets the managed status of the subscription.
|
|
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
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:
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:
MQException
- If the call fails. MQTopic
- public MQTopic(MQQueueManager qMgr,
- java.lang.String topicName,
- java.lang.String topicObject,
- int openAs,
- int options,
- java.lang.String alternateUserId)
- throws MQException
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.
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 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 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.
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:
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 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).
MQException
- If the call fails. 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
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 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 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.
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.
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:
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
MQException
- If the call fails. 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 parameters)
- throws MQException
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 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 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.
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.
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:
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
String
type properties. The corresponding language
conversion routines can be used to convert the values to the relevant types. MQException
- If the call fails. MQTopic
- public MQTopic(MQQueueManager qMgr,
- MQDestination destination,
- java.lang.String topicName,
- java.lang.String topicObject,
- int options)
- throws MQException
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 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 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.
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.
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:
MQException
- If the call fails. MQTopic
- public MQTopic(MQQueueManager qMgr,
- MQDestination destination,
- java.lang.String topicName,
- java.lang.String topicObject,
- int options,
- java.lang.String alternateUserId)
- throws MQException
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 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 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.
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.
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:
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).
MQException
- If the call fails. 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
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 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 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.
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.
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:
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
MQException
- If the call fails. 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 parameters)
- throws MQException
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 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 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.
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.
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:
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
String
type properties. The corresponding language
conversion routines can be used to convert the values to the relevant types. MQException
- If the call fails. Method Detail
isDurable
- public boolean isDurable()
- throws MQException
false
.
true
if the subscription is durable, false
otherwise MQException
- If the call fails. isManaged
- public boolean isManaged()
- throws MQException
false
.
true
if the subscription is managed by the queue manager,
false
otherwise MQException
- If the call fails. isSubscribed
- public boolean isSubscribed()
- throws MQException
true
if the topic was opened for subscription, false
if the
topic was opened for publication MQException
- If the call fails. getSubscriptionReference
- public MQSubscription getSubscriptionReference( )
- throws MQException
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.
MQException
- If the call fails. getUnmanagedDestinationReference
- public MQDestination getUnmanagedDestinationReference( )
- throws MQException
MQDestination
( MQQueue
) associated with an unmanaged subscription.
This is the destination specified when the topic was created.
MQException
- If the call fails. close
- public void close()
- throws MQException
MQManagedObject
closeOptions
.
close
in class MQManagedObject
openAs
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.
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.