com.edustructures.sifworks.tools.mapping
Class Mappings

java.lang.Object
  com.edustructures.sifworks.tools.mapping.Mappings

public class Mappings
extends java.lang.Object

Manages a set of mapping rules that define how to tranform a set of application field values into SIF Data Objects. The Mappings class is a powerful facility for programmatically transforming sets of data 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.

To use the Mappings class,

• 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.
  
  
• Call the map method to produce a SIFDataObject from a set of field values prepared by your application (i.e. when preparing outbound messages), or to populate your data from a SIFDataObject (i.e. when processing inbound messages).
  
  
• The set of field values being mapped to or from SIF is maintained by an instance of a class implementing the FieldAdaptor interface. The ADK provides a default set of classes that implement this interface and that can map data to a Map (as strings or as native data types), as well as to a Java ResultSet object.
  
  
• The ADK allows for custom data mapping implementations to be created. To create your own custom implementation, create a class that implements the FieldAdaptor interface.

Overview

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 Hierarchy

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.

SourceId Filter

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.

ZoneId Filter

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.

SIFVersion Filter

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.

Mappings Rules

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 set of of values. Each entry in the FieldAdaptor 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 FieldAdaptor prepared by the agent. Call the map method that accepts a FieldAdaptor 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.

XML Configuration

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.

Notes for ADK 1.x users

In the 1.x version of the ADK, all of the overloads of the map method expected a java.util.Map to be passed in. ADK 2.0 supports mapping to other storage types of data, and as such, the java.util.Map parameter was replaced with a FieldAdaptor.

The ADK does provides the StringMapAdaptor implementation class that matches the mappings behavior of the 1.x version of the ADK. To convert your ADK 1.x code to use the ADK 2.x Mappings class, create an instance of StringMapAdaptor to wrap your Map instance and pass that to the Mappings.Map(...)StringMapAdaptor formats data from SIF using SIF 1.x formats and stores them in the Map as a text value.

Here is an example...

   // ADK 1.x code...
   HashMap values;
   SIFDataObject sdo;
   Mappings.Map( values, sdo );
   
   // ADK 2.x equivalent....
   HashMap values;
   SIFDataObject sdo;
   StringMapAdaptor fieldAdaptor = new StringMapAdaptor( values );
   Mappings.Map( fieldAdaptor, sdo );
   

Version:

ADK 1.0

Constructor Summary

Mappings()
Constructs the root-level Mappings container

Mappings(Mappings parent, java.lang.String id)
Constructs a child Mappings object with no filters.

Mappings(Mappings parent, java.lang.String id, java.lang.String sourceIdFilter, java.lang.String zoneIdFilter, java.lang.String sifVersionFilter)
Constructs a child Mappings object with optional filters.

Method Summary

