From 0758e7c569457ab64a21db5babcbad48e2579f15 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=B4=E6=99=9F=20Wu=20Sheng?= <wu.sheng@foxmail.com>
Date: Sun, 31 Oct 2021 21:48:37 +0800
Subject: [PATCH] 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(+)
 create mode 100644 docs/en/faq/ext-dirs.md

diff --git a/CHANGES.md b/CHANGES.md
index 47b2fef1e..beded1370 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 000000000..0b2f12ecd
--- /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 a4cb55711..223b42bb0 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"