com.ibm.broker.config.proxy

Class AdministeredObject

java.lang.Object

com.ibm.broker.config.proxy.AdministeredObject

Direct Known Subclasses:

ActivityLogProxy, AdminQueueEntry, AdminQueueProxy, BrokerProxy, CollectiveProxy, ConfigManagerProxy, DataCaptureProxy, DeployedObjectGroupProxy, LogProxy, MessageFlowProxy, PolicyManagerProxy, PolicyProxy, ResourceManagerProxy, ServiceFederationManagerProxy, SubscriptionsProxy, TopicProxy, TopologyProxy, WebAdminProxy, WebUserProxy

public abstract class AdministeredObject
extends java.lang.Object

This is the abstract superclass from which most representations of broker objects inherit. The class provides a set of methods common to all these types, such as the setting and getting of common attributes and the ability to traverse and manipulate the object hierarchy. The recommended approach to working with broker objects is similar for all AdministeredObject types:

1. The calling application asks for a reference to the AdministeredObject. Note that ExecutionGroupProxy is a subclass of AdministeredObject.
   

       ExecutionGroupProxy e = b.getExecutionGroupByName("myEG");

2. At this point, the IBM Integration API (CMP) will ask the broker for details of the requested object, and asks it to keep the IBM Integration API (CMP) informed of any subsequent changes to the object. While this communication takes place, the caller may work with the administered object returned to it, although if the caller asks for information which is not yet available to the IBM Integration API (CMP) (because the broker has not yet supplied it) a pause may occur while the requested information is obtained. An example of information being requested is:
   

        boolean showGreenLight = e.isRunning();
    

3. The caller may wish to change properties of the AdministeredObject. Properties include persistent configurational characteristics of the object (such as its description) as well as operational characteristics (such as whether it is running):
   

        e.setShortDescription("Test execution group");
        e.startMessageFlows();
    

   The broker processes these requests asynchronously. In order to benefit from the flexibility of this asynchronous design, methods to change these properties will return to the caller as soon as the requests are sent to the broker, not when they have been necessarily processed. Applications must interrogate the time and value of the last completion code (getTimeOfLastCompletionCode() and getLastCompletionCode() respectively) to determine when requests have completed, or (preferably) use the AdministeredObjectListener mechanism. For methods that initiate deployment, a third option is to instruct the IBM Integration API (CMP) to only return when a response to the deployment has been successfully received from the affected broker.
   

        DeployResult dr = e.deploy(barFile, isIncremental, 60 * 1000); // wait up to one minute
        if (dr.getCompletionCode() == CompletionCodeType.success) {
            // broker has responded successfully
        }
    

4. In order to receive notifications when requests are processed by the broker, and also to be told of other changes to the object, the caller can register user-written implementors of AdministeredObjectListener to the IBM Integration API (CMP):
   

        AdministeredObjectListener myListener = new MyAdministeredObjectListener();
        // Interested in changes to execution group 'e'
        e.registerListener( myListener );
    

5. When finished with the object, the caller must first deregister any previously registered listeners.
   

        // After this call, myListener will no longer be informed of any changes to 'e'.
        e.deregisterListener( myListener );
    

6. As with all other Java objects, AdministeredObjects can go out of scope. At some unspecified point in time after this happens, an internal thread is notified by the JVM that this has taken place, and the IBM Integration API (CMP) then tidies up any resources associated with the object and asks the broker to unsubscribe the application from further notifications regarding the object. If the application wishes to make use of an administered object after it has been deregistered from updates from the broker, the process restarts from step one.
   
   

   Note that AdministeredObjects that have AdministeredObjectListener instances registered will not get tidied in this way until either they are deregistered, the application is disconnected from the broker or the application ends.

com.ibm.broker.config.proxy.AdministeredObject
Responsibilities	Provides a means of manipulating arbitrary managed objects within the broker. This includes object creation, object deletion, object modification, and listener registration/deregistration. Instances are responsible for maintaining information about the objects they represent locally. AdministeredObjects have a collection of String based properties that describe the object's attributes, such as their name, and also any managed subcomponents of the AdministeredObject- for example, execution groups within a broker. AdministeredObjects may have listeners registered against them, which are informed of any changes to the AdministeredObject's state.
Internal Collaborators	com.ibm.broker.config.proxy.AdministeredObjectListener

 Change Activity:
 -------- ----------- -------------   ------------------------------------
 Reason:  Date:       Originator:     Comments:
 -------- ----------- -------------   ------------------------------------
 f25103.1 2004-03-18  HDMPL           v6 Release
 45112.7  2007-07-30  HDMPL           v6.1 release:
                                         Methods now return genericized types where relevant
                                         Added isAwaitingSubmissionForDeletion()
                                         Added getManagedSubcomponentsAsStrings(Properties, Properties)
                                         Added getManagedSubcomponentsAsStrings(Properties)
                                         Deprecated getManagedSubcomponents(Properties, boolean, Properties)
                                         Deprecated getManagedSubcomponents(Properties, boolean)
 51619.6  2008-11-27  HDMPL           v7 release:                                        
                                         Added hasBeenPopulatedByBroker()
 80006    2011-05-13  HDCAB           v8 release:                                        
                                         Added equals() method.
IC97070   2013-11-12  naishm          v8 CMP DEPLOYMENT SOMETIMES GOES TO THE WRONG EXECUTION GROUP

 

Method Summary

Methods

