org.apache.hadoop.service
Class AbstractService

java.lang.Object
  extended by org.apache.hadoop.service.AbstractService
All Implemented Interfaces:
Closeable, Service
Direct Known Subclasses:
AbstractLivelinessMonitor, AMRMClient, AMRMClientAsync, AsyncDispatcher, CompositeService, HistoryFileManager, NMClient, NMClientAsync, YarnClient

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

This is the base implementation class for services.


Constructor Summary
AbstractService(String name)
          Construct the service.
 
Method Summary
 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.
 org.apache.hadoop.service.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.
 org.apache.hadoop.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(org.apache.hadoop.service.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 org.apache.hadoop.service.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 org.apache.hadoop.service.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 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(org.apache.hadoop.service.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


Copyright © 2013 Apache Software Foundation. All Rights Reserved.