com.ibm.able.platform
Class RmiPlatformSupportServiceSystem

java.lang.Object
  java.rmi.server.RemoteObject
      org.jagent.service.util.RMIBasicService
          com.ibm.able.platform.AbleBasicService
              com.ibm.able.platform.RmiPlatformSupportServiceSystem

All Implemented Interfaces:

AblePersistenceSupportProcessor, org.jagent.service.IPService, java.rmi.Remote, RmiAblePlatformService, RmiAblePlatformServiceEventGenerator, RmiPlatformSupportService, org.jagent.service.RMIService, java.io.Serializable, javax.agent.service.Service

public final class RmiPlatformSupportServiceSystem

extends AbleBasicService

implements RmiPlatformSupportService, AblePersistenceSupportProcessor

RmiPlatformSupportServiceSystem is the implementation of a Platform Support Service; see PlatformSupportService for details.

Since:

ABLE 2.2.0

See Also:

Serialized Form

Field Summary

Fields inherited from class com.ibm.able.platform.AbleBasicService

ANS_PRINCIPAL, LOCAL_PRINCIPAL, myAnsPrincipal, myKeyPair, myMsgLog, myPrincipal, mySecSppt, myServiceEventListeners, myServiceProperties, myTrcLog, myTrustLevel, myVerifiableAgentName, myVerifiableNamingService, Refreshing, REQUESTORS_PORT, Running, SOCKET_FACTORY, Terminated, Unknown

Fields inherited from class java.rmi.server.RemoteObject

ref

Fields inherited from interface org.jagent.service.RMIService

RMI, SERVICE_PROTOCOL

Fields inherited from interface org.jagent.service.IPService

SERVICE_HOST, SERVICE_PORT

Constructor Summary

RmiPlatformSupportServiceSystem()
Creates an instance of an RMI-based Platform Support Service.

RmiPlatformSupportServiceSystem(javax.agent.service.ServiceProperties theServiceProperties)
Creates an instance of an RMI-based Platform Support Service, using the specified service properties.

Method Summary

void	addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Adds a service event listener to this service, and, if persistence is on, adds the listener to persistence store.
java.lang.String	getBindingName()
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	refreshLocalFromPersistence(AblePersistenceSupport thePersistenceSupport, java.lang.Object[] thePersistedRecords) Takes the persisted Objects that are read in, and sets them locally.
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, and, if persistence is on, removes the listener from persistence store.
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) When this service is terminated, there will be Verifiable Directory specific cleanup that needs to be done.

Methods inherited from class com.ibm.able.platform.AbleBasicService

getAblePlatformServiceEventListeners, getState, notifyAblePlatformServiceEventListeners, setState, thenNotifyAblePlatformServiceEventListeners

Methods inherited from class org.jagent.service.util.RMIBasicService

bindServiceToRegistry, getServiceProperties, setServiceProperties, shutdown

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.ibm.able.platform.RmiAblePlatformService

getState

Methods inherited from interface com.ibm.able.platform.RmiAblePlatformServiceEventGenerator

getAblePlatformServiceEventListeners

Constructor Detail

RmiPlatformSupportServiceSystem

public RmiPlatformSupportServiceSystem()
                                throws java.lang.Exception

Creates an instance of an RMI-based Platform Support Service.

Throws:

java.lang.Exception - On any error.

RmiPlatformSupportServiceSystem

public RmiPlatformSupportServiceSystem(javax.agent.service.ServiceProperties theServiceProperties)
                                throws java.lang.Exception

Creates an instance of an RMI-based Platform Support Service, using the specified service properties.

Parameters:

theServiceProperties - Service properties on which the service is based.

Throws:

java.lang.Exception - On any error.

Method Detail

getBindingName

public java.lang.String getBindingName()

addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                         throws AbleException

Adds a service event listener to this service, and, if persistence is on, adds the listener to persistence store.

Specified by:

addAblePlatformServiceEventListener in interface RmiAblePlatformServiceEventGenerator

Overrides:

addAblePlatformServiceEventListener in class AbleBasicService