Modifier and Type	Method and Description
void	deregisterListener(AdministeredObjectListener listener) Asks the IBM Integration API (CMP) to unsubscribe a previously registered AdministeredObjectListener, given the listener instance that was supplied during registration.
void	deregisterListener(AdvancedAdministeredObjectListener listener) Asks the IBM Integration API (CMP) to unsubscribe a previously registered AdvancedAdministeredObjectListener, given the listener instance that was supplied during registration.
int	elements(java.lang.String key) For groups of attributes (such as subcomponents) this method returns the largest number for which an attribute exists in the current object.
boolean	equals(java.lang.Object obj) Compares this AdministeredObject with the Object passed in.
java.util.Properties	getAdvancedProperties() Returns a filtered list of the properties table associated with the current object, filtered to advanced properties only.
java.util.Properties	getBasicProperties() Returns a filtered list of the properties table associated with the current object, filtered to basic properties only.
abstract ConfigurationObjectType	getConfigurationObjectType() Returns the ConfigurationObjectType associated with this AdministeredObject type.
abstract ConfigurationObjectType	getConfigurationObjectTypeOfParent() Returns the ConfigurationObjectType associated with the logical parent of this AdministeredObject type.
java.util.Vector<LogEntry>	getLastBIPMessages() Returns the last vector of BIP messages that are associated with this object.
CompletionCodeType	getLastCompletionCode() Returns the completion code of the last operation that was performed by this connection to the broker on the object that this AdministeredObject represents.
java.lang.String	getLastUpdateUser() Deprecated. The property that describes which user last made a change is not used as of WebSphere Message Broker V7. Use the Administration Log (LogProxy) to discover which changes have been made by which user.
java.lang.String	getLongDescription() Returns the long description field for the current AdministeredObject.
AdministeredObject	getManagedSubcomponent(java.util.Properties props) Returns the first object that has the requested properties.
AdministeredObject	getManagedSubcomponentFromStringRepresentation(java.lang.String representation) Returns the object which has the current object as a parent that has the supplied string representation.
java.util.Enumeration<AdministeredObject>	getManagedSubcomponents(java.util.Properties filter) Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker).
java.util.Enumeration<?>	getManagedSubcomponents(java.util.Properties filter, boolean returnContainsStrings) Deprecated. Because the returned Enumeration cannot be checked for type-safety, this method should no longer be used. To return an enumeration of AdministeredObject subcomponents, use getManagedSubcomponents(Properties). To return an enumeration of strings, use the method getManagedSubcomponentsAsStrings(Properties).
java.util.Enumeration<?>	getManagedSubcomponents(java.util.Properties filter, boolean returnContainsStrings, java.util.Properties initialPropertiesOfNewObject) Deprecated. Because the returned Enumeration cannot be checked for type-safety, this method should no longer be used. To return an enumeration of AdministeredObject subcomponents, use getManagedSubcomponents(Properties, Properties). To return an enumeration of strings, use the method getManagedSubcomponentsAsStrings(Properties, Properties).
java.util.Enumeration<AdministeredObject>	getManagedSubcomponents(java.util.Properties filter, java.util.Properties initialPropertiesOfNewObject) Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker).
java.util.Enumeration<java.lang.String>	getManagedSubcomponentsAsStrings(java.util.Properties filter) Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker).
java.util.Enumeration<java.lang.String>	getManagedSubcomponentsAsStrings(java.util.Properties filter, java.util.Properties initialPropertiesOfNewObject) Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker).
java.lang.String	getName() Returns the name of the object
int	getNumberOfSubcomponents() Returns the number of subcomponents that are directly owned by this object.
AdministeredObject	getParent() Returns the AdministeredObject that logically owns this object.
java.util.Properties	getProperties() Returns a clone of the properties table associated with the current object.
java.lang.String	getProperty(java.lang.String key) Returns the local value of the supplied attribute.
java.lang.String	getProperty(java.lang.String key, boolean waitIfNotAvailable) Returns the local value of the supplied attribute.
java.lang.String	getProperty(java.lang.String key, int element) For properties that end in a number (for example, subcomponent properties) this method returns the value of the property that ends in the supplied number, waiting if the information is not available.
java.lang.String	getProperty(java.lang.String key, int element, boolean waitIfNotAvailable) For properties that end in a number (for example, subcomponent properties) this method returns the value of the property that ends in the supplied number, optionally waiting if the information is not available.
java.util.Date	getRepositoryTimestamp() Deprecated. As of WebSphere Message Broker V7, there is no configuration repository and so this method is no longer used. The effects of invoking it are not defined.
java.lang.String	getShortDescription() Helper method to return the short description field for the Administered Object.
java.util.GregorianCalendar	getTimeOfLastCompletionCode() Returns the time that the completion code field was last updated, as a result of a request that was sent out by this connection to the broker.
java.util.GregorianCalendar	getTimeOfLastUpdate() Returns the time that the object was last updated by a broker.
java.lang.String	getType() Convenience method to return the type of this administered object.
java.lang.String	getUUID() Convenience method to return the unique identifier of this administered object.
boolean	hasBeenPopulatedByBroker() Returns true if and only if this object handle has received at least one update publication from the connected broker.
boolean	hasBeenPopulatedByBroker(boolean waitIfNotUpdated) Returns true if and only if this object handle has received at least one update publication from the connected broker.
boolean	hasBeenRestrictedByBroker() This method returns true if and only if the IBM Integration API (CMP) has been told by the broker that the object cannot be viewed by the current user.
boolean	hasBeenRestrictedByBroker(boolean waitIfNotUpdated) This method returns true if and only if the IBM Integration API (CMP) has been told by the broker that the object cannot be viewed by the current user.
boolean	hasBeenRestrictedByConfigManager() Deprecated. As of WebSphere Message Broker V7, Configuration Managers are not used. Use hasBeenRestrictedByBroker() to determine if a broker has prevented the application from viewing the AdministeredObject.
boolean	hasBeenRestrictedByConfigManager(boolean waitIfNotUpdated) Deprecated. As of WebSphere Message Broker V7, Configuration Managers are not used.
boolean	hasBeenUpdatedByConfigManager() Deprecated. As this method can also be used to determine whether objects have been updated when connected directly to a broker, this method's name is no longer accurate. Use hasBeenPopulatedByBroker() instead. This method will return the same value as hasBeenPopulatedByBroker().
boolean	hasBeenUpdatedByConfigManager(boolean waitIfNotUpdated) Deprecated. As this method can also be used to determine whether objects have been updated when connected directly to a broker, this method's name is no longer accurate. Use hasBeenPopulatedByBroker(boolean) instead. This method will return the same value as hasBeenPopulatedByBroker(boolean).
boolean	isAwaitingSubmissionForCreation() Returns true if and only if the current object has been created as part of the current batch, but the batch has not yet been sent to the broker.
boolean	isAwaitingSubmissionForDeletion() Returns true if and only if the current object has been deleted as part of the current batch, but the batch has not yet been sent to the broker.
boolean	isDeployed() Deprecated. As of WebSphere Message Broker V7, this method is not relevant as the Configuration Manager is no longer used. The effects of calling this method are no longer defined.
boolean	isShared() Deprecated. As of WebSphere Message Broker V7, this method is not relevant as the Configuration Manager is no longer used. The effects of calling this method are no longer defined.
void	refresh() Forces this AdministeredObject to reregister itself with the broker and to re-receive the object's complete set of attributes.
void	registerListener(AdministeredObjectListener listener) Asks the broker to keep the caller informed of any changes to the current AdministeredObject.
void	registerListener(AdvancedAdministeredObjectListener listener) Asks the broker to keep the caller informed of any changes to the current AdministeredObject.
void	registerListener(AdvancedAdministeredObjectListener listener, boolean sendNotificationImmediately, java.lang.Object nextNotificationCorrelationID) Asks the broker to keep the caller informed of any changes to the current AdministeredObject, and ask to be provided with advanced notifications.
void	setLongDescription(java.lang.String desc) Sets the long description field of the current AdministeredObject.
void	setName(java.lang.String name) Sets the name of the current AdministeredObject.
void	setProperties(java.util.Properties suppliedProps) Asks the broker to update a set of properties for the current object.
void	setShortDescription(java.lang.String desc) Sets the short description field of the current AdministeredObject.
java.lang.String	toString() Displays the type and UUID of the current object (or the name if it is available).
java.lang.String	toVerboseString() Displays the list of all properties currently associated with this administered object.
void	unsubscribeFromConfigurationManagerUpdates() Deprecated. Because the Configuration Manager is no longer used, this method is not used as of WebSphere Message Broker V7. The effects of invoking it are no longer defined.
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 subclass of AdministeredObject being used.
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 (for subclass implementations) the type attribute to be the name of the subclass of AdministeredObject being used.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

