com.ibm.able.platform
Class AbleBasicService

java.lang.Object
  java.rmi.server.RemoteObject
      org.jagent.service.util.RMIBasicService
          com.ibm.able.platform.AbleBasicService

All Implemented Interfaces:

org.jagent.service.IPService, java.rmi.Remote, RmiAblePlatformService, RmiAblePlatformServiceEventGenerator, org.jagent.service.RMIService, java.io.Serializable, javax.agent.service.Service

Direct Known Subclasses:

RmiAgentLifeCycleSystem, RmiAgentLoggingSystem, RmiPlatformPersistenceSystem, RmiPlatformSupportServiceSystem, RMIVerifiableDirectorySystem, RMIVerifiableNamingSystem

public abstract class AbleBasicService

extends org.jagent.service.util.RMIBasicService

implements RmiAblePlatformService

The base class of all ABLE-provided platform services, such as the VerifiableAgentDirectoryService, the VerifiableAgentNamingService, and the AgentLifeCycleService; this class is inserted between the JAS RMIBasicService and all ABLE-supplied services to provide common function to the ABLE-supplied services. To derived services this class provides:

• A registry of service event listeners and methods to add, remove, and notify registered service event listeners. These methods are implementations of methods found in the RmiAblePlatformServiceEventGenerator interface.
• A flag to keep track of what state the service is currently in.
• A reference to a Message logger where informational, warning, and error messages can be routed.
• A reference to a Trace logger where tracing information can be routed.

Additionally, when security is on (Able.Preferences.isSecure()==true), this class provides:

• Public and Private keys (in a KeyPair) that can be used for signing, unsigning, encrypting, and decrypting objects.
• A VerifiableAgentName (VAN) so that the service can legitimately identify itself to other services and, through the VerifiableAgentNamingService, identify requestors of its own services.
• A SecuritySupport object that can be used to generate and verify security keys, as some methods can only be accessed through valid security keys.
• The KERBEROS principal of the person that is responsible for this service.
• A Trust Level, which together with SecuritySupport and security keys, is used to determine what access is allowed to requestors of this service.
• A cached reference to the VerifiableNamingService, since the service is heavily used when security is on.

This class is abstract because it does not implement the getBindingName() method specified by RMIBasicService. That method must be implemented by classes derived from this one.

See Also:

Serialized Form

Field Summary

static java.lang.String	ANS_PRINCIPAL Service Properties passed to a service's factory when the service is started by AblePlatformSupport.
static java.lang.String	LOCAL_PRINCIPAL
protected java.lang.String	myAnsPrincipal The principal of the AgentNamingService.
protected java.security.KeyPair	myKeyPair The Public and Private keys for this service.
protected AbleLogger	myMsgLog A logger where informational, warning, and error messages can be routed.
protected java.lang.String	myPrincipal The principal of this service.
protected AbleSecuritySupport	mySecSppt A helper object to assist with security related matters.
protected java.util.Vector	myServiceEventListeners Service event listeners that are registered with this service.
protected javax.agent.service.ServiceProperties	myServiceProperties ServiceProperies passed to this service's contructor are cached here.
protected AbleLogger	myTrcLog A logger where tracing information can be routed.
protected java.lang.String	myTrustLevel The Trust Level contained in the VerifiableAgentName (VAN) for this service.
protected VerifiableAgentName	myVerifiableAgentName The IBM Verifiable Agent Name (VAN) for this service.
protected VerifiableAgentNamingService	myVerifiableNamingService The IBM VerifiableAgentNamingService for this service, set in the constructor.
static int	Refreshing Service state: the service is running, but is in the process of refreshing its data from the persistence store.
static java.lang.String	REQUESTORS_PORT
static int	Running Service state: the service is active; it has been invoked.
static java.lang.String	SOCKET_FACTORY
static int	Terminated Service state: the service has been terminated.
static int	Unknown Service state: the service is in an unknown state.

Fields inherited from class java.rmi.server.RemoteObject

ref

Fields inherited from interface org.jagent.service.RMIService

RMI, SERVICE_PROTOCOL

Fields inherited from interface org.jagent.service.IPService

SERVICE_HOST, SERVICE_PORT

Constructor Summary

AbleBasicService()
Creates an instance of the basic service.

AbleBasicService(javax.agent.service.ServiceProperties theServiceProperties)
Creates an instance of the basic service based on the specified service properties.

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.
int	getState() Gets the current state of this service.
protected void	notifyAblePlatformServiceEventListeners(AblePlatformServiceEvent theEvent, AblePersistenceSupport thePrstSppt, java.lang.String theListenerColumnName) Delivers the specified service event to all registered service event listeners; should any service event listener fail to receive the event, the listener is removed from the list and will receive no furhter events until it reregisters.
void	removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Removes a service event listener from this service.
protected void	setState(int theState) Sets the state of this service.
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.
protected void	thenNotifyAblePlatformServiceEventListeners(java.lang.String theCallingMethod, int theEventId, java.lang.String theEventDescription, java.lang.Object theEventObject1, java.lang.Object theEventObject2, AblePersistenceSupport thePrstSppt, java.lang.String theListenerColumnName) Packages the specified parameters into an AblePlatformServiceEvent and calls "notify" to deliver the event to all registered service event listeners.

