WBI BrokersTM
Config Manager Proxy API

com.ibm.broker.config.proxy
Class TopologyProxy

java.lang.Object
  extended bycom.ibm.broker.config.proxy.AdministeredObject
      extended bycom.ibm.broker.config.proxy.TopologyProxy

public class TopologyProxy
extends AdministeredObject

There is exactly one Topology associated with each Config Manager, and this is referenced by the TopologyProxy object.

In order to use TopologyProxy 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);
     TopologyProxy t = cmp.getTopology();
 

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

Responsibilities Represents a container for all Brokers and the links between them.
Internal Collaborators com.ibm.broker.config.proxy.BrokerProxy
com.ibm.broker.config.proxy.CollectiveProxy
 
 Change Activity:
 --------- ----------- ------------- ------------------------------------
 Reason:   Date:       Originator:   Comments:
 --------- ----------- ------------- ------------------------------------
 f25103.7  2004-03-18  HDMPL         v6 Release
 
 


Nested Class Summary
static class TopologyProxy.Connection
          A small data structure representing a connection between two brokers in the topology.
 
Method Summary
 BrokerProxy createBroker(String name, String qmgr)
          Asks the Config Manager to add a broker with the supplied name and queue manager to the Topology workspace.
 CollectiveProxy createCollective(String name)
          Asks the Config Manager to create a collective with the supplied name.
 void createConnectionByName(String sourceName, String targetName)
          Asks the Config Manager to create a logical connection between two brokers.
 void createConnectionByUUID(String sourceUUID, String targetUUID)
          Asks the Config Manager to create a logical connection between two brokers by UUID.
 void deleteBroker(String name)
          Asks the Config Manager to remove the broker with the supplied name from the Topology workspace.
 void deleteCollective(String name)
          Asks the Config Manager to remove the collective with the supplied name from the Topology workspace.
 void deleteConnectionByName(String sourceName, String targetName)
          Asks the Config Manager to remove a logical connection between two brokers.
 void deleteConnectionByUUID(String sourceUUID, String targetUUID)
          Asks the Config Manager to remove a logical connection between two brokers.
 void deploy()
          Deploys any changes made to the pub/sub topology since the last pub/sub topology deploy to the affected brokers.
 void deploy(boolean isDelta)
          Deploys the pub/sub topology configuration to brokers.
 DeployResult deploy(boolean isDelta, long timeToWaitMs)
          Deploys the pub/sub topology configuration to brokers.
 BrokerProxy getBroker(Properties props)
          Returns the first BrokerProxy object that matches the filter specified by the Properties argument.
 BrokerProxy getBrokerByName(String brokerName)
          Returns the BrokerProxy object with the supplied name, or null if a broker of that name does not exist or if the supplied argument was null.
 Enumeration getBrokers(Properties props)
          Returns an enumeration of all the BrokerProxy objects that match the filter specified by the Properties argument.
 CollectiveProxy getCollective(Properties props)
          Returns the first CollectiveProxy object that matches the filter specified by the Properties argument.
 CollectiveProxy getCollectiveByName(String collectiveName)
          Returns the CollectiveProxy object with the supplied name, or null if a collective of that name does not exist or if the supplied argument was null.
 Enumeration getCollectives(Properties props)
          Returns an enumeration of all the CollectiveProxy objects that match the filter specified by the Properties argument.
 ConfigurationObjectType getConfigurationObjectType()
          Returns the ConfigurationObjectType associated with this AdministeredObject type.
 ConfigurationObjectType getConfigurationObjectTypeOfParent()
          Returns the ConfigurationObjectType associated with the logical parent of this AdministeredObject type.
 Enumeration getConnections()
          Returns an enumeration of all TopologyProxy.Connection objects.
 Enumeration getConnections(String brokerUUID)
          Returns an enumeration of TopologyProxy.Connection objects that affect the broker with the supplied UUID
 int getNumberOfConnections()
          Returns the number of Connection objects in the topology.
 int getNumberOfConnections(String brokerUUID)
          Returns the number of Connection objects in the topology, or that involve the broker with the supplied UUID.
 String toString()
          Displays the name of the object
 
