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:
BrokerProxy b = topol.getBrokerByName("myBroker");
boolean showGreenLight = b.isRunning();
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 }
AdministeredObjectListener myListener = new MyAdministeredObjectListener(); // Interested in changes to broker 'b' b.registerListener( myListener );
// After this call, myListener will no longer be informed of any changes to 'b'. b.deregisterListener( myListener );
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 |
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 | Description |
---|---|
AdministeredObject(AdministeredObjectPool) | Initialises a new AdministeredObject AdministeredObjects can only be created by the AdministeredObjectPool. |
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. |
protected static long baseRetryWaitTimeThe initial time to wait between retries (in milliseconds)
protected static final java.lang.String copyrightIBM Copyright
protected static final java.lang.String LOCAL_ATTRIBUTE_IDENTIFIERThis 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).
protected static long maxRetriesAs 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.
protected com.ibm.broker.config.proxy.AdministeredObjectPool owningPoolThe AdministeredObjectPool that was responsible for creating this object. Also, it is this pool that is queried for the subcomponents of the current AdministeredObject.
protected java.util.Vector potentialNewSubcomponentsA 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?).
protected static long retryWaitTimeIncrementHow much to increase the retry wait time by after each consecutive failure.
protected static final java.lang.String sccsidVersion information
protected java.util.Vector subcomponentsToBeSubmittedForCreationInCurrentBatchA 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.
protected static final java.lang.String UUID_DELIMITERShorthand for the string used to separate the type parameter from the UUID parameter in the subcomponent properties.
protected AdministeredObject(AdministeredObjectPool creator)Initialises a new AdministeredObject AdministeredObjects can only be created by the AdministeredObjectPool.
protected void clearPredictedNewSubcomponents()Clears the vector of predicted new subcomponents.
protected AdministeredObject createManagedSubcomponent(Properties suppliedProps) throws ConfigManagerProxyLoggedExceptionAsks 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).
- Parameters
- suppliedProps - required attributes of the new object. Must contain at least CommsMessageConstants.CHILD_TYPE_PROPERTY and CommsMessageConstants.CHILD_UUID_PROPERTY values.
- Returns
- AdministeredObject that can be used to reference the newly created object. If the subcomponent is not instantiable (e.g. a connection between two brokers) then null is returned.
- Throws
ConfigManagerProxyLoggedException
if the request to create a new subcomponent could not be sent to the Configuration Manager.
protected void deleteManagedSubcomponents(Properties suppliedProps) throws ConfigManagerProxyLoggedExceptionAsks 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).
- Returns
- Properties the filter which will be used to identify which objects to delete. Must contain at least CommsMessageConstants.CHILD_TYPE_PROPERTY and CommsMessageConstants.CHILD_UUID_PROPERTY values.
- Throws
ConfigManagerProxyLoggedException
if the request to delete the subcomponent could not be sent to the Configuration Manager.
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.
- Parameters
- listener - the object that will no longer be notified of any events
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.
- Parameters
- listener - the object that will no longer be notified of any events
protected void doAddAccessControlEntries(AccessControlEntry[] accessControlList) throws ConfigManagerProxyLoggedExceptionAdds 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.
- Parameters
- accessControlList - Array of access control entries which are to be added to this object.
- Throws
ConfigManagerProxyLoggedException
if the request to update the object could not be sent to the Configuration Manager.
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.
- Returns
- AccessControlEntry[] array of AccessControlEntry objects that apply to this object.
- Throws
ConfigManagerProxyPropertyNotInitializedException
if this objects list of Access Control Entries was not supplied by the Configuration Manager before a timeout occurred.
protected void doRemoveAccessControlEntries(AccessControlEntry[] accessControlList) throws ConfigManagerProxyLoggedExceptionDeletes 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.
- Parameters
- accessControlList - Array of access control entries which are to be removed from this object.
- Throws
ConfigManagerProxyLoggedException
if the request to update the object could not be sent to the Configuration Manager.
protected void doSetAccessControlEntries(AccessControlEntry[] accessControlList) throws ConfigManagerProxyLoggedExceptionSets 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.
- Parameters
- accessControlList - Array of access control entries which are to apply to this object.
- Throws
ConfigManagerProxyLoggedException
if the request to update the object could not be sent to the Configuration Manager.- Throws
ConfigManagerProxyPropertyNotInitializedException
if this objects current list of Access Control Entries was not supplied by the Configuration Manager before a timeout occurred.
public int elements(String key) throws ConfigManagerProxyPropertyNotInitializedExceptionFor 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.
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.
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.
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.
- Returns
- Vector of com.ibm.broker.config.proxy.LogEntry objects. The vector may be empty or null.
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 createNote, 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.
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.
- Returns
- String a userid
public String getLongDescription() throws ConfigManagerProxyPropertyNotInitializedExceptionHelper method to return the long description field for the current Administered Object.
- Returns
- String description string.
- Throws
ConfigManagerProxyPropertyNotInitializedException
if the requested property is not yet known.
public AdministeredObject getManagedSubcomponent(Properties props) throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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 Config Manager has not yet supplied them.
public AdministeredObject getManagedSubcomponentFromStringRepresentation(String representation) throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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 or if the object could not be found.
- Throws
ConfigManagerProxyPropertyNotInitializedException
if this object's subcomponent information had not been supplied by the Configuration Manager before a timeout occurred.
public Enumeration getManagedSubcomponents(Properties filter) throws ConfigManagerProxyPropertyNotInitializedExceptionAsks 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.
- 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 the list of available subcomponents could not be determined because the Config Manager has not yet supplied them.
public Enumeration getManagedSubcomponents(Properties filter, boolean returnContainsStrings) throws ConfigManagerProxyPropertyNotInitializedExceptionAsks 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.
- 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 the list of available subcomponents could not be determined because the Config Manager has not yet supplied them.
public Enumeration getManagedSubcomponents(Properties filter, boolean returnContainsStrings, Properties initialPropertiesOfNewObject) throws ConfigManagerProxyPropertyNotInitializedExceptionAsks 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.
- 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 Config Manager has not yet supplied them.
public String getName() throws ConfigManagerProxyPropertyNotInitializedExceptionReturns the name of the object
- Returns
- String name of the current object.
- Throws
ConfigManagerProxyPropertyNotInitializedException
if the property could not be determined because the Config Manager has not yet supplied the relevant information.
public int getNumberOfSubcomponents() throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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 Configuration Manager by the time a timeout occurred.
public AdministeredObject getParent() throws ConfigManagerProxyLoggedExceptionReturns 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 Configuration Manager, but the request could not be sent to the Configuration Manager.
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.
- Returns
- Properties where each key contains a String based attribute name for the current object and each value contains the attribute's value.
public String getProperty(String key) throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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.
- 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 Configuration Manager. If this is the case, this method will issue retries in accordance with the retry characteristics set by the ConfigManagerProxy.setRetryCharacteristics() method. Only after these retries have been exhausted will the ConfigManagerProxyPropertyNotInitializedException be thrown.
public String getProperty(String key, boolean waitIfNotAvailable) throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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.
- 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 Configuration Manager the method will wait for the length of time described by ConfigManagerProxy.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 Configuration Manager. 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 ConfigManagerProxy.setRetryCharacteristics() method. Only after these retries have been exhausted will the ConfigManagerProxyPropertyNotInitializedException be thrown. If the information has not yet been supplied by the Configuration Manager and the value of waitIfNotAvailable is false, this method will throw a ConfigManagerProxyPropertyNotInitializedException immediately.
protected String getProperty(String key, boolean waitIfNotAvailable, boolean ignoreExceptions) throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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.
- 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 Configuration Manager the method will wait for the length of time described by ConfigManagerProxy.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.
- ignoreExceptions - If and only if this is true, no ConfigManagerProxyPropertyNotInitializedExceptions will be thrown. In this case, if the required information is not available, null will be returned.
- 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 Configuration Manager. 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 ConfigManagerProxy.setRetryCharacteristics() method. Only after these retries have been exhausted will the ConfigManagerProxyPropertyNotInitializedException be thrown. If the information has not yet been supplied by the Configuration Manager and the value of waitIfNotAvailable is false, this method will throw a ConfigManagerProxyPropertyNotInitializedException immediately.If ignoreExceptions is set to true, the exception will never be thrown. In this case, if the information is not available then null will be returned. If ignoreExceptions is set to false, the normal algorithm for throwing a ConfigManagerProxyPropertyNotInitializedException applies.
public String getProperty(String key, int element) throws ConfigManagerProxyPropertyNotInitializedExceptionFor 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
public String getProperty(String key, int element, boolean waitIfNotAvailable) throws ConfigManagerProxyPropertyNotInitializedExceptionFor 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 Configuration Manager the method will wait for the length of time described by ConfigManagerProxy.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
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.
- Parameters
- propertyName - key whose base name is sought
- Returns
- String containing the base key name
protected int getPropertyInt(String key) throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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.
- Parameters
- key - The name of the property to find. Use the AttributeConstants.*_PROPERTY constants here.
- Returns
- int representing the value of the property or -1 if the property could not be found or was not a parseable number.
- Throws
ConfigManagerProxyPropertyNotInitializedException
if, due to the administered object not having been updated by the Configuration Manager yet, the value of the requested property is unknown. If a failure occurs this method will issue retries in accordance with the retry characteristics set by the ConfigManagerProxy.setRetryCharacteristics() method. Only after these retries have been exhausted will the ConfigManagerProxyPropertyNotInitializedException be thrown.
public Date getRepositoryTimestamp() throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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.
- Returns
- Date the time of the last modification, or null if the information is not available.
- Throws
ConfigManagerProxyPropertyNotInitializedException
if a timestamp might exist, but the object's information has not yet been supplied by the Configuration Manager.
public String getShortDescription() throws ConfigManagerProxyPropertyNotInitializedExceptionHelper 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.
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.
- Returns
- GregorianCalendar of the time the object's completion code field was last updated.
- See Also
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.
- Returns
- GregorianCalendar of the time the object was last updated. The value will be null if the object has never received an update.
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.
- Returns
- String The name of this AdministeredObject type.
public String getUUID()Convenience method to return the unique identifier of this administered object.
- Returns
- String The UUID of this AdministeredObject
protected String getUUIDOfParent()Returns the UUID of the parent of this object (if the parent UUID has been implemented for the underlying object type).
- Returns
- String
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).
- Returns
- boolean true if and only if the object is NOT available
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.
- Parameters
- waitIfNotUpdated - If this is set to true and the administered object has not yet received an update from the Configuration Manager, 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 Configuration Manager 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 Configuration Manager 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 Configuration Manager, the call will return immediately.
- Returns
- boolean true if and only if the object is NOT available
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.
- Returns
- boolean true if the object has had at least one update by the Configuration Manager, false otherwise.
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.
- 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 Configuration Manager, false otherwise.
- See Also
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.
- Returns
- true if the object is awaiting submission for creation.
- See Also
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.
- Returns
- true if the object is awaiting submission for deletion.
- See Also
public boolean isDeployed() throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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.
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.
- Parameters
- propertyName - to be checked
- Returns
- boolean true if the property is a last property identifier.
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.
- Parameters
- propertyName - to be checked
- Returns
- boolean true if the property ends in a digit.
public boolean isShared() throws ConfigManagerProxyPropertyNotInitializedExceptionReturns 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.
- Returns
- boolean true if the object is shared.
- Throws
ConfigManagerProxyPropertyNotInitializedException
if the required information has not been supplied by the Configuration Manager.
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.
- Parameters
- props - Properties uniquely describing the attributes of the subcomponent to remove from this object (e.g. UUID and Type).
- newProxy - The object to which the child should be moved to.
- Throws
ConfigManagerProxyPropertyNotInitializedException
if the topic corresponding to the supplied name could not be loaded because information on the parent object (i.e. this) has not yet been supplied.- Throws
ConfigManagerProxyLoggedException
if the object with the supplied properties does not exist as a child of the current topic, if a batch of requests was already in progress, if the child and the target are the same, if the target is the same as the current object, or if the source and target objects are of different types, if the target object is null, or if the message to move could not be sent to the Configuration Manager.
public void refresh() throws ConfigManagerProxyLoggedExceptionForces 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).
- Throws
ConfigManagerProxyLoggedException
if the request to refresh the object could not be sent to the Configuration Manager.
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.
- Parameters
- listener - the object that will be notified of any events on the current AdministeredObject.
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.
- Parameters
- listener - the object that will be notified of any events on the current AdministeredObject.
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.
- 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 Configuration Manager. 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.
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.
- Parameters
- key - The name of the property to set. Use the AttributeConstants.*_PROPERTY constants here.
protected void setIsAwaitingSubmissionForCreation(boolean newValue)Sets the flag that describes whether the object is awaiting creation.
- Parameters
- newValue - New value for the isAwaitingSubmissionForCreation flag.
protected void setIsAwaitingSubmissionForDeletion(boolean newValue)Sets the flag that describes whether the object is awaiting deletion.
- Parameters
- newValue - New value for the isAwaitingSubmissionForDeletion flag.
protected void setLastBIPMessages(Vector lastBIPMessages)Sets the object's vector of BIP messages
- Parameters
- lastBIPMessages - of com.ibm.broker.config.proxy.LogEntry objects. The vector may be empty or null.
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.
- Parameters
- newCompletionCode - the outcome of the operation being processed.
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.
- Parameters
- key - The name of the property to set. Use the AttributeConstants.*_PROPERTY constants here.
- value - The value to set the property to.
public void setLongDescription(String desc) throws ConfigManagerProxyLoggedExceptionHelper 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.
- Parameters
- desc - New description string.
- Throws
ConfigManagerProxyLoggedException
if the request could not be sent to the Configuration Manager.
public void setName(String name) throws ConfigManagerProxyLoggedExceptionHelper 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.
- Parameters
- name - New name.
- Throws
ConfigManagerProxyLoggedException
if the request could not be sent to the Configuration Manager.
public void setProperties(Properties suppliedProps) throws ConfigManagerProxyLoggedExceptionAsks 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.
- Parameters
- suppliedProps - the attributes that the caller wishes to set
- Throws
ConfigManagerProxyLoggedException
if the request could not be sent to the Configuration Manager.
public void setShortDescription(String desc) throws ConfigManagerProxyLoggedExceptionHelper 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.
- Parameters
- desc - New description string.
- Throws
ConfigManagerProxyLoggedException
if the request could not be sent to the Configuration Manager.
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.
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.
- Returns
- String Representation of the current object
- Overrides
- toString in class Object
public String toVerboseString()Displays the list of all properties currently associated with this administered object.
- Returns
- String Representation of the current object
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.
protected void updateRestrictionFlag(boolean objectUnavailable)Updates the value of the restriction flag used by hasBeenRestrictedByConfigManager().
- Parameters
- objectUnavailable - new restriction status (true if and only if the object is NOT available)
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.
- Parameters
- name -
- Returns
- Properties a new Properties object with the relevant key/value pairs set.
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.
- Parameters
- uuid -
- Returns
- Properties a new Properties object with the UUID property set. to the supplied value.