void	addChild(Mappings m) Adds a Mappings child
void	addRules(ObjectMapping om) Add an ObjectMapping definition to this Mappings instance
void	addValueSet(ValueSet vset) Add a ValueSet to this Mappings instance
int	allowsSourceId(java.lang.String sourceId) Determines if this nested Mappings instance allows the specified SourceId.
int	allowsVersion(SIFVersion version) Determines if this nested Mappings instance allows the specified version of SIF
int	allowsZoneId(java.lang.String zoneId) Determines if this nested Mappings instance allows the specified ZoneId.
Mappings	copy(Mappings newParent) Creates a copy of this Mappings object and adds the copy as a child of the specified parent.
Mappings	createChild(java.lang.String id) Create a Mappings child
int	getChildCount() Count the number of Mappings children
Mappings[]	getChildren() Return an array of all Mappings children
java.lang.String	getId() Gets the unique ID of this Mappings instance
Mappings	getMappings(java.lang.String id) Gets the Mappings object with the specified ID.
org.w3c.dom.Node	getNode() Gets the optional DOM Node associated with this Mappings instance.
ObjectMapping	getObjectMapping(java.lang.String objectType, boolean inherit) Gets the ObjectMapping defined for the specified object type from this Mappings instance, optionally including those inherited by its parents.
ObjectMapping[]	getObjectMappings() Gets all ObjectMappings defined for this Mappings instance, including those inherited by its parents.
ObjectMapping[]	getObjectMappings(boolean inherit) Gets all ObjectMappings defined for this Mappings instance, optionally including those inherited by its parents.
Mappings	getParent() Gets the parent Mappings instance
java.lang.String	getProperty(java.lang.String name, java.lang.String defaultValue) Gets a user-defined property.
java.lang.String[]	getPropertyNames() Gets the names of all user-defined properties currently set on this Mappings instance.
Mappings	getRoot() Gets the root Mappings container.
ObjectMapping	getRules(SIFDataObject object, boolean inherit) Return an ObjectMapping definition for a given object type.
ObjectMapping	getRules(java.lang.String objType, boolean inherit) Returns the ObjectMapping for a given object type.
SIFVersion[]	getSIFVersionFilter() Returns the SIFVersion filters in effect for this Mappings instance.
java.lang.String	getSIFVersionFilterString() Returns the SIF Version filters in effect for this Mappings instance as a comma-delimited string.
java.lang.String[]	getSourceIdFilter() Returns the SourceId filters in effect for this Mappings instance.
java.lang.String	getSourceIdFilterString() Returns the SourceId filters in effect for this Mappings instance as a comma-delimited string.
ValueSet	getValueSet(java.lang.String id, boolean inherit) Gets a ValueSet by ID.
ValueSet[]	getValueSets(boolean inherit) Gets all ValueSets for this Mappings instance.
java.lang.String[]	getZoneIdFilter() Returns the ZoneId filters in effect for this Mappings instance.
java.lang.String	getZoneIdFilterString() Returns the Zone ID filters in effect for this Mappings instance as a comma-delimited string.
boolean	hasProperty(java.lang.String name) Determines if a user-defined property is currently set on this Mappings instance.
boolean	isRoot() Determines if this is the root Mappings container.
static void	main(java.lang.String[] args) Displays the Mappings defined by a configuration file Usage: Mappings config.xml [[/zone=zoneId /sifVersion=version /sourceId=sourceId] /v] When the /zone, /sifVersion, or /sourceId parameters are specified, the Mappings.select method is called to select the Mappings object that most closely matches the Zone(s), SIF Version, and SourceId value(s).
void	mapInbound(SIFDataObject dataObject, FieldAdaptor results) Produce a table of field values from a SIF Data Object using an inbound mapping operation.
void	mapInbound(SIFDataObject data, FieldAdaptor results, SIFVersion version) Produce a table of field values from a SIF Data Object using an inbound mapping operation.
void	mapOutbound(FieldAdaptor adaptor, SIFDataObject dataObject) Populate a SIFDataObject from values in the supplied HashMap by evaluating all field rules for the associated SIF Data Object type.
void	mapOutbound(FieldAdaptor adaptor, SIFDataObject dataObject, SIFVersion version) Populate a SIFDataObject from values in the supplied FieldAdaptor.
void	mapOutbound(FieldAdaptor adaptor, SIFDataObject dataObject, ValueBuilder valueBuilder) Populate a SIFDataObject from values in the supplied FieldAdaptor.
void	mapOutbound(FieldAdaptor adaptor, SIFDataObject dataObject, ValueBuilder valueBuilder, SIFVersion version) Populate a SIFDataObject from values in the supplied FieldAdaptor.
void	populate(org.w3c.dom.Document doc, org.w3c.dom.Node parent) Populate the Mappings hierarchy from an XML Document.
void	removeChild(Mappings m) Removes a Mappings child
void	removeRules(ObjectMapping om) Remove an ObjectMapping definition from this Mappings instance
ValueSet	removeValueSet(java.lang.String id) Remove a ValueSet from this Mappings instance.
void	removeValueSet(ValueSet vset) Remove a ValueSet from this Mappings instance.
Mappings	select(java.lang.String zoneId, java.lang.String sourceId, SIFVersion version) Selects the appropriate Mappings object to use for map operations.
MappingsContext	selectInbound(ElementDef elementDef, SIFVersion version, java.lang.String zoneId, java.lang.String sourceId) Selects an appropriate MappingsContext object to use for an inbound map operation.
MappingsContext	selectOutbound(ElementDef elementDef, SIFVersion version, java.lang.String zoneId, java.lang.String sourceId) Selects an appropriate MappingsContext object to use for an outbound map operation.
void	setNode(org.w3c.dom.Node node) Sets the optional DOM Node associated with this Mappings instance.
void	setProperty(java.lang.String name, java.lang.String value) Set a user-defined property.
void	setSIFVersionFilter(java.lang.String filter) Sets a SIFVersion filter on this Mappings object.
void	setSourceIdFilter(java.lang.String filter) Sets a SourceId filter on this Mappings object.
void	setZoneIdFilter(java.lang.String filter) Sets a ZoneId filter on this Mappings object.
org.w3c.dom.Node	toDOM(org.w3c.dom.Document doc) Stores all configuration information from this Mappings instance to the specified DOM document
org.w3c.dom.Node	toDOM(org.w3c.dom.Document doc, boolean renderAsRuntimeMappings) Produces a DOM Node graph of this Mappings object.
java.lang.String	toXML() Returns the Mappings as a string in XML form
java.lang.String	toXML(boolean renderAsRuntimeMappings) Returns the Mappings as a string in XML form.