Methods inherited from class org.jagent.service.util.RMIBasicService

bindServiceToRegistry, getBindingName, getServiceProperties, setServiceProperties, shutdown

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ANS_PRINCIPAL

public static final java.lang.String ANS_PRINCIPAL

Service Properties passed to a service's factory when the service is started by AblePlatformSupport.

See Also:

Constant Field Values

LOCAL_PRINCIPAL

public static final java.lang.String LOCAL_PRINCIPAL

See Also:

Constant Field Values

REQUESTORS_PORT

public static final java.lang.String REQUESTORS_PORT

See Also:

Constant Field Values

SOCKET_FACTORY

public static final java.lang.String SOCKET_FACTORY

See Also:

Constant Field Values

Unknown

public static final int Unknown

Service state: the service is in an unknown state.

See Also:

Constant Field Values

Running

public static final int Running

Service state: the service is active; it has been invoked.

See Also:

Constant Field Values

Refreshing

public static final int Refreshing

Service state: the service is running, but is in the process of refreshing its data from the persistence store.

See Also:

Constant Field Values

Terminated

public static final int Terminated

Service state: the service has been terminated.

See Also:

Constant Field Values

myServiceEventListeners

protected final java.util.Vector myServiceEventListeners

Service event listeners that are registered with this service.

See Also:

addAblePlatformServiceEventListener(AblePlatformServiceEventListener), removeAblePlatformServiceEventListener(AblePlatformServiceEventListener), notifyAblePlatformServiceEventListeners(AblePlatformServiceEvent,AblePersistenceSupport,String)

myKeyPair

protected java.security.KeyPair myKeyPair

The Public and Private keys for this service.

Note that this field is always null unless platform security is on.

This field is set by the constructor.

myVerifiableAgentName

protected VerifiableAgentName myVerifiableAgentName

The IBM Verifiable Agent Name (VAN) for this service. The service does not have to be an "agent" to have a VAN.

Note that this field is always null unless platform security is on.

If security is on, this field is dependent on IBM's VerifiableAgentNamingService.

This field is set by the constructor.

myTrustLevel

protected java.lang.String myTrustLevel

The Trust Level contained in the VerifiableAgentName (VAN) for this service.

myVerifiableNamingService

protected VerifiableAgentNamingService myVerifiableNamingService

The IBM VerifiableAgentNamingService for this service, set in the constructor. This naming service is valid only when platform security is on. Otherwise, the value is always null.

myPrincipal

protected java.lang.String myPrincipal

The principal of this service. This field is initialized to null, and set in the constructor either through platform preferences or service properties. Note that for the AgentNamingService, <myPrincipal> and <myAnsPrincipal> are identical.

See Also:

myAnsPrincipal

myAnsPrincipal

protected java.lang.String myAnsPrincipal

The principal of the AgentNamingService. This field is initialized to null, and set in the constructor either through platform preferences or service properties. Note that for the AgentNamingService, <myPrincipal> and <myAnsPrincipal> are identical.

See Also:

myPrincipal

myServiceProperties

protected javax.agent.service.ServiceProperties myServiceProperties

ServiceProperies passed to this service's contructor are cached here. This is not a clone, but an actual reference to the ServiceProperties object. This field is initialized to null.

mySecSppt

protected AbleSecuritySupport mySecSppt

A helper object to assist with security related matters.

This object is null unless security is on.

When security is on, this object is created by the constructor for all derived services except for the RMIVerifiableNamingService, which, because it is responsible for obtaining its own VAN, must set this field itself.

After construction, this field is used as a helper object to generate and verify secure keys and check trust levels.

myMsgLog

protected AbleLogger myMsgLog

A logger where informational, warning, and error messages can be routed. This field is set in the constructor from Able.MessageLog.

myTrcLog

protected AbleLogger myTrcLog

A logger where tracing information can be routed. This field is set in the constructor from Able.TraceLog.

Constructor Detail

AbleBasicService

public AbleBasicService()
                 throws java.lang.Exception

Creates an instance of the basic service.

AbleBasicService

public AbleBasicService(javax.agent.service.ServiceProperties theServiceProperties)
                 throws java.lang.Exception

Creates an instance of the basic service based on the specified service properties.

Parameters:

theServiceProperties - Service properties on which the service is based. LOCAL_PRINCIPAL, ANS_PRINCIPAL, and RMIService.SERVICE_PORT are a few of the properties examined.

Method Detail

terminateService

public void terminateService(AbleSecureKey theSecureKey)
                      throws AbleException,
                             javax.agent.service.naming.NamingException

