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

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, RmiPlatformPersistenceSystem, 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:

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

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 java.lang.String REQUESTORS_PORT
           
static java.lang.String SOCKET_FACTORY
           
 
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.
protected  void notifyAblePlatformServiceEventListeners(AblePlatformServiceEvent theEvent)
          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.
 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)
          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.

LOCAL_PRINCIPAL

public static final java.lang.String LOCAL_PRINCIPAL

REQUESTORS_PORT

public static final java.lang.String REQUESTORS_PORT

SOCKET_FACTORY

public static final java.lang.String SOCKET_FACTORY

myServiceEventListeners

protected final java.util.Vector myServiceEventListeners
Service event listeners that are registered with this service.
See Also:
addAblePlatformServiceEventListener(AblePlatformServiceEventListener), removeAblePlatformServiceEventListener(AblePlatformServiceEventListener), notifyAblePlatformServiceEventListeners(AblePlatformServiceEvent)

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
Following copied from interface: com.ibm.able.platform.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:
java.rmi.RemoteException - On any RMI error.

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
Following copied from interface: com.ibm.able.platform.RmiAblePlatformServiceEventGenerator
Parameters:
theListener - Any object interested in listening for service events generated by this service.

Throws:
java.rmi.RemoteException - On any RMI error.

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
Following copied from interface: com.ibm.able.platform.RmiAblePlatformServiceEventGenerator
Parameters:
theListener - A previously registered object that is no longer interested in listening for service events generated by this service.

Throws:
java.rmi.RemoteException - On any RMI error.

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
Following copied from interface: com.ibm.able.platform.RmiAblePlatformServiceEventGenerator
Returns:
All registered AblePlatformServiceEventListener objects.
Throws:
java.rmi.RemoteException - On any RMI error.

thenNotifyAblePlatformServiceEventListeners

protected void thenNotifyAblePlatformServiceEventListeners(java.lang.String theCallingMethod,
                                                           int theEventId,
                                                           java.lang.String theEventDescription,
                                                           java.lang.Object theEventObject1,
                                                           java.lang.Object theEventObject2)
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.

See Also:
notifyAblePlatformServiceEventListeners(AblePlatformServiceEvent), addAblePlatformServiceEventListener(AblePlatformServiceEventListener), removeAblePlatformServiceEventListener(AblePlatformServiceEventListener), AblePlatformServiceEvent

notifyAblePlatformServiceEventListeners

protected void notifyAblePlatformServiceEventListeners(AblePlatformServiceEvent theEvent)
                                                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.

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), addAblePlatformServiceEventListener(AblePlatformServiceEventListener), removeAblePlatformServiceEventListener(AblePlatformServiceEventListener), AblePlatformServiceEvent

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

(C) Copyright IBM Corporation 1999, 2003