# Class AppState

java.lang.Object
com.codename1.continuity.AppState

All Implemented Interfaces:
  `Externalizable`

public final class AppState extends Object implements Externalizable

A snapshot of where the user was and what they were doing: the route stack, plus whatever your `StateProvider` chose to add.

The same value serves three purposes, which is why it carries more than the two halves above. It is written to storage so the app can come back after its process dies; it is advertised to the user's other devices so one of them can continue the work; and it travels through a `StateRelay` to devices the platform cannot reach on its own. The `deviceId`, `sequence` and `timestamp` are what let the receiving side tell a state it has already seen -- or its own echo -- from one worth acting on.

##### The routes

`getRoutes()` is the `com.codename1.router.Navigation` stack as a list of paths, oldest first. Restoring it re-runs each path through the route table, which is why an app that navigates with `@Route` gets its screens back for free and one that calls `new MyForm().show()` does not: those navigations are not URL-addressable, so there is nothing to write down. Such an app restores from the payload instead.

##### The payload

`getPayload()` is yours. It has to survive being written to disk, handed to an operating system and delivered to a different device running a possibly different build of your app, so it is restricted to values that mean the same thing everywhere: `String`, `Integer`, `Long`, `Double`, `Boolean`, and `List` and `Map` of those. Anything else is refused when the state is built, with a message naming the offending key, rather than being dropped somewhere the failure cannot be traced back here.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AppState()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `externalize(DataOutputStream out)`
  Allows us to store an object state, this method must be implemented in order to save the state of an object
  `String`
  `getDeviceId()`
  The device this state was produced on.
  `String`
  `getObjectId()`
  The object id must be unique, it is used to identify the object when loaded even when it is obfuscated.
  `Map<String,Object>`
  `getPayload()`
  The application payload.
  `List<String>`
  `getRoutes()`
  The navigation stack as route paths, oldest first.
  `long`
  `getSequence()`
  A counter that increases with every state this device publishes.
  `long`
  `getTimestamp()`
  When this state was produced, as milliseconds since the epoch on the producing device.
  `String`
  `getTitle()`
  A human readable label for what the user is doing, which a receiving device may show before they accept the continuation.
  `int`
  `getVersion()`
  Returns the version for the current persistance code, the version will be pased to internalized thus allowing the internalize method to recognize classes persisted in older revisions
  `void`
  `internalize(int version, DataInputStream in)`
  Loads the object from the input stream and allows deserialization
  `boolean`
  `isEmpty()`
  True when there is nothing here worth restoring or sending.
  `AppState`
  `setDeviceId(String id)`
  Sets the originating device id.
  `AppState`
  `setPayload(Map<String,Object> p)`
  Replaces the application payload.
  `AppState`
  `setRoutes(List<String> r)`
  Replaces the route paths.
  `AppState`
  `setSequence(long s)`
  Sets the sequence number.
  `AppState`
  `setTimestamp(long t)`
  Sets the production timestamp.
  `AppState`
  `setTitle(String t)`
  Sets the human readable label.
  `String`
  `toString()`
  Returns a string representation of the object.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### AppState

    public AppState()

