1. General Information
The primary target of ShapeChange are GML application schemas, represented as a set of XML Schema documents. However, there are other targets that ShapeChange may be configured to produce. The targets are described here, both conceptually (the specifications underlying each target) and practically (how ShapeChange may be configured to produce each form of output).
1.1. Encoding Rules
An encoding rule, as defined in ISO 19118:2005, is an "identifiable collection of conversion rules" that "is applied to application schema specific data structures to produce system-independent data structures suitable for transport or storage" (ISO 19118:2005, section 6.4.1). Both input and output data structures are specified in a schema language, such as UML or XML Schema; accordingly, an encoding rule includes a schema conversion rule.
The encoding rule concept drives ShapeChange: the conversion from an application schema in UML to another data structure is (broadly) driven by a set of rules, encapsulated by the internal code of the classes in the Target packages.
The ShapeChange configuration framework contains provisions for specifying which of a set of possible encoding rules applies to a particular transformation, with the ability for an application schema in UML to support multiple encoding rules for different "platforms" or targets. For example, the XML Schema target allows for detailled customization of the encoding rule.
1.2. Java Implementation Details
Within the ShapeChange Java framework, each target/output format definition is implemented as a Java class. In keeping with the modularity of ShapeChange, each such target implements the de.interactive-instruments.ShapeChange.Target.Target interface, which contains method "hooks" for the various steps in the output process- initializing the target, processing each class in the application schema appropriately for the target type, and finally writing the output to one or more files (XSD, HTML or other file). The fully-qualified name of this class must be provided in the configuration file.
1.3. Configuration
Each individual target for a run of ShapeChange is defined in the configuration file as its own <Target> element. All <Target> definitions are nested under the <targets> element.
All <Target> definitions, no matter the actual target type, are configured via XML attributes and parameters. <MapEntry> definitions may also be used to customize mappings.
1.3.1. Target Attributes
Each <Target> element has three attributes, one required and two optional. These attributes are as follows:
Attribute Name |
Required / Optional |
Default Value |
Explanation |
class |
Required |
- |
A string representing a fully-qualified target "handler" class (an implementation of the Target interface). |
mode |
Optional |
enabled |
Whether or not this particular target is "turned on". This allows for multiple targets to be specified in a configuration file, and turned on/off at will. The possible values are:
|
inputs |
Optional |
defaults to the input model |
A (space-separated list of) identifiers, referencing the id of transformers and/or the input model. If multiple identifiers are provided, the target is executed for the output model of each referenced transformer and/or the input model. If the attribute is omitted then the target is applied on the input model. |
1.3.2. Target Parameters
In addition to the required attributes, each <Target> may have additional parameters defined via <targetParameter> elements.
Each target type may define its own expected or required parameters; the target-specific subheadings of the subpages will describe these for each target type.
ShapeChange also supports a set of common tasks to process output files that were generated by a target. Further details, including the parameters to control the output processing, are described in the section Common Output Processing.
1.3.3. Map Entries
The <mapEntries> section of the <Target> element may contain a series of <MapEntry> definitions.
Map entries allow for customized mapping from UML classes to target elements, by enabling the specification of generic "rules".
The attributes of a <MapEntry> are as follows:
| Attribute Name | Explanation |
|---|---|
type |
(Required) The UML type/class name to be mapped.. |
rule |
(Required) The "rule" for the mapping. This is a freeform String field; the interpretation of its value is left to the code implementing the target. |
targetType |
The type to which the type will be mapped. The interpretation of its value is left to the code implementing the target. |
param |
An optional parameter for the mapping. The interpretation of its value is left to the code implementing the target. |
A sample <mapEntries> element is given below (for a FME target that is part of an extension to ShapeChange):
1
2
3
4
5
6
7
8
<mapEntries>
<!-- 19107 to FME geometry types -->
<MapEntry rule="FME" targetType="*" type="GM_Primitive"/>
<MapEntry param="fme_point" rule="FME" targetType="fme_point" type="GM_Point"/>
<MapEntry param="fme_line,fme_aggregate" rule="FME" targetType="fme_line" type="GM_Curve"/>
<MapEntry param="fme_polygon,fme_donut,fme_aggregate" rule="FME" targetType="fme_area"
type="GM_Surface"/>
</mapEntries>
2. Selecting the Schemas to Process
When processing a model, the default behavior of ShapeChange is to process all schemas contained in that model. The typical use case, however, is that a specific (set of) application schema(s) shall be processed, and that other schemas - like the ISO schemas – merely provide type definitions. The following configuration parameters are used to select the set of schemas to process: appSchemaName, appSchemaNameRegex, and appSchemaNamespaceRegex. They are typically set in the input configuration, and that is the default place for ShapeChange to look for them. However, a target configuration can also define one or more of these parameters. If it does, then ShapeChange will use the parameters from the target configuration, rather than the input configuration, to select the schemas to be processed by the target.
3. Common Output Processing
The following list of common processing tasks can be applied to output files created by a target:
-
modifying the file name
-
adding a generation comment to the content of the file
-
applying an XSL transformation to the file
|
Note
|
The tasks are performed by ShapeChange in the given order. |
The target parameters to control the output processing are documented in detail in the following sections.
3.4. Parameters
3.4.1. processOutput_addComment
(available since v2.4.0)
Type: Boolean
Default Value: false
Explanation: If set to "true", a comment will be added to output files (with one of the following file extensions: xml, xsd, rdf, owl, sch, trix, sql, ddl, ttl, nt, trig, nq, json). The comment is given via parameter processOutput_comment.
The comment syntax depends upon the file extension:
-
xml|xsd|rdf|owl|sch|trix: An XML comment is created.
-
sql|ddl: The comment line starts with '-- '.
-
ttl|nt|trig|nq: The comment line starts with '# '.
-
json: The comment is encoded as a JSON member with key "$comment" (defined by the JSON Schema specification).
Applies to:
3.4.2. processOutput_applyXslt
(available since v2.4.0)
Type: Boolean
Default Value: false
Explanation: If set to "true", an XSL transformation will be applied to output files created by the target, with one of the following file extensions: xml, xsd, rdf, owl, sch, trix, html, sql, ddl, ttl, nt, trig, nq. Default is "false".
Applies to:
3.4.3. processOutput_comment
(available since v2.4.0)
Type: String
Default Value: Last modified date of the output file, formatted according to yyyyMMdd, followed by the schema version if appropriate (target is a) either not a SingleTarget, or a SingleTarget and a main schema has been defined – see mainAppSchema parameter - or only a single schema is processed by ShapeChange, and b) the target is not a DeferrableOutputWriter (like the FeatureCatalogue target), and a link to shapechange.net. Example: Created by ShapeChange on 20170818 from application schema version 1.1 - https://shapechange.net/.
Explanation: Comment to add to the content of output files (see parameter processOutput_addComment). If no value is provided for this parameter, the default value applies (i.e., the comment will be auto-generated).
Applies to:
3.4.4. processOutput_fileNamePrefix
(available since v2.4.0)
Type: String
Default Value: Last modified date of the output file, formatted according to yyyyMMdd, followed by the schema version if appropriate (target is a) either not a SingleTarget, or a SingleTarget and a main schema has been defined – see mainAppSchema parameter - or only a single schema is processed by ShapeChange, and b) the target is not a DeferrableOutputWriter (like the FeatureCatalogue target), and a link to shapechange.net. Example: 20170818.v1.1.s1.xsd
Explanation: Prefix to add to the name of output files (see parameter processOutput_modifyFileName). If no value is provided for this parameter, the default value applies (i.e., the prefix will be auto-generated).
Applies to:
3.4.5. processOutput_modifyFileName
(available since v2.4.0)
Type: Boolean
Default Value: false
Explanation: If set to "true", the name of output files will be augmented with a prefix. The prefix is given via parameter processOutput_fileNamePrefix.
Applies to:
3.4.6. processOutput_xslt_outputSuffix
(available since v2.4.0)
Type: String
Default Value: "_transformed.xml"
Explanation: Define the suffix to append to base names of files (i.e. the file name without file extension) created by applying an XSL transformation to output files. The suffix is required to identify the intended type of output files. For example, if an XML Schema file is transformed, the result could be an XML Schema but also an XML file. If the suffix is set to the same file extension as the input file of the transformation (e.g. ".xsd" when processing an XML Schema file), the input file will be overwritten.
Applies to:
3.4.7. processOutput_xslt_deleteInputFilesAfterTransformation
(available since v2.4.0)
Type: Boolean
Default Value: false
Explanation: If set to "true", the input file of an XSL transformation (that is applied to output files created by a target) will be deleted - unless the result file of the transformation has overwritten the input file.
Applies to:
3.4.8. processOutput_pathToXsltDirectory
(available since v2.4.0)
Type: String
Default Value: "." (i.e. the current run directory)
Explanation: Path to the directory that contains the XSL transformation file(s). Can be an HTTP URL.
Applies to:
3.4.9. processOutput_xsltFileName
(available since v2.4.0)
Type: String
Default Value: none
Explanation: Name of the XSL transformation file to apply. The file must be contained in the directory identified by parameter processOutput_pathToXsltDirectory.
Applies to:
3.4.10. xslTransformerFactory
(available since v2.4.0)
Type: String
Default Value: none
Explanation: Identifies the XSLT processor implementation, to be used for processing output files (see parameter processOutput_applyXslt). In order to process XSLT transformations with version 2.0 or higher, this parameter should point to the implementation of an XSLT processor that is capable of processing such XSLTs, for example Saxon-HE (home edition; open source):
-
sf.saxon.TransformerFactoryImpl
-
NOTE: Download the Saxon HE jar from the official maven repository. Each release of ShapeChange uses a specific version of Saxon HE. The table in the Release Notes indicates which version is needed for the ShapeChange release that you are using. Copy the Saxon HE jar to the lib folder of your ShapeChange distribution.
-
Applies to:
3.5. Configuration Example
1
2
3
4
5
6
7
8
9
10
11
12
13
<TargetXmlSchema class="de.interactive_instruments.ShapeChange.Target.XmlSchema.XmlSchema"
inputs="trf" mode="enabled">
<targetParameter name="processOutput_modifyFileName" value="true"/>
<targetParameter name="processOutput_addGenerationComment" value="true"/>
<targetParameter name="processOutput_applyXslt" value="true"/>
<targetParameter name="processOutput_xslt_outputSuffix" value="_transformed.xsd"/>
<targetParameter name="processOutput_pathToXsltDirectory"
value="src/test/resources/outputProcessing/xslt"/>
<targetParameter name="processOutput_xsltFileName" value="onlyRoot_transformation.xsl"/>
<targetParameter name="processOutput_xslt_deleteInputFilesAfterTransformation" value="false"/>
<targetParameter name="xslTransformerFactory" value="net.sf.saxon.TransformerFactoryImpl"/>
<!-- ... other target parameters (like outputDirectory and defaultEncodingRule), rules, map entries etc. ... -->
</TargetXmlSchema>
4. Supported Target Types
A list of the currently supported targets is given here.