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:

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

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

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

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

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

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

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