Methods inherited from class com.ibm.broker.config.proxy.AdministeredObject
deregisterListener, deregisterListener, elements, getAccessControlEntries, getLastBIPMessages, getLastCompletionCode, getLastUpdateUser, getLongDescription, getManagedSubcomponent, getManagedSubcomponentFromStringRepresentation, getManagedSubcomponents, getManagedSubcomponents, getManagedSubcomponents, getName, getNumberOfSubcomponents, getParent, getPredictedNewSubcomponents, getProperties, getProperty, getProperty, getProperty, getProperty, getRepositoryTimestamp, getShortDescription, getTimeOfLastCompletionCode, getTimeOfLastUpdate, getType, getUUID, hasBeenRestrictedByConfigManager, hasBeenRestrictedByConfigManager, hasBeenUpdatedByConfigManager, hasBeenUpdatedByConfigManager, isAwaitingSubmissionForCreation, isDeployed, isShared, refresh, registerListener, registerListener, registerListener, setAccessControlEntries, setLongDescription, setName, setProperties, setShortDescription, toVerboseString, unsubscribeFromConfigurationManagerUpdates, withName, withUUID
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

createBroker

public BrokerProxy createBroker(String name,
                                String qmgr)
                         throws ConfigManagerProxyLoggedException

Asks the Config Manager to add a broker with the supplied name and queue manager to the Topology workspace. It is assumed that the Broker has already been created using e.g. mqsicreatebroker.

Note that a default execution group is NOT created. After using this method, callers must then create a default execution group. For example: broker.createExecutionGroup("default");

Parameters:
name - Name of the new broker.
qmgr - Queue Manager associated with the new broker.
Returns:
BrokerProxy - A BrokerProxy that represents the new broker.
Throws:
ConfigManagerProxyLoggedException - - if the request to create a broker could not be sent to the Config Manager.

deleteBroker

public void deleteBroker(String name)
                  throws ConfigManagerProxyLoggedException,
                         ConfigManagerProxyPropertyNotInitializedException

Asks the Config Manager to remove the broker with the supplied name from the Topology workspace.

This method will, in the following order:

  1. Remove the broker from any collectives of which it is a member.
  2. Delete any connections for which the broker is the source or target.
  3. Delete any execution groups of the broker.
  4. Remove the broker from the Config Manager hierarchy and pub/sub topology..
This method does NOT deploy these changes to the broker.

Parameters:
name - Name of the broker to delete
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the broker with the supplied name could not be found because the Configuration Manager has not supplied complete topology information.
ConfigManagerProxyLoggedException - if the request to remove the broker could not be sent to the Config Manager.

deploy

public void deploy()
            throws ConfigManagerProxyLoggedException
Deploys any changes made to the pub/sub topology since the last pub/sub topology deploy to the affected brokers. The method returns as soon as the deploy request is enqueued for sending to the Configuration Manager.

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

deploy

public void deploy(boolean isDelta)
            throws ConfigManagerProxyLoggedException
Deploys the pub/sub topology configuration to brokers.

Parameters:
isDelta - If true, only changes to the deployed pub/sub topology made since the last pub/sub topology deploy will be submitted to brokers. Otherwise, the complete pub/sub topology will be deployed to all brokers. The method returns as soon as the deploy request is enqueued for sending to the Configuration Manager.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Config Manager.

deploy

public DeployResult deploy(boolean isDelta,
                           long timeToWaitMs)
                    throws ConfigManagerProxyLoggedException
Deploys the pub/sub topology configuration to brokers.

Parameters:
isDelta - If true, only changes to the deployed pub/sub topology made since the last pub/sub topology deploy will be submitted to brokers. Otherwise, the complete pub/sub topology will be deployed to all brokers.
timeToWaitMs - A positive value describes the maximum length of time to wait for broker responses (in milliseconds) before returning the DeployResult. Alternatively:
  • A value of 0 causes the method to return immediately after the message has been successfully sent to the Configuration Manager.
  • A value of AttributeConstants.DEPLOYRESULT_SUPPRESSION causes the method to return null immediately after the message has been successfully sent to the Configuration Manager. DeployResult objects are relatively expensive to create and maintain, and so supplying this constant should be used if the DeployResult is not parsed, or if performance of the Config Manager Proxy application is critical.
  • A value of AttributeConstants.DEPLOYRESULT_WAIT_INDEFINITELY causes the method to wait until responses have been received from all brokers affected by the deploy.
  • If batch mode is enabled the method returns immediately regardless of the value of this parameter. All completion codes in the returned DeployResult object will be 'pending' unless the value of timeToWaitMs is AttributeConstants.DEPLOYRESULT_SUPPRESSION, in which case the DeployResult will be null (as usual).
