JDK-8215722 : Java Access Bridge logging and debug flags dynamically controlled
  • Type: CSR
  • Component: client-libs
  • Sub-Component: javax.accessibility
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 13
  • Submitted: 2018-12-20
  • Updated: 2019-04-09
  • Resolved: 2019-04-09
Related Reports
CSR :  
JDK-8196681 - Java Access Bridge logging and debug flags dynamically controlled
Description
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:
<Timestamp> [Log_Level]: <message>\n,
where, Timestamp is time in nanoseconds,
Log_Level can be any of INFO, ERROR, WARN,
message is the log text.
Comments
Administratively, marking this request as approved as it was pushed before starting the CSR process, and thus pushed in violation of the CSR process, and the work to amend the feature continues under JDK-8221680.
09-04-2019
A new CSR (JDK-8221680) is raised, which simplifies the log file specification. Hence, this CSR will be withdrawn.
29-03-2019
If the proposal now is to specify a directory with `JAVA_ACCESS_BRIDGE_LOGDIR` then it should be okay.
22-03-2019
[~kaddepalli] what is a current status of next iteration?
20-03-2019
> JAVA_ACCESSBRIDGE_LOGFILE but as it's a JDK-specific feature then maybe it should be prefixed with JDK_ rather than JAVA_. It is named for the technology whose activities it logs, so I think it is fine as is. Java Access Bridge is used in documentation and is the sole name for this. Naming an env variable differently would just be confusing. But since we are now using the var to specify the directory it might be better called JAVA_ACCESS_BRIDGE_LOGDIR rather than use "FILE" > Having it looking for the file extension in the value is a bit strange, My earlier comment above says the revised proposal will name the files with the .log extension with no possibility to customise and that the variable will specify only the directory, so this is already something that is being addressed.
06-03-2019
The env variable name in the proposal is currently JAVA_ACCESSBRIDGE_LOGFILE but as it's a JDK-specific feature then maybe it should be prefixed with JDK_ rather than JAVA_. Using the value for two log files is a bit unusually but okay. Having it looking for the file extension in the value is a bit strange, I think it would be simpler to just append ".windowsaccessbridge.log" and ".javaaccessbridge.log".
05-03-2019
[~darcy], Mostly, in other places we use PlatformLogger, which is a full-blown logging framework, which has different levels of logging enabled, and mostly (I haven't checked this) would generate a log file per process id. For our current feature, when multiple applications are launched, all but the first application will not have access to the java_access_bridge.txt file, and will continue without logging anything. But, the windows_access_bridge.txt would contain interleaved messages, which may make it harder to debug the actual problem at hand. As this is a debug only feature, it was intentionally designed to run with only one application at a time. The format of the logging is added to the specification.
14-02-2019
To repeat the previously asked question: "How are log files for other kinds of information handled?" How do other platform processes that write log deal with this situation? For java_access_bridge.txt, if the file is already open for writing does a second process block, exit with an error, continue without doing logging, something else? Since apparently the file to write to can be communicated to windows_access_bridge.txt, it would be possible to create a channel to communicate a per-process file to write to. Where is the format of the log messages documented, even if not for end-user consumption?
11-02-2019
[~darcy], I think you are trying to ask this question: "How does this feature handle logging, when multiple Java Applications are running simultaneously?" Assuming this question: This feature has two parts to it - "java_access_bridge.txt" file created by the Java Application, and "windows_access_bridge.txt", created by JAWs(AT). With the current implementation, the first launched Java application will get the chance to open the file and write to it. The applications that launched later will not be able to write to this file,since it is already open. JAWs will open the file "windows_access_bridge.txt", and it will keep appending the information regarding the multiple applications that are interacting with it. Now, even if we address the problem of multiple java applications not able to generate log files (by creating a log file as per process id), the fact that JAWs can create only one log file, will be a limitation. Fixing that, even if possible would mean a lot of effort, which doesn't seem to be justified for this debug only feature. Hope this clarifies your concern.
01-02-2019
The feature is not meant for users. Rather it is meant for developers/support who will be analyzing these files to debug problems with Accessbridge on windows. For the creation of the files, process id is not involved, since the Java application uses javaaccessbridge.dll, which will have the suffix "_java_access_bridge". On the other hand the AT (JAWs) will use windowsaccesbridge.dll, and it will create another file with the suffix "_windows_access_bridge".
30-01-2019
Presumably two files with matching processing ids could be written out as opposed to one file with a processing id. I'm not convinced the current proposal is a reasonable one for users.
30-01-2019
The files in this case are written out from two different processes - Java Application and the AT (JAWs) which loads the WindowsAccessBridge.dll. So, each process writes out only file, and the name for each file is appropriately suffixed for the support to understand which process wrote what file.
26-01-2019
How are log files for other kinds of information handled? Presumably they include some kind of process id to allow multiple files to be written. Administratively, I'm moving this request to Provisional, but I think the functionality may need some refinement.
23-01-2019