Package io.github.pimak.ntfy.jul

Class NtfyJulHandler

java.lang.Object
java.util.logging.Handler
io.github.pimak.ntfy.jul.NtfyJulHandler
public final class NtfyJulHandler extends Handler
A Handler that forwards SEVERE-and-above (and, when a warn route is configured, WARNING) LogRecords to the ntfy AlertEngine. This is the framework-neutral JUL adapter: attach it to any java.util.logging logger (plain JUL apps, Tomcat, Helidon, …), or let a framework install it — the Quarkus extension feeds it to a LogHandlerBuildItem, so it sees every log record the application produces (JUL, JBoss LogManager, and the SLF4J/Log4j bridges all funnel through java.util.logging).

For zero-code installation see NtfyJulAutoHandler (declarative, logging.properties) and NtfyJulInstaller (programmatic one-liner).

A logging handler must never throw, or it can corrupt the caller's logging path; every publish(java.util.logging.LogRecord) is fully guarded. Level gating mirrors the other adapters: records at Level.SEVERE (JUL's ERROR-equivalent) or above are always alerted, and Level.WARNING records only once the engine activated a warn route (warn-topic). Nothing below WARNING is ever alerted.

  • Constructor Details

    • NtfyJulHandler

      public NtfyJulHandler(AlertEngine engine)
      Equivalent to NtfyJulHandler(AlertEngine, List) with an empty MDC allow-list, i.e. no MDC values in the alert body. Retained as an explicit constructor so callers written against an earlier release stay both source- AND binary-compatible: the (AlertEngine) descriptor keeps linking without recompilation, and its behavior is unchanged.
      Parameters:
      engine - an already-started engine; this handler owns its lifecycle and stops it on close().

    • NtfyJulHandler

      public NtfyJulHandler(AlertEngine engine, List<String> includeMdcKeys)
      Parameters:
      engine - an already-started engine; this handler owns its lifecycle and stops it on close().
      includeMdcKeys - the MDC keys whose values may be rendered into the alert body, in rendering order — an explicit allow-list with no wildcard form; null or empty means no MDC value is ever read. Defensively copied, so a later mutation of the caller's list cannot widen what this handler publishes.

  • Method Details

    • forConfig

      public static NtfyJulHandler forConfig(NtfyConfig config)
      Builds a handler around a fresh, started AlertEngine for config, with engine self-diagnostics routed to System.err (never back through the logging pipeline — see JulDiagnostics). The single construction path shared by the programmatic installer, the auto-handler, and the Quarkus extension's recorder.

      config should be active; an inactive or invalid config never throws — the engine refuses activation with a diagnostic and the returned handler simply drops records.

      Because this is the single construction path, forwarding NtfyConfig.getIncludeMdcKeys() here is the ONE change that wires include-mdc-keys through every installation route at once: NtfyJulInstaller, NtfyJulAutoHandler and the Quarkus extension's recorder all build their handler through forConfig, so none of them needs to know the option exists.

    • counters

      public PipelineCounters counters()
      The alert pipeline's observability counters for this handler's engine — the JUL counterpart of the Logback/Log4j2 appenders' getCounters(). Read-only and pulled, never logged, so surfacing them (in a Micrometer meter, a health check, a JMX bean, …) cannot re-enter the logging pipeline.

      Unlike the appenders, a handler owns exactly one engine for its whole lifetime — it is constructed around an already-started engine and stops it on close() — so the returned instance is stable and its tallies are monotonic for as long as the handler is installed. Re-installing the handler (a new forConfig) yields a new engine with fresh counters.

    • publish

      public void publish(LogRecord record)
      Specified by:
      publish in class Handler

    • flush

      public void flush()
      Specified by:
      flush in class Handler

    • close

      public void close()
      Specified by:
      close in class Handler