com.sas.services
Class AbstractRemoteService

com.sas.services.AbstractRemoteService

All Implemented Interfaces:

com.sas.entities.EntityKeyInterface, ServiceNotificationBroadcasterInterface, RemoteServiceInterface, java.rmi.Remote

Direct Known Subclasses:

AbstractService, ActivatableDiscoveryService, AuthenticationService, EventBrokerDiscoveryService, EventBrokerService, InformationService, SessionService, UserService

public abstract class AbstractRemoteService
implements RemoteServiceInterface, ServiceNotificationBroadcasterInterface

Abstract implementation of a remoteable service. A service may extend this implementation if it is remoteable and is intended to be deployed in a distributed environment.

Note that this class is extended by com.sas.services.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

AbstractRemoteService()
Constructs a service.

AbstractRemoteService(DiscoveryServiceInterface discoveryService)
Constructs a service.

Method Summary

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.
long	getCreationTime() Gets the time at which this configuration was created.
java.lang.String	getDetails() Returns a String representation of this service.
DiscoveryServiceInterface	getDiscoveryService() Gets the discovery service.
java.lang.String	getEntityKey() Gets this service's entity key.
protected Environment	getEnvironment() Get the Environment object.
ServiceConfigurationInterface	getServiceConfiguration() Gets this service's configuration.
ServiceConfigurationInterface	getServiceConfiguration(java.lang.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.
boolean	isHandlingJVMShutdown() Determines whether or not this service is currently handling a JVM shutdown.
void	notifyServiceObservers(ServiceEvent serviceEvent) Notify all registered service observers of the specified service event.
void	reconfigure(ServiceConfigurationInterface serviceConfiguration) Re-configures the service.
void	removeAllServiceObservers() Removes all service observers.
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(java.lang.String entityKey) Set the unique entity key for the service.
void	setRemoteableExporter(RemoteObjectExporterInterface remoteableExporter) Sets the remoteable exporter.
void	setServiceState(ServiceState serviceState) Sets the service's state.
java.lang.String	toString() Returns a String representation of this service that includes the service's entity key.
void	unbindFromDiscoveryService() Unbinds this service from the discovery service.

Constructor Detail

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 bind in order to be discoverable by other services.

Method Detail

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

Unbinds this service from the discovery service.

Throws:

ServiceException - if an exception was encountered unbinding 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(RemoteObjectExporterInterface remoteableExporter)
                           throws java.lang.IllegalStateException

Sets the remoteable exporter.

Parameters:

remoteableExporter - Utility to export/unexport a remoteable object.

Throws:

java.lang.IllegalStateException - if the service has been destroyed.

getServiceConfiguration

public ServiceConfigurationInterface getServiceConfiguration()
                                                      throws java.lang.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:

java.lang.IllegalStateException - if the service has been destroyed.

getServiceConfiguration

public ServiceConfigurationInterface getServiceConfiguration(java.lang.Object key)
                                                      throws java.lang.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:

java.lang.IllegalStateException - if the service has been destroyed.

configure

public void configure(ServiceConfigurationInterface serviceConfiguration)
               throws InitializationException,
                      java.rmi.RemoteException,
                      ServiceException

Configures the service.

Specified by:

configure in interface RemoteServiceInterface

Parameters:

serviceConfiguration - Service's configuration.

Throws:

InitializationException - in unable to configure the service.

java.rmi.RemoteException - if a network anomaly is encountered.

ServiceException - if a service exception is encountered.

reconfigure

public void reconfigure(ServiceConfigurationInterface serviceConfiguration)
                 throws ServiceException,
                        java.rmi.RemoteException

Re-configures the service.

Specified by:

reconfigure in interface RemoteServiceInterface

Parameters:

serviceConfiguration - Service's configuration.

Throws:

ServiceException - in unable to reconfigure the service.

java.rmi.RemoteException - if a network anomaly is encountered.

getEntityKey

public java.lang.String getEntityKey()
                              throws java.rmi.RemoteException,
                                     java.lang.IllegalStateException

Gets this service's entity key.

Specified by:

getEntityKey in interface com.sas.entities.EntityKeyInterface

Returns:

Service's entity key.

Throws:

java.rmi.RemoteException - if a network anomaly occurs.

java.lang.IllegalStateException - if the service has been destroyed.

setEntityKey

public void setEntityKey(java.lang.String entityKey)
                  throws java.rmi.RemoteException,
                         java.lang.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:

java.rmi.RemoteException - if a network anomaly occurs.

java.lang.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 java.rmi.RemoteException,
                          java.lang.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:

java.rmi.RemoteException - if a network anomaly occurs.

java.lang.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.

java.lang.IllegalArgumentException - if a null service state is specified.

isExported

public boolean isExported()
                   throws java.lang.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:

java.lang.IllegalStateException - if the service has not been configured or has been destroyed.

isAccessibleToRemoteClients

public boolean isAccessibleToRemoteClients()
                                    throws java.lang.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:

java.lang.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 callback 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 callback.

destroy

public void destroy()
             throws java.rmi.RemoteException,
                    ServiceException

Handles the destruction of this service. If this service 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:

java.rmi.RemoteException - if a network anomaly is encountered.

ServiceException - if a service exception is encountered.

addServiceObserver

public final void addServiceObserver(ServiceRemoteObserverInterface serviceObserver)
                              throws java.rmi.RemoteException,
                                     java.lang.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:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException - if the service has not been configured or has been destroyed.

removeServiceObserver

public final void removeServiceObserver(ServiceRemoteObserverInterface serviceObserver)
                                 throws java.rmi.RemoteException

Removes a service observer.

Specified by:

removeServiceObserver in interface ServiceNotificationBroadcasterInterface

Parameters:

serviceObserver - An observer no longer interested in receiving service notifications.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

removeAllServiceObservers

public final void removeAllServiceObservers()
                                     throws java.rmi.RemoteException

Removes all service observers.

Specified by:

removeAllServiceObservers in interface ServiceNotificationBroadcasterInterface

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

notifyServiceObservers

public final void notifyServiceObservers(ServiceEvent serviceEvent)
                                  throws java.rmi.RemoteException,
                                         java.lang.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:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.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 java.lang.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:

java.lang.IllegalStateException - if the service has not been configured or has been destroyed.

getDetails

public java.lang.String getDetails()

Returns a String representation of this service.

Returns:

String representation of this service.

toString

public java.lang.String toString()

Returns a String representation of this service that includes the service's entity key.

Overrides:

toString in class java.lang.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.