# HG changeset patch # User Sebastien Jodogne # Date 1718379551 -7200 # Node ID df28170c2af393eb3b3f8cef4b7b9e71d152c23d # Parent 416c049749660ecf29a103bd972017c5386d367f documenting java diff -r 416c04974966 -r df28170c2af3 Sphinx/source/plugins/java.rst --- 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 @@ `__ 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 `. 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 `. The largest part of the +Java API is automatically generated from the `Orthanc plugin SDK in C `__ using the `Clang `__ compiler front-end. @@ -40,6 +40,157 @@ `__. +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) +`__ 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 `__, and +* For `Microsoft Windows 64 `__. + + +.. _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 ` and the +:ref:`Java SDK ` are located in the current directory, here +is a :ref:`configuration file ` 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 +`__. + + +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 +`__. + + +FHIR server for Orthanc +----------------------- + +Instructions for using the sample FHIR server for Orthanc that is +described in the `reference paper +`__ can be found in the +`source distribution +`__. + + 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 `__, and/or to send it to the `Orthanc Users discussion forum `__. Check out the :ref:`FAQ about licensing ` for more context. - - -Usage ------ - - -FHIR server ------------ - diff -r 416c04974966 -r df28170c2af3 Sphinx/source/plugins/java/Changes.java --- /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; + } + } + }); + } +} diff -r 416c04974966 -r df28170c2af3 Sphinx/source/plugins/java/ExtendingRest.java --- /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 headers, + Map getParameters, + byte[] body) { + output.answerBuffer("Hello from Java!\n".getBytes(), "text/plain"); + } + }); + } +} diff -r 416c04974966 -r df28170c2af3 Sphinx/source/plugins/java/HelloWorld.java --- /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!"); + } +} diff -r 416c04974966 -r df28170c2af3 Sphinx/source/plugins/java/HelloWorld.json --- /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" + } +} diff -r 416c04974966 -r df28170c2af3 Sphinx/source/plugins/java/HelloWorldWindows.json --- /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" + } +}