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 AblePlatformPreferences

    java.lang.Object
      com.ibm.able.platform.AblePlatformPreferences

All Implemented Interfaces:
  java.io.Serializable

public final class AblePlatformPreferences
extends java.lang.Object
implements java.io.Serializable

This class encapsulates and provides (mostly read-only) access to the end-user's platform operating preferences. These preferences are read from a physical properties file named by AblePlatform.PropertiesFileName (`ableplatform.preferences` at the time of this writing); the properties file is expected to reside in the directory specified by the System property `able.prefdir`, or failing that, the directory specified by the System property `user.home` (system properties may be overriden by using the `-D` parameter on a Java program's start command). If no property file is found in either location, a default property file containing default values is written to disk, but most likely this will not work satifactorily in the user's operating environment.

The platform preference file contains information about such things as:

- Cryptography
- Who is allowed to run agents on the platform
- Who is trusted and to what degree
- Where agents are allowed to run
- What services are provided to the agents
- What agents are allowed to be introduced into the system, and by whom.

An example, but non-working, preference file is shipped in ABLE's `example` directory. For the latest specifics of a platform preference file refer to the Platform Guide.

See Also:
  Serialized Form

Nested Class Summary
`class` | `AblePlatformPreferences.AgentPoolEntry_` This class encapsulates the definition of a single agent pool as found in a platform preference file.
`class` | `AblePlatformPreferences.PrincipalEntry_` This class encapsulates the definition of a single Principal as found in a platform preference file.
`class` | `AblePlatformPreferences.ServiceEntry_` This class encapsulates the definition of a single platform Service as found in a platform preference file.
`class` | `AblePlatformPreferences.TrustLevelEntry_` This class encapsulates the definition of a single TrustLevel as found in a platform preference file.

Field Summary
`static int` | `TRUSTLEVEL_EQUAL_TO` TrustLevel comparison operator: equal to.
`static int` | `TRUSTLEVEL_GREATER_THAN` TrustLevel comparison operator: greater than.
`static int` | `TRUSTLEVEL_GREATER_THAN_OR_EQUAL_TO` TrustLevel comparison operator: greater than or equal to.
`static int` | `TRUSTLEVEL_LESS_THAN` TrustLevel comparison operator: less than.
`static int` | `TRUSTLEVEL_LESS_THAN_OR_EQUAL_TO` TrustLevel comparison operator: less than or equal to.
`static int` | `TRUSTLEVEL_NOT_EQUAL_TO` TrustLevel comparison operator: not equal to.

Constructor Summary
`AblePlatformPreferences()` Instantiates preference objects from a Properties file read from disk.
`AblePlatformPreferences(java.lang.String thePropertiesFileName)` Instantiates preference objects from a Properties file read from the specified file on disk.

