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

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

  This is the base implementation class for services.

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete 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.
    `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 `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(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 © 2022 Apache Software Foundation. All rights reserved.