registerListener

public void registerListener(AdministeredObjectListener listener)

Asks the broker to keep the caller informed of any changes to the current AdministeredObject.

The listener will only be invoked after a message from the broker is received by the IBM Integration API (CMP) that states the current object has been modified or deleted, or if a previous action involving this object and originated by this application has been completed.

In order to register listeners against multiple AdministeredObjects, user applications must call registerListener() for each object for which it wishes to receive notifications.

Parameters:

listener - the object that will be notified of any events on the current AdministeredObject.

registerListener

public void registerListener(AdvancedAdministeredObjectListener listener,
                    boolean sendNotificationImmediately,
                    java.lang.Object nextNotificationCorrelationID)

Asks the broker to keep the caller informed of any changes to the current AdministeredObject, and ask to be provided with advanced notifications.

Most applications will not need to use the information provided by the AdvancedAdministeredObjectListener and should therefore not call this method to register their listeners. Use registerListener(AdministeredObjectListener) if possible.

The listener will only be invoked after a message from the broker is received by the IBM Integration API (CMP) that states the current object has been modified or deleted, or if a previous action involving this object and originated by this application has been completed.

In order to register listeners against multiple AdministeredObjects, user applications must call registerListener() for each object for which it wishes to receive notifications.

Each AdvancedAdministeredObjectListener instance can have at most one correlationID for each AdministeredObject for which it is registered.

Note: If the caller sets sendNotificationImmediately to false AND the object has not yet received its complete set of attributes from the broker, this method will pause until the complete attribute list has been provided; this is done in order to establish a viable baseline from which 'changed attributes' list can be calculated. In this case, if the complete attribute list is not provided by the time the configured timeout occurs, the first processModify() message for this object may include the complete set of attributes for the AdministeredObject when the attribute list finally does arrive.

Parameters:

listener - the object that will be notified of any events

sendNotificationImmediately - If false, processModify() will only ever be called upon receipt of a modification message from the broker. If true, the method will additionally be called as soon as the listener is registered. This special notification will contain information on all of the object's attributes.

nextNotificationCorrelationID - This is used to group together listeners that share notification information. Specifically, when a 'modify' or 'delete' notification occurs, advanced listeners are told an approximate time till the next notification to a listener with the same correlation identifier is expected. Specify null here to not use a correlation identifier for this listener.

registerListener

public void registerListener(AdvancedAdministeredObjectListener listener)

Asks the broker to keep the caller informed of any changes to the current AdministeredObject.

The listener will only be invoked after a message from the broker is received by the IBM Integration API (CMP) that states the current object has been modified or deleted, or if a previous action involving this object and originated by this application has been completed.

In order to register listeners against multiple AdministeredObjects, user applications must call registerListener() for each object for which it wishes to receive notifications.

After a successful completion of this call, no "object modified" notification will be sent to the listener until the next time a modification happens to occur on the object. Listeners that wish to receive an immediate notification (e.g. to provide a baseline for any future deltas) must call registerListener(listener, true, *) instead.

Parameters:

listener - the object that will be notified of any events on the current AdministeredObject.

unsubscribeFromConfigurationManagerUpdates

public void unsubscribeFromConfigurationManagerUpdates()

Deprecated. Because the Configuration Manager is no longer used, this method is not used as of WebSphere Message Broker V7. The effects of invoking it are no longer defined.

deregisterListener

public void deregisterListener(AdministeredObjectListener listener)

Asks the IBM Integration API (CMP) to unsubscribe a previously registered AdministeredObjectListener, given the listener instance that was supplied during registration.

If the supplied listener was registered with this AdministeredObject more than once, all registrations will be removed.

If the supplied listener has not been registered with this administered object then this method does nothing.

Parameters:

listener - the object that will no longer be notified of any events

deregisterListener

public void deregisterListener(AdvancedAdministeredObjectListener listener)

Asks the IBM Integration API (CMP) to unsubscribe a previously registered AdvancedAdministeredObjectListener, given the listener instance that was supplied during registration.

If the supplied listener was registered with this AdministeredObject more than once, all registrations will be removed.

If the supplied listener has not been registered with this administered object then this method does nothing.

Parameters:

listener - the object that will no longer be notified of any events

setProperties

public void setProperties(java.util.Properties suppliedProps)
                   throws ConfigManagerProxyLoggedException

Asks the broker to update a set of properties for the current object. It is not usually necessary to call this method directly, as helper methods exist for most properties that you might choose to set.

The broker will be asked to set all properties for which a key exists in the supplied Properties object, to the values associated with each key. For example:

 Properties p = new Properties();
 p.setProperty(AttributeConstants.SHORT_DESCRIPTION_PROPERTY, "hi");
 p.setProperty(AttributeConstants.LONG_DESCRIPTION_PROPERTY, "hello");
 broker1.setProperties(p);

will attempt to set the short and long description of the AdministeredObject described by broker1.

By default, a successful return from this method means that the request has been sent to the broker, and callers should use AdministeredObjectListener instances to discover the results of this request. However:

• If synchronous updates have been enabled through a prior call to the BrokerProxy.setSynchronous() method, this method will only return successfully once it has been successfully processed by the broker. If the request is rejected by the broker, or if no response is received before a timeout occurs, a ConfigManagerProxyRequestTimeoutException or ConfigManagerProxyRequestFailureException will be thrown.
• If batching has been enabled through a prior call to the BrokerProxy.beginUpdates() method, this method will return successfully once the property change request has been added to the current batch.
• If both synchronous updates and batching have been enabled, the method will return successfully once the property change request has been added to the current batch.

Parameters:

suppliedProps - the properties that the caller wishes to set.

Throws:

ConfigManagerProxyLoggedException - if the request could not be sent to the broker, or (only if synchronous updates have been enabled) the request was not successfully processed by the broker.

ConfigManagerProxyRequestTimeoutException - if synchronous updates have been enabled and a response was not received by the broker before a timeout occurred. (Note that this exception type extends ConfigManagerProxyLoggedException).

ConfigManagerProxyRequestFailureException - if synchronous updates have been enabled and the request was rejected by the broker. (Note that this exception type extends ConfigManagerProxyLoggedException).

