Package com.sas.services

Class ServiceProxy

java.lang.Object
com.sas.services.ServiceProxy
All Implemented Interfaces:
com.sas.entities.EntityKeyInterface, ServiceNotificationBroadcasterInterface, RemoteServiceInterface, Serializable, Remote
Direct Known Subclasses:
RemoteDiscoveryServiceProxy, SessionServiceProxy, StoredProcessServiceProxy
public class ServiceProxy extends Object implements RemoteServiceInterface, 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.

Since:
1.1
See Also:

  • Constructor Details

    • 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 Details

    • 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 service proxy 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 service proxy 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 service proxy.

      Returns:
      The proxy to the foundation service.
      Throws:
      IllegalStateException - if the service has been destroyed.

    • configure

      public final void configure(ServiceConfigurationInterface serviceConfiguration) throws ServiceException, 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:
      ServiceException - if a previously initialized service does not support reconfiguration.
      RemoteException - if a network anomaly is encountered.

    • reconfigure

      public final void reconfigure(ServiceConfigurationInterface serviceConfiguration) throws ServiceException, RemoteException, 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.
      RemoteException - if a network anomaly is encountered.
      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 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
      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 cannot be updated 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)
      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 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

    • getEntityKey

      public final 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(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(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 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, 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.
      RemoteException - if unable to discover a networked service.