com.ibm.able.platform
Class RmiPlatformSupportServiceProxy

java.lang.Object
  com.ibm.able.platform.RmiPlatformSupportServiceProxy

All Implemented Interfaces:

AblePlatformService, AblePlatformServiceEventGenerator, PlatformSupportService, java.io.Serializable, javax.agent.service.Service

public class RmiPlatformSupportServiceProxy

extends java.lang.Object

implements PlatformSupportService, java.io.Serializable

An RMI Platform Support Service Proxy contains a reference to an RMI version of a Platform Support Service (known as the delegate); the proxy contains methods identical to the methods in the actual service such that when a method is called on the proxy, the proxy forwards the call on to the actual service, but the proxy:

1. traps all RemoteExceptions that might be thrown by the service,
2. turns the RemoteExceptions into PlatformSupportService exceptions, and then
3. rethrows the new exception.

In this way, code making use of the proxy does not have to be sensitive to RMI RemoteExceptions and can code to a common Platform Support Service interface.

Since:

ABLE 2.2.0

See Also:

Serialized Form

Field Summary

Fields inherited from interface com.ibm.able.platform.PlatformSupportService

COLUMN_NAMES, COLUMN_TYPES, SERVICE_TYPE, ServiceEventListener

Constructor Summary

RmiPlatformSupportServiceProxy(RmiPlatformSupportService theDelegate, java.rmi.registry.Registry theRegistry, java.lang.String theAddress)
Creates a proxy over the specified RMI reference to a Platform Support Service.

Method Summary

void	addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Adds a service event listener to this service.
java.util.Vector	getAblePlatformServiceEventListeners() Gets a collection of all service event listeners registered with this service event generator.
javax.agent.service.ServiceProperties	getServiceProperties() Gets the service properties of the underlying service.
int	getState() Returns the state of this service.
void	quiesceAgentPool(java.lang.String theAgentPoolAlias, AbleSecureKey theSecureKey) Quiesces the specified agent pool by sending a quitAgent to each agent known to be running in the pool.
void	recoverAgentPool(java.lang.String theAgentPoolAlias, AbleSecureKey theSecureKey) Recovers the specified agent pool by recreating agents and services that are to be running there.
void	refreshAgentPoolPreferences(java.lang.String theAgentPoolAlias, AblePlatformPreferences thePlatformPreferences, AbleSecureKey theSecureKey) Refreshes the specified agent pool's platform preferences from a specified platform preference object.
void	refreshAgentPoolPreferences(java.lang.String theAgentPoolAlias, AbleSecureKey theSecureKey) Refreshes the specified agent pool's platform preferences from a file that has first been securely distributed to the system containing that agent pool.
void	refreshAgentPoolPreferencesFromFileLocalToAgentPool(java.lang.String theAgentPoolAlias, java.lang.String theFileName, AbleSecureKey theSecureKey) Refreshes the specified agent pool's platform preferences from a file that has first been distributed to the system containing that agent pool.
void	refreshAgentPoolPreferencesFromFileLocalToService(java.lang.String theAgentPoolAlias, java.lang.String theFileName, AbleSecureKey theSecureKey) Refreshes the specified agent pool's platform preferences from a file that has first been distributed to the system containing the agent pool running the Platform Support Service.
void	refreshPlatformPreferences(AblePlatformPreferences thePlatformPreferences, AbleSecureKey theSecureKey) Refreshes every agent pool's platform preferences from a specified platform preference object.
void	refreshPlatformPreferences(AbleSecureKey theSecureKey) Refreshes every agent pool's platform preferences from a file that has first been securely distributed to every system that contains an agent pool.
void	refreshPlatformPreferencesFromFileLocalToAgentPool(java.lang.String theFileName, AbleSecureKey theSecureKey) Refreshes every agent pool's platform preferences from a file that has first been distributed to each system containing an agent pool.
void	refreshPlatformPreferencesFromFileLocalToService(java.lang.String theFileName, AbleSecureKey theSecureKey) Refreshes every agent pool's platform preferences from a file that has first been distributed to the system containing the agent pool running the Platform Support Service.
void	removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Removes a service event listener from this service.
void	setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties) Sets the service properties of the underlying service.
void	terminateAgentPool(java.lang.String theAgentPoolAlias, AbleSecureKey theSecureKey) Terminates the specified agent pool by killing it's JVM.
void	terminatePlatform(AbleSecureKey theSecureKey) Terminates all known agent pools across the entire platform by killing their JVMs.
void	terminateService(AbleSecureKey theSecureKey) Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.
java.lang.String	toString() Gets a string describing the contents of the object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RmiPlatformSupportServiceProxy

