com.sas.services
Class ServiceProxy

java.lang.Object
  |
  +--com.sas.services.ServiceProxy

All Implemented Interfaces:

RemoteServiceInterface, ServiceNotificationBroadcasterInterface

Direct Known Subclasses:

AuthenticationServiceProxy, InformationServiceProxy, RemoteDiscoveryServiceProxy, SessionServiceProxy, StoredProcessServiceProxy, UserServiceProxy

public class ServiceProxy

extends Object

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

Fields inherited from interface com.sas.services.RemoteServiceInterface

CLASS_IDENTIFIER

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 rediscover an instance of a remote service represented by this proxy.
long	getCreationTime() Gets the time at which this service was created.
String	getEntityKey() Gets the service proxy's entity key.
protected RemoteServiceInterface	getService() Gets the service.
ServiceConfigurationInterface	getServiceConfiguration() Gets the service's configuration.
ServiceConfigurationInterface	getServiceConfiguration(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	removeAllServiceObservers() Removes all service observers.
void	removeServiceObserver(ServiceRemoteObserverInterface serviceObserver) Removes a service observer.
boolean	sameEnitityKey(String entityKey) Determines if the this service's entity key is the same.
boolean	sameEntity(EntityKeyInterface entity) Determines whether or not the specified entity is the same as this entity.
void	setEntityKey(String entityKey)
void	setServiceState(ServiceState serviceState) Sets the state of the service.
String	toString() Gets a string representation of this service proxy.

Methods inherited from class java.lang.Object

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

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

IllegalStateException - if the service has been destroyed.

configure

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

Description copied from interface: RemoteServiceInterface

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

Throws:

IllegalStateException - if service re-configuration is not supported.

See Also:

RemoteServiceInterface.configure(com.sas.services.ServiceConfigurationInterface)

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()

Description copied from interface: RemoteServiceInterface

Gets the time at which this service was created.

Specified by:

getCreationTime in interface RemoteServiceInterface

See Also:

RemoteServiceInterface.getCreationTime()

getServiceState

public final short getServiceState()
                            throws 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:

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

setServiceState

public final void setServiceState(ServiceState serviceState)
                           throws ServiceException

Description copied from interface: RemoteServiceInterface

Sets the state of the service.

Specified by:

setServiceState in interface RemoteServiceInterface

See Also:

RemoteServiceInterface.setServiceState(com.sas.services.ServiceState)

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(Object key)

Description copied from interface: RemoteServiceInterface

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

See Also:

RemoteServiceInterface.getServiceConfiguration(java.lang.Object)

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 RemoteException

Adds a service observer.

Specified by:

addServiceObserver in interface ServiceNotificationBroadcasterInterface

Parameters:

serviceObserver - An observer interested in receiving service notifications.

Throws:

RemoteException - if a network anomaly is encountered.

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

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.

destroy

public final void destroy()

Destroys the service proxy.

Specified by:

destroy in interface RemoteServiceInterface

Following copied from interface: com.sas.services.RemoteServiceInterface

Throws:

RemoteException - if a network anomaly is encountered.

ServiceException - if the service is unable to prepare itself for destruction.

getEntityKey

public final String getEntityKey()

Gets the service proxy's entity key.

Specified by:

getEntityKey in interface 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(String entityKey)

Specified by:

setEntityKey in interface EntityKeyInterface

See Also:

EntityKeyInterface.setEntityKey(String)

sameEntity

public final boolean sameEntity(EntityKeyInterface entity)

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

Specified by:

sameEntity in interface 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(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.

toString

public String toString()

Gets a string representation of this service proxy.

Overrides:

toString in class Object

Returns:

String representation of this service proxy.

findRemoteService

protected RemoteServiceInterface findRemoteService()
                                            throws ServiceException,
                                                   RemoteException

Attempts to rediscover 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 rediscover the service.

RemoteException - if unable to discover a networked service.