de.aristaflow.adept2.base.service

Interface ADEPT2Service

All Known Subinterfaces:

ActivityEventManager, ActivityManagerService, ActivityRepository, ActivityStateListener, ADEPT2ClientService, AdministrationService, ClientService, ClusterService, CommunicationService<I1,O1,I2,O2>, ConfigurableService, ConfMgrRegistry, DataManager, EventManager, ExecutionClientService, ExecutionManager, ExecutionMessageListener, FileroDataSource, GlobalProvider, GlobalRegistry, GlobalRegistryProvider, GlobalTransactionManager, GUIManager, HTTPService, InitTabManager, InstanceStartEventManager, InstanceStateListener, JDBCDataSource, LicenceManager, LocalExecutionClientService, LogManager, MailService, MailService, ModellingClientService, OrgModelManager, OrgPolicyScriptService, ProcessCheckService, ProcessImageRenderer, ProcessManager, ProcessRepository, RemoteExecutionClientService, RemoteGUIManager, RuntimeManager, RuntimeService, ServletService, SubInstanceStateListener, SubprocessManager, UpdateManager, WorklistClientService, WorklistManager

All Known Implementing Classes:

AbstractADEPT2Service, AbstractAuthenticatedService, AbstractConfigurableAuthenticatedService, AbstractConfigurableService, AbstractEventManager, AbstractGUIManager, AbstractNonPrivilegedService, AbstractRegistry, AristaFlowHTTPService, AuthenticatedInjectedService, BootstrapRegistry, ClusterNode, DefaultEventManager, DefaultProcessCheckService, EmbdServContHTTPService, EmbeddedServletService, InitialisedInjectedService, InjectedADEPT2Service, InstanceToInstanceRegistry, LocalServiceRegistry, ModelFactoryRegistry, MultiplexingClientService, NullGUIManager, NullHTTPService, PluginRegistry, PVPUpdateManager, RegistryProviderConf, RegistryProviderDb, RemoteHTMLGUIManager, ServiceRegistry, TwoPhaseBootstrap

public interface ADEPT2Service

Description of an (ADEPT2) service which can be initialised and started by the registry.

Beside methods for starting and shutting down, this interface also allows for defining which other services will be required. This can be achieved by implementing getStartupRequiredServices() and getRuntimeRequiredServices() (see the comments of these methods for further information).

The differentiation allows for a clean start of a service and all of its dependencies. This also allows for cyclic dependencies between services, as long as the cycle does not exist within "startup-required" services ( getStartupRequiredServices()).

A service has the following life cycle:

1. instantiated (by constructor)
2. initialised (by init(URI[], URI[]))
3. started (by start())
4. pre shut down (by preShutdown(boolean))
5. shut down (by shutdown(boolean))

Any of these methods is executed exactly once by the registry. These methods may access the registry but only with the thread that executes this methods.

A service may expect that it is only called, when it is in state 'started'.
Starting a service will be accomplished as follows:

1. instantiate the service (object)
2. get the lists of startup-required services
3. instantiate, (recursively) initialise and start these services
4. call init(URI[], URI[])
5. call start()

A service needs to provide a constructor accepting a Configuration as well as a Registry. The first parameter provides the configuration for the service, the second one allows the service to retrieve other services from the registry.
The provided configuration will already be checked against the ConfigurationDescription of a service - if present. Such a configuration description allows the service to declare its needs for its configuration. Complex configurations may be checked via a ConfigurationValidator . If the configuration does not match the configuration description, the service will not be instantiated at all.

The constructor may throw a ConfigurationException in case the designated configuration is invalid, for instance, it does not provide a mandatory configuration value. This is treated like an AbortServiceException when calling init(URI[], URI[]) or start(). The service needs to implement the appropriate cleanup - if necessary in the early stage of constructing - since shutdown(boolean) will not be called.
To allow for a stable system, services should always check their configuration in the constructor or not later then start(). At runtime, an erroneous configuration may be a serious problem for a service. However, the service can not be shut down easily at this time.