Description copied from interface: RmiAblePlatformService

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 RmiAblePlatformService

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:

AbleException

javax.agent.service.naming.NamingException

getState

public int getState()
             throws AbleException

Gets the current state of this service.

The states of Services derived from AbleBasicService are as follows:

• When a service is first created, its state is Unknown.
• During bring-up, if a service needs to recover its internal data from a persistence store, the service's state will change to Refreshing for the duration of that time.

  Services should not be used while they are Refreshing. Data returned from any such calls during this time should not be trusted.

• After construction and after any data recovery activity, the service's state is Running. This is a service's normal state, and the service can be used in the normal way.
• If a call to terminateService is successful, the service's state is Terminated. Any attempt to use a service in this state will most likely result in an exception.

Specified by:

getState in interface RmiAblePlatformService

Returns:

The state of this service.

Throws:

AbleException - On any RMI error.

See Also:

Running, Refreshing, Terminated, Unknown

addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                         throws AbleException

Description copied from interface: RmiAblePlatformServiceEventGenerator

Adds a service event listener to this service.

Specified by:

addAblePlatformServiceEventListener in interface RmiAblePlatformServiceEventGenerator

Parameters:

theListener - Any object interested in listening for service events generated by this service.

Throws:

AbleException

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                            throws AbleException

Description copied from interface: RmiAblePlatformServiceEventGenerator

Removes a service event listener from this service.

Specified by:

removeAblePlatformServiceEventListener in interface RmiAblePlatformServiceEventGenerator

Parameters:

theListener - A previously registered object that is no longer interested in listening for service events generated by this service.

Throws:

AbleException

getAblePlatformServiceEventListeners

public java.util.Vector getAblePlatformServiceEventListeners()
                                                      throws AbleException

Description copied from interface: RmiAblePlatformServiceEventGenerator

Gets a collection of all service event listeners registered with this service event generator.

Specified by:

getAblePlatformServiceEventListeners in interface RmiAblePlatformServiceEventGenerator

Returns:

All registered AblePlatformServiceEventListener objects.

Throws:

AbleException

thenNotifyAblePlatformServiceEventListeners

protected void thenNotifyAblePlatformServiceEventListeners(java.lang.String theCallingMethod,
                                                           int theEventId,
                                                           java.lang.String theEventDescription,
                                                           java.lang.Object theEventObject1,
                                                           java.lang.Object theEventObject2,
                                                           AblePersistenceSupport thePrstSppt,
                                                           java.lang.String theListenerColumnName)

Packages the specified parameters into an AblePlatformServiceEvent and calls "notify" to deliver the event to all registered service event listeners.

Parameters:

theCallingMethod - The name of the method generating the service event; for example, "createAgentInstance".

theEventId - A service event ID as defined in AblePlatformServiceEvent

theEventDescription - An NLS message describing the event.

theEventObject1 - An arbitrary object that is solely dependent on the service generating the event. For property-change types of events, this parameter typically contains the "old" property value.

theEventObject2 - An arbitrary object that is solely dependent on the service generating the event. For property-change types of events, this parameter typically contains the "new" property value.

thePrstSppt - The AblePersistenceSupport object from which failing listeners should be removed. If persistence is off, this must be null.

theListenerColumnName - The name of the listener column in thePrstSppt.

See Also:

notifyAblePlatformServiceEventListeners(AblePlatformServiceEvent,AblePersistenceSupport,String), addAblePlatformServiceEventListener(AblePlatformServiceEventListener), removeAblePlatformServiceEventListener(AblePlatformServiceEventListener), AblePlatformServiceEvent

notifyAblePlatformServiceEventListeners

protected void notifyAblePlatformServiceEventListeners(AblePlatformServiceEvent theEvent,
                                                       AblePersistenceSupport thePrstSppt,
                                                       java.lang.String theListenerColumnName)
                                                throws javax.agent.service.ServiceException,
                                                       javax.agent.service.ServiceFailure

Delivers the specified service event to all registered service event listeners; should any service event listener fail to receive the event, the listener is removed from the list and will receive no furhter events until it reregisters.

Parameters:

theEvent - The service event to be broadcast to all registered service event listeners.

thePrstSppt - The AblePersistenceSupport object from which failing listeners should be removed. If persistence is off, this must be null.

theListenerColumnName - The name of the listener column in thePrstSppt.

Throws:

javax.agent.service.ServiceException - On any service error.

javax.agent.service.ServiceFailure - On any service failure.

See Also:

thenNotifyAblePlatformServiceEventListeners(String,int,String,Object,Object,AblePersistenceSupport,String), addAblePlatformServiceEventListener(AblePlatformServiceEventListener), removeAblePlatformServiceEventListener(AblePlatformServiceEventListener), AblePlatformServiceEvent

setState

protected void setState(int theState)

Sets the state of this service. Once the state is set to AbleBasicService.Terminated then the state may no longer be altered.

Parameters:

theState - What the service's current state should be set to.

See Also: