Class Hierarchy All Classes All Fields and Methods

Class com.ibm.broker.config.proxy.AdministeredObject

java.lang.Object
        com.ibm.broker.config.proxy.AdministeredObject

public abstract class AdministeredObject
extends Object

This is the abstract superclass from which most domain object representations 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 domain objects is similar for all administered object types:

  1. The calling application asks for a reference to the administered object. Note that BrokerProxy is a subclass of AdministeredObject.
        BrokerProxy b = topol.getBrokerByName("myBroker");
  2. At this point, the Configuration Manager Proxy will ask the Configuration Manager for details of the requested object, and asks it to keep the Configuration Manager Proxy 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 Configuration Manager Proxy (because the Configuration Manager has not yet supplied it) a pause may occur while the requested information is obtained. An example of information being requested is:
         boolean showGreenLight = b.isRunning();
     
  3. The caller may wish to change properties of the administered object. Properties include persistent characteristics of the object (such as its description) as well as operational characteristics (such as whether it is running):
         b.setShortDescription("Test broker");
         b.startMessageFlows();
     
    The Configuration Manager 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 Configuration Manager, 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. Or, for methods that initiate deployment, a third option is to instruct the Configuration Manager Proxy to only return when a response to the deployment has been successfully received from the affected broker(s).
         DeployResult dr = b.deploy(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 Configuration Manager, and also to be told of other changes to the object, the caller can register user-written implementors of AdministeredObjectListener to the Configuration Manager Proxy.
         AdministeredObjectListener myListener = new MyAdministeredObjectListener();
         // Interested in changes to broker 'b'
         b.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 'b'.
         b.deregisterListener( myListener );
     
  6. As with all other Java objects, administered objects can go out of scope. At some unspecified point in time after this happens, an internal Configuration Manager Proxy thread is notified by the JVM that this has taken place, and the Configuration Manager Proxy then tidies up any resources associated with the object and asks the Configuration Manager 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 Configuration Manager, the process restarts from step one.


    Note that administered objects that have AdministeredObjectListener instances registered will not get tidied in this way until either they are deregistered, the Configuration Manager Proxy is disconnected from the Configuration Manager or the application ends.

com.ibm.broker.config.proxy.AdministeredObject

Responsibilities Provides a means of manipulating arbitrary managed objects within the Configuration Manager domain. 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
 d41882   2005-11-25  HDMPL           Added isAwaitingSubmissionForDeletion()

 

Field Index
Field Description
baseRetryWaitTime The initial time to wait between retries (in milliseconds)
copyright IBM Copyright
LOCAL_ATTRIBUTE_IDENTIFIER This string is used at the beginning of attributes that are not common across all proxies connected to the Configuration Manager, but are valid attributes to have in administered objects (such as the local userid, version number).
maxRetries As the communication link with the Configuration Manager is no longer a request/response protocol we may not always have been supplied a required piece of information that is needed to perform an operation (for example, we can't return a broker's execution group list if that broker's information has not been supplied to us).
owningPool The AdministeredObjectPool that was responsible for creating this object.
potentialNewSubcomponents A Vector of AdministeredObjects.
retryWaitTimeIncrement How much to increase the retry wait time by after each consecutive failure.
sccsid Version information
subcomponentsToBeSubmittedForCreationInCurrentBatch A Vector of AdministeredObjects.
UUID_DELIMITER Shorthand for the string used to separate the type parameter from the UUID parameter in the subcomponent properties.
Constructor Index
Constructor Description
AdministeredObject(AdministeredObjectPool) Initialises a new AdministeredObject AdministeredObjects can only be created by the AdministeredObjectPool.
Method Index
Method Description
void clearPredictedNewSubcomponents() Clears the vector of predicted new subcomponents.
AdministeredObject createManagedSubcomponent(Properties) Asks the Configuration Manager to create a new object that logically belongs within the current administered object (for example, create a new Execution Group within this Broker).
void deleteManagedSubcomponents(Properties) Asks the Configuration Manager to remove objects that logically belong within the current administered object.
void deregisterListener(AdministeredObjectListener) Asks the Configuration Manager Proxy to unsubscribe a previously registered AdministeredObjectListener, given the listener instance that was supplied during registration.
void deregisterListener(AdvancedAdministeredObjectListener) Asks the Configuration Manager Proxy to unsubscribe a previously registered AdvancedAdministeredObjectListener, given the listener instance that was supplied during registration.
void doAddAccessControlEntries(AccessControlEntry[]) Adds this list to the list of access control entries that applies to this object.
AccessControlEntry[] doGetAccessControlEntries() Creates and returns a set of AccessControlEntry objects that describes the set of (principal,permission) tuples that have been applied specifically to this object.
void doRemoveAccessControlEntries(AccessControlEntry[]) Deletes this list from the list of access control entries that applies to this object.
void doSetAccessControlEntries(AccessControlEntry[]) Sets the complete list of access control entries that apply to this object.
int elements(String) For groups of attributes (such as subcomponents) this method returns the largest number for which an attribute exists in the current object.
ConfigurationObjectType getConfigurationObjectType() Returns the ConfigurationObjectType associated with this AdministeredObject type.
ConfigurationObjectType getConfigurationObjectTypeOfParent() Returns the ConfigurationObjectType associated with the logical parent of this AdministeredObject type.
Vector 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 Configuration Manager on the object that this AdministeredObject represents.
String getLastUpdateUser() Returns the userid of the person who caused the last modification message to be sent for this object.
String getLongDescription() Helper method to return the long description field for the current Administered Object.
AdministeredObject getManagedSubcomponent(Properties) Returns the first object that has the requested properties.
AdministeredObject getManagedSubcomponentFromStringRepresentation(String) Returns the object which has the current object as a parent that has the supplied string representation.
Enumeration getManagedSubcomponents(Properties) Asks the Configuration Manager 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).
Enumeration getManagedSubcomponents(Properties, boolean) Asks the Configuration Manager 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).
Enumeration getManagedSubcomponents(Properties, boolean, Properties) Asks the Configuration Manager 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).
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.
Properties getProperties() Returns a clone of the complete local attribute list for the current object, based on information supplied solely from the Config Manager.
String getProperty(String) Returns the local value of the supplied attribute.
String getProperty(String, boolean) Returns the local value of the supplied attribute.
String getProperty(String, boolean, boolean) Returns the local value of the supplied attribute.
String getProperty(String, int) 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.
String getProperty(String, int, boolean) 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.
String getPropertyBaseName(String) Returns the 'base' name of the supplied property key name.
int getPropertyInt(String) Returns a property value as an int.
Date getRepositoryTimestamp() Returns the most recent repository timestamp associated with this object.
String getShortDescription() Helper method to return the short description field for the Administered Object.
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 Configuration Manager.
GregorianCalendar getTimeOfLastUpdate() Returns the time that the object was last updated by a Configuration Manager publication.
String getType() Convenience method to return the type of this administered object.
String getUUID() Convenience method to return the unique identifier of this administered object.
String getUUIDOfParent() Returns the UUID of the parent of this object (if the parent UUID has been implemented for the underlying object type).
boolean hasBeenRestrictedByConfigManager() Returns true if and only if the proxy has been told by the Configuration Manager that the object is not available for use by the current user.
boolean hasBeenRestrictedByConfigManager(boolean) Returns true if and only if the proxy has been told by the Configuration Manager that the object is not available for use by the current user.
boolean hasBeenUpdatedByConfigManager() Returns true if and only if this object handle has received at least one update publication from the Configuration Manager.
boolean hasBeenUpdatedByConfigManager(boolean) Returns true if and only if this object handle has received at least one update publication from the Configuration Manager.
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 Configuration Manager.
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 Configuration Manager.
boolean isDeployed() Returns true if and only if the object that this AdministeredObject represents exists in the deployed section of the Configuration Manager database.
boolean isLastPropertyIdentifier(String) Returns true if and only if the supplied property name is the last element identifier in a group of properties.
boolean isPartOfAPropertyGroup(String) Returns true if and only if the supplied property name is part of a set of related property elements.
boolean isShared() Returns true if and only if the object that this AdministeredObject represents exists in the shared section of the Configuration Manager database.
void moveManagedSubcomponent(Properties, AdministeredObject) Atomically removes a managed subcomponent and adds it to the supplied instance (which must be of the same type).
void refresh() Forces this AdministeredObject to reregister itself with the Configuration Manager and to re-receive the object's complete set of attributes.
void registerListener(AdministeredObjectListener) Asks the Configuration Manager to keep the caller informed of any changes to the current AdministeredObject.
void registerListener(AdvancedAdministeredObjectListener) Asks the Configuration Manager to keep the caller informed of any changes to the current AdministeredObject.
void registerListener(AdvancedAdministeredObjectListener, boolean, Object) Asks the Configuration Manager to keep the caller informed of any changes to the current AdministeredObject, and ask to be provided with advanced notifications.
void removeLocalProperty(String) Removes the local property with the supplied name.
void setIsAwaitingSubmissionForCreation(boolean) Sets the flag that describes whether the object is awaiting creation.
void setIsAwaitingSubmissionForDeletion(boolean) Sets the flag that describes whether the object is awaiting deletion.
void setLastBIPMessages(Vector) Sets the object's vector of BIP messages
void setLastCompletionCode(CompletionCodeType) Sets the last completion code, and the corresponding 'time of last update' fields.
void setLocalProperty(String, String) Updates the local property with the supplied value.
void setLongDescription(String) Helper method to set the long description field of the current Administered Object.
void setName(String) Helper method to set the name of the Administered Object.
void setProperties(Properties) Asks the Configuration Manager to update a set of attributes for the current object.
void setShortDescription(String) Helper method to set the short description field of the Administered Object.
void setTimeOfLastUpdate() Updates the field that contains the time the Configuration Manager Proxy last received an update notification.
String toString() Displays the type and UUID of the current object (or the name if it is available).
String toVerboseString() Displays the list of all properties currently associated with this administered object.
void unsubscribeFromConfigurationManagerUpdates() Asks the Proxy to explicitly unsubscribe the current AdministeredObject from receiving future Configuration Manager updates.
void updateRestrictionFlag(boolean) Updates the value of the restriction flag used by hasBeenRestrictedByConfigManager().
Properties withName(String) 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.
Properties withUUID(String) 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.

