com.sas.services
Interface RemoteServiceInterface

All Superinterfaces:

com.sas.entities.EntityKeyInterface, java.rmi.Remote, ServiceNotificationBroadcasterInterface

All Known Subinterfaces:

AuthenticationServiceInterface, DiscoveryServiceInterface, EventBrokerDiscoveryServiceInterface, EventBrokerServiceInterface, InformationServiceInterface, LocalDiscoveryServiceInterface, LoggingServiceInterface, 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 disocvery 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 necesssary 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 is remoteable 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

static java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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

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(java.lang.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 or not 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.services.mgmt.ServiceNotificationBroadcasterInterface

addServiceObserver, notifyServiceObservers, removeAllServiceObservers, removeServiceObserver

Field Detail

CLASS_IDENTIFIER_SERVICE_TYPE_1_1

static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 Detail

getServiceConfiguration

ServiceConfigurationInterface getServiceConfiguration()
                                                      throws java.rmi.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:

java.rmi.RemoteException - if a network anomaly occurs.

getServiceConfiguration

ServiceConfigurationInterface getServiceConfiguration(java.lang.Object key)
                                                      throws java.rmi.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:

java.rmi.RemoteException - if a network anomaly occurs.

configure

void configure(ServiceConfigurationInterface serviceConfiguration)
               throws InitializationException,
                      java.rmi.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.

java.rmi.RemoteException - if a network anomaly is encountered.

ServiceException - if a previously initialized service does not support reconfiguration.

reconfigure

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

java.rmi.RemoteException - if a network anomaly is encountered.

destroy

void destroy()
             throws ServiceException,
                    java.rmi.RemoteException

Destroys the service. This method should only be invoked after a service has been configured. It is suggested that the service invoke the destory 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:

java.rmi.RemoteException - if a network anomaly is encountered.

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

getServiceState

short getServiceState()
                      throws java.rmi.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:

java.rmi.RemoteException - if a network anomaly is encountered.

setServiceState

void setServiceState(ServiceState serviceState)
                     throws ServiceException,
                            java.rmi.RemoteException

Sets the state of the service.

Parameters:

serviceState - Service's state.

Throws:

ServiceException - if an invalid service state is specified.

java.rmi.RemoteException - if a network anomaly is encountered.

getCreationTime

long getCreationTime()
                     throws java.rmi.RemoteException

Gets the time at which this service was created.

Returns:

The time the service was created.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

isExported

boolean isExported()
                   throws ServiceException,
                          java.rmi.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.

java.rmi.RemoteException - if a network anomaly occurs.

isAccessibleToRemoteClients

boolean isAccessibleToRemoteClients()
                                    throws ServiceException,
                                           java.rmi.RemoteException

Determines whether or not 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.

java.rmi.RemoteException - if a network anomaly occurs.

getServiceProxy

RemoteServiceInterface getServiceProxy()
                                       throws java.rmi.RemoteException

Gets the service proxy.

Returns:

A proxy to this service or null if a proxy is not available.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.