ABLE 2.0.0 07/02/2003 10:25:01

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 as 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:

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

Inner 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.
 
Method Summary
 boolean compareTrustLevel(java.lang.String theTrustLevelAlias1, int theComparison, java.lang.String theTrustLevelAlias2)
          Compares two trust levels by alias.
 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.
static java.lang.String Copyright()
          Gets the copyright statement of this class.
 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 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)

TRUSTLEVEL_LESS_THAN

public static final int TRUSTLEVEL_LESS_THAN
TrustLevel comparison operator: less than.
See Also:
compareTrustLevel(String,int,String)

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)

TRUSTLEVEL_GREATER_THAN

public static final int TRUSTLEVEL_GREATER_THAN
TrustLevel comparison operator: greater than.
See Also:
compareTrustLevel(String,int,String)

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)

TRUSTLEVEL_NOT_EQUAL_TO

public static final int TRUSTLEVEL_NOT_EQUAL_TO
TrustLevel comparison operator: not equal to.
See Also:
compareTrustLevel(String,int,String)
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.

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.


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.

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

Copyright

public static java.lang.String Copyright()
Gets the copyright statement of this class.
Returns:
this class's copyright statement.


ABLE 2.0.0 07/02/2003 10:25:01

(C) Copyright IBM Corporation 1999, 2003