Class PushNotificationException

java.lang.Object
java.lang.Throwable
java.lang.Exception
com.iizix.push.PushNotificationException
All Implemented Interfaces:
Serializable
public class PushNotificationException extends Exception
The failure a Push Notification (PN) API callback receives when an operation is refused or cannot be carried out, carrying a reason code a program can branch on.

The reason codes are the wire contract's error vocabulary (PUSH-WIRE-CONTRACT section 1.3) plus the codes only the Java API can meet: PERMISSION_DENIED, GESTURE_REQUIRED, NO_DEVICE, NO_USER and - ruled 2026-09-24, PUSH-PROPS-DESIGN section 4.6 - UNSUPPORTED, TIMEOUT and KEY_CONFLICT, and DISMISSED (since P4-09, the subscribe action). Of the wire's own codes the Java API reports BAD_REQUEST, NOT_CONFIGURED (since P4-07), STORE_FAILURE and INTERNAL. The message is for a log and is never parsed.

The user text (getUserText(), CC-FIX-IIZIRUN-RESUME-RECONNECT, AP-D-2 (c) of CC-PROVE-ANDROID-PUSH-SIGNIN): what the user can be shown for the failure and can do about it, in English, never null - for permission_denied on a phone "Notifications are off for this app: turn them on in the phone's Settings.", since a phone whose user once refused is never asked again and nothing else tells the user why nothing happens. The message stays the log's. An application with a text table of its own uses reason as the key of its entry.