getProperties

public java.util.Properties getProperties()

Returns a clone of the properties table associated with the current object. Modifying any properties in the returned object will not modify the object itself, unless it is subsequently supplied to the setProperties() method.

As of WebSphere Message Broker V7, this method will pause until the object has received at least one update from the broker. If an update is not received before the timeout specified in BrokerProxy.setRetryCharacteristics() is reached, AdministeredObject.hasBeenPopulatedByBroker() will return false and the returned Properties object will contain a much smaller set of properties, that the IBM Integration API (CMP) has derived from other sources.

Returns:

Properties where each key contains a String based property name for the current object and each value contains the property's value. All keys, and selected values, are defined in the AttributeConstants interface.

getBasicProperties

public java.util.Properties getBasicProperties()
                                        throws ConfigManagerProxyPropertyNotInitializedException

Returns a filtered list of the properties table associated with the current object, filtered to basic properties only. Modifying any properties in the returned object will not modify the object itself, unless it is subsequently supplied to the setProperties() method.

This method will pause until the object has received at least one update from the broker. If an update is not received before the timeout specified in BrokerProxy.setRetryCharacteristics() is reached, AdministeredObject.hasBeenPopulatedByBroker() will return false and the returned Properties object will contain a much smaller set of properties, that the IBM Integration API (CMP) has derived from other sources.

Returns:

Properties where each key contains a String based property name for the current object and each value contains the property's value. Only keys which apply to the current property, and not its children are returned. Only basic properties are returned, for more properties use getAdvancedProperties()

Throws:

ConfigManagerProxyPropertyNotInitializedException

getAdvancedProperties

public java.util.Properties getAdvancedProperties()
                                           throws ConfigManagerProxyPropertyNotInitializedException

Returns a filtered list of the properties table associated with the current object, filtered to advanced properties only. Modifying any properties in the returned object will not modify the object itself, unless it is subsequently supplied to the setProperties() method.

This method will pause until the object has received at least one update from the broker. If an update is not received before the timeout specified in BrokerProxy.setRetryCharacteristics() is reached, AdministeredObject.hasBeenPopulatedByBroker() will return false and the returned Properties object will contain a much smaller set of properties, that the IBM Integration API (CMP) has derived from other sources.

Returns:

Properties where each key contains a String based property name for the current object and each value contains the property's value. Only keys which apply to the current property, and not its children are returned. Only advanced properties are returned, for more properties use getBasicProperties()

Throws:

ConfigManagerProxyPropertyNotInitializedException

getManagedSubcomponents

public java.util.Enumeration<AdministeredObject> getManagedSubcomponents(java.util.Properties filter)
                                                                  throws ConfigManagerProxyPropertyNotInitializedException

Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker). This method takes a Properties object which will be used to filter the results, to allow commands of the form "give me all the execution groups with the following property". The enumeration will only contain those objects that are accessible to the current user.

For example:

 Properties p = new Properties();
 p.setProperty(AttributeConstants.OBJECT_RUNSTATE_PROPERTY,
                           AttributeConstants.OBJECT_RUNSTATE_RUNNING);
 Enumeration e = eg.getManagedSubcomponents(p);
 

will return an Enumeration of AdministeredObjects for which the runstate property is true (i.e. if applied to a MessageFlowProxy, the enumeration will contain all MessageFlowProxy objects that are running).

Note: If a batch of requests is being formed, the search is broadened to include all objects being created by the batch. This is so that new objects can be manipulated before they actually exist within the object hierarchy.

Parameters:

filter - the filter which will be used to identify the required objects. 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 subcomponents.

Returns:

Enumeration AdministeredObjects that satisfied the filter criteria.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if information on the object's subcomponents was not supplied before a timeout occurred.

getManagedSubcomponents

public java.util.Enumeration<?> getManagedSubcomponents(java.util.Properties filter,
                                               boolean returnContainsStrings)
                                                 throws ConfigManagerProxyPropertyNotInitializedException

Deprecated. Because the returned Enumeration cannot be checked for type-safety, this method should no longer be used. To return an enumeration of AdministeredObject subcomponents, use getManagedSubcomponents(Properties). To return an enumeration of strings, use the method getManagedSubcomponentsAsStrings(Properties).

Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker). This method takes a Properties object which will be used to filter the results, to allow commands of the form "give me all the execution groups with the following property". The enumeration will only contain those objects that are accessible to the current user.

For example:

 Properties p = new Properties();
 p.setProperty(AttributeConstants.OBJECT_RUNSTATE_PROPERTY,
                           AttributeConstants.OBJECT_RUNSTATE_RUNNING);
 Enumeration e = eg.getManagedSubcomponents(p, false);
 

will return an Enumeration of AdministeredObjects for which the runstate property is true (i.e. if applied to a MessageFlowProxy, the enumeration will contain all MessageFlowProxys that are running).

The type of object inside the returned enumeration is determined by the value of the boolean returnContainsStrings parameter. The benefit of a true value here is that it avoids needlessly instantiating AdministeredObject types that may not actually be required.

Note: If a batch of requests is being formed, the search is broadened to include all objects being created by the batch. This is so that new objects can be manipulated before they actually exist within the object hierarchy.

Parameters:

filter - The filter which will be used to identify the required objects. 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 subcomponents.

returnContainsStrings - Describes the format of the returned enumeration (see below).

Returns:

Enumeration If returnContainsStrings is true, the enumeration contains Strings in the format described by AdministeredObject.getTypeAndUUIDString() that satisfied the filter criteria. If returnContainsStrings is false, the enumeration contains AdministeredObjects that satisfied the filter criteria.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if information on the object's subcomponents was not supplied before a timeout occurred.

getManagedSubcomponentsAsStrings

public java.util.Enumeration<java.lang.String> getManagedSubcomponentsAsStrings(java.util.Properties filter)
                                                                         throws ConfigManagerProxyPropertyNotInitializedException

Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker). This method takes a Properties object which will be used to filter the results, to allow commands of the form "give me all the Execution Groups with the following property". The enumeration will only contain those objects that are accessible to the current user.

For example:

 Properties p = new Properties();
 p.setProperty(AttributeConstants.OBJECT_RUNSTATE_PROPERTY,
                           AttributeConstants.OBJECT_RUNSTATE_RUNNING);
 Enumeration e = eg.getManagedSubcomponentsAsStrings(p);
 

will return an Enumeration of Strings that describe objects for which the runstate property is true (i.e. if applied to a MessageFlowProxy, the enumerated strings will describe all MessageFlowProxy objects that are running).

The benefit of returning an enumeration of String objects is that it avoids needlessly instantiating AdministeredObject types that may not actually be required. The strings can be turned into AdministeredObjects by using the getManagedSubcomponentFromStringRepresentation(String) method.