- ## Method Details

  - ### getRoutes

    public List<String> getRoutes()

    The navigation stack as route paths, oldest first. Never null, possibly empty.

    ###### Returns

    an unmodifiable view of the route paths

  - ### setRoutes

    public AppState setRoutes(List<String> r)

    Replaces the route paths.

    ###### Parameters

    - `r`: the paths, oldest first; null is treated as empty

    ###### Returns

    this state, for chaining

  - ### getPayload

    public Map<String,Object> getPayload()

    The application payload. Never null, possibly empty.

    The view is unmodifiable ALL THE WAY DOWN. Wrapping only the outer map left every nested List and Map mutable, which matters most for an arrival: the same AppState handed to a listener or a provider is afterwards parked, persisted, acknowledged and published, so a caller that consumed a nested list -- removing items as it applied them, which is an ordinary way to write that loop -- changed the framework's own snapshot of what arrived. setPayload() deep-copies on the way in for exactly this reason; the way out needed to match.

    ###### Returns

    an unmodifiable view of the payload

  - ### setPayload

    public AppState setPayload(Map<String,Object> p)

    Replaces the application payload.

    ###### Parameters

    - `p`: the payload; null is treated as empty

    ###### Returns

    this state, for chaining

    ###### Throws

    - `IllegalArgumentException`: when a value cannot cross to another device

  - ### getDeviceId

    public String getDeviceId()

    The device this state was produced on. Used to drop a state's own echo when it comes back through a relay. Never null.

    ###### Returns

    the originating device id

  - ### setDeviceId

    public AppState setDeviceId(String id)

    Sets the originating device id.

    ###### Parameters

    - `id`: the id; null is treated as the empty string

    ###### Returns

    this state, for chaining

  - ### getTitle

    public String getTitle()

    A human readable label for what the user is doing, which a receiving device may show before they accept the continuation. Null when the app did not set one.

    ###### Returns

    the title, or null

  - ### setTitle

    public AppState setTitle(String t)

    Sets the human readable label.

    ###### Parameters

    - `t`: the title, or null for none

    ###### Returns

    this state, for chaining

  - ### getSequence

    public long getSequence()

    A counter that increases with every state this device publishes. Together with the device id it identifies a state exactly, which is how a receiver recognizes one it has already acted on -- two states can share a timestamp, because clocks are coarse.

    ###### Returns

    the sequence number

  - ### setSequence

    public AppState setSequence(long s)

    Sets the sequence number.

    ###### Parameters

    - `s`: the sequence number

    ###### Returns

    this state, for chaining

  - ### getTimestamp

    public long getTimestamp()

    When this state was produced, as milliseconds since the epoch on the producing device.

    Treat it as advisory. It comes from another device's clock, so it is only as trustworthy as that clock: it can be behind, ahead, or -- across a daylight saving change or a manual correction -- both within one session.

    ###### Returns

    the timestamp

  - ### setTimestamp

    public AppState setTimestamp(long t)

    Sets the production timestamp.

    ###### Parameters

    - `t`: milliseconds since the epoch

    ###### Returns

    this state, for chaining

  - ### isEmpty

    public boolean isEmpty()

    True when there is nothing here worth restoring or sending.

    ###### Returns

    true when both the routes and the payload are empty

  - ### toString

    public String toString()
    Description copied from class: `Object`
    Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + '@' + Integer.toHexString(hashCode())
    Overrides:
      `toString` in class `Object`

  - ### getVersion

    public int getVersion()
    Description copied from interface: `Externalizable`

    Returns the version for the current persistance code, the version will be pased to internalized thus allowing the internalize method to recognize classes persisted in older revisions

    ###### Returns

    version number for the persistant code

    Specified by:
      `getVersion` in interface `Externalizable`

  - ### getObjectId

    public String getObjectId()
    Description copied from interface: `Externalizable`

    The object id must be unique, it is used to identify the object when loaded even when it is obfuscated.

    ###### Returns

    a unique id

    Specified by:
      `getObjectId` in interface `Externalizable`

  - ### externalize

    public void externalize(DataOutputStream out) throws IOException
    Description copied from interface: `Externalizable`

    Allows us to store an object state, this method must be implemented in order to save the state of an object

    ###### Parameters

    - `out`: the stream into which the object must be serialized

    ###### Throws

    - `java.io.IOException`: the method may throw an exception
    Specified by:
      `externalize` in interface `Externalizable`
    Throws:
      `IOException`

  - ### internalize

    public void internalize(int version, DataInputStream in) throws IOException
    Description copied from interface: `Externalizable`

    Loads the object from the input stream and allows deserialization

    ###### Parameters

    - `version`: the version the class returned during the externalization processs

    - `in`: the input stream used to load the class

    ###### Throws

    - `java.io.IOException`: the method may throw an exception
    Specified by:
      `internalize` in interface `Externalizable`
    Throws:
      `IOException`