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 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