public RmiPlatformSupportServiceProxy(RmiPlatformSupportService theDelegate,
                                      java.rmi.registry.Registry theRegistry,
                                      java.lang.String theAddress)

Creates a proxy over the specified RMI reference to a Platform Support Service.

Parameters:

theDelegate - A reference to an RMI version of a Platform Support Service.

theRegistry - The RMI registry at which the above Platform Support Service is registered.

theAddress - The RMI address at which the above Platform Support Service is registered.

Method Detail

getServiceProperties

public javax.agent.service.ServiceProperties getServiceProperties()

Gets the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; null is always returned.

Specified by:

getServiceProperties in interface javax.agent.service.Service

Returns:

null at all times.

setServiceProperties

public void setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties)

Sets the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; the call is simply ignored.

Specified by:

setServiceProperties in interface javax.agent.service.Service

Parameters:

theServiceProperties - The service properties to be used by the service.

quiesceAgentPool

public void quiesceAgentPool(java.lang.String theAgentPoolAlias,
                             AbleSecureKey theSecureKey)
                      throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Quiesces the specified agent pool by sending a quitAgent to each agent known to be running in the pool.

Note that there is nothing that prevents new agents from being created in the pool during the time the pool is being quiesced.

Specified by:

quiesceAgentPool in interface PlatformSupportService

Parameters:

theAgentPoolAlias - The name of an agent pool defined in the platform preference file.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

recoverAgentPool

public void recoverAgentPool(java.lang.String theAgentPoolAlias,
                             AbleSecureKey theSecureKey)
                      throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Recovers the specified agent pool by recreating agents and services that are to be running there.

AgentLifeCycleService is used to recreate any agents that it originally created in the pool. AblePlatformSupport is used to recreate any services that were originally running in the pool. If persistence was active for a service, that service should recover itself nicely.

Specified by:

recoverAgentPool in interface PlatformSupportService

Parameters:

theAgentPoolAlias - The name of an agent pool defined in the platform preference file.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

terminateAgentPool

public void terminateAgentPool(java.lang.String theAgentPoolAlias,
                               AbleSecureKey theSecureKey)
                        throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Terminates the specified agent pool by killing it's JVM. First, any agents running in the agent pool are quiesced; next, any services running in the agent pool are terminated gracefully; finally, the JVM is killed.

Specified by:

terminateAgentPool in interface PlatformSupportService

Parameters:

theAgentPoolAlias - The name of an agent pool defined in the platform preference file.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

terminatePlatform

public void terminatePlatform(AbleSecureKey theSecureKey)
                       throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Terminates all known agent pools across the entire platform by killing their JVMs. Each agent pool is examined in turn. First, any agents running in the agent pool are quiesced; next, any services running in the agent pool are terminated gracefully; finally, the agent pool's JVM is killed and the next agent pool is examined. Note that the agent pools containing the AgentLifeCycle and AgentNaming services are always terminated last.

Specified by:

terminatePlatform in interface PlatformSupportService

Parameters:

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

refreshAgentPoolPreferences

