--- a/Sphinx/source/plugins/java.rst	Wed Jun 05 20:18:46 2024 +0200
+++ b/Sphinx/source/plugins/java.rst	Fri Jun 14 17:39:11 2024 +0200
@@ -15,9 +15,9 @@
 <https://en.wikipedia.org/wiki/Java_(programming_language)>`__ instead
 of the more complex C/C++ programming languages.
 
-Java plugins have access to more features and a more consistent SDK
-than :ref:`Lua scripts <lua>`. The largest part of the Java API is
-automatically generated from the `Orthanc plugin SDK in C
+Java applications for Orthanc have access to more features and a more
+consistent SDK than :ref:`Lua scripts <lua>`. The largest part of the
+Java API is automatically generated from the `Orthanc plugin SDK in C
 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.4/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__
 using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler
 front-end.
@@ -40,6 +40,157 @@
   <https://orthanc.uclouvain.be/hg/orthanc-java/>`__.
 
 
+Compilation
+-----------
+
+The Java plugin for Orthanc implies the compilation of two modules:
+
+- The **plugin shared library**, which is needed for all users to run
+  Java applications from within Orthanc, and
+
+- The **Orthanc Java SDK**, which is needed for developers of Java
+  applications for Orthanc.
+
+
+.. _java_shared_library:
+
+Shared library
+^^^^^^^^^^^^^^
+
+.. highlight:: text
+
+If targeting **GNU/Linux distributions**, compiling the shared library
+of the Java plugin (which is written in C++) works as follows::
+
+  $ mkdir BuildPlugin
+  $ cd BuildPlugin
+  $ cmake ../Plugin -DCMAKE_BUILD_TYPE=Release
+  $ make
+
+This requires the `JNI (Java Native Interface)
+<https://en.wikipedia.org/wiki/Java_Native_Interface>`__ to be
+installed on your system (on Ubuntu setups, you can simply install the
+``default-jdk`` package). This produces the ``libOrthancJava.so``
+shared library. This shared library depends on the very specific
+configuration of your system, so precompiled binaries are not
+available.
+
+If targeting **Microsoft Windows**, the supported way of compiling the
+plugin consists in using the MinGW toolchains to cross-compile the
+shared library on a GNU/Linux host::
+
+  $ mkdir BuildWindows64
+  $ cd BuildWindows64
+  $ cmake ../Plugin -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release \
+    -DCMAKE_TOOLCHAIN_FILE=../Resources/Orthanc/Toolchains/MinGW-W64-Toolchain64.cmake
+  $ make
+
+This produces the ``libOrthancJava.dll`` shared library. Contrarily to
+GNU/Linux distributions, precompiled binaries are available:
+
+* For `Microsoft Windows 32 <https://orthanc.uclouvain.be/downloads/windows-32/orthanc-java/index.html>`__, and
+* For `Microsoft Windows 64 <https://orthanc.uclouvain.be/downloads/windows-64/orthanc-java/index.html>`__.
+
+
+.. _java_sdk:
+
+Java SDK
+^^^^^^^^
+
+In addition to the shared library that is needed by all the users, the
+developers of Java applications for Orthanc need a set of Java classes
+that provide access to the native functions of the Orthanc plugin SDK.
+
+The Orthanc Java SDK is available in the folder ``JavaSDK`` of the
+source distribution. A cross-platform ``.jar`` file containing the
+Orthanc Java SDK can be compiled as follows::
+
+  $ mkdir BuildJavaSDK
+  $ cd BuildJavaSDK
+  $ cmake ../JavaSDK
+  $ make
+
+This requires a JDK to be installed on your computer. This generates
+the file ``OrthancJavaSDK.jar``.
+
+
+Usage
+-----
+
+Here is a minimal example of a Java application for Orthanc:
+
+.. literalinclude:: java/HelloWorld.java
+                    :language: java
+
+If both the :ref:`shared library <java_shared_library>` and the
+:ref:`Java SDK <java_sdk>` are located in the current directory, here
+is a :ref:`configuration file <configuration>` to run this sample Java
+application on a GNU/Linux distribution:
+
+.. literalinclude:: java/HelloWorld.json
+                    :language: json
+
+Orthanc can then be started as follows (the path to ``libjvm.so`` must
+be adapted depending on your configuration)::
+
+  $ javac HelloWorld.java -classpath ./OrthancJavaSDK.jar
+  $ LD_PRELOAD=/usr/lib/jvm/java-11-openjdk-amd64/lib/server/libjvm.so ./Orthanc ./HelloWorld.json
+
+On Microsoft Windows, one would use the following configuration file
+(beware of the ``:`` that is replaced by ``;`` in the ``Classpath``
+option):
+
+.. literalinclude:: java/HelloWorldWindows.json
+                    :language: json
+
+This example simply outputs a line in the logs of Orthanc. Indeed, the
+``static`` section of the class that is specified in the
+``InitializationClass`` option is executed during the initialization
+of the plugin.
+
+You can find the full **Javadoc documentation of the Orthanc Java
+SDK** `at the following location
+<https://orthanc.uclouvain.be/javadoc/>`__.
+
+
+Examples
+--------
+
+Adding a route in the REST API of Orthanc
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+New routes can be added to the REST API of Orthanc as follows:
+
+.. literalinclude:: java/ExtendingRest.java
+                    :language: java
+
+Reacting to events
+^^^^^^^^^^^^^^^^^^
+
+Java applications can react to Orthanc events as follows:
+
+.. literalinclude:: java/Changes.java
+                    :language: java
+
+
+Additional samples
+^^^^^^^^^^^^^^^^^^
+
+More advanced samples using Maven can be found `in the source
+distribution of the Java plugin
+<https://orthanc.uclouvain.be/hg/orthanc-java/file/default/Samples>`__.
+
+
+FHIR server for Orthanc
+-----------------------
+
+Instructions for using the sample FHIR server for Orthanc that is
+described in the `reference paper
+<https://doi.org/10.5220/0012384600003657>`__ can be found in the
+`source distribution
+<https://orthanc.uclouvain.be/hg/orthanc-java/file/default/Samples/FHIR/NOTES.txt>`__.
+
+
 Licensing
 ---------
 
