RFR: 8223717: javafx printing: Support Specifying Print to File in the API [v3]

[Kevin Rushforth]

On Thu, 24 Jun 2021 23:00:42 GMT, Phil Race <prr at openjdk.org> wrote:

>> This enhancement adds the String property outputFileProperty() to the JobSettings class.
>> The value should be a string that references a local file encoded as a URL.
>> If this is non-null and set to a location that the user has permission to write to,
>> then the printer output will be spooled there instead of the printer, so long as the platform printing system supports this.
>> The user can of course also set a print-to-file destination in the platform printer dialogs which may over-ride what the application set. But now the application can also see what it was set to, and cancel or alter it if necessary.
>> 
>> A simple manual test is provided, manual mainly because the few real printing functional tests are all manual as they are only useful if run with a printer configured.
>
> Phil Race has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8223717: javafx printing: Support Specifying Print to File in the API

Overall the new API and functionality looks good, and fills a void that was discussed [in this thread](https://mail.openjdk.java.net/pipermail/openjfx-dev/2019-May/023292.html) a couple years ago.

General comments:

* If the user selects "print to file" from the native dialog, it will write to the `outputFile` property. This should be documented.

* On the question of error handling. There are two types of errors we could consider. 

The first, which is the one we had been discussing, is where the URL is a valid file URL, but the program can't write to it, either because we are running with a security manager and the application doesn't have permission, or because we can't write to the output file (e.g., the path doesn't exist or is read-only).

The second is a bad URL. If the URL is malformed or uses an unsupported protocol (anything other than `file:`), we could throw IllegalArgumentException, either when the invalid URL is set or when the print job is run. We might want to do this regardless of what we do about the first type of error. This could be done as simple as adding `@throws IllegalArgumentException if the url uses a protocol other than "file:"`. What do you think?

For files that can't be written (the first type of error), we have three choices:

1. Define it loosely such that using a file that cannot be written to will either throw an exception when the print job is run or it will be ignored.

2. Define it to always throw an exception. We would need to add validation logic in PrintJob before calling the implementation methods, but we wouldn't necessarily be able to catch all errors (e.g., an IOEXception that only happens after you start writing to the file). This seems like overkill.

3. Define it to never throw an exception. The implementation would need to wrap the call to print in a try / catch, probably logging the result.

I would probably lean towards 1 (which is what you are suggesting), but 3 could work as well.

I left a couple inline comments on the API.

modules/javafx.graphics/src/main/java/javafx/print/JobSettings.java line 492:

> 490:      * a writable file it may be ignored, or a SecurityException may be thrown.
> 491:      * The default value is an empty string, which is interpreted as unset,
> 492:      * which means output is sent to the printer.

Can you add a `* @defaultValue empty string` javadoc tag?

-------------

PR: https://git.openjdk.java.net/jfx/pull/543