Returns:
DeployResult object that can be used to query the results of the deployment.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Config Manager.

getBrokers

public Enumeration getBrokers(Properties props)
                       throws ConfigManagerProxyPropertyNotInitializedException
Returns an enumeration of all the BrokerProxy objects that match the filter specified by the Properties argument.

Parameters:
props - Filter to select which broker proxies to return.
Returns:
Enumeration - Broker proxies that matched the supplied filter.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of available brokers could not be determined because the Config Manager did not supply the topology information to the Config Manager Proxy before a timeout occurred.

getBroker

public BrokerProxy getBroker(Properties props)
                      throws ConfigManagerProxyPropertyNotInitializedException

Returns the first BrokerProxy object that matches the filter specified by the Properties argument.

Parameters:
props - - Filter to select the broker proxy to return.
Returns:
BrokerProxy - The first object that matched the supplied filter, or null if no brokers exist.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of available brokers could not be determined because the Config Manager did not supply the topology information to the Config Manager Proxy before a timeout occurred.

getBrokerByName

public BrokerProxy getBrokerByName(String brokerName)
                            throws ConfigManagerProxyPropertyNotInitializedException
Returns the BrokerProxy object with the supplied name, or null if a broker of that name does not exist or if the supplied argument was null.

Parameters:
brokerName -
Returns:
BrokerProxy Config Manager Proxy representation of the requested broker.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of available brokers could not be determined because the Config Manager did not supply the topology information to the Config Manager Proxy before a timeout occurred.

createConnectionByName

public void createConnectionByName(String sourceName,
                                   String targetName)
                            throws ConfigManagerProxyLoggedException,
                                   ConfigManagerProxyPropertyNotInitializedException
Asks the Config Manager to create a logical connection between two brokers.

If this method is called as part of a batch of requests in which either or both of the brokers are to be renamed, the operation will fail with a ConfigManagerProxyLoggedException. Callers wishing to avoid this situation should either not use batch mode, or use createConnectionByUUID() instead.

Parameters:
sourceName - Name of the source broker
targetName - Name of the target broker
Throws:
ConfigManagerProxyLoggedException - if the request to create a connection could not be sent to the Config Manager, if either the source broker or the target broker does not exist, or if either parameter refers to a broker for which an uncommitted rename exists.
ConfigManagerProxyPropertyNotInitializedException - if a communication problem means that details of the broker names could not be supplied by the Configuration Manager.

createConnectionByUUID

public void createConnectionByUUID(String sourceUUID,
                                   String targetUUID)
                            throws ConfigManagerProxyLoggedException
Asks the Config Manager to create a logical connection between two brokers by UUID.

Parameters:
sourceUUID - UUID of the source broker
targetUUID - UUID of the target broker
Throws:
ConfigManagerProxyLoggedException - if the request to create a connection could not be sent to the Config Manager, or if either the source broker or the target broker does not exist.

deleteConnectionByName

public void deleteConnectionByName(String sourceName,
                                   String targetName)
                            throws ConfigManagerProxyLoggedException,
                                   ConfigManagerProxyPropertyNotInitializedException
Asks the Config Manager to remove a logical connection between two brokers.

If this method is called as part of a batch of requests in which either or both of the brokers are to be renamed, the operation will fail with a ConfigManagerProxyLoggedException. Callers wishing to avoid this situation should either not use batch mode, or use deleteConnectionByUUID() instead.

Parameters:
sourceName - Name of the source broker
targetName - Name of the target broker
Throws:
ConfigManagerProxyLoggedException - if the request to remove a connection could not be sent to the Config Manager, or if either the source broker or the target broker does not exist, or if either parameter refers to a broker for which an uncommitted rename exists.
ConfigManagerProxyPropertyNotInitializedException - if the Configuration Manager did not supply complete topology information, which means that the broker names could not be resolved.

deleteConnectionByUUID

public void deleteConnectionByUUID(String sourceUUID,
                                   String targetUUID)
                            throws ConfigManagerProxyLoggedException
