Flattener

Contents

Introduction

Properties of a feature type (from an Application Schema model) often make use of non-simple types, i.e. other feature types, object types, data types, and union types. The resulting structures can become quite complex, which can make it difficult to exchange data via or convert data into formats that do not support such complexity (for example Shapefiles).

The Flattener can be used to simplify a complex Application Schema model, up to the point where all complex data structures have been resolved to feature type properties whose type is either a simple type (like Integer, Boolean or CharacterString), a code list, or an enumeration.

NOTE: the flattening process modifies the structure of the model. Flattening rules often modify the name of model elements (e.g. classes and properties) to preserve the model semantics if applicable (e.g. that a flattened property is the n-th element of a property with unlimited maximum multiplicity, or that a flattened property represents one choice of a union). The flattening rules thereby also modify a code value that may exist for the model element. A code value represents an abbreviation of a model element name. For example, the code value of a class named ‘ConstructionZone’ could be ‘CZ’. Per default, the Flattener uses the alias of a model element to look up and store the code value. Via the parameter ‘codeByTaggedValue’ the Flattener can be instructed to use a specific tagged value for managing the code value.

WARNING – The Flattener currently does not support handling of profile information (see Profiler transformation). Thus profiling should be applied before flattening. The reverse order may lead to unexpected results.

The following section specifies the configuration of a Flattener (including applicable transformation rules and the according behavior).

Configuration

The following sections specifiy the configuration options for a Flattener.

Class

The class for the Flattener implementation is de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener.

Rules

The following optional rules are supported by the Flattener.

rule-trf-all-removeType

Behavior

Removes the types identified by the removeType parameter from the application schema in the model. This includes all properties (attributes or associations / association roles) that are of this type as well as any inheritance relationships (the type being a superclass or subclass of another class).

NOTE: this rule is only applicable for types defined in (one of) the application schema(s) selected for processing.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
removeType  Required (if the parameter is omitted, a warning will be logged and the rule not executed)

rule-trf-cls-remove-inheritance-relationship

Behavior

Removes inheritance relationships of classes to the classes whose name matches the regular expression provided by parameter “removeInheritanceIncludeRegex”. then all supertype relationships to this class will be removed in the model. In other words: a class whose name matches the regular expression is disconnected from its subtypes NOTE: Applies to classes in the whole model!

Parameters

Parameter Name Required / Optional (for Execution of Rule)
removeInheritanceIncludeRegex  Required (if the parameter is omitted, a warning will be logged and the rule not executed)

Map Entries

none

rule-trf-cls-dissolve-mixins

Behavior

Copies the attributes of a mixin to its subtypes and removes the mixin from the model, thus dissolving the mixin.

NOTE: does NOT copy associations!

Parameters

none

Map Entries

none

rule-trf-prop-removeObjectToFeatureTypeNavigability

Behavior

If the name of an object type matches the regular expression given via the configuration parameter removeObjectToFeatureNavRegex, then each navigable property whose value type is a feature type will be removed from the object type. If the property is an attribute it will be removed from the model. If the property is an association role and the whole association is no longer navigable then the association will be removed.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
removeObjectToFeatureNavRegex  Required (if the parameter is omitted, an error will be logged and the rule not executed)
includeObjectToObjectNavigability  Optional

Map Entries

none

rule-trf-all-removeFeatureTypeRelationships

Behavior

Removes all navigable properties from a feature type if the value type of the property also is a feature type.

Parameters

none

Map Entries

none

rule-trf-prop-removeNavigabilityBasedOnIsFlatTarget

Behavior

If a navigable association role has isFlatTarget tagged value set to true then it will be removed from the model. More specifically:

  • If the association is bi-directional, the association role will be set to be non-navigable.
  • If the association is uni-directional (and the role is the only navigable end), the whole association will be removed.

This will ensure that the contents of the class (A) that owns the property (so the class on the other end of the association) can be copied into the value type (B) of the property but not the other way round – if (A) was flattened by rule-trf-prop-flatten-types. Setting the isFlatTarget tagged value is especially useful for managing how complex type flattening is applied in case of a bi-directional association.

NOTE: if the isFlatTarget setting(s) on the association leads to the removal of the whole association (because both ends have been removed / are no longer navigable) a warning will be logged.

Parameters

none

Map Entries

none

rule-trf-all-flatten-constraints

Behavior

Processes all class and property constraints: the Flattener keeps only those that have a textual comment embedded in “/*” and “*/” and reduces these constraints to this textual comment.

The Flattener also ensures that duplicates of a class or property constraint, i.e. any constraint that has the same text value as another constraint, are removed.

NOTE: only processes constraints belonging to classes and properties of the application schema(s) selected for processing.

Parameters

none

Map Entries

none

rule-trf-prop-flatten-codelists

Behavior

Switches the type of each property that is of a <<codeList>> type to CharacterString. Removes the code list classes from the model.

NOTE: only applies to properties of the application schema(s) selected for processing.

Parameters

none

Map Entries

none

rule-trf-prop-flatten-ONINAs

Behavior

Switches the type of all properties with type of name XxxReason to the type of the “value” property (that belongs to XxxReason; most often it has the name “Xxx”). If the type of the “value” property is an enumeration, the Flattener adds ONINA codes (other, noInformation, notApplicable) to it. If the model makes use of the “BooleanReason” type, the Flattener adds a new enumeration BooleanWithONINA (enums: false, true, noInformation, notApplicable, other) to the model (in the package where the BooleanReason resides) and switches all properties in the application schema with type BooleanReason to use the type BooleanWithONINA.The Flattener also removes all XxxReason <<union>> classes.

NOTE: current behavior assumes that properties of type XxxReason are attributes, not association roles.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
codeByTaggedValue  Optional

Map Entries

none

rule-trf-prop-optionality

Behavior

