public final class Continuity

Turns the framework on. Called for you by setStateProvider(StateProvider); call it directly when the route stack alone is all you need saved.

Nothing before this call has any effect, which is what keeps an app that does not use this API behaving exactly as it always did.

Whether this platform can advertise the current state to the user’s other devices while they are together.

Branch on this rather than on the platform name: it is true on Apple platforms today and the set is expected to grow, and a com.codename1.ui.Display#getPlatformName test would have to be found and changed when it does.

Whether a restorable state found at startup, or arriving from another device, is applied automatically. On by default.

Turning it off leaves restore() and every listener working exactly as before; what stops is the framework acting on its own. Use it when the decision to move the user is always the app’s.

How old a stored state may be and still be restored, in milliseconds. Zero, the default, means no limit: an app the user opens after a month comes back where they left it, which is what they expect of it.

Set it when coming back is only meaningful for a while – a checkout, a queue position, a booking hold.

Internal. Called by com.codename1.router.Navigation between the route factories of a restore, and again before it shows the rebuilt screen. True once a factory has ended the session – so the rebuild stops instead of running every remaining factory against an account that has just signed out.

The lifecycle check in restore() runs only after restoreStack() has returned, which is far too late for this: by then those factories have constructed their forms, and whatever they queried or wrote for the signed-out account is done. Emptying the stack afterwards undoes none of it.

A direct call for the reason routeStackChanged() gives: it answers false immediately unless a restore is actually in progress, and a listener registry here would be public API earned by one internal caller.

Writes the current state now, and offers it to every enabled channel: storage always, the platform’s continuation where there is one, and the relay if one is set.

Cheap enough to call freely – the state is a list of paths and a small map – but it does touch storage, so it belongs at the end of a change rather than inside a loop.

Internal. Whether a checkpoint is owed – something changed since the last one was written.

Exists so a port with a suspend callback can skip the event-thread round trip entirely in the common case, where the write-through already happened as the user navigated.

Builds a state from the route stack and the provider. Useful for sending one somewhere of your own.

The state itself is not stored – only checkpoint() does that – but the sequence counter it allocates is remembered, so states keep a rising order across a relaunch even for an application that never checkpoints. When that counter cannot be written this returns null, because a state carrying a number this device will hand out again is unsafe to send.

Restores whatever getRestorableState() offers.

Written to read as “restore, or else begin”:

public void start() {
    if (!Continuity.restore()) {
        Navigation.navigate("/home");
    }
}

Records that the application has handled state itself, so it is not offered again.

For the pattern ContinuityListener documents: do the work yourself and return false. That path never reaches restore(), so nothing recorded the acknowledgement durably – the sequence stayed in this process only, and after a relaunch the relay’s unchanged document was accepted again and the listener repeated its side effects, against the act-once guarantee.

Deliberately NOT inferred from a false return. False also means “keep it, I will prompt and call restore() when the user accepts”, and marking that handled immediately would lose the state if the process died before they answered – which is the same data loss as marking a parked state. The two intentions are different, so the application says which it means.

Restores a specific state: hands its payload to the provider, then replays its route stack.

This is the second half of the “ask first” pattern – a ContinuityListener that returned false to hold a state calls this once the user accepts it.

Asks the relay for anything newer than what is here, on a background thread. Returns immediately.

Worth calling when the app comes back to the foreground: a continuation reaches a nearby device on its own, but a relay is only read when something asks it to be.

Forgets everything: the stored checkpoint, any parked arrival, the activity advertised to the user’s other devices, and anything queued for the relay.

Belongs on your logout path, PAIRED WITH disable(), and enable() on the way back in.

This call alone is not a logout. It forgets the account’s data and deliberately leaves continuity switched ON, because forgetting state and turning the feature off are two different things: an application is entitled to do the first without the second – a “start over” that is not a sign-out – and making this imply the other would stop continuity dead for every app that used it that way and never called enable() again.

The consequence, if it is not paired: a continuation that arrives while the login screen is up reaches a framework that is still listening and still enabled. It is a valid arrival by every test this class makes – it came AFTER the clear, so it is not from the session that ended – so the signed-out account’s routes and payload are restored over the login screen and written to storage. disable() is what closes that gap; enable() at login reopens it.

The advertised activity outlives the app’s own screen, so an account’s work would otherwise stay offered to the devices around it after the user signed out – and a queued relay publish would have gone out later under whatever credentials the relay returned by then, which after a logout is the NEXT account’s.

One thing it cannot undo: a relay request already on the wire when this is called. Nothing in this process can recall that. What this guarantees is that nothing follows it.

The activity type this app publishes and answers to, which is the app’s package name followed by .continuity.

Fixed by the build, which declares the same string to the platform in NSUserActivityTypes; the two have to agree or the operating system refuses to deliver anything. Exposed because an app that also publishes activities of its own needs to know which one is this framework’s, and because it is the first thing to check when a continuation never arrives.

Internal. Installs the inbound seam WITHOUT turning continuity on. Application code uses com.codename1.continuity.sync.SyncedStore.addChangeListener.

com.codename1.continuity.sync is a package of its own precisely so that its cost is earned separately, and enable() is not a cost the synced store asks for: it makes every route change checkpoint, and a checkpoint advertises the app’s navigation to the devices around it over Handoff. Registering a store listener used to call it, so an application that wanted a key/value store the user’s devices share – and nothing else – was opted into broadcasting its route stack.

The store’s own notification does not go through enabled (see Callback.syncedStoreChanged), which is what lets the listener work with continuity still off.