public final class StateCodec

Object
StateCodec

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.

Methods

`public static` `Map<String, Object> toMap(AppState state)`	Renders a state as the nested map an operating system can carry between devices.
`public static` `AppState fromMap(Map<String, Object> m)`	Rebuilds a state from the map form.
`public static` `String toJson(AppState state)`	Renders a state as JSON, for a relay.
`public static` `AppState fromJson(String json) throws IOException`	Parses the JSON form.
`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.
`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.

Inherited methods

From Object

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

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 AppState: 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 Map<String, Object>: 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 AppState: 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 String: 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

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 Map<String, Object>: 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 AppState: the state

Returns

the encoded size in characters