Sets all model properties that are of a type identified by the enforceOptionality parameter to optional.

NOTE: only applies to properties of the application schema(s) selected for processing.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
enforceOptionality  Required (if the parameter is omitted, a warning will be logged and the rule not executed)

Map Entries

none

rule-trf-cls-flatten-inheritance

Behavior

At first, the Flattener identifies all supertypes contained in the application schema(s) selected for processing.

NOTE: the selection can be influenced via the parameter flattenInheritanceIncludeRegex. Only those supertypes where the name of the supertype itself or of one of its own supertypes (in the complete supertype hierarchy – but only searching within schema(s) selected for processing) matches the regular expression provided by this parameter will be selected for flattening. This can be useful if only certain inheritance hierarchies shall be flattened by this rule.

Then all classes are identified that aren’t supertypes themselves but inherit from one of the previously selected supertypes or whose supertypes don’t belong to the application schema(s) selected for processing. This is required to correctly dissolve inheritance relationships at the end of this rule.

NOTE: restricting inheritance flattening to classes that are contained in the application schema(s) selected for processing can lead to subtypes not having all the properties that they have (through inheritance) in the original model (due to supertypes contained in schema(s) that were not selected for processing).

A union class is created for each of the selected supertypes (in the package of that supertype). It represents a choice between the supertype and its direct and indirect subtypes. Abstract types as well as mixins are ignored, though – resulting in a choice between instantiable types. The value type of each property whose value type is one of the selected supertypes is switched to the according union (unless the property is part of the union itself).

The properties of selected supertypes are then recursively copied to their subtypes, thereby retaining relevant information (property name, type, cardinality, property tagged values etc).Note:

  • In case of an overloaded property (i.e. both supertype and subtype have a property with the same name, but the subtype overrides it with a different value type) the value type defined by the subtype is used.
  • Dependencies are currently not copied.
  • OCL constraints do not need to be copied because ShapeChange already establishes constraints from a superclass in its subclasses while loading the input model.

Associations to, from, and between supertypes to which inheritance flattening applies are copied. To prevent ambiguities, copies of association roles whose value type was a supertype to which inheritance flattening applied receive the name of their new value type as suffix.

Finally, the Flattener removes all Xxx classes that 1) have subclasses and 2) are abstract and/or mixins from the model, and also removes all generalization dependencies (from supertypes to subtypes and vice versa).

NOTE: Flattening of inheritance structures for types from external packages is currently not supported.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
flattenInheritanceIncludeRegex  Optional
separatorForPropertyFromUnion  Optional
codeByTaggedValue  Optional

Map Entries

none

req-flattener-flattenTypes-identify-circular-dependencies

Behavior

If this requirement is included then the Flattener will create a graph of schema types that would be selected for rule-trf-prop-flatten-types (which depends on the settings for the parameters flattenDataTypesExcludeRegex, flattenObjectTypes and flattenObjectTypesIncludeRegex).

Types that are not flattened will be excluded from the graph, i.e. especially feature types and – if they are not flattened – object and data types. Edges within the graph represent navigable routes (each edge from type A to type B contains the set of properties in type A that have B as value type). The flattener will then identify all circles that may exist in the graph, logging them on log level INFO.

NOTE: when creating the graph, the flattener does not take into account additional information that might override navigability between types, like the tagged value “isFlatTarget”. Such information must be used to flatten the model before processing the requirement – e.g. via rule-trf-prop-removeNavigabilityBasedOnIsFlatTarget.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
flattenDataTypesExcludeRegex Optional
flattenObjectTypes  Optional
flattenObjectTypesIncludeRegex  Optional

Map Entries

none

rule-trf-prop-flatten-multiplicity

Behavior

This rule applies to each property P with cardinality greater than one. Copies of P are added to the class so that the class has as many P properties as the maximum cardinality of P or the maxOccurs value indicate.

NOTE: maxOccurs is a global parameter value that can be overwritten via a tagged value on P.

An index number is added to the names of all newly established properties and, if they exist, aliases/codes of the P properties (P_1, P_2, …).

NOTE: the separator between the property name and the index number can be configured via the transformation parameter separatorForPropertyIndexNumber (default is “_”)

NOTE: dissolves associations where one navigable end has maximum multiplicity > 1. Dissolving an association means that a potentially existing association class is removed from the model (if it must be kept, transform the association class as described in GML 3.3 before flattening) and each navigable end is turned into an attribute property of the class it belongs to. An association where both ends have maximum multiplicity less than or equal to 1 will be kept as-is.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
maxOccurs  Optional
maxOccursForSpecificProperties  Optional
ignoreFeatureOrObjectTypedProperties  Optional
ignoreFeatureTypedProperties  Optional
separatorForPropertyIndexNumber  Optional
codeByTaggedValue  Optional

Map Entries

none

Subrules

The following rules can be used to further modify the behavior of multiplicity flattening:

  • rule-trf-prop-flatten-multiplicity-keepBiDirectionalAssociations
  • rule-trf-prop-flatten-multiplicity-withMaxMultiplicityThreshold

rule-trf-prop-flatten-multiplicity-keepBiDirectionalAssociations

NOTE: this is a subrule of rule-trf-prop-flatten-multiplicity (which must be enabled in order for the subrule to have any effect)

Behavior

In case that multiplicity flattening would result in dissolving a bi-directional association (because one or both association ends would be flattened) this rule ensures that the association is kept as-is. This can be useful in case that n:m relationships represented by bi-directional associations shall be maintained in the model – for example for the creation of associative tables while deriving SQL DDL.

NOTE: A warning will be logged if this rule prevents the dissolution of a bi-directional association.

Parameters

none

rule-trf-prop-flatten-multiplicity-withMaxMultiplicityThreshold

NOTE: this is a subrule of rule-trf-prop-flatten-multiplicity (which must be enabled in order for the subrule to have any effect)