@@ -49,22 +200,13 @@
 
 This has an important consequence: If you distribute Orthanc to
 clients together with one Java plugin, you **must** disclose the
-source code of your Java script to the Orthanc community under the
+source code of your Java plugins to the Orthanc community under the
 terms of the GPL or AGPL licenses.
 
-We suggest you to put the source code of your Java scripts on the
+We suggest you to put the source code of your Java plugins on the
 dedicated `"OrthancContributed" repository on GitHub
 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__,
 and/or to send it to the `Orthanc Users discussion forum
 <https://discourse.orthanc-server.org>`__.
 
 Check out the :ref:`FAQ about licensing <licensing>` for more context.
-
-
-Usage
------
-
-
-FHIR server
------------
-

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/java/Changes.java	Fri Jun 14 17:39:11 2024 +0200
@@ -0,0 +1,26 @@
+import be.uclouvain.orthanc.Callbacks;
+import be.uclouvain.orthanc.ChangeType;
+import be.uclouvain.orthanc.Functions;
+import be.uclouvain.orthanc.ResourceType;
+
+public class Changes {
+    static {
+        Callbacks.register(new Callbacks.OnChange() {
+            @Override
+            public void call(ChangeType changeType, ResourceType resourceType, String resourceId) {
+                switch (changeType) {
+                case ORTHANC_STARTED:
+                    Functions.logWarning("Orthanc has started");
+                    break;
+
+                case ORTHANC_STOPPED:
+                    Functions.logWarning("Orthanc has stopped");
+                    break;
+
+                default:
+                    break;
+                }
+            }
+        });
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/java/ExtendingRest.java	Fri Jun 14 17:39:11 2024 +0200
@@ -0,0 +1,22 @@
+import be.uclouvain.orthanc.Callbacks;
+import be.uclouvain.orthanc.HttpMethod;
+import be.uclouvain.orthanc.RestOutput;
+
+import java.util.Map;
+
+public class ExtendingRest {
+    static {
+        Callbacks.register("/java", new Callbacks.OnRestRequest() {
+            @Override
+            public void call(RestOutput output,
+                             HttpMethod method,
+                             String uri,
+                             String[] regularExpressionGroups,
+                             Map<String, String> headers,
+                             Map<String, String> getParameters,
+                             byte[] body) {
+                output.answerBuffer("Hello from Java!\n".getBytes(), "text/plain");
+            }
+        });
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/java/HelloWorld.java	Fri Jun 14 17:39:11 2024 +0200
@@ -0,0 +1,7 @@
+import be.uclouvain.orthanc.Functions;
+
+public class HelloWorld {
+    static {
+        Functions.logWarning("Hello from Java!");
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/java/HelloWorld.json	Fri Jun 14 17:39:11 2024 +0200
@@ -0,0 +1,8 @@
+{
+  "Plugins" : [ "./libOrthancJava.so" ],
+  "Java" : {
+    "Enabled" : true,
+    "Classpath" : "./OrthancJavaSDK.jar:.",
+    "InitializationClass" : "HelloWorld"
+  }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/java/HelloWorldWindows.json	Fri Jun 14 17:39:11 2024 +0200
@@ -0,0 +1,8 @@
+{
+  "Plugins" : [ "./OrthancJava.dll" ],
+  "Java" : {
+    "Enabled" : true,
+    "Classpath" : "./OrthancJavaSDK.jar;.",
+    "InitializationClass" : "HelloWorld"
+  }
+}