WBI BrokersTM
Config Manager Proxy API

com.ibm.broker.config.proxy
Class ConfigManagerProxy

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

public class ConfigManagerProxy
extends AdministeredObject

This class allows applications to connect to and manipulate Configuration Managers. All domain objects are accessible through this one.

In order to use ConfigManagerProxy 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);
 

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

Responsibilities
  • Represents a container for all managed objects within a Configuration Manager's domain.
  • Each instance also represents a connection to a Configuration Manager.
  • Provides shortcuts to individual object types managed by the API, and to global Configuration Manager operations (e.g. system trace)
Internal Collaborators com.ibm.broker.config.proxy.TopologyProxy
com.ibm.broker.config.proxy.LogProxy
com.ibm.broker.config.proxy.TopicRootProxy
com.ibm.broker.config.proxy.ConfigManagerConnectionParameters
com.ibm.broker.config.proxy.SubscriptionsProxy

 Change Activity:
 -------- ----------- -------------   ------------------------------------
 Reason:  Date:       Originator:     Comments:
 -------- ----------- -------------   ------------------------------------
 f19590.1 2004-03-19  HDMPL           v6 Release

 


Method Summary
 void beginUpdates()
          Tells the ConfigManagerProxy to hold back from sending any subsequent state-changing requests to the Config Manager, so multiple requests can be later sent off in a single message (or "batch").
 void cancelDeployment()
          Tells the Configuration Manager to cancel ALL deployment actions in the domain that are currently in progress.
 void clearUpdates()
          Tells the ConfigManagerProxy to discard any state-changing requests received since the last call to beginUpdates().
 void deregisterListeners()
          Deregisters ALL external listeners associated with the current ConfigManagerProxy connection.
static void disableConfigManagerProxyTracing()
          Stops Config Manager Proxy service tracing.
 void disconnect()
          Deregisters all listeners registered to this ConfigManagerProxy instance and closes the link to the Config Manager.
static void enableConfigManagerProxyTracing(String filename)
          Enables Config Manager Proxy service tracing, sending output to the file with the supplied name.
 String getConfigManagerFullVersion()
          Returns the full version string of the Configuration Manager to which this Config Manager Proxy instance is connected.
 String getConfigManagerOSArch()
          Returns a string describing the architecture of the Configuration Manager machine to which this Config Manager Proxy is connected.
 String getConfigManagerOSName()
          Returns a string describing the name of the operating system running on the Configuration Manager machine to which this Config Manager Proxy is connected.
 String getConfigManagerOSVersion()
          Returns a string describing the version of the operation system on the Configuration Manager machine to which this Config Manager Proxy is connected.
static int getConfigManagerProxyVersion()
          Returns the version string for the Config Manager Proxy.
 int getConfigManagerVersion()
          Returns the major version identifier of the Configuration Manager to which the Config Manager Proxy is connected.
 ConfigurationObjectType getConfigurationObjectType()
          Returns the ConfigurationObjectType associated with this AdministeredObject type.
 ConfigurationObjectType getConfigurationObjectTypeOfParent()
          Returns the ConfigurationObjectType associated with the logical parent of this AdministeredObject type.
static ConfigManagerProxy getInstance(ConfigManagerConnectionParameters cmcp)
          Asks the Config Manager Proxy to connect to a Configuration Manager with the supplied parameters.
 LogProxy getLog()
          Asks the Configuration Manager to register for all log records associated with the current user, through a LogProxy instance.
 SubscriptionsProxy getSubscriptions(String topic, String brokers, String users, String subscriptionsPoints, GregorianCalendar startDate, GregorianCalendar endDate)
          Generates a SubscriptionsProxy that represents those subscriptions fulfilling the supplied criteria.
 TopicRootProxy getTopicRoot()
          Returns the RootTopicProxy object associated with this Config Manager.
 TopologyProxy getTopology()
          Returns the TopologyProxy object associated with this Config Manager.
 boolean isBatching()
          Returns true if and only if the creation of a batch is currently in progress.
 boolean isIncompatible()
          Returns true if and only if the Config Manager Proxy has received a message from the Configuration Manager which indicates that the Configuration Manager is unable to process requests from this Config Manager Proxy because the versions are not compatible.
 boolean isIncompatible(boolean waitIfNotUpdated)
          Returns true if and only if the Config Manager Proxy has received a message from the Configuration Manager which indicates that the Configuration Manager is unable to process requests from this Config Manager Proxy because the versions are not compatible.
 void sendUpdates()
          Tells the ConfigManagerProxy to send to the Config Manager all requests received since the beginUpdates() call.
 void sendUpdates(int correlationID)
          Tells the ConfigManagerProxy to send to the Config Manager all requests received since the beginUpdates() call.
