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

    `

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