com.ibm.broker.config.proxy
Class TopicProxy

java.lang.Object
  extended by com.ibm.broker.config.proxy.AdministeredObject
      extended by com.ibm.broker.config.proxy.TopicProxy
Direct Known Subclasses:
TopicRootProxy

public class TopicProxy
extends AdministeredObject

Represents a node in the topic hierarchy.

In order to use TopicProxy objects, applications must first obtain handles to them. Here is an example of how to do this:

     ConfigManagerConnectionParameters cmcp =
         new MQConfigManagerConnectionParameters("localhost", 1414, "QMGR");
     ConfigManagerProxy cmp = ConfigManagerProxy.getInstance(cmcp);
     TopicRootProxy t1 = cmp.getTopicRoot();
     TopicProxy t2 = t1.getChildTopicByName("shares");
     TopicProxy t3 = t2.getChildTopicByName("tech");
     TopicProxy t4 = t3.getChildTopicByName("ibm");
 

com.ibm.broker.config.proxy.TopicProxy extends com.ibm.broker.config.proxy.AdministeredObject

Responsibilities Represents a node in the topic tree. Is also a container of sub-topics. Sub-topics are also represented as TopicProxy objects, and the result is a Topic hierarchy.
Internal Collaborators None

 Change Activity:
 -------- ----------- ------------- ------------------------------------
 Reason:  Date:       Originator:   Comments:
 -------- ----------- ------------- ------------------------------------
 f25103.1 2004-03-18  HDMPL         v6 Release
 f44739.7 2007-07-30  HDMPL         v6.1 release:
                                         Methods now return genericized types where relevant
 

Version:
Config/com/ibm/broker/config/proxy/TopicProxy.java, CMP, S000 1.49

Nested Class Summary
static class TopicProxy.Policy
          A small class that represents a policy for a given topic.
static class TopicProxy.QoP
          A small structure that represents all the possible types of a topic's quality of protection.
 
Method Summary
 void addDefaultPolicy(TopicProxy.Policy defaultPolicy)
          Adds the default Topic Policy.
 void addPolicies(TopicProxy.Policy[] list)
          Adds an array of policies to this topic's list of policies and sends the results to the Configuration Manager.
 TopicProxy createChildTopic(java.lang.String name)
          Creates a topic of the supplied name so that it sits under the current topic.
 void deleteChildTopic(java.lang.String name)
          Removes the topic with the supplied name (and its children) from the current topic.
 TopicProxy getChildTopic(java.util.Properties props)
          Returns the first TopicProxy object directly (that is, one level) underneath the current one that matches the supplied filter.
 TopicProxy getChildTopicByName(java.lang.String topicName)
          Returns the TopicProxy object with the supplied name, or null if a topic of that name does not exist or if the supplied argument was null.
 java.util.Enumeration<TopicProxy> getChildTopics(java.util.Properties props)
          Returns an enumeration of all TopicProxy objects directly (that is, one level) underneath the current one that match the supplied filter.
 ConfigurationObjectType getConfigurationObjectType()
          Returns the ConfigurationObjectType associated with this AdministeredObject type.
 ConfigurationObjectType getConfigurationObjectTypeOfParent()
          Returns the ConfigurationObjectType associated with the logical parent of this AdministeredObject type.
 TopicProxy.Policy getDefaultPolicy()
          Returns the default Topic Policy.
 java.lang.String getMulticastEnabled()
          Returns the multicast 'enabled' string associated with this topic.
 boolean getMulticastEncrypted()
          Returns the multicast 'encrypted' flag associated with this topic.
 java.lang.String getMulticastIPv4GroupAddress()
          Returns the IPv4 multicast group address associated with this topic.
 java.lang.String getMulticastIPv6GroupAddress()
          This method is reserved for future use.
 boolean getMulticastQualityOfService()
          Returns the multicast 'qualityOfService' flag associated with this topic.
 int getNumberOfPolicies()
          Returns the number of TopicProxy.Policy objects in the topic's list, excluding any default policy.
 java.util.Enumeration getPolicies()
          Returns a Enumeration of all the TopicProxy.Policy objects in the topic's list.
 TopicProxy.QoP getQualityOfProtectionLevel()
          Returns the Quality of Protection level associated with this topic.
 java.lang.String getTopicName()
          Returns the name of the topic
 void moveTopic(java.lang.String name, TopicProxy newProxy)
          Atomically removes the topic tree with the supplied name from the current TopicProxy and adds it to the supplied instance.
 void removeDefaultPolicy()
          Removes the default Topic Policy.
 void removePolicies(TopicProxy.Policy[] list)
          Removes a list of policies from this topic's list of policies and sends the results to the Configuration Manager.
 void setDefaultPolicy(TopicProxy.Policy defaultPolicy)
          Sets the default Topic Policy.
 void setMulticastEnabled(java.lang.String isEnabled)
          Sets the multicast 'enabled' value for the topic.
 void setMulticastEncrypted(boolean isEncrypted)
          Sets the multicast 'encrypted' flag for the topic.
 void setMulticastGroupAddress(java.lang.String ipv4GroupAddress, java.lang.String ipv6GroupAddress)
          Sets the multicast group addresses for the topic.
 void setMulticastQualityOfService(boolean isReliable)
          Sets the multicast QoS flag for the topic.
 void setQualityOfProtectionLevel(TopicProxy.QoP newQoP)
          Sets the Quality of Protection level for the topic.
