com.sas.services
Class ServiceProxy

com.sas.services.ServiceProxy

All Implemented Interfaces:

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

Direct Known Subclasses:

RemoteDiscoveryServiceProxy, SessionServiceProxy, StoredProcessServiceProxy

public class ServiceProxy
implements RemoteServiceInterface, java.io.Serializable

Foundation service proxy. If the service is available locally then a local reference will be used. If a local reference isn't available, then the remote service stub will be proxied.

Some attributes of a service are defined at the time a service is constructed an not alterable.

• time at which the service was created
• service's ID (its entity key)
• service configuration

The following attributes are not cached to ensure that the current value is always obtained.

• service's state

Some service methods may not be invoked by a client that is remote to the process in which the service was instantiated. These methods will be ignored if invoked by a remote client.

• removeAllServiceObservers()
• setServiceState(ServiceState)

Since:

1.1

See Also:

Serialized Form

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

ServiceProxy(RemoteServiceInterface service)
Constructs a foundation service proxy for the specified service.

Method Summary

void	addServiceObserver(ServiceRemoteObserverInterface serviceObserver) Adds a service observer.
void	configure(ServiceConfigurationInterface serviceConfiguration) Configures the service.
void	destroy() Destroys the service proxy.
protected RemoteServiceInterface	findRemoteService() Attempts to re-discover an instance of a remote service represented by this proxy.
long	getCreationTime() Gets the time at which this service was created.
java.lang.String	getEntityKey() Gets the service proxy's entity key.
protected RemoteServiceInterface	getService() Gets the service.
ServiceConfigurationInterface	getServiceConfiguration() Gets the service's configuration.
ServiceConfigurationInterface	getServiceConfiguration(java.lang.Object key) Gets the service's configuration associated with the specified lookup key.
RemoteServiceInterface	getServiceProxy() Gets the service proxy.
short	getServiceState() Gets the foundation service's state.
boolean	isAccessibleToRemoteClients() Determines whether or not the service is accessible to remote clients.
boolean	isExported() Determines whether or not the service has been exported to the RMI system.
boolean	isLocalService() Determines whether or not this proxy has a local handle to the service.
boolean	isProxyToRemoteService() Determines whether or not this is a proxy to a remote service
void	notifyServiceObservers(ServiceEvent serviceEvent) Notify all registered service observers of the specified service event.
void	reconfigure(ServiceConfigurationInterface serviceConfiguration) Reconfigure the service.
void	removeAllServiceObservers() Removes all service observers.
void	removeServiceObserver(ServiceRemoteObserverInterface serviceObserver) Removes a service observer.
boolean	sameEnitityKey(java.lang.String entityKey) Determines if the this service's entity key is the same.
boolean	sameEntity(com.sas.entities.EntityKeyInterface entity) Determines whether or not the specified entity is the same as this entity.
void	setEntityKey(java.lang.String entityKey)
void	setServiceState(ServiceState serviceState) Sets the state of the service.

Constructor Detail

ServiceProxy

public ServiceProxy(RemoteServiceInterface service)
             throws InitializationException

Constructs a foundation service proxy for the specified service. The service may be either a locally accessible service or a stub to a remotely accessible service. If its a remote stub, then the static attributes of the service will be cached to eliminate the need to query them via the stub.

Parameters:

service - Foundation service.

Throws:

InitializationException - if an invalid service is specified.

Method Detail

getService

protected final RemoteServiceInterface getService()
                                           throws java.lang.IllegalStateException

Gets the service. The returned service will be either a remote service stub or a locally accessible service. If a local reference is available it will be returned.

If the proxied service is a stub to a remote service which is no longer available because it is not reachable on a particular host:port, then a ConnectException will be thrown when one attempts to invoke a service method.

If the proxied service is a stub to a remote service which is no longer available because it is not reachable on a particular host and well known port, then a NoSuchObjectException will be thrown when one attempts to invoke a service method. This indicates that the remote object is no longer registered in the remote JVM by the specified object ID.

If either of these conditions apply, then a subclass implementation of this proxy may wish to catch this exception and invoke findRemoteService() to attempt to re-initialize this proxy with another remote service stub that satisfies the same service template as the original proxied service.

Returns:

The proxied foundation service.

Throws:

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

configure

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

Configures the service. Note that this method may used to initialize a service or to re-configure a previously initialized service.

An InitializationException will be thrown if the service is unable to complete the configuration request successfully. Suggested policy for handling such an exception is for the service to invoke its destroy() method if a service is being initialized.

A ServiceException will be thrown if a request to reconfigure the service fails and the service is able to restore its previous configuration. If a reconfiguration request fails and the service is unable to restore its previous configuration, then an InitializationException should be thrown instead of a ServiceException.

Specified by:

configure in interface RemoteServiceInterface

Parameters:

serviceConfiguration - An object containing configuration data necessary to initialize or re-configure a service. Note that the service must verify that the object type is supported. An InitializationException should be thrown if the initialization was not completed successfully to indicate that the instance should not be used.

