Interface IPushNotificationCommonAPI

All Known Subinterfaces:
IAppSessionPushNotificationAPI, IPushNotificationAPI
All Known Implementing Classes:
AppSessionPushAPI, ClientSessionPushAPI, PushSessionAPI
public interface IPushNotificationCommonAPI
The members shared by the two server-side Push Notification (PN) APIs: the client session's IPushNotificationAPI and the application session's IAppSessionPushNotificationAPI.

Scope. An instance is bound to one application session, and through it to one application ID and to the user authenticated in that session. Every query answers for that application and that user; nothing here reaches another application's subscriptions, with one declared exception: IPushNotificationAPI.resetDeviceEverywhere (ruled 2026-09-25, P4-b), which removes the user's rows of every application on the device the session is on, as iiziRun's Reset does. When the session has no authenticated user, every operation that answers for "the session's user" fails loudly with the reason no_user; it never matches nothing and reports success.

Asynchronous, with the result on the session's worker thread. Every operation returns at once and reports through a BiFunction<RESULT,Exception,Void> callback, the form the codebase already uses for asynchronous callbacks (LocationUtils.getGeoLocation). Exactly one of the two arguments is non-null: the result, or the failure. The value the callback returns is ignored; return null.

The callback is called on the worker thread of the session the API belongs to - the client session's worker (IClientSessionGyro.getClientWorker()) for IPushNotificationAPI, the application session's worker (IAppSessionGyro.getAppWorker()) for IAppSessionPushNotificationAPI. It is never called on an engine, transport, servlet, WebSocket or database thread, and never synchronously inside the method that started the operation, even when the answer is known at once. Application code may therefore touch properties and the UI from the callback without posting. When the session is disposed before an operation completes, the operation still completes on the server - a send is not cancelled - the callback is not called, and the outcome is logged at INFO.

A failure is a PushNotificationException carrying a reason code from the wire contract's error vocabulary, or an unexpected exception from the implementation.

Listeners are registered synchronously: registration is not an operation, and it returns whether the listener set changed. Implementations hold them in a com.iizix.GenericListener, so adding a listener twice changes nothing and a listener that throws is logged without stopping the others.

The contract behind these declarations is BuildUtil/markdown/designs/PUSH-WIRE-CONTRACT.md section 9.

Author:
Christopher Mindus

  • Method Details

    • newMessageBuilder

      IPushNotificationMessageBuilder newMessageBuilder()
      Creates a new, empty builder of a notification for a send through this API: the way application code builds an IPushNotification without reaching the engine (ruled 2026-09-26, CC-PUSH-ROADMAP row 6 A). The builder is bound to nothing and the call is synchronous: it answers whether or not the engine is running - a send is what fails, with the reason internal, when it is not. A notification built without a time-to-live takes the application's TTL property, else the server default, at dispatch (PUSH-WIRE-CONTRACT section 6.4).
      Returns:
      A fresh builder, never null.

    • querySubscriptions

      void querySubscriptions(String topic, BiFunction<List<IPushSubscriptionInfo>, Exception, Void> callback)
      Queries the subscriptions of the session's user for this application, on every device the user has subscribed from. The result never carries key material, an endpoint or a token.
      Parameters:
      topic - The topic, the empty string for the application-level subscriptions, or null for every topic.
      callback - Called on the session's worker thread with the subscriptions, possibly empty, or with the failure.
      Throws:
      NullPointerException - If callback is null.

    • queryAvailableTransports

      void queryAvailableTransports(BiFunction<Set<PushTransport>, Exception, Void> callback)
      Queries the transports this server can deliver through for this application: PushTransport.VAPID when the application has a VAPID key pair, PushTransport.FCM when it has Firebase credentials. PushTransport.APNS is never in the set.

      An empty set means Push Notification cannot reach any device of this application on this server. The application should say so rather than offer a subscription that can never be delivered to.

      Parameters:
      callback - Called on the session's worker thread with the set, possibly empty, or with the failure.
      Throws:
      NullPointerException - If callback is null.

    • addPushNotificationListener

      boolean addPushNotificationListener(IPushNotificationListener listener)
      Adds a listener for the Push Notification events of this session's user and application. The listener is called on the session's worker thread. Adding the same listener again has no effect but to return false.
      Parameters:
      listener - The listener.
      Returns:
      true if the listener was added, false if it was already present.
      Throws:
      NullPointerException - If listener is null.

    • removePushNotificationListener

      boolean removePushNotificationListener(IPushNotificationListener listener)
      Removes a listener.
      Parameters:
      listener - The listener.
      Returns:
      true if the listener was removed, false if it was not present.