The Mappings class is a powerful facility for programmatically transforming sets of field/value pairs into SifDataObject instances based on XPath-like mapping rules. These rules can be read from any DOM Document or configuration file read and written by the AgentConfig class, which makes them easily customizable by the end-user.

Mappings are arranged into a selection hierarchy so that different sets of rules can be created for individual zones, agent SourceIds, and versions of SIF. Rules at lower levels in the hierarchy are inherited from higher levels. Thus, you could create a default set of rules describing how to produce StudentPersonal objects for all zones, and extend or override these rules in a set of child rules that are specific to an individual zone. When selecting the Mappings object for the SIF Message being processed, the select method would choose the zone-specific set of rules over the default rules, but would inherit any default field mappings not explicitly overridden. This technique is very useful when the mapping rules of a SIF Agent differ from zone-to-zone or from one version of SIF to the next.

Each Mappings object is comprised of one or more of the following:

ObjectMappings that defines how to map fields of the application to a SIF Data Object's elements and attributes. Create one ObjectMapping per SIF Data Object type (e.g. for "StudentPersonal", "BusInfo", etc.) An ObjectMapping instance is in turn comprised of one or more FieldMapping objects, each of which is comprised of a Rule. Two Rule implementations are currently defined: XPathRule, which uses an XPath-like query string to describe how to interpret or build a SIF element or attribute; and OtherIdRule, which describes how to interpret or build <OtherId> values.

ValueSets that define a simple mapping from codes and constants used in the application to equivalent codes and constants used by SIF. A ValueSet could be used, for example, to define a mapping table for Grade Levels, Ethnicity Codes, English Proficiency Codes, etc.

User-defined properties comprised of a name and value pair.

Mappings objects form a hierarchy comprised of a root Mappings object -- which is always present and does not have an ID -- and one or more child Mappings of the root. The root serves as a container for all other Mappings objects. Each child of the root container must be assigned a unique ID. Mappings may also be assigned an optional ZoneId filter, SourceId filter, an SIF Version filter.

The unique ID is used to select a Mappings object at runtime when multiple groups of Mappings are present. If you only have one Mappings object, it is recommended that it be given an ID of "default". However, agents that both provide and consume objects will usually define two groups of Mappings objects: one used in the translation of incoming messages and another used in the production of outgoing messages. In this case it is recommended that two Mappings objects be defined, one with an ID of "incoming" or similar and the other with an ID of "outgoing" or similar.

When Mappings are nested, child Mappings inherit the filters, ObjectMappings, ValueSets, and properties of the parent.

When a SourceId filter is assigned to a Mappings object, the select method will exclude any Mappings object that does not include the SourceId passed to that method. If you have tested your agent with several Student Information Systems, for example, you may wish to define the unique mapping rules for each SIS in a separate Mappings object where the SourceId filter includes the SourceId of the SIS agent.

When a ZoneId filter is assigned to a Mappings object, the select method will exclude any Mappings instance that does not include the ZoneId passed to that method. The ZoneId filter can be used to customize mappings on a zone-by-zone basis.

When a SifVersion filter is assigned to a Mappings object, the select method will exclude any Mappings instance that does not include the SIF Version passed to that method. Such a filter can be used to customize mappings for a specific version of SIF. This is often necessary if the tag names of elements or attributes have changed from one version of SIF to the next. In this case, the XPath-like rules that you include in a Mappings object must reflect the element and attribute names of each version of SIF.

Mapping rules are comprised of one or more ObjectMapping and FieldMapping objects that define how to map a field of the local application's database to a SIF Data Object element or attribute. When multiple mappings are defined for a field, the first one that evaluates true is selected. The map method that accepts a SifElement object evaluates the rules of a Mappings object against a SIF Data Object instance to produce a IDictionary of values. Each entry in the table is a key/value pair where the key is the name of the local application field and the value is the value from the SIF Data Object that mapped to that field. Thus, an agent can call the map method to obtain a table of values for each SIF Data Object it is processing. The Mappings class can also be used to produce a SIF Data Object instance from a IDictionary prepared by the agent. Call the map method that accepts a IDictionary instance to return a SifElement object.

Mappings are comprised of a hierarchy of ObjectMapping and FieldMapping object. The ObjectMapping class encapsulates a SIF Data Object type such as StudentPersonal and BusInfo. Each ObjectMapping contains one or more FieldMapping objects to define a field-level mapping. Mapping rules are specified in an XPath-like format relative to the SIF Data Object type named in the ObjectMapping.

The populate method constructs a Mappings hierarchy from a parsed DOM Document. The populate method can only be called on the root Mappings container. Consult the Mappings.dtd file in the Adk's Extras directory for the expected schema.

Author: Eric Petersen

Version: Adk 1.0

Create a Mappings instance and populate it with Mappings children. The easiest way to accomplish this is to call the read method to read an XML configuration file or the populate method to populate a Mappings instance from a DOM Document. Refer to the Adk Developer Guide for more information.

When your agent needs to map local application field values to SIF Data Object elements and attributes, call the select method to select the appropriate Mappings instance based on ZoneId, SourceId, and SIF Version. The select method returns a Mappings instance.