Class PushClient

java.lang.Object
com.codename1.push.PushClient
public final class PushClient extends Object

Owns push registration and delivers typed push events to an application.

Create exactly one client from the application's init() method, keep it in a field on the main application class, and call register() from start(). Registration is idempotent, so it is safe for start() to call it again when Codename One resumes the application. Do not call unregister() from stop(); unregistering removes the device subscription and is intended for an explicit user opt-out.

The listener is mandatory and is installed before native registration starts. Messages that reach the runtime before register() are kept in a bounded process-local queue and replayed when the client becomes active. Native cold-start implementations also persist messages until the Codename One runtime starts. All listener and registration-sink callbacks run on the Codename One EDT.

Codename One does not discover a listener with reflection or Class.forName(). Calling build() without a listener fails immediately, but the application is responsible for retaining the client and calling register(). Only one client can be active in a process.

See Also:

  • Method Details

    • builder

      public static PushClient.Builder builder(String appId)

      Starts a client builder for a managed BuildCloud push application.

      The application key is displayed in the Push section of the Codename One Console. It identifies the application during client registration; it is not a server API key. Install a PushTransport on the returned builder to bypass BuildCloud and use an application-owned push server.

      Parameters:
      appId - the non-empty Push application key, or an application-owned identifier when using a custom transport
      Returns:
      a new builder
      Throws:
      IllegalArgumentException - if appId is null or empty

    • register

      public void register()

      Activates this client and requests native push registration.

      This method is idempotent. Calling it from each invocation of the application's start() method requests registration only once. A native token persisted before this client becomes active is replayed immediately, then the platform is asked to refresh it. Registration otherwise completes asynchronously through PushListener.onRegistration(PushSubscription) or PushListener.onError(PushError). Messages queued before activation are replayed before this method requests a new native token.

      If another PushClient is already active, this client reports an active_client error and remains inactive.

    • unregister

      public void unregister()

      Removes this device's subscription.

      Use this for an explicit notification opt-out or account-removal workflow, not as part of the normal stop() lifecycle. A later call to register() may subscribe again after unregistration completes. Custom transports report completion through PushTransport.Callback.unregistered().

    • getAppId

      public String getAppId()
      Returns the application key supplied to builder(String).
      Returns:
      the application key

    • getSubscription

      public PushSubscription getSubscription()
      Returns the latest native subscription reported by the transport.
      Returns:
      the current subscription, or null before registration or after unregistration

    • getActiveCallback

      public static PushCallback getActiveCallback()

      Returns the compatibility callback used by generated native bootstraps.

      Application code should use PushListener; this method exists for generated platform code and native transport integrations.

      Returns:
      the active native callback, or null before a client is registered

    • hasActiveClient

      public static boolean hasActiveClient()
      Indicates whether an active client can receive a native message now.
      Returns:
      true after register() activates a client and before unregistration completes

    • dispatch

      public static void dispatch(String envelopeJson)

      Delivers an encoded schema-3 envelope from generated native code.

      If no client is active yet, the message is queued and replayed on the next successful register(). Application code normally does not call this method; a custom PushTransport should use its callback's PushTransport.Callback.message(String) method.

      Parameters:
      envelopeJson - the complete schema-3 JSON envelope