Methods inherited from class java.lang.Object

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

Constructor Detail

Mappings

public Mappings()

Constructs the root-level Mappings container

Mappings

public Mappings(Mappings parent,
                java.lang.String id)

Constructs a child Mappings object with no filters.

Parameters:

parent - The parent Mappings object

id - A unique string ID for this Mappings object

Mappings

public Mappings(Mappings parent,
                java.lang.String id,
                java.lang.String sourceIdFilter,
                java.lang.String zoneIdFilter,
                java.lang.String sifVersionFilter)

Constructs a child Mappings object with optional filters.

Parameters:

parent - The root Mappings object

id - A unique identifier for this Mappings object

sourceIdFilter - A comma-delimited list of SourceIds or null if no SourceId filter should be applied to this Mappings object

zoneIdFilter - A comma-delimited list of ZoneIds or null if no SourceId filter should be applied to this Mappings object

sifVersionFilter - A comma-delimited list of SIF Versions, in the form "1.0r1", or null if no SIF Version filter should be applied to this Mappings object

Method Detail

copy

public Mappings copy(Mappings newParent)
              throws ADKMappingException

Creates a copy of this Mappings object and adds the copy as a child of the specified parent. Note the root Mappings container cannot be copied. If this method is called on the root an exception is raised.

This method performs a "deep copy", such that a copy is made of each child Mappings, ObjectMapping, FieldMapping, ValueSet, and Property instance.

Parameters:

newParent - The parent Mappings instance

Returns:

A "deep copy" of this root Mappings object

Throws:

ADKMappingException - thrown if this method is not called on the root Mappings container

setNode

public void setNode(org.w3c.dom.Node node)

Sets the optional DOM Node associated with this Mappings instance. The DOM Node is set when a Mappings object is populated from a DOM Document.

Parameters:

node - The DOM Node associated with this Mappings instance

getNode

public org.w3c.dom.Node getNode()

Gets the optional DOM Node associated with this Mappings instance. The DOM Node is set when a Mappings object is populated from a DOM Document.

Returns:

The DOM Node associated with this Mappings instance

getId

public java.lang.String getId()

Gets the unique ID of this Mappings instance

Returns:

The unique ID of this Mappings instance

getParent

public Mappings getParent()

Gets the parent Mappings instance

Returns:

The parent Mappings instance or NULL if this is the top-level Mappings instance

isRoot

public boolean isRoot()

Determines if this is the root Mappings container. Applications may call the select and map methods on the root container only.

Returns:

true if this is the root Mappings container, otherwise false

getRoot

public Mappings getRoot()

Gets the root Mappings container.

Returns:

The root Mappings container instance

addChild

public void addChild(Mappings m)

Adds a Mappings child

Parameters:

m - The child Mappings instance to add to this parent

createChild

public Mappings createChild(java.lang.String id)
                     throws ADKMappingException

Create a Mappings child

Parameters:

id - The ID of the new Mappings instance

Returns:

The newly-created child Mappings instance with the specified ID

Throws:

ADKMappingException - If the child cannot be created

removeChild

public void removeChild(Mappings m)

Removes a Mappings child

Parameters:

m - The child Mappings instance to remove

getChildren

public Mappings[] getChildren()

Return an array of all Mappings children

Returns:

An array of all Mappings children

getChildCount

public int getChildCount()

Count the number of Mappings children

Returns:

The number of Mappings children

setSourceIdFilter

public void setSourceIdFilter(java.lang.String filter)

Sets a SourceId filter on this Mappings object.

Parameters:

filter - A comma-delimited list of SourceIds that define the agents this Mappings object applies to. If the filter includes an asterisk, the Mappings object will have no SourceId filter regardless of whether any other SourceIds are specified in the filter string.