Behavior

If this rule is enabled then a property will only be subject to multiplicity flattening if its upper multiplicity boundary is lower than or equal to the integer value given by the configuration parameter maxMultiplicityThreshold.

Examples:

  • PropertyA, multiplicity 1..5 – maxMultiplicityThreshold: 5 -> multiplicity flattening WILL be applied to the property (unless additional behavior forbids it)
  • PropertyB, multiplicity 0..7 – maxMultiplicityThreshold: 5 -> multiplicity flattening WILL NOT be applied to the property
  • PropertyC, multiplicity 1..* – maxMultiplicityThreshold: 5 -> multiplicity flattening WILL NOT be applied to the property
  • PropertyD, multiplicity 0..1 – maxMultiplicityThreshold: 5 -> multiplicity flattening would not be applied to the property anyway

Parameters

Parameter Name Required / Optional (for Execution of Rule)
 maxMultiplicityThreshold  Required (if not provided or invalid, the rule does not have any effect)

rule-trf-prop-flatten-types

Behavior

This rule flattens complex model structures.

At first, all classes that shall be flattened by the rule are identified. Per default, that is all data type, union, and object types (A) that:

  1. belong to one of the schemas selected for processing and
  2. are used as value type by the property (P1of ) of a feature, object, union or data type (B) of the selected schemas.

NOTE 1: if object types shall not be flattened, make use of the configuration parameter flattenObjectTypes (set it to false). If only a subset of object types shall be flattened, then set flattenObjectTypes to false and identify the object types that shall be flattened via the parameter flattenObjectTypesIncludeRegex.

NOTE 2: if certain data types shall not be flattened, make use of the configuration parameter flattenDataTypesExcludeRegex (providing a regular expression that matches the names of the data types to exclude from type flattening).

All properties (P1) that have a value type for which a type mapping is defined in the ShapeChange configuration (via Map Entries for the Flattener transformation containing this rule, see further below) receive the value type defined by the type mapping.

If the value type of property (P1) in type (B) is one of type (A), the content of (A) is flattened, i.e. the properties of (A) are copied to (B):

  • If the configuration parameter ignoreReflexiveRelationshipInTypeFlattening is set to true (default is false) then all properties of (A) whose value type is (A) itself are not flattened. In other words, reflexive relationships in types that are flattened are ignored.
  • Each property (P2) of type (A) is copied into type (B):
    • The copy of (P2) receives the documentation and tagged values of (P1).
    • Name and alias/code of the copy are modified to reflect the flattening process:
      • The names of (P1) and (P2) are concatenated with a separator. If (A) is a union then the separator is the value of the configuration parameter separatorForPropertyFromUnion. Otherwise the separator is the value of parameter separatorForPropertyFromNonUnion.
      • If (A) has tagged value omitWhenFlattened set to true then the name of (P1) is not used in the name of the copy. In other words, the copy receives the name of (P2).
        • NOTE: this behavior can be useful in case that class (A) is just a helper class that aggregates a number of properties that are used by multiple classes (example: a WaterResourceInfo class). The behavior also helps reducing the length of names of flattened model elements.
        • WARNING: this mechanism only works if the maximum multiplicity of (P1) is exactly 1. In addition, (B) must not contain a property with a name that equals the name of one of the properties from (A). Otherwise the result would be ambiguous.
      • The aforementioned procedure is also applied to combine the alias/code of the properties (P1) and (P2) – but only if both properties have an alias/code.
      • If the property (P1) has the tagged value “name” then that tagged value is also set in copies of (P2), combined with the “name” tagged value of (P2) if the tagged value is set there (the separator is “-” in that case).
    • In addition, the multiplicity is modified:
      • If (A) is a union then the minimum multiplicity of the property copy is set to 0 (in order to support the “choice” character of the union). Otherwise the minimum multiplicity is set to the lower one of (P1) and (P2).
      • The maximum multiplicity is set to unbounded if one of (P1) and (P2) has that maximum multiplicity – otherwise it is set to the product of the maximum multiplicity values of (P1) and (P2).
    • Property copies are inserted in (B) in the order in which they occur in (A) – at the location of (P1).

Finally, all types (A) and properties (P1) – which have been replaced by a number of copies – are removed from the model.

NOTE: This rule currently only flattens data, object, and union types from selected application schema, not from external packages. Types from external packages may be replaced according to the type mappings defined for this rule.

NOTE: if a schema contains an undirected association between types to be flattened (most likely object types) then the flattening process can lead to unexpected results. The tagged value “isFlatTarget” can be used to further specify the flattening behavior for undirected associations. See the documentation for rule-trf-prop-removeNavigabilityBasedOnIsFlatTarget for further details.


Example 1

ClassA:

  • <<property>> p: ClassB [1..3]

ClassB:

  • <<property>> prop1: Integer [1..*]
  • <<property>> prop2: Boolean [0..3]

The Flattener will transform this to:

ClassA:

  • <<property>> p.prop1: Integer [1..*]
  • <<property>> p.prop2: Boolean [0..9]

Example 2

ClassA:

  • <<property>> pA: ClassB

ClassB (tagged value “omitWhenFlattened”= true):

  • <<property>> pB1: Integer
  • <<property>> pB2: Boolean

The Flattener will transform this to:

ClassA:

  • <<property>> pB1: Integer
  • <<property>> pB2: Boolean

As we can see, the names of ClassA properties in the flattened schema do not contain the component “pA”.

 

Parameters

Parameter Name Required / Optional (for Execution of Rule)
codeByTaggedValue  Optional
flattenDataTypesExcludeRegex Optional
flattenObjectTypes  Optional
flattenObjectTypesIncludeRegex  Optional
ignoreReflexiveRelationshipInTypeFlattening  Optional
includeUnionIdentifierTaggedValue Optional
mergeDescriptors Optional
separatorForPropertyFromUnion  Optional
setMinCardinalityToZeroWhenMergingUnion  Optional
includeUnionIdentifierTaggedValue Optional

