Package com.sas.services

# Interface RemoteServiceInterface

All Superinterfaces:
  `com.sas.entities.EntityKeyInterface`, `Remote`, `ServiceNotificationBroadcasterInterface`

All Known Subinterfaces:
  `AuthenticationServiceInterface`, `DiscoveryServiceInterface`, `EventBrokerDiscoveryServiceInterface`, `EventBrokerServiceInterface`, `InformationServiceInterface`, `LocalDiscoveryServiceInterface`, `RemoteDiscoveryServiceInterface`, `ServiceInterface`, `SessionServiceInterface`, `StoredProcessServiceInterface`, `UserServiceInterface`

All Known Implementing Classes:
  `AbstractDiscoveryService`, `AbstractRemoteService`, `AbstractService`, `ActivatableDiscoveryService`, `AuthenticationService`, `DiscoveryService`, `EventBrokerDiscoveryService`, `EventBrokerService`, `InformationService`, `RemoteDiscoveryServiceProxy`, `ServiceProxy`, `SessionService`, `SessionServiceProxy`, `StoredProcessServiceProxy`, `UserService`

public interface RemoteServiceInterface extends com.sas.entities.EntityKeyInterface, ServiceNotificationBroadcasterInterface
Interface used to designate a service that is capable of servicing clients that operate outside of the JVM process in which a service was instantiated. It is also the base interface implemented by all services.

It is envisioned that the typical service will have a service configuration which may be associated with other ancillary service configurations to detail a deployment context or discovery context. The service implementor is free to define any additional service configurations. Note that a service is not required to have a service configuration.

Services will be initialized or reconfigured using the `RemoteServiceInterface.configure(ServiceConfigurationInterface)` method.

The `RemoteServiceInterface.destroy()` method is intended to be used to notify a service that it is being destroyed so that it may perform any housekeeping necessary to release resources, etc. Once the destroy method has been invoked, the service should no longer be used.

A service should directly implement this interface if it can be accessed from a remote JVM and is intended to be deployed in a distributed environment.

This interface is extended by `com.sas.services.ServiceInterface`. `ServiceInterface` provides a version that may be used locally within a JVM process. Unlike `RemoteServiceInterface` its methods do not throw `RemoteException`.

Since:
  1.0
See Also:
  - `ServiceInterface`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CLASS_IDENTIFIER`
  The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a foundation service developed using the current API.
  `static final String`
  `CLASS_IDENTIFIER_1_1`
  The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a Java foundation service using the 1.1 API.
  `static final String`
  `CLASS_IDENTIFIER_1_2`
  The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a foundation service developed using the 1.2 API.
  `static final String`
  `CLASS_IDENTIFIER_SERVICE_TYPE`
  The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a foundation service developed using the current API.
  `static final String`
  `CLASS_IDENTIFIER_SERVICE_TYPE_1_1`
  ClassIdentifier used to lookup a prototype `ServiceType` for an interface implemented by a foundation service developed against the 1.1 API.
  `static final String`
  `CLASS_IDENTIFIER_SERVICE_TYPE_1_2`
  The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a foundation service developed using the 1.2 API.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `configure(ServiceConfigurationInterface serviceConfiguration)`
  Configures the service.
  `void`
  `destroy()`
  Destroys the service.
  `long`
  `getCreationTime()`
  Gets the time at which this service was created.
  `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 current state of the service.
  `boolean`
  `isAccessibleToRemoteClients()`
  Determines whether the service is accessible to remote clients.
  `boolean`
  `isExported()`
  Determines whether or not the service has been exported to the RMI system.
  `void`
  `reconfigure(ServiceConfigurationInterface serviceConfiguration)`
  Reconfigure the service.
  `void`
  `setServiceState(ServiceState serviceState)`
  Sets the state of the service.

  ### Methods inherited from interface com.sas.entities.EntityKeyInterface

  `getEntityKey, sameEntity, setEntityKey`

  ### Methods inherited from interface com.sas.services.mgmt.ServiceNotificationBroadcasterInterface

  `addServiceObserver, notifyServiceObservers, removeAllServiceObservers, removeServiceObserver`

