Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

(C) Copyright IBM Corporation 1999, 2005