Map Entries

If a property has a <<dataType>> or <<type>> as its type and a process map entry defines a target type for this type, then the type of the property is switched to that target type.

rule-trf-all-flatten-name

Behavior

The Flattener replaces the name of each model element (class, property) with its code value, if it is set.

  • By default the alias of a model element (e.g. class or property) is used to look up and store code values. This behavior can be modified via the codeByTaggedValue configuration parameter.
  • If the parameter lowerCaseCodeForProperties is set to true then code values used as property names are converted to lower case.
  • If the parameter codeForEnumerationValues is set to false, enumeration value names are not replaced.
  • By default the original name of a model element is stored in its code value. This behavior can be turned off via the configuration parameter keepOriginalNameAsCode (set to false).

NOTE: at the moment this rule only updates names of classes and properties in the application schema. It does not modify names of association infos or packages.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
codeByTaggedValue  Optional
codeForEnumerationValues  Optional
keepOriginalNameAsCode  Optional
lowerCaseCodeForProperties  Optional

Map Entries

none

rule-trf-prop-remove-name-and-code-component

Alias: rule-trf-prop-remove-name-and-alias-component

Behavior

The Flattener removes all components of the name and code value (if existent) of a property that match one of the regular expressions defined by the parameter ‘removePropertyNameAndCodeComponent’.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
codeByTaggedValue  Optional
removePropertyNameAndCodeComponent  Optional (if not provided or empty, the model simply won’t be changed.

Map Entries

none

rule-trf-prop-flatten-homogeneousgeometries

Behavior

This rule ensures that a feature type only uses a single type of geometry. If a feature type has properties with different geometry type, copies of the feature type will be created that then have a homogeneous geometry type.

Each feature type is inspected to identify the geometry types its properties use. If the name of a value type from one of these properties has the prefix “GM_” then the according type is counted as a geometry type. For each geometry type, a reference is kept to the set of properties that use it as value type (S).

NOTE: if a feature type only uses a single geometry type then application of this rule can be prevented by setting the configuration parameter omitHomogeneousGeometriesForTypesWithSingleGeometryProperty to true.

For each of the properties in (S), the related properties (SRel) within the same feature type (FT) are identified as follows:

  • If the name of a property from (S) contains the separator for non unions (defined via configuration parameter separatorForPropertyFromNonUnion) then the part of the property name (NP) is computed that spans from the start of the name to that separator.
  • All properties of (FT) that have the same name prefix (NP) are considered to be related and thus belong to (SRel).
  • NOTE: this is especially useful to identify geometry metadata properties after inheritance and complex type flattening has been applied.

Now geometry type specific copies of feature types can be created. This only happens if a type mapping (defined via Map Entries – see further below) exists for the geometry type. A map entry must identify the geometry type in its “type” attribute, and the attributes “targetType” and “param” must be set. The attribute “targetType” contains the name of a geometry type (GTT) and allows mapping of geometry types (e.g. replacing GM_Surface with GM_Object, if desired). The attribute “param” contains an abbreviation (GA) for the geometry type.

The name of a feature type copy uses the original class name, with a suffix consisting of the separatorForGeometryTypeSuffix (which is a configuration parameter) and the geometry type abbreviation (GA). A potentially existing alias/code of the feature type copy are adjusted as well.

All properties that belong to a geometry type that is different to the one used by the feature type copy are removed from the copy.

The remaining properties with geometry type are mapped to (GTT) as defined by the process map entry.

The configuration parameter applyHomogeneousGeometriesOnSubtypes can be used to ensure that geometry type specific inheritance trees are created.

A union with the geometry type specific copies of a feature type – and possibly its subtypes – is created. Wherever the original feature type was used as value type of an attribute in the schema(s) selected for processing, it is replaced by the union.

NOTE: the creation and assignment of these unions may require a final flattening of complex types via rule-trf-prop-flatten-types.

NOTE: Associations and association roles receive a specific treatment: For each association where FT is at one end: establish a copy of the association for each geometry type specific copy of FT and append the geometry type specific suffix to the name of the role that has FT as value type (regardless whether it is navigable or not); set minimum multiplicity of the role with value type being a geometry specific type to 0 (regardless whether it is navigable or not).

Finally, all copied feature types are removed from the model.

NOTE: this rule is only applicable to direct geometry properties of a feature type, i.e. it does not take into account geometry typed properties that indirectly (e.g. via properties with complex data type) belong to the feature type.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
applyHomogeneousGeometriesOnSubtypes  Optional
omitHomogeneousGeometriesForTypesWithSingleGeometryProperty  Optional
separatorForPropertyFromNonUnion  Optional
separatorForPropertyFromUnion  Optional
separatorForGeometryTypeSuffix  Optional
codeByTaggedValue  Optional

Map Entries

The process map entries for this rule define mappings and naming parameters for the geometry types to be processed by this rule, as follows:

  • If a process map entry has a type but not a targetType then the type is removed from the model (with associated properties).
  • If a process map entry has a targetType and parameter value then the type is mapped to that targetType, appending the parameter value to the class name.
  • If there is a process map entry for a type with targetType but it contains no parameter then the type is removed, just as if no type mapping was defined.

rule-trf-cls-replace-with-union-properties

(available since 2.2.0)

Behavior

If only a single property (A) of a non-union type (e.g. a datatype) has a specific union as value type, and if that property has maximum multiplicity 1, then copies of the union properties replace property A. The sequenceNumbers of the property copies will be adjusted, so that the union property copies are correctly positioned within their new class. Their multiplicity is also adjusted: minimum occurrence is the product of the minimum occurrence of property A and the original union property, while the maximum occurrence is “*” if the maximum occurrence of one of the two properties is “*”, otherwise it is the product of the maximum occurrences.

Finally, those unions that 1) have been processed by this rule and 2) are no longer used by properties of the selected schemas are removed from the model.

