com.ibm.able.platform
Interface PlatformSupportService

All Superinterfaces:

AblePlatformService, AblePlatformServiceEventGenerator, javax.agent.service.Service

All Known Implementing Classes:

RmiPlatformSupportServiceProxy

public interface PlatformSupportService

extends javax.agent.service.Service, AblePlatformService

The PlatformSupportService interface defines the operations that can be requested of a Platform Support Service.

A Platform Support Service can be used to:

• Refresh platform preferences in a specified agent pool.
• Refresh platform preferences in all agent pools across the entire platform.
• Quiesce all agents running in a specified agent pool.
• Terminate a specified agent pool: quiesce all agents in the pool, terminate all services running in the agent pool, and kill the JVM containing the agent pool.
• Terminate all agent pools across the entire platform.

Since:

ABLE 2.2.0

Field Summary

static java.lang.String[]	COLUMN_NAMES The table's column names and types that this service will persist to.
static java.lang.String[]	COLUMN_TYPES
static java.lang.String	SERVICE_TYPE The well-known service type, set to "platform-support-service".
static int	ServiceEventListener

Method Summary

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

Methods inherited from interface javax.agent.service.Service

getServiceProperties, setServiceProperties

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

getState, terminateService

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

addAblePlatformServiceEventListener, getAblePlatformServiceEventListeners, removeAblePlatformServiceEventListener

Field Detail

SERVICE_TYPE

public static final java.lang.String SERVICE_TYPE

The well-known service type, set to "platform-support-service".

See Also:

Constant Field Values

COLUMN_NAMES

public static final java.lang.String[] COLUMN_NAMES

The table's column names and types that this service will persist to.

COLUMN_TYPES

public static final java.lang.String[] COLUMN_TYPES

ServiceEventListener

public static final int ServiceEventListener

See Also:

Constant Field Values

Method Detail

quiesceAgentPool

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

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.

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

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.

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.

Since:

ABLE 2.3.0

terminateAgentPool

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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.