# Interface ContinuityListener

public interface ContinuityListener

Notified when a state arrives from somewhere other than this device's own storage: one of the user's other devices handed off what they were doing, or a `StateRelay` produced something newer than what is here.

Registered with `Continuity.addContinuationListener(ContinuityListener)`. Called on the event dispatch thread, and never for this device's own echo.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `stateReceived(AppState state)`
  A state arrived.

- ## Method Details

  - ### stateReceived

    boolean stateReceived(AppState state)

    A state arrived. Return true to let the framework restore it, false to ignore it.

    Returning false is the hook for the decisions only the app can make -- that the user is midway through a payment and must not be moved, that the state is older than what is on screen, that it belongs to a different account than the one signed in here. A listener that returns false has consumed the state: nothing is restored and no other listener is asked.

    ###### A false you will not come back from must acknowledge

    False keeps the state. It has to: the ordinary reason to return false is that you are about to ask the user, and the arrival's only other copy may be on the relay -- so the framework holds it, and holds this device's own checkpoints off the relay behind it, until you say what happened. `Continuity.restore(AppState)` says accepted; `Continuity.acknowledge(AppState)` says finished with.

    So a false that REJECTS -- the wrong account, older than the screen, anything you will never restore -- must call `Continuity.acknowledge(AppState)`, or that hold never ends: `Continuity.getRestorableState()` goes on offering the state you rejected, and this device stops publishing to the relay for the rest of the process. The framework cannot tell a rejection from a prompt that has not been answered yet, and guessing wrong in the other direction loses work the user was about to accept.

    Doing the work yourself and returning false is a supported pattern, and is how an app prompts before jumping: keep the state, return false, and call `Continuity.restore(AppState)` when the user accepts.

    If you handle it yourself and never call `restore`, call `Continuity.acknowledge(AppState)` instead. Restoring records that the state was acted on so it is not offered again after a relaunch; handling it silently does not, and without the acknowledgement the relay's unchanged document is accepted on the next launch and your side effects run a second time. It is not inferred from the false return, because false also means "I am going to prompt" -- and marking that handled before the user answers would lose the state if the process died first.

    ###### Parameters

    - `state`: the state that arrived

    ###### Returns

    true to restore it now