Parameters

Parameter Name Required / Optional (for Execution of Rule)
includeUnionIdentifierTaggedValue Optional
replaceUnionExcludeRegex Optional

Map Entries

None

rule-trf-cls-flatten-inheritance-add-attributes-at-bottom

Available for ShapeChange version: 2.3.0+

Behavior: If this rule is enabled, then attributes copied from a supertype to a subtype during the execution of rule-trf-cls-flatten-inheritance will be placed at the bottom of the sequence of existing properties, instead of at the top.

Parameters: none

Map Entries: none

A Word on the Order of Execution

Flattening rules and requirements can be configured as a sequence of standalone transformations. This is useful to apply flattening in a very specific order. For example, configure one transformation to flatten inheritance and then configure another transformation to flatten multiplicity (with input being the result of inheritance flattening).

Because all flattening behavior is implemented by a single transformer – the “Flattener” – it is possible to configure a single transformation with all flattening rules and requirements that shall be processed. In this case, the order of execution is especially important. The Flattener executes flattening rules and requirements in the following order:

  1. rule-trf-all-removeType
  2. rule-trf-cls-dissolve-mixins
  3. rule-trf-prop-removeObjectToFeatureTypeNavigability
  4. rule-trf-all-removeFeatureTypeRelationships
  5. rule-trf-prop-removeNavigabilityBasedOnIsFlatTarget
  6. rule-trf-all-flatten-constraints
  7. rule-trf-prop-flatten-codelists
  8. rule-trf-prop-flatten-ONINAs
  9. rule-trf-prop-optionality
  10. rule-trf-cls-flatten-inheritance
  11. req-flattener-flattenTypes-identify-circular-dependencies
  12. rule-trf-prop-flatten-multiplicity
  13. rule-trf-cls-replace-with-union-properties
  14. rule-trf-prop-flatten-types
  15. rule-trf-all-flatten-name
  16. rule-trf-prop-remove-name-and-code-component
  17. rule-trf-prop-flatten-homogeneousgeometries
  18. rule-trf-cls-remove-inheritance-relationship

The execution order may or may not have an impact on rule parameter values. For example, if the maxOccursForSpecificProperties parameter was set to change the maximum cardinality of a property in a type that is a supertype and has already been processed – and removed – by rule-trf-cls-flatten-inheritance, then the parameter won’t have an effect on the resulting schema. One would need to set the parameter in such a way that it takes the preceding modifications (applied through flattening) into account. In this example one would need to list all the (direct and indirect, non-abstract) subtypes of the supertype to change the cardinality of the property that they received from the supertype.

Further considerations regarding the order of rule execution:

  • If rule-trf-prop-flatten-types was executed before rule-trf-prop-flatten-multiplicity then the index number appended for each individual copy created by rule-trf-prop-flatten-multiplicity for a property p with maximum cardinality > 1 would not be added to the name of property p but to each following facet (created by rule-trf-prop-flatten-types). Thus, instead of p_1.xyz, p_2.xyz, p_3.xyz one would get p.xyz_1, p.xyz_2, p.xyz_3. By looking at the latter list of names one would think that property xyz had maximum cardinality > 1, while it is actually property p.

Parameters

The parameters supported by the Flattener are described in the following sections.

applyHomogeneousGeometriesOnSubtypes

Alias: none

Type: Boolean

Default Value: false

Behavior:

Controls whether or not rule-trf-prop-flatten-homogeneousgeometries creates geometry type specific inheritance trees.

Applies to Rule(s):

  • rule-trf-prop-flatten-homogeneousgeometries

codeByTaggedValue

Alias: none

Type: String

Default Value: by default the alias is used to look up and store the code value

Behavior:

Provides the name of a tagged value that shall be used to look up and store the code value of a model element (e.g. class or property).

Applies to Rule(s):

  • rule-trf-all-flatten-name
  • rule-trf-cls-flatten-inheritance
  • rule-trf-prop-flatten-homogeneousgeometries
  • rule-trf-prop-flatten-multiplicity
  • rule-trf-prop-flatten-ONINAs
  • rule-trf-prop-flatten-types
  • rule-trf-prop-remove-name-and-code-component

codeForEnumerationValues

Alias: aliasForEnumerationValues

Type: Boolean

Default Value: true

Behavior

True if flattening of enumeration value/property names by replacing them with the code value (if set) shall be performed, else false (in that case, the existing name is kept for enumeration values).

Applies to Rule(s)

  • rule-trf-all-flatten-name

enforceOptionality

Alias: none

Type: (comma separated) list of Strings

Default Value: none

Behavior

Properties that are of one of the types listed in this parameter (type is identified via its name, for example “GM_Point, GM_Curve, GM_MultiPoint”) are set to optional.

Applies to Rule(s)

  • rule-trf-prop-optionality

flattenDataTypesExcludeRegex

Alias: none

Type: String (with Java compliant regular expression)

Default Value: none

Behavior

This parameter allows to identify the complex data types that shall NOT be flattened. The value of this parameter contains a (Java compliant) regular expression which, if it matches the name of a data type, marks it to be excluded from type flattening.

Applies to Rule(s)

  • req-flattener-flattenTypes-identify-circular-dependencies
  • rule-trf-prop-flatten-types

flattenInheritanceIncludeRegex

Alias: none

Type: String (with Java compliant regular expression)

Default Value: none

Behavior

