[java-source-utils] Transform XML using XSLT

[pjcollins]

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 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.

[pjcollins]

@jonpryor there is some overlap here and in #923, I'm not sure which one we want to try to land first, or if we should try to combine them at this point.

[jonpryor]

On Windows, wouldn't we want/shouldn't C:\\this\\file\\does\\not\\exist fail? The primary point isn't that the filename itself is invalid -- which would be the case on Windows with XYZABC:\\… -- but rather that a "valid" file path refers a non-existent filesystem entry.

(Plus, on Unix, I'm not sure it's really possible to have a path which itself is invalid. NUL is "valid" {kinda, sorta} in that everything up to the NUL is handled, including newlines!)

[pjcollins]

I believe C:\\this\\file\\does\\not\\exist would not throw a FileNotFoundException when attempting to create a PrintStream, as the mkdirs call makes the path valid. We could change this to use a single non common drive name prefix that doesn't exist (e.g. X or something like that), or we could maybe just ignore this test on Windows.

[jonpryor]

…so now I'm confused, which isn't great: @Test(expected=FileNotFoundException.class) should be asserting that FileNotFoundException is thrown. The fact that this test is passing means that FileNotFoundException is thrown.

No java.io.File APIs document throwing FileNotFoundException, meaning parent.mkdirs() isn't throwing.

This leaves the PrintStream(File) constructor, which is documented as throwing FileNotFoundException:

If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

So how's this test work in the first place?

Permissions, apparently; consider:

import java.io.*;

class ps {
    public static void main (String[] args) throws Throwable {
        for (String a : args) {
            File f = new File(a);
            System.out.println(a + " exists? " + f.exists());
            File p = f.getParentFile();
            System.out.println(a + " parent? " + (p != null));
            if (p != null)
                System.out.println("mkdirs on parent? " + p.mkdirs());
            new PrintStream(a);
        }
    }
}

If I run this as:

java ps /this/does/not/exist

I get:

/this/does/not/exist exists? false
/this/does/not/exist parent? true
mkdirs on parent? false
Exception in thread "main" java.io.FileNotFoundException: /this/does/not/exist (No such file or directory)
	at java.base/java.io.FileOutputStream.open0(Native Method)
…

meaning File.mkdirs() (1) doesn't throw, but (2) doesn't do anything, because a non-root user can't create the directory /this.

I imagine the same would be true on Windows.

/me tests…

So on Windows, a non-Admin user can create C:\This. Which is why this test will "fail" on Windows, because File.mkdirs() succeeds. Which is entirely unexpected (to me).

🤔

[jonpryor]

This, on the other hand, fails (as expected):

> mkdir "\Program Files\a"
Access is denied.

So maybe on Windows we need to do:

if (osName.startsWith("Windows")) {
    invalidFilePath = "C:\\Program Files\\does\\not\\exist";
}

[pjcollins]

I think the Microsoft hosted machine pools we use have special permissions that allow the "agent" user to have more access and control. Program Files modification does not appear to be restricted for the Pipelines user account. I'm trying to look for a restricted path but we may ultimately want to skip these two tests on Windows.

[pjcollins]

There are no restrictions in writing to C:\Program Files, C:\Program Files (x86) or C:\Windows on these machines. Rather than continuing to try to seek out a restricted path I've decided to ignore these tests when running on CI on Windows.