public void refreshAgentPoolPreferences(java.lang.String theAgentPoolAlias,
                                        AbleSecureKey theSecureKey)
                                 throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Refreshes the specified agent pool's platform preferences from a file that has first been securely distributed to the system containing that agent pool. The file that is read is the same file that was read when the agent pool was originally started; that is, the file's name is ableplatform.preferences and the file's location is at the place specified by the system property able.prefdir.

Specified by:

refreshAgentPoolPreferences in interface PlatformSupportService

Parameters:

theAgentPoolAlias - The name of an agent pool defined in the platform preference file.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

refreshAgentPoolPreferences

public void refreshAgentPoolPreferences(java.lang.String theAgentPoolAlias,
                                        AblePlatformPreferences thePlatformPreferences,
                                        AbleSecureKey theSecureKey)
                                 throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Refreshes the specified agent pool's platform preferences from a specified platform preference object. The new preferences are not saved to disk, and so are effective only for the current session.

Note that when security is enabled, this method ultimately has no effect, because the AblePlatformPreference class is not currently able to verify and authorise callers; therefore it ignores calls that can be used to alter the platform in a malicious way.

Specified by:

refreshAgentPoolPreferences in interface PlatformSupportService

Parameters:

theAgentPoolAlias - The name of an agent pool defined in the platform preference file.

thePlatformPreferences - A platform preference object containing a new set of preferences.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

refreshAgentPoolPreferencesFromFileLocalToAgentPool

public void refreshAgentPoolPreferencesFromFileLocalToAgentPool(java.lang.String theAgentPoolAlias,
                                                                java.lang.String theFileName,
                                                                AbleSecureKey theSecureKey)
                                                         throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Refreshes the specified agent pool's platform preferences from a file that has first been distributed to the system containing that agent pool. The complete path name to the file must be specified. The new preferences are not saved to the original startup preference file, and so are effective only for the current session.

Note that when security is enabled, this method ultimately has no effect, because the AblePlatformPreference class is not currently able to verify and authorise callers; therefore it ignores calls that can be used to alter the platform in a malicious way.

Specified by:

refreshAgentPoolPreferencesFromFileLocalToAgentPool in interface PlatformSupportService

Parameters:

theAgentPoolAlias - The name of an agent pool defined in the platform preference file.

theFileName - The complete name (including path) of a file that contains a valid set of ABLE platform preference specifications.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

refreshAgentPoolPreferencesFromFileLocalToService

public void refreshAgentPoolPreferencesFromFileLocalToService(java.lang.String theAgentPoolAlias,
                                                              java.lang.String theFileName,
                                                              AbleSecureKey theSecureKey)
                                                       throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Refreshes the specified agent pool's platform preferences from a file that has first been distributed to the system containing the agent pool running the Platform Support Service. The complete path name to the file must be specified. The new preferences are not saved to the original startup preference file, and so are effective only for the current session.

Note that when security is enabled, this method ultimately has no effect, because the AblePlatformPreference class is not currently able to verify and authorise callers; therefore it ignores calls that can be used to alter the platform in a malicious way.

Specified by:

refreshAgentPoolPreferencesFromFileLocalToService in interface PlatformSupportService

Parameters:

theAgentPoolAlias - The name of an agent pool defined in the platform preference file.

theFileName - The complete name (including path) of a file that contains a valid set of ABLE platform preference specifications.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

refreshPlatformPreferences

public void refreshPlatformPreferences(AbleSecureKey theSecureKey)
                                throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Refreshes every agent pool's platform preferences from a file that has first been securely distributed to every system that contains an agent pool. The file that is read is the same file that was read when each agent pool was originally started; that is, the file's name is ableplatform.preferences and the file's location is at the place specified by the system property able.prefdir.

Specified by:

refreshPlatformPreferences in interface PlatformSupportService

Parameters:

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

refreshPlatformPreferences

public void refreshPlatformPreferences(AblePlatformPreferences thePlatformPreferences,
                                       AbleSecureKey theSecureKey)
                                throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Refreshes every agent pool's platform preferences from a specified platform preference object. The new preferences are not saved to disk, and so are effective only for the current session.

