[skywalking-java] branch ext-classloader created (now c3b6ef5)

[wu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a change to branch ext-classloader
in repository https://gitbox.apache.org/repos/asf/skywalking-java.git.


      at c3b6ef5  Add FAQ about `Why is `-Djava.ext.dirs` not supported?`.

This branch includes the following new commits:

     new c3b6ef5  Add FAQ about `Why is `-Djava.ext.dirs` not supported?`.

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[skywalking-java] 01/01: Add FAQ about `Why is `-Djava.ext.dirs` not supported?`.

[wu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch ext-classloader
in repository https://gitbox.apache.org/repos/asf/skywalking-java.git

commit c3b6ef5c4252178d5d6f1c6725cdb74e4b6909a9
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Sun Oct 31 21:26:44 2021 +0800

    Add FAQ about `Why is `-Djava.ext.dirs` not supported?`.
---
 docs/en/faq/ext-dirs.md | 28 ++++++++++++++++++++++++++++
 docs/menu.yml           |  4 ++++
 2 files changed, 32 insertions(+)

diff --git a/docs/en/faq/ext-dirs.md b/docs/en/faq/ext-dirs.md
new file mode 100644
index 0000000..0b2f12e
--- /dev/null
+++ b/docs/en/faq/ext-dirs.md
@@ -0,0 +1,28 @@
+## Why is `-Djava.ext.dirs` not supported?
+
+`-Djava.ext.dirs` provides the extension class loader mechanism which was introduced in JDK 1.2, which was released in 1998.
+According to [JEP 220: Modular Run-Time Images](http://openjdk.java.net/jeps/220), it ends in JDK 9, 
+to simplify both the Java SE Platform and the JDK we have removed the extension mechanism, 
+including the java.ext.dirs system property and the lib/ext directory.
+
+This JEP has been applied since JDK11, which is the most active LTS JDK version. When use `-Djava.ext.dirs` in JDK11+, 
+the JVM would not be able to boot with following error.
+```shell
+<JAVA_HOME>/lib/ext exists, extensions mechanism no longer supported; Use -classpath instead.
+.Error: Could not create the Java Virtual Machine.
+Error: A fatal exception has occurred. Program will exit.
+```
+
+So, SkyWalking agent would not support the extension class loader mechanism. 
+
+### How to resolve this issue? 
+If you are using JDK8 and `-Djava.ext.dirs`, follow the JRE recommendations, **Use -classpath instead**.
+This should be a transparent change, which only affects your booting script.
+
+Also, if you insist on keeping using `-Djava.ext.dirs`, the community had [a pull request](https://github.com/apache/skywalking-java/pull/19),
+which leverages the bootstrap instrumentation core of the agent to support the extension class loader.
+
+In theory, this should work, but the SkyWalking doesn't officially verify it before noticing the above JEP.
+You could take it as a reference. 
+
+The official recommendation still keeps as **Use -classpath instead**.
\ No newline at end of file
diff --git a/docs/menu.yml b/docs/menu.yml
index a4cb557..223b42b 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -78,6 +78,10 @@ catalog:
         path: "/en/setup/service-agent/java-agent/java-plugin-development-guide/"
       - name: "Java Agent Performance Test"
         path: "https://skyapmtest.github.io/Agent-Benchmarks/"
+  - name: "FAQs"
+    catalog:
+      - name: "Why is java.ext.dirs not supported?"
+        path: "/en/faq/ext-dirs"
   - name: "Contribution"
     catalog:
       - name: "Compiling Guidance"