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 AblePlatformSupport

All Superinterfaces:
  java.rmi.Remote

All Known Implementing Classes:
  AblePlatformSupportImpl

public interface AblePlatformSupport
extends java.rmi.Remote

This class specifies the remote interface to ABLE platform infrastructure objects, one of which "lives" inside each agent pool participating in the overall ABLE platform. Each platform support object provides information about the agent pool under its control and about the agents and services running there. A platform support object also helps the Agent Lifecycle Service create agents in its agent pool.

Method Summary
`java.lang.Object` | `getNewObject(java.lang.String theClassName, AbleSecureKey theSecureKey)` Gets a reference to a new instance of the specified class, which is created by calling the class's null argument constructor.
`java.lang.Object` | `getNewObject(java.lang.String theClassName, java.lang.Object[] theConstructorArgs, AbleSecureKey theSecureKey)` Gets a reference to a new instance of the specified class, which is created by calling the class's constructor that matches the specified arguments.
`java.lang.Object` | `getNewObject(java.lang.String theHostName, java.lang.String thePort, java.lang.String theClassName, java.lang.Object[] theConstructorArgs, AbleSecureKey theSecureKey)` Gets a reference to a new instance of the specified class, which is created in an agent pool on the specified host and port by calling the class's constructor that matches the specified arguments.
`java.util.Hashtable` | `getPlatformAgentPools()` Gets a collection of agent pool definitions as specified in the platform preference file.
`java.lang.String` | `getPlatformCryptographyAlgorithm()` Gets the platform's cryptography algorithm as specified in the platform preference file.
`java.lang.String` | `getPlatformCryptographyProvider()` Gets the platform's cryptography provider as specified in the platform preference file.
`java.lang.String` | `getPlatformName()` Gets the platform's name as specified in the platform preference file.
`AblePlatformPreferences` | `getPlatformPreferences(AbleSecureKey theSecureKey)` Returns the Platform Preferences under which the agent pool is running.
`boolean` | `getPlatformSecurity()` Gets the overall ABLE security setting as specified in the ABLE preference file.
`javax.agent.service.Service` | `getPlatformService(java.lang.String theRequestorsPort, java.lang.String theServiceAlias)` Gets the specified platform Service object.
`javax.agent.service.ServiceRoot` | `getPlatformServiceRoot(java.lang.String theRequestorsPort)` Gets the platform's service root.
`void` | `refreshPreferences(AblePlatformPreferences thePlatformPreferences, AbleSecureKey theSecureKey)` Causes this AblePlatformSupport object to refresh the current platform preferences from the specified preferences.
`void` | `refreshPreferences(AbleSecureKey theSecureKey)` Causes this AblePlatformSupport object to refresh the current platform preferences from the original file on disk.
`void` | `refreshPreferences(java.lang.String theFileName, AbleSecureKey theSecureKey)` Causes this AblePlatformSupport object to refresh the current platform preferences from the specified file.
`void` | `terminatePlatformSupport(AbleSecureKey theSecureKey)` Terminates this AblePlatformSupport object and the agent pool in which it is running.

Method Detail

### getNewObject

    public java.lang.Object getNewObject(java.lang.String theClassName,
                                         AbleSecureKey theSecureKey)
                                  throws java.rmi.RemoteException,
                                         javax.agent.service.naming.NamingException

  Gets a reference to a new instance of the specified class, which is created by calling the class's null argument constructor.

  Parameters:
    `theClassName` - The fully qualified class name of the object to be created. The class name must represent a legitimate Remote, Serializable object accessible via the CLASSPATH.

    `theSecureKey` - When platform security is off, this parameter may be null; otherwise, this must be a valid security key from a caller with the proper authority to create new objects within the ABLE platform.

  Returns:
    A reference to the newly constructed object. Obviously, the caller is responsible for casting the returned object to the appropriate data type.
  Throws:
    `java.rmi.RemoteException` - On any error.
    `javax.agent.service.naming.NamingException`

### getNewObject

    public java.lang.Object getNewObject(java.lang.String theClassName,
                                         java.lang.Object[] theConstructorArgs,
                                         AbleSecureKey theSecureKey)
                                  throws java.rmi.RemoteException,
                                         javax.agent.service.naming.NamingException

  Gets a reference to a new instance of the specified class, which is created by calling the class's constructor that matches the specified arguments.

  Parameters:
    `theClassName` - The fully qualified class name of the object to be created. The class name must represent a legitimate Remote, Serializable object accessible via the CLASSPATH.

    `theConstructorArgs` - An array of objects that will be passed to the constructor of the specified class. The order and data type of each object in the array must match the signature of a constructor of the specified class.

    `theSecureKey` - When platform security is off, this parameter may be null; otherwise, this must be a valid security key from a caller with the proper authority to create new objects within the ABLE platform.

  Returns:
    A reference to the newly constructed object. Obviously, the caller is responsible for casting the returned object to the appropriate data type.
  Throws:
    `java.rmi.RemoteException` - On any error.
    `javax.agent.service.naming.NamingException`