Method Summary
`java.lang.String` | `aliasOfLocalAgentPool()` Gets the alias of the current AgentPool.
`boolean` | `compareTrustLevel(java.lang.String theTrustLevelAlias1, int theComparison, java.lang.String theTrustLevelAlias2)` Compares two trust levels by alias.
`java.util.SortedSet` | `configuredAgentSystems()` Returns a sorted set of strings naming the systems on which agents can possibly run.
`java.util.SortedSet` | `configuredAgentTypes()` Returns a sorted set of strings naming the types of possible agents.
`java.util.Vector` | `configuredForAns(java.lang.String theAgentPoolAlias)` Determines whether the specified AgentPool is configured to run the Agent Naming Service, and if it is, returns the ServiceEntry_ for that service.
`AblePlatformPreferences.AgentPoolEntry_` | `configuredHostPort(java.lang.String theHostName, java.lang.String theIpAddress, java.lang.String thePort)` Determines whether the system specified by the input parameters matches an AgentPool definition in the platform preference file, and if so, returns the matching AgentPool.
`java.util.Vector` | `configuredServices()` Gets all services configured to run anywhere on the platform.
`java.util.Vector` | `configuredServices(java.lang.String theAgentPoolAlias)` Gets all services configured to run in the specified AgentPool.
`AblePlatformPreferences.AgentPoolEntry_` | `getAgentPool(java.lang.String theAgentPoolAlias)`
`java.util.Hashtable` | `getAgentPools()` Gets the collection of AgentPool definitions as specified in the end-user's preference file.
`java.lang.String` | `getCryptographyAlgorithm()` Gets the cryptography algorithm as defined in the end-user's preference file.
`java.lang.String` | `getCryptographyProvider()` Gets the cryptography provider as specified in the end-user's preference file.
`java.util.Hashtable` | `getPermittedAgents()` Gets a collection of all agents that are permitted to run on this platform.
`java.lang.String` | `getPlatformName()` Gets the name of the platform as defined in the end-user's preference file.
`java.util.Hashtable` | `getPrincipals()` Gets the collection of Kerberos principal definitions as specified in the end-user's preference file.
`java.lang.String` | `getServiceFactoryClassName(java.lang.String theServiceAlias)` Gets the class name of the factory that can create the specified service.
`java.lang.String` | `getServiceIpAddress(java.lang.String theServiceAlias)` Gets the configured IP address of where the specified service is to run.
`java.util.Hashtable` | `getServiceList()` Gets the collection of service definitions as specified in the end-user's preference file.
`java.lang.String` | `getServicePort(java.lang.String theServiceAlias)` Gets the configured port of where the specified service is to run.
`java.util.Vector` | `getServices()` Gets the collection of service names (service types) as specified in the end-user's preference file; note that each service type must match exactly (except for case) the type as it is defined in the actual service.
`java.util.Hashtable` | `getTrustLevels()` Gets the collection of trust level definitions as specified in the end-user's preference file.
`java.lang.String` | `portOfLocalAgentPool()` Gets the port at which the current AgentPool runs.
`java.lang.String` | `principalOfAgentPool(java.lang.String theAgentPoolAlias)` Gets the principal under which the specified AgentPool runs.
`java.lang.String` | `principalOfLocalAgentPool()` Gets the principal under which the current AgentPool runs.
`java.lang.String` | `principalOfService(java.lang.String theServiceAlias)` Gets the principal under which the specified service runs.
`void` | `readPropertiesFile()` Loads up the current set of working preferences from a physical properties file.
`void` | `setLocalAgentPool(java.lang.String theAgentPoolAlias)` Any Agent (or other code) introduced into the platform from a command line environment rather than by Agent Lifecycle Services must use this method (once; subsequent calls are ignored) to associate itself with a particular AgentPool and the AgentPool's principal.
`java.lang.String` | `trustLevelOfPrincipal(java.lang.String thePrincipal)` Gets the configured trust level of the specified principal.
`void` | `updatePreferenceVariables(AblePlatformPreferences theNewPreferences)` When security is off, changes all current working preferences to the values contained in the specified preferences object.
`void` | `updatePreferenceVariablesAndWritePropertiesFile(AblePlatformPreferences theNewPreferences)` When security is off, changes all current working preferences to the values contained in the specified preferences object.
`void` | `writePropertiesFile()` Saves the current set of working preferences to a physical properties file.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### TRUSTLEVEL_EQUAL_TO

    public static final int TRUSTLEVEL_EQUAL_TO

  TrustLevel comparison operator: equal to.

  See Also:
    `compareTrustLevel(String,int,String)`, Constant Field Values

### TRUSTLEVEL_LESS_THAN

    public static final int TRUSTLEVEL_LESS_THAN

  TrustLevel comparison operator: less than.

  See Also:
    `compareTrustLevel(String,int,String)`, Constant Field Values

### TRUSTLEVEL_LESS_THAN_OR_EQUAL_TO

    public static final int TRUSTLEVEL_LESS_THAN_OR_EQUAL_TO

  TrustLevel comparison operator: less than or equal to.

  See Also:
    `compareTrustLevel(String,int,String)`, Constant Field Values

### TRUSTLEVEL_GREATER_THAN

    public static final int TRUSTLEVEL_GREATER_THAN

  TrustLevel comparison operator: greater than.

  See Also:
    `compareTrustLevel(String,int,String)`, Constant Field Values

### TRUSTLEVEL_GREATER_THAN_OR_EQUAL_TO

    public static final int TRUSTLEVEL_GREATER_THAN_OR_EQUAL_TO

  TrustLevel comparison operator: greater than or equal to.

  See Also:
    `compareTrustLevel(String,int,String)`, Constant Field Values

