(since v2.4.0)

1. Introduction

The ProfileLoader transformation loads profiles (typically defined using the ShapeChange Profile Management Tool (PMT)) into the model that is processed by ShapeChange.

2. Description

The ProfileLoader can load a set of profiles – contained in model files that have the ShapeChange specific XML format (SCXML - which can be produced using the Model Export target) – into the model that is being processed by the transformation. The model files must be contained in a specific directory (specified via parameter directoryWithProfilesToLoad) and can be selected via a regular expression that matches the file name, including the file extension (the regular expression is given via parameter regexToFilterProfilesToLoad).

As a pre-processing step, the ProfileLoader can delete the profiles in the input model, thus creating a clean slate for loading the external profiles (see rule-trf-profileLoader-preProcessing-deleteInputModelProfiles). The ProfileLoader can also validate the profile definitions in the input model (see rule-trf-profileLoader-preProcessing-validateInputModelProfiles).

The ProfileLoader must consider the way that profiles are defined in the input model. ShapeChange supports two profile definition behaviors: explicit and non-explicit. Since profile definitions in the external model files that are loaded by the ProfileLoader are explicit (the SCXML format requires explicit profiles), an input model with non-explicit profile definitions must be converted – unless profiles of the input model are deleted during pre-processing. By default, the ProfileLoader transformation assumes that the profile definitions in the model are explicit. By setting parameter profilesInModelSetExplicitly to false, the transformation can be configured to convert profile definitions. In that case, the transformation will then gather the names of all profiles defined in the input model, and assign this set of profiles to each class without a profile assignment. Alternatively, the profile names can explicitly be configured via the configuration parameter profilesForClassesWithoutExplicitProfileAssignments. Properties without profile assignment receive the profiles of their class.

For each external model file with profiles, the ProfileLoader:

  • Can validate the profile definitions in the model file (see rule-trf-profileLoader-validateLoadedModelProfiles). Inconsistencies will be reported in the log.

  • Can compute differences between the input model and the model contained in the model file (see rule-trf-profileLoader-diffModels). Which differences shall be checked can be configured via parameter diffElementTypes. Detected differences will be reported in the log. This can help identify potential inconsistencies that may be introduced while loading profile definitions, due to different model and schema versions.

  • Loads the profiles from the model file into the input model. Profiles that already exist in the input model are overwritten, for model elements that can be found in the input model and in the model file. The parameter profilesToLoad can be used to restrict the set of profiles that are loaded.

Finally, the ProfileLoader can validate the profiles in the resulting model (see rule-trf-profileLoader-postProcessing-validateResultingModelProfiles).

Note
By default, the ProfileLoader only processes the profiles of classes (and their properties) from schemas that are selected for processing. If the parameter processAllSchemas is set to true, classes (and their properties) from all schemas are processed.

3. Configuration

3.1. Class

The class for this transformer implementation is de.interactive_instruments.ShapeChange.Transformation.Profiling.ProfileLoader

3.2. Transformation Rules

3.2.1. rule-trf-profileLoader-preProcessing-deleteInputModelProfiles

If this rule is enabled, the tagged value 'profiles' as well as the profile information parsed from that tagged value are removed from all classes and properties of the input model.

Note
This can be useful to create a 'clean slate' before loading profiles into the model.

3.2.2. rule-trf-profileLoader-preProcessing-validateInputModelProfiles

If this rule is enabled, the profiles defined in the input model are validated during the pre-processing phase. This validation will not occur if all profile information is removed in the input model via rule-trf-profileLoader-preProcessing-deleteInputModelProfiles.

3.2.3. rule-trf-profileLoader-diffModels

If this rule is enabled, differences between a loaded model and the input model are logged. Differences are computed for either all or only selected schemas (for further details, see parameter processAllSchemas). The schema version, if defined, is always checked. Additional checks, more specifically the types of differences, can be configured via parameter diffElementTypes. This rule supports the identification of potential consistency issues of resulting profiles, due to differences between loaded models and the input model.

3.2.4. rule-trf-profileLoader-validateLoadedModelProfiles

If this rule is enabled, the profiles in each external model are validated after that model has been loaded. The validation takes place before the profiles are loaded into the input model. This rule supports the identification of potential consistency issues with the profiles of loaded models.

3.2.5. rule-trf-profileLoader-postProcessing-validateResultingModelProfiles

If this rule is enabled, the profiles in the resulting model are validated during the post-processing phase (i.e., after profiles have been loaded).

3.3. Parameters

3.3.1. diffElementTypes

Required / Optional: optional

Type: String (with comma separated values)

Default Value: CLASS, ENUM, MULTIPLICITY, PROPERTY, NAME, STEREOTYPE, SUPERTYPE, SUBPACKAGE, VALUETYPE

Explanation: Comma-separated list of names of diff element types. The diff result will only provide information on these types of differences (in addition to a possibly existing schema version difference).

The following diff element types are currently supported: NAME, DOCUMENTATION, MULTIPLICITY, VALUETYPE, CLASS, SUPERTYPE, SUBPACKAGE, PROPERTY, ENUM, STEREOTYPE, TAG, ALIAS, DEFINITION, DESCRIPTION, PRIMARYCODE, GLOBALIDENTIFIER, LEGALBASIS, AAAMODELLART, AAAGRUNDDATENBESTAND

Applies to Rule(s): rule-trf-profileLoader-diffModels

3.3.2. directoryWithProfilesToLoad

Required / Optional: required

Type: String

Default Value: none

Explanation: The path to the folder that contains the profiles.

Applies to Rule(s): none – default behavior

3.3.3. processAllSchemas

Required / Optional: optional

Type: Boolean

Default Value: false

Explanation: By default, only the profiles of classes (and their properties) from schemas that are selected for processing are processed. If this parameter is set to true, classes (and their properties) from all schemas are processed.

Applies to Rule(s): none – default behavior

3.3.4. profilesForClassesWithoutExplicitProfileAssignments

Required / Optional: optional

Type: String (with comma separated values)

Default Value: all profiles defined in the input model

Explanation: Comma-separated list of names of profiles that will be set for input model classes that do not belong to a specific profile. This is relevant while pre-processing the input model in case that the profiles are not set explicitly in the input model (parameter profilesInModelSetExplicitly is false).

Applies to Rule(s): none – default behavior

3.3.5. profilesInModelSetExplicitly

Required / Optional: optional

Type: Boolean

Default Value: true

Explanation: Indicates if profile definitions in the input model are explicitly set (true) or not (false). If they are not, then profile inheritance would apply, which must be converted before loading (also see parameter profilesForClassesWithoutExplicitProfileAssignments).

Applies to Rule(s): none – default behavior

3.3.6. profilesToLoad

Required / Optional: optional

Type: String (comma separated list of values)

Default Value: all profiles

Explanation: Names of profiles to be loaded into the input model.

Applies to Rule(s): none – default behavior

3.3.7. regexToFilterProfilesToLoad

Required / Optional: optional

Type: String (with regular expression)

Default Value: .*(\.xml|\.zip)$

Explanation: By default, the ProfileLoader loads all XML and ZIP files in the directory that is stated by the transformation parameter directoryWithProfilesToLoad (excluding subdirectories). That behavior can be changed to only use the files from that directory whose name matches the regular expression given by the parameter regexToFilterProfilesToLoad.

Applies to Rule(s): none – default behavior

4. Configuration Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<Transformer class="de.interactive_instruments.ShapeChange.Transformation.Profiling.ProfileLoader"
  id="INPUT" mode="enabled">
  <parameters>
   <ProcessParameter name="directoryWithProfilesToLoad" value="model/v1/profiles"/>
   <ProcessParameter name="regexToFilterProfilesToLoad" value="profileA.xml"/>
   <ProcessParameter name="profilesInModelSetExplicitly" value="false"/>
   <ProcessParameter name="profilesForClassesWithoutExplicitProfileAssignments" value="A"/>
   <ProcessParameter name="processAllSchemas" value="true"/>
  </parameters>
  <rules>
   <ProcessRuleSet name="profileLoading">
    <rule name="rule-trf-profileLoader-preProcessing-validateInputModelProfiles"/>
    <rule name="rule-trf-profileLoader-validateLoadedModelProfiles"/>
    <rule name="rule-trf-profileLoader-diffModels"/>
    <rule name="rule-trf-profileLoader-postProcessing-validateResultingModelProfiles"/>
   </ProcessRuleSet>
  </rules>
 </Transformer>