# Class StateCodec

java.lang.Object
com.codename1.continuity.StateCodec

public final class StateCodec extends Object

Turns an `AppState` into the two forms it has to travel in, and refuses payloads that cannot make the trip.

The two forms are deliberately different. A continuation is handed to the operating system, which stores it as a property list and may deliver it to another device, so it is a nested map of plist-representable values. A relay payload crosses a network to a device that may not be an Apple one at all, so it is JSON. Both are lossless for the value types the payload admits, which is the whole reason the payload admits so few.

This class is public so that a `StateRelay` written by an application can use the same wire format the built-in one does, and so tests can assert on it.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static int`
  `encodedSize(AppState state)`
  The number of characters the rendered JSON form occupies, which is the closest portable stand-in for what a payload costs on any of the transports.
  `static AppState`
  `fromJson(String json)`
  Parses the JSON form.
  `static AppState`
  `fromMap(Map<String,Object> m)`
  Rebuilds a state from the map form.
  `static void`
  `requireRepresentable(Map<String,Object> payload)`
  Throws when any value in the map could not survive being written to a property list, sent as JSON and read back by another build of the app on another device.
  `static String`
  `toJson(AppState state)`
  Renders a state as JSON, for a relay.
  `static Map<String,Object>`
  `toMap(AppState state)`
  Renders a state as the nested map an operating system can carry between devices.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### toMap

    public static Map<String,Object> toMap(AppState state)

    Renders a state as the nested map an operating system can carry between devices.

    ###### Parameters

    - `state`: the state, must not be null

    ###### Returns

    a map of plist-representable values

  - ### fromMap

    public static AppState fromMap(Map<String,Object> m)

    Rebuilds a state from the map form. Unknown keys are ignored, so a newer build of the app on another device can add fields without breaking this one.

    ###### Parameters

    - `m`: the map, or null

    ###### Returns

    the state, or null when the map is null or carries nothing recognizable

  - ### toJson

    public static String toJson(AppState state)

    Renders a state as JSON, for a relay.

    ###### Parameters

    - `state`: the state, must not be null

    ###### Returns

    the JSON document

  - ### fromJson

    public static AppState fromJson(String json) throws IOException

    Parses the JSON form.

    ###### Parameters

    - `json`: the document, or null

    ###### Returns

    the state, or null when the document is null, empty or not an object

    ###### Throws

    - `java.io.IOException`: when the document is malformed
    Throws:
      `IOException`

  - ### requireRepresentable

    public static void requireRepresentable(Map<String,Object> payload)

    Throws when any value in the map could not survive being written to a property list, sent as JSON and read back by another build of the app on another device.

    The admitted types are `String`, `Integer`, `Long`, `Double`, `Boolean`, and `List` and `Map` of those. `Map` keys must be strings, because neither destination format has any other kind of key.

    ###### Parameters

    - `payload`: the payload, or null

    ###### Throws

    - `IllegalArgumentException`: naming the path to the first offending value

  - ### encodedSize

    public static int encodedSize(AppState state)

    The number of characters the rendered JSON form occupies, which is the closest portable stand-in for what a payload costs on any of the transports.

    ###### Parameters

    - `state`: the state

    ###### Returns

    the encoded size in characters