Package io.karatelabs.common

Interface Stoppable

All Superinterfaces:
AutoCloseable
public interface Stoppable extends AutoCloseable
Anything long-lived that an embedding application may need to enumerate and drain — an HTTP server, a websocket client, a thread pool, a browser process.

This is the stop contract for the Karate ecosystem. A component that holds threads, sockets or child processes past the call that created it should implement this interface and register itself once it is genuinely running, then unregister when it has stopped — whether that stop came from the owner, from the registry, or from the component itself (a socket closed by the peer, a process that exited).

Implementation rules, all of which KarateLifecycle.shutdownAll() relies on:

  • stop() is graceful — it releases resources the polite way (close frames, in-flight requests drained) rather than killing threads.
  • stop() is blocking — it returns only once the component has actually stopped, so a caller can sequence shutdown deterministically.
  • stop() is idempotent — calling it twice, or on something that already stopped by itself, is a no-op and never throws for that reason.

Daemon threads (see ThreadUtils) remain the backstop, not the plan: if a stop is skipped for any reason the JVM still terminates, but callbacks may be dropped and peers may see abrupt disconnects. Registering here is what turns that backstop into an orderly shutdown.

Extends AutoCloseable so an instance can be used in try-with-resources; close() simply delegates to stop() and, unlike the parent declaration, throws no checked exception.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
     
    default ExecutorService
    lifecycleExecutor()
    The executor this component owns, when it owns one — purely for inspection (queue depth, active count) by tooling.
    String
    lifecycleKind()
    Short category shared by all instances of a kind, lower-case and hyphenated — e.g.
    String
    lifecycleName()
    Human-readable identity for logs and for listing what is running, ideally carrying the one detail that distinguishes this instance from its siblings — e.g.
    void
    stop()
    Stop this component: graceful, blocking, idempotent.

  • Method Details

    • lifecycleName

      String lifecycleName()
      Human-readable identity for logs and for listing what is running, ideally carrying the one detail that distinguishes this instance from its siblings — e.g. "http-server:8080", "ws-client:ws://localhost:8080/echo".

    • lifecycleKind

      String lifecycleKind()
      Short category shared by all instances of a kind, lower-case and hyphenated — e.g. "http-server", "ws-client", "executor". Meant for grouping and filtering, never parsed for meaning.

    • stop

      void stop()
      Stop this component: graceful, blocking, idempotent.

    • close

      default void close()
      Specified by:
      close in interface AutoCloseable

    • lifecycleExecutor

      default ExecutorService lifecycleExecutor()
      The executor this component owns, when it owns one — purely for inspection (queue depth, active count) by tooling. Returns null when there is nothing meaningful to expose, which is the common case; never call shutdown() on what this hands back, that is stop()'s job.