# Class IntentSerializer

java.lang.Object
com.codename1.intents.IntentSerializer

public final class IntentSerializer extends Object

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.

- ## Method Summary

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

  ### Methods inherited from class Object

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

- ## Method Details

  - ### serializeDeclarations

    public static String serializeDeclarations(List<IntentDeclaration> declarations)

    Serializes the application's intent catalogue.

    ###### Parameters

    - `declarations`: 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`: 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`: the parameterization's values
    - `paramsJson`: 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`: the entities to serialize
    - `images`: 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`: the entities to serialize
    - `images`: receives PNG blobs keyed by the name used in the JSON; may be null when inlining
    - `inlineImages`: 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`: the entity type id
    - `id`: 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`: the result to serialize
    - `images`: 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`: the document; null or empty yields null
    Throws:
      `IOException`