org.apache.hadoop.service

Class AbstractService

java.lang.Object

org.apache.hadoop.service.AbstractService

All Implemented Interfaces:

Closeable, AutoCloseable, Service

Direct Known Subclasses:

CompositeService

@InterfaceAudience.Public
@InterfaceStability.Evolving
public abstract class AbstractService
extends Object
implements Service

This is the base implementation class for services.

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.hadoop.service.Service

Service.STATE

Constructor Summary

Constructors

Constructor and Description
AbstractService(String name) Construct the service.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Relay to stop()
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 Service.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 conf) Initialize the service.
boolean	isInState(Service.STATE expected) Query to see if the service is in a specific state.
protected void	noteFailure(Exception exception) Failure handling: record the exception that triggered it -if there was not one already.
protected void	putBlocker(String name, String details) Put a blocker to the blocker map -replacing any with the same name.
static void	registerGlobalListener(ServiceStateChangeListener l) Register a global listener, which receives notifications from the state change events of all services in the JVM
void	registerServiceListener(ServiceStateChangeListener l) Register a listener to the service state change events.
void	removeBlocker(String name) Remove a blocker from the blocker map - this is a no-op if the blocker is not present
protected void	serviceInit(Configuration conf) All initialization code needed by a service.
protected void	serviceStart() Actions called during the INITED to STARTED transition.
protected void	serviceStop() Actions called during the transition to the STOPPED state.
protected void	setConfig(Configuration conf) Set the configuration for this service.
void	start() Start the service.
void	stop() Stop the service.
String	toString()
static boolean	unregisterGlobalListener(ServiceStateChangeListener l) unregister a global listener.
void	unregisterServiceListener(ServiceStateChangeListener l) 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractService

public AbstractService(String name)

Construct the service.

Parameters:

name - service name

Method Detail

getServiceState

public final Service.STATE getServiceState()

Description copied from interface: Service

Get the current service state

Specified by:

getServiceState in interface Service

Returns:

the state of the service

getFailureCause

public final Throwable getFailureCause()

Description copied from interface: Service

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

Specified by:

getFailureCause in interface Service

Returns:

the failure logged during a transition to the stopped state

getFailureState

public Service.STATE getFailureState()

Description copied from interface: Service

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

Specified by:

getFailureState in interface Service

Returns:

the state or null if there was no failure

setConfig

protected void setConfig(Configuration conf)

Set the configuration for this service. This method is called during init(Configuration) and should only be needed if for some reason a service implementation needs to override that initial setting -for example replacing it with a new subclass of Configuration

Parameters:

conf - new configuration.

init

public void init(Configuration conf)

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 Service.stop() MUST be invoked and the service enter the state Service.STATE.STOPPED. This invokes serviceInit(org.apache.hadoop.conf.Configuration)

Specified by:

init in interface Service

Parameters:

conf - the configuration of the service. This must not be null

Throws:

ServiceStateException - if the configuration was null, the state change not permitted, or something else went wrong

start

public 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 Service.stop() MUST be invoked and the service enter the state Service.STATE.STOPPED.

Specified by:

start in interface Service

Throws:

ServiceStateException - if the current service state does not permit this action

stop

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

Specified by:

stop in interface Service

close

public final void close()
                 throws IOException

Relay to stop()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Service

Throws:

IOException

noteFailure

protected final void noteFailure(Exception exception)

Failure handling: record the exception that triggered it -if there was not one already. Services are free to call this themselves.

Parameters:

exception - the exception

waitForServiceToStop

public final boolean waitForServiceToStop(long timeout)

Description copied from interface: Service

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.

Specified by:

waitForServiceToStop in interface Service

Parameters:

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

Returns:

true iff the service stopped in the time period

serviceInit

protected void serviceInit(Configuration conf)
                    throws Exception

All initialization code needed by a service. This method will only ever be called once during the lifecycle of a specific service instance. Implementations do not need to be synchronized as the logic in init(Configuration) prevents re-entrancy. The base implementation checks to see if the subclass has created a new configuration instance, and if so, updates the base class value

Parameters:

conf - configuration

Throws:

Exception - on a failure -these will be caught, possibly wrapped, and wil; trigger a service stop

serviceStart

protected void serviceStart()
                     throws Exception

Actions called during the INITED to STARTED transition. This method will only ever be called once during the lifecycle of a specific service instance. Implementations do not need to be synchronized as the logic in start() prevents re-entrancy.

Throws:

Exception - if needed -these will be caught, wrapped, and trigger a service stop

serviceStop

protected void serviceStop()
                    throws Exception

Actions called during the transition to the STOPPED state. This method will only ever be called once during the lifecycle of a specific service instance. Implementations do not need to be synchronized as the logic in stop() prevents re-entrancy. Implementations MUST write this to be robust against failures, including checks for null references -and for the first failure to not stop other attempts to shut down parts of the service.

Throws:

Exception - if needed -these will be caught and logged.

registerServiceListener

public void registerServiceListener(ServiceStateChangeListener l)

Description copied from interface: Service

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.

Specified by:

registerServiceListener in interface Service

Parameters:

l - a new listener

unregisterServiceListener

public void unregisterServiceListener(ServiceStateChangeListener l)

Description copied from interface: Service

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

Specified by:

unregisterServiceListener in interface Service

Parameters:

l - the listener to unregister.

registerGlobalListener

public static void registerGlobalListener(ServiceStateChangeListener l)

Register a global listener, which receives notifications from the state change events of all services in the JVM

Parameters:

l - listener

unregisterGlobalListener

public static boolean unregisterGlobalListener(ServiceStateChangeListener l)

unregister a global listener.

Parameters:

l - listener to unregister

Returns:

true if the listener was found (and then deleted)

getName

public String getName()

Description copied from interface: Service

Get the name of this service.

Specified by:

getName in interface Service

Returns:

the service name

getConfig

public Configuration getConfig()

Description copied from interface: Service

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

Specified by:

getConfig in interface Service

Returns:

the current configuration, unless a specific implentation chooses otherwise.

getStartTime

public long getStartTime()

Description copied from interface: Service

Get the service start time

Specified by:

getStartTime in interface Service

Returns:

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

getLifecycleHistory

public List<LifecycleEvent> getLifecycleHistory()

Description copied from interface: Service

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

Specified by:

getLifecycleHistory in interface Service

Returns:

a possibly empty but never null list of lifecycle events.

isInState

public final boolean isInState(Service.STATE expected)

Description copied from interface: Service

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

Specified by:

isInState in interface Service

Parameters:

expected - the expected state

Returns:

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

toString

public String toString()

Overrides:

toString in class Object

putBlocker

protected void putBlocker(String name,
              String details)

Put a blocker to the blocker map -replacing any with the same name.

Parameters:

name - blocker name

details - any specifics on the block. This must be non-null.

removeBlocker

public void removeBlocker(String name)

Remove a blocker from the blocker map - this is a no-op if the blocker is not present

Parameters:

name - the name of the blocker

getBlockers

public Map<String,String> getBlockers()

Description copied from interface: Service

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

Specified by:

getBlockers in interface Service

Returns:

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