[skywalking-java] branch main updated: Add FAQ about `Why is -Djava.ext.dirs not supported?` (#63)

[wu...@apache.org]

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

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


The following commit(s) were added to refs/heads/main by this push:
     new 0758e7c  Add FAQ about `Why is -Djava.ext.dirs not supported?` (#63)
0758e7c is described below

commit 0758e7c569457ab64a21db5babcbad48e2579f15
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Sun Oct 31 21:48:37 2021 +0800

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

diff --git a/CHANGES.md b/CHANGES.md
index 47b2fef..beded13 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -9,6 +9,8 @@ Release Notes.
 
 #### Documentation
 
+* Add a FAQ, `Why is `-Djava.ext.dirs` not supported?`.
+
 All issues and pull requests are [here](https://github.com/apache/skywalking/milestone/99?closed=1)
 
 ------------------
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"