Interface IPushNotificationEngine

All Known Implementing Classes:
PushEngine
public interface IPushNotificationEngine
The push notification 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.push bundle and 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; the next access to the service creates a fresh engine rather than reviving this one.

      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.

    • 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.