Interface IPushNotificationEngine

All Known Implementing Classes:
PushEngine
public interface IPushNotificationEngine
The Push Notification (PN) engine — the runtime that owns the executor, the concurrency ceiling, the spool, the transports, and the region router, and that performs sends.

A single engine exists per server, implemented in the com.iizix.server bundle, in the package com.iizix.server.push.engine, where PushEngineFactory builds it; com.iizix.server requires com.iizix.core, where this interface lives. Its lifecycle belongs to com.iizix.server.PushNotificationModule, which ServerShell.onWorkerStarted registers with addModule after loadApplications and before the onServerReady loop. The engine is obtained through the server: IServer.getPushNotificationEngine() (see IPushNotificationService). The engine bounds its own outbound concurrency — the virtual-thread executor it runs on is unbounded by construction, so a permit from a semaphore sized to IPushSettings.getMaxParallelPush() is acquired before each dispatch and released on completion, giving the hard ceiling on notifications in flight.

Author:
IIZI

  • Method Details

    • getState

      PushEngineState getState()
      Gets the current lifecycle state of the engine.
      Returns:
      The state; never null.

    • isDisposed

      boolean isDisposed()
      Reports whether the engine has been disposed.

      A disposed engine is in PushEngineState.STOPPED and performs no further work, and it is never revived. PushNotificationModule disposes of the engine and unregisters it from PushNotificationEngineProvider in the same step, so until a later server start registers a new engine IServer.getPushNotificationEngine() throws UnsupportedOperationException rather than returning this one; see IPushNotificationService.

      Returns:
      true if this engine has been disposed.

    • dispose

      void dispose()
      Disposes the engine: transitions through PushEngineState.STOPPING to PushEngineState.STOPPED, refusing new sends, allowing in-flight sends to complete, persisting the spool, and releasing the executor and transports. Idempotent — disposing an already-disposed engine has no effect.

    • getSettings

      IPushSettings getSettings()
      Gets the active configuration settings backing this engine.
      Returns:
      The settings; never null.

    • getRegionTree

      IRegionTree getRegionTree()
      Gets the region tree the router resolves residency against.
      Returns:
      The region tree; never null.

    • newMessageBuilder

      IPushNotificationMessageBuilder newMessageBuilder()
      Creates a new, empty message builder bound to this engine, so that defaults such as TTL are taken from this engine's settings.
      Returns:
      A fresh IPushNotificationMessageBuilder; never null.

    • getPushUserRegistry

      IPushUserRegistry getPushUserRegistry()
      Gets the registry of the Push Notification HTTP API's program users (PUSH-CREDENTIALS.md section 7, ruling R6; declared here by CC-PUSH-SERVER-INI decision 5, 2026-09-26): server code registers a user in memory with a password and the groups whose privileges it gets, and a program then authenticates with it over Basic authentication. Implemented by the engine's credentials, beside the users of the credentials file, which always wins over a registration.
      Returns:
      The registry; never null.

    • planSend

      IRoutingPlan planSend(IPushSendRequest request) throws PushAuthorizationException
      Builds the routing plan for a send without dispatching it — a dry run.

      Resolves the filter against the region tree and the effective policies, and checks the operator's authorization, producing the same IRoutingPlan a real send would, but sending nothing. Useful for the ServerAdmin UI to preview "this send would touch these regions, this many in-session, this many device, this many excluded" before committing.

      Parameters:
      request - The send request (filter, notification, policies, authorization context).
      Returns:
      The routing plan that a real send of this request would follow.
      Throws:
      PushAuthorizationException - if the request's operator is not authorized for a region the plan requires.

    • send

      CompletableFuture<PushResult> send(IPushSendRequest request, IPushProgressListener progress)
      Performs a send asynchronously.

      Builds the routing plan, checks authorization, then dispatches each region slice — local slices through this server's send path, remote slices to the region's server over the server-to-server channel — acquiring a concurrency permit per dispatch so the in-flight count never exceeds IPushSettings.getMaxParallelPush(). Unreachable regions and unreachable endpoints spool. The returned future completes when every slice has been resolved, with a PushResult that carries the routing plan and the per-target, per-region, per-tier outcomes.

      To wait a bounded time for completion, call future.get(timeout, unit) on the result — the framework's completion handle is a standard CompletableFuture.

      Parameters:
      request - The send request.
      progress - An optional progress callback invoked as slices complete, for bulk sends; may be null.
      Returns:
      A future completing with the aggregate PushResult.