Flattener
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.
req-flattener-flattenTypes-identify-circular-dependencies
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 |
rule-trf-all-flatten-constraints
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.
rule-trf-all-flatten-name
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 (attributes and association roles) in the application schema. It does not modify names of associations or packages.
Parameters:
| Parameter Name | Required / Optional (for Execution of Rule) |
| codeByTaggedValue | Optional |
| codeForEnumerationValues | Optional |
| keepOriginalNameAsCode | Optional |
| lowerCaseCodeForProperties | Optional |
rule-trf-all-flatten-removeConstraints
(since v2.4.0)
Removes all constraints from all classes – and their properties – in the schemas selected for processing.
rule-trf-all-flatten-type-mapToSimpleBaseType
(since v2.4.0)
Identify types in the schemas selected for processing that have one of the simple base types specified via parameter simpleBaseTypes as supertype. For each property of classes in the schemas selected for processing with such a basic type as type, change the type to the according simple base type. Finally, remove all types with simple base type that have been identified before.
rule-trf-all-removeFeatureTypeRelationships
Removes all navigable properties from a feature type if the value type of the property also is a feature type.
rule-trf-all-removeType
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-dissolve-mixins
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!
rule-trf-cls-flatten-inheritance
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).
NOTE: Tagged value representsFeatureTypeSet = true is added to the union. This allows for specific treatment of this kind of union, for example in rule-trf-prop-flatten-types-ignoreUnionsRepresentingFeatureTypeSets and rule-xsd-cls-union-omitUnionsRepresentingFeatureTypeSets.
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 |
rule-trf-cls-flatten-inheritance-add-attributes-at-bottom
(since v2.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.
rule-trf-cls-flatten-inheritance-associationRoleNameUsingCodeOfValueType
(since v2.4.0)
Alias: none
Behavior: Copies of association roles whose value type was a supertype to which inheritance flattening applied receive the code of their new value type as suffix. If a code is not defined for the new value type, then its name is used (which is the default behavior of rule-trf-cls-flatten-inheritance).
Parameter(s):
- codeByTaggedValue (optional – by default, the alias is used to look up the code value)
rule-trf-cls-flatten-inheritance-ignore-arcgis-subtypes
(available since v2.6.0)
This rule will modify the behaviour of rule-trf-cls-flatten-inheritance so that it will ignore classes that represent ArcGIS subtypes. In other words, inheritance flattening will only be performed to the level of the supertype of a class that represents an ArcGIS subtype, leaving the inheritance relationship between that subtype and its supertype intact.
This is important for encoding ArcGIS subtypes that are explicitly modelled in the conceptual model, when executing the ArcGIS Workspace target.
rule-trf-cls-flatten-inheritance-mergeLinkedDocuments
(available since v2.5.0)
If the super- and subtype both have linked documents, they are merged and the result is set as linked document of the subtype. Merging means that the linked document of the subtype is appended to the linked document of the supertype. Between the two documents, ShapeChange can add a pagebreak (which is controlled via the configuration parameter linkedDocumentPagebreak) to visually separate the documents.
If only the supertype has a linked document, it is set as linked document of the subtype without any modification.
NOTES:
- Linked documents are typcially created using Enterprise Architect. ShapeChange can load these files (as .docx) when loading the input model (see input parameter loadLinkedDocuments). Linked documents can be used, for example, by the SQL DDL target when creating a database model.
The LinkedDocumentTransformer can be used to prepare linked documents before merging.
rule-trf-cls-flatten-reverse-inheritance
(since v2.10)
This transformation rule “reverses” inheritanc, i.e., it moves properties of subtypes up into supertypes, ending at the highest level of inheritance trees contained in the schemas selected for processing.
NOTE: This rule does not take into account mixins. Mixin classes need to be dissolved before this transformation rule is executed, using rule-trf-cls-dissolve-mixins.
NOTE: The rule does not flatten inheritance hierarchies that involve basic types. A basic type is a type that inherits – directly or indirectly – from one of the base types from ISO 19103, for example Integer or CharacterString. The names of these base supertypes can be configured via transformation parameter basicTypeSupertypeNames.
The transformation starts at the lowest levels of the inheritance tree, taking into account subtypes from schemas in the whole model. If a supertype only has subtypes that do not have subtypes themselves, the transformation moves the properties of these subtypes into the supertype, thereby setting the minimum multiplicity of the property to 0. The transformation thereby ignores properties from subtypes that override a property from a direct or indirect supertype. Furthermore, the transformation checks if two or more properties of the subtypes have the same name, but different value type or multiplicity. If that is the case, then these properties are moved into the supertype, with their name and code (if set, either the alias or a tagged value, which can be controlled using parameter codeByTaggedValue) altered by appending the name/code of the subtype as suffix (using a separator that can be configured using transformation parameter typeSuffixSeparator). If multiple subtypes have properties with same name, value type, and multiplicity, then only one of these properties is moved to the supertype (and the others are ignored) – the semantics of these properties are assumed to be sufficiently similar.
The properties that are moved from subtypes to a supertype are ordered according to their names, and added in this order at the bottom of the properties list of the supertype. Once all relevant properties have been moved to the supertype, the inheritance relationship between the supertype and its subtypes is removed.
When processing of the inheritance trees in the schemas selected for processing has reached the highest level (either a root contained in the schemas selected for processing, or a class whose supertype is outside these schemas), a new property is added to the remaining classes of these inheritance trees. The value type of the property is an enumeration that lists the non-abstract (sub)types of the inheritance tree (the transformation keeps track of this information). The name of the property is defined via transformation parameter typeEnumerationPropertyName. The property is intended to indicate which of the feature types from the original conceptual model is encoded in instance data.
At the end of processing, the transformation sets all remaining classes of the inheritance trees to non-abstract. Furthermore, if the value type of a property (in the whole model) is one of the subtypes that has been processed, then the value type is changed to the remaining (direct or indirect) superclass from the inheritance tree to which the subtype belonged. Finally, all processed subtypes are removed from the model.
NOTE: This rule can be useful in case that the goal is to have a small set of feature types, where each type represents a root type, and is able to encode information from all subtypes that are defined in the conceptual schema. For example, rather than publishing a set of 50 feature collections, each for an individual feature type, 45 types are direct or indirect subtypes of 5 feature types, you would just want to publish 5 collections for these root types – making it more simple for clients to access your data.
rule-trf-cls-non-default-geometry-to-feature-type
(since v2.10)
For any geometric property (identified using a regular expression on the value type, as defined by parameter geometryTypeRegex) of a type in one of the schemas selected for processing that does NOT have tag defaultGeometry with value equal to (ignoring case) true, do the following:
- Create a new feature type. The name of this new type is a combination of the class that owns the property, and the property name, e.g. FeatureTypeX_geometryY. The code of the new type is set in a similar fashion, if both the class and the property have a code value. The new type is placed into the package that also owns the class.
- Add a geometry attribute to the new feature type, with multiplicity 1, and the same value type as the geometric property.
- Create a directed association from the class to the new feature type, where the navigable role has the same name and multiplicity as the geometric property. The non-navigable role has the name of the class (uncapitalized), and multiplicity 1.
NOTE: This rule can be useful to transform a model where types have multiple geometric properties (where one typically is identified as the default geometry by having tagged value defaultGeometry=true) to a model where each type only has a single geometric property.
rule-trf-cls-remove-inheritance-relationship
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) |
rule-trf-cls-replace-with-union-properties
(available since 2.2.0)
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 |
rule-trf-prop-flatten-codelists
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.
rule-trf-prop-flatten-directposition-typed-properties
(since v2.11)
For each property P that 1) belongs to a class from the schemas selected for processing and 2) has DirectPosition (used for attributes indicating height/elevation) as value type, the transformation rule switches the type of P to type Real.
At the moment, one subrule has been defined for this transformation rule:
- rule-trf-prop-flatten-directposition-typed-properties-add-rsid-property: adds a new property U to the class, whose name is the name of P plus the suffix defined by parameter directPositionRsidSuffix, with value type CharacterString, and sequence number so that U is placed right after P. If a code is defined for P, then U will receive that code as well. The lower bound of the multiplicity of U is set to 0..1 if the lower bound of the property itself is 0 and is set 1..1 if the lower bound of P is 1 or higher (TIP: use this rule together with rule-trf-prop-flatten-multiplicity).
NOTE: both rule and subrule must be enabled in order for the subrule to have effect.
rule-trf-prop-flatten-explicit-time-interval
(since v2.10)
An attribute (from the schemas selected for processing) that has tagged value timeIntervalBoundaryType with non-empty value is processed as follows:
- The value type is changed to the type whose name is given by the tagged value.
- A copy of the attribute is created. Suffix “End” is added to the name of the copy (and also to its code, if it has one). The sequence number of the copy is changed so that it is situated right after the original attribute.
- Suffix “Start” is added to the name of the original attribute (and also to its code, if it has one).
rule-trf-prop-flatten-homogeneousgeometries
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 all of the following conditions are fulfilled:
- A type mapping (defined via Map Entries – see further below) exists for the geometry type. A process 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.
- Tagged value geometry is not set, does not have a value, or one of the (comma-separated) values equals the “param” attribute of the process map entry that was identified before.
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: Tagged value representsFeatureTypeSet = true is added to the union. This allows for specific treatment of this kind of union, for example in rule-trf-prop-flatten-types-ignoreUnionsRepresentingFeatureTypeSets and rule-xsd-cls-union-omitUnionsRepresentingFeatureTypeSets.
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.
Parameter(s):
- applyHomogeneousGeometriesOnSubtypes
- codeByTaggedValue
- descriptorModification_geometryTypeAlias
- descriptorModification_geometryTypeSuffixSeparator
- omitHomogeneousGeometriesForTypesWithSingleGeometryProperty
- separatorForGeometryTypeSuffix
- separatorForPropertyFromNonUnion
- separatorForPropertyFromUnion
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-prop-flatten-mediatype-typed-properties
(since v2.11)
For each property P that 1) belongs to a class from the schemas selected for processing and 2) has MediaType as value type, the transformation rule switches the type of P to type CharacterString.
In addition, an extra property with suffix “_type” and type CharacterString is created. The lower bound of the multiplicity is set to 0..1 if the lower bound of the P is 0 and is set 1..1 if the lower bound of the property itself is 1 or higher (TIP: use this rule together with rule-trf-prop-flatten-multiplicity).
MediaType, defined in ISO 19103, inherits from CharacterString and has an extra property “type” that provides the media type name, see also IANA’s media type registry.
rule-trf-prop-flatten-measure-typed-properties
(since v2.10)
For each property P that 1) belongs to a class from the schemas selected for processing and 2) has a measure type (as defined by parameter measureTypes) as value type, the transformation rule switches the type of P to type Real.
Several subrules have been defined for this transformation rule:
- rule-trf-prop-flatten-measure-typed-properties-fixed-uom-suffix – adds a suffix to the name of P, if P has a fixed unit of measure, which is defined by the presence of a non-empty tagged value, whose tag name is defined by parameter measureUomTaggedValue, or identified by parameter fixedUomPropertyDefinitions . The uom symbol is given by the tagged value or the parameter. If a code is defined for P, then the suffix is also appended to that code. The separator which is put between the name of P and the uom symbol suffix is defined by parameter uomSuffixSeparator. This subrule can be useful to change the name/code of a property from, for example, “length” to “length_m”.
-
rule-trf-prop-flatten-measure-typed-properties-add-uom-property – adds a new property U to the class, whose name is the name of P plus suffix “_uom”, with value type CharacterString, multiplicity 0..1, and sequence number so that U is placed right after P. If a code is defined for P, then U will receive that code as well, using “_uom” as suffix.
- v2.11 and higher: the multiplicity is set to
- 0..1 if the lower bound of the property itself is 0
- 1..1 if the lower bound of the property itself is 1 or higher
- v.2.10: the multiplicity is alway set to 0..1
- v2.11 and higher: the multiplicity is set to
NOTES:
- This rule – together with its subrules – is useful to achieve a flat representation of measure typed properties.
- The rule has originally been developed as part of the work in the OGC UML-to-GML Application Schema Pilot (UGAS-2020). See the project report for further details on the application of the rule, section 7.3.2.2.1 Measure.
rule-trf-prop-flatten-multiplicity
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: If maxOccurs for a property is exactly 1, then the property is not copied or renamed. In that case, just the maximum cardinality of the property is set to 1.
NOTE: The separator between the property name and the index number can be configured via the transformation parameter separatorForPropertyIndexNumber (default is “_”). The index number can also be added to descriptors – for further details, see the documentation of parameter descriptorModification_propertyIndexNumberSeparator.
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.
Parameter(s):
- codeByTaggedValue
- descriptorModification_propertyIndexNumberSeparator
- ignoreFeatureOrObjectTypedProperties
- ignoreFeatureTypedProperties
- maxOccurs
- maxOccursForSpecificProperties
- separatorForPropertyIndexNumber
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)
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.
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)
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-ONINAs
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”).
The multiplicity of these properties is multiplied with the multiplicity of the value(s) property (minOccurs_property = minOccurs_property * minOccurs_values_property; same for maxOccurs, taking into account the case that one of the maxOccurs is ‘unlimited’).
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 |
rule-trf-prop-flatten-ONINAs-onlyRemoveReasons
(since v2.4.0)
Amends rule-trf-prop-flatten-ONINAs as follows:
- ONINA enums (“other”, “noInformation”, “notApplicable”) are not added to enumerations
- No BooleanWithONINA type is created
The type of a property with a “Reason” union as type will simply be changed to the type of the value(s) property from the “Reason” union. Once this modification is complete, all “Reason” unions are removed.
rule-trf-prop-flatten-types
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:
- belong to one of the schemas selected for processing and
- 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. Note that the documentation of the parameter also has an example where the expression is used to exclude all but a certain set of data types from 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 descriptors 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 descriptors of the properties (P1) and (P2).
- Separators for descriptors are configured via the configuration parameters descriptorModification_nonUnionSeparator and descriptorModification_unionSeparator. If these parameters are not configured, then the values from parameters separatorForPropertyFromUnion and separatorForPropertyFromNonUnion are used as fallback.
- NOTE: Descriptors dataCaptureStatement and example are not concatenated using a separator. Since these two descriptors can be multi-valued, the two sets of values would simply be combined.
- NOTE: The tagged value omitWhenFlattened does not apply to the descriptor globalIdentifier.
- 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 (since v2.8.0): If the copy of a property from (A) has the same name as a property that already exists in (B), then by default the copy from (A) is ignored. However, that behavior can be changed using parameter flattenTypesPropertyCopyDuplicateBehavior, essentially allowing you to overwrite the existing property in (B).
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:
- codeByTaggedValue
- descriptorModification_nonUnionSeparator
- descriptorModification_unionSeparator
- flattenDataTypesExcludeRegex
- flattenObjectTypes
- flattenObjectTypesIncludeRegex
- flattenTypesPropertyCopyDuplicateBehavior
- includeUnionIdentifierTaggedValue
- ignoreReflexiveRelationshipInTypeFlattening
- includeUnionIdentifierTaggedValue
- mergeDescriptors
- separatorForPropertyFromUnion
- setMinCardinalityToZeroWhenMergingUnion
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-prop-flatten-types-ignoreSelfReferenceByPropertyWithAssociationClassOrigin
(since v2.4.0)
When copying properties while processing rule-trf-prop-flatten-types, properties that originate from an association class and represent a self reference are not copied. More specifically: if a property P1 whose type is flattened has tagged value toAssociationClassFrom and a property P2 from that type has tagged value fromAssociationClassTo, and both tagged values have the same value, then property P2 is not copied.
rule-trf-prop-flatten-types-ignoreUnionsRepresentingFeatureTypeSets
(since v2.4.0)
Amends rule-trf-prop-flatten-types to ignore unions that represent feature type sets, i.e. unions that have tagged value representsFeatureTypeSet = true. These unions are not flattened and also not removed at the end of processing rule-trf-prop-flatten-types.
rule-trf-prop-flatten-types-removeMappedTypes
(since v2.4.0)
All types for which map entries have been declared in the configuration of the flattener transformation are removed at the end of processing rule-trf-prop-flatten-types.
rule-trf-prop-optionality
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) |
rule-trf-prop-remove-name-and-code-component
(Alias: rule-trf-prop-remove-name-and-alias-component)
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. |
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.
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 |
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:
- rule-trf-all-removeType
- rule-trf-cls-dissolve-mixins
- rule-trf-prop-removeObjectToFeatureTypeNavigability
- rule-trf-all-removeFeatureTypeRelationships
- rule-trf-prop-removeNavigabilityBasedOnIsFlatTarget
- rule-trf-all-flatten-constraints
- rule-trf-all-flatten-removeConstraints
- rule-trf-prop-flatten-codelists
- rule-trf-prop-flatten-ONINAs
- rule-trf-prop-optionality
- rule-trf-all-flatten-type-mapToSimpleBaseType
- rule-trf-cls-flatten-inheritance
- req-flattener-flattenTypes-identify-circular-dependencies
- rule-trf-prop-flatten-multiplicity
- rule-trf-cls-replace-with-union-properties
- rule-trf-prop-flatten-types
- rule-trf-all-flatten-name
- rule-trf-prop-remove-name-and-code-component
- rule-trf-prop-flatten-homogeneousgeometries
- rule-trf-cls-remove-inheritance-relationship
- rule-trf-cls-flatten-geometryTypeInheritance
- rule-trf-prop-flatten-measure-typed-properties
- rule-trf-prop-flatten-directposition-typed-properties
- rule-trf-prop-flatten-mediatype-typed-properties
- rule-trf-prop-flatten-explicit-time-interval
- rule-trf-cls-flatten-reverse-inheritance
- rule-trf-cls-non-default-geometry-to-feature-type
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
basicTypeSupertypeNames
Alias: none
Type: (comma separated) list of Strings
Default Value: Character, CharacterString, Number, Real, Integer, Decimal, Date, DateTime, Boolean, Measure, Length, Distance, Area, Velocity, Volume
Behavior: Identifies the types within the conceptual model that are supertypes of basic types defined in application schemas. Such basic types will not be processed by rule-trf-cls-flatten-reverse-inheritance.
Applies to Rule(s):
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
descriptorModification_geometryTypeAlias
(since v2.4.0)
Alias: none
Type: structured string; sequence of descriptors with separator value in curly braces; each item of the sequence should satisfy the following regular expression: (\w+)\{([^}]+)}
Default value: none
Behavior
Defines the geometry type suffix to append to specific descriptors of a geometry type specific feature copy. The separator is defined via the configuration parameter descriptorModification_geometryTypeSuffixSeparator. The parameter value lists descriptors, each with a list of suffixes for specific geometry types.
By default, the geometry type suffix is defined by param attributes of map entries. If one of these suffixes is defined for a descriptor by the descriptorModification_geometryTypeAlias parameter, then the according value is used as suffix instead.
Example
<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"/> </mapEntries>
<ProcessParameter name="descriptorModification_geometryTypeAlias"
value="alias{P=Point,C=Curve,S=Surface}"/>
This will result in the alias of feature types with point geometry having the suffix “Point” instead of just “P”.
Applies to Rule(s)
- rule-trf-prop-flatten-homogeneousgeometries
descriptorModification_geometryTypeSuffixSeparator
(since v2.4.0)
Alias: none
Type: structured string; sequence of descriptors with separator value in curly braces; each item of the sequence should satisfy the following regular expression: (\w+)\{([^}]+)}
Default value: none
Behavior
Use this parameter for appending a geometry type suffix to specific descriptors of a geometry type specific feature copy, with a descriptor specific separator. The parameter value lists descriptors to which the geometry type suffix shall be appended. For each such descriptor, the separator is contained in curly braces (that directly follow the descriptor name).
By default, the geometry type suffix is defined by param attributes of map entries. The suffix to use for specific geometry types can be configured per descriptor via the parameter descriptorModification_geometryTypeAlias.
Example
<ProcessParameter name="descriptorModification_geometryTypeSuffixSeparator" value="alias{ : } definition{ : }"/>
Applies to Rule(s)
- rule-trf-prop-flatten-homogeneousgeometries
descriptorModification_nonUnionSeparator
(since v2.4.0)
Alias: none
Type: structured string; sequence of descriptors with separator value in curly braces; each item of the sequence should satisfy the following regular expression: (\w+)\{([^}]+)}
Default value: none
Behavior
Use this parameter for merging specific descriptors – with a descriptor specific separator – when flattening the property of a non-union type into another type. The parameter value lists descriptors that shall be merged. The global identifier is always merged (with “.” as separator, if nothing specific is configured). For each such descriptor, the separator is contained in curly braces (that directly follow the descriptor name).
If one or both of the descriptors from the two properties – one being a property of the non-union type and one being the property that has the non-union type as value type – do not have a value, then the descriptors are not merged. Instead, if a descriptor is available, it is used as-is.
Example
<ProcessParameter name="descriptorModification_nonUnionSeparator" value="documentation{ : }, alias{ : }, definition{ : }, description{ : }, primaryCode{ : }"/>
Applies to Rule(s)
- rule-trf-prop-flatten-types
descriptorModification_propertyIndexNumberSeparator
(since v2.4.0)
Alias: none
Type: structured string; sequence of descriptors with separator value in curly braces; each item of the sequence should satisfy the following regular expression: (\w+)\{([^}]+)}
Default value: none
Behavior
Use this parameter for appending the index number to specific descriptors, with a descriptor specific separator. The parameter value lists descriptors to which the index number shall be appended. For each such descriptor, the separator is contained in curly braces (that directly follow the descriptor name).
Example
<ProcessParameter name="descriptorModification_propertyIndexNumberSeparator" value="alias{ - } definition{ : }"/>
Applies to Rule(s)
- rule-trf-prop-flatten-multiplicity
descriptorModification_unionSeparator
(since v2.4.0)
Alias: none
Type: structured string; sequence of descriptors with separator value in curly braces; each item of the sequence should satisfy the following regular expression: (\w+)\{([^}]+)}
Default value: none
Behavior
Use this parameter for merging specific descriptors – with a descriptor specific separator – when flattening the property of a union type into another type. The parameter value lists descriptors that shall be merged. The global identifier is always merged (with “.” as separator, if nothing specific is configured). For each such descriptor, the separator is contained in curly braces (that directly follow the descriptor name).
If one or both of the descriptors from the two properties – one being a property of the union type and one being the property that has the union type as value type – do not have a value, then the descriptors are not merged. Instead, if a descriptor is available, it is used as-is.
Example
<ProcessParameter name="descriptorModification_unionSeparator" value="documentation{ : }, alias{ : }, definition{ : }, description{ : }, primaryCode{ : }"/>
Applies to Rule(s)
- rule-trf-prop-flatten-types
directPositionRsidSuffix
Alias: none
Type: String
Default value: _srsName
Behavior
Defines the suffix of the new property that is created with rule rule-trf-prop-flatten-directposition-typed-properties-add-rsid-property.
Applies to Rule(s)
- rule-trf-prop-flatten-directposition-typed-properties-add-rsid-property
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
fixedUomPropertyDefinitions
(since v2.10)
Alias: none
Type: (comma separated) list of Strings
Default Value: none
Behavior: Identifies the which properties have fixed unit of measure, and which suffix to append to the name of such a property. Each string value is a key-value-pair (separator is ‘=’), where the key either is a property name (if all properties of that name with a relevant measure type shall receive that suffix) or a combination of class name, “.”, and property name (if the key-value-pair only applies to the property of a specific class).
Example: Feature1.angle = _deg, length=_m
Applies to Rule(s)
- subrule rule-trf-prop-flatten-measure-typed-properties-fixed-uom-suffix of rule-trf-prop-flatten-measure-typed-properties
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.
NOTE: If you only want to flatten a certain set of data types from the schemas selected for processing, then you can use ‘negative lookahead’ in the regular expression to actually ensure that these types are flattened, but the other data types are excluded. For example, if the data types CountInterval, IntegerInterval, and CurrencyValue shall be flattened, but no other data type, use the following regular expression: ^(?!(CountInterval|IntegerInterval|CurrencyValue)).+$
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
flattenTypesPropertyCopyDuplicateBehavior
Alias: none
Type: Enumeration: “IGNORE” or “OVERWRITE”
Default Value: IGNORE
Behavior
Defines the behavior for copying a property – while flattening types – from class A to class B, and class B already has a property with the same name. Available behaviors are:
- IGNORE: The property from class A shall be ignored. The property from class B is kept.
- OVERWRITE: The property from class A shall overwrite the property from class B.
Applies to Rule(s)
- rule-trf-prop-flatten-types
geometryTypeRegex
(since v2.10)
Alias: none
Type: String (with Java compliant regular expression)
Default Value: ^GM_.*
Behavior: If the name of the value type of a property matches the regular expression, then the property is considered to be a geometric property.
Applies to Rule(s)
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
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
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
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
linkedDocumentPagebreak
(since v2.5.0)
Required / Optional: optional
Type: Boolean
Default Value: false
Explanation: If set to true, a pagebreak will be added between two linked documents that are merged.
Applies to Rule(s): rule-trf-cls-flatten-inheritance-mergeLinkedDocuments
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
measureTypes
(since v2.10)
Alias: none
Type: (comma separated) list of Strings
Default Value: Angle, AngularSpeed, Area, Currency, Distance, Length, Measure, Scale, Speed, TimeMeasure, Volume, Weight
Behavior: Defines the names of the types that are measures, to be processed by rule-trf-prop-flatten-measure-typed-properties.
Applies to Rule(s)
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
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
simpleBaseTypes
(since v2.4.0)
Type: Comma separated list of strings
Default Value: “CharacterString, Integer, Measure, Real”
Behavior
List of names of types that represent simple base types.
Applies to Rule(s)
- rule-trf-all-flatten-type-mapToSimpleBaseType
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
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
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.
typeEnumerationPropertyName
(since v2.10)
Alias: none
Type: String
Default Value: “_type”
Behavior: The name of the new property that is added to a root class in rule-trf-cls-flatten-reverse-inheritance, with value type being the enumeration that lists all the non-abstract types that the root class can represent.
Applies to Rule(s):
typeSuffixSeparator
(since v2.10)
Alias: none
Type: String
Default Value: “_”
Behavior: The separator to use when appending the name/code of a subtype to the name/code of a property that is moved by rule-trf-cls-flatten-reverse-inheritance to a supertype.
Applies to Rule(s):
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>