static void setLogger(String className)
          If directed to gather Config Manager Proxy trace for IBM service, do not use this method - use enableTracing(String) and disableTracing() instead.
static void setLogger(String className, String params)
          Initializes a Config Manager Proxy logger.
static void setRetryCharacteristics(int maxRetries, int baseRetryWaitTime, int retryWaitTimeIncrement)
          Sets the retry characteristics for the Config Manager Proxy.
static void setRetryCharacteristics(long maxWaitTimeMs)
          Sets the retry characteristics for the Config Manager Proxy.
 void startDebugSystemTrace()
          Asks the Configuration Manager to start debug system trace.
 void startSystemTrace()
          Asks the Configuration Manager to start system trace.
 void stopSystemTrace()
          Asks the Configuration Manager to stop system trace.
 String toString()
          Displays the name of the object
static Properties withUUID(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 subclass of AdministeredObject being used.
 
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
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getInstance

public static ConfigManagerProxy getInstance(ConfigManagerConnectionParameters cmcp)
                                      throws ConfigManagerProxyLoggedException
Asks the Config Manager Proxy to connect to a Configuration Manager with the supplied parameters. The sole parameter to getInstance() is a ConfigManagerConnectionParameters object, of which there are two implementors currently:

Parameters:
cmcp - An object describing the transport to use, and any connection parameters required, to connect to the Configuration Manager.
Returns:
ConfigManagerProxy a object that represents an established connection to a Config Manager.
Throws:
ConfigManagerProxyLoggedException - if a connection could not be established for whatever reason.

disconnect

public void disconnect()
Deregisters all listeners registered to this ConfigManagerProxy instance and closes the link to the Config Manager. This makes client APIs unusable. After calling this method, the only way to re-establish the link to the Config Manager is by reissuing the ConfigManagerProxy.getInstance() call.


cancelDeployment

public void cancelDeployment()
                      throws ConfigManagerProxyLoggedException
Tells the Configuration Manager to cancel ALL deployment actions in the domain that are currently in progress. As a domain-wide action, this method should only be called in extreme circumstances.

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

deregisterListeners

public void deregisterListeners()
Deregisters ALL external listeners associated with the current ConfigManagerProxy connection.

Note: The same effect can be achieved by using ConfigManagerProxy.disconnect(). The difference is that this call doesn't close the link to the Config Manager- it is possible to use call this method and still make use of the APIs and the listener registration mechanism.


getTopology

public TopologyProxy getTopology()
                          throws ConfigManagerProxyPropertyNotInitializedException
Returns the TopologyProxy object associated with this Config Manager.

Returns:
TopologyProxy - a reference to the topology object associated with the Config Manager, or null if there is no topology information available in the Config Manager.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the Topology subcomponent could not be loaded because the Config Manager has not yet supplied the required information.

getConfigManagerProxyVersion

public static int getConfigManagerProxyVersion()
Returns the version string for the Config Manager Proxy.

Returns:
version

getTopicRoot

public TopicRootProxy getTopicRoot()
                            throws ConfigManagerProxyPropertyNotInitializedException
Returns the RootTopicProxy object associated with this Config Manager.

Returns:
RootTopicProxy - a reference to the root topic object associated with the Config Manager. Returns null if there is no root topic associated with this Config Manager.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the Topology subcomponent could not be loaded because the Config Manager has not yet supplied the required information.

getSubscriptions

public SubscriptionsProxy getSubscriptions(String topic,
                                           String brokers,
                                           String users,
                                           String subscriptionsPoints,
                                           GregorianCalendar startDate,
                                           GregorianCalendar endDate)
                                    throws ConfigManagerProxyLoggedException
Generates a SubscriptionsProxy that represents those subscriptions fulfilling the supplied criteria.

Parameters:
topic - Name of the topic to search, or null to search all topic names. '%' can be used within the string to denote a wildcard.
brokers - Which brokers to search, or null to search all brokers. '%' can be used within the string to denote a wildcard.
users - Which users to search, or null to search all users. '%' can be used within the string to denote a wildcard.
subscriptionsPoints - Which subscriptions points to search, or null to search all subscriptions points. '%' can be used within the string to denote a wildcard.
startDate - The earliest date to search, or null to not specify a start date.
endDate - The latest date to search, or null to not specify an end date.
Returns:
SubscriptionsProxy Object that describes the query. The object will be asynchronously populated with the matching results.
Throws:
ConfigManagerProxyLoggedException - if the request could not be sent to the Configuration Manager.

getLog

public LogProxy getLog()
                throws ConfigManagerProxyPropertyNotInitializedException
Asks the Configuration Manager to register for all log records associated with the current user, through a LogProxy instance.

Returns:
LogProxy represents all log records associated with the current user.
Throws:
ConfigManagerProxyPropertyNotInitializedException - if the Topology subcomponent could not be loaded because the Config Manager has not yet supplied the required information.

getConfigurationObjectTypeOfParent

public ConfigurationObjectType getConfigurationObjectTypeOfParent()
Returns the ConfigurationObjectType associated with the logical parent of this AdministeredObject type. As the ConfigManagerProxy is the root of the hierarchy, this method returns null.

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

setRetryCharacteristics

public static void setRetryCharacteristics(int maxRetries,
                                           int baseRetryWaitTime,
                                           int retryWaitTimeIncrement)
Sets the retry characteristics for the Config Manager Proxy. These settings are used for all ConfigManagerProxy connections in the JVM.

The Config Manager Proxy may not always have been supplied a required piece of information that is needed to perform an operation (e.g. it can't return a broker's execution group list if that broker's information has not been supplied to it by the Configuration Manager). This can happen if the proxy has a slow link to the Configuration Manager, or if the Configuration Manager is heavily burdened or just not running.

Collectively, the parameters supplied to this method represent the maximum amount of time to wait for the required information to arrive before the exception is thrown. Specifically, three parameters are required which describe how many times the Config Manager Proxy should poll incoming messages from the Configuration Manager to see if the required information has arrived. The three parameters are: the number of times to retry, the initial amount of time to wait between failure (in milliseconds) and the amount of time to increase the wait time by on successive failure (again in milliseconds).

So supplying (10,1000,1000) to this method (which happens to be the default) means that retries will occur one, two, four, seven, eleven seconds after the first failure (and so on). If the required information still cannot be found after the number of maxRetries is exhausted, a ConfigManagerProxyPropertyNotInitializedException will be thrown to the calling application.

Parameters:
maxRetries - the maximum number of consecutive failures before an exception is thrown to the calling application.
baseRetryWaitTime - The initial time to wait between retries (in milliseconds)
retryWaitTimeIncrement - How much to increase the retry wait time by after each consecutive failure.

setRetryCharacteristics

public static void setRetryCharacteristics(long maxWaitTimeMs)
Sets the retry characteristics for the Config Manager Proxy. These settings are used for all ConfigManagerProxy connections in the JVM.

The Config Manager Proxy may not always have been supplied a required piece of information that is needed to perform an operation (e.g. it can't return a broker's execution group list if that broker's information has not been supplied to it by the Configuration Manager). This can happen if the proxy has a slow link to the Configuration Manager, or if the Configuration Manager is heavily burdened or just not running.

Parameters:
maxWaitTimeMs - the maximum length of time the Config Manager Proxy can wait for a response from the Configuration Manager before a ConfigManagerProxyPropertyNotInitalizedException is thrown.

enableConfigManagerProxyTracing

public static void enableConfigManagerProxyTracing(String filename)
                                            throws ConfigManagerProxyLoggedException
Enables Config Manager Proxy service tracing, sending output to the file with the supplied name. Enabling service trace will cause the Config Manager Proxy to work more slowly than usual.

Not to be confused with startSystemTrace() and startDebugSystemTrace(), which enables tracing of the Configuration Manager.

Parameters:
filename - File spec of the output file
Throws:
ConfigManagerProxyLoggedException - if the logger could not be instantiated.

disableConfigManagerProxyTracing

public static void disableConfigManagerProxyTracing()
Stops Config Manager Proxy service tracing.

Not to be confused with stopSystemTrace(), which enables tracing of the Configuration Manager.


setLogger

public static void setLogger(String className,
                             String params)
                      throws ConfigManagerProxyLoggedException
Initializes a Config Manager Proxy logger. If directed to gather Config Manager Proxy trace for IBM service, do not use this method - use enableConfigManagerProxyTracing(String) and disableConfigManagerProxyTracing() instead. Use startDebugSystemTrace(), startSystemTrace() and stopSystemTrace() to control Configuration Manager tracing. Use MessageFlowProxy.setUserTrace() to control tracing of message flows.

Parameters:
className - Fully qualified name of the logger class (must extend com.ibm.broker.config.proxy.Logger) A null or blank value here will disable logging.
params - any parameters required by the logger
Throws:
ConfigManagerProxyLoggedException - if the logger could not be instantiated.

setLogger

public static void setLogger(String className)
                      throws ConfigManagerProxyLoggedException
If directed to gather Config Manager Proxy trace for IBM service, do not use this method - use enableTracing(String) and disableTracing() instead. Use startDebugSystemTrace(), startSystemTrace() and stopSystemTrace() to control Configuration Manager tracing. Use MessageFlowProxy.setUserTrace() to control tracing of message flows.

This method sets up an logger that does not require parameters.

Parameters:
className - Fully qualified name of the logger class (must extend com.ibm.broker.config.proxy.Logger). A null or blank value here will disable logging.
Throws:
ConfigManagerProxyLoggedException - if the logger could not be instantiated.

beginUpdates

public void beginUpdates()
                  throws ConfigManagerProxyLoggedException
Tells the ConfigManagerProxy to hold back from sending any subsequent state-changing requests to the Config Manager, so multiple requests can be later sent off in a single message (or "batch"). Requests for information (for instance, requests to discover an object's attributes) will not be batched. The scope of this method is for any requests using this ConfigManagerProxy connection to the Configuration Manager.

Throws:
ConfigManagerProxyLoggedException - - if a batch is already in progress.
See Also:
sendUpdates(), clearUpdates(), isBatching()

sendUpdates

public void sendUpdates()
                 throws ConfigManagerProxyLoggedException
Tells the ConfigManagerProxy to send to the Config Manager all requests received since the beginUpdates() call. After this method completes, subsequent requests will not be batched unless another beginUpdates() is called.

Throws:
ConfigManagerProxyLoggedException - If a batch was not in progress, if the batch contained no requests, or if the request could not be sent to the Config Manager.
See Also:
beginUpdates(), clearUpdates(), isBatching()

sendUpdates

public void sendUpdates(int correlationID)
                 throws ConfigManagerProxyLoggedException
Tells the ConfigManagerProxy to send to the Config Manager all requests received since the beginUpdates() call. After this method completes, subsequent requests will not be batched unless another beginUpdates() is called.

Parameters:
correlationID - Identifier that will accompany any actionresponse messages sent back to the caller through the AdministeredObjectListener interface.
Throws:
ConfigManagerProxyLoggedException - if a batch was not in progress, if the batch contained no requests or if the request could not be sent to the Config Manager.
See Also:
beginUpdates(), sendUpdates(), clearUpdates(), isBatching()

clearUpdates

public void clearUpdates()
Tells the ConfigManagerProxy to discard any state-changing requests received since the last call to beginUpdates(). If a batch was not in progress, or if the current batch has already been submitted using sendUpdates(), this call does nothing.

See Also:
beginUpdates(), sendUpdates(), isBatching()

isBatching

public boolean isBatching()
Returns true if and only if the creation of a batch is currently in progress.

Returns:
boolean status of batch mode
See Also:
beginUpdates(), sendUpdates(), clearUpdates()

isIncompatible

public boolean isIncompatible()
Returns true if and only if the Config Manager Proxy has received a message from the Configuration Manager which indicates that the Configuration Manager is unable to process requests from this Config Manager Proxy because the versions are not compatible. If the ConfigManagerProxy object has not yet received any update from the Config Manager, the call will block until the first response (e.g. 'Proxy is incompatible' message) is received (or the timeout configured in ConfigManagerProxy.setRetryCharacteristics() occurs).

Note that the timeout condition will result in the response of false being returned, correctly indicating that no 'object-restricted' response has been received. Callers wishing to programmatically detect the timeout condition should use hasBeenUpdatedByConfigManager(true).

Returns:
boolean true if and only if the Configuration Manager is unable to successfully communicate with this Proxy.

isIncompatible

public boolean isIncompatible(boolean waitIfNotUpdated)
Returns true if and only if the Config Manager Proxy has received a message from the Configuration Manager which indicates that the Configuration Manager is unable to process requests from this Config Manager Proxy because the versions are not compatible.

Parameters:
waitIfNotUpdated - If this is set to true and the administered object has not yet received an update from the Config Manager, the call will block until the first response (e.g. the 'Proxy is incompatible' message) is received (or the timeout configured in ConfigManagerProxy.setRetryCharacteristics() occurs). This parameter allows the caller to ensure correctness of the returned value (if the value of the incompatible flag is sought before the first response from the Config Manager has necessarily been returned, the method may confusingly return 'false' even though the Config Manager is not compatible).
Returns:
boolean true if and only if the Configuration Manager is unable to successfully communicate with this Proxy because of a version incompatibility.

startSystemTrace

public void startSystemTrace()
                      throws ConfigManagerProxyLoggedException
Asks the Configuration Manager to start system trace. Not to be confused with enableTracing(), which enables tracing of the Config Manager Proxy application.

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

stopSystemTrace

public void stopSystemTrace()
                     throws ConfigManagerProxyLoggedException
Asks the Configuration Manager to stop system trace. Not to be confused with disableTracing(), which enables tracing of the Config Manager Proxy application.

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

startDebugSystemTrace

public void startDebugSystemTrace()
                           throws ConfigManagerProxyLoggedException
Asks the Configuration Manager to start debug system trace.

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

getConfigManagerVersion

public int getConfigManagerVersion()
                            throws ConfigManagerProxyPropertyNotInitializedException
Returns the major version identifier of the Configuration Manager to which the Config Manager Proxy is connected. The returned value will be one of the following:

getConfigManagerFullVersion

public String getConfigManagerFullVersion()
                                   throws ConfigManagerProxyPropertyNotInitializedException
Returns the full version string of the Configuration Manager to which this Config Manager Proxy instance is connected. The format of the string is not guaranteed.

If the Config Manager Proxy is connected to a Configuration Manager of less than v6 level, this method returns null.

Returns:
String full version
Throws:
ConfigManagerProxyNotInitializedException - if the version information was not supplied by the Configuration Manager before a timeout occurred.
ConfigManagerProxyPropertyNotInitializedException

getConfigManagerOSName

public String getConfigManagerOSName()
                              throws ConfigManagerProxyPropertyNotInitializedException
Returns a string describing the name of the operating system running on the Configuration Manager machine to which this Config Manager Proxy is connected. The returned value is the value of the 'os.name' system property in the Configuration Manager.

If the Config Manager Proxy is connected to a Configuration Manager of less than v6 level, this method returns null.

Returns:
String system property
Throws:
ConfigManagerProxyNotInitializedException - if the required information was not supplied by the Configuration Manager before a timeout occurred.
ConfigManagerProxyPropertyNotInitializedException

getConfigManagerOSArch

public String getConfigManagerOSArch()
                              throws ConfigManagerProxyPropertyNotInitializedException
Returns a string describing the architecture of the Configuration Manager machine to which this Config Manager Proxy is connected. The returned value is the value of the 'os.arch' system property in the Configuration Manager.

If the Config Manager Proxy is connected to a Configuration Manager of less than v6 level, this method returns null.

Returns:
String system property
Throws:
ConfigManagerProxyNotInitializedException - if the required information was not supplied by the Configuration Manager before a timeout occurred.
ConfigManagerProxyPropertyNotInitializedException

getConfigManagerOSVersion

public String getConfigManagerOSVersion()
                                 throws ConfigManagerProxyPropertyNotInitializedException
Returns a string describing the version of the operation system on the Configuration Manager machine to which this Config Manager Proxy is connected. The returned value is the value of the 'os.version' system property in the Configuration Manager.

If the Config Manager Proxy is connected to a Configuration Manager of less than v6 level, this method returns null.

Returns:
String system property
Throws:
ConfigManagerProxyNotInitializedException - if the required information was not supplied by the Configuration Manager before a timeout occurred.
ConfigManagerProxyPropertyNotInitializedException

withUUID

public static Properties withUUID(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 subclass of AdministeredObject being used. This provides an easy way of supplying filters to the get*() methods. For example, broker1.getExecutionGroup(ExecutionGroup.withUUID("1234")); will return the Execution Group with UUID "1234" that exists in broker1.

Parameters:
uuid - property to set
Returns:
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.

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