setZoneIdFilter

public void setZoneIdFilter(java.lang.String filter)

Sets a ZoneId filter on this Mappings object.

Parameters:

filter - A comma-delimited list of ZoneIds that define the zones this Mappings object applies to. If the filter includes an asterisk, the Mappings object will have no ZoneId filter regardless of whether any other ZoneIds are specified in the filter string.

setSIFVersionFilter

public void setSIFVersionFilter(java.lang.String filter)

Sets a SIFVersion filter on this Mappings object.

Parameters:

filter - A comma-delimited list of SIFVersion strings, in the form "1.0r1", that define the zones this Mappings object applies to. If the filter includes an asterisk, the Mappings object will have no SIFVersion filter regardless of whether any other SIFVersions are specified in the filter string.

setProperty

public void setProperty(java.lang.String name,
                        java.lang.String value)

Set a user-defined property.

Parameters:

name - The property name

value - The property value

getProperty

public java.lang.String getProperty(java.lang.String name,
                                    java.lang.String defaultValue)

Gets a user-defined property.

Parameters:

name - The property name

defaultValue - The value to return if the property is not defined

Returns:

The value of the property

hasProperty

public boolean hasProperty(java.lang.String name)

Determines if a user-defined property is currently set on this Mappings instance.

Parameters:

name - The property name

Returns:

true if the property is set; otherwise false

getPropertyNames

public java.lang.String[] getPropertyNames()

Gets the names of all user-defined properties currently set on this Mappings instance.

Returns:

An array of property names

populate

public void populate(org.w3c.dom.Document doc,
                     org.w3c.dom.Node parent)
              throws ADKConfigException,
                     ADKMappingException

Populate the Mappings hierarchy from an XML Document.

This method can only be called on the root Mappings object or an exception is raised. It reads all <mapping> elements from the Document to build the Mappings hierarchy.

Parameters:

doc - A DOM Document that defines one or more <mappings> elements from which to populate the Mappings hierarchy. Note the root Mappings object is a virtual object and therefore not represented by a Node in this Document.

parent - A DOM Node in the source document that should be considered the parent Node of this Mappings object. This parameter is required because the root Mappings object is a virtual object that is not represented in the DOM graph, so some other node usually serves as its parent (e.g. the <agent> node in an AgentConfig configuration file)

Throws:

ADKConfigException - is thrown if a required element or attribute is missing or has an invalid value

ADKMappingException - is thrown if this method is called on a Mappings instance other than the root Mappings container

getMappings

public Mappings getMappings(java.lang.String id)
                     throws ADKMappingException

Gets the Mappings object with the specified ID.

Unlike the select methods, getMappings should be called when the agent knows the specific Mappings object it is going to use to perform a mapping operation. Conversely, the select methods select the most appropriate Mappings object based on the ZoneId, SourceId, and SIFVersion values passed to those methods.

Parameters:

id - The unique string identifier of the Mappings object to return.

Returns:

The Mappings instance with the specified ID, or null if no match was found.

Throws:

ADKMappingException - thrown if this method is not called on the root Mappings container

select

public Mappings select(java.lang.String zoneId,
                       java.lang.String sourceId,
                       SIFVersion version)
                throws ADKMappingException

Selects the appropriate Mappings object to use for map operations. Call this method on the root Mappings object to obtain a Mappings instance, then call its map method to perform a mapping operation.

The selection process is as follows:

• All children of this Mappings are evaluated as a group in a flat list. The group is ordered by "restrictiveness". The more filters defined for a Mappings the more restrictive it is considered. Thus, a Mappings that defines a ZoneId, SourceId, and SIFVersion filter will be evaluated before a less-restrictive Mappings that defines only a SourceId filter. Because children inherit the filters of their parent, a child can never be less restrictive than its parent. Two or more Mappings with equal restrictiveness are evaluated in natural order, so care should be taken to not organize child Mappings objects with equal filters or the first one present will always be selected.
  
  
• The ordered Mappings are evaluated sequentially. For each, the ZoneId, SourceId, and Version are compared against any filters in effect for the Mappings instance. Any Mappings that does not pass the criteria is eliminated from the list of candidates.
  
  
• If no child Mappings pass the selection process, the Mappings on which this method is called is returned (i.e. self is returned) This ensures that this method always returns a non-null Mappings instance to the caller.
  
  

Parameters:

zoneId - Restricts the selection of a Mappings object to only those that allow this ZoneId. This parameter may be null.

sourceId - Restricts the selection of a Mappings object to only those that allow this SourceId. This parameter may be null.

version - Restricts the selection of a Mappings object to only those that allow this version of SIF. This parameter may be null.

Returns:

The first Mappings child instance that matches the criteria or null if no match was found

Throws:

ADKMappingException - If this method is called on Mappings instance other than those directly under the Root instance

selectInbound

public MappingsContext selectInbound(ElementDef elementDef,
                                     SIFVersion version,
                                     java.lang.String zoneId,
                                     java.lang.String sourceId)
                              throws ADKMappingException

Selects an appropriate MappingsContext object to use for an inbound map operation. Call this method on the root Mappings object to obtain a MappingsContext instance, then call its map method to perform an inbound mapping operation.

Parameters:

elementDef - The ElementDef of the Element being mapped to

version - The SIFVersion to use when evaluating mappings XPaths.

zoneId - The ID of the zone that this mappings operation is being performed on

sourceId - The Source ID of the destination agent that this mappings is being performed for

Returns:

a MappingsContext that can be used for evaluating mappings

Throws:

ADKMappingException

selectOutbound

public MappingsContext selectOutbound(ElementDef elementDef,
                                      SIFVersion version,
                                      java.lang.String zoneId,
                                      java.lang.String sourceId)
                               throws ADKMappingException

Selects an appropriate MappingsContext object to use for an outbound map operation. Call this method on the root Mappings object to obtain a MappingsContext instance, then call its map method to perform an outbound mapping operation.

Parameters:

elementDef - The ElementDef of the Element being mapped to

version - The SIFVersion to use when evaluating mappings XPaths.

zoneId - The ID of the zone that this mappings operation is being performed on

sourceId - The Source ID of the destination agent that this mappings is being performed for

Returns:

a MappingsContext that can be used for evaluating mappings

Throws:

ADKMappingException

mapInbound

public void mapInbound(SIFDataObject dataObject,
                       FieldAdaptor results)
                throws ADKMappingException

Produce a table of field values from a SIF Data Object using an inbound mapping operation.

This map method populates the supplied data adaptor with element or attribute values from the SIFDataObject by evaluating all field rules defined by this Mappings object for the associated SIF Data Object type.

This method is intended to obtain element and attribute values from a SIFDataObject consumed by the agent when processing SIF Events or SIF Responses. In contrast, the other form of the map method is intended to populate a new SIFDataObject instance when an agent is publishing objects to a zone.

Parameters:

dataObject - The SIFDataObject from which to retrieve element and attribute values from when performing the mapping operation.

results - A FieldAdaptor to receive the results of the mapping,

Throws:

ADKMappingException - thrown if an error occurs while evaluating a field rule

mapInbound

public void mapInbound(SIFDataObject data,
                       FieldAdaptor results,
                       SIFVersion version)
                throws ADKMappingException

Produce a table of field values from a SIF Data Object using an inbound mapping operation.

This form of the map method allows the client to specify whether it is performing an inbound or outbound mapping operation. Currently, the direction flag is used to invoke automatic ValueSet translations on fields that have a ValueSet attribute.

Parameters:

data - The SIFDataObject from which to retrieve element and attribute values from when performing the mapping operation.

results - A FieldAdaptor instance that stores fields as the result of the mapping operation.

version - The SIFVersion associated with the mapping operation. For inbound SIF_Event and SIF_Response messages, this value should be obtained by calling getSIFVersion on the SIFMessageInfo parameter passed to the message handler. For inbound SIF_Request messages, it should be obtained by calling the SIFMessageInfo.getSIFRequestVersion method. For outbound messages, this value should be obtained by calling ADK.getSIFVersion to get the version of SIF the class framework was initialized with. Note when this parameter is null, no SIF Version filtering will be applied to field mapping rules.

Throws:

ADKMappingException - thrown if an error occurs while evaluating a field rule

Since:

ADK 1.5

mapOutbound

public void mapOutbound(FieldAdaptor adaptor,
                        SIFDataObject dataObject)
                 throws ADKMappingException

Populate a SIFDataObject from values in the supplied HashMap by evaluating all field rules for the associated SIF Data Object type. For each key in the FieldAdaptor, the corresponding field rule is evaluated to assign the FieldAdaptor value to the appropriate element or attribute in the SIFDataObject. If a field is not represented in the FieldAdaptor, its associated rule will not be evaluated.