Asks the Config Manager to remove a logical connection between two brokers.

Parameters:
sourceUUID - UUID of the source broker
targetUUID - UUID of the target broker
Throws:
ConfigManagerProxyLoggedException - if the request to remove a connection could not be sent to the Config Manager, or if either the source broker or the target broker does not exist.

createCollective

public CollectiveProxy createCollective(String name)
                                 throws ConfigManagerProxyLoggedException

Asks the Config Manager to create a collective with the supplied name.

Parameters:
name - of the new collective
Returns:
CollectiveProxy represents the new collective.
Throws:
ConfigManagerProxyLoggedException - if the request to create a collective could not be sent to the Config Manager.

deleteCollective

public void deleteCollective(String name)
                      throws ConfigManagerProxyLoggedException,
                             ConfigManagerProxyPropertyNotInitializedException

Asks the Config Manager to remove the collective with the supplied name from the Topology workspace.

Parameters:
name - Name of the collective to remove from the topology.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the collective with the supplied name could not be found because the Configuration Manager has not supplied complete topology information.
ConfigManagerProxyLoggedException - if a collective with the supplied name does not exist, or if the request to delete the collective could not be sent to the Config Manager.

getCollectives

public Enumeration getCollectives(Properties props)
                           throws ConfigManagerProxyPropertyNotInitializedException
Returns an enumeration of all the CollectiveProxy objects that match the filter specified by the Properties argument.

Parameters:
props - Filter to select which collective proxies to return.
Returns:
Enumeration The CollectiveProxy objects which matched the supplied filter. If no matches were found, the Enumeration will be empty.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the collectives information could not be determined because the topology information has not yet been supplied.

getCollective

public CollectiveProxy getCollective(Properties props)
                              throws ConfigManagerProxyPropertyNotInitializedException
Returns the first CollectiveProxy object that matches the filter specified by the Properties argument. If multiple matches are found, an arbitrary match is returned. If no matches are found, null is returned.

Parameters:
props - Filter to select the collective proxy to return.
Returns:
CollectiveProxy The first object that matched the supplied filter.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of available brokers could not be determined because the Config Manager has not yet supplied the topology information.

getCollectiveByName

public CollectiveProxy getCollectiveByName(String collectiveName)
                                    throws ConfigManagerProxyPropertyNotInitializedException
Returns the CollectiveProxy object with the supplied name, or null if a collective of that name does not exist or if the supplied argument was null.

Parameters:
collectiveName -
Returns:
CollectiveProxy Config Manager Proxy representation of the requested collective.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of available collectives could not be determined because the Config Manager did not supply the topology information to the Config Manager Proxy before a timeout occurred.

getConnections

public Enumeration getConnections()
                           throws ConfigManagerProxyPropertyNotInitializedException
Returns an enumeration of all TopologyProxy.Connection objects.

Returns:
Enumeration of TopologyProxy.Connection objects.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list could not be determined because the Config Manager has not yet supplied the topology information.

getNumberOfConnections

public int getNumberOfConnections(String brokerUUID)
                           throws ConfigManagerProxyPropertyNotInitializedException
Returns the number of Connection objects in the topology, or that involve the broker with the supplied UUID.

Parameters:
brokerUUID - UUID of the broker to match, or null to return the number of connection objects in the topology.
Returns:
int Number of connections
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list of could not be determined because the Config Manager has not yet supplied the topology information.

getNumberOfConnections

public int getNumberOfConnections()
                           throws ConfigManagerProxyPropertyNotInitializedException
Returns the number of Connection objects in the topology.

Returns:
int Number of connections
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list could not be determined because the Config Manager has not yet supplied the topology information.

getConnections

public Enumeration getConnections(String brokerUUID)
                           throws ConfigManagerProxyPropertyNotInitializedException
Returns an enumeration of TopologyProxy.Connection objects that affect the broker with the supplied UUID

Parameters:
brokerUUID - UUID of the broker whose connections are to be returned. If this parameter is null or blank, all known connections in the topology are returned.
Returns:
Enumeration of TopologyProxy.Connection objects.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the list could not be determined because the Config Manager has not yet supplied the topology information.

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.

toString

public String toString()
Displays the name of the object

Overrides:
toString in class AdministeredObject
Returns:
String Representation of the current object

WBI BrokersTM
Config Manager Proxy API