Author:
Christopher Mindus
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    BAD_REQUEST
    The reason "bad_request": an argument was refused, e.g.
    static final String
    DISMISSED
    The reason "dismissed": the user closed the permission prompt a subscribe action's click raised without answering it; the permission stays undecided and the next click asks again (P4-09, PUSH-PROPS-DESIGN section 8.3).
    static final String
    GESTURE_REQUIRED
    The reason "gesture_required": a Browser subscription needs the user's click.
    static final String
    INTERNAL
    The reason "internal": anything else, the engine not running included; the message never carries a stack trace.
    static final String
    KEY_CONFLICT
    The reason "key_conflict": the Browser already holds a push subscription under another VAPID key, and it is never replaced (RR-21 A); or a Cordova device's FCM token belongs to another Firebase project than the application's, as it does inside iiziRun Developer (ruled 2026-09-26, CC-PUSH-ROADMAP row 4 A), and no row is stored for it.
    static final String
    NO_DEVICE
    The reason "no_device": this session has no channel to a device - a Designer, Design Viewer or VSViewer session, a client built before the channel existed, or a channel that reported no device UUID - so no client-bound call can reach one.
    static final String
    NO_USER
    The reason "no_user": the session has no authenticated user, so nothing can answer for "the session's user".
    static final String
    NOT_CONFIGURED
    The reason "not_configured": the application offers no transport this device can be reached through - no VAPID key pair for a Browser, no Firebase project for a Cordova device - so a subscription could never be delivered to (PUSH-WIRE-CONTRACT section 5.1's 409, met by the Java API's subscribe since P4-07).
    static final String
    PERMISSION_DENIED
    The reason "permission_denied": the user refused notifications; final until the user changes it in the Browser's or the operating system's settings, and no code can ask again.
    final String
    reason
    The reason code, never null.
    static final String
    STORE_FAILURE
    The reason "store_failure": the subscription store failed.
    static final String
    TIMEOUT
    The reason "timeout": the client did not answer a client-bound call by its deadline, 30 seconds, or 5 minutes for a subscribe that may show a native prompt (RR-10 A, RR-11 A).
    static final String
    UNSUPPORTED
    The reason "unsupported": the device cannot receive Push Notification at all (RR-10 A).

  • Constructor Summary

    Constructors
    Constructor
    Description
    PushNotificationException(String reason, String message)
    Constructor: the user text is userText(String,PushTransport) of the reason without a transport.
    PushNotificationException(String reason, String message, Throwable cause)
    Constructor with a cause.
    PushNotificationException(String reason, String message, Throwable cause, String userText)
    Constructor with a cause and the text for the user.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    getUserText()
    Gets the text for the user: what the user can be shown for this failure and can do about it, in English, never null.
    static String
    userText(String reason, PushTransport transport)
    The text for the user of a reason code, in English: for PERMISSION_DENIED where to turn notifications on again - the phone's Settings for a device reached by PushTransport.FCM, the Browser's site settings for one reached by PushTransport.VAPID, both when the transport is unknown - and what to do for the other codes; a code this class does not know gets the general text.

    Methods inherited from class Throwable

    addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • PERMISSION_DENIED

      public static final String PERMISSION_DENIED
      The reason "permission_denied": the user refused notifications; final until the user changes it in the Browser's or the operating system's settings, and no code can ask again.
      See Also:

    • GESTURE_REQUIRED

      public static final String GESTURE_REQUIRED
      The reason "gesture_required": a Browser subscription needs the user's click. Not an error in the application's code: configure the subscribe action and let the user press the button.
      See Also:

    • DISMISSED

      public static final String DISMISSED
      The reason "dismissed": the user closed the permission prompt a subscribe action's click raised without answering it; the permission stays undecided and the next click asks again (P4-09, PUSH-PROPS-DESIGN section 8.3). Only a click reports it.
      See Also:

    • NO_DEVICE

      public static final String NO_DEVICE
      The reason "no_device": this session has no channel to a device - a Designer, Design Viewer or VSViewer session, a client built before the channel existed, or a channel that reported no device UUID - so no client-bound call can reach one.
      See Also:

    • NO_USER

      public static final String NO_USER
      The reason "no_user": the session has no authenticated user, so nothing can answer for "the session's user".
      See Also:

    • UNSUPPORTED

      public static final String UNSUPPORTED
      The reason "unsupported": the device cannot receive Push Notification at all (RR-10 A).
      See Also:

    • TIMEOUT

      public static final String TIMEOUT
      The reason "timeout": the client did not answer a client-bound call by its deadline, 30 seconds, or 5 minutes for a subscribe that may show a native prompt (RR-10 A, RR-11 A).
      See Also:

    • KEY_CONFLICT

      public static final String KEY_CONFLICT
      The reason "key_conflict": the Browser already holds a push subscription under another VAPID key, and it is never replaced (RR-21 A); or a Cordova device's FCM token belongs to another Firebase project than the application's, as it does inside iiziRun Developer (ruled 2026-09-26, CC-PUSH-ROADMAP row 4 A), and no row is stored for it.
      See Also:

    • NOT_CONFIGURED

      public static final String NOT_CONFIGURED
      The reason "not_configured": the application offers no transport this device can be reached through - no VAPID key pair for a Browser, no Firebase project for a Cordova device - so a subscription could never be delivered to (PUSH-WIRE-CONTRACT section 5.1's 409, met by the Java API's subscribe since P4-07). queryAvailableTransports tells beforehand.
      See Also:

    • BAD_REQUEST

      public static final String BAD_REQUEST
      The reason "bad_request": an argument was refused, e.g. a notification that supplies the reserved data.iizi member (PUSH-WIRE-CONTRACT section 6.2).
      See Also:

    • STORE_FAILURE

      public static final String STORE_FAILURE
      The reason "store_failure": the subscription store failed.
      See Also:

    • INTERNAL

      public static final String INTERNAL
      The reason "internal": anything else, the engine not running included; the message never carries a stack trace.
      See Also:

    • reason

      public final String reason
      The reason code, never null.

  • Constructor Details

    • PushNotificationException

      public PushNotificationException(String reason, String message)
      Constructor: the user text is userText(String,PushTransport) of the reason without a transport.
      Parameters:
      reason - The reason code.
      message - The message.

    • PushNotificationException

      public PushNotificationException(String reason, String message, Throwable cause)
      Constructor with a cause.
      Parameters:
      reason - The reason code.
      message - The message.
      cause - The cause, or null.

    • PushNotificationException

      public PushNotificationException(String reason, String message, Throwable cause, String userText)
      Constructor with a cause and the text for the user.
      Parameters:
      reason - The reason code.
      message - The message.
      cause - The cause, or null.
      userText - The text for the user, or null for the reason's own without a transport (userText(String,PushTransport)).

  • Method Details

    • getUserText

      public String getUserText()
      Gets the text for the user: what the user can be shown for this failure and can do about it, in English, never null. An application with a text table uses reason as the key of its own entry instead.
      Returns:
      The text.

    • userText

      public static String userText(String reason, PushTransport transport)
      The text for the user of a reason code, in English: for PERMISSION_DENIED where to turn notifications on again - the phone's Settings for a device reached by PushTransport.FCM, the Browser's site settings for one reached by PushTransport.VAPID, both when the transport is unknown - and what to do for the other codes; a code this class does not know gets the general text.
      Parameters:
      reason - The reason code, or null.
      transport - The device's transport, or null when unknown.
      Returns:
      The text, never null.