- ## Field Details

  - ### CLASS_IDENTIFIER_SERVICE_TYPE_1_1

    static final String CLASS_IDENTIFIER_SERVICE_TYPE_1_1
    ClassIdentifier used to lookup a prototype `ServiceType` for an interface implemented by a foundation service developed against the 1.1 API.
    See Also:
      - Constant Field Values

  - ### CLASS_IDENTIFIER_SERVICE_TYPE_1_2

    static final String CLASS_IDENTIFIER_SERVICE_TYPE_1_2
    The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a foundation service developed using the 1.2 API.
    See Also:
      - Constant Field Values

  - ### CLASS_IDENTIFIER_SERVICE_TYPE

    static final String CLASS_IDENTIFIER_SERVICE_TYPE
    The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a foundation service developed using the current API.
    See Also:
      - Constant Field Values

  - ### CLASS_IDENTIFIER_1_1

    static final String CLASS_IDENTIFIER_1_1
    The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a Java foundation service using the 1.1 API.
    See Also:
      - Constant Field Values

  - ### CLASS_IDENTIFIER_1_2

    static final String CLASS_IDENTIFIER_1_2
    The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a foundation service developed using the 1.2 API.
    See Also:
      - Constant Field Values

  - ### CLASS_IDENTIFIER

    static final String CLASS_IDENTIFIER
    The metadata element `ClassIdentifier` designating a `ServiceComponent` metadata element as one that is a foundation service developed using the current API.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getServiceConfiguration

    ServiceConfigurationInterface getServiceConfiguration() throws RemoteException
    Gets the service's configuration. If no service configuration is defined then this method will return `null`.
    Returns:
      Service's configuration or `null` if no service configuration is defined.

      Note that a service configuration may be associated with other ancillary service configurations. `ServiceConfigurationInterface.getServiceConfigurations()` may be used to obtain an iterator of associated service configurations. `ServiceConfigurationInterface.getServiceConfiguration(Object)` may be used to obtain a service configuration based upon a known lookup key.

    Throws:
      `RemoteException` - if a network anomaly occurs.

  - ### getServiceConfiguration

    ServiceConfigurationInterface getServiceConfiguration(Object key) throws RemoteException
    Gets the service's configuration associated with the specified lookup key. If no service configuration is defined then this method will return `null`.
    Parameters:
      `key` - Lookup key for the desired service configuration.
    Returns:
      Service's configuration or `null` if no service configuration is defined.
    Throws:
      `RemoteException` - if a network anomaly occurs.

  - ### configure

    void configure(ServiceConfigurationInterface serviceConfiguration) throws InitializationException, RemoteException, ServiceException
    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`.

    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.
      `RemoteException` - if a network anomaly is encountered.
      `ServiceException` - if a previously initialized service does not support reconfiguration.

  - ### reconfigure

    void reconfigure(ServiceConfigurationInterface serviceConfiguration) throws ServiceException, RemoteException
    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.

    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.

  - ### destroy

    void destroy() throws ServiceException, RemoteException
    Destroys the service. This method should only be invoked after a service has been configured. It is suggested that the service invoke the destroy method if a configuration request fails and the service is not in a stable state.

    The service should release any resources it holds in preparation for termination of use of this service.

    Throws:
      `RemoteException` - if a network anomaly is encountered.
      `ServiceException` - if the service is unable to prepare itself for destruction.

  - ### getServiceState

    short getServiceState() throws RemoteException
    Gets the current state of the service. The state will be one of
    - ServiceState.SERVICE_STATE_UNINITIALIZED
    - ServiceState.SERVICE_STATE_INITIALIZED
    - ServiceState.SERVICE_STATE_DEACTIVATED
    Returns:
      Service's state.
    Throws:
      `RemoteException` - if a network anomaly is encountered.

  - ### setServiceState

    void setServiceState(ServiceState serviceState) throws ServiceException, RemoteException
    Sets the state of the service.
    Parameters:
      `serviceState` - Service's state.
    Throws:
      `ServiceException` - if an invalid service state is specified.
      `RemoteException` - if a network anomaly is encountered.

  - ### getCreationTime

    long getCreationTime() throws RemoteException
    Gets the time at which this service was created.
    Returns:
      The time the service was created.
    Throws:
      `RemoteException` - if a network anomaly is encountered.

  - ### isExported

    boolean isExported() throws ServiceException, RemoteException
    Determines whether or not the service has been exported to the RMI system.
    Returns:
      `true` if the service has been exported or `false` if it hasn't.
    Throws:
      `ServiceException` - if unable to process the request.
      `RemoteException` - if a network anomaly occurs.

  - ### isAccessibleToRemoteClients

    boolean isAccessibleToRemoteClients() throws ServiceException, RemoteException
    Determines whether the service is accessible to remote clients.
    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.
      `RemoteException` - if a network anomaly occurs.

  - ### getServiceProxy

    RemoteServiceInterface getServiceProxy() throws RemoteException
    Gets the service proxy.
    Returns:
      A proxy to this service or `null` if a proxy is not available.
    Throws:
      `RemoteException` - if a network anomaly is encountered.