org.apache.hadoop.service

Interface Service

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AbstractService, CompositeService, NodeHealthScriptRunner

@InterfaceAudience.Public
@InterfaceStability.Evolving
public interface Service
extends Closeable

Service LifeCycle.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Service.STATE Service states

Method Summary

Methods

Modifier and Type	Method and Description
void	close() A version of stop() that is designed to be usable in Java7 closure clauses.
Map<String,String>	getBlockers() Get the blockers on a service -remote dependencies that are stopping the service from being live.
Configuration	getConfig() Get the configuration of this service.
Throwable	getFailureCause() Get the first exception raised during the service failure.
Service.STATE	getFailureState() Get the state in which the failure in getFailureCause() occurred.
List<LifecycleEvent>	getLifecycleHistory() Get a snapshot of the lifecycle history; it is a static list
String	getName() Get the name of this service.
Service.STATE	getServiceState() Get the current service state
long	getStartTime() Get the service start time
void	init(Configuration config) Initialize the service.
boolean	isInState(Service.STATE state) Query to see if the service is in a specific state.
void	registerServiceListener(ServiceStateChangeListener listener) Register a listener to the service state change events.
void	start() Start the service.
void	stop() Stop the service.
void	unregisterServiceListener(ServiceStateChangeListener listener) Unregister a previously registered listener of the service state change events.
boolean	waitForServiceToStop(long timeout) Block waiting for the service to stop; uses the termination notification object to do so.

Method Detail

init

void init(Configuration config)

Initialize the service. The transition MUST be from Service.STATE.NOTINITED to Service.STATE.INITED unless the operation failed and an exception was raised, in which case stop() MUST be invoked and the service enter the state Service.STATE.STOPPED.

Parameters:

config - the configuration of the service

Throws:

RuntimeException - on any failure during the operation

start

void start()

Start the service. The transition MUST be from Service.STATE.INITED to Service.STATE.STARTED unless the operation failed and an exception was raised, in which case stop() MUST be invoked and the service enter the state Service.STATE.STOPPED.

Throws:

RuntimeException - on any failure during the operation

stop

void stop()

Stop the service. This MUST be a no-op if the service is already in the Service.STATE.STOPPED state. It SHOULD be a best-effort attempt to stop all parts of the service. The implementation must be designed to complete regardless of the service state, including the initialized/uninitialized state of all its internal fields.

Throws:

RuntimeException - on any failure during the stop operation

close

void close()
           throws IOException

A version of stop() that is designed to be usable in Java7 closure clauses. Implementation classes MUST relay this directly to stop()

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - never

RuntimeException - on any failure during the stop operation

registerServiceListener

void registerServiceListener(ServiceStateChangeListener listener)

Register a listener to the service state change events. If the supplied listener is already listening to this service, this method is a no-op.

Parameters:

listener - a new listener

unregisterServiceListener

void unregisterServiceListener(ServiceStateChangeListener listener)

Unregister a previously registered listener of the service state change events. No-op if the listener is already unregistered.

Parameters:

listener - the listener to unregister.

getName

String getName()

Get the name of this service.

Returns:

the service name

getConfig

Configuration getConfig()

Get the configuration of this service. This is normally not a clone and may be manipulated, though there are no guarantees as to what the consequences of such actions may be

Returns:

the current configuration, unless a specific implentation chooses otherwise.

getServiceState

Service.STATE getServiceState()

Get the current service state

Returns:

the state of the service

getStartTime

long getStartTime()

Get the service start time

Returns:

the start time of the service. This will be zero if the service has not yet been started.

isInState

boolean isInState(Service.STATE state)

Query to see if the service is in a specific state. In a multi-threaded system, the state may not hold for very long.

Parameters:

state - the expected state

Returns:

true if, at the time of invocation, the service was in that state.

getFailureCause

Throwable getFailureCause()

Get the first exception raised during the service failure. If null, no exception was logged

Returns:

the failure logged during a transition to the stopped state

getFailureState

Service.STATE getFailureState()

Get the state in which the failure in getFailureCause() occurred.

Returns:

the state or null if there was no failure

waitForServiceToStop

boolean waitForServiceToStop(long timeout)

Block waiting for the service to stop; uses the termination notification object to do so. This method will only return after all the service stop actions have been executed (to success or failure), or the timeout elapsed This method can be called before the service is inited or started; this is to eliminate any race condition with the service stopping before this event occurs.

Parameters:

timeout - timeout in milliseconds. A value of zero means "forever"

Returns:

true iff the service stopped in the time period

getLifecycleHistory

List<LifecycleEvent> getLifecycleHistory()

Get a snapshot of the lifecycle history; it is a static list

Returns:

a possibly empty but never null list of lifecycle events.

getBlockers

Map<String,String> getBlockers()

Get the blockers on a service -remote dependencies that are stopping the service from being live.

Returns:

a (snapshotted) map of blocker name->description values