static java.util.Properties withName(java.lang.String name)
          Returns a new Properties object that has the Name attribute set to the supplied String, and the type attribute to be the name of the Topic class.
static java.util.Properties withUUID(java.lang.String uuid)
          Returns a new Properties object that has the UUID attribute set to the supplied String, and the type attribute to be the name of the Topic class.
 
Methods inherited from class com.ibm.broker.config.proxy.AdministeredObject
deregisterListener, deregisterListener, elements, getLastBIPMessages, getLastCompletionCode, getLastUpdateUser, getLongDescription, getManagedSubcomponent, getManagedSubcomponentFromStringRepresentation, getManagedSubcomponents, getManagedSubcomponents, getManagedSubcomponents, getManagedSubcomponents, getManagedSubcomponentsAsStrings, getManagedSubcomponentsAsStrings, getName, getNumberOfSubcomponents, getParent, getProperties, getProperty, getProperty, getProperty, getProperty, getRepositoryTimestamp, getShortDescription, getTimeOfLastCompletionCode, getTimeOfLastUpdate, getType, getUUID, hasBeenRestrictedByConfigManager, hasBeenRestrictedByConfigManager, hasBeenUpdatedByConfigManager, hasBeenUpdatedByConfigManager, isAwaitingSubmissionForCreation, isAwaitingSubmissionForDeletion, isDeployed, isShared, refresh, registerListener, registerListener, registerListener, setLongDescription, setName, setProperties, setShortDescription, toString, toVerboseString, unsubscribeFromConfigurationManagerUpdates
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

createChildTopic

public TopicProxy createChildTopic(java.lang.String name)
                            throws ConfigManagerProxyLoggedException
Creates a topic of the supplied name so that it sits under the current topic. The access permissions of the child are (by default) set to those of the parent.

If a topic already exists with the supplied name, the existing topic is returned.

Parameters:
name - - Name of the new topic.
Throws:
ConfigManagerProxyLoggedException - if the request to create a topic could not be sent to the Configuration Manager

getChildTopic

public TopicProxy getChildTopic(java.util.Properties props)
                         throws ConfigManagerProxyPropertyNotInitializedException
Returns the first TopicProxy object directly (that is, one level) underneath the current one that matches the supplied filter.

Parameters:
props - Filter to restrict which children to return, based on the topics' attributes. Each key is an attribute name of the required object and each value is the required value of the attribute. A null or empty Properties object will match all topics that have this topic as a parent.
Returns:
TopicProxy The first direct subcomponent which matched the supplied filter, or null if no subcomponent exists.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of topics could not be determined because the Config Manager has not yet supplied the topic information.
See Also:
AttributeConstants