Only those supertypes whose name – or the name of one of its supertypes up in the inheritance hierarchy (but ignoring supertypes outside of the application schema(s) selected for processing – matches the regular expression are subject to inheritance flattening via rule-trf-cls-flatten-inheritance.

Applies to Rule(s)

  • rule-trf-cls-flatten-inheritance

flattenObjectTypes

Alias: none

Type: Boolean

Default Value: true

Behavior

If set to ‘false’, object type classes (with no stereotype or stereotype <<type>>) will not be flattened by rule-trf-prop-flatten-types.

Applies to Rule(s)

  • req-flattener-flattenTypes-identify-circular-dependencies
  • rule-trf-prop-flatten-types

flattenObjectTypesIncludeRegex

Alias: none

Type: String (with Java compliant regular expression)

Default Value: none

Behavior

If the parameter ‘flattenObjectTypes’ is set to false, then via this parameter one can still identify object types that shall be flattened. The value of this parameter contains a (Java compliant) regular expression which, if it matches the name of an object type, marks it for type flattening.

Applies to Rule(s)

  • req-flattener-flattenTypes-identify-circular-dependencies
  • rule-trf-prop-flatten-types

ignoreFeatureTypedProperties

Alias: none

Type: Boolean

Default Value: false

Behavior

If set to ‘true’, the multiplicity of an attribute whose type is a feature type is kept as is, thus ignoring the maxOccurs setting completely. For associations where both ends are feature types the multiplicity will also be kept as is. For all other cases multiplicity will be flattened using the maxOccurs setting.

Applies to Rule(s)

  • rule-trf-prop-flatten-multiplicity

ignoreFeatureOrObjectTypedProperties

Alias: none

Type: Boolean

Default Value: false

Behavior

If set to ‘true’, the multiplicity of an attribute whose type is a feature, object, or mixin type is kept as is, thus ignoring the maxOccurs setting completely. For associations where the type of both ends falls into one of the aforementioned categories (feature, object, mixin) the multiplicity will also be kept as is. For all other cases multiplicity will be flattened using the maxOccurs setting.

Applies to Rule(s)

  • rule-trf-prop-flatten-multiplicity

ignoreReflexiveRelationshipInTypeFlattening

Alias: none

Type: Boolean

Default Value: false

Behavior

If this parameter is set to true then reflexive relationships in types that are flattened are ignored in rule-trf-prop-flatten-types.

Applies to Rule(s)

  • rule-trf-prop-flatten-types

includeObjectToObjectNavigability

Alias: none

Type: String

Default Value: false

Behavior

If this parameter is set to true then execution of rule-trf-prop-removeObjectToFeatureTypeNavigability will also remove navigable properties whose value type is an object type.

Applies to Rule(s)

  • rule-trf-prop-removeObjectToFeatureTypeNavigability

includeUnionIdentifierTaggedValue

(available since 2.2.0)

Alias: none

Type: Boolean

Default Value: false

Behavior

If this parameter is set to true, then properties that originate from flattening a specific union will be tagged (with tag ‘SC_UNION_SET’). This allows identifying which properties belong to the union after it has been flattened – just by looking at the tagged values. Properties from a union that are copied into another union will not be tracked. Also, tracking information will be removed / not created if union options replace a property with max multiplicity > 1 (because then the union semantics will become irrelevant, as that property can have values from more than one union option).

Applies to Rule(s)

  • rule-trf-prop-flatten-types
  • rule-trf-cls-replace-with-union-properties

keepOriginalNameAsCode

Alias: keepOriginalNameAsAlias

Type: Boolean

Default Value: true

Behavior

If set to ‘false’, the original name of a model element is not stored in its code value during the execution of rule-trf-all-flatten-name.

Applies to Rule(s)

  • rule-trf-all-flatten-name

lowerCaseCodeForProperties

Alias: lowerCaseAliasForProperties

Type: Boolean

Default Value: false

Behavior

True if code values shall be converted to lower case while replacing property names with code values, else false.

Applies to Rule(s)

  • rule-trf-all-flatten-name

maxMultiplicityThreshold

Alias: none

Type: Integer (>1)

Default Value: none

Behavior

Identifies the threshold for multiplicity flattening if rule-trf-prop-flatten-multiplicity-withMaxMultiplicityThreshold is enabled, together with rule-trf-prop-flatten-multiplicity. The value shall be an integer bigger than 1.

Applies to Rule(s)

  • rule-trf-prop-flatten-multiplicity-withMaxMultiplicityThreshold

maxOccurs

Alias: none

Type: Integer (>0)

Default Value: 3

Behavior

Identifies the default for the maximum occurrence of model properties with cardinality greater than one.The tagged value “maxOccurs” can also directly be set for a model property. In that case its value overrides the default defined by this parameter.

Applies to Rule(s)

  • rule-trf-prop-flatten-multiplicity

maxOccursForSpecificProperties

Alias: none

Type: (comma separated) list of Strings

Default Value: none

Behavior

Allows the override of the local and global maxOccurs settings defined for a model property (local = via the ‘maxOccurs’ tagged value on the property, global = via the ‘maxOccurs’ parameter in the configuration).

Each component in the list of strings that is the value of this parameter follows a specific pattern:<class name>::<property name>::<explicit maxOccurs>

Example: FeatureEntity::propGeometry::1 -> the property ‘propGeometry’ in class ‘FeatureEntity’ shall have a maximum occurrence of 1

Multiple patterns are separated via a comma.

Applies to Rule(s)

  • rule-trf-prop-flatten-multiplicity

mergeDescriptors

Alias: none

Type: Boolean

Default Value: false

Behavior

If set to true, then descriptors of properties will be merged during type flattening:

  • Definition, description, primary code, and legal basis will be concatenated, using a single space as separator.
  • The data capture statements  will be merged into a single list – same for examples.

Applies to Rule(s)

  • rule-trf-prop-flatten-types

omitHomogeneousGeometriesForTypesWithSingleGeometryProperty

Alias: none

Type: Boolean

Default Value: false

Behavior:

Set to true if rule-trf-prop-flatten-homogeneousgeometries shall not be applied on feature types that only use a single geometry type (in other words: they already have homogeneous geometry).

Applies to Rule(s):

  • rule-trf-prop-flatten-homogeneousgeometries

removeInheritanceIncludeRegex

Alias: none

Type: String (with Java compliant regular expression)

Default Value: none

Behavior:

If the name of a class matches this expression, then all supertype relationships to this class will be removed in the model. In other words: the class is disconnected from its subtypes.

Applies to Rule(s):

  • rule-trf-cls-remove-inheritance-relationship

removeObjectToFeatureNavRegex

Alias: none

Type: String (with Java compliant regular expression)

Default Value: none

Behavior

If the name of an object type matches this expression, then each navigable property whose value type is a feature type will be removed from the object type.

Applies to Rule(s)

  • rule-trf-prop-removeObjectToFeatureTypeNavigability

removePropertyNameAndCodeComponent

Alias: removePropertyNameAndAliasComponent

Type: (comma separated) list of Strings (representing Java compliant regular expressions)

Default Value: none

Behavior

Each match (for one of the regular expressions listed in this parameter, for example “.valueOrReason”) within the name or code value of a property is replaced by the empty string (thus removing the matching part of the property name/code).This is useful for shortening the names of feature type properties whose complex structure has been flattened to a simple one. Common name parts that are introduced during the flattening process can thus be removed.

NOTE: expects Java compliant regular expressions; constructs of the expression can be escaped accordingly.

Applies to Rule(s)

  • rule-trf-prop-remove-name-and-code-component

removeType

Alias: none

Type: (comma separated) list of Strings

Default Value: none

Behavior

Any of the types (identified by name, for example “ClassX”) listed in this parameter will be removed from the model.

Applies to Rule(s)

  • rule-trf-all-removeType

replaceUnionExcludeRegex

(available since 2.2.0)

Alias: none

Type: String (with Java compliant regular expression)

Default Value: none

Behavior

This parameter identifies the unions that shall NOT be flattened. The value of this parameter contains a (Java compliant) regular expression which, if it matches the name of a union, marks it to be excluded by the Flattener.

Applies to Rule(s)

  • rule-trf-cls-replace-with-union-properties

separatorForPropertyFromNonUnion

Alias: none

Type: (non empty) String

Default Value: “.”

Behavior

Separator to use for name/code concatenation when flattening properties from a NON union type. If the length of the parameter value is zero, the default value will be used.

Applies to Rule(s)

  • rule-trf-prop-flatten-types
  • rule-trf-prop-flatten-homogeneousgeometries

separatorForPropertyFromUnion

Alias: none

Type: (non empty) String

Default Value: “-“

Behavior

Separator to use for name/code concatenation when flattening properties from a union type. If the length of the parameter value is zero, the default value will be used.

Applies to Rule(s)

  • rule-trf-cls-flatten-inheritance
  • rule-trf-prop-flatten-types
  • rule-trf-prop-flatten-homogeneousgeometries

separatorForPropertyIndexNumber

Alias: none

Type: String (can be empty)

Default Value: “_”

Behavior

Separator to use for concatenating the name/code of a property with an index number while flattening multiplicity.

Applies to Rule(s)

  • rule-trf-prop-flatten-multiplicity

separatorForGeometryTypeSuffix

Alias: none

Type: String (can be empty)

Default Value: “” (the empty string)

Behavior

Separator to use for concatenating the name of a feature type with the geometry type suffix while applying rule-trf-prop-flatten-homogeneousgeometries.

Applies to Rule(s)

  • rule-trf-prop-flatten-homogeneousgeometries

setMinCardinalityToZeroWhenMergingUnion

(available since 2.2.0)

Alias: none

Type: Boolean

Default Value: true

Behavior

If, during execution of “rule-trf-prop-flatten-types”, a union is flattened, then by default the minimum multiplicity of the flattened property is set to 0. However, if the replaced property has a maximum multiplicity of 1 and the transformation parameter “includeUnionIdentifierTaggedValue” is set to true, then the union semantics can be represented in the model. In that case, setting the minimum multiplicity of the flattened property to 0 would unnecessarily reduce valuable information. To prevent this from happening, set this parameter to false (the default is true).

Applies to Rule(s)

  • rule-trf-prop-flatten-types

targetNamespaceSuffix

Alias: none

Type: String

Default Value: none

Behavior

If provided, the value of this parameter is added to the targetNamespaces of all selected schema in the flattened model (unless the target namespace already ends with this suffix).

Applies to Rule(s): universal parameter for Flattener transformation, i.e. if added to a Flattener transformation, it will be applied to the transformation result.

 

 

Sample Configurations

Single Transformation

<Transformer
   class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="flat" mode="enabled">
    <parameters>
        <ProcessParameter name="targetNamespaceSuffix" value="/flat"/>
        <ProcessParameter name="maxOccurs" value="3"/>
        <ProcessParameter name="enforceOptionality"
            value="GM_Object,GM_Point,GM_MultiPoint,GM_Curve,GM_MultiCurve,GM_Surface,GM_MultiSurface,GM_Solid,GM_MultiSolid"/>
        <ProcessParameter name="lowerCaseCodeForProperties" value="true"/>
        <ProcessParameter name="codeForEnumerationValues" value="false"/>
        <ProcessParameter name="removeType" value="TypeMeta,FeatureAttMetadata"/>
        <ProcessParameter name="removePropertyNameAndCodeComponent"
            value="(?i)\.valueOrReason"/>
    </parameters>
    <rules>
        <ProcessRuleSet name="flattener">
            <rule name="rule-trf-all-removeType"/>
            <rule name="rule-trf-prop-flatten-ONINAs"/>
            <rule name="rule-trf-prop-optionality"/>
            <rule name="rule-trf-cls-flatten-inheritance"/>
            <rule name="rule-trf-prop-flatten-multiplicity"/>
            <rule name="rule-trf-prop-flatten-types"/>
            <rule name="rule-trf-all-flatten-constraints"/>
            <rule name="rule-trf-all-flatten-name"/>
            <rule name="rule-trf-prop-remove-name-and-code-component"/>
            <rule name="rule-trf-prop-flatten-homogeneousgeometries"/>
        </ProcessRuleSet>
    </rules>
    <mapEntries>
        <ProcessMapEntry rule="rule-trf-prop-flatten-types" targetType="CharacterString"
            type="CI_Citation"/>
        <ProcessMapEntry rule="rule-trf-prop-flatten-types" targetType="Real" type="Measure"/>
        <ProcessMapEntry param="_P" rule="rule-trf-prop-flatten-homogeneousgeometries"
            targetType="GM_Point" type="GM_Point"/>
        <ProcessMapEntry param="_C" rule="rule-trf-prop-flatten-homogeneousgeometries"
            targetType="GM_Object" type="GM_Curve"/>
        <ProcessMapEntry param="_S" rule="rule-trf-prop-flatten-homogeneousgeometries"
            targetType="GM_Object" type="GM_Surface"/>
        <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries" type="GM_Solid"/>
        <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries"
            type="GM_MultiPoint"/>
        <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries"
            type="GM_MultiCurve"/>
        <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries"
            type="GM_MultiSurface"/>
        <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries"
            type="GM_MultiSolid"/>
    </mapEntries>
</Transformer>

Chain of Transformations

<transformers>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_removeType" mode="enabled">
    <parameters>
      <ProcessParameter name="removeType" value="TypeMeta,FeatureAttMetadata"/>
    </parameters>
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-all-removeType"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_removeObjectToFeatureTypeNavigability" input="F_removeType" mode="enabled">
    <parameters>
      <ProcessParameter name="removeObjectToFeatureNavRegex" value="^((?!Geometry).)*Info"/>
      <ProcessParameter name="includeObjectToObjectNavigability" value="true"/>
    </parameters>
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-removeObjectToFeatureTypeNavigability"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_removeNavigabilityBasedOnIsFlatTarget" input="F_removeObjectToFeatureTypeNavigability"
    mode="enabled">
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-removeNavigabilityBasedOnIsFlatTarget"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_constraints" input="F_removeNavigabilityBasedOnIsFlatTarget" mode="enabled">
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-all-flatten-constraints"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_codelists" input="F_constraints" mode="enabled">
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-flatten-codelists"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_oninas" input="F_codelists" mode="enabled">
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-flatten-ONINAs"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_inheritance" input="F_oninas" mode="enabled">
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-cls-flatten-inheritance"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_multiplicity" input="F_inheritance" mode="enabled">
    <parameters>
      <ProcessParameter name="maxOccurs" value="3"/>
    </parameters>
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-flatten-multiplicity"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_types" input="F_multiplicity" mode="enabled">
    <parameters>
      <ProcessParameter name="ignoreReflexiveRelationshipInTypeFlattening" value="true"/>
    </parameters>
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-flatten-types"/>
      </ProcessRuleSet>
    </rules>
    <mapEntries>
      <ProcessMapEntry rule="rule-trf-prop-flatten-types" targetType="CharacterString"
        type="CI_Citation"/>
      <ProcessMapEntry rule="rule-trf-prop-flatten-types" targetType="CharacterString"
        type="CI_Address"/>
      <ProcessMapEntry rule="rule-trf-prop-flatten-types" targetType="CharacterString"
        type="CI_Contact"/>
      <ProcessMapEntry rule="rule-trf-prop-flatten-types" targetType="Real" type="Measure"/>
    </mapEntries>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_name" input="F_types" mode="enabled">
    <parameters>
      <ProcessParameter name="lowerCaseCodeForProperties" value="true"/>
    </parameters>
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-all-flatten-name"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_removeNameComp" input="F_name" mode="enabled">
    <parameters>
      <ProcessParameter name="removePropertyNameAndCodeComponent" value="(?i)\.valueOrReason"/>
    </parameters>
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-remove-name-and-code-component"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_homogGeom" input="F_removeNameComp" mode="enabled">
    <parameters>
      <ProcessParameter name="targetNamespaceSuffix" value="/flat"/>
      <ProcessParameter name="separatorForGeometryTypeSuffix" value="_"/>
    </parameters>
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-flatten-homogeneousgeometries"/>
      </ProcessRuleSet>
    </rules>
    <mapEntries>
      <ProcessMapEntry param="P" rule="rule-trf-prop-flatten-homogeneousgeometries"
        targetType="GM_Point" type="GM_Point"/>
      <ProcessMapEntry param="C" rule="rule-trf-prop-flatten-homogeneousgeometries"
        targetType="GM_Curve" type="GM_Curve"/>
      <ProcessMapEntry param="S" rule="rule-trf-prop-flatten-homogeneousgeometries"
        targetType="GM_Surface" type="GM_Surface"/>
      <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries" type="GM_Solid"/>
      <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries" type="GM_MultiPoint"/>
      <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries" type="GM_MultiCurve"/>
      <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries" type="GM_MultiSurface"/>
      <ProcessMapEntry rule="rule-trf-prop-flatten-homogeneousgeometries" type="GM_MultiSolid"/>
    </mapEntries>
  </Transformer>
  <Transformer class="de.interactive_instruments.ShapeChange.Transformation.Flattening.Flattener"
    id="F_types_final" input="F_homogGeom" mode="enabled">
    <rules>
      <ProcessRuleSet name="flattener">
        <rule name="rule-trf-prop-flatten-types"/>
      </ProcessRuleSet>
    </rules>
  </Transformer>
</transformers>