JsonMapper and TransformResult

JsonMapper

The JsonMapper interface provides runtime access to execute a mapper. The general way to obtain a JsonMapper instance involves two steps. First, use the JsonConfigAccess class to get a handle to the JsonMapping. Second, looking up the mapper by name. Both of the following approaches are equivalent:

var mapping = JsonConfigAccess.getMapping("gw.pl.contact-1.0")
var mapper = mapping.Mappers.get("Contact")

// Or you can use the helper method on JsonConfigAccess
var mapper = JsonConfigAccess.getMapper("gw.pl.contact-1.0", "Contact")

Once you have access to a JsonMapper instance, you can then invoke one of the transformObject or transformObjects method variants to obtain a TransformResult object:

var contact : Contact // Presumably the Contact is coming from somewhere:
                      // from the event message rule context, from a query, etc.
var mapper = JsonConfigAccess.getMapper("gw.pl.contact-1.0", "Contact")
var transformResult = mapper.transformObject(contact)

JsonMappingOptions

The transformObject methods can optionally take a JsonMappingOptions object that can change some aspects of how the transform is performed. The JsonMappingOptions object is the mechanism for applying a GraphQL filter to the mapping. Take the following code for example:

var contact : Contact
var mapper = JsonConfigAccess.getMapper("gw.pl.contact-1.0", "Contact")
var transformResult = mapper.transformObject(contact, 
                      new JsonMappingOptions().withFilter
                      ("gw.pl.contact.contact_summary-1.0"))

You can also use the JsonMappingOptions object to disable the automatic tracking that prevents infinite recursion during mapping execution. You can also use the object to allow the transform to complete even if there are exceptions thrown during the mapping. An example of this use case is if you are serializing the output even in the presence of errors for debugging purposes.

TransformResult

The TransformResult object represents the results of a completed transform call. This object contains the results of executing each of the path expressions against a supplied root object. The TransformResult object is an intermediate representation of the data that can then be serialized out to either JSON or XML. For more details of how PolicyCenter translates JSON and JSON Schema into XML and XSD, see the REST API Framework. The TransformResult object is similar to a JsonObject in that it is mainly a map of property names to values. However, the object differs from a JsonObject in that each property value embeds information about the JSON schema property that it represents. Serializing out a JsonObject requires passing the JSON schema definition as an argument during serialization. By contract, the TransformResult object has schema information already embedded in it and always serializes based on that schema. So you can just invoke methods like toPrettyJsonString or toXmlString directly:

var contact : Contact
var mapper = JsonConfigAccess.getMapper("gw.pl.contact-1.0", "Contact")
var transformResult = mapper.transformObject(contact)
var jsonString = transformResult.toPrettyJsonString()
var xmlString = trasnformResult.toXmlString()

The TransformResult object also exposes some methods to allow traversing the tree of values explicitly. You could potentially use these methods to build custom serialization formats for the data.

Serialization options

The various serialization methods on TransformResult objects can take an optional JsonSerializationOptions object. This object controls aspects of how serialization works. By default, serializing a TransformResult object will ignore null properties, null list items, and empty arrays. Note that this last default is different from default JsonObject serialization. The reason is that entity arrays are never null. Mappings will often be used with entities. You can use the JsonSerializationOptions object to change that serialization behavior. However, note that including null properties or elements will require that the associated JSON schema properties or items be marked as x-gw-nullable.

The JsonSerializationOptions object can also be used to include some special properties on the root object when the data is serialized. Such properties can include the fully-qualified name of the schema definition, the correlation ID of the current request, or the timestamp at which the transform was executed. These options are only valid for serialization to JSON. See the javadoc on JsonSerializationOptions for more details.

Usage in REST

In REST API implementations, a TransformResult object can be returned directly by a handler method or embedded as the entity in a Response object. There is no need to explicitly call any of the serialization methods like toJsonString. The REST API Framework itself will serialize the TransformResult object appropriately based on the negotiated content type of the response.