Parameters:

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

Throws:

AbleException - On any error adding the listener.

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                            throws AbleException

Removes a service event listener from this service, and, if persistence is on, removes the listener from persistence store.

Specified by:

removeAblePlatformServiceEventListener in interface RmiAblePlatformServiceEventGenerator

Overrides:

removeAblePlatformServiceEventListener in class AbleBasicService

Parameters:

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

Throws:

AbleException - On any error removing the listener.

terminateService

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

When this service is terminated, there will be Verifiable Directory specific cleanup that needs to be done. AbleBasicService's terminateService method has been overridden to take care of this cleanup.

Since this service is persisting information, it's persistence support Object will do some cleanup when being terminated.

Specified by:

terminateService in interface RmiAblePlatformService

Overrides:

terminateService in class AbleBasicService

Parameters:

theSecureKey - If security is on, the key used to secure this communication; otherwise, null.

Throws:

AbleException - If the caller is not authorized to make this call.

javax.agent.service.naming.NamingException - On all naming errors.

quiesceAgentPool

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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.

java.rmi.RemoteException - On any RMI error.

recoverAgentPool

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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.

java.rmi.RemoteException

terminateAgentPool

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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:

java.rmi.RemoteException - On any RMI error.

PlatformSupportServiceException - On any platform support error.

terminatePlatform

public void terminatePlatform(AbleSecureKey theSecureKey)
                       throws java.rmi.RemoteException,
                              PlatformSupportServiceException

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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:

java.rmi.RemoteException - On any RMI error.

PlatformSupportServiceException - On any platform support error.

refreshAgentPoolPreferences

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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.

java.rmi.RemoteException - On any RMI error.

refreshAgentPoolPreferences

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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:

java.rmi.RemoteException - On any RMI error.

PlatformSupportServiceException - On any platform support error.

refreshAgentPoolPreferencesFromFileLocalToAgentPool

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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.

java.rmi.RemoteException - On any RMI error.

refreshAgentPoolPreferencesFromFileLocalToService

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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:

java.rmi.RemoteException - On any RMI error.

PlatformSupportServiceException - On any platform support error.

refreshPlatformPreferences

public void refreshPlatformPreferences(AbleSecureKey theSecureKey)
                                throws java.rmi.RemoteException,
                                       PlatformSupportServiceException

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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:

java.rmi.RemoteException - On any RMI error.

PlatformSupportServiceException - On any platform support error.

refreshPlatformPreferences

public void refreshPlatformPreferences(AblePlatformPreferences thePlatformPreferences,
                                       AbleSecureKey theSecureKey)
                                throws java.rmi.RemoteException,
                                       PlatformSupportServiceException

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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:

java.rmi.RemoteException - On any RMI error.

PlatformSupportServiceException - On any platform support error.

refreshPlatformPreferencesFromFileLocalToAgentPool

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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.

java.rmi.RemoteException - On any RMI error.

refreshPlatformPreferencesFromFileLocalToService

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

Description copied from interface: RmiPlatformSupportService

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 RmiPlatformSupportService

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:

java.rmi.RemoteException - On any RMI error.

PlatformSupportServiceException - On any platform support error.

refreshLocalFromPersistence

public void refreshLocalFromPersistence(AblePersistenceSupport thePersistenceSupport,
                                        java.lang.Object[] thePersistedRecords)
                                 throws java.lang.Exception

Description copied from interface: AblePersistenceSupportProcessor

Takes the persisted Objects that are read in, and sets them locally.

This method is called one time during the lifetime of this AblePersistenceSupportProcessor Object. This method will be called the first time a successful connection is made to the PlatformPersistenceService and the persisted Objects are read in.

Specified by:

refreshLocalFromPersistence in interface AblePersistenceSupportProcessor

Parameters:

thePersistenceSupport - the object making the callback so that the processor can tell which AblePersistenceSupport object is making the call.

thePersistedRecords - Object[] containing all of the rows of the table this Object persists to.

Throws:

java.lang.Exception - On any error locally restoring the persisted data.