Package com.sas.services

# Class AbstractRemoteService

java.lang.Object
com.sas.services.AbstractRemoteService

All Implemented Interfaces:
  `com.sas.entities.EntityKeyInterface`, `ServiceNotificationBroadcasterInterface`, `RemoteServiceInterface`, `Remote`

Direct Known Subclasses:
  `AbstractService`, `ActivatableDiscoveryService`, `AuthenticationService`, `EventBrokerDiscoveryService`, `EventBrokerService`, `InformationService`, `SessionService`, `UserService`

public abstract class AbstractRemoteService extends Object implements RemoteServiceInterface, ServiceNotificationBroadcasterInterface
Abstract implementation of a service which can be accessed from a remote JVM. A service may extend this implementation if it is intended to be deployed in a distributed environment.

Note that this class is extended by `AbstractService` which provides a version that may be used locally within a JVM process. Methods specified in the local version do not throw `RemoteException`.

Since:
  1.0
See Also:
  - `RemoteServiceInterface`
  - `ServiceConfigurationInterface`

- ## Field Summary

  ### Fields inherited from interface com.sas.services.RemoteServiceInterface

  `CLASS_IDENTIFIER, CLASS_IDENTIFIER_1_1, CLASS_IDENTIFIER_1_2, CLASS_IDENTIFIER_SERVICE_TYPE, CLASS_IDENTIFIER_SERVICE_TYPE_1_1, CLASS_IDENTIFIER_SERVICE_TYPE_1_2`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractRemoteService()`
  Constructs a service.
  `AbstractRemoteService(DiscoveryServiceInterface discoveryService)`
  Constructs a service.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `addServiceObserver(ServiceRemoteObserverInterface serviceObserver)`
  Adds a service observer.
  `void`
  `bindToDiscoveryService()`
  Binds this service to the discovery service.
  `void`
  `configure(ServiceConfigurationInterface serviceConfiguration)`
  Configures the service.
  `void`
  `destroy()`
  Handles the destruction of this service.
  `final long`
  `getCreationTime()`
  Gets the time at which this configuration was created.
  `String`
  `getDetails()`
  Returns a String representation of this service.
  `DiscoveryServiceInterface`
  `getDiscoveryService()`
  Gets the discovery service.
  `String`
  `getEntityKey()`
  Gets this service's entity key.
  `protected final Environment`
  `getEnvironment()`
  Get the Environment object.
  `ServiceConfigurationInterface`
  `getServiceConfiguration()`
  Gets this service's configuration.
  `ServiceConfigurationInterface`
  `getServiceConfiguration(Object key)`
  Gets the service configuration associated with the specified lookup key.
  `RemoteServiceInterface`
  `getServiceProxy()`
  Gets the service proxy.
  `short`
  `getServiceState()`
  Gets the service's state.
  `void`
  `handleJVMShutdown()`
  Handles JVM shutdown to destroy resources allocated by this service.
  `boolean`
  `isAccessibleToRemoteClients()`
  Determines whether or not the service is intended to be accessible to remote clients.
  `boolean`
  `isExported()`
  Determines whether or not the service has been exported to the RMI system.
  `final boolean`
  `isHandlingJVMShutdown()`
  Determines whether or not this service is currently handling a JVM shutdown.
  `final void`
  `notifyServiceObservers(ServiceEvent serviceEvent)`
  Notify all registered service observers of the specified service event.
  `void`
  `reconfigure(ServiceConfigurationInterface serviceConfiguration)`
  Re-configures the service.
  `final void`
  `removeAllServiceObservers()`
  Removes all service observers.
  `final void`
  `removeServiceObserver(ServiceRemoteObserverInterface serviceObserver)`
  Removes a service observer.
  `boolean`
  `sameEntity(com.sas.entities.EntityKeyInterface entity)`
  Determines whether or not this service entity is the same as the specified entity.
  `void`
  `setDiscoveryService(DiscoveryServiceInterface discoveryService)`
  Sets the discovery service which may be used to locate other services.
  `void`
  `setEntityKey(String entityKey)`
  Set the unique entity key for the service.
  `void`
  `setRemoteableExporter(com.sas.net.rmi.RemoteObjectExporterInterface remoteableExporter)`
  Sets the remoteable exporter.
  `void`
  `setServiceState(ServiceState serviceState)`
  Sets the service's state.
  `String`
  `toString()`
  Returns a String representation of this service that includes the service's entity key.
  `void`
  `unbindFromDiscoveryService()`
  Removes this service from the discovery service.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### AbstractRemoteService

    public AbstractRemoteService()
    Constructs a service.

  - ### AbstractRemoteService

    public AbstractRemoteService(DiscoveryServiceInterface discoveryService)
    Constructs a service.
    Parameters:
      `discoveryService` - A discovery service which may be used to locate other services and to which a service must be bound in order to be discovered by other services.

- ## Method Details

  - ### getDiscoveryService

    public DiscoveryServiceInterface getDiscoveryService()
    Gets the discovery service.
    Returns:
      Discovery service or `null` if undefined.

  - ### bindToDiscoveryService

    public void bindToDiscoveryService() throws ServiceException
    Binds this service to the discovery service.
    Throws:
      `ServiceException` - if an exception was encountered binding this service to the discovery service.

  - ### unbindFromDiscoveryService

    public void unbindFromDiscoveryService() throws ServiceException
    Removes this service from the discovery service.
    Throws:
      `ServiceException` - if an exception was encountered removing this service from the discovery service.

  - ### setDiscoveryService

    public void setDiscoveryService(DiscoveryServiceInterface discoveryService)
    Sets the discovery service which may be used to locate other services.
    Parameters:
      `discoveryService` - Discovery service which may be used to locate other services.

  - ### setRemoteableExporter

    public void setRemoteableExporter(com.sas.net.rmi.RemoteObjectExporterInterface remoteableExporter) throws IllegalStateException
    Sets the remoteable exporter.
    Parameters:
      `remoteableExporter` - Utility to export/unexport a remoteable object.
    Throws:
      `IllegalStateException` - if the service has been destroyed.

  - ### getServiceConfiguration

    public ServiceConfigurationInterface getServiceConfiguration() throws IllegalStateException
    Gets this service's configuration. The service configuration may contain ancillary sub-configurations which are available via a hash map lookup.

    The service's configuration can always be retrieved regardless of the service's state.

    Specified by:
      `getServiceConfiguration` in interface `RemoteServiceInterface`
    Returns:
      Service's configuration.
    Throws:
      `IllegalStateException` - if the service has been destroyed.

  - ### getServiceConfiguration

    public ServiceConfigurationInterface getServiceConfiguration(Object key) throws IllegalStateException
    Gets the service configuration associated with the specified lookup key. For example, if the base service configuration contained an ancillary configuration keyed by a value like `ServiceConfigurationInterface.CONFIGURATION_SERVICE_DISCOVERY` then this configuration would be returned if defined. If a `null` lookup key is specified, then the base service configuration is returned.

    The service's configuration can always be retrieved regardless of the service's state.

    Specified by:
      `getServiceConfiguration` in interface `RemoteServiceInterface`
    Parameters:
      `key` - Key designating an ancillary configuration.
    Returns:
      Service configuration associated with the specified key or `null` if no configuration is defined for the specified key.
    Throws:
      `IllegalStateException` - if the service has been destroyed.

  - ### configure

    public void configure(ServiceConfigurationInterface serviceConfiguration) throws InitializationException, RemoteException, ServiceException
    Configures the service.
    Specified by:
      `configure` in interface `RemoteServiceInterface`
    Parameters:
      `serviceConfiguration` - Service's configuration.
    Throws:
      `InitializationException` - in unable to configure the service.
      `RemoteException` - if a network anomaly is encountered.
      `ServiceException` - if a service exception is encountered.

  - ### reconfigure

    public void reconfigure(ServiceConfigurationInterface serviceConfiguration) throws ServiceException, RemoteException
    Re-configures the service.
    Specified by:
      `reconfigure` in interface `RemoteServiceInterface`
    Parameters:
      `serviceConfiguration` - Service's configuration.
    Throws:
      `ServiceException` - in unable to reconfigure the service.
      `RemoteException` - if a network anomaly is encountered.

  - ### getEntityKey

    public String getEntityKey() throws RemoteException, IllegalStateException
    Gets this service's entity key.
    Specified by:
      `getEntityKey` in interface `com.sas.entities.EntityKeyInterface`
    Returns:
      Service's entity key.
    Throws:
      `RemoteException` - if a network anomaly occurs.
      `IllegalStateException` - if the service has been destroyed.

  - ### setEntityKey

    public void setEntityKey(String entityKey) throws RemoteException, IllegalStateException
    Set the unique entity key for the service. The entity key for the services cannot be changed. This method will throw an IllegalStateException.
    Specified by:
      `setEntityKey` in interface `com.sas.entities.EntityKeyInterface`
    Parameters:
      `entityKey` - Unique entity key.
    Throws:
      `RemoteException` - if a network anomaly occurs.
      `IllegalStateException` - if the service has been destroyed or if an attempt is made to alter the entity key which is immutable.

  - ### sameEntity

    public boolean sameEntity(com.sas.entities.EntityKeyInterface entity) throws RemoteException, IllegalStateException
    Determines whether or not this service entity is the same as the specified entity.
    Specified by:
      `sameEntity` in interface `com.sas.entities.EntityKeyInterface`
    Parameters:
      `entity` - Entity to be compared to this service entity.
    Returns:
      `true` if the service entities are the same or `false` if they aren't.
    Throws:
      `RemoteException` - if a network anomaly occurs.
      `IllegalStateException` - if the service has been destroyed.

  - ### getServiceState

    public short getServiceState()
    Gets the service's state.
    Specified by:
      `getServiceState` in interface `RemoteServiceInterface`
    Returns:
      Service's state.

  - ### setServiceState

    public void setServiceState(ServiceState serviceState) throws ServiceException
    Sets the service's state.
    Specified by:
      `setServiceState` in interface `RemoteServiceInterface`
    Parameters:
      `serviceState` - Service's new state.
    Throws:
      `ServiceException` - if unable to process the request.
      `IllegalArgumentException` - if a `null` service state is specified.

  - ### isExported

    public boolean isExported() throws IllegalStateException
    Determines whether or not the service has been exported to the RMI system. This method can only be invoked after the service has been configured.
    Specified by:
      `isExported` in interface `RemoteServiceInterface`
    Returns:
      `true` if the service has been exported or `false` if it hasn't.
    Throws:
      `IllegalStateException` - if the service has not been configured or has been destroyed.

  - ### isAccessibleToRemoteClients

    public boolean isAccessibleToRemoteClients() throws IllegalStateException
    Determines whether or not the service is intended to be accessible to remote clients. This method can only be invoked after the service has been configured.
    Specified by:
      `isAccessibleToRemoteClients` in interface `RemoteServiceInterface`
    Returns:
      `true` if the service is intended to be accessible to remote clients or `false` if it isn't.
    Throws:
      `IllegalStateException` - if the service has not been configured or has been destroyed.

  - ### handleJVMShutdown

    public void handleJVMShutdown() throws ServiceException
    Handles JVM shutdown to destroy resources allocated by this service. Note that in the case of a JVM shutdown that each service will be notified by the JVM that a shutdown is occurring. No call back order is guaranteed, so when this occurs a service should not rely upon any other services being available since they may have already been destroyed.
    Throws:
      `ServiceException` - if unable to shutdown cleanly.

  - ### isHandlingJVMShutdown

    public final boolean isHandlingJVMShutdown()
    Determines whether or not this service is currently handling a JVM shutdown.
    Returns:
      `true` if the service is destroying itself in response to a JVM shutdown call back.

  - ### destroy

    public void destroy() throws RemoteException, ServiceException
    Handles the destruction of this service. If this service was previously exported to make it accessible to remote clients, then it will be unexported.

    Once a service has been destroyed it should never be used again. The service's state is set to `ServiceState.SERVICE_STATE_DEACTIVATED`.

    Specified by:
      `destroy` in interface `RemoteServiceInterface`
    Throws:
      `RemoteException` - if a network anomaly is encountered.
      `ServiceException` - if a service exception is encountered.

  - ### addServiceObserver

    public final void addServiceObserver(ServiceRemoteObserverInterface serviceObserver) throws RemoteException, IllegalStateException
    Adds a service observer. This method can only be invoked after the service has been configured.
    Specified by:
      `addServiceObserver` in interface `ServiceNotificationBroadcasterInterface`
    Parameters:
      `serviceObserver` - An observer interested in receiving service notifications.
    Throws:
      `RemoteException` - if a network anomaly is encountered.
      `IllegalStateException` - if the service has not been configured or has been destroyed.

  - ### removeServiceObserver

    public final void removeServiceObserver(ServiceRemoteObserverInterface serviceObserver) throws RemoteException
    Removes a service observer.
    Specified by:
      `removeServiceObserver` in interface `ServiceNotificationBroadcasterInterface`
    Parameters:
      `serviceObserver` - An observer no longer interested in receiving service notifications.
    Throws:
      `RemoteException` - if a network anomaly is encountered.

  - ### removeAllServiceObservers

    public final void removeAllServiceObservers() throws RemoteException
    Removes all service observers.
    Specified by:
      `removeAllServiceObservers` in interface `ServiceNotificationBroadcasterInterface`
    Throws:
      `RemoteException` - if a network anomaly is encountered.

  - ### notifyServiceObservers

    public final void notifyServiceObservers(ServiceEvent serviceEvent) throws RemoteException, IllegalArgumentException
    Notify all registered service observers of the specified service event.
    Specified by:
      `notifyServiceObservers` in interface `ServiceNotificationBroadcasterInterface`
    Parameters:
      `serviceEvent` - Service event to be broadcast to all registered service observers.
    Throws:
      `RemoteException` - if a network anomaly is encountered.
      `IllegalArgumentException` - if a `null` service event is specified.

  - ### getCreationTime

    public final long getCreationTime()
    Gets the time at which this configuration was created. Can be used to order services based upon their creation times. Originally specified using currentTimeMillis().
    Specified by:
      `getCreationTime` in interface `RemoteServiceInterface`
    Returns:
      Time at which this configuration was created.

  - ### getServiceProxy

    public RemoteServiceInterface getServiceProxy() throws IllegalStateException
    Gets the service proxy. A subclass should override this method if a proxy is available. This method can only be invoked after the service has been configured.
    Specified by:
      `getServiceProxy` in interface `RemoteServiceInterface`
    Returns:
      A proxy to this service or `null` if a proxy is not available.
    Throws:
      `IllegalStateException` - if the service has not been configured or has been destroyed.

  - ### getDetails

    public String getDetails()
    Returns a String representation of this service.
    Returns:
      String representation of this service.

  - ### toString

    public String toString()
    Returns a String representation of this service that includes the service's entity key.
    Overrides:
      `toString` in class `Object`
    Returns:
      String representation of this service.

  - ### getEnvironment

    protected final Environment getEnvironment()
    Get the Environment object. An Environment object encapsulates resources provided by the container.
    Returns:
      Environment which may be used to access resources provided by a container or `null`.