AbstractService (Apache Hadoop Main 3.5.0 API)
Description: declaration: package: org.apache.hadoop.service, class: AbstractService

Package org.apache.hadoop.service

# Class AbstractService

java.lang.Object
org.apache.hadoop.service.AbstractService

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`, `Service`

Direct Known Subclasses:
  `AbstractLaunchableService`, `AbstractLivelinessMonitor`, `AHSClient`, `AMRMClient`, `AMRMClientAsync`, `AsyncDispatcher`, `CompositeService`, `HistoryFileManager`, `NMClient`, `NMClientAsync`, `SharedCacheClient`, `YarnClient`

@Public @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
  Description
  `AbstractService(String name)`
  Construct the service.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final 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.
  `final 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.
  `final Service.STATE`
  `getServiceState()`
  Get the current service state
  `long`
  `getStartTime()`
  Get the service start time
  `void`
  `init(Configuration conf)`
  Initialize the service.
  `final boolean`
  `isInState(Service.STATE expected)`
  Query to see if the service is in a specific state.
  `protected final 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.
  `final 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 Details

  - ### AbstractService

    public AbstractService(String name)
    Construct the service.
    Parameters:
      `name` - service name

- ## Method Details

  - ### 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 `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Specified by:
      `close` in interface `Service`
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### 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 will 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