Example for dependencies: A process manager implementation requires a DataManager (for execution), a LogManager and a JDBCDataSource. Since the LogManager and the JDBCDataSource are already used during the initialisation, the process manager implementation will return {"LogManager", "JDBCDataSource"} in getStartupRequiredServices() and {"DataManager"} in getRuntimeRequiredServices(). Instead of plain strings, the constants from ComponentTypes (for instance ComponentTypes.COMPONENT_TYPE_DATA_MANAGER should be used.

Method Summary

Modifier and Type	Method and Description
java.net.URI[]	getLocalUris() Returns the URIs under which the service is locally exported.
SerialisablePair<java.lang.String,java.lang.String>	getRelease() Gets the release of this service, that is, the build version and the build date.
java.lang.String[]	getRuntimeRequiredServices() Returns a list of service types, which are requested when needed at runtime.
SerialisableTriple<java.lang.String,java.lang.String,java.lang.String>	getServiceInstanceName() Gets the (optional) cluster name, the unique node name and the hierarchical instance name of this service.
java.lang.String[]	getStartupRequiredServices() Returns a list of service types, which are required for executing the service.
java.net.URI[]	getURIs() Returns the URIs which are set for this service in init(URI[], URI[]).
void	init(java.net.URI[] localExportedUris, java.net.URI[] globalExportedUris) Initialise the service.
long	ping() Gets whether the service is running and accepts requests or not and since when.
void	preShutdown(boolean emergency) Signals this service that it is about to be shut down.
void	shutdown(boolean emergency) Signals this service that it is being shut down.
void	start() Starts the service.

Method Detail

ping

long ping()

Gets whether the service is running and accepts requests or not and since when. This allows, for instance, to check remotely whether this service is available. Additionally, restarts of the service can be detected by comparing the returned start time with the previous one.

Returns:

The start time of the service, 0 for a service that has not been started, -1 for a service that has been shut down.
If you need the old boolean logic use 0 < ping().

getRelease

SerialisablePair<java.lang.String,java.lang.String> getRelease()

Gets the release of this service, that is, the build version and the build date.

Returns:

The build version and the build date of this service.

getServiceInstanceName

SerialisableTriple<java.lang.String,java.lang.String,java.lang.String> getServiceInstanceName()

Gets the (optional) cluster name, the unique node name and the hierarchical instance name of this service.

Returns:

The (optional) cluster name, the unique node name and the hierarchical instance name of this service.

getStartupRequiredServices

java.lang.String[] getStartupRequiredServices()

Returns a list of service types, which are required for executing the service. The service is allowed for querying the Registry for implementations of this type during init(URI[], URI[]) or to start() the service.
It is assured that init(URI[], URI[]) is not called before the required services are started. The order in the array is not relevant since the dependencies of the required services are also inspected and respected.
These services may also be accessed when shutting down the service.

Returns:

A list of service types which are required by this service.

getRuntimeRequiredServices

java.lang.String[] getRuntimeRequiredServices()

Returns a list of service types, which are requested when needed at runtime. This has to be after the component is initialised and started and before the shutdown. This means before requesting a runtime required service init(URI[], URI[]) as well as start() have to be returned. When starting another thread, this has to be synchronised correctly.
Since these services are not necessarily started before this service, they may be shutdown before shutting down this service. This has to be considered when calling a runtime required service. If a service is absolutely necessary when shutting down, it will have to be declared as startup-required.

All services required at startup should not be returned again here.

Returns:

A list of services which are required during runtime and requested lazily.

getLocalUris

java.net.URI[] getLocalUris()

Returns the URIs under which the service is locally exported. If this service is only locally available, there will be only one URI and this is a local one. The request for the corresponding component will fail if it is not a local service.
Internal services may return an empty array.

Returns:

The URIs with which this service is exported locally - this may also be one local URI or an empty array for internal services, that should not be reached at all, for instance communication services.

getURIs

java.net.URI[] getURIs()

Returns the URIs which are set for this service in init(URI[], URI[]). For a published service these are the global URIs, otherwise the method will return the local URIs.

Returns:

The URIs with which this service is globally published or the local URIs.

init

void init(java.net.URI[] localExportedUris,
          java.net.URI[] globalExportedUris)
   throws AbortServiceException

Initialise the service. Startup-required services may already be used here.
After returning form init(URI[], URI[]), the service must be ready for start().

Parameters:

localExportedUris - The URIs with which this service is exported locally or a local URI or an empty array for internal services.

globalExportedUris - The URIs with which this service is published globally or null in case the service is not published.

Throws:

AbortServiceException - If this service cannot be initialised due to a severe problem, an AbortServiceException will be thrown. shutdown(boolean) will not be called when aborting; the service has to shut down itself/clean up before throwing the exception.

start

void start()
    throws AbortServiceException

Starts the service. This method is executed exactly once by the registry and it must return to start further services. For a stand-alone-service own threads or processes have to be started here.
This method is executed exactly once by the registry.

After returning from start(), the service must be ready to receive any API call. This implicates for instance, that the thread calling this method may not leave the method before a server thread is actually ready to receive requests.

Throws:

AbortServiceException - If this service cannot be started due to a severe problem, an AbortServiceException will be thrown. shutdown(boolean) will not be called when aborting; the service has to shut down itself/clean up before throwing the exception.

preShutdown

void preShutdown(boolean emergency)

Signals this service that it is about to be shut down. While this method is called, the service is normally available, that is, it can be reached remotely and it should not refuse connections without reason.
This method can be used to perform some cleanup or to start cleaning up and continuing until shutdown(boolean). All startup required services are available in pre shutdown, runtime services may already be shut down.
In case of an emergency shutdown, even startup required services may not be available. Additionally, shutting down should be rather fast, so cleanup should concentrate on the really important things. An emergency pre-shutdown usually should not do anything.

Parameters:

emergency - Whether the shutdown will be an emergency shutdown. Normally a service should not do anything in pre-shutdown in case of an emergency.

shutdown

void shutdown(boolean emergency)

Signals this service that it is being shut down. While this method is called, the service is no longer (remotely) available. It should terminate and close all activities and connections. Since the service is in an inconsistent state while shutting down, access should be restricted to the threads relevant for shutting down. All other requests should be blocked (see ServiceThreadHandling.
All startup required services are available in shutdown, runtime services may already be shut down.
In case of an emergency shutdown, even startup required services may not be available. Additionally, shutting down should be rather fast, so cleanup should concentrate on the really important things and use brief timeouts when waiting.

Parameters:

emergency - Whether the shutdown will be an emergency shutdown.