This method is intended to populate a new SIFDataObject instance when an agent is publishing objects to a zone. The other form of the map method is intended to obtain element and attribute values from a SIFDataObject consumed by the agent when processing SIF Events or SIF Responses.

To use this method,

1. Create a FieldAdaptor and populate it with all known field values. The key of each entry must be the local application-defined name of the field -- the same field name used in field rules -- and the value is the string value to assign to the corresponding element or attribute in the SIFDataObject when a field rule matches.
2. Create a SIFDataObject instance of the appropriate type (e.g. a com.edustructures.sifworks.student.StudentPersonal instance if the mapping will be applied to an incoming <StudentPersonal> message).
3. Call this map method to apply all field values in the FieldAdaptor to corresponding elements and/or attributes in the SIFDataObject. The method first looks up the ObjectMapping instance corresponding to the SIF Data Object type. If no ObjectMapping has been defined for the object type, no action is taken and the method returns successfully without exception. Otherwise, all field rules defined by the ObjectMapping are evaluated in order.

Parameters:

adaptor - A FieldAdaptor instance which returns field values used to populate individual elements within the supplied SIFDataObject.

dataObject - The SIFDataObject to assign field values to

Throws:

ADKMappingException - thrown if an error occurs while evaluating a field rule

mapOutbound

public void mapOutbound(FieldAdaptor adaptor,
                        SIFDataObject dataObject,
                        ValueBuilder valueBuilder)
                 throws ADKMappingException

Populate a SIFDataObject from values in the supplied FieldAdaptor.

This form of the map method that accepts a custom ValueBuilder implementation to evaluate value expressions in XPath-like query strings. The map method uses the DefaultValueBuilder class as its built-in implementation, but you can supply your own by calling this method instead.

Parameters:

adaptor - A FieldAdaptor instance which returns field values used to populate individual elements within the supplied SIFDataObject.

dataObject - The SIFDataObject to assign field values to

valueBuilder - A custom ValueBuilder implementation to evaluate value expressions in XPath-like query strings

Throws:

ADKMappingException - thrown if an error occurs while evaluating a field rule

mapOutbound

public void mapOutbound(FieldAdaptor adaptor,
                        SIFDataObject dataObject,
                        SIFVersion version)
                 throws ADKMappingException

Populate a SIFDataObject from values in the supplied FieldAdaptor.

This form of the map method allows the client to specify the SIFVersion that is in effect for this mapping operation

Parameters:

adaptor - A FieldAdaptor instance which returns field values used to populate individual elements within the supplied SIFDataObject.

dataObject - The SIFDataObject to assign field values to

version - The SIFVersion that should be used when evaluating this mappings operation. The SIFVersion influences the XPaths that are used to set elements in the data object

Throws:

ADKMappingException

mapOutbound

public void mapOutbound(FieldAdaptor adaptor,
                        SIFDataObject dataObject,
                        ValueBuilder valueBuilder,
                        SIFVersion version)
                 throws ADKMappingException

Populate a SIFDataObject from values in the supplied FieldAdaptor.

This form of the map method allows the caller to specify whether it is performing an inbound or outbound mapping operation, as well as the version of SIF associated with the SIF Data Object that's being mapped. These values are used to filter field mapping rules. The direction flag is also used to invoke automatic ValueSet translations on fields that have a ValueSet attribute.

Parameters:

adaptor - A FieldAdaptor instance which returns field values used to populate individual elements within the supplied SIFDataObject.

dataObject - The SIFDataObject to assign field values to

valueBuilder - A custom ValueBuilder implementation to evaluate value expressions in XPath-like query strings

version - The SIFVersion associated with the mapping operation. For inbound SIF_Event and SIF_Response messages, this value should be obtained by calling getSIFVersion on the SIFMessageInfo parameter passed to the message handler. For inbound SIF_Request messages, it should be obtained by calling the SIFMessageInfo.getSIFRequestVersion method. For outbound messages, this value should be obtained by calling ADK.getSIFVersion to get the version of SIF the class framework was initialized with. Note when this parameter is null, no SIF Version filtering will be applied to field mapping rules.

Throws:

ADKMappingException - thrown if an error occurs while evaluating a field rule

Since:

ADK 1.5

getSourceIdFilter

public java.lang.String[] getSourceIdFilter()