Note that when security is enabled, this method ultimately has no effect, because the AblePlatformPreference class is not currently able to verify and authorise callers; therefore it ignores calls that can be used to alter the platform in a malicious way.

Specified by:

refreshPlatformPreferences in interface PlatformSupportService

Parameters:

thePlatformPreferences - A platform preference object containing a new set of preferences.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

refreshPlatformPreferencesFromFileLocalToAgentPool

public void refreshPlatformPreferencesFromFileLocalToAgentPool(java.lang.String theFileName,
                                                               AbleSecureKey theSecureKey)
                                                        throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Refreshes every agent pool's platform preferences from a file that has first been distributed to each system containing an agent pool. The complete path name to the file must be specified and it must be the same for every agent pool. The new preferences are not saved to the original startup preference file, and so are effective only for the current session.

Note that when security is enabled, this method ultimately has no effect, because the AblePlatformPreference class is not currently able to verify and authorise callers; therefore it ignores calls that can be used to alter the platform in a malicious way.

Specified by:

refreshPlatformPreferencesFromFileLocalToAgentPool in interface PlatformSupportService

Parameters:

theFileName - The complete name (including path) of a file that contains a valid set of ABLE platform preference specifications.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

refreshPlatformPreferencesFromFileLocalToService

public void refreshPlatformPreferencesFromFileLocalToService(java.lang.String theFileName,
                                                             AbleSecureKey theSecureKey)
                                                      throws PlatformSupportServiceException

Description copied from interface: PlatformSupportService

Refreshes every agent pool's platform preferences from a file that has first been distributed to the system containing the agent pool running the Platform Support Service. The complete path name to the file must be specified. The new preferences are not saved to the original startup preference file, and so are effective only for the current session.

Note that when security is enabled, this method ultimately has no effect, because the AblePlatformPreference class is not currently able to verify and authorise callers; therefore it ignores calls that can be used to alter the platform in a malicious way.

Specified by:

refreshPlatformPreferencesFromFileLocalToService in interface PlatformSupportService

Parameters:

theFileName - The complete name (including path) of a file that contains a valid set of ABLE platform preference specifications.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:

PlatformSupportServiceException - On any platform support error.

terminateService

public void terminateService(AbleSecureKey theSecureKey)
                      throws AbleException,
                             javax.agent.service.naming.NamingException

Description copied from interface: AblePlatformService

Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.

Specified by:

terminateService in interface AblePlatformService

Parameters:

theSecureKey - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.

Throws:

javax.agent.service.naming.NamingException - On any naming error.

AbleException - On any remote error or Able error.

getState

public int getState()
             throws AbleException

Description copied from interface: AblePlatformService

Returns the state of this service.

Specified by:

getState in interface AblePlatformService

Returns:

The state of this service.

Throws:

AbleException - On any remote error or Able error.

addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                         throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Adds a service event listener to this service.

Specified by:

addAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator

Parameters:

theListener - Any object interested in listening for service events generated by this service.

Throws:

AbleException - If the listener to be added is null, or on any error.

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                            throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Removes a service event listener from this service.

Specified by:

removeAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator

Parameters:

theListener - A previously registered object that is no longer interested in listening for service events generated by this service.

Throws:

AbleException - If the listener to be removed is null, or on any error.

getAblePlatformServiceEventListeners

public java.util.Vector getAblePlatformServiceEventListeners()
                                                      throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Gets a collection of all service event listeners registered with this service event generator.

Specified by:

getAblePlatformServiceEventListeners in interface AblePlatformServiceEventGenerator

Returns:

All registered AblePlatformServiceEventListener objects.

Throws:

AbleException - On any error.

toString

public java.lang.String toString()

Gets a string describing the contents of the object.

Returns:

A string containing the current contents of the object.