Difference between revisions of "XML Data mapper"

From GreenVulcano Wiki
Jump to: navigation, search
(Creating additional nodes)
(Links)
 
(57 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
==Introduction==
 
==Introduction==
XML Data mapper module allows users to implement a data transformation from one format defined by a source xsd to a format defined by a target xsd, and to create xsl documents in a data transformation defined in [[{{VULCON}}]].
+
XML Data mapper module allows users to design a XSL data transformation from one XML document, defined by a source xsd, to another XML document, defined by a target xsd. The designer output is a XSL document associated to a data transformation defined in [[{{VULCON}}]].
The use of graphics speeds up the process of defining the mapping of data, and gives it a simple and efficient graphical representation.
+
The use of a graphical designer speeds up the process of defining the data mapping, and gives it a simple and efficient graphical representation.
 +
 
 +
(in the examples the output namespaces have been removed for clarity)
  
 
==Create a data transformation==
 
==Create a data transformation==
The steps required to create a graphical form of data transformation are:
+
The steps required to create a graphical data transformation are:
 +
*Verify that the XSD documents describing the source/target XMLs are present in the /conf/xsds folder
 
*Access the {{VULCON}} Core view and expand the GVDataTransformation node
 
*Access the {{VULCON}} Core view and expand the GVDataTransformation node
 
*Click on Transformations item with right mouse button and choose in the drop-down list
 
*Click on Transformations item with right mouse button and choose in the drop-down list
Line 10: Line 13:
 
Transformations --> Create XSLT Transformation
 
Transformations --> Create XSLT Transformation
 
</syntaxhighlight>
 
</syntaxhighlight>
*Using the appearing wizard, insert the data transformation definition parameters:
+
*Populate the wizard parameters:
**Transformation Name: a configuration file with .gvxdt extension and a xsl transformation file with .xsl extension will be created with the name choosen in this field
+
**Transformation Name: the name by which the transformation is referenced by {{GVESB}} Core. Is also the name of the editor configuration file with .gvxdt extension and of the XSL transformation file with .xsl extension
**Data Source: the datasource name that indicates the repository where files will be deposited
+
**Data Source: the data source name that indicates the DTE repository where files will be created
**Path XSL: internal del datasource path in which the xsl file will be generated
+
**Path XSL: sub-folders of the selected data source path in which the XSL file will be generated
**XSD Input: xsd file name defining the source format
+
**XSD Input: XSD file name defining the source document. The files suggested by the drop-down list must be stored in the /conf/xsds folder
**root XSD Input: source xsd file root element name from which start the data transformation operation. Xsd files suggested by the drop-down list are stored in the /conf/xsds folder
+
**root XSD Input: root element of the source XML document from which start the data transformation operation
**XSD Output: xsd file name defining the target format
+
**XSD Output: XSD file name defining the target document. The files suggested by the drop-down list must be stored in the /conf/xsds folder
**root XSD Output: target xsd file root element name from which start the data transformation operation. Xsd files suggested by the drop-down list are stored in the /conf/xsds folder
+
**root XSD Output: root element of the target XML document
*Click the wizard Finish button: in [[Graphic Editor]] [[{{VULCON}} perspective]] will appear the [[#Data mapper graphic editor|Data mapper graphic editor]].
+
*Click the Finish button: in [[Graphic Editor]] [[{{VULCON}} perspective]] will appear the [[#Data mapper graphic editor|Data mapper graphic editor]] in which in possible to design the transformation
===Data mapper graphic editor===
+
*[[#Xsl file generation|Generate]] the resultant XSL file.
 +
==Data mapper graphic editor==
 
[[File:DataMapper.png|thumb|Data Mapper]]
 
[[File:DataMapper.png|thumb|Data Mapper]]
In Data mapper graphic editor are visible the representations for input and output formats.Items followed by '=' character are attributes, while those enclosed in angle brackets '<>' are nodes of the xml data. Is it possible to compress or expand simply by clicking on '+' or '-' symbols on the left of each node name.
+
In Data mapper graphic editor are visible the representations for input and output formats.Items followed by '=' character are attributes, while those enclosed in angle brackets '<>' are nodes of the XML document. Is it possible to collaps or expand child nodes simply by clicking on '+' or '-' symbols on the left of each node name.
The right pane contains the palettes used for the definition of the data mapping.  
+
The right panel contains the palettes used for the definition of the data mapping functions.  
 
The Select button allows the selection of the xsd nodes interested for the transformation.  
 
The Select button allows the selection of the xsd nodes interested for the transformation.  
 
The Create link button allows to define [[#Links|links]]:
 
The Create link button allows to define [[#Links|links]]:
Line 30: Line 34:
 
*between the output of a function and a target element.
 
*between the output of a function and a target element.
 
In the folders below that buttons, it is possible to access the [[#Functions|functions]] used for data-mapping grouped by topic.
 
In the folders below that buttons, it is possible to access the [[#Functions|functions]] used for data-mapping grouped by topic.
 +
 +
===Open editor===
 +
To open the editor you can:
 +
*double click a .gvxdt file previously created in the Project view;
 +
*right-clicking on the XSLTransformation in the core view and then choosing the 'Open mapping <transformation name>' item.
 +
===Import Function===
 +
The import function is a top-level element that is used to import the contents of one style sheet into another.
 +
Is it possible to assign a value to a parameter of an imported stylesheet.
 +
 +
Parameter:
 +
*uri: attribute whose value is a URI reference identifying the stylesheet to be imported
 +
*param-name: parameter of imported stylesheet (otional)
 +
 +
[[File:Import.png|thumb|Import Function without parameter]]
 +
<syntaxhighlight lang="xml">
 +
  <?xml version="1.0" encoding="UTF-8"?>
 +
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 +
        exclude-result-prefixes="xsl fs" version="2.0"
 +
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
 +
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
 +
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
 +
    <xsl:import href="getPerson.xsl"/>
 +
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
 +
            <xsl:element name="persona"
 +
                        namespace="http://www.greenvulcano.it/greenvulcano">
 +
                <xsl:apply-imports/>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template>
 +
</xsl:stylesheet>
 +
</syntaxhighlight>
 +
 +
[[File:ImportWithParam.png|thumb|Import Function with parameter]]
 +
<syntaxhighlight lang="xml">
 +
  <?xml version="1.0" encoding="UTF-8"?>
 +
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 +
          exclude-result-prefixes="xsl fs" version="2.0"
 +
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
 +
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
 +
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
 +
    <xsl:import href="getPerson.xsl">
 +
        <xsl:with-param name="param" select="/RowSet/data/row/col[1]"/>
 +
    </xsl:import>
 +
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
 +
            <xsl:element name="persona"
 +
                        namespace="http://www.greenvulcano.it/greenvulcano">
 +
                <xsl:apply-imports/>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template>
 +
</xsl:stylesheet>
 +
</syntaxhighlight>
  
 
===Links===
 
===Links===
 
A link is a relation between the node in the source format and its counterpart in the target format.
 
A link is a relation between the node in the source format and its counterpart in the target format.
Clicking the Create link button in the Palette pane, link mode is enabled. In this mode is possible creating a new connection simply clicking on a node in the source xsd format, and dragging it on a target node.
+
Clicking the Create link button in the Palette pane, link mode is enabled. In this mode is possible to create new connection simply clicking on a node in the XSD source model, and dragging it on a target node.
Once defined a new connection in the graphic area, properties of the selected object are shown in Properties area.
+
Once defined a new connection in the graphic area, its properties are shown in Properties area.
 
'Match' property allows the definition of the selected mapping generation mode:
 
'Match' property allows the definition of the selected mapping generation mode:
*template: a template node will be created e called into the mapping;
+
*template: a template node will be created, activated by the source element
*for-each: a for-each node will be created to generate all defined mapping.
+
*for-each: a for-each node will be created to process iteratively the source element
 +
*none: has not created any link
 +
[[File:LinkTemplate.png|thumb|Link complex node with parameter template]]
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
<syntaxhighlight lang="xml">
 +
  <?xml version="1.0" encoding="UTF-8"?>
 +
      <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 +
          exclude-result-prefixes="xsl fs" version="2.0"
 +
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
 +
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
 +
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
 +
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
 +
            <xsl:apply-templates select="/RowSet/data"/>
 +
        </xsl:element>
 +
    </xsl:template>
 +
    <xsl:template match="/RowSet/data">
 +
        <xsl:element name="persona" namespace="http://www.greenvulcano.it/greenvulcano">
 +
            <xsl:element name="cognome"
 +
                        namespace="http://www.greenvulcano.it/greenvulcano">
 +
                <xsl:value-of select="row/col[1]"/>
 +
            </xsl:element>
 +
            <xsl:element name="nome" namespace="http://www.greenvulcano.it/greenvulcano">
 +
                <xsl:value-of select="row/col[2]"/>
 +
            </xsl:element>
 +
            <xsl:element name="citta" namespace="http://www.greenvulcano.it/greenvulcano">
 +
                <xsl:value-of select="row/col[3]"/>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template>
 +
  </xsl:stylesheet>
 +
</syntaxhighlight>
 +
 
 +
[[File:LinkForEach.png|thumb|Link complex node with parameter template]]
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
<syntaxhighlight lang="xml">
 +
  <?xml version="1.0" encoding="UTF-8"?>
 +
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 +
        exclude-result-prefixes="xsl fs" version="2.0"
 +
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
 +
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
 +
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
 +
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
 +
            <xsl:for-each select="/RowSet/data">
 +
                <xsl:element name="persona"
 +
                            namespace="http://www.greenvulcano.it/greenvulcano">
 +
                    <xsl:element name="cognome"
 +
                                namespace="http://www.greenvulcano.it/greenvulcano">
 +
                        <xsl:value-of select="row/col[1]"/>
 +
                    </xsl:element>
 +
                    <xsl:element name="nome"
 +
                                namespace="http://www.greenvulcano.it/greenvulcano">
 +
                        <xsl:value-of select="row/col[2]"/>
 +
                    </xsl:element>
 +
                    <xsl:element name="citta"
 +
                                namespace="http://www.greenvulcano.it/greenvulcano">
 +
                        <xsl:value-of select="row/col[3]"/>
 +
                    </xsl:element>
 +
                </xsl:element>
 +
            </xsl:for-each>
 +
        </xsl:element>
 +
    </xsl:template>
 +
    </xsl:stylesheet>
 +
</syntaxhighlight>
 +
 
 +
Other Properties:
 +
*mode: allow an element to be processed multiple times, each time producing a different result.
 +
*condition: boolean condition applied to template, condition is a drop list of all the condition that have been defined in the transformation
 +
*priority: priority of a template rule is specified by the priority attribute on the template rule.
 +
 
 +
If you need to map the node and add a value you can use the link-and-value
 +
[[File:Link-and-value.png|thumb|Link complex node with parameter template]]
 +
 
 +
 
 +
 
 +
 
 +
 
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 +
      exclude-result-prefixes="xsl fs" version="2.0"
 +
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
 +
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
 +
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
 +
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
 +
            <xsl:element name="cliente">
 +
                <xsl:value-of select="col"/>
 +
                <xsl:element name="cognome"
 +
                            namespace="http://www.greenvulcano.it/greenvulcano">
 +
                    <xsl:value-of select="col[1]"/>
 +
                </xsl:element>
 +
                <xsl:element name="nome"
 +
                            namespace="http://www.greenvulcano.it/greenvulcano">
 +
                    <xsl:value-of select="col[3]"/>
 +
                </xsl:element>
 +
                <xsl:element name="citta"
 +
                            namespace="http://www.greenvulcano.it/greenvulcano"/>
 +
                <xsl:element name="nomecompleto"
 +
                            namespace="http://www.greenvulcano.it/greenvulcano">
 +
                    <xsl:value-of select="col[4]"/>
 +
                </xsl:element>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template>
 +
</xsl:stylesheet>
 +
</syntaxhighlight>
 +
 
 
===Functions===
 
===Functions===
To create a function you must select a function at the right of Graphic Editor and click in the space where you want to be created. For some functions you must define the format of the same being created, such as the "concat" string you must define how input parameters are needed for this. In this case will be presented with a window that requires the additional information requested. This value will be associated with a Property of the function can be created and modified in the lower box of the Property. To use the functions must then make the link to define the input parameters and the link to define which target element must be connected to the output of the function under consideration.
+
Folders on the right of Graphic Editor contains the most common used [http://www.w3schools.com/xpath/xpath_functions.asp XSLT and XPath functions], organized by topic.<br/>
 +
To use a function is sufficient to select it in the appropriate folder and then to click in the design area. For those functions which have a variable number of parameters, such as the 'concat' function, a dedicated pop-up will open. Once done this steps, a graphical representation of the new function will be shown in the design area.<br/>
 
[[File:DTEFunction.png|thumb|DTE Function]]
 
[[File:DTEFunction.png|thumb|DTE Function]]
If a parameter to a function you want to assign a constant value, right-click the parameter in question and choose the value to be determined. If you would need to use a feature not present in the default settings you can use a custom function that is accessed from its folder present in the Palette. When creating a custom function will be presented the new window where you go to add the following fields:
+
At this point you need to create all links to map the input parameters and the one to define the element that will assume the output value of the function.<br/>
*Name: name of the function to create (example: java:it.greenvulcano.gvesb.datahandling.utils.GenericRetriever.getData).
+
To give a constant value to a function parameter you must right-click on its graphical representation and then insert the value. To modify a parameter value simply set it in the corresponding property in the lower Property editor.<br/>
*Label: label displayed on the editor (example: getId).
+
If the desired function is not present inside function folders, it is possible to define it choosing from Custom folder. To do this you must enter values ​​in the following fields:
*Numarg: number of function arguments.
+
[[File:DTECustomFunction.png|thumb|DTE Custom Function]]
*Prefix: namespace prefix used by the function (example: java).
+
*Name: the name of the function to create (eg.: java:it.greenvulcano.gvesb.datahandling.utils.GenericRetriever.getData).
*Namespace: namespace of the function ( ''' Inserire il link --- nel DTE vecchio http://xml.apache.org/xalan/java)
+
*Label: the label displayed on the editor (eg.: getId).
===Creating additional nodes===
+
*Numarg: the number of function arguments.
Some changes need to create nodes by duplicating the basic knot. To realize this operation, simply select the node with the right base and create a new duplicate node. Alongside the new selected node will be reported on the value of the Ordinary, a node associated with the numeral represents the only instance of n-th (n par value of the numeral) of that node. while if not has the numeral is associated with a node that represents all the nodes of that type.
+
*Prefix: the namespace prefix used by the function (example: java).
 +
*Namespace: the namespace of the function (eg.: <nowiki>http://xml.apache.org/xalan/java</nowiki>)
  
 +
The following table presents some XSL helper classes, useful in XSL data manipulation:
 +
{|class="gvtable" style="width: 40%"
 +
! style="width: 20%" | Helper !! style="width: 75%" | Use this for ...
 +
|-
 +
| [[XSLHelper | XSLTUtils]] || manipulate date/time and strings
 +
|-
 +
| [[XSLHelper | GenericRetriever]] || query the database for data conversion
 +
|-
 +
| [[XSLHelper | JavaScriptRetriever]] || execute JavaScript code
 +
|}
  
 +
You can assign a constant value parameter of a function between right-clicking the mouse on the parameter
 +
===Conditional Processing with if===
 +
There are two ways to insert an if statement:
 +
*Using the if statement as function
 +
*Inserting the condition as a property of a link
 +
[[File:mappingif.png|thumb|if function]]
 +
If the function is used when you want to insert an condition mapping of a complex node.
 +
<syntaxhighlight lang="xml">
 +
      <xsl:element name="anagrafica">
 +
            <xsl:if test="/RowSet/data/row/col[1] = string(&apos;Romano&apos;)">
 +
                <xsl:for-each select="/RowSet/data/row/col[1]">
 +
                    <xsl:element name="cliente">
 +
                        <xsl:element name="cognome">
 +
                            <xsl:value-of select="concat(null,/RowSet/data/row/col[2],/RowSet/data/row/col[3])"/>
 +
                        </xsl:element>
 +
                        <xsl:element name="nome"/>
 +
                        <xsl:element name="citta"/>
 +
                        <xsl:element name="nomecompleto"/>
 +
                    </xsl:element>
 +
                </xsl:for-each>
 +
            </xsl:if>
 +
        </xsl:element>
 +
</syntaxhighlight>
 +
[[File:mappingif2.png|thumb|if function]]
 +
Use the property when you want to map a simple node
 +
<syntaxhighlight lang="xml">
 +
            <xsl:element name="cliente">
 +
                <xsl:if test="/RowSet/data/row/col[1] = &apos;Romano&apos;">
 +
                    <xsl:element name="cognome">
 +
                        <xsl:value-of select="/RowSet/data/row/col[1]"/>
 +
                    </xsl:element>
 +
                </xsl:if>
 +
            </xsl:element>
 +
        </xsl:element>
 +
</syntaxhighlight>
 +
 +
===Conditional Processing with choose===
 +
The choose element selects one among a number of possible alternatives.
 +
[[File:Choose.png|thumb|Choose]]
 +
<syntaxhighlight lang="xml">
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica">
 +
            <xsl:apply-templates select="/RowSet/data/row"/>
 +
        </xsl:element>
 +
    </xsl:template>
 +
    <xsl:template match="/RowSet/data/row">
 +
        <xsl:element name="cliente">
 +
            <xsl:choose>
 +
                <xsl:when test="position() = 1">
 +
                    <xsl:element name="cognome">
 +
                        <xsl:value-of select="col"/>
 +
                    </xsl:element>
 +
                </xsl:when>
 +
                <xsl:when test="col[1] = col[2]">
 +
                    <xsl:element name="cognome">
 +
                        <xsl:value-of select="col[1]"/>
 +
                    </xsl:element>
 +
                </xsl:when>
 +
                <xsl:when test="count(col) &gt; 0">
 +
                    <xsl:element name="cognome">
 +
                        <xsl:value-of select="col[3]"/>
 +
                    </xsl:element>
 +
                </xsl:when>
 +
                <xsl:otherwise>
 +
                    <xsl:element name="cognome">
 +
                        <xsl:value-of select="col[4]"/>
 +
                    </xsl:element>
 +
                </xsl:otherwise>
 +
            </xsl:choose>
 +
            <xsl:element name="nome"/>
 +
            <xsl:element name="citta">
 +
                <xsl:value-of select="col[2]"/>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template>
 +
</syntaxhighlight>
 +
===Filter===
 +
There are two ways to insert an filter:
  
 +
*Using the filter statement as function
 +
*Inserting nodes with the right mouse button
  
 +
If you enter without condition filters you can use the first method.
 +
[[File:Filter.png|thumb|Filter]]
 +
<syntaxhighlight lang="xml">
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica">
 +
            <xsl:apply-templates select="/RowSet/data/row"/>
 +
            <xsl:element name="cliente">
 +
                <xsl:element name="cognome"/>
 +
                <xsl:element name="nome"/>
 +
                <xsl:element name="citta"/>
 +
                <xsl:element name="citta">
 +
                    <xsl:value-of select="concat(/RowSet/data/row/col[1],/RowSet/data/row[1]/col[2])"/>
 +
                </xsl:element>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template>
 +
</syntaxhighlight>
 +
If you enter concondition filters you can use the second method.
 +
[[File:Filterwithcond.png|thumb|Filter with condition]]
 +
<syntaxhighlight lang="xml">
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica">
 +
            <xsl:apply-templates select="/RowSet/data/row"/>
 +
        </xsl:element>
 +
    </xsl:template>
 +
    <xsl:template match="/RowSet/data/row">
 +
        <xsl:element name="cliente">
 +
            <xsl:element name="cognome"/>
 +
            <xsl:for-each select="col[position() = 1]">
 +
                <xsl:element name="nome">
 +
                    <xsl:value-of select="."/>
 +
                </xsl:element>
 +
            </xsl:for-each>
 +
            <xsl:element name="citta">
 +
                <xsl:value-of select="."/>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template
 +
</syntaxhighlight>
 +
===Variables===
 +
To enter a variable in the transformation use the function variable in tab Core.
 +
[[File:Variable.png|thumb|Variable]]
 +
<syntaxhighlight lang="xml">
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica">
 +
            <xsl:apply-templates select="/RowSet/data/row"/>
 +
        </xsl:element>
 +
    </xsl:template>
 +
    <xsl:template match="/RowSet/data/row">
 +
        <xsl:variable name="var" select="concat(col[1],col[2])"/>
 +
        <xsl:element name="cliente">
 +
            <xsl:element name="cognome">
 +
                <xsl:value-of select="$var"/>
 +
            </xsl:element>
 +
            <xsl:element name="nome">
 +
                <xsl:value-of select="$var"/>
 +
            </xsl:element>
 +
            <xsl:element name="citta">
 +
                <xsl:value-of select="col[3]"/>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template>
 +
</syntaxhighlight>
 +
===Parameter===
 +
To enter a parameter in the transformation use the function parameter.
 +
Name is the name of the parameter, and value is the default value.
 +
[[File:Parameter.png|thumb|Parameter]]
 +
<syntaxhighlight lang="xml">
 +
        <xsl:element name="anagrafica">
 +
            <xsl:element name="cliente">
 +
                <xsl:element name="cognome">
 +
                    <xsl:value-of select="$param"/>
 +
                </xsl:element>
 +
                <xsl:element name="nome"/>
 +
                <xsl:element name="citta"/>
 +
                <xsl:element name="nomecompleto"/>
 +
            </xsl:element>
 +
        </xsl:element>
 +
</syntaxhighlight>
 +
===Parameter template===
 +
To  defines the value of a parameter to be passed into a template must use the paramtemplate function.
 +
[[File:Paramtemplate.png|thumb|Parameter Template]]
 +
<syntaxhighlight lang="xml">
 +
    <xsl:param name="paramname" select="&apos;value&apos;"/>
 +
    <xsl:template match="/">
 +
        <xsl:element name="anagrafica">
 +
            <xsl:apply-templates select="/RowSet/data/row/col">
 +
                <xsl:with-param name="paramname" select="value"/>
 +
            </xsl:apply-templates>
 +
        </xsl:element>
 +
    </xsl:template>
 +
    <xsl:template match="/RowSet/data/row/col">
 +
        <xsl:param name="paramname"/>
 +
        <xsl:element name="cliente">
 +
            <xsl:element name="cognome">
 +
                <xsl:value-of select="$paramname"/>
 +
            </xsl:element>
 +
            <xsl:element name="nome">
 +
                <xsl:value-of select="/RowSet/data/row/col[2]"/>
 +
            </xsl:element>
 +
            <xsl:element name="ente">
 +
                <xsl:value-of select="/RowSet/data/row/col[3]"/>
 +
            </xsl:element>
 +
        </xsl:element>
 +
    </xsl:template>
 +
</syntaxhighlight>
 +
===Additional nodes===
 +
Some XSL transformations need to create nodes by duplicating the base node. To realize this operation, simply select the base node with the right mouse button and then a new duplicate node will be created. An ordinal value will be reported next to the new selected node. A node with an 'n' ordinal value represents the only n-th instance of that node. A node without ordinal values represents all the nodes of that type.
  
{{VOTE}}
+
==Xsl file generation==
 +
To generate the xsl file you must select the 'xsl Save File' menu item icon on the editor tool bar. The file will be created in the subsequently selected directory.

Latest revision as of 09:58, 24 February 2015

Introduction

XML Data mapper module allows users to design a XSL data transformation from one XML document, defined by a source xsd, to another XML document, defined by a target xsd. The designer output is a XSL document associated to a data transformation defined in VulCon. The use of a graphical designer speeds up the process of defining the data mapping, and gives it a simple and efficient graphical representation.

(in the examples the output namespaces have been removed for clarity)

Create a data transformation

The steps required to create a graphical data transformation are:

  • Verify that the XSD documents describing the source/target XMLs are present in the /conf/xsds folder
  • Access the VulCon Core view and expand the GVDataTransformation node
  • Click on Transformations item with right mouse button and choose in the drop-down list
Transformations --> Create XSLT Transformation
  • Populate the wizard parameters:
    • Transformation Name: the name by which the transformation is referenced by GreenVulcano® ESB Core. Is also the name of the editor configuration file with .gvxdt extension and of the XSL transformation file with .xsl extension
    • Data Source: the data source name that indicates the DTE repository where files will be created
    • Path XSL: sub-folders of the selected data source path in which the XSL file will be generated
    • XSD Input: XSD file name defining the source document. The files suggested by the drop-down list must be stored in the /conf/xsds folder
    • root XSD Input: root element of the source XML document from which start the data transformation operation
    • XSD Output: XSD file name defining the target document. The files suggested by the drop-down list must be stored in the /conf/xsds folder
    • root XSD Output: root element of the target XML document
  • Click the Finish button: in Graphic Editor VulCon perspective will appear the Data mapper graphic editor in which in possible to design the transformation
  • Generate the resultant XSL file.

Data mapper graphic editor

Data Mapper

In Data mapper graphic editor are visible the representations for input and output formats.Items followed by '=' character are attributes, while those enclosed in angle brackets '<>' are nodes of the XML document. Is it possible to collaps or expand child nodes simply by clicking on '+' or '-' symbols on the left of each node name. The right panel contains the palettes used for the definition of the data mapping functions. The Select button allows the selection of the xsd nodes interested for the transformation. The Create link button allows to define links:

  • between a source and a target element;
  • between a source element and a parameter of a function;
  • between the output of a function and a parameter of another function;
  • between the output of a function and a target element.

In the folders below that buttons, it is possible to access the functions used for data-mapping grouped by topic.

Open editor

To open the editor you can:

  • double click a .gvxdt file previously created in the Project view;
  • right-clicking on the XSLTransformation in the core view and then choosing the 'Open mapping <transformation name>' item.

Import Function

The import function is a top-level element that is used to import the contents of one style sheet into another. Is it possible to assign a value to a parameter of an imported stylesheet.

Parameter:

  • uri: attribute whose value is a URI reference identifying the stylesheet to be imported
  • param-name: parameter of imported stylesheet (otional)
Import Function without parameter
  <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
         exclude-result-prefixes="xsl fs" version="2.0"
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xsl:import href="getPerson.xsl"/>
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
    <xsl:template match="/">
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
            <xsl:element name="persona"
                         namespace="http://www.greenvulcano.it/greenvulcano">
                <xsl:apply-imports/>
            </xsl:element>
        </xsl:element>
    </xsl:template>
</xsl:stylesheet>
Import Function with parameter
  <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
          exclude-result-prefixes="xsl fs" version="2.0"
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xsl:import href="getPerson.xsl">
        <xsl:with-param name="param" select="/RowSet/data/row/col[1]"/>
    </xsl:import>
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
    <xsl:template match="/">
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
            <xsl:element name="persona"
                         namespace="http://www.greenvulcano.it/greenvulcano">
                <xsl:apply-imports/>
            </xsl:element>
        </xsl:element>
    </xsl:template>
</xsl:stylesheet>

Links

A link is a relation between the node in the source format and its counterpart in the target format. Clicking the Create link button in the Palette pane, link mode is enabled. In this mode is possible to create new connection simply clicking on a node in the XSD source model, and dragging it on a target node. Once defined a new connection in the graphic area, its properties are shown in Properties area. 'Match' property allows the definition of the selected mapping generation mode:

  • template: a template node will be created, activated by the source element
  • for-each: a for-each node will be created to process iteratively the source element
  • none: has not created any link
Link complex node with parameter template




  <?xml version="1.0" encoding="UTF-8"?>
      <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
           exclude-result-prefixes="xsl fs" version="2.0"
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
    <xsl:template match="/">
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
            <xsl:apply-templates select="/RowSet/data"/>
        </xsl:element>
    </xsl:template>
    <xsl:template match="/RowSet/data">
        <xsl:element name="persona" namespace="http://www.greenvulcano.it/greenvulcano">
            <xsl:element name="cognome"
                         namespace="http://www.greenvulcano.it/greenvulcano">
                <xsl:value-of select="row/col[1]"/>
            </xsl:element>
            <xsl:element name="nome" namespace="http://www.greenvulcano.it/greenvulcano">
                <xsl:value-of select="row/col[2]"/>
            </xsl:element>
            <xsl:element name="citta" namespace="http://www.greenvulcano.it/greenvulcano">
                <xsl:value-of select="row/col[3]"/>
            </xsl:element>
        </xsl:element>
    </xsl:template>
  </xsl:stylesheet>
Link complex node with parameter template




  <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
         exclude-result-prefixes="xsl fs" version="2.0"
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
    <xsl:template match="/">
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
            <xsl:for-each select="/RowSet/data">
                <xsl:element name="persona"
                             namespace="http://www.greenvulcano.it/greenvulcano">
                    <xsl:element name="cognome"
                                 namespace="http://www.greenvulcano.it/greenvulcano">
                        <xsl:value-of select="row/col[1]"/>
                    </xsl:element>
                    <xsl:element name="nome"
                                 namespace="http://www.greenvulcano.it/greenvulcano">
                        <xsl:value-of select="row/col[2]"/>
                    </xsl:element>
                    <xsl:element name="citta"
                                 namespace="http://www.greenvulcano.it/greenvulcano">
                        <xsl:value-of select="row/col[3]"/>
                    </xsl:element>
                </xsl:element>
            </xsl:for-each>
        </xsl:element>
    </xsl:template>
    </xsl:stylesheet>

Other Properties:

  • mode: allow an element to be processed multiple times, each time producing a different result.
  • condition: boolean condition applied to template, condition is a drop list of all the condition that have been defined in the transformation
  • priority: priority of a template rule is specified by the priority attribute on the template rule.

If you need to map the node and add a value you can use the link-and-value

Link complex node with parameter template



<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
      exclude-result-prefixes="xsl fs" version="2.0"
                xmlns:fs="http://www.w3.org/2005/xpath-functions"
                xmlns:gv="http://www.greenvulcano.it/greenvulcano"
                xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xsl:output encoding="utf-8" indent="yes" method="xml"/>
    <xsl:template match="/">
        <xsl:element name="anagrafica" namespace="http://www.greenvulcano.it/greenvulcano">
            <xsl:element name="cliente">
                <xsl:value-of select="col"/>
                <xsl:element name="cognome"
                             namespace="http://www.greenvulcano.it/greenvulcano">
                    <xsl:value-of select="col[1]"/>
                </xsl:element>
                <xsl:element name="nome"
                             namespace="http://www.greenvulcano.it/greenvulcano">
                    <xsl:value-of select="col[3]"/>
                </xsl:element>
                <xsl:element name="citta"
                             namespace="http://www.greenvulcano.it/greenvulcano"/>
                <xsl:element name="nomecompleto"
                             namespace="http://www.greenvulcano.it/greenvulcano">
                    <xsl:value-of select="col[4]"/>
                </xsl:element>
            </xsl:element>
        </xsl:element>
    </xsl:template>
</xsl:stylesheet>

Functions

Folders on the right of Graphic Editor contains the most common used XSLT and XPath functions, organized by topic.
To use a function is sufficient to select it in the appropriate folder and then to click in the design area. For those functions which have a variable number of parameters, such as the 'concat' function, a dedicated pop-up will open. Once done this steps, a graphical representation of the new function will be shown in the design area.

DTE Function

At this point you need to create all links to map the input parameters and the one to define the element that will assume the output value of the function.
To give a constant value to a function parameter you must right-click on its graphical representation and then insert the value. To modify a parameter value simply set it in the corresponding property in the lower Property editor.
If the desired function is not present inside function folders, it is possible to define it choosing from Custom folder. To do this you must enter values ​​in the following fields:

DTE Custom Function
  • Name: the name of the function to create (eg.: java:it.greenvulcano.gvesb.datahandling.utils.GenericRetriever.getData).
  • Label: the label displayed on the editor (eg.: getId).
  • Numarg: the number of function arguments.
  • Prefix: the namespace prefix used by the function (example: java).
  • Namespace: the namespace of the function (eg.: http://xml.apache.org/xalan/java)

The following table presents some XSL helper classes, useful in XSL data manipulation:

Helper Use this for ...
XSLTUtils manipulate date/time and strings
GenericRetriever query the database for data conversion
JavaScriptRetriever execute JavaScript code

You can assign a constant value parameter of a function between right-clicking the mouse on the parameter

Conditional Processing with if

There are two ways to insert an if statement:

  • Using the if statement as function
  • Inserting the condition as a property of a link
if function

If the function is used when you want to insert an condition mapping of a complex node.

       <xsl:element name="anagrafica">
            <xsl:if test="/RowSet/data/row/col[1] = string(&apos;Romano&apos;)">
                <xsl:for-each select="/RowSet/data/row/col[1]">
                    <xsl:element name="cliente">
                        <xsl:element name="cognome">
                            <xsl:value-of select="concat(null,/RowSet/data/row/col[2],/RowSet/data/row/col[3])"/>
                        </xsl:element>
                        <xsl:element name="nome"/>
                        <xsl:element name="citta"/>
                        <xsl:element name="nomecompleto"/>
                    </xsl:element>
                </xsl:for-each>
            </xsl:if>
        </xsl:element>
if function

Use the property when you want to map a simple node

            <xsl:element name="cliente">
                <xsl:if test="/RowSet/data/row/col[1] = &apos;Romano&apos;">
                    <xsl:element name="cognome">
                        <xsl:value-of select="/RowSet/data/row/col[1]"/>
                    </xsl:element>
                </xsl:if>
             </xsl:element>
        </xsl:element>

Conditional Processing with choose

The choose element selects one among a number of possible alternatives.

Choose
    <xsl:template match="/">
        <xsl:element name="anagrafica">
            <xsl:apply-templates select="/RowSet/data/row"/>
        </xsl:element>
    </xsl:template>
    <xsl:template match="/RowSet/data/row">
        <xsl:element name="cliente">
            <xsl:choose>
                <xsl:when test="position() = 1">
                    <xsl:element name="cognome">
                        <xsl:value-of select="col"/>
                    </xsl:element>
                </xsl:when>
                <xsl:when test="col[1] = col[2]">
                    <xsl:element name="cognome">
                        <xsl:value-of select="col[1]"/>
                    </xsl:element>
                </xsl:when>
                <xsl:when test="count(col) &gt; 0">
                    <xsl:element name="cognome">
                        <xsl:value-of select="col[3]"/>
                    </xsl:element>
                </xsl:when>
                <xsl:otherwise>
                    <xsl:element name="cognome">
                        <xsl:value-of select="col[4]"/>
                    </xsl:element>
                </xsl:otherwise>
            </xsl:choose>
            <xsl:element name="nome"/>
            <xsl:element name="citta">
                <xsl:value-of select="col[2]"/>
            </xsl:element>
        </xsl:element>
    </xsl:template>

Filter

There are two ways to insert an filter:

  • Using the filter statement as function
  • Inserting nodes with the right mouse button

If you enter without condition filters you can use the first method.

Filter
     <xsl:template match="/">
        <xsl:element name="anagrafica">
            <xsl:apply-templates select="/RowSet/data/row"/>
            <xsl:element name="cliente">
                <xsl:element name="cognome"/>
                <xsl:element name="nome"/>
                <xsl:element name="citta"/>
                <xsl:element name="citta">
                    <xsl:value-of select="concat(/RowSet/data/row/col[1],/RowSet/data/row[1]/col[2])"/>
                </xsl:element>
            </xsl:element>
        </xsl:element>
    </xsl:template>

If you enter concondition filters you can use the second method.

Filter with condition
    <xsl:template match="/">
        <xsl:element name="anagrafica">
            <xsl:apply-templates select="/RowSet/data/row"/>
        </xsl:element>
    </xsl:template>
    <xsl:template match="/RowSet/data/row">
        <xsl:element name="cliente">
            <xsl:element name="cognome"/>
            <xsl:for-each select="col[position() = 1]">
                <xsl:element name="nome">
                    <xsl:value-of select="."/>
                </xsl:element>
            </xsl:for-each>
            <xsl:element name="citta">
                <xsl:value-of select="."/>
            </xsl:element>
        </xsl:element>
    </xsl:template

Variables

To enter a variable in the transformation use the function variable in tab Core.

Variable
    <xsl:template match="/">
        <xsl:element name="anagrafica">
            <xsl:apply-templates select="/RowSet/data/row"/>
        </xsl:element>
    </xsl:template>
    <xsl:template match="/RowSet/data/row">
        <xsl:variable name="var" select="concat(col[1],col[2])"/>
        <xsl:element name="cliente">
            <xsl:element name="cognome">
                <xsl:value-of select="$var"/>
            </xsl:element>
            <xsl:element name="nome">
                <xsl:value-of select="$var"/>
            </xsl:element>
            <xsl:element name="citta">
                <xsl:value-of select="col[3]"/>
            </xsl:element>
        </xsl:element>
    </xsl:template>

Parameter

To enter a parameter in the transformation use the function parameter. Name is the name of the parameter, and value is the default value.

Parameter
        <xsl:element name="anagrafica">
            <xsl:element name="cliente">
                <xsl:element name="cognome">
                    <xsl:value-of select="$param"/>
                </xsl:element>
                <xsl:element name="nome"/>
                <xsl:element name="citta"/>
                <xsl:element name="nomecompleto"/>
            </xsl:element>
        </xsl:element>

Parameter template

To defines the value of a parameter to be passed into a template must use the paramtemplate function.

Parameter Template
    <xsl:param name="paramname" select="&apos;value&apos;"/>
    <xsl:template match="/">
        <xsl:element name="anagrafica">
            <xsl:apply-templates select="/RowSet/data/row/col">
                <xsl:with-param name="paramname" select="value"/>
            </xsl:apply-templates>
        </xsl:element>
    </xsl:template>
    <xsl:template match="/RowSet/data/row/col">
        <xsl:param name="paramname"/>
        <xsl:element name="cliente">
            <xsl:element name="cognome">
                <xsl:value-of select="$paramname"/>
            </xsl:element>
            <xsl:element name="nome">
                <xsl:value-of select="/RowSet/data/row/col[2]"/>
            </xsl:element>
            <xsl:element name="ente">
                <xsl:value-of select="/RowSet/data/row/col[3]"/>
            </xsl:element>
        </xsl:element>
    </xsl:template>

Additional nodes

Some XSL transformations need to create nodes by duplicating the base node. To realize this operation, simply select the base node with the right mouse button and then a new duplicate node will be created. An ordinal value will be reported next to the new selected node. A node with an 'n' ordinal value represents the only n-th instance of that node. A node without ordinal values represents all the nodes of that type.

Xsl file generation

To generate the xsl file you must select the 'xsl Save File' menu item icon on the editor tool bar. The file will be created in the subsequently selected directory.