Class PushSessionAPI

java.lang.Object
com.iizix.server.push.api.PushSessionAPI
All Implemented Interfaces:
IPushNotificationCommonAPI, PushEvents.ISink
Direct Known Subclasses:
AppSessionPushAPI, ClientSessionPushAPI
public abstract class PushSessionAPI extends Object implements IPushNotificationCommonAPI, PushEvents.ISink
The part of the server-side Push Notification (PN) API the client session's and the application session's instances share (PUSH-PROPS-DESIGN section 4.1, P4-04): the message builder, the queries and the listeners of IPushNotificationCommonAPI, the threading rule of section 5, and the engine-sourced events of section 4.4 received from the engine's PushEvents.

Threading. Nothing blocking runs on a session worker: a store query runs on a virtual thread and only its result is posted, through PushCallbackTask, to the worker the context names. An answer known at once - no_user, an argument refused - is posted the same way and never handed back inside the call. Listener registration is the one synchronous member, as contract 9.2 says.

Events reach this instance on the store's or the engine's thread - a receipt on the reporting client's connection thread (P4-11) - are matched to the session's user and application then, and are posted to the worker where the GenericListener delivers them, each listener in its own try/catch.

Disposal. dispose() unregisters from the hub, clears the listeners and abandons every pending callback with an INFO line (design 6.2). It is called by the gyro's own disposal, before the session's worker is disposed of.

Author:
Christopher Mindus

  • Field Details

  • Constructor Details

  • Method Details

    • context

      public IPushSessionContext context()
      Gets the session.
      Returns:
      The session context.

    • isDisposed

      public boolean isDisposed()
      Checks whether this instance is disposed of.
      Returns:
      true if disposed.

    • getPendingCount

      public int getPendingCount()
      Gets the number of callbacks posted to the worker and not yet run, for diagnostics and tests.
      Returns:
      The count.

    • dispose

      public void dispose()
      Disposes of this instance: unregisters from the engine's events, clears the listeners and abandons every pending callback, each logged INFO as not completed.

    • engine

      protected PushEngine engine() throws PushNotificationException
      Gets the running engine.
      Throws:
      PushNotificationException - internal when no engine is running.

    • user

      protected long user(String operation) throws PushNotificationException
      Gets the session's user ID.
      Parameters:
      operation - The operation, for the message.
      Throws:
      PushNotificationException - no_user when the session has no authenticated user.

    • topics

      protected static List<String> topics(String topic)
      The store's Topic filter for a query: null is every Topic, the empty string the application-level subscription, a name that Topic.

    • complete

      protected <R> void complete(String operation, BiFunction<R, Exception, Void> callback, R result, Exception failure)
      Posts a completed operation's callback to the session's worker.
      Parameters:
      operation - The operation.
      callback - The callback.
      result - The result, null on failure.
      failure - The failure, null on success.

    • fail

      protected <R> void fail(String operation, BiFunction<R, Exception, Void> callback, String reason, String message)
      Posts a failure known at once to the session's worker - never handed back inside the call.
      Parameters:
      operation - The operation.
      callback - The callback.
      reason - The reason code.
      message - The message.

    • runOff

      protected <R> void runOff(String operation, BiFunction<R, Exception, Void> callback, Callable<R> work)
      Runs blocking work - a store call, a send - on a virtual thread and posts its outcome to the session's worker. A PushNotificationException is reported as it is, an SQLException as store_failure, anything else as internal.
      Parameters:
      operation - The operation.
      callback - The callback.
      work - The work.

    • newMessageBuilder

      public IPushNotificationMessageBuilder newMessageBuilder()
      --- IPushNotificationCommonAPI ---
      Specified by:
      newMessageBuilder in interface IPushNotificationCommonAPI
      Returns:
      A fresh builder, never null.

    • querySubscriptions

      public void querySubscriptions(String topic, BiFunction<List<IPushSubscriptionInfo>, Exception, Void> callback)
      Description copied from interface: IPushNotificationCommonAPI
      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.
      Specified by:
      querySubscriptions in interface IPushNotificationCommonAPI
      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.

    • queryAvailableTransports

      public void queryAvailableTransports(BiFunction<Set<PushTransport>, Exception, Void> callback)
      Description copied from interface: IPushNotificationCommonAPI
      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.

      Specified by:
      queryAvailableTransports in interface IPushNotificationCommonAPI
      Parameters:
      callback - Called on the session's worker thread with the set, possibly empty, or with the failure.

    • addPushNotificationListener

      public boolean addPushNotificationListener(IPushNotificationListener listener)
      Description copied from interface: IPushNotificationCommonAPI
      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.
      Specified by:
      addPushNotificationListener in interface IPushNotificationCommonAPI
      Parameters:
      listener - The listener.
      Returns:
      true if the listener was added, false if it was already present.

    • removePushNotificationListener

      public boolean removePushNotificationListener(IPushNotificationListener listener)
      Description copied from interface: IPushNotificationCommonAPI
      Removes a listener.
      Specified by:
      removePushNotificationListener in interface IPushNotificationCommonAPI
      Parameters:
      listener - The listener.
      Returns:
      true if the listener was removed, false if it was not present.

    • isFor

      public boolean isFor(long uid, String appId)
      --- PushEvents.ISink: the engine-sourced events, posted to the worker ---
      Specified by:
      isFor in interface PushEvents.ISink
      Parameters:
      uid - The user ID.
      appId - The canonical application ID.
      Returns:
      true when the sink's session belongs to that user and that application and has a listener to tell.

    • onSubscriptionCreated

      public void onSubscriptionCreated(SubscriptionRecord subscription)
      Description copied from interface: PushEvents.ISink
      Called when a subscription was newly stored.
      Specified by:
      onSubscriptionCreated in interface PushEvents.ISink
      Parameters:
      subscription - The row.

    • onSubscriptionRemoved

      public void onSubscriptionRemoved(SubscriptionRecord subscription, String reason)
      Description copied from interface: PushEvents.ISink
      Called when a subscription was removed.
      Specified by:
      onSubscriptionRemoved in interface PushEvents.ISink
      Parameters:
      subscription - The row as it was.
      reason - An IPushNotificationListener.REMOVED_* constant.

    • onSendFailed

      public void onSendFailed(String messageID, DeliveryTarget target, DeliveryOutcome outcome, String detail)
      Description copied from interface: PushEvents.ISink
      Called when a target of a send ended in a failure (PushEvents.FAILURES).
      Specified by:
      onSendFailed in interface PushEvents.ISink
      Parameters:
      messageID - The message ID of the send, empty when the notification carried none.
      target - The target.
      outcome - The outcome.
      detail - The diagnostic, never null.

    • onNotificationReceived

      public void onNotificationReceived(IPushReceipt receipt)
      Description copied from interface: PushEvents.ISink
      Called when a client reported that a notification was shown (P4-11).
      Specified by:
      onNotificationReceived in interface PushEvents.ISink
      Parameters:
      receipt - The receipt.

    • onNotificationAction

      public void onNotificationAction(IPushReceipt receipt, String action)
      Description copied from interface: PushEvents.ISink
      Called when a client reported a click on a notification or on one of its actions (P4-11).
      Specified by:
      onNotificationAction in interface PushEvents.ISink
      Parameters:
      receipt - The receipt.
      action - The action identity, empty for the notification itself.