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.

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

  Constructors
  Constructor
  Description
  `ServiceProxy(RemoteServiceInterface service)`
  Constructs a foundation service proxy for the specified service.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `addServiceObserver(ServiceRemoteObserverInterface serviceObserver)`
  Adds a service observer.
  `final void`
  `configure(ServiceConfigurationInterface serviceConfiguration)`
  Configures the service.
  `final void`
  `destroy()`
  Destroys the service proxy.
  `protected RemoteServiceInterface`
  `findRemoteService()`
  Attempts to re-discover an instance of a remote service represented by this proxy.
  `final long`
  `getCreationTime()`
  Gets the time at which this service was created.
  `final String`
  `getEntityKey()`
  Gets the service proxy's entity key.
  `protected final RemoteServiceInterface`
  `getService()`
  Gets the service.
  `final ServiceConfigurationInterface`
  `getServiceConfiguration()`
  Gets the service's configuration.
  `final ServiceConfigurationInterface`
  `getServiceConfiguration(Object key)`
  Gets the service's configuration associated with the specified lookup key.
  `RemoteServiceInterface`
  `getServiceProxy()`
  Gets the service proxy.
  `final 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.
  `final boolean`
  `isLocalService()`
  Determines whether or not this proxy has a local handle to the service.
  `final boolean`
  `isProxyToRemoteService()`
  Determines whether this is a proxy to a remote service
  `final void`
  `notifyServiceObservers(ServiceEvent serviceEvent)`
  Notify all registered service observers of the specified service event.
  `final void`
  `reconfigure(ServiceConfigurationInterface serviceConfiguration)`
  Reconfigure the service.
  `final void`
  `removeAllServiceObservers()`
  Removes all service observers.
  `final void`
  `removeServiceObserver(ServiceRemoteObserverInterface serviceObserver)`
  Removes a service observer.
  `final boolean`
  `sameEnitityKey(String entityKey)`
  Determines if the this service's entity key is the same.
  `final boolean`
  `sameEntity(com.sas.entities.EntityKeyInterface entity)`
  Determines whether or not the specified entity is the same as this entity.
  `final void`
  `setEntityKey(String entityKey)`
  `final void`
  `setServiceState(ServiceState serviceState)`
  Sets the state of the service.

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

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

- ## 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.