Note: If a batch of requests is being formed, the search is broadened to include all objects being created by the batch. This is so that new objects can be manipulated before they actually exist within the object hierarchy.

Parameters:

filter - The filter which will be used to identify the required objects. 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 subcomponents.

Returns:

Enumeration The enumeration contains Strings in the format described by AdministeredObject.getTypeAndUUIDString() that satisfied the filter criteria.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the list of available subcomponents could not be determined because the broker has not yet supplied them.

getManagedSubcomponentsAsStrings

public java.util.Enumeration<java.lang.String> getManagedSubcomponentsAsStrings(java.util.Properties filter,
                                                                       java.util.Properties initialPropertiesOfNewObject)
                                                                         throws ConfigManagerProxyPropertyNotInitializedException

Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker). This method takes a Properties object which will be used to filter the results, to allow commands of the form "give me all the execution groups with the following property". The enumeration will only contain those objects that are accessible to the current user.

For example:

 Properties p = new Properties();
 p.setProperty(AttributeConstants.OBJECT_RUNSTATE_PROPERTY,
                           AttributeConstants.OBJECT_RUNSTATE_RUNNING);
 Enumeration e = eg.getManagedSubcomponents(p, false, null);
 

will return an Enumeration of AdministeredObjects for which the runstate property is true (i.e. if applied to a MessageFlowProxy, the enumeration will contain all MessageFlowProxys that are running).

The benefit of returning an enumeration of String objects is that it avoids needlessly instantiating AdministeredObject types that may not actually be required. The strings can be turned into AdministeredObjects by using the getManagedSubcomponentFromStringRepresentation(String) method.

Note: If a batch of requests is being formed, the search is broadened to include all objects being created by the batch. This is so that new objects can be manipulated before they actually exist within the object hierarchy.

Parameters:

filter - The filter which will be used to identify the required objects. 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 subcomponents.

initialPropertiesOfNewObject - If new AdministeredObjects have to be created, this parameter can be used to describe any default attributes of the new objects. May be null if no default attributes are required (but consider using another variant of getManagedSubcomponents() instead).

Returns:

Enumeration The enumeration contains Strings in the format described by AdministeredObject.getTypeAndUUIDString() that satisfied the filter criteria.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the list of available subcomponents could not be determined because the broker has not yet supplied them.

getManagedSubcomponents

public java.util.Enumeration<?> getManagedSubcomponents(java.util.Properties filter,
                                               boolean returnContainsStrings,
                                               java.util.Properties initialPropertiesOfNewObject)
                                                 throws ConfigManagerProxyPropertyNotInitializedException

Deprecated. Because the returned Enumeration cannot be checked for type-safety, this method should no longer be used. To return an enumeration of AdministeredObject subcomponents, use getManagedSubcomponents(Properties, Properties). To return an enumeration of strings, use the method getManagedSubcomponentsAsStrings(Properties, Properties).

Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker). This method takes a Properties object which will be used to filter the results, to allow commands of the form "give me all the Execution Groups with the following property". The enumeration will only contain those objects that are accessible to the current user.

For example:

 Properties p = new Properties();
 p.setProperty(AttributeConstants.OBJECT_RUNSTATE_PROPERTY,
                           AttributeConstants.OBJECT_RUNSTATE_RUNNING);
 Enumeration e = eg.getManagedSubcomponents(p, false, null);
 

will return an Enumeration of AdministeredObjects for which the runstate property is true (i.e. if applied to a MessageFlowProxy, the enumeration will contain all MessageFlowProxys that are running).

The type of object inside the returned enumeration is determined by the value of the boolean returnContainsStrings parameter. The benefit of a true value here is that it avoids needlessly instantiating AdministeredObject types that may not actually be required.

Note: If a batch of requests is being formed, the search is broadened to include all objects being created by the batch. This is so that new objects can be manipulated before they actually exist within the object hierarchy.

Parameters:

filter - The filter which will be used to identify the required objects. 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 subcomponents.

returnContainsStrings - Describes the format of the returned enumeration (see below).

initialPropertiesOfNewObject - If new AdministeredObjects have to be created, this parameter can be used to describe any default attributes of the new objects. May be null if no default attributes are required (but consider using another variant of getManagedSubcomponents() instead).

Returns:

Enumeration If returnContainsStrings is true, the enumeration contains Strings in the format described by AdministeredObject.getTypeAndUUIDString() that satisfied the filter criteria. If returnContainsStrings is false, the enumeration contains AdministeredObjects that satisfied the filter criteria.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the list of available subcomponents could not be determined because the broker has not yet supplied them.

getManagedSubcomponents

public java.util.Enumeration<AdministeredObject> getManagedSubcomponents(java.util.Properties filter,
                                                                java.util.Properties initialPropertiesOfNewObject)
                                                                  throws ConfigManagerProxyPropertyNotInitializedException

Asks the broker to return an enumeration of all the existing objects that logically belong directly within the current administered object (for example, the execution groups within a broker). This method takes a Properties object which will be used to filter the results, to allow commands of the form "give me all the execution groups with the following property". The enumeration will only contain those objects that are accessible to the current user.

For example:

 Properties p = new Properties();
 p.setProperty(AttributeConstants.OBJECT_RUNSTATE_PROPERTY,
                           AttributeConstants.OBJECT_RUNSTATE_RUNNING);
 Enumeration e = eg.getManagedSubcomponents(p, new Properties());
 

will return an Enumeration of AdministeredObjects for which the runstate property is true (i.e. if applied to a MessageFlowProxy, the enumeration will contain all MessageFlowProxy objects that are running).

Note: If a batch of requests is being formed, the search is broadened to include all objects being created by the batch. This is so that new objects can be manipulated before they actually exist within the object hierarchy.

Parameters:

filter - The filter which will be used to identify the required objects. 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 subcomponents.

initialPropertiesOfNewObject - If new AdministeredObjects have to be created, this parameter can be used to describe any default attributes of the new objects. May be null if no default attributes are required (but consider using another variant of getManagedSubcomponents() instead).

Returns:

Enumeration The enumeration contains AdministeredObjects that satisfied the filter criteria.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if information on the object's subcomponents was not supplied before a timeout occurred.

getManagedSubcomponentFromStringRepresentation

public AdministeredObject getManagedSubcomponentFromStringRepresentation(java.lang.String representation)
                                                                  throws ConfigManagerProxyPropertyNotInitializedException

Returns the object which has the current object as a parent that has the supplied string representation. The String must be in the form "ObjectType+UUID", for example: ExecutionGroup+34d49ca0-fb00-0000-0080-f4ea5a35573b This is a convenience method to get objects from processModify() notifications, which uses this format to notify AdministeredObjectListeners of new objects.

