public final class PushClient

  1. Object
  2. PushClient

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

Nested types

class PushClient.BuilderConfigures a PushClient.

Methods

public static PushClient.Builder builder(String appId)Starts a client builder for a managed BuildCloud push application.
public void register()Activates this client and requests native push registration.
public void unregister()Removes this device’s subscription.
public String getAppId()Returns the application key supplied to builder(String).
public PushSubscription getSubscription()Returns the latest native subscription reported by the transport.
public static PushCallback getActiveCallback()Returns the compatibility callback used by generated native bootstraps.
public static boolean hasActiveClient()Indicates whether an active client can receive a native message now.
public static void dispatch(String envelopeJson)Delivers an encoded schema-3 envelope from generated native code.

Inherited methods

From Object

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

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 String
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 String
the complete schema-3 JSON envelope