Throws:

InitializationException - if unable to initialize the service. If this exception is thrown then the service should not be used.

ServiceException - if a previously initialized service does not support reconfiguration.

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

reconfigure

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

Reconfigure the service. This method should be used to reinitialize a service.

Since the configure method provides one-time functionality such as exporting and adding shutdown hooks, this method should be used in lieu of the configure method to re-configure a service.

Specified by:

reconfigure in interface RemoteServiceInterface

Parameters:

serviceConfiguration - An object containing configuration data necessary to re-configure a service.

Throws:

ServiceException - if unable to re-configure the service.

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

java.lang.IllegalStateException

isExported

public boolean isExported()
                   throws ServiceException

Determines whether or not the service has been exported to the RMI system.

Specified by:

isExported in interface RemoteServiceInterface

Returns:

true if the service has been exported or false if it hasn't.

Throws:

ServiceException - if unable to process the request.

isAccessibleToRemoteClients

public boolean isAccessibleToRemoteClients()
                                    throws ServiceException

Determines whether or not the service is accessible to remote clients.

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:

ServiceException - if unable to process the request.

getCreationTime

public final long getCreationTime()

Gets the time at which this service was created.

Specified by:

getCreationTime in interface RemoteServiceInterface

Returns:

The time the service was created.

getServiceState

public final short getServiceState()
                            throws java.rmi.RemoteException

Gets the foundation service's state. The state is always queried from the service since its value may change over time.

Specified by:

getServiceState in interface RemoteServiceInterface

Returns:

Service's state.

Throws:

java.rmi.RemoteException - if unable to ascertain the state of a remote service.

setServiceState

public final void setServiceState(ServiceState serviceState)
                           throws ServiceException

Sets the state of the service.

Specified by:

setServiceState in interface RemoteServiceInterface

Parameters:

serviceState - Service's state.

Throws:

ServiceException - if an invalid service state is specified.

getServiceConfiguration

public final ServiceConfigurationInterface getServiceConfiguration()

Gets the service's configuration. The configuration is data defined at service construction time that is not updateable by remote clients. If this proxy is for a remote service, then the remote service's configuration is cached to eliminate an unnecessary call to obtain static data that isn't going change.

Specified by:

getServiceConfiguration in interface RemoteServiceInterface

Returns:

Service's configuration or null if a configuration is not defined.

getServiceConfiguration

public final ServiceConfigurationInterface getServiceConfiguration(java.lang.Object key)

Gets the service's configuration associated with the specified lookup key. If no service configuration is defined then this method will return null.

Specified by:

getServiceConfiguration in interface RemoteServiceInterface

Parameters:

key - Lookup key for the desired service configuration.

Returns:

Service's configuration or null if no service configuration is defined.

getServiceProxy

public RemoteServiceInterface getServiceProxy()

Gets the service proxy.

Specified by:

getServiceProxy in interface RemoteServiceInterface

Returns:

A proxy to this service or null if a proxy is not available.

addServiceObserver

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

Adds a service observer.

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.

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

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.

destroy

public final void destroy()

Destroys the service proxy.

Specified by:

destroy in interface RemoteServiceInterface

getEntityKey

public final java.lang.String getEntityKey()

Gets the service proxy's entity key.

Specified by:

getEntityKey in interface com.sas.entities.EntityKeyInterface

Returns:

The service's ID. A null ID indicates that an entity key could not be determined for the service indicating that the service is not accessible.

setEntityKey

public final void setEntityKey(java.lang.String entityKey)

Specified by:

setEntityKey in interface com.sas.entities.EntityKeyInterface

sameEntity

public final boolean sameEntity(com.sas.entities.EntityKeyInterface entity)

Determines whether or not the specified entity is the same as this entity.

Specified by:

sameEntity in interface com.sas.entities.EntityKeyInterface

Parameters:

entity - Entity to be compared

Returns:

true if the entities are the same.

See Also:

EntityKeyInterface.sameEntity(EntityKeyInterface)

sameEnitityKey

public final boolean sameEnitityKey(java.lang.String entityKey)

Determines if the this service's entity key is the same.

Parameters:

entityKey - Another service's entity key.

Returns:

true if the entity key's are the same.

isProxyToRemoteService

public final boolean isProxyToRemoteService()

Determines whether or not this is a proxy to a remote service

Returns:

true if this is a proxy to a remote service or false if it is a proxy to local service.

isLocalService

public final boolean isLocalService()

Determines whether or not this proxy has a local handle to the service.

Returns:

true if the service is local.

findRemoteService

protected RemoteServiceInterface findRemoteService()
                                            throws ServiceException,
                                                   java.rmi.RemoteException

Attempts to re-discover an instance of a remote service represented by this proxy.

Returns:

A remotely accessible service that has been re-discovered or null if the service is not available.

Throws:

ServiceException - if unable to re-discover the service.

java.rmi.RemoteException - if unable to discover a networked service.