Returns the SourceId filters in effect for this Mappings instance. A Mappings instances always inherits the filters of its ancestry.

Returns:

An array of SourceIds or null if this Mappings object applies to all SIF Agents

See Also:

setSourceIdFilter(java.lang.String)

getSourceIdFilterString

public java.lang.String getSourceIdFilterString()

Returns the SourceId filters in effect for this Mappings instance as a comma-delimited string.

Returns:

A comma-delimited string of the SourceId in the filter

getZoneIdFilterString

public java.lang.String getZoneIdFilterString()

Returns the Zone ID filters in effect for this Mappings instance as a comma-delimited string.

Returns:

A comma-delimited string of the SourceId in the filter

getSIFVersionFilterString

public java.lang.String getSIFVersionFilterString()

Returns the SIF Version filters in effect for this Mappings instance as a comma-delimited string.

Returns:

A comma-delimited string of the SourceId in the filter

getZoneIdFilter

public java.lang.String[] getZoneIdFilter()

Returns the ZoneId filters in effect for this Mappings instance. A Mappings instances always inherits the filters of its ancestry.

Returns:

An array of ZoneIds or null if this Mappings object applies to all zones

See Also:

setZoneIdFilter(java.lang.String)

getSIFVersionFilter

public SIFVersion[] getSIFVersionFilter()

Returns the SIFVersion filters in effect for this Mappings instance. A Mappings instances always inherits the filters of its ancestry.

Returns:

An array of SIFVersion objects or null if this Mappings object applies to all versions of SIF

See Also:

setSIFVersionFilter(java.lang.String)

allowsSourceId

public int allowsSourceId(java.lang.String sourceId)

Determines if this nested Mappings instance allows the specified SourceId.

This method is only called on nested children of a Mappings object, never on a top-level Mappings object because top-level parents always allow all ZoneIds, SourceIds, and SIF Versions.

Parameters:

sourceId - An agent's SourceId

Returns:

true if the SourceId is permitted by the SourceId filter in effect and can therefore be considered for selection by the select method; false if the SourceId is not included in the SourceId filter and should therefore not be considered for selection

allowsZoneId

public int allowsZoneId(java.lang.String zoneId)

Determines if this nested Mappings instance allows the specified ZoneId.

This method is only called on nested children of a Mappings object, never on a top-level Mappings object because top-level parents always allow all ZoneIds, SourceIds, and SIF Versions.

Parameters:

zoneId - A ZoneId

Returns:

true if the ZoneId is permitted by the ZoneId filter in effect and can therefore be considered for selection by the select method; false if the ZoneId is not included in the ZoneId filter and should therefore not be considered for selection

allowsVersion

public int allowsVersion(SIFVersion version)

Determines if this nested Mappings instance allows the specified version of SIF

This method is only called on nested children of a Mappings object, never on a top-level Mappings object because top-level parents always allow all ZoneIds, SourceIds, and SIF Versions.

Parameters:

version - A SIFVersion instance describing a version of SIF

Returns:

true if the version is permitted by the SIFVersion filter in effect and can therefore be considered for selection by the select method; false if the version is not included in the SIFVersion filter and should therefore not be considered for selection

addValueSet

public void addValueSet(ValueSet vset)

Add a ValueSet to this Mappings instance

Parameters:

vset - The ValueSet instance to add to this Mappings instance

removeValueSet

public void removeValueSet(ValueSet vset)

Remove a ValueSet from this Mappings instance.

If the ValueSet has a DOM Node attached to it, it is removed from its parent Node and dereferenced.

Parameters:

vset - The ValueSet to remove

removeValueSet

public ValueSet removeValueSet(java.lang.String id)

Remove a ValueSet from this Mappings instance.

If a ValueSet with the specified ID is found, it is removed from this Mappings and returned; otherwise no action is taken. If the ValueSet has a DOM Node attached to it, it is removed from its parent Node and dereferenced.

Parameters:

id - The ID of the ValueSet to remove

Returns:

The ValueSet that was removed from this Mappings instance or NULL

getValueSet

public ValueSet getValueSet(java.lang.String id,
                            boolean inherit)

Gets a ValueSet by ID.

Parameters:

id - The unique ID of the ValueSet

inherit - true to inherit the ValueSet from the Mappings ancestry if not found as a child of this Mappings object; false to return null if no ValueSet is found

Returns:

The ValueSet that was found or Null

getValueSets

public ValueSet[] getValueSets(boolean inherit)