### TRUSTLEVEL_NOT_EQUAL_TO

    public static final int TRUSTLEVEL_NOT_EQUAL_TO

  TrustLevel comparison operator: not equal to.

  See Also:
    `compareTrustLevel(String,int,String)`, Constant Field Values

Constructor Detail

### AblePlatformPreferences

    public AblePlatformPreferences()

  Instantiates preference objects from a Properties file read from disk.

  This package's properties file is first looked for in the directory as specified by the system property contained in the variable Able.PropertiesFileDirectoryProperty and if the named property isn't set, then in the user's home directory. If there is no properties file in either location, a default properties file is created.

### AblePlatformPreferences

    public AblePlatformPreferences(java.lang.String thePropertiesFileName)

  Instantiates preference objects from a Properties file read from the specified file on disk.

Parameters:
  `thePropertiesFileName` - The fully specified name of a readable file on disk. If the file is not found, a default set of properties is created and written to disk.
Since:
  ABLE 2.2.0

Method Detail

### setLocalAgentPool

    public final void setLocalAgentPool(java.lang.String theAgentPoolAlias)

  Any Agent (or other code) introduced into the platform from a command line environment rather than by Agent Lifecycle Services must use this method (once; subsequent calls are ignored) to associate itself with a particular AgentPool and the AgentPool's principal.

  Parameters:
    `theAgentPoolAlias` - The alias of an AgentPool configured in the platform preference file.

### getPlatformName

    public final java.lang.String getPlatformName()

  Gets the name of the platform as defined in the end-user's preference file.

  Returns:
    The name of the platform as specified in the preference file, or the default name contained in the variable `AblePlatform.DefaultPlatformName` if no platform name has been specified.

### getCryptographyAlgorithm

    public final java.lang.String getCryptographyAlgorithm()

  Gets the cryptography algorithm as defined in the end-user's preference file.

  Returns:
    The cryptogtraphy algorithm as specified in the preference file, or `DSA` if no algorithm has been specified.

### getCryptographyProvider

    public final java.lang.String getCryptographyProvider()

  Gets the cryptography provider as specified in the end-user's preference file.

  Returns:
    The cryptogtraphy provider as specified in the preference file, or the empty string if no provider has been specified.

### getPrincipals

    public final java.util.Hashtable getPrincipals()

  Gets the collection of Kerberos principal definitions as specified in the end-user's preference file.

  Returns:
    A collection of principal definitions as specified in the preference file, where defined principal aliases (`Principal.n.Alias`) are the keys to the collection and `PrincipalEntry_` objects are elements of the collection; if no principals are defined in the preference file, the returned collection is empty.

### getTrustLevels

    public final java.util.Hashtable getTrustLevels()

  Gets the collection of trust level definitions as specified in the end-user's preference file.

  Returns:
    A collection of trust level definitions as specified in the preference file, where defined TrustLevel aliases (`TrustLevel.n.Alias`) are the keys to the collection and `TrustLevelEntry_` objects are elements of the collection; if no trust levels are defined in the preference file, the returned collection is empty.

### getAgentPools

    public final java.util.Hashtable getAgentPools()

  Gets the collection of AgentPool definitions as specified in the end-user's preference file.

  Returns:
    A collection of AgentPool definitions as specified in the preference file, where defined AgentPool aliases (`AgentPool.n.Alias`) are the keys to the collection and `AgentPoolEntry_` objects are elements of the collection; if no agent pools are defined in the preference file, the returned collection is empty.

### getServices

    public final java.util.Vector getServices()

  Gets the collection of service names (service types) as specified in the end-user's preference file; note that each service type must match exactly (except for case) the type as it is defined in the actual service. For example, JAS specifies that an agent naming service must have a service type of "agent-naming-service".

  Returns:
    A collection of service names as specified in the preference file, where defined service types are the keys to the collection; if no service names are defined in the preference file, the returned collection is empty.

### getServiceList

    public final java.util.Hashtable getServiceList()

  Gets the collection of service definitions as specified in the end-user's preference file.

  Returns:
    A collection of service definitions as specified in the preference file, where service names (service types) are the keys to the collection and `ServiceEntry_` objects are elements of the collection; if no services are defined in the preference file, the returned collection is empty.

### getPermittedAgents

    public final java.util.Hashtable getPermittedAgents()

  Gets a collection of all agents that are permitted to run on this platform.

  Returns:
    A collection of agent definitions as specified in the preference file, where defined agent aliases (`Agent.n.Alias`) are the keys to the collection and `AbleAgentClassDescription` objects are the elements of the collection; if no agents are defined in the preference file, the return collection is empty.

### readPropertiesFile

    public void readPropertiesFile()

  Loads up the current set of working preferences from a physical properties file.

  See Also:
    `writePropertiesFile()`

### writePropertiesFile

    public void writePropertiesFile()

  Saves the current set of working preferences to a physical properties file.

  See Also:
    `readPropertiesFile()`

### updatePreferenceVariablesAndWritePropertiesFile

    public void updatePreferenceVariablesAndWritePropertiesFile(AblePlatformPreferences theNewPreferences)

  When security is off, changes all current working preferences to the values contained in the specified preferences object. Note that a side-effect is that the new preference values are written to disk.

  When security is on all calls to this method are ignored.

  Parameters:
    `theNewPreferences` - A preferences object containing replacement values for the current set of working preferences.

### updatePreferenceVariables

    public void updatePreferenceVariables(AblePlatformPreferences theNewPreferences)

  When security is off, changes all current working preferences to the values contained in the specified preferences object.

  When security is on all calls to this method are ignored.

  Parameters:
    `theNewPreferences` - A preferences object containing replacement values for the current set of working preferences.
  Since:
    ABLE 2.2.0

### configuredForAns

    public final java.util.Vector configuredForAns(java.lang.String theAgentPoolAlias)

  Determines whether the specified AgentPool is configured to run the Agent Naming Service, and if it is, returns the ServiceEntry_ for that service.

  Parameters:
    `theAgentPoolAlias` - The alias of an AgentPool defined in the platform preference file. This alias is normally obtained with a call to configuredHostPort().

  Returns:
    a collection of two elements. The first element is a Boolean; its value is true if the ANS is to run in the specified AgentPool. If the ANS is to run in some other AgentPool, the boolean's value is false. The second element of the collection is a clone of the ServiceEntry_ object for where the ANS is to run.

### configuredHostPort

    public final AblePlatformPreferences.AgentPoolEntry_ configuredHostPort(java.lang.String theHostName,
                                                                            java.lang.String theIpAddress,
                                                                            java.lang.String thePort)

  Determines whether the system specified by the input parameters matches an AgentPool definition in the platform preference file, and if so, returns the matching AgentPool.

  Parameters:
    `theHostName` - The name of the system.

    `theIpAddress` - The system's IP address.

    `thePort` - The system's port number.

  Returns:
    If the specified information matches a configured AgentPool, the AgentPool definition is returned, from which the AgentPool's alias can be extracted and used, for example, on a subsequent `configuredServices(String)` call. If no matching AgentPool definition is found, null is returned.

### configuredServices

    public final java.util.Vector configuredServices()

  Gets all services configured to run anywhere on the platform.

  Returns:
    If the platform is configured to run any services, a collection of ServiceEntry_ objects is returned, where each object represents a service to run somewhere on the platform. Otherwise, an empty collection is returned.

### configuredServices

    public final java.util.Vector configuredServices(java.lang.String theAgentPoolAlias)

  Gets all services configured to run in the specified AgentPool.

  Parameters:
    `theAgentPoolAlias` - The alias of an AgentPool defined in the platform preference file. This alias is normally obtained with a call to `configuredHostPort(String,String,String)`.

  Returns:
    If the agent pool is configured to run any services, a collection of ServiceEntry_ objects is returned, where each object represents a service to run in the specified AgentPool. Otherwise, an empty collection is returned.

### principalOfAgentPool

    public final java.lang.String principalOfAgentPool(java.lang.String theAgentPoolAlias)

  Gets the principal under which the specified AgentPool runs.

  Parameters:
    `theAgentPoolAlias` - The alias of an AgentPool defined in the platform preference file.

  Returns:
    the Kerberos principal under which the specified AgentPool runs. This may be the empty ("") string if no principal has been configured.

### principalOfLocalAgentPool

    public final java.lang.String principalOfLocalAgentPool()

  Gets the principal under which the current AgentPool runs.

  Returns:
    the Kerberos principal under which the local AgentPool runs. This may be the empty ("") string if no principal has been configured.

### portOfLocalAgentPool

    public final java.lang.String portOfLocalAgentPool()

  Gets the port at which the current AgentPool runs.

  Returns:
    the port at which the local AgentPool runs. This may be the empty string ("") if no port has been configured.

### aliasOfLocalAgentPool

    public final java.lang.String aliasOfLocalAgentPool()

  Gets the alias of the current AgentPool.

  Returns:
    the alias of the local AgentPool. This may be the empty string ("") if no agent pool has been configured.
  Since:
    ABLE 2.3.0

### principalOfService

    public final java.lang.String principalOfService(java.lang.String theServiceAlias)

  Gets the principal under which the specified service runs.

  Parameters:
    `theServiceAlias` - The alias of a service defined in the platform preference file. This alias is normally obtained with a call to `configuredServices(String)`.

  Returns:
    the Kerberos principal under which the service runs. This may be the empty ("") string if no principal has been configured.

### getServiceFactoryClassName

    public final java.lang.String getServiceFactoryClassName(java.lang.String theServiceAlias)

  Gets the class name of the factory that can create the specified service.

  Parameters:
    `theServiceAlias` - The alias of a service defined in the platform preference file.

  Returns:
    the fully qualified class name of the factory object that can create the specified service as the name was specified in the platform preference file. This may be the empty ("") string if no factory has been configured.

### getServiceIpAddress

    public final java.lang.String getServiceIpAddress(java.lang.String theServiceAlias)

  Gets the configured IP address of where the specified service is to run.

  Parameters:
    `theServiceAlias` - The alias of a service defined in the platform preference file.

  Returns:
    the IP address of where the service is to run. This may be the empty ("") string if no IP address has been configured.

### getServicePort

    public final java.lang.String getServicePort(java.lang.String theServiceAlias)

  Gets the configured port of where the specified service is to run.

  Parameters:
    `theServiceAlias` - The alias of a service defined in the platform preference file.

  Returns:
    the port of where the service is to run. This may be the empty ("") string if no port has been configured.

### trustLevelOfPrincipal

    public final java.lang.String trustLevelOfPrincipal(java.lang.String thePrincipal)

  Gets the configured trust level of the specified principal.

  A principal is defined in the platform preference file, and then associated with a trust level, also defined in the file. Each principal may be at more than one trust level. Order of trust is assumed in the order that the trust levels are listed in the preferences file. The trust level of a principal will be the trust level that it appears in first, which will also be the hightest trust level that it is part of since order is implied.

  Parameters:
    `thePrincipal` - A principal defined in the platform preference file.

  Returns:
    the trust level of this principal; null if the principal is not defined.

### compareTrustLevel

    public final boolean compareTrustLevel(java.lang.String theTrustLevelAlias1,
                                           int theComparison,
                                           java.lang.String theTrustLevelAlias2)

  Compares two trust levels by alias.

  Parameters:
    `theTrustLevelAlias1` - The alias of the first trust level to compare.
    `theComparison` - The type of comparison to perform between the two specified trust levels. The specified value must be a valid TRUSTLEVEL_nnn comparison operator.
    `theTrustLevelAlias2` - The alias of the second trust level to compare.
  Returns:
    A boolean holding the result of the comparison. However, if either of the trust levels is undefined, or if the specified comparison operator is invalid, a message is logged and false is returned.
  See Also:
    `TRUSTLEVEL_EQUAL_TO`, `TRUSTLEVEL_LESS_THAN`, `TRUSTLEVEL_LESS_THAN_OR_EQUAL_TO`, `TRUSTLEVEL_GREATER_THAN`, `TRUSTLEVEL_GREATER_THAN_OR_EQUAL_TO`, `TRUSTLEVEL_NOT_EQUAL_TO`

### getAgentPool

    public AblePlatformPreferences.AgentPoolEntry_ getAgentPool(java.lang.String theAgentPoolAlias)

### configuredAgentSystems

    public final java.util.SortedSet configuredAgentSystems()

  Returns a sorted set of strings naming the systems on which agents can possibly run.

  Since:
    ABLE 2.3.0

### configuredAgentTypes

    public final java.util.SortedSet configuredAgentTypes()

  Returns a sorted set of strings naming the types of possible agents.

  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