Summary
-------

Distribute the `jdk.jsobject` module with JavaFX for use by JavaFX WebView applications in preparation for that module being removed from the JDK.


Problem
-------

The `jdk.jsobject` module, which is currently part of the JDK, will be deprecated for removal in JDK 24 by [JDK-8311530](https://bugs.openjdk.org/browse/JDK-8311530) / CSR [JDK-8338249](https://bugs.openjdk.org/browse/JDK-8338249).This module is not used anywhere in the JDK itself, and the only remaining use is in JavaFX to enable WebView applications to do Java <--> JavaScript interoperation with web pages rendered by WebView. The primary class that enables this is `netscape.javascript.JSObject`.

Once the `jdk.jsobject` module is removed from the JDK, which might be as early as JDK 26, applications using `JSObject` will no longer compile or run. Additionally, the `javafx.web` module depends upon `jdk.jsobject`, so any application that uses WebView will fail, because the `javafx.web` module will no longer be able to be loaded.

Solution
--------

Build and deliver a copy of the `jdk.jsobject` module as part of JavaFX along with the javafx.* modules. When building and testing JavaFX WebView, always use the version of `jdk.jsobject` included with JavaFX. This will provide a smooth transition for application developers with no source code changes on their part.

The `jdk.jsobject` module and all classes will be identical to that which currently ships in the JDK, therefore preserving both source and binary compatibility. An application that uses `JSObject`, and compiles against JDK 23, which will pick up the `JSObject` class from the JDK, can run in JDK 24 with JavaFX 24 using the version of `jdk.jsobject` from either the JDK or JavaFX. This is possible because `jdk.jsobject` will be an upgradable module in JDK 24, in addition to being deprecated for removal.

There are three modes of operations that applications typically compile and run in:

1. Using the set of modular jars from the JavaFX SDK
2. Using `jlink` to produce a JDK that includes the JavaFX modules, and optionally, your application
3. Using the JavaFX artifacts hosted on maven central as dependencies in a maven or gradle script


Taking each of these scenarios separately, here is how they will work with JDK 24 + JavaFX 24:

### Using the set of modular jars from the JavaFX SDK

Running the standard way, putting the JavaFX modules on the `--module-path` as follows:

```
javac --module-path=/path/to/javafx-sdk-24/lib
java --module-path=/path/to/javafx-sdk-24/lib
```

The above will result in the `jdk.jsobject` from the JDK being used, which will include deprecation for removal warnings for `JSObject`.

Optionally, put the JavaFX modules on the `--upgrade-module-path` to use the version from JavaFX and avoid these warnings:

```
javac --upgrade-module-path=/path/to/javafx-sdk-24/lib
java --upgrade-module-path=/path/to/javafx-sdk-24/lib
```

The above will result in the `jdk.jsobject` from JavaFX being used, avoiding any deprecation warnings. 

NOTE: Using `--upgrade-module-path` will result in an error if you use JDK 23 or earlier to run your program. Use `--module-path` instead.


### Using `jlink` to produce a JDK that includes the JavaFX modules

Running jlink using the set of options you normally use to produce the JDK + JavaFX will produce a JDK that includes the `jdk.jsobject` module from JavaFX:

```
jlink --output jdk-with-javafx \
    --module-path /path/to/javafx-jmods-24 \
    --add-modules ALL-MODULE-PATH
```

You can then run `javac` and `java` using that JDK with no deprecation warnings.

NOTE: This will result in an error if you use JDK 23 or earlier to run jlink. We recommend running JavaFX 24 with JDK 24, but developers can continue to use JDK 23 if they explicitly put the jmods from the JDK on the module path ahead of the JavaFX modules. For example:

```
jlink --output jdk-with-javafx \
    --module-path /path/to/jdk-23/jmods:/path/to/javafx-jmods-24 \
    --add-modules ALL-MODULE-PATH
```


### Using the JavaFX artifacts hosted on maven central

The javafx.web pom file will include a dependency on `jdk.jsobject`. This will result in the `jdk.jsobject` from the JDK being used, since it does not use the `--upgrade-module-path`, but will allow applications to continue to run on a JDK in the future with `jdk.jsobject` removed.


Specification
-------------

Add the following module, package, and classes to JavaFX:

Module: `jdk.jsobject`

Package: `netscape.javascript`

Classes:

* `JSObject`
* `JSException`

See the attached file apidiff-8337280.zip file for the complete specification.