Fields

baseRetryWaitTime

protected static long baseRetryWaitTime

The initial time to wait between retries (in milliseconds)

copyright

protected static final java.lang.String copyright

IBM Copyright

LOCAL_ATTRIBUTE_IDENTIFIER

protected static final java.lang.String LOCAL_ATTRIBUTE_IDENTIFIER

This string is used at the beginning of attributes that are not common across all proxies connected to the Configuration Manager, but are valid attributes to have in administered objects (such as the local userid, version number).

maxRetries

protected static long maxRetries

As the communication link with the Configuration Manager is no longer a request/response protocol we may not always have been supplied a required piece of information that is needed to perform an operation (for example, we can't return a broker's execution group list if that broker's information has not been supplied to us).

If this happens the Configuration Manager Proxy may throw ConfigManagerProxyPropertyNotInitializedException. This can happen frequently if the proxy has a slow link to the Configuration Manager, or if the calling application tries to make use of an AdministeredObject too soon after requesting it.

Hence, the need for a internal retry mechanism to catch the ConfigManagerProxyPropertyNotInitializedException and retry the operation. This variable represents the maximum number of consecutive exceptions we must get before we pass the exception on to the calling application.

Note: these retry values can be configured by the calling application through the ConfigManagerProxy.setRetryCharacteristics() methods.

owningPool

protected com.ibm.broker.config.proxy.AdministeredObjectPool owningPool

The AdministeredObjectPool that was responsible for creating this object. Also, it is this pool that is queried for the subcomponents of the current AdministeredObject.

potentialNewSubcomponents

protected java.util.Vector potentialNewSubcomponents

A Vector of AdministeredObjects. Each element of this vector describes a new subcomponent of the object that has been sent to the Configuration Manager for creation, but for which no response has yet been received. For example, if an application calls 'BrokerProxy.createExecutionGroup()' the returned value from that method will also be stored here until the Configuration Manager reports a success or failure response to the request.

This vector is cleared whenever an actionresponse message to a createchild request comes in from the Configuration Manager regarding this object. It's possible therefore, that the vector is cleared prematurely (i.e. if an unrelated createchild response comes in for this AdministeredObject). Alternatively, if the Configuration Manager decides to send the actionresponse message to the createchild message before the processModify() is receieved, there is a small window in which the new object will be neither in this vector, nor available to the in the hierarchy. But this is OK, because we know that the Configuration Manager always sends the actionresponse after any modification messages.

The reason why this vector exists is for the scenario in which a user asks to create an object, but then immediately tries to get the object back before the Configuration Manager has responded. Without this vector, the Configuration Manager Proxy has no reference to the newly created object and so a different object is returned on the get call. It's not terribly important, because the calling application has the option of just using the returned value from the create method (why would it ever need to get a new handle to the object if it already has a reference to it?).

retryWaitTimeIncrement

protected static long retryWaitTimeIncrement

How much to increase the retry wait time by after each consecutive failure.

sccsid

protected static final java.lang.String sccsid

Version information

subcomponentsToBeSubmittedForCreationInCurrentBatch

protected java.util.Vector subcomponentsToBeSubmittedForCreationInCurrentBatch

A Vector of AdministeredObjects. When a request to create a subcomponent is put together ready for sending to the Configuration Manager, a reference to the unconfirmed AdministeredObject child is added to this Vector. This Vector can then be used if the caller wishes to traverse the object hierarchy, but would otherwise be prohibited from doing so because this object's subcomponent list has not yet been updated. For example, if 'this' object is a broker, "when an execution group is created a reference to the new execution group is added to the vector. Then if the caller wishes to list the broker's execution groups before the response comes back from the Configuration Manager and before the "subcomponent.*" list gets updated, the Proxy knows to include a new execution group that is yet to be confirmed as created. This vector is cleared whenever a batch is submitted, and so is only really useful for referring to subcomponents during the creation of a batch of requests.

UUID_DELIMITER

protected static final java.lang.String UUID_DELIMITER

Shorthand for the string used to separate the type parameter from the UUID parameter in the subcomponent properties.

Constructors

AdministeredObject

protected AdministeredObject(AdministeredObjectPool creator) 

Initialises a new AdministeredObject AdministeredObjects can only be created by the AdministeredObjectPool.

Methods

clearPredictedNewSubcomponents

protected void clearPredictedNewSubcomponents() 

Clears the vector of predicted new subcomponents.

createManagedSubcomponent

protected AdministeredObject createManagedSubcomponent(Properties suppliedProps) throws ConfigManagerProxyLoggedException

Asks the Configuration Manager to create a new object that logically belongs within the current administered object (for example, create a new Execution Group within this Broker). This method takes a Properties object that contains the attributes of this new object (e.g. "name" and "type"). Returned from this method is an object of type AdministeredObject which can be used to reference the object that the client has asked the Configuration Manager to create. This does not mean that the returned value represents a successfully created object within the Configuration Manager as the actual request to create the object will be completed asynchronously. However, as requests from the same source will be processed FIFO at the Configuration Manager, it is possible to make use of the returned object in subsequent requests, even before the object is created. (Of course, if the creation fails any subsequent calls that reference this object will fail also.)

This method is largely internal now, as most object manipulation can be done via individual shortcut methods (which just reference the *ManagedSubcomponent() methods here).

deleteManagedSubcomponents

protected void deleteManagedSubcomponents(Properties suppliedProps) throws ConfigManagerProxyLoggedException

Asks the Configuration Manager to remove objects that logically belong within the current administered object. This method takes a Properties object that filters the object to be deleted (e.g. Delete the object of type "ExecutionGroupProxy" with the uuid "1234-1234-1234").

This method is largely internal now, as most object manipulation can be done via individual shortcut methods (which just reference the *ManagedSubcomponent() methods here).

deregisterListener

public void deregisterListener(AdministeredObjectListener listener) 

Asks the Configuration Manager Proxy 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.

deregisterListener

public void deregisterListener(AdvancedAdministeredObjectListener listener) 

Asks the Configuration Manager Proxy 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.

doAddAccessControlEntries

protected void doAddAccessControlEntries(AccessControlEntry[] accessControlList) throws ConfigManagerProxyLoggedException

Adds this list to the list of access control entries that applies to this object. Null elements in the array are ignored.

This operation is completely transactional. If the Configuration Manager successfully processes this request, all access control entries from the supplied array will be associated with this administered object. If not, the access control list for this object will have not been modified.

If the Configuration Manager to which the Configuration Manager Proxy is connected is of a version less than v6, this method will have no effect.

doGetAccessControlEntries

protected AccessControlEntry[] doGetAccessControlEntries() 

Creates and returns a set of AccessControlEntry objects that describes the set of (principal,permission) tuples that have been applied specifically to this object.

This method does not return details of permissions that have been implicitly granted by inherited access control entries.

doRemoveAccessControlEntries

protected void doRemoveAccessControlEntries(AccessControlEntry[] accessControlList) throws ConfigManagerProxyLoggedException

Deletes this list from the list of access control entries that applies to this object. Null elements in the array are ignored. In addition, if any elements of the array are not associated with the administered object, they will be ignored.

This operation is completely transactional. If the Configuration Manager successfully processes this request, no access control entries from the supplied array will be associated with this administered object. If not, the access control list for this object will have not been modified.

If the Configuration Manager to which the Configuration Manager Proxy is connected is of a version less than v6, this method will have no effect.

doSetAccessControlEntries

protected void doSetAccessControlEntries(AccessControlEntry[] accessControlList) throws ConfigManagerProxyLoggedException

Sets the complete list of access control entries that apply to this object. Null elements in the array are ignored. If the array itself is null or empty, all access control entries for this object are removed.

This method submits only changed access control entries to the Configuration Manager. It converts the supplied array into a set of access control entries to add and a set of access control entries to remove, based on the information currently supplied from the Configuration Manager. The add and remove operations are processed separately by the Configuration Manager as two atomic, transactional requests.

If the Configuration Manager to which the Configuration Manager Proxy is connected is of a version less than v6, this method will have no effect.

elements

public int elements(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.

getConfigurationObjectType

public abstract ConfigurationObjectType getConfigurationObjectType() 

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

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.

getLastBIPMessages

public Vector 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 Configuration Manager Proxy.

getLastCompletionCode

public CompletionCodeType getLastCompletionCode() 

Returns the completion code of the last operation that was performed by this connection to the Configuration Manager 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.

getLastUpdateUser

public String getLastUpdateUser() 

Returns the userid of the person who caused the last modification message to be sent for this object. The field is only set after at least one modification has been received in the lifetime of this connection. If this value is null, the object has never had an update.

Note that there are circumstances in which the user that caused the last update will be unknown; for example, if the runstate of an object happens to change.

getLongDescription

public String getLongDescription() throws ConfigManagerProxyPropertyNotInitializedException

Helper method to return the long description field for the current Administered Object.

getManagedSubcomponent

public AdministeredObject getManagedSubcomponent(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.

getManagedSubcomponentFromStringRepresentation

public AdministeredObject getManagedSubcomponentFromStringRepresentation(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.

getManagedSubcomponents

public Enumeration getManagedSubcomponents(Properties filter) throws ConfigManagerProxyPropertyNotInitializedException

Asks the Configuration Manager 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.

getManagedSubcomponents

public Enumeration getManagedSubcomponents(Properties filter,
                                           boolean returnContainsStrings) throws ConfigManagerProxyPropertyNotInitializedException

Asks the Configuration Manager 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.

getManagedSubcomponents

public Enumeration getManagedSubcomponents(Properties filter,
                                           boolean returnContainsStrings,
                                           Properties initialPropertiesOfNewObject) throws ConfigManagerProxyPropertyNotInitializedException

Asks the Configuration Manager 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.

getName

public String getName() throws ConfigManagerProxyPropertyNotInitializedException

Returns the name of the object

getNumberOfSubcomponents

public int getNumberOfSubcomponents() throws ConfigManagerProxyPropertyNotInitializedException

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

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.

getProperties

public Properties getProperties() 

Returns a clone of the complete local attribute list for the current object, based on information supplied solely from the Config Manager. Modifying any properties in the returned object will not modify the object itself, unless it is subsequently supplied to the setProperties() method.

getProperty

public String getProperty(String key) throws ConfigManagerProxyPropertyNotInitializedException

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

getProperty

public String getProperty(String key,
                          boolean waitIfNotAvailable) throws ConfigManagerProxyPropertyNotInitializedException

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

getProperty

protected String getProperty(String key,
                             boolean waitIfNotAvailable,
                             boolean ignoreExceptions) throws ConfigManagerProxyPropertyNotInitializedException

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

getProperty

public String getProperty(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.

getProperty

public String getProperty(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.

getPropertyBaseName

protected static String getPropertyBaseName(String propertyName) 

Returns the 'base' name of the supplied property key name. For properties with an element number suffix (e.g. "subcomponent.1") this will be the text before the point and digit (e.g. "subcomponent") For all other property names this will be the same as the input String.

getPropertyInt

protected int getPropertyInt(String key) throws ConfigManagerProxyPropertyNotInitializedException

Returns a property value as an int. The information returned is "to the best of our knowledge", as the Configuration Manager may have recently updated the required property, but we are yet to receive an asynchronous update.

getRepositoryTimestamp

public Date getRepositoryTimestamp() throws ConfigManagerProxyPropertyNotInitializedException

Returns the most recent repository timestamp associated with this object. The timestamp is updated whenever the record associated with the object is updated inside the Configuration Manager's internal repository.

getShortDescription

public String getShortDescription() throws ConfigManagerProxyPropertyNotInitializedException

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

getTimeOfLastCompletionCode

public 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 Configuration Manager. If this field is null, this object has never received such a completion code.

getTimeOfLastUpdate

public GregorianCalendar getTimeOfLastUpdate() 

Returns the time that the object was last updated by a Configuration Manager publication. 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.

getType

public 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 parseable.

getUUID

public String getUUID() 

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

getUUIDOfParent

protected String getUUIDOfParent() 

Returns the UUID of the parent of this object (if the parent UUID has been implemented for the underlying object type).

hasBeenRestrictedByConfigManager

public boolean hasBeenRestrictedByConfigManager() 

Returns true if and only if the proxy has been told by the Configuration Manager that the object is not available for use by the current user. If the object has not yet received any update from the Configuration Manager, 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).

hasBeenRestrictedByConfigManager

public boolean hasBeenRestrictedByConfigManager(boolean waitIfNotUpdated) 

Returns true if and only if the proxy has been told by the Configuration Manager that the object is not available for use by the current user.

hasBeenUpdatedByConfigManager

public boolean hasBeenUpdatedByConfigManager() 

Returns true if and only if this object handle has received at least one update publication from the Configuration Manager. 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.

hasBeenUpdatedByConfigManager

public boolean hasBeenUpdatedByConfigManager(boolean waitIfNotUpdated) 

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

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 Configuration Manager.

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 Configuration Manager.

isDeployed

public boolean isDeployed() throws ConfigManagerProxyPropertyNotInitializedException

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.

isLastPropertyIdentifier

protected static boolean isLastPropertyIdentifier(String propertyName) 

Returns true if and only if the supplied property name is the last element identifier in a group of properties. For example, "subcomponent.3" will return false, "subcomponent" will return false, but "subcomponent.last" will return true.

isPartOfAPropertyGroup

protected static boolean isPartOfAPropertyGroup(String propertyName) 

Returns true if and only if the supplied property name is part of a set of related property elements. For example, "subcomponent.3" will return true, but "subcomponent" will return false. "subcomponent.last" will return true.

isShared

public boolean isShared() throws ConfigManagerProxyPropertyNotInitializedException

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 Configuration Manager Proxy application that has the relevant authority.

moveManagedSubcomponent

protected void moveManagedSubcomponent(Properties props,
                                       AdministeredObject newProxy) throws ConfigManagerProxyLoggedException, ConfigManagerProxyPropertyNotInitializedException

Atomically removes a managed subcomponent and adds it to the supplied instance (which must be of the same type).

Requires that a "batch" of operations (controlled using ConfigManagerProxy.beginUpdates(), clearUpdates() and sendUpdates() is NOT already in progress.

Simple checks are made to ensure that the source object doesn't equal the target object, that the child name is not the target, and that the new parent type is of the same type as this old parent.

HOWEVER... It is still possible to end up with circular references if you try to copy an object, say, into one of its children. Such a call may succeed and you might find that some objects in the hierarchy can no longer be referenced. Hence, care should be taken by the caller to ensure that this does not happen.

refresh

public void refresh() throws ConfigManagerProxyLoggedException

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

This method must not be called on Administered Objects that do not yet exist on the Configuration Manager (ie. objects initialized during a batch of creation requests).

registerListener

public void registerListener(AdministeredObjectListener listener) 

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

The listener will only be invoked after a message from the Configuration Manager is received by the Configuration Manager Proxy that states the current object has been modified or deleted, or if a previous action involving this object and originated by this Configuration Manager Proxy 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.

registerListener

public void registerListener(AdvancedAdministeredObjectListener listener) 

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

The listener will only be invoked after a message from the Configuration Manager is received by the Configuration Manager Proxy that states the current object has been modified or deleted, or if a previous action involving this object and originated by this Configuration Manager Proxy 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.

registerListener

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

Asks the Configuration Manager 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 Configuration Manager is received by the Configuration Manager Proxy that states the current object has been modified or deleted, or if a previous action involving this object and originated by this Configuration Manager Proxy 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 Configuration Manager, 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.

removeLocalProperty

protected void removeLocalProperty(String key) 

Removes the local property with the supplied name.

For attributes that do not begin "local." this call can only ever be made by the Receiver mechanism that will update the administeredObjectProperties object based on information supplied by the Configuration Manager.

Any attempt to use this call to set properties outside of the Receiver classes could result in confusing information being supplied to the caller and should therefore be avoided.

"local." attributes are used to store information that the Configuration Manager doesn't supply (such as the current userid, the proxy's version number etc.) Consequently these attributes can be set by anyone.

setIsAwaitingSubmissionForCreation

protected void setIsAwaitingSubmissionForCreation(boolean newValue) 

Sets the flag that describes whether the object is awaiting creation.

setIsAwaitingSubmissionForDeletion

protected void setIsAwaitingSubmissionForDeletion(boolean newValue) 

Sets the flag that describes whether the object is awaiting deletion.

setLastBIPMessages

protected void setLastBIPMessages(Vector lastBIPMessages) 

Sets the object's vector of BIP messages

setLastCompletionCode

protected void setLastCompletionCode(CompletionCodeType newCompletionCode) 

Sets the last completion code, and the corresponding 'time of last update' fields. This should be called by the AdministeredObjectPool. processResponse() method only, when it receives a Response of OperationType.actionresponse.

setLocalProperty

protected void setLocalProperty(String key,
                                String value) 

Updates the local property with the supplied value.

For attributes that do not begin "local." this call can only ever be made by the Receiver mechanism that will update the administeredObjectProperties object based on information supplied by the Configuration Manager.

Any attempt to use this call to set properties outside of the Receiver classes could result in confusing information being supplied to the caller and should therefore be avoided.

"local." attributes are used to store information that the Configuration Manager doesn't supply (such as the current userid, the proxy's version number etc.) Consequently these attributes can be set by anyone.

setLongDescription

public void setLongDescription(String desc) throws ConfigManagerProxyLoggedException

Helper method to set the long description field of the current Administered Object. If this method returns successfully the request will have been sent to the Configuration Manager (or batched for sending if a batch is in progress) but not necessarily processed by the Configuration Manager. Use an AdministeredObjectListener to discover the outcome of this request.

setName

public void setName(String name) throws ConfigManagerProxyLoggedException

Helper method to set the name of the Administered Object. If this method returns successfully the request will have been sent to the Configuration Manager (or batched for sending if a batch is in progress) but not necessarily processed by the Configuration Manager. Use an AdministeredObjectListener to discover the outcome of this request.

setProperties

public void setProperties(Properties suppliedProps) throws ConfigManagerProxyLoggedException

Asks the Configuration Manager to update a set of attributes for the current object. The Configuration Manager will be asked to set all attributes 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.NAME_PROPERTY, "B1");
 p.setProperty(AttributeConstants.LONG_DESCRIPTION_PROPERTY, "hello");
 broker1.setProperties(p);
 
will attempt to set the name and the long description of the administered object described by broker1.

Upon returning from this method, the request will have been sent to the Configuration Manager (or added to a batch if batch mode is enabled) but it will not have been necessarily serviced by the Configuration Manager. Callers should use AdministeredObjectListener instances to discover the results of this request.

setShortDescription

public void setShortDescription(String desc) throws ConfigManagerProxyLoggedException

Helper method to set the short description field of the Administered Object. If this method returns successfully the request will have been sent to the Configuration Manager (or batched for sending if a batch is in progress) but not necessarily processed by the Configuration Manager. Use an AdministeredObjectListener to discover the outcome of this request.

setTimeOfLastUpdate

protected void setTimeOfLastUpdate() 

Updates the field that contains the time the Configuration Manager Proxy last received an update notification.

Note that an update publication is not the same as an actionresponse to a request. Publications are sent by the Configuration Manager whenever an object gets updated. ActionResponses are the 'return codes' that get sent after we send the Configuration Manager a request. Rather unsurprisingly, this method should only be called from AdministeredObjectPool.processResponse() when it processes a publication notification.

toString

public 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.

toVerboseString

public String toVerboseString() 

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

unsubscribeFromConfigurationManagerUpdates

public void unsubscribeFromConfigurationManagerUpdates() 

Asks the Proxy to explicitly unsubscribe the current AdministeredObject from receiving future Configuration Manager updates. When this method completes, ALL AdministeredObjectListeners for this object will stop receiving messages regarding this object, and so this method should only be called if updates to the object are definitely NOT required by all callers using this ConfigManagerProxy connection.

After calling this method this AdministeredObject instance can no longer be used. If the logical parent of this object (e.g. the TopologyProxy if this object is a BrokerProxy) subsequently tries to retrieve the object to which this AdministeredObject refers, a new instance of the object will be returned which will be subscribed to updates from the Configuration Manager.

Using this method is not necessary for most applications, as objects are automatically unsubscribed when they go out of scope and are tidied by the JVM.

updateRestrictionFlag

protected void updateRestrictionFlag(boolean objectUnavailable) 

Updates the value of the restriction flag used by hasBeenRestrictedByConfigManager().

withName

public static Properties withName(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.

withUUID

public static Properties withUUID(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.

Class Hierarchy All Classes All Fields and Methods