getChildTopicByName

public TopicProxy getChildTopicByName(java.lang.String topicName)
                               throws ConfigManagerProxyPropertyNotInitializedException
Returns the TopicProxy object with the supplied name, or null if a topic of that name does not exist or if the supplied argument was null.

Parameters:
topicName -
Returns:
TopicProxy Configuration Manager Proxy representation of the requested topic.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of available topics could not be determined because the Configuration Manager did not supply the topic information to the Configuration Manager Proxy before a timeout occurred.

getChildTopics

public java.util.Enumeration<TopicProxy> getChildTopics(java.util.Properties props)
                                                 throws ConfigManagerProxyPropertyNotInitializedException
Returns an enumeration of all TopicProxy objects directly (that is, one level) underneath the current one that match the supplied filter. So calling this method on the "shares" topic with no filter inside the following hierarchy...
 shares = { tech, retail, oil }
 tech = { billco, ibm }
 retail = { ... }
 
...would return an Enumeration of three TopicProxy objects representing tech, retail and oil.

Parameters:
props - Filter to restrict which children to return, based on the required topics' attributes. Each key is an attribute name of the required object and each value is the required value of the attribute. A null or empty Properties object will match all topics that have the current topic as a parent.
Returns:
Enumeration of TopicProxy objects. The enumeration will contain no elements if there are no children underneath the current topic.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of topics could not be determined because the Config Manager has not yet supplied the topic information.

deleteChildTopic

public void deleteChildTopic(java.lang.String name)
                      throws ConfigManagerProxyLoggedException,
                             ConfigManagerProxyPropertyNotInitializedException

Removes the topic with the supplied name (and its children) from the current topic. If more than one topic with the supplied name exists, all instances are removed.

Parameters:
name - of the topic to delete. If null, all topics are removed.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of topics could not be determined because the Config Manager has not yet supplied the topic information.
ConfigManagerProxyLoggedException - if the request to delete the topics could not be sent to the Configuration Manager.

moveTopic

public void moveTopic(java.lang.String name,
                      TopicProxy newProxy)
               throws ConfigManagerProxyLoggedException,
                      ConfigManagerProxyPropertyNotInitializedException

