Original CSR: JDK-8215722

Meta: I work on windows builds at RedHat (akashche@redhat.com) doing backports of JDK-8196681 and JDK-8219914 to 8u. I was advised by Christoph Langer to retoractively file a CSR for JDK-8226571 that was already pushed to 11u.

Note: according to original CSR timestamps in log files should contain time in nanoseconds, in actual implementation milliseconds are used instead. Original CSR unchanged text is below.

Summary

This request is to write the accessibility related communication exchange between JAWs and Java Application to a log file for debugging problems.

Problem

Java Access Bridge (JAB) which is a windows-only JDK native API to support accessibility, does not provide any way to enable logging of itself or an Assistive Technology using JAB. This means that debugging of problems in a user setting is impossible and it is thus hard to identify and fix problems. Since JAB communicates with an AT, both sides need to support logging to make this useful.

Solution

Define an environment variable "JAVA_ACCESSBRIDGE_LOGFILE" which when specified, and pointing to a writable file location, will enable logging of Java Access Bridge activity to files specified by that variable. Two log files will be created, using the variable name as a path and prefix: one written by the JavaAccessBridge itself (loaded by Java), one written by AT which loads a Java provided DLL, windowsaccessbridge.dll

If the variable is undefined or empty, or points to a non-writable location, no logging will be performed. This will be provided to customers on request.

The logging is explicitly limited to be enabled for one application at a time, i.e. it cannot support concurrent applications, which is sufficient for its purpose as a debugging tool.

Specification

Define an environment variable "JAVA_ACCESSBRIDGE_LOGFILE" which when specified, and pointing to a writable file location, will enable logging of Java Access Bridge activity to two files as follows:

JAVA_ACCESSBRIDGE_LOGFILE represents the path name + file name prefix to be used for two files, created using this prefix, i.e. : 1) ${JAVA_ACCESSBRIDGE_LOGFILE}_java_access_bridge.{ext} 2) ${JAVA_ACCESSBRIDGE_LOGFILE}_windows_access_bridge.{ext} Note that {ext} can be specified in the environment variable itself. If there is no extension specified, then by default ".log" extension will be used. (1) logs information from the Java process which loads javaaccessbridge.dll (2) logs information from the AT process which loads windowsaccessbridge.dll

The logging should be limited to be enabled for one application at a time, i.e., it cannot support concurrent applications, which is sufficient for its purpose as a debugging tool.

The logged results are intended to be interpreted by support, not the customer.

The logging format is as follows: [Log_Level]: \n, where, Timestamp is time in nanoseconds, Log_Level can be any of INFO, ERROR, WARN, message is the log text.