org.jboss.msc.service

Interface Service<T>

Type Parameters:

T - the type of value that this service provides; may be Void

All Superinterfaces:

Value<T>

All Known Subinterfaces:

SingletonService<T>

All Known Implementing Classes:

AbstractService, ValueInjectionService, ValueService

public interface Service<T>
extends Value<T>

A service is a thing which can be started and stopped. A service may be started or stopped from any thread. In general, injections will always happen from the same thread that will call start(), and uninjections will always happen from the same thread that had called stop(). However no other guarantees are made with respect to locking or thread safety; a robust service implementation should always take care to protect any mutable state appropriately.

The value type specified by this service is used by default by consumers of this service, and should represent the public interface of this service, which may or may not be the same as the implementing type of this service.

When writing MSC service implementations, your start(StartContext) and stop(StopContext) methods must never block. This means these methods must not:

• Use network connections
• Wait for network connections
• Sleep
• Wait on a condition
• Wait on a count down latch
• Call any method which may do any of the above
• Wait for termination of a thread pool or other service
• Wait for another service to change state

If your service start/stop does any of these things, you must use the asynchronous start/stop mechanism (LifecycleContext.asynchronous()) and do one of the following:

• Initiate your task in start()/stop(), and utilize a callback (NIO, ThreadPoolExecutor.terminated(), etc.) to call LifecycleContext.complete() when your start/stop completes instead of blocking
• Delegate your blocking task to a thread pool (Executor) which calls LifecycleContext.complete() when done
• Use proper dependencies instead of explicitly waiting for services in your start/stop

Note that using LifecycleContext.execute(Runnable) to execute the blocking task is also not permissible.

Author:

David M. Lloyd

Field Summary

Fields

Modifier and Type	Field and Description
static Service<Void>	NULL A simple null service which performs no start or stop action.
static Value<Service<Void>>	NULL_VALUE A value which resolves to the null service.

Method Summary

Modifier and Type	Method and Description
void	start(StartContext context) Start the service.
void	stop(StopContext context) Stop the service.

Methods inherited from interface org.jboss.msc.value.Value

getValue

Field Detail

NULL

static final Service<Void> NULL

A simple null service which performs no start or stop action.

NULL_VALUE

static final Value<Service<Void>> NULL_VALUE

A value which resolves to the null service.

Method Detail

start

void start(StartContext context)
    throws StartException

Start the service. Do not return until the service has been fully started, unless an asynchronous service start is performed. All injections will be complete before this method is called.

If the service start involves any activities that may block, the asynchronous mechanism provided by the context should be used. See the class javadoc for details.

Parameters:

context - the context which can be used to trigger an asynchronous service start

Throws:

StartException - if the service could not be started for some reason

stop

void stop(StopContext context)

Stop the service. Do not return until the service has been fully stopped, unless an asynchronous service stop is performed. All injections will remain intact until the service is fully stopped. This method should not throw an exception.

If the service start involves any activities that may block, the asynchronous mechanism provided by the context should be used. See the class javadoc for details.

Parameters:

context - the context which can be used to trigger an asynchronous service stop