Gets all ValueSets for this Mappings instance.

Parameters:

inherit - true to include ValueSets from the Mappings ancestry in the returned array, false to include only ValueSets defined by this Mappings object

Returns:

The ValueSets that are defined by this Mappings instance

addRules

public void addRules(ObjectMapping om)

Add an ObjectMapping definition to this Mappings instance

Parameters:

om - The ObjectMapping to add to this Mappings instance

removeRules

public void removeRules(ObjectMapping om)

Remove an ObjectMapping definition from this Mappings instance

Parameters:

om - The ObjectMapping definition to remove

getObjectMappings

public ObjectMapping[] getObjectMappings()

Gets all ObjectMappings defined for this Mappings instance, including those inherited by its parents.

Returns:

An array of all ObjectMappings

getObjectMappings

public ObjectMapping[] getObjectMappings(boolean inherit)

Gets all ObjectMappings defined for this Mappings instance, optionally including those inherited by its parents.

Parameters:

inherit - True if ObjectMappings defined by parents should be included as well.

Returns:

An array of all ObjectMappings

getObjectMapping

public ObjectMapping getObjectMapping(java.lang.String objectType,
                                      boolean inherit)

Gets the ObjectMapping defined for the specified object type from this Mappings instance, optionally including those inherited by its parents.

Parameters:

objectType - The object type, such as "StudentPersoanal

inherit - True if an ObjectMapping from the parent Mappings instance can be returned

Returns:

An ObjectMapping instance

getRules

public ObjectMapping getRules(SIFDataObject object,
                              boolean inherit)

Return an ObjectMapping definition for a given object type.

Parameters:

object - A SIF Data Object (e.g. "StudentPersonal")

inherit - True to inherit the ObjectMapping from the ancestry if this Mappings instance does not define it

Returns:

an ObjectMapping definition for the given object type.

getRules

public ObjectMapping getRules(java.lang.String objType,
                              boolean inherit)

Returns the ObjectMapping for a given object type.

Parameters:

objType - The name of a SIF Data Object (e.g. "StudentPersonal")

inherit - True to inherit the ObjectMapping from the ancestry if this Mappings instance does not define it

Returns:

The ObjectMappints instance for the given object type

toDOM

public org.w3c.dom.Node toDOM(org.w3c.dom.Document doc)
                       throws org.xml.sax.SAXException

Stores all configuration information from this Mappings instance to the specified DOM document

Parameters:

doc -

Returns:

The root DOM node created by this method

Throws:

org.xml.sax.SAXException

toDOM

public org.w3c.dom.Node toDOM(org.w3c.dom.Document doc,
                              boolean renderAsRuntimeMappings)
                       throws org.xml.sax.SAXException

Produces a DOM Node graph of this Mappings object.

NOTE: This method creates the node but does not append it to the document that is passed in. It is the responsibility of the caller to add the node where appropriate

Parameters:

doc - The parent document

renderAsRuntimeMappings - true to inherit object and field rules so this Mappings is rendered with dynamic content as it would be evaluated at runtime. This can be useful for diagnostics (i.e. displaying the current state of a Mappings object), but not for rendering to a configuration file.

Returns:

A DOM Node graph representing this Mappings object

Throws:

org.xml.sax.SAXException

toXML

public java.lang.String toXML()

Returns the Mappings as a string in XML form

Returns:

A string representing the XML form of this Mappings instance

toXML

public java.lang.String toXML(boolean renderAsRuntimeMappings)

Returns the Mappings as a string in XML form.

Parameters:

renderAsRuntimeMappings - true to inherit object and field rules so this Mappings is rendered with dynamic content as it would be evaluated at runtime. This can be useful for diagnostics (i.e. displaying the current state of a Mappings object), but not for rendering to a configuration file.

Returns:

A string representing the XML form of this Mappings instance

main

public static void main(java.lang.String[] args)

Displays the Mappings defined by a configuration file Usage: Mappings config.xml [[/zone=zoneId /sifVersion=version /sourceId=sourceId] /v] When the /zone, /sifVersion, or /sourceId parameters are specified, the Mappings.select method is called to select the Mappings object that most closely matches the Zone(s), SIF Version, and SourceId value(s). All three options must be specified. When these options are not present, all Mappings are written to System.out When the /v option is specified, the configuration file is parsed with a validating parser.

Parameters:

args - The command-line arguments, as documented, used by this method