Add docs

docs/polyglot/java.md

@@ -65,6 +65,21 @@ main =
 >
 > - Expand on the detail when there is time.
 
+## Native libraries
+Java can load native libraries using, e.g., the [System.loadLibrary](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/System.html#loadLibrary(java.lang.String))
+or [ClassLoader.findLibrary](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ClassLoader.html#findLibrary(java.lang.String))
+methods.
+If a Java method loaded from the `polyglot/java` directory in project `Proj` tries to load a
+native library via one of the aforementioned mechanisms, the runtime system will look for the
+native library in the `polyglot/lib` directory within the project `Proj`.
+The algorithm used to search for the native libraries within the `polyglot/lib` directory hierarchy conforms to the [NetBeans JNI specification](https://bits.netbeans.org/23/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html#jni).
+The runtime system implements this by overriding the [ClassLoader.findLibrary](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ClassLoader.html#findLibrary(java.lang.String))
+method on the `ClassLoader` used to load the Java class.
+
+Only the `polyglot/lib` directory within the project is searched for the native libraries.
+This means that the native library search path is effectively _isolated_ for every project.
+
+
 ## Download a Java Library from Maven Central
 
 A typical use-case when bringing in some popular Java library into Enso