Feature Chaining¶

Create a mapping file for every complex type¶

We need one mapping file per complex type that is going to be nested, including non features, e.g. gsml:CompositionPart.

Non-feature types that cannot be individually accessed (eg. CompositionPart as a Data Type) can still be mapped separately for its reusability. For this case, the containing feature type has to include these types in its mapping file. The include tag should contain the nested mapping file path relative to the location of the containing type mapping file. In GeologicUnit_MappingFile.xml:

<includedTypes>
    <Include>CGITermValue_MappingFile.xml</Include>
    <Include>CompositionPart_MappingFile.xml</Include>
</includedTypes>

Feature types that can be individually accessed don’t need to be explicitly included in the mapping file, as they would be configured for GeoServer to find. Such types would have their mapping file associated with a corresponding datastore.xml file, which means that it can be found from the data store registry. In other words, if the type is associated with a datastore.xml file, it doesn’t need to be explicitly included if referred from another mapping file.

Example:

For this output: MappedFeature_Output.xml, here are the mapping files:

• MappedFeature_MappingFile.xml

• GeologicUnit_MappingFile.xml

• CompositionPart_MappingFile.xml

• GeologicEvent_MappingFile.xml

• CGITermValue_MappingFile.xml

GeologicUnit type

You can see within GeologicUnit features, both gml:composition (CompositionPart type) and gsml:geologicHistory (GeologicEvent type) are multi-valued properties. It shows how multiple cases of multi-valued properties can be configured within a single Feature Type. This also proves that you can “chain” non-feature type, as CompositionPart is a Data Type.

GeologicEvent type

Both gsml:eventEnvironment (CGI_TermValue type) and gsml:eventProcess (also of CGI_TermValue type) are multi-valued properties. This also shows that “chaining” can be done on many levels, as GeologicEvent is nested inside GeologicUnit. Note that gsml:eventAge properties are configured as inline attributes, as there can only be one event age per geologic event, thus eliminating the need for feature chaining.

Configure nesting on the nested feature type¶

In the nested feature type, make sure we have a field that can be referenced by the parent feature. If there isn’t any existing field that can be referred to, the system field FEATURE_LINK can be mapped to hold the foreign key value. This is a multi-valued field, so more than one instances can be mapped in the same feature type, for features that can be nested by different parent types. Since this field doesn’t exist in the schema, it wouldn’t appear in the output document.

In the source expression tag:

• OCQL: the value of this should correspond to the OCQL part of the parent feature

Example One: Using FEATURE_LINK in CGI TermValue type, which is referred by GeologicEvent as gsml:eventProcess and gsml:eventEnvironment.

In GeologicEvent (the container feature) mapping:

<AttributeMapping>
      <targetAttribute>gsml:eventEnvironment</targetAttribute>
      <sourceExpression>
              <OCQL>id</OCQL>
              <linkElement>gsml:CGI_TermValue</linkElement>
              <linkField>FEATURE_LINK[1]</linkField>
      </sourceExpression>
      <isMultiple>true</isMultiple>
</AttributeMapping>
<AttributeMapping>
      <targetAttribute>gsml:eventProcess</targetAttribute>
      <sourceExpression>
              <OCQL>id</OCQL>
              <linkElement>gsml:CGI_TermValue</linkElement>
              <linkField>FEATURE_LINK[2]</linkField>
      </sourceExpression>
      <isMultiple>true</isMultiple>
</AttributeMapping>

In CGI_TermValue (the nested feature) mapping:

<AttributeMapping>
  <!-- FEATURE_LINK[1] is referred by geologic event as environment -->
  <targetAttribute>FEATURE_LINK[1]</targetAttribute>
  <sourceExpression>
      <OCQL>ENVIRONMENT_OWNER</OCQL>
  </sourceExpression>
</AttributeMapping>
<AttributeMapping>
  <!-- FEATURE_LINK[2] is referred by geologic event as process -->
  <targetAttribute>FEATURE_LINK[2]</targetAttribute>
  <sourceExpression><
      <OCQL>PROCESS_OWNER</OCQL>
  </sourceExpression>
</AttributeMapping>

The ENVIRONMENT_OWNER column in CGI_TermValue view corresponds to the ID column in GeologicEvent view.

Geologic Event property file:

CGI Term Value property file:

The system field FEATURE_LINK doesn’t get encoded in the output:

<gsml:GeologicEvent>
  <gml:name codeSpace="urn:cgi:classifierScheme:GSV:GeologicalUnitId">gu.25699</gml:name>
  <gsml:eventAge>
    <gsml:CGI_TermRange>
       <gsml:lower>
          <gsml:CGI_TermValue>
            <gsml:value codeSpace="urn:cgi:classifierScheme:ICS:StratChart:2008">Oligocene</gsml:value>
          </gsml:CGI_TermValue>
       </gsml:lower>
       <gsml:upper>
          <gsml:CGI_TermValue>
            <gsml:value codeSpace="urn:cgi:classifierScheme:ICS:StratChart:2008">Paleocene</gsml:value>
          </gsml:CGI_TermValue>
       </gsml:upper>
    </gsml:CGI_TermRange>
  </gsml:eventAge>
  <gsml:eventEnvironment>
    <gsml:CGI_TermValue>
       <gsml:value>fluvial</gsml:value>
    </gsml:CGI_TermValue>
  </gsml:eventEnvironment>
  <gsml:eventProcess>
    <gsml:CGI_TermValue>
       <gsml:value>channelled stream flow</gsml:value>
    </gsml:CGI_TermValue>
  </gsml:eventProcess>

Example Two: Using existing field (gml:name) to hold the foreign key, see MappedFeature_MappingFile.xml:

gsml:specification links to gml:name in GeologicUnit:

<AttributeMapping>
  <targetAttribute>gsml:specification</targetAttribute>
  <sourceExpression>
    <OCQL>GEOLOGIC_UNIT_ID</OCQL>
    <linkElement>gsml:GeologicUnit</linkElement>
    <linkField>gml:name[3]</linkField>
  </sourceExpression>
</AttributeMapping>

In GeologicUnit_MappingFile.xml:

GeologicUnit has 3 gml:name properties in the mapping file, so each has a code space to clarify them:

<AttributeMapping>
  <targetAttribute>gml:name[1]</targetAttribute>
  <sourceExpression>
    <OCQL>ABBREVIATION</OCQL>
  </sourceExpression>
  <ClientProperty>
    <name>codeSpace</name>
    <value>'urn:cgi:classifierScheme:GSV:GeologicalUnitCode'</value>
  </ClientProperty>
</AttributeMapping>
<AttributeMapping>
  <targetAttribute>gml:name[2]</targetAttribute>
  <sourceExpression>
    <OCQL>NAME</OCQL>
  </sourceExpression>
  <ClientProperty>
    <name>codeSpace</name>
    <value>'urn:cgi:classifierScheme:GSV:GeologicalUnitName'</value>
  </ClientProperty>
</AttributeMapping>
<AttributeMapping>
  <targetAttribute>gml:name[3]</targetAttribute>
  <sourceExpression>
    <OCQL>id</OCQL>
  </sourceExpression>
  <ClientProperty>
    <name>codeSpace</name>
    <value>'urn:cgi:classifierScheme:GSV:MappedFeatureReference'</value>
  </ClientProperty>
</AttributeMapping>

The output with multiple gml:name properties and their code spaces:

<gsml:specification>
  <gsml:GeologicUnit gml:id="gu.25678">
      <gml:description>Olivine basalt, tuff, microgabbro, minor sedimentary rocks</gml:description>
      <gml:name codeSpace="urn:cgi:classifierScheme:GSV:GeologicalUnitCode">-Py</gml:name>
      <gml:name codeSpace="urn:cgi:classifierScheme:GSV:GeologicalUnitName">Yaugher Volcanic Group</gml:name>
      <gml:name codeSpace="urn:cgi:classifierScheme:GSV:MappedFeatureReference">gu.25678</gml:name>

If this is the “one” side of a one-to-many or many-to-one database relationship, we can use the feature id as the source expression field, as you can see in above examples. See one_to_many_relationship.JPG as an illustration.

If we have a many-to-many relationship, we have to use one denormalized view for either side of the nesting. This means we can either use the feature id as the referenced field, or assign a column to serve this purpose. See many_to_many_relationship.JPG as an illustration.

Test this configuration by running a getFeature request for the nested feature type on its own.

Configure nesting on the “containing” feature type¶

When nesting another complex type, you need to specify in your source expression:

• OCQL: OGC’s Common Query Language expression of the data store column

• linkElement:

  • the nested element name, which is normally the targetElement or mappingName of the corresponding type.

  • on some cases, it has to be an OCQL function (see Polymorphism)

• linkField: the indexed XPath attribute on the nested element that OCQL corresponds to

Example: Nesting composition part in geologic unit feature.

In Geologic Unit mapping file:

<AttributeMapping>
    <targetAttribute>gsml:composition</targetAttribute>
    <sourceExpression>
            <OCQL>id</OCQL>
            <linkElement>gsml:CompositionPart</linkElement>
            <linkField>FEATURE_LINK</linkField>
    </sourceExpression>
    <isMultiple>true</isMultiple>
</AttributeMapping>

• OCQL: id is the geologic unit id

• linkElement: links to gsml:CompositionPart type

• linkField: FEATURE_LINK, the linking field mapped in gsml:CompositionPart type that also stores the geologic unit id. If there are more than one of these attributes in the nested feature type, make sure the index is included, e.g. FEATURE_LINK[2].

Geologic Unit property file:

Composition Part property file:

Run the getFeature request to test this configuration. Check that the nested features returned in Step 2 are appropriately lined inside the containing features. If they are not there, or exceptions are thrown, scroll down and read the “Trouble Shooting” section.