Integration mappers

Each integration mapping file can have any number of integration mappers defined in it. Each integration mapper defines a single entry point into the mapping transformation. An integration mapper takes a single input object and transforms it into JSON or XML syntax that matches an output schema. Each integration mapper contains mapping properties that correspond to each property in the output schema. Each integration mapper defines the following:

A root type: Both the expected runtime input to this mapper and the base type of the symbol available to path and predicate expressions.
A schema definition: The JSON Schema definition whose output this mapper is producing. The schema definition is resolved in the context of the root schema name for the mapping file.
A set of properties: Definitions for obtaining data for each property in a referenced schema definition. A mapper is not technically required to specify every property on the referenced schema definition. However, a warning will be issued if there are properties on the schema definition that are not being mapped.

Note that the mapper name is not required to match the name of the schema definition it targets. In fact, you may legally have multiple mappers that target the same schema defined within the same file. For example, the mappers might take different root object types but produce output that conforms to the same schema.

Mapping properties

The properties on an integration mapper must correspond to properties on the associated JSON Schema definition. Moreover, the names of the keys in the mapper properties are assumed to be the names of the JSON schema definition properties. Effectively, the integration mapper is defining the output directly in terms of the schema. The integration mapper is then specifying how to get the value for each property that can appear in the output.

path

Each mapping property must specify a path expression. This expression is a Gosu expression that evaluates to the value that must be used as the output of that schema property. The path expression has a single symbol available to it. The single symbol has a type equal to the root type of the mapper. The single symbol also has a name equal to the relative name of the type. For example, suppose that the root type for a mapper is entity.Contact. The path expressions on the mapper properties will have a single symbol named Contact with a type of entity.Contact. The path expression must evaluate to something appropriate for the referenced schema property:

If the schema property is a scalar property, the path expression must evaluate to a Java Input Type listed in JSON data types and formats. The evaluation is based on the type/format/x-gw-type of the schema property. For example, if the schema type is string and the format is date-time, the path expression must evaluate to something assignable to java.util.Date.
If the schema property is an array of scalars, the path expression must evaluate to an Iterable or array. The elements of the Iterable or array can be inputs to the data conversion for the type of the schema property items.
If the schema property is an object property, then the mapper property must be specified. In addition, the return type of the path expression must be assignable to the root type of the referenced mapper. For example, if the referenced mapper is #/mappers/Address and the Address mapper has a root type of entity.Address, the path expression must evaluate to an entity.Address or a subtype.
If the schema property is an object array property, then the mapper property must be specified. In addition, the path expression must evaluate to an Iterable or array whose elements can be assigned to the root type of the referenced mapper.

There is no automatic coercion performed for path expressions. Moreover, if a schema property is of type string with no format or is x-gw-type, the Gosu path expression must evaluate to a java.lang.String. This evaluation must be with no implicit invocation of toString or any similar method.

The path expression can be an arbitrary Gosu expression. The expression is not required to be a simple property path. The expression could be a method call, a static method call, or another complex Gosu expression.

predicate

The predicate property is an optional boolean or Boolean predicate that will be evaluated before the path expression is evaluated. The predicate property can also return a java.lang.Boolean type. However, the property cannot evaluate to null at runtime. If the predicate expression evaluates to false, the path expression will never be evaluated and the property will be treated as having a null value. The predicate expression can be used to guard the evaluation of the path expression. This guarding can be useful if the output schema flattens subtype columns onto a single object. For example, suppose that the output schema for Contact defines properties firstName and lastName. In this case, the predicate expression might be

Contact typeis
                Person

, and the path expression could be

(Contact
                as Person).FirstName

. Using the predicate expression in this way allows the path expression to downcast directly instead of using a more awkward ternary expression.

mapper

The mapper property defines the mapper to use when the schema property is an object or array of objects. Mapper references use a similar syntax as schema references. They must be of the form #/mappers/<name> when the referenced mapper is defined in the same mapping. They must be of the form <alias>#/mappers/<name> when the mapper is imported as <alias>. The referenced mapper must have a schemaDefinition property that matches the $ref on the schema property. For example, suppose that the Contact JSON schema definition has a primaryAddress schema property with a $ref of #/definitions/Address. In this case, the primaryAddress property on the Contact integration mapper must have a mapper reference where the schemaDefinition is Address. See Integration mapping examples for an example of how the structure of integration mapping properties and mapper references mimic the structure of JSON schema properties and definition references.