### getNewObject

    public java.lang.Object getNewObject(java.lang.String theHostName,
                                         java.lang.String thePort,
                                         java.lang.String theClassName,
                                         java.lang.Object[] theConstructorArgs,
                                         AbleSecureKey theSecureKey)
                                  throws java.rmi.RemoteException,
                                         javax.agent.service.naming.NamingException

  Gets a reference to a new instance of the specified class, which is created in an agent pool on the specified host and port by calling the class's constructor that matches the specified arguments.

  Parameters:
    `theHostName` - The IP address (name or number) of a system that is running another AblePlatformSupport object in an agent pool listening at the specified port.

    `thePort` - The port number at which the above system is listening for remote AblePlatformSupport requests.

    `theClassName` - The fully qualified class name of the desired object. The class name must represent a legitimate Remote, Serializable object accessible via the CLASSPATH.

    `theConstructorArgs` - An array of objects that will be passed to the constructor of the specified class. The order and data type of each object in the array must match the signature of a constructor of the specified class.

    `theSecureKey` - When platform security is off, this parameter may be null; otherwise, this must be a valid security key from a caller with the proper authority to create new objects within the ABLE platform.

  Returns:
    A reference to the newly constructed object. Obviously, the caller is responsible for casting the returned object to the appropriate data type.
  Throws:
    `java.rmi.RemoteException` - On any error.
    `javax.agent.service.naming.NamingException`

### getPlatformCryptographyAlgorithm

    public java.lang.String getPlatformCryptographyAlgorithm()
                                                      throws java.rmi.RemoteException

  Gets the platform's cryptography algorithm as specified in the platform preference file.

  Returns:
    The platform's cryptography algorithm.
  Throws:
    `java.rmi.RemoteException` - On any error.

### getPlatformCryptographyProvider

    public java.lang.String getPlatformCryptographyProvider()
                                                     throws java.rmi.RemoteException

  Gets the platform's cryptography provider as specified in the platform preference file.

  Returns:
    The platform's cryptography provider.
  Throws:
    `java.rmi.RemoteException` - On any error.

### getPlatformName

    public java.lang.String getPlatformName()
                                     throws java.rmi.RemoteException

  Gets the platform's name as specified in the platform preference file.

  Returns:
    The platform's name.
  Throws:
    `java.rmi.RemoteException` - On any error.

### getPlatformSecurity

    public boolean getPlatformSecurity()
                                throws java.rmi.RemoteException

  Gets the overall ABLE security setting as specified in the ABLE preference file.

  Returns:
    true if ABLE is operating with security on; false otherwise.
  Throws:
    `java.rmi.RemoteException` - On any error.

### getPlatformService

    public javax.agent.service.Service getPlatformService(java.lang.String theRequestorsPort,
                                                          java.lang.String theServiceAlias)
                                                   throws java.rmi.RemoteException

  Gets the specified platform Service object.

  Note that the ServiceManager is called to find the specified service, and that the ServiceManager will use the specified service's factory to "get" the service. "Getting" the service may be as simple as an RMI look up, or it may involve creating the service from scratch.

  Parameters:
    `theRequestorsPort` - The port, if any (may be null), of the object requesting the service object. This is used to help determine whether the requestor is running in the same agent pool as the specified Service.

    `theServiceAlias` - The binding name of the service to be returned.

  Returns:
    The specified Service, if found. If not found, that is, the service couldn't be successfully looked up or created, an exception is thrown.
  Throws:
    `java.rmi.RemoteException` - On any error.

### getPlatformServiceRoot

    public javax.agent.service.ServiceRoot getPlatformServiceRoot(java.lang.String theRequestorsPort)
                                                           throws java.rmi.RemoteException

  Gets the platform's service root.

  Parameters:
    `theRequestorsPort` - The port, if any (may be null), of the object requesting the service root. This is used to help determine whether the requestor is running in the same agent pool as any Service that may need to be constructed.

  Returns:
    The platform's service root.
  Throws:
    `java.rmi.RemoteException` - On any error.

