public final class IntentSerializer

  1. Object
  2. IntentSerializer

Serializes intent declarations, entities and results to the wire format the platform bridges consume: a compact JSON document plus PNG blobs named by content hash. This class is an internal seam between the core API and the platform bridges – it is public only because ports live in separate artifacts; applications never call it.

The format is versioned ("v": 1). Everything crosses as data because an invocation can be answered while the app has no UI, and because the peer is Swift or Kotlin rather than Java.

Methods

public static String serializeDeclarations(List<IntentDeclaration> declarations)Serializes the application’s intent catalogue.
public static String serializeParams(Map<String, Object> params)Serializes a parameter map for donation or invocation.
public static String mergeParams(Map<String, Object> bound, String paramsJson)Merges bound values under a serialized parameter document, returning a fresh document.
public static String serializeEntities(List<AppEntity> entities, Map<String, byte[]> images)Serializes entities for the search index, collecting their thumbnails.
public static String serializeEntities(List<AppEntity> entities, Map<String, byte[]> images, boolean inlineImages)Serializes entities, optionally carrying their thumbnails inside the document.
public static String serializeEntityRef(String entityType, String id)Serializes a single {type, id} reference for index removal.
public static String serializeResult(IntentResult result, Map<String, byte[]> images)Serializes an intent result for the platform, collecting any snippet imagery.
public static Map<String, Object> parsePayload(String json) throws IOExceptionReduces a Java value to something the wire format can carry.

Inherited methods

From Object

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

Method details

serializeDeclarations

public static String serializeDeclarations(List<IntentDeclaration> declarations)
Serializes the application’s intent catalogue.

Parameters

declarations List<IntentDeclaration>
the declarations to serialize; null becomes empty

serializeParams

public static String serializeParams(Map<String, Object> params)

Serializes a parameter map for donation or invocation.

Values are reduced to the wire types – text, numbers, booleans and epoch millis for dates – because the receiving side is not Java. An AppEntity value reduces to its id, which is the only part of it the platform needs in order to hand the same entity back later.

Parameters

params Map<String, Object>
the values; null becomes an empty document

mergeParams

public static String mergeParams(Map<String, Object> bound, String paramsJson)

Merges bound values under a serialized parameter document, returning a fresh document.

Used when a parameterization is donated: the shortcut has to carry the values the parameterization bound, with anything supplied at donation time still winning, because a binding is a default rather than a lock.

Parameters

bound Map<String, Object>
the parameterization’s values
paramsJson String
values supplied at donation time, may be null

serializeEntities

public static String serializeEntities(List<AppEntity> entities, Map<String, byte[]> images)
Serializes entities for the search index, collecting their thumbnails.

Parameters

entities List<AppEntity>
the entities to serialize
images Map<String, byte[]>
receives PNG blobs keyed by the name used in the JSON

serializeEntities

public static String serializeEntities(List<AppEntity> entities, Map<String, byte[]> images, boolean inlineImages)

Serializes entities, optionally carrying their thumbnails inside the document.

Indexing wants the second form: the blobs go out separately, keyed by the name embedded in the JSON, because a search index takes them one at a time and a base64 copy of every thumbnail in one string would be wasteful.

A query answering a platform picker wants the first. The reply is synchronous and the caller is a native picker being built right now, so there is nowhere to put a side channel of bytes that the reply is guaranteed to be matched with. Inlining a handful of small thumbnails is the whole transaction.

Parameters

entities List<AppEntity>
the entities to serialize
images Map<String, byte[]>
receives PNG blobs keyed by the name used in the JSON; may be null when inlining
inlineImages boolean
true to also write each thumbnail as base64 under imageData

serializeEntityRef

public static String serializeEntityRef(String entityType, String id)
Serializes a single {type, id} reference for index removal.

Parameters

entityType String
the entity type id
id String
the entity id

serializeResult

public static String serializeResult(IntentResult result, Map<String, byte[]> images)
Serializes an intent result for the platform, collecting any snippet imagery.

Parameters

result IntentResult
the result to serialize
images Map<String, byte[]>
receives PNG blobs referenced by the snippet

parsePayload

public static Map<String, Object> parsePayload(String json) throws IOException

Reduces a Java value to something the wire format can carry. Returns null for anything unsupported, which the callers drop rather than guess at.

Note the deliberate absence of a cast-and-catch: every branch is an instanceof test. On iOS a failed cast does not throw, so a catch (ClassCastException) here would be dead code guarding a native crash. Parses an intent payload, keeping whole numbers as Long.

The convenience JSONParser.parseJSON defaults to materialising every number as a Double, which silently rounds anything past 2^53: an id of 9007199254740993 arrives as …992, still integral, so every downstream check accepts it and the handler acts on a number the caller never sent. Ids of that size are ordinary – snowflake ids, database keys – and the corruption is invisible at every layer.

Every path that reads an intent payload goes through this, in core and in the ports, so the guarantee does not depend on remembering it at six call sites.

Parameters

json String
the document; null or empty yields null

Throws

IOException