Note that the delimiter ('+') is specified in AttributeConstants.UUID_DELIMITER.

Parameters:

representation - String of the form "ObjectType+UUID".

Returns:

AdministeredObject subcomponent of the current object that has the supplied representation. The return value will be null if the supplied string was null, invalid, the object could not be found or the object has already been deleted.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if this object's subcomponent information had not been supplied by the broker before a timeout occurred.

getManagedSubcomponent

public AdministeredObject getManagedSubcomponent(java.util.Properties props)
                                          throws ConfigManagerProxyPropertyNotInitializedException

Returns the first object that has the requested properties. If the search yields multiple matches an arbitrary match is returned, although an object that is "awaiting submission for creation" will be returned in preference to one that is not.

Parameters:

props - the filter which will be used to identify the required objects. A null or empty object will match an arbitrary subcomponent.

Returns:

AdministeredObject the first object that matched the filtered criteria. Returns null if no element was found.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the list of available subcomponents could not be determined because the broker has not yet supplied them.

getType

public java.lang.String getType()

Convenience method to return the type of this administered object. Where possible, use getConfigurationObjectType() instead, as it returns the type in a form that is more easily parsed.

Returns:

String The name of this AdministeredObject type.

getUUID

public java.lang.String getUUID()

Convenience method to return the unique identifier of this administered object.

Returns:

String The UUID of this AdministeredObject

getName

public java.lang.String getName()
                         throws ConfigManagerProxyPropertyNotInitializedException

Returns the name of the object

Returns:

String name of the current object.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the property could not be determined because the broker has not yet supplied the relevant information.

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 (for subclass implementations) 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*() calls. For example, broker1.getExecutionGroup(ExecutionGroup.withUUID("1234")); will return the Execution Group with UUID "1234" that exists in broker1.

Parameters:

uuid -

Returns:

Properties a new Properties object with the UUID property set. to the supplied value.

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 subclass of AdministeredObject being used. This provides an easy way of supplying filters to the get*() calls. For example, broker1.getExecutionGroup(ExecutionGroup.withName("eg1")); will return the Execution Group with Name "eg1" that exists in broker1.

Parameters:

name -

Returns:

Properties a new Properties object with the relevant key/value pairs set.

getProperty

public java.lang.String getProperty(java.lang.String key)
                             throws ConfigManagerProxyPropertyNotInitializedException

Returns the local value of the supplied attribute. The information returned will be incorrect if the broker has recently modified the required property and the IBM Integration API (CMP) has not yet received notification of the change.

Parameters:

key - The name of the property to find. Use the AttributeConstants.*_PROPERTY constants here.

Returns:

String the local copy of the required property, or null if the property could not be found.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the value of the property is unknown because the information has not yet been supplied by the broker. If this is the case, this method will issue retries in accordance with the retry characteristics set by the BrokerProxy.setRetryCharacteristics() method. Only after these retries have been exhausted will the ConfigManagerProxyPropertyNotInitializedException be thrown.

getProperty

public java.lang.String getProperty(java.lang.String key,
                           boolean waitIfNotAvailable)
                             throws ConfigManagerProxyPropertyNotInitializedException

Returns the local value of the supplied attribute. The information returned will be incorrect if the broker has recently modified the required property and this application has not yet received notification of the change.

Parameters:

key - The name of the property to find. Use the AttributeConstants.*_PROPERTY constants here.

waitIfNotAvailable - if set to true, if the object has not yet been updated by the broker the method will wait for the length of time described by BrokerProxy.setRetryCharacteristics() for the information to become available. If set to false, the method will return immediately if the information is available, or throw a ConfigManagerProxyPropertyNotInitializedException if the information is not available.

Returns:

String the local copy of the required property, or null if the property could not be found.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the value of the property is unknown because the information has not yet been supplied by the broker. If this is the case, AND the value of waitIfNotAvailable is true, this method will issue retries in accordance with the retry characteristics set by the BrokerProxy.setRetryCharacteristics() method. Only after these retries have been exhausted will the ConfigManagerProxyPropertyNotInitializedException be thrown. If the information has not yet been supplied by the broker and the value of waitIfNotAvailable is false, this method will throw a ConfigManagerProxyPropertyNotInitializedException immediately.

getProperty

public java.lang.String getProperty(java.lang.String key,
                           int element)
                             throws ConfigManagerProxyPropertyNotInitializedException

For properties that end in a number (for example, subcomponent properties) this method returns the value of the property that ends in the supplied number, waiting if the information is not available.

Parameters:

key - The name of the property to find. Use the AttributeConstants.*_PROPERTY constants here.

element - The number of the property to find and return.

Returns:

String The value of the requested property, or null if the property could not be found.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the requested property is not yet known.

See Also:

elements(java.lang.String)

getProperty

public java.lang.String getProperty(java.lang.String key,
                           int element,
                           boolean waitIfNotAvailable)
                             throws ConfigManagerProxyPropertyNotInitializedException

For properties that end in a number (for example, subcomponent properties) this method returns the value of the property that ends in the supplied number, optionally waiting if the information is not available.

Parameters:

key - The name of the property to find. Use the AttributeConstants.*_PROPERTY constants here.

element - The number of the property to find and return

waitIfNotAvailable - if set to true, if the object has not yet been updated by the broker the method will wait for the length of time described by BrokerProxy.setRetryCharacteristics() for the information to become available. If set to false, the method will return immediately.

Returns:

String The value of the requested property, or null if the property could not be found.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the requested property is not yet known.

See Also:

elements(java.lang.String)

isAwaitingSubmissionForCreation

public boolean isAwaitingSubmissionForCreation()

Returns true if and only if the current object has been created as part of the current batch, but the batch has not yet been sent to the broker.

Returns:

true if the object is awaiting submission for creation.

See Also:

BrokerProxy.beginUpdates()

isAwaitingSubmissionForDeletion

public boolean isAwaitingSubmissionForDeletion()

Returns true if and only if the current object has been deleted as part of the current batch, but the batch has not yet been sent to the broker.

Returns:

true if the object is awaiting submission for deletion.

Since:

V6.0.0.1

See Also:

BrokerProxy.beginUpdates()

isShared

public boolean isShared()
                 throws ConfigManagerProxyPropertyNotInitializedException

Deprecated. As of WebSphere Message Broker V7, this method is not relevant as the Configuration Manager is no longer used. The effects of calling this method are no longer defined.

Returns true if and only if the object that this AdministeredObject represents exists in the shared section of the Configuration Manager database. Shared objects can be viewed or modified by the user of any application that has the relevant authority.

Returns:

boolean true if the object is shared.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the required information has not been supplied by the Configuration Manager.

isDeployed

public boolean isDeployed()
                   throws ConfigManagerProxyPropertyNotInitializedException