### getPlatformAgentPools

    public java.util.Hashtable getPlatformAgentPools()
                                              throws java.rmi.RemoteException

  Gets a collection of agent pool definitions as specified in the platform preference file.

  Returns:
    A collection of AblePlatformPreferences.AgentPoolEntry_ objects, where each object in the collection represents an agent pool definition from the platform preference file. The key to the collection is a string that is the alias of each agent pool as defined in the preference file.
  Throws:
    `java.rmi.RemoteException` - On any error.

### terminatePlatformSupport

    public void terminatePlatformSupport(AbleSecureKey theSecureKey)
                                  throws java.rmi.RemoteException,
                                         javax.agent.service.naming.NamingException

  Terminates this AblePlatformSupport object and the agent pool in which it is running.

  The following actions occur:

  - All nonessential platform services running in the agent pool are terminated.
  - If the AgentLifeCycleService is running here, it is terminated.
  - If the AgentNamingService is running here, it is terminated last.
  - PlatformSupport is unbound from the Registry.
  - The VM is exited.

  Please note the following:

  - The caller should ask AgentLifeCycleService to quiesce all agents running in this agent pool before calling this method. This method does nothing with running agents.
  - The AblePlatformSupport object containing AgentLifeCycleService should be terminated next to last.
  - The AblePlatformSupport object containing AgentNamingService should be terminated last.

  Parameters:
    `theSecureKey` - When platform security is off, this parameter may be null; otherwise, this must be a valid security key from a caller with the proper authority to terminate this platform support object and the agent pool in which it is running.

  Throws:
    `java.rmi.RemoteException` - On any error.
    `javax.agent.service.naming.NamingException`

### refreshPreferences

    public void refreshPreferences(AbleSecureKey theSecureKey)
                            throws java.rmi.RemoteException,
                                   javax.agent.service.naming.NamingException

  Causes this AblePlatformSupport object to refresh the current platform preferences from the original file on disk. It is assumed the file has been securely changed.

  Parameters:
    `theSecureKey` - When platform security is off, this parameter may be null; otherwise, this must be a valid security key from a caller with the proper authority to change the platform's preferences.
  Throws:
    `java.rmi.RemoteException` - On any error.
    `javax.agent.service.naming.NamingException` - When security is on and the key fails to verify.
  Since:
    ABLE 2.2.0

### refreshPreferences

    public void refreshPreferences(AblePlatformPreferences thePlatformPreferences,
                                   AbleSecureKey theSecureKey)
                            throws java.rmi.RemoteException,
                                   javax.agent.service.naming.NamingException

  Causes this AblePlatformSupport object to refresh the current platform preferences from the specified preferences.

  Parameters:
    `thePlatformPreferences` - A set of platform preferences from which the current platform preferences are updated.
    `theSecureKey` - When platform security is off, this parameter may be null; otherwise, this must be a valid security key from a caller with the proper authority to change the platform's preferences.
  Throws:
    `java.rmi.RemoteException` - On any error.
    `javax.agent.service.naming.NamingException` - When security is on and the key fails to verify.
  Since:
    ABLE 2.2.0

### refreshPreferences

    public void refreshPreferences(java.lang.String theFileName,
                                   AbleSecureKey theSecureKey)
                            throws java.rmi.RemoteException,
                                   javax.agent.service.naming.NamingException

  Causes this AblePlatformSupport object to refresh the current platform preferences from the specified file.

  Parameters:
    `theFileName` - The name of a file (including path information) that contains valid platform preference specifications. The file must be accessible to the JVM in which this AblePlatformSupport object is running.
    `theSecureKey` - When platform security is off, this parameter may be null; otherwise, this must be a valid security key from a caller with the proper authority to change the platform's preferences.
  Throws:
    `java.rmi.RemoteException` - On any error.
    `javax.agent.service.naming.NamingException` - When security is on and the key fails to verify.
  Since:
    ABLE 2.2.0

### getPlatformPreferences

    public AblePlatformPreferences getPlatformPreferences(AbleSecureKey theSecureKey)
                                                   throws java.rmi.RemoteException

  Returns the Platform Preferences under which the agent pool is running.

  Parameters:
    `theSecureKey` - When platform security is off, this parameter may be null; otherwise, this must be a valid security key from a caller with the proper authority to change the platform's preferences.
  Returns:
    The AblePlatformPreference object instantiated in this agent pool, or, if security is on and either the security checks fail or a NamingException occurred, null.
  Throws:
    `java.rmi.RemoteException` - On any error.
  Since:
    ABLE 2.3.0

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