Summary

Support loading of Assistive Technology from a service provider

Problem

Currently Assistive Technology, in particular the Java Access Bridge, is loaded by java.awt.Toolkit.getDefaultToolkit using reflection to load and instantiate the com.sun.java.accessibility.AccessBridge class.  In Java 9, the AccessBridge class will be in a different module than the module from which it is called.  It is called by java.awt.Toolkit.getDefaultToolkit in the java.desktop module.  The AccessBridge API is module-private. getDefaultToolKit will not be able to access the AccessBridge class.

Also, additional accessibility support implementations need to be loaded such as test tools and support for Assistive Technology on other platforms, in particular the Java ATK Wrapper on Linux.

Solution

Use a service provider interface.

Specification

The service provider will provide a mapping from the platform specific accessibility API to the Java Accessibility API.

Each service provider implementation is named.  That name is fetched with the getName method.  The service provider can be activated via the activate method. Service providers can be loaded when the default toolkit is initialized.

If the java.awt.Toolkit implementation is not a headless implementation and if they exist, service providers of javax.accessibility.AccessibilityProvider will be loaded if specified by the system property javax.accessibility.assistive_technologies.

The names specified in the javax.accessibility.assistive_technologies system property are used to query each service provider implementation.  If the requested name matches the name of the service provider, the activate method will be invoked to activate the matching service provider.

Note that the javax.accessibility.assistive_technologies system property is not new for Java 9 and is only mentioned above for clarity.

There is one (unneeded) file that will be removed from the system: conf/accessibilty.properties.  The properties file that is actually used is ${user.home}/.accessibility.properties.  This has been the case since 7u6 when the Java Access Bridge was originally added to the JRE.  A user could manually create this file and it would be used but that is not the standard means to specify accessibility properties.  This file was used prior to Vista when there was no concept of a user home directory.

The patch for the changed javadoc for java.awt.Toolkit.getDefaultToolkit is:

     /**
      * Gets the default toolkit.
      * <p>
-     * If a system property named <code>"java.awt.headless"</code> is set
-     * to <code>true</code> then the headless implementation
-     * of <code>Toolkit</code> is used.
+     * If a system property named {@code "java.awt.headless"} is set
+     * to {@code true} then the headless implementation
+     * of {@code Toolkit} is used.
      * <p>
-     * If there is no <code>"java.awt.headless"</code> or it is set to
-     * <code>false</code> and there is a system property named
-     * <code>"awt.toolkit"</code>,
+     * If there is no {@code "java.awt.headless"} or it is set to
+     * {@code false} and there is a system property named
+     * {@code "awt.toolkit"},
      * that property is treated as the name of a class that is a subclass
-     * of <code>Toolkit</code>;
+     * of {@code Toolkit};
      * otherwise the default platform-specific implementation of
-     * <code>Toolkit</code> is used.
+     * {@code Toolkit} is used.
+     * <p>
+     * If this Toolkit is not a headless implementation and if they exist, service
+     * providers of {@link javax.accessibility.AccessibilityProvider} will be loaded
+     * if specified by the system property
+     * {@code javax.accessibility.assistive_technologies}.
+     * <p>
+     * An example of setting this property is to invoke Java with
+     * {@code -Djavax.accessibility.assistive_technologies=MyServiceProvider}.
+     * In addition to MyServiceProvider other service providers can be specified
+     * using a comma separated list.  Service providers are loaded after the AWT
+     * toolkit is created. All errors are handled via an AWTError exception.
      * <p>
-     * Also loads additional classes into the VM, using the property
-     * 'assistive_technologies' specified in the Sun reference
-     * implementation by a line in the 'accessibility.properties'
-     * file.  The form is "assistive_technologies=..." where
-     * the "..." is a comma-separated list of assistive technology
-     * classes to load.  Each class is loaded in the order given
-     * and a single instance of each is created using
-     * Class.forName(class).newInstance().  This is done just after
-     * the AWT toolkit is created.  All errors are handled via an
-     * AWTError exception.
+     * The names specified in the assistive_technologies property are used to query
+     * each service provider implementation.  If the requested name matches the
+     * {@linkplain AccessibilityProvider#getName name} of the service provider, the
+     * {@link AccessibilityProvider#activate} method will be invoked to activate the
+     * matching service provider.
+     *
+     * @implSpec
+     * If assistive technology service providers are not specified with a system
+     * property this implementation will look in a properties file located as follows:
+     * <ul>
+     * <li> {@code ${user.home}/.accessibility.properties}
+     * <li> {@code ${java.home}/conf/accessibility.properties}
+     * </ul>
+     * Only the first of these files to be located will be consulted.  The requested
+     * service providers are specified by setting the {@code assistive_technologies=}
+     * property.  A single provider or a comma separated list of providers can be
+     * specified.
+     *
      * @return    the default toolkit.
      * @exception  AWTError  if a toolkit could not be found, or
      *                 if one could not be accessed or instantiated.
+     * @see javax.accessibility.AccessibilityProvider
      */
     public static synchronized Toolkit getDefaultToolkit() {

The javadoc for the new file javax.accessibility.AccesibilityProvider is:

/**
 * Service Provider Interface (SPI) for Assistive Technology.
 * <p>
 * This service provider class provides mappings from the platform
 * specific accessibility APIs to the Java Accessibility API.
 * <p>
 * Each service provider implementation is named and can be activated via the
 * {@link #activate} method. Service providers can be loaded when the default
 * {@link java.awt.Toolkit toolkit} is initialized.
 *
 * @apiNote There will typically be one provider per platform, such as Windows
 * or Linux, to support accessibility for screen readers and magnifiers.  However,
 * more than one service provider can be activated.  For example, a test tool
 * which provides visual results obtained by interrogating the Java Accessibility
 * API can be activated along with the activation of the support for screen readers
 * and screen magnifiers.
 *
 * @see java.awt.Toolkit#getDefaultToolkit
 * @see java.util.ServiceLoader
 * @since 1.9
 */
public abstract class AccessibilityProvider {

    /**
     * Initializes a new accessibility provider.
     *
     * @throws  SecurityException
     *          If a security manager has been installed and it denies
     *          {@link RuntimePermission}{@code("accessibilityProvider")}
     */
    protected AccessibilityProvider() { ...


    /**
     * Returns the name of this service provider.  This name is used to locate a
     * requested service provider.
     *
     * @return the name of this service provider
     */
    public abstract String getName();

    /**
     * Activates the support provided by this service provider.
     */
    public abstract void activate();