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

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