[java-source-utils] Transform XML using XSLT (#924)

I've seen inconsistent XML output from java-source-utils when running
on macOS vs. Windows, or JDK 8 vs. JDK 11.  On Windows I've seen extra
carriage returns in CDATA blocks, and when using JDK 9+ we've seen
additional new lines added between XML elements.

An XSL style sheet can be used to improve the formatting consistency
of the XML that is produced.  This should prevent us from generating
inconsistent API docs across macOS and Windows.

There is still [an outstanding issue][0] concerning CDATA blocks
between JDK 8 and JDK 11 that I have not yet been able to sort out.
This issue has seemingly been ["fixed" in JDK 14][1].

[0]: https://stackoverflow.com/questions/55853220/handling-change-in-newlines-by-xml-transformation-for-cdata-from-java-8-to-java
[1]: https://bugs.java.com/bugdatabase/view_bug.do?bug_id=JDK-8223291

Author: pjcollins

build-tools/automation/azure-pipelines.yaml

@@ -179,6 +179,5 @@ jobs:
   - template: templates\core-tests.yaml
     parameters:
       runNativeTests: true
-      runJavaTests: true
 
   - template: templates\fail-on-issue.yaml

build-tools/automation/templates/core-tests.yaml

@@ -1,7 +1,6 @@
 parameters:
   condition: succeeded()
   runNativeTests: false
-  runJavaTests: false
 
 steps:
 - task: DotNetCoreCLI@2
@@ -110,15 +109,13 @@ steps:
 
 - task: DotNetCoreCLI@2
   displayName: 'Tests: java-source-utils'
-  condition: eq('${{ parameters.runJavaTests }}', 'true')
   inputs:
     command: build
     arguments: -c $(Build.Configuration) tools/java-source-utils/java-source-utils.csproj -t:RunTests
   continueOnError: true
 
 - task: PublishTestResults@2
   displayName: Publish JUnit Test Results
-  condition: eq('${{ parameters.runJavaTests }}', 'true')
   inputs:
     testResultsFormat: JUnit
     testResultsFiles: 'tools/java-source-utils/build/test-results/**/TEST-*.xml'

build-tools/automation/templates/publish-test-results.yaml

@@ -9,7 +9,6 @@ steps:
 
 - task: PublishTestResults@2
   displayName: Publish JUnit Test Results
-  condition: ne('$(Agent.OS)', 'Windows')
   inputs:
     testResultsFormat: JUnit
     testResultsFiles: '**/TEST-*.xml'

build-tools/scripts/RunNUnitTests.targets

@@ -30,7 +30,7 @@
         ContinueOnError="ErrorAndContinue"
     />
     <MSBuild
-        Condition=" !$([MSBuild]::IsOSPlatform ('windows')) "
+        Condition=" '$(SkipJSUTests)' != 'true' "
         Projects="$(MSBuildThisFileDirectory)..\..\tools\java-source-utils\java-source-utils.csproj"
         Targets="RunTests"
     />

tools/java-source-utils/src/main/java/com/microsoft/android/JavadocXmlGenerator.java

@@ -2,6 +2,8 @@
 
 import java.io.File;
 import java.io.FileNotFoundException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
 import java.io.IOException;
 import java.io.PrintStream;
 import java.io.UnsupportedEncodingException;
@@ -17,6 +19,7 @@
 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;
 import org.w3c.dom.Element;
@@ -65,10 +68,10 @@ private void startApi() throws ParserConfigurationException {
 	}
 
 	public void close() throws TransformerException {
+		InputStream is = getClass().getClassLoader().getResourceAsStream("transform-style.xsl");
+		InputStreamReader isr = new InputStreamReader(is);
 		Transformer transformer = TransformerFactory.newInstance()
-			.newTransformer();
-		transformer.setOutputProperty(OutputKeys.INDENT, "yes");
-		transformer.setOutputProperty("{http://xml.apache.org/xslt}indent-amount", "2");
+			.newTransformer(new StreamSource (isr));
 		transformer.transform(new DOMSource(document), new StreamResult(output));
 
 		if (output != System.out) {

tools/java-source-utils/src/main/resources/transform-style.xsl

@@ -0,0 +1,45 @@
+<xsl:stylesheet version="1.0"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:xalan="http://xml.apache.org/xalan">
+
+  <xsl:output method="xml"
+              encoding="UTF-8"
+              indent="yes"
+              xalan:indent-amount="2"
+              standalone="no"
+              cdata-section-elements="javadoc"/>
+
+  <xsl:strip-space elements="*"/>
+
+  <xsl:template match="node()|@*">
+    <xsl:copy>
+    <xsl:apply-templates select="node()|@*"/>
+    </xsl:copy>
+  </xsl:template>
+
+
+  <!-- Remove extra carriage returns from `<javadoc/>` CDATA elements to help standardize output across Unix and Windows -->
+  <xsl:template match="javadoc/text()">
+    <xsl:call-template name="removeCarriageReturn"/>
+  </xsl:template>
+
+  <xsl:template name="removeCarriageReturn">
+    <xsl:param name="pText" select="."/>
+
+    <xsl:if test="string-length($pText) >0">
+      <xsl:choose>
+        <xsl:when test="not(contains($pText,'&#13;'))">
+          <xsl:value-of select="$pText"/>
+        </xsl:when>
+
+        <xsl:otherwise>
+          <xsl:value-of select="substring-before($pText, '&#13;')"/>
+          <xsl:call-template name="removeCarriageReturn">
+            <xsl:with-param name="pText" select="substring-after($pText, '&#13;')"/>
+          </xsl:call-template>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:if>
+  </xsl:template>
+
+</xsl:stylesheet>

tools/java-source-utils/src/test/java/com/microsoft/android/JavadocXmlGeneratorTest.java

@@ -10,6 +10,7 @@
 import javax.xml.parsers.ParserConfigurationException;
 import javax.xml.transform.TransformerException;
 
+import org.junit.Assume;
 import org.junit.Test;
 import static org.junit.Assert.*;
 
@@ -19,7 +20,14 @@
 public final class JavadocXmlGeneratorTest {
 	@Test(expected = FileNotFoundException.class)
 	public void init_invalidFileThrows() throws FileNotFoundException, ParserConfigurationException, TransformerException, UnsupportedEncodingException {
-		try (JavadocXmlGenerator g = new JavadocXmlGenerator("/this/file/does/not/exist")) {
+		String invalidFilePath = "/this/file/does/not/exist";
+		String osName = System.getProperty("os.name");
+		if (osName.startsWith("Windows")) {
+			invalidFilePath = System.getenv("ProgramFiles") + "\\this\\file\\does\\not\\exist";
+			// Ignore if running on an Azure Pipelines Microsoft hosted agent by only running when %AGENT_NAME% is not set.
+			Assume.assumeTrue(System.getenv("AGENT_NAME") == null);
+		}
+		try (JavadocXmlGenerator g = new JavadocXmlGenerator(invalidFilePath)) {
 		}
 	}
 
@@ -40,9 +48,11 @@ public void testWritePackages_noPackages() throws ParserConfigurationException,
 		generator.writePackages(packages);
 		generator.close();
 
-		final   String  expected =
+		final   String  expected = (
 			"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n" +
-			"<api api-source=\"java-source-utils\"/>\n";
+			"<api api-source=\"java-source-utils\"/>\n"
+		).replace("\n", System.lineSeparator());
+
 		assertEquals("no packages", expected, bytes.toString());
 	}
 
@@ -53,7 +63,7 @@ public void testWritePackages_demo() throws ParserConfigurationException, Transf
 		final   JavadocXmlGenerator     generator   = new JavadocXmlGenerator(new PrintStream(bytes));
 		final   JniPackagesInfo         packages    = JniPackagesInfoTest.createDemoInfo();
 
-		final   String                  expected    = 
+		final   String                  expected    = (
 			"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n" +
 			"<api api-source=\"java-source-utils\">\n" +
 			"  <package jni-name=\"\" name=\"\">\n" +
@@ -94,7 +104,8 @@ public void testWritePackages_demo() throws ParserConfigurationException, Transf
 			"      </method>\n" +
 			"    </interface>\n" +
 			"  </package>\n" +
-			"</api>\n";
+			"</api>\n"
+		).replace("\n", System.lineSeparator());
 
 		generator.writePackages(packages);
 		generator.close();

tools/java-source-utils/src/test/java/com/microsoft/android/ParameterNameGeneratorTest.java

@@ -7,6 +7,7 @@
 import java.io.UnsupportedEncodingException;
 import java.util.Arrays;
 
+import org.junit.Assume;
 import org.junit.Test;
 import static org.junit.Assert.*;
 
@@ -17,7 +18,14 @@ public class ParameterNameGeneratorTest {
 
 	@Test(expected = FileNotFoundException.class)
 	public void init_invalidFileThrows() throws FileNotFoundException, UnsupportedEncodingException {
-		new ParameterNameGenerator("/this/file/does/not/exist");
+		String invalidFilePath = "/this/file/does/not/exist";
+		String osName = System.getProperty("os.name");
+		if (osName.startsWith("Windows")) {
+			invalidFilePath = System.getenv("ProgramFiles") + "\\this\\file\\does\\not\\exist";
+			// Ignore if running on an Azure Pipelines Microsoft hosted agent by only running when %AGENT_NAME% is not set.
+			Assume.assumeTrue(System.getenv("AGENT_NAME") == null);
+		}
+		new ParameterNameGenerator(invalidFilePath);
 	}
 
 	@Test(expected = IllegalArgumentException.class)
@@ -45,7 +53,7 @@ public void testWritePackages_demo() {
 		ParameterNameGenerator  generator   = new ParameterNameGenerator(new PrintStream(bytes));
 		JniPackagesInfo         packages    = JniPackagesInfoTest.createDemoInfo();
 
-		final String expected = 
+		final String expected = (
 			";---------------------------------------\n" +
 			"  class A\n" +
 			"    #ctor(int one, java.lang.String two)\n" +
@@ -60,7 +68,8 @@ public void testWritePackages_demo() {
 			";---------------------------------------\n" +
 			"  interface Exampleable\n" +
 			"    example(java.lang.String e)\n" +
-			"";
+			""
+		).replace("\n", System.lineSeparator());
 
 		generator.writePackages(packages);
 		assertEquals("global package + example packages", expected, bytes.toString());