Atomically removes the topic tree with the supplied name from the current TopicProxy and adds it to the supplied instance. Requires that a "batch" of operations (controlled using ConfigManagerProxy. beginUpdates(), clearUpdates() and sendUpdates() is NOT already in progress.

Simple checks are made to ensure that the source topic doesn't equal the target topic, and that the child name is not the target. However it is still possible to end up with circular references if you try to copy a topic tree into one of its children. Such a call may succeed and you might find that some topics can no longer be referenced. Hence, care should be taken by the caller to ensure that this does not happen.

Parameters:
name - The name of the Subtopic to remove from this TopicProxy
newProxy - - The TopicProxy to which the broker should be added.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the topic corresponding to the supplied name could not be loaded because information on the parent topic (i.e. this) has not yet been supplied.
ConfigManagerProxyLoggedException - if the topic with the supplied name does not exist as a child of the current topic, if a batch of requests was already in progress, if the child name and the target are the same, if the target is the same as the current topic, or if the message to move could not be sent to the Configuration Manager.

getTopicName

public java.lang.String getTopicName()
                              throws ConfigManagerProxyPropertyNotInitializedException
Returns the name of the topic

Returns:
String name of the current TopicProxy
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of topics could not be determined because the Config Manager has not yet supplied the topic information.

getQualityOfProtectionLevel

public TopicProxy.QoP getQualityOfProtectionLevel()
                                           throws ConfigManagerProxyPropertyNotInitializedException
Returns the Quality of Protection level associated with this topic.

Returns:
TopicProxy.QoP Describes the level of protection assigned to the topic.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of topics could not be determined because the Config Manager has not yet supplied the topic information.

getMulticastEnabled

public java.lang.String getMulticastEnabled()
                                     throws ConfigManagerProxyPropertyNotInitializedException
Returns the multicast 'enabled' string associated with this topic. The returned value is one of (AttributeConstants.) TOPIC_MULTICASTENABLE_DISABLE, TOPIC_MULTICASTENABLE_ENABLE and TOPIC_MULTICASTENABLE_INHERIT.

Returns:
String the value of the multicastEnable flag.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the property could not be determined because the Config Manager has not yet supplied the topic information.

getMulticastIPv4GroupAddress

public java.lang.String getMulticastIPv4GroupAddress()
                                              throws ConfigManagerProxyPropertyNotInitializedException
Returns the IPv4 multicast group address associated with this topic.

Returns:
String the IPv4 group address for this address. If no IPv4 group address exists for this topic, null is returned.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the property could not be determined because the Config Manager has not yet supplied the topic information.

getMulticastIPv6GroupAddress

public java.lang.String getMulticastIPv6GroupAddress()
                                              throws ConfigManagerProxyPropertyNotInitializedException
This method is reserved for future use.

Returns:
Throws:
ConfigManagerProxyPropertyNotInitializedException

getMulticastEncrypted

public boolean getMulticastEncrypted()
                              throws ConfigManagerProxyPropertyNotInitializedException
Returns the multicast 'encrypted' flag associated with this topic.

Returns:
boolean true if and only if the multicast encrypted flag is set.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the property could not be determined because the Config Manager has not yet supplied the topic information.

getMulticastQualityOfService

public boolean getMulticastQualityOfService()
                                     throws ConfigManagerProxyPropertyNotInitializedException
Returns the multicast 'qualityOfService' flag associated with this topic.

Returns:
boolean true if and only if the topic has reliable quality of service.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the property could not be determined because the Config Manager has not yet supplied the topic information.

getDefaultPolicy

public TopicProxy.Policy getDefaultPolicy()
                                   throws ConfigManagerProxyPropertyNotInitializedException
Returns the default Topic Policy.

Returns:
TopicProxy.Policy Containing the default policy. The type of this Policy is defined as AttributeConstants.TOPIC_PRINCIPAL_PUBLICGROUP.
Throws:
ConfigManagerProxyPropertyNotInitializedException - If the default policy has not been supplied to us from the Configuration Manager.

setQualityOfProtectionLevel

public void setQualityOfProtectionLevel(TopicProxy.QoP newQoP)
                                 throws ConfigManagerProxyLoggedException
Sets the Quality of Protection level for the topic.

Parameters:
newQoP - - The new Quality of Protection level (TopicProxy.QoP.none, TopicProxy.QoP.channelIntegrity, TopicProxy.QoP.messageIntegrity or TopicProxy.QoP.encrypted).
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager, or if the supplied argument was TopicProxy.QoP.unknown.

setMulticastEnabled

public void setMulticastEnabled(java.lang.String isEnabled)
                         throws ConfigManagerProxyLoggedException
Sets the multicast 'enabled' value for the topic. Valid values are (AttributeConstants.) TRUE, FALSE and TOPIC_MULTICAST_ENABLE_INHERIT.

Parameters:
isEnabled - the requested value of the multicastEnabled flag.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager.

setMulticastGroupAddress

public void setMulticastGroupAddress(java.lang.String ipv4GroupAddress,
                                     java.lang.String ipv6GroupAddress)
                              throws ConfigManagerProxyLoggedException
Sets the multicast group addresses for the topic.

Parameters:
ipv4GroupAddress - IPv4 group address for this topic.
ipv6GroupAddress - Reserved for future use. Do not set this parameter to anything other than null or the empty string.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager.

setMulticastEncrypted

public void setMulticastEncrypted(boolean isEncrypted)
                           throws ConfigManagerProxyLoggedException
Sets the multicast 'encrypted' flag for the topic.

Parameters:
isEncrypted - True if and only if the topic is encrypted.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager.

setMulticastQualityOfService

public void setMulticastQualityOfService(boolean isReliable)
                                  throws ConfigManagerProxyLoggedException
Sets the multicast QoS flag for the topic.

Parameters:
isReliable - True if and only if the topic has reliable quality of service.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager.

setDefaultPolicy

public void setDefaultPolicy(TopicProxy.Policy defaultPolicy)
                      throws ConfigManagerProxyLoggedException
Sets the default Topic Policy. Validates that Publish, Subscribe and Persistence attributes of the defaultPolicy are not set to INHERIT.

Parameters:
defaultPolicy - Containing the default policy values.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager.

addDefaultPolicy

public void addDefaultPolicy(TopicProxy.Policy defaultPolicy)
                      throws ConfigManagerProxyLoggedException
Adds the default Topic Policy.

Parameters:
defaultPolicy - Containing the default policy values.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager.

removeDefaultPolicy

public void removeDefaultPolicy()
                         throws ConfigManagerProxyLoggedException
Removes the default Topic Policy.

Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager.

withUUID

public static java.util.Properties withUUID(java.lang.String uuid)
Returns a new Properties object that has the UUID attribute set to the supplied String, and the type attribute to be the name of the Topic class. This provides an easy way of supplying filters to the get*() calls. For example, t.getChildTopics(TopicProxy.withUUID("1234")); will return the Topic with UUID "1234" that exists in t.

Returns:
java.util.Properties - a new Properties object with the relevant key/value pairs set.

withName

public static java.util.Properties withName(java.lang.String name)
Returns a new Properties object that has the Name attribute set to the supplied String, and the type attribute to be the name of the Topic class. This provides an easy way of supplying filters to the get*() calls. For example, t.getChildTopics(TopicProxy.withName("tech")); will return the Topic with Name "tech" that exists in t.

Returns:
java.util.Properties - a new Properties object with the relevant key/value pairs set.

getConfigurationObjectType

public ConfigurationObjectType getConfigurationObjectType()
Returns the ConfigurationObjectType associated with this AdministeredObject type.

Specified by:
getConfigurationObjectType in class AdministeredObject
Returns:
ConfigurationObjectType associated with this class.

getConfigurationObjectTypeOfParent

public ConfigurationObjectType getConfigurationObjectTypeOfParent()
Returns the ConfigurationObjectType associated with the logical parent of this AdministeredObject type.

Specified by:
getConfigurationObjectTypeOfParent in class AdministeredObject
Returns:
ConfigurationObjectType associated with the logical parent of this class.

getPolicies

public java.util.Enumeration getPolicies()
                                  throws ConfigManagerProxyPropertyNotInitializedException
Returns a Enumeration of all the TopicProxy.Policy objects in the topic's list.

Returns:
Enumeration of TopicProxy.Policy objects.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the requested property is not yet known.

getNumberOfPolicies

public int getNumberOfPolicies()
                        throws ConfigManagerProxyPropertyNotInitializedException
Returns the number of TopicProxy.Policy objects in the topic's list, excluding any default policy. The returned value will be the number of elements in the enumeration supplied by getPolicies() (assuming the set of policies does not change).

Returns:
int Number of TopicProxy.Policy objects.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the requested property is not yet known.

addPolicies

public void addPolicies(TopicProxy.Policy[] list)
                 throws ConfigManagerProxyLoggedException

Adds an array of policies to this topic's list of policies and sends the results to the Configuration Manager.

Parameters:
list - set of policies to add to the TopicProxy.
Throws:
ConfigManagerProxyLoggedException - if the new list of policies could not be sent to the Configuration Manager.

removePolicies

public void removePolicies(TopicProxy.Policy[] list)
                    throws ConfigManagerProxyLoggedException,
                           ConfigManagerProxyPropertyNotInitializedException

Removes a list of policies from this topic's list of policies and sends the results to the Configuration Manager.

Parameters:
list - set of policies to remove from the TopicProxy.
Throws:
ConfigManagerProxyLoggedException - if the new list of policies could not be sent to the Configuration Manager.
ConfigManagerProxyPropertyNotInitializedException