[This is preliminary documentation and is subject to change.]
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.
| C# | Visual Basic | Visual C++ |
public virtual Mappings Select( string zoneId, string sourceId, SifVersion version )
Public Overridable Function Select ( _ zoneId As String, _ sourceId As String, _ version As SifVersion _ ) As Mappings
public: virtual Mappings^ Select ( String^ zoneId, String^ sourceId, SifVersion^ version )
- zoneId (String)
- Restricts the selection of a Mappings object to only those that allow this ZoneId. This parameter may be null.
- sourceId (String)
- Restricts the selection of a Mappings object to only those that allow this SourceId. This parameter may be null.
- version (SifVersion)
- Restricts the selection of a Mappings object to only those that allow this version of SIF. This parameter may be null.
The first Mappings child instance that matches the criteria or
null if no match was found