Deprecated. As of WebSphere Message Broker V7, this method is not relevant as the Configuration Manager is no longer used. The effects of calling this method are no longer defined.

Returns true if and only if the object that this AdministeredObject represents exists in the deployed section of the Configuration Manager database. Deployed objects have been the subject of a deployment action at least once- that is, have been deployed to brokers.

Returns:

boolean true if the object is deployed.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the required information has not been supplied by the Configuration Manager.

getParent

public AdministeredObject getParent()
                             throws ConfigManagerProxyLoggedException

Returns the AdministeredObject that logically owns this object. If invoked on the root of the object hierarchy, this method returns null.

Returns:

AdministeredObject parent of the current object

Throws:

ConfigManagerProxyLoggedException - if the parent object is not immediately available and has to be requested from the broker, but the request could not be sent to find it.

getRepositoryTimestamp

public java.util.Date getRepositoryTimestamp()
                                      throws ConfigManagerProxyPropertyNotInitializedException

Deprecated. As of WebSphere Message Broker V7, there is no configuration repository and so this method is no longer used. The effects of invoking it are not defined.

Throws:

ConfigManagerProxyPropertyNotInitializedException

elements

public int elements(java.lang.String key)
             throws ConfigManagerProxyPropertyNotInitializedException

For groups of attributes (such as subcomponents) this method returns the largest number for which an attribute exists in the current object. For instance, if the attributes "subcomponent.1" and "subcomponent.2" exist in the current object but "subcomponent.3" does not, elements("subcomponent.") will return 2.

Parameters:

key - The name of the property to find. Use the AttributeConstants.*_PROPERTY constants here.

Returns:

The number of the last available property or zero if there are no elements available for the supplied property.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the requested property is not yet known.

setLongDescription

public void setLongDescription(java.lang.String desc)
                        throws ConfigManagerProxyLoggedException

Sets the long description field of the current AdministeredObject. If this method returns successfully the request will have been sent to the broker, batched for sending if a batch is in progress, or successfully processed by the broker if synchronous updates have been enabled.

Parameters:

desc - New description string.

Throws:

ConfigManagerProxyLoggedException - if the request could not be sent to the broker. If synchronous updates have been enabled using BrokerProxy.setSynchronous(), subclasses of this exception type will also be thrown if the request is rejected by the broker, or if the request is not processed before a timeout occurs.

getLongDescription

public java.lang.String getLongDescription()
                                    throws ConfigManagerProxyPropertyNotInitializedException

Returns the long description field for the current AdministeredObject.

Returns:

String description string.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the requested property is not yet known.

setShortDescription

public void setShortDescription(java.lang.String desc)
                         throws ConfigManagerProxyLoggedException

Sets the short description field of the current AdministeredObject. If this method returns successfully the request will have been sent to the broker, batched for sending if a batch is in progress, or successfully processed by the broker if synchronous updates have been enabled.

Parameters:

desc - New description string.

Throws:

ConfigManagerProxyLoggedException - if the request could not be sent to the broker. If synchronous updates have been enabled using BrokerProxy.setSynchronous(), subclasses of this exception type will also be thrown if the request is rejected by the broker, or if the request is not processed before a timeout occurs.

getShortDescription

public java.lang.String getShortDescription()
                                     throws ConfigManagerProxyPropertyNotInitializedException

Helper method to return the short description field for the Administered Object.

Returns:

String description string.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the requested property is not yet known.

setName

public void setName(java.lang.String name)
             throws ConfigManagerProxyLoggedException,
                    java.lang.IllegalArgumentException

Sets the name of the current AdministeredObject. If this method returns successfully the request will have been sent to the broker, batched for sending if a batch is in progress, or successfully processed by the broker if synchronous updates have been enabled.

Parameters:

name - New name

Throws:

ConfigManagerProxyLoggedException - if the request could not be sent to the broker. If synchronous updates have been enabled using BrokerProxy.setSynchronous(), subclasses of this exception type will also be thrown if the request is rejected by the broker, or if the request is not processed before a timeout occurs.

java.lang.IllegalArgumentException - if the supplied name is null or empty.

getLastCompletionCode

public CompletionCodeType getLastCompletionCode()

Returns the completion code of the last operation that was performed by this connection to the broker on the object that this AdministeredObject represents. As requests are processed asynchronously, this method should be used in conjunction with getTimeOfLastCompletionCode() to ensure that the completion code refers to the correct operation. For example:

   GregorianCalendar oldCCTime = topology.getTimeOfLastCompletionCode();
   BrokerProxy b = topology.createBroker("fred");
   GregorianCalendar newCCTime = oldCCTime;
   while (oldCCTime.equals(newCCTime)) {
     newCCTime = topology.getTimeOfLastCompletionCode();
   }
   CompletionCodeType ccType = topology.getLastCompletionCode();
   // ccType refers to the results of the broker create
 

Note, this is not very efficient code because it hangs the caller's thread and does not check for timeouts. The preferred way of getting back results of operations is to use the listener mechanism. See registerListener() for more information.

Returns:

CompletionCodeType of the last operation performed to this AdministeredObject by this connection.

getTimeOfLastCompletionCode

public java.util.GregorianCalendar getTimeOfLastCompletionCode()

Returns the time that the completion code field was last updated, as a result of a request that was sent out by this connection to the broker. If this field is null, this object has never received such a completion code.

Returns:

GregorianCalendar of the time the object's completion code field was last updated.

See Also:

getLastCompletionCode()

getLastBIPMessages

public java.util.Vector<LogEntry> getLastBIPMessages()

Returns the last vector of BIP messages that are associated with this object. These are set when a previously submitted action completes and the response is received by the IBM Integration API (CMP).

Returns:

Vector of com.ibm.broker.config.proxy.LogEntry objects. The Vector will be empty or null if no log entries were associated with the last response.

getTimeOfLastUpdate

public java.util.GregorianCalendar getTimeOfLastUpdate()

Returns the time that the object was last updated by a broker. The request that caused the successful update did not necessarily originate from this JVM. If this value is null, the object has never had an update.

Returns:

GregorianCalendar of the time the object was last updated. The value will be null if the object has never received an update.

getLastUpdateUser

public java.lang.String getLastUpdateUser()

Deprecated. The property that describes which user last made a change is not used as of WebSphere Message Broker V7. Use the Administration Log (LogProxy) to discover which changes have been made by which user.

Returns the empty string.

Returns:

the empty string.

getNumberOfSubcomponents

public int getNumberOfSubcomponents()
                             throws ConfigManagerProxyPropertyNotInitializedException

Returns the number of subcomponents that are directly owned by this object.

Returns:

int a number greater than or equal to 0.

Throws:

ConfigManagerProxyPropertyNotInitializedException - if the required information had not been supplied by the broker by the time a timeout occurred.

hasBeenUpdatedByConfigManager

public boolean hasBeenUpdatedByConfigManager()

Deprecated. As this method can also be used to determine whether objects have been updated when connected directly to a broker, this method's name is no longer accurate. Use hasBeenPopulatedByBroker() instead. This method will return the same value as hasBeenPopulatedByBroker().

Returns true if and only if this object handle has received at least one update publication from the broker. This call returns immediately. If this method returns false, it means that requests for attributes of this AdministeredObject are likely to cause a pause while the information is discovered.

Returns:

boolean true if the object has had at least one update by the broker, false otherwise.

hasBeenUpdatedByConfigManager

public boolean hasBeenUpdatedByConfigManager(boolean waitIfNotUpdated)

Deprecated. As this method can also be used to determine whether objects have been updated when connected directly to a broker, this method's name is no longer accurate. Use hasBeenPopulatedByBroker(boolean) instead. This method will return the same value as hasBeenPopulatedByBroker(boolean).

Returns true if and only if this object handle has received at least one update publication from the broker. If no updates have been received, this method optionally waits for the first update to arrive.

Parameters:

waitIfNotUpdated - If set to true, this method will retry for the currently configured timeout period if the object has not been updated. If the object has not been updated after the timeout period has expired, false will be returned.

Returns:

boolean true if the object has had at least one update by the broker, false otherwise.

See Also:

BrokerProxy.setRetryCharacteristics(long)

hasBeenPopulatedByBroker

public boolean hasBeenPopulatedByBroker()

Returns true if and only if this object handle has received at least one update publication from the connected broker. This call returns immediately. If this method returns false, it means that requests for attributes of this AdministeredObject are likely to cause a pause while the information is discovered.

Returns:

boolean true if the object has had at least one update by the server, false otherwise.

hasBeenPopulatedByBroker

public boolean hasBeenPopulatedByBroker(boolean waitIfNotUpdated)

Returns true if and only if this object handle has received at least one update publication from the connected broker. If no updates have been received, this method optionally waits for the first update to arrive.

Parameters:

waitIfNotUpdated - If set to true, this method will retry for the currently configured timeout period if the object has not been updated. If the object has not been updated after the timeout period has expired, false will be returned.

Returns:

boolean true if the object has had at least one update by the broker, false otherwise.

See Also:

BrokerProxy.setRetryCharacteristics(long)

hasBeenRestrictedByBroker

public boolean hasBeenRestrictedByBroker(boolean waitIfNotUpdated)

This method returns true if and only if the IBM Integration API (CMP) has been told by the broker that the object cannot be viewed by the current user.

If the userid running the IBM Integration API (CMP) application is given view authority after first being denied view authority to the object, the application then needs to call the refresh() method to attempt to register for the object again. Only once the broker has responded to the refresh() method will hasBeenRestrictedByBroker() begin to return 'false'.

Parameters:

waitIfNotUpdated - If set to true, this method will retry for the currently configured timeout period if the object has not received at least one response from the broker. If the object has not received a response after the timeout period has expired, false will be returned.

Returns:

boolean true if and only if the object has been restricted.

hasBeenRestrictedByBroker

public boolean hasBeenRestrictedByBroker()

This method returns true if and only if the IBM Integration API (CMP) has been told by the broker that the object cannot be viewed by the current user.

If the userid running the IBM Integration API (CMP) application is given view authority after first being denied view authority to the object, the application then needs to call the refresh() method to attempt to register for the object again. Only once the broker has responded to the refresh() method will hasBeenRestrictedByBroker() begin to return 'false'.

Returns:

boolean true if and only if the object has been restricted.

hasBeenRestrictedByConfigManager

public boolean hasBeenRestrictedByConfigManager()

Deprecated. As of WebSphere Message Broker V7, Configuration Managers are not used. Use hasBeenRestrictedByBroker() to determine if a broker has prevented the application from viewing the AdministeredObject.

This method returns true if and only if the IBM Integration API (CMP) has been told by the broker that the object is not available for use by the current user. If the object has not yet received any update from the broker, the call will block until the first update or 'object has been restricted' 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 object is NOT available

hasBeenRestrictedByConfigManager

public boolean hasBeenRestrictedByConfigManager(boolean waitIfNotUpdated)

Deprecated. As of WebSphere Message Broker V7, Configuration Managers are not used.

This method returns true if and only if the IBM Integration API (CMP) has been told by the broker that the object is not available for use by the current user.

Parameters:

waitIfNotUpdated - If this is set to true and the administered object has not yet received an update from the broker, the call will block until an update 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 restriction flag is sought before the 'this object has been restricted' response from the broker has necessarily been returned, that this method may return 'false' even though the object is not accessible to the user. This is because it is the receipt of a negative response from the broker that triggers the flag to be set.). If the parameter is set to false, or the object has already received at least one message from the broker, the call will return immediately.

Returns:

boolean true if and only if the object has been restricted.

refresh

public void refresh()
             throws ConfigManagerProxyLoggedException

Forces this AdministeredObject to reregister itself with the broker and to re-receive the object's complete set of attributes. This call is not generally necessary, as the broker will keep the object's subscription active indefinitely and keep the application up to date with its latest information anyway.

This method must not be called on AdministeredObject instances that do not yet exist on the broker (ie. objects initialized during a batch of creation requests).

Throws:

ConfigManagerProxyLoggedException - if the request to refresh the object could not be sent to the broker.

getConfigurationObjectType

public abstract ConfigurationObjectType getConfigurationObjectType()

Returns the ConfigurationObjectType associated with this AdministeredObject type. For example, for ExecutionGroupProxy, ConfigurationObjectType.executiongroup is returned.

Returns:

ConfigurationObjectType associated with this class.

getConfigurationObjectTypeOfParent

public abstract ConfigurationObjectType getConfigurationObjectTypeOfParent()

Returns the ConfigurationObjectType associated with the logical parent of this AdministeredObject type. For example, for ExecutionGroupProxy, ConfigurationObjectType.broker is returned.

Returns:

ConfigurationObjectType associated with this class.

toVerboseString

public java.lang.String toVerboseString()

Displays the list of all properties currently associated with this administered object.

Returns:

String Representation of the current object

toString

public java.lang.String toString()

Displays the type and UUID of the current object (or the name if it is available). The format is not guaranteed, and therefore should not be parsed programatically.

Overrides:

toString in class java.lang.Object

Returns:

String Representation of the current object

equals

public boolean equals(java.lang.Object obj)

Compares this AdministeredObject with the Object passed in.

Two instances of an AdministeredObject are equal if and only if they are both AdministeredObjects and they have the same ConfigurationObjectType and UUID.

Overrides:

equals in class java.lang.Object

Parameters:

obj - - the object that is to be compared with this one.

Returns:

true if the two AdministeredObjects are equal