-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add XSLT transformations for iia-hash element
- Loading branch information
1 parent
326ff0d
commit dd0f8a5
Showing
14 changed files
with
527 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| The XSLT templates, Java class example and this explanation are based on | ||
| [this comment](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/109#issuecomment-1593875245) | ||
| and inspired by [this comment](https://github.com/erasmus-without-paper/ewp-specs-api-iias/issues/109#issuecomment-1569982153). | ||
|
|
||
| ### Short explanation | ||
|
|
||
| The result of the [XSLT transformation](transform_version_6.xsl) for | ||
| [IIA version v6 example](https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-api-iias/stable-v7/resources/xsltKit/get-response-v6.xml) | ||
| is something similar to this: | ||
|
|
||
| ``` | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <iia> | ||
| <iia-id>0f7a5682-faf7-49a7-9cc7-ec486c49a281</iia-id> | ||
| <text-to-hash>_0f7a5682-faf7-49a7-9cc7-ec486c49a281__1954991__uw.edu.pl__140__hibo.no__031__Social and behavioural sciences__5__false__7__8__2014/2015__2020/2021__uw.edu.pl__140__hibo.no__2__en__C1__0314__8__2016/2017__2017/2018_</text-to-hash> | ||
| </iia> | ||
| ``` | ||
|
|
||
| And it is the same result we obtain if we apply the [XSLT transformation](transform_version_7.xsl) for | ||
| [IIA version v7 example](https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-api-iias/stable-v7/resources/xsltKit/get-response-v7.xml). | ||
|
|
||
| We should next hash the value of the `text-to-hash` element with an SHA-256 algorithm to obtain the new `iia-hash` element value. | ||
|
|
||
| The transformation can manage changes to IIA introduced in version 7 of the API. It also reflects changes to IIA mapping. | ||
| Thanks to the `not-yet-defined` attribute it manages elements that are required by the new version but cannot be provided automatically for the old IIAs. | ||
| Also `v6-value` attribute of the `isced-f-code` element is used to acquire the old ISCED code value as defined in IIA version 6. | ||
|
|
||
| When an IIA has at least one element with the attribute `not-yet-defined`, | ||
| the transformation adds a `<valid-for-approval>false</valid-for-approval>` sub-element as the last child of the `<iia>` element. | ||
|
|
||
| To transform an XML you may need to find the right processor, | ||
| e.g. for Java [Saxon-HE-9.5.1-8.jar](http://www.java2s.com/example/jar/s/download-saxonhe9518jar-file.html) works while the previous versions fail. | ||
|
|
||
| We provide an example in Java that transforms an IIA XML (as a byte array) via the XSLT (as a byte array too) and obtain the above-mentioned XML: | ||
|
|
||
| ``` | ||
| public String getXmlTransformed(byte xmlBytes[], byte xsltBytes[]) throws Exception | ||
| { | ||
| DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); | ||
| dbf.setNamespaceAware(true); | ||
| DocumentBuilder db = dbf.newDocumentBuilder(); | ||
| Document document = db.parse(new ByteArrayInputStream(xmlBytes)); | ||
| TransformerFactory transformerFactory = TransformerFactory.newInstance(); | ||
| Transformer transformer = transformerFactory.newTransformer( | ||
| new StreamSource(new ByteArrayInputStream(xsltBytes))); | ||
| ByteArrayOutputStream output = new ByteArrayOutputStream(); | ||
| transformer.transform(new DOMSource(document), new StreamResult(output)); | ||
| return new String(output.toByteArray()); | ||
| } | ||
| ``` | ||
|
|
||
| The solution described here consists of the following resources: | ||
| - [transform_version_6.xsl](transform_version_6.xsl) to be used with your IIA v6, | ||
| - [transform_version_7.xsl](transform_version_7.xsl) to be used with your IIA v7, | ||
| - [XsltTest.java](XsltTest.java) to transform an IIA XML using one of the above-mentioned XSLTs. | ||
|
|
||
|
|
||
| ### Further explanation | ||
|
|
||
|
|
||
| The XSLT produces one `<iia>` element for every `<iia>` element present in the IIA Get response. | ||
| The `<iia-id>` sub-element can be used to identify each IIA. | ||
|
|
||
| Every `<iia>` element has two sub-elements and optionally a third one: | ||
| - `<iia-id>` to indicate the associated IIA ID, | ||
| - `<text-to-hash>` to expose the string built as a concatenation of all the leaf elements (elements without children) | ||
| separated by an underscore (e.g.: `_myValue_`). Before every element we have the values of its attributes (if they exist); | ||
| they are represented inside two markers` _@ `and `@_ `(e.g. `_@attributeValue@_`). There are some additional rules: | ||
| - the `<text-to-hash>` element contains both IIA IDs (sending and receiving); so it changes when IIA mapping changes, | ||
| - the `<text-to-hash>` element does not contain: | ||
| - the sending/receiving contacts (for both of v6 and v7 XSLT) | ||
| - the `receiving-academic-year-id` (only for v6 XSLT) | ||
| - the `receiving-first-academic-year-id` and the `receiving-last-academic-year-id` (only for v7 XSLT) | ||
| - the `<text-to-hash>` element contains, at the end of every mobility: | ||
| - for XSLT v6: the values of the first and last occurrence of the receiving-academic-year-id element | ||
| - for XSLT v7: the values of the receiving-first-academic-year-id and receiving-last-academic-year-id | ||
| - the `<text-to-hash>` element does not contain: (only for v7) | ||
| - all the elements having the attribute `not-yet-defined`; this attribute is never printed in the output, | ||
| - the `isced-f-code` element value is replaced with the `v6-value` attribute value if defined (only for v7), | ||
| - `<valid-for-approval>` is present and set to false if the IIA v7 contains: | ||
| - an element with the `not-yet-defined` attribute set to true, | ||
| - an element with the `v6-value` attribute set to a non-empty value. | ||
|
|
||
| To test the XSLT against your IIA Get response XMLs you can use those online tools: | ||
| - https://linangdata.com/xslt-tester/ | ||
| - http://xsltransform.net/ | ||
|
|
||
| To compute the hash code you can use: | ||
| - https://www.fileformat.info/tool/hash.htm |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| import java.io.ByteArrayInputStream; | ||
| import java.io.ByteArrayOutputStream; | ||
| import java.nio.file.Files; | ||
| import java.nio.file.Path; | ||
| import java.nio.file.Paths; | ||
| import javax.xml.parsers.DocumentBuilder; | ||
| import javax.xml.parsers.DocumentBuilderFactory; | ||
| import javax.xml.transform.Transformer; | ||
| import javax.xml.transform.TransformerFactory; | ||
| import javax.xml.transform.dom.DOMSource; | ||
| import javax.xml.transform.stream.StreamResult; | ||
| import javax.xml.transform.stream.StreamSource; | ||
| import org.w3c.dom.Document; | ||
|
|
||
| /** | ||
| * Class to test the XSLT. | ||
| * The first parameter is the IIA xml file name, the second is the xlst stylesheet file name. | ||
| * They both must be in the directory from where you invoke this class | ||
| * | ||
| * @author Francesco De Milato | ||
| */ | ||
| public class XsltTest | ||
| { | ||
| public XsltTest (){} | ||
|
|
||
| public static void main(String args[]) throws Exception | ||
| { | ||
| XsltTest xml = new XsltTest(); | ||
| System.setProperty( | ||
| "javax.xml.transform.TransformerFactory","net.sf.saxon.TransformerFactoryImpl"); | ||
|
|
||
| if (args.length!=2) System.out.println("ERROR!\nSintax: java it.unige.ewp.tools.XmlTest <iiaFileName> <xsltFileName>"); | ||
| else | ||
| { | ||
| String iiaFileName = args[0]; | ||
| String xsltFileName = args[1]; | ||
|
|
||
| Path xsltPath = Paths.get(xsltFileName); | ||
| Path iiaPath = Paths.get(iiaFileName); | ||
|
|
||
| byte[] xsltData = Files.readAllBytes(xsltPath); | ||
| byte[] iiaData = Files.readAllBytes(iiaPath); | ||
|
|
||
| System.out.println("\n\nXSLT Result: \n"+xml.getXmlTransformed(iiaData, xsltData)); | ||
| System.out.println("\n\nBe careful to use the right xslt for your IIA Version!"); | ||
| System.out.println("Now you can get the element text-to-hash and compute its SHA-256 hash code\n\n"); | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * Transform an xml file by means of an xslt file | ||
| * | ||
| * @param xmlBytes The content of the xml file | ||
| * @param xsltBytes The content of the xslt file | ||
| * @return An xml useful to compute the hash code | ||
| * @throws Exception | ||
| */ | ||
| public String getXmlTransformed(byte xmlBytes[], byte xsltBytes[]) throws Exception | ||
| { | ||
| DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); | ||
| dbf.setNamespaceAware(true); | ||
|
|
||
| DocumentBuilder db = dbf.newDocumentBuilder(); | ||
| Document document = db.parse(new ByteArrayInputStream(xmlBytes)); | ||
|
|
||
| TransformerFactory transformerFactory = TransformerFactory.newInstance(); | ||
| Transformer transformer = transformerFactory.newTransformer( | ||
| new StreamSource(new ByteArrayInputStream(xsltBytes))); | ||
| ByteArrayOutputStream output = new ByteArrayOutputStream(); | ||
|
|
||
| transformer.transform(new DOMSource(document), new StreamResult(output)); | ||
|
|
||
| return new String( output.toByteArray()); | ||
| } | ||
| } | ||
|
|
Oops, something went wrong.
dd0f8a5There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why is the terminated-as-a-whole attribute not part of the hashed string? According to the voting results from 7 June 2023, termination as a whole should be treated like any other modification/termination, which, I suppose, implies that it should require a re-approval. Or am I missing something?
dd0f8a5There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You are right that it should be part of the hashed string to meet the requirements. The issue now is how to modify the XSLT without changing the major version of IIA.
dd0f8a5There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There is no need to change the IIA version; bugs happen, improvements too...
Just replace the XSLT with a new one, the XSD remains the same.
And no one should trust in the XSLT until deeply tested
The new XSLT (v7) could start from here