com.ibm.able.platform
Class AblePlatform

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

All Implemented Interfaces:

java.io.Serializable

public final class AblePlatform

extends java.lang.Object

implements java.io.Serializable

The AblePlatform class provides constants and class methods to support the distributed platform of the IBM Agent Building and Learning Environment (ABLE); in addition to static methods that help determine the values of certain preferences set by the user in the platform preference file, methods are provided to obtain the platform's service root and to look up services individually.

See Also:

Serialized Form

Field Summary

static java.lang.String	AbleAgentAgentPool
static java.lang.String	AbleAgentAutonomyLevel The following are keys of attributes that are added to each agent's JAS AgentDescription by each AblePlatformDefaultAgent when it is created.
static java.lang.String	AbleAgentDescription
static java.lang.String	AbleAgentLastUpdate
static java.lang.String	AbleAgentMovable
static java.lang.String	AbleAgentPoolSystem
static java.lang.String	AbleAgentRmiAddress
static java.lang.String	AbleAgentRmiHost
static java.lang.String	AbleAgentRmiName
static java.lang.String	AbleAgentStatus
static java.lang.String	AbleAgentSummary
static java.lang.String	AbleAgentType
static java.lang.String	AbleAgentVendor
static java.lang.String	AbleAgentVersion
static java.lang.String	AbleDirectLocatorObject
static java.lang.String	AbleDirectLocatorType
static java.lang.String	AbleEnvelopeDisplayName
static java.lang.String	AbleEnvelopeNestedName
static java.lang.String	AbleLocatorProtocol
static int	CustomAutonomy Autonomy level: custom autonomy; an agent operating with this level is operating on a custom level.
static java.lang.String	DefaultPlatformName A default name for a platform when no platform name is specified in the preferences file.
static int	HighAutonomy Autonomy level: high autonomy; an agent operating with this level is highly autonomous.
static java.security.KeyPairGenerator	KeyGenerator This KeyPairGenerator is created using the cryptography algorithm and cryptography provider specified in the preferences file.
static int	LowAutonomy Autonomy level: low autonomy; an agent operating with this level is hardly autonomous.
static int	MediumAutonomy Autonomy level: medium autonomy; an agent operating with this level is somewhat autonomous.
static java.lang.String	PlatformMessageBundle The fully qualified name of the class that contains this package's NLS messages.
static java.lang.String	PlatformSupportName The name of the platform support object as it is used when doing RMI lookups, rebinds, and so on.
static AblePlatformPreferences	Preferences The current set of preferences, as loaded from the preferences file.

Method Summary

static AbleMessageContainer	AutonomyLevel(int theAutonomyLevel) Turns the specified autonomy level into a human readable form for error messages.
static java.security.KeyPair	generateKeyPair() Gets a KeyPair from the special KeyPairGenerator created using the cryptography algorithm and cryptography provider specified in the preferences file.
static AblePlatformAgent	getAgentReference(javax.agent.service.directory.AgentDescription theAgentDescription) Extracts a direct reference to an AblePlatformAgent from an AgentDescription created and registered by that same agent.
static javax.agent.Locator	getLocatorForInbox(javax.agent.service.directory.AgentDescription theAgentDescription, java.lang.String theInboxName) Searches the given AgentDescription for a Locator with the given inbox name, and returns the first one found.
static javax.agent.Locator	getLocatorForType(javax.agent.service.directory.AgentDescription theAgentDescription, java.lang.String theDesiredType) Extracts and returns a Locator of the given type from the given AgentDescription.
static java.lang.String	getPlatformCryptographyAlgorithm() Gets the platform's cryptography algorithm as specified in the platform preference file.
static java.lang.String	getPlatformCryptographyProvider() Gets the platform's cryptography provider as specified in the platform preference file.
static java.lang.String	getPlatformName() Gets the platform's name as specified in the platform preference file.
static boolean	getPlatformSecurity() Gets the platform's security setting as specified in the platform preference file.
static javax.agent.service.ServiceRoot	getPlatformServiceRoot(java.lang.String theRequestorsPort) Gets the platform's service root.
static javax.agent.service.Service	getService(java.lang.String theRequestorsPort, java.lang.String theServiceAlias) Gets the specified platform service.
static javax.agent.service.ServiceRoot	getServiceRoot(java.lang.String theRequestorsPort) Gets the platform's service root.
static java.lang.String	NlsMsg(java.lang.String theMsgKey) Gets an NLS message by key; the message must not contain any insertion text.
static java.lang.String	NlsMsg(java.lang.String theMsgKey, java.lang.Object[] theInserts) Gets an NLS message by key with the specified text inserted into the message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PlatformSupportName

public static final java.lang.String PlatformSupportName

The name of the platform support object as it is used when doing RMI lookups, rebinds, and so on.

See Also:

Constant Field Values

PlatformMessageBundle

public static final java.lang.String PlatformMessageBundle

The fully qualified name of the class that contains this package's NLS messages.

See Also:

Constant Field Values

AbleAgentAutonomyLevel

public static final java.lang.String AbleAgentAutonomyLevel

The following are keys of attributes that are added to each agent's JAS AgentDescription by each AblePlatformDefaultAgent when it is created. Most of the values for each named attribute are taken from the agent's description in the preferences file.

See Also:

Constant Field Values

AbleAgentDescription

public static final java.lang.String AbleAgentDescription

See Also:

Constant Field Values

AbleAgentLastUpdate

public static final java.lang.String AbleAgentLastUpdate

See Also:

Constant Field Values

AbleAgentMovable

public static final java.lang.String AbleAgentMovable

See Also:

Constant Field Values

AbleAgentRmiAddress

public static final java.lang.String AbleAgentRmiAddress

See Also:

Constant Field Values

AbleAgentRmiHost

public static final java.lang.String AbleAgentRmiHost

See Also:

Constant Field Values

AbleAgentRmiName

public static final java.lang.String AbleAgentRmiName

See Also:

Constant Field Values

AbleAgentStatus

public static final java.lang.String AbleAgentStatus

See Also:

Constant Field Values

AbleAgentSummary

public static final java.lang.String AbleAgentSummary

See Also:

Constant Field Values

AbleAgentType

public static final java.lang.String AbleAgentType

See Also:

Constant Field Values

AbleAgentVendor

public static final java.lang.String AbleAgentVendor

See Also:

Constant Field Values

AbleAgentVersion

public static final java.lang.String AbleAgentVersion

See Also:

Constant Field Values

AbleAgentAgentPool

public static final java.lang.String AbleAgentAgentPool

See Also:

Constant Field Values

AbleAgentPoolSystem

public static final java.lang.String AbleAgentPoolSystem

See Also:

Constant Field Values

AbleDirectLocatorType

public static final java.lang.String AbleDirectLocatorType

See Also:

Constant Field Values

AbleDirectLocatorObject

public static final java.lang.String AbleDirectLocatorObject

See Also:

Constant Field Values

AbleEnvelopeDisplayName

public static final java.lang.String AbleEnvelopeDisplayName

See Also:

Constant Field Values

AbleEnvelopeNestedName

public static final java.lang.String AbleEnvelopeNestedName

See Also:

Constant Field Values

AbleLocatorProtocol

public static final java.lang.String AbleLocatorProtocol

See Also:

Constant Field Values

CustomAutonomy

public static final int CustomAutonomy

Autonomy level: custom autonomy; an agent operating with this level is operating on a custom level.

See Also:

AutonomyLevel(int), Constant Field Values

HighAutonomy

public static final int HighAutonomy

Autonomy level: high autonomy; an agent operating with this level is highly autonomous.

See Also:

AutonomyLevel(int), Constant Field Values

MediumAutonomy

public static final int MediumAutonomy

Autonomy level: medium autonomy; an agent operating with this level is somewhat autonomous.

See Also:

AutonomyLevel(int), Constant Field Values

LowAutonomy

public static final int LowAutonomy

Autonomy level: low autonomy; an agent operating with this level is hardly autonomous.

See Also:

AutonomyLevel(int), Constant Field Values

DefaultPlatformName

public static final java.lang.String DefaultPlatformName

A default name for a platform when no platform name is specified in the preferences file.

See Also:

Constant Field Values

Preferences

public static final AblePlatformPreferences Preferences

The current set of preferences, as loaded from the preferences file.

KeyGenerator

public static final java.security.KeyPairGenerator KeyGenerator

This KeyPairGenerator is created using the cryptography algorithm and cryptography provider specified in the preferences file. (A preference file must specifiy a cryptography algorithm. The cryptography provider is optional.) The KeyPairGenerator is used by ABLE platform services, AblePlatformDefaultAgents, and other platform code to obtain KeyPairs. The KeyPairGenerator is always available, even if security is off.

See Also:

getPlatformCryptographyAlgorithm(), getPlatformCryptographyProvider()

Method Detail

AutonomyLevel

public static final AbleMessageContainer AutonomyLevel(int theAutonomyLevel)

Turns the specified autonomy level into a human readable form for error messages.

Parameters:

theAutonomyLevel - A valid (or invalid) AblePlatform.<AutonomyLevel> value.

Returns:

A human readable form of the specified autonomy level; for example, "High" is returned if the input argument is the value HighAutonomy. If the specified number is not a valid autonomy level, "AutonomyLevel_Unrecognised " is returned, where "n" is the original input argument.

See Also:

CustomAutonomy, HighAutonomy, MediumAutonomy, LowAutonomy

generateKeyPair

public static final java.security.KeyPair generateKeyPair()

Gets a KeyPair from the special KeyPairGenerator created using the cryptography algorithm and cryptography provider specified in the preferences file.

Returns:

A KeyPair, or null if a KeyPair cannot be obtained for any reason.

See Also:

KeyGenerator

getPlatformCryptographyAlgorithm

public static java.lang.String getPlatformCryptographyAlgorithm()

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

Returns:

The platform's cryptography algorithm.

See Also:

AblePlatformPreferences.getCryptographyAlgorithm()

getPlatformCryptographyProvider

public static java.lang.String getPlatformCryptographyProvider()

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

Returns:

The platform's cryptography provider.

See Also:

AblePlatformPreferences.getCryptographyProvider()

getPlatformName

public static java.lang.String getPlatformName()

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

Returns:

The platform's name.

See Also:

AblePlatformPreferences.getPlatformName()

getPlatformSecurity

public static boolean getPlatformSecurity()

Gets the platform's security setting as specified in the platform preference file.

Returns:

true if the platform is operating with security on; false otherwise.

See Also:

AblePreferences.getSecurity()

getPlatformServiceRoot

public static javax.agent.service.ServiceRoot getPlatformServiceRoot(java.lang.String theRequestorsPort)

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, containing just those services that have been successfully started at the time of the call.

See Also:

getServiceRoot(String)

getServiceRoot

public static javax.agent.service.ServiceRoot getServiceRoot(java.lang.String theRequestorsPort)

Gets the platform's service root.

The JAS ServiceManager.getService method is used to create or locate each service configured in the platform preference file.

Each call to this method generates a new ServiceRoot, rather than returning a cached ServiceRoot, because a service may go down and come back up at a new IP address. Also, using this technique ensures that if a service needs to be restarted on the local host, it will be.

If a configured service is missing at some remote host, that error is logged.

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, containing just those services that have been successfully started at the time of the call.

getService

public static javax.agent.service.Service getService(java.lang.String theRequestorsPort,
                                                     java.lang.String theServiceAlias)
                                              throws AbleException

Gets the specified platform service.

Note that the JAS ServiceManager is called to find the 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 alias of the service as mandated by the platform preference file; note that the alias must be the desired service's actual binding name (case insensitive).

Returns:

The requested service, if found (either located or created). If not found, an exception is thrown.

Throws:

AbleException - If the specified service cannot be located or created.

getLocatorForType

public static javax.agent.Locator getLocatorForType(javax.agent.service.directory.AgentDescription theAgentDescription,
                                                    java.lang.String theDesiredType)

Extracts and returns a Locator of the given type from the given AgentDescription.

Parameters:

theAgentDescription - The AgentDescription in which to look for the Locator.

theDesiredType - The type of Locator to look for.

Returns:

The locator with the desired type, or null if none is found.

getLocatorForInbox

public static javax.agent.Locator getLocatorForInbox(javax.agent.service.directory.AgentDescription theAgentDescription,
                                                     java.lang.String theInboxName)

Searches the given AgentDescription for a Locator with the given inbox name, and returns the first one found. Looks for the inbox name under the key stored in com.ibm.able.platform.AblePlatform.AbleLocatorProtocol.

Parameters:

theAgentDescription - The AgentDescription to search.

theInboxName - The name of the inbox to search for.

Returns:

The Locator with the given inbox name, or null if not found.

NlsMsg

public static java.lang.String NlsMsg(java.lang.String theMsgKey)

Gets an NLS message by key; the message must not contain any insertion text.

Parameters:

theMsgKey - A unique key identifying the message to be retrieved.

Returns:

The requested message, if found; if not found, a message in English declaring the specified key is unknown.

NlsMsg

public static java.lang.String NlsMsg(java.lang.String theMsgKey,
                                      java.lang.Object[] theInserts)

Gets an NLS message by key with the specified text inserted into the message.

Parameters:

theMsgKey - A unique key identifying the message to be retrieved.

theInserts - An array of String objects which are inserted into the message before it is returned.

Returns:

The requested message, with text inserted, if found; if not found, a message in English declaring the specified key is unknown, with the insertion text appended to the end of the message.

getAgentReference

public static AblePlatformAgent getAgentReference(javax.agent.service.directory.AgentDescription theAgentDescription)

Extracts a direct reference to an AblePlatformAgent from an AgentDescription created and registered by that same agent.

Parameters:

theAgentDescription - Must be an AgentDescription created by an AblePlatformAgent and obtained from the AgentDirectoryService.

Returns:

A reference to an AblePlatformAgent, if found, or null if not found, or if the agent is not an instance of an AblePlatformAgent.

Since:

ABLE 2.3.0