Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/java.rst @ 1077:df28170c2af3
documenting java
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Fri, 14 Jun 2024 17:39:11 +0200 |
| parents | d2be251975d1 |
| children | a8d6ae201eeb |
| rev | line source |
|---|---|
| 999 | 1 .. _java-plugin: |
| 2 | |
| 3 | |
| 4 Java plugin for Orthanc | |
| 5 ======================= | |
| 6 | |
| 7 .. contents:: | |
| 8 | |
| 9 | |
| 10 Overview | |
| 11 -------- | |
| 12 | |
| 13 This plugin can be used to write :ref:`Orthanc plugins | |
| 14 <creating-plugins>` using the `Java programming language | |
| 15 <https://en.wikipedia.org/wiki/Java_(programming_language)>`__ instead | |
| 16 of the more complex C/C++ programming languages. | |
| 17 | |
| 1077 | 18 Java applications for Orthanc have access to more features and a more |
| 19 consistent SDK than :ref:`Lua scripts <lua>`. The largest part of the | |
| 20 Java API is automatically generated from the `Orthanc plugin SDK in C | |
| 1075 | 21 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.4/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ |
| 999 | 22 using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler |
| 23 front-end. | |
| 24 | |
| 25 As of release 1.0 of the plugin, the coverage of the C SDK is about | |
| 26 76% (122 functions are automatically wrapped in Java out of a total of | |
| 27 160 functions from the Orthanc SDK 1.10.0). | |
| 28 | |
|
1055
ebe3214f3ab0
added citation instructions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1021
diff
changeset
|
29 **For researchers**: `Please cite this paper |
|
ebe3214f3ab0
added citation instructions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1021
diff
changeset
|
30 <https://doi.org/10.5220/0012384600003657>`__. |
|
ebe3214f3ab0
added citation instructions
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1021
diff
changeset
|
31 |
| 999 | 32 |
| 33 Source code | |
| 34 ----------- | |
| 35 | |
| 36 * Link to the `official releases of this plugin | |
| 37 <https://orthanc.uclouvain.be/downloads/sources/orthanc-java/index.html>`__. | |
| 38 | |
| 39 * Link to the `code repository | |
| 40 <https://orthanc.uclouvain.be/hg/orthanc-java/>`__. | |
| 41 | |
| 42 | |
| 1077 | 43 Compilation |
| 44 ----------- | |
| 45 | |
| 46 The Java plugin for Orthanc implies the compilation of two modules: | |
| 47 | |
| 48 - The **plugin shared library**, which is needed for all users to run | |
| 49 Java applications from within Orthanc, and | |
| 50 | |
| 51 - The **Orthanc Java SDK**, which is needed for developers of Java | |
| 52 applications for Orthanc. | |
| 53 | |
| 54 | |
| 55 .. _java_shared_library: | |
| 56 | |
| 57 Shared library | |
| 58 ^^^^^^^^^^^^^^ | |
| 59 | |
| 60 .. highlight:: text | |
| 61 | |
| 62 If targeting **GNU/Linux distributions**, compiling the shared library | |
| 63 of the Java plugin (which is written in C++) works as follows:: | |
| 64 | |
| 65 $ mkdir BuildPlugin | |
| 66 $ cd BuildPlugin | |
| 67 $ cmake ../Plugin -DCMAKE_BUILD_TYPE=Release | |
| 68 $ make | |
| 69 | |
| 70 This requires the `JNI (Java Native Interface) | |
| 71 <https://en.wikipedia.org/wiki/Java_Native_Interface>`__ to be | |
| 72 installed on your system (on Ubuntu setups, you can simply install the | |
| 73 ``default-jdk`` package). This produces the ``libOrthancJava.so`` | |
| 74 shared library. This shared library depends on the very specific | |
| 75 configuration of your system, so precompiled binaries are not | |
| 76 available. | |
| 77 | |
| 78 If targeting **Microsoft Windows**, the supported way of compiling the | |
| 79 plugin consists in using the MinGW toolchains to cross-compile the | |
| 80 shared library on a GNU/Linux host:: | |
| 81 | |
| 82 $ mkdir BuildWindows64 | |
| 83 $ cd BuildWindows64 | |
| 84 $ cmake ../Plugin -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release \ | |
| 85 -DCMAKE_TOOLCHAIN_FILE=../Resources/Orthanc/Toolchains/MinGW-W64-Toolchain64.cmake | |
| 86 $ make | |
| 87 | |
| 88 This produces the ``libOrthancJava.dll`` shared library. Contrarily to | |
| 89 GNU/Linux distributions, precompiled binaries are available: | |
| 90 | |
| 91 * For `Microsoft Windows 32 <https://orthanc.uclouvain.be/downloads/windows-32/orthanc-java/index.html>`__, and | |
| 92 * For `Microsoft Windows 64 <https://orthanc.uclouvain.be/downloads/windows-64/orthanc-java/index.html>`__. | |
| 93 | |
| 94 | |
| 95 .. _java_sdk: | |
| 96 | |
| 97 Java SDK | |
| 98 ^^^^^^^^ | |
| 99 | |
| 100 In addition to the shared library that is needed by all the users, the | |
| 101 developers of Java applications for Orthanc need a set of Java classes | |
| 102 that provide access to the native functions of the Orthanc plugin SDK. | |
| 103 | |
| 104 The Orthanc Java SDK is available in the folder ``JavaSDK`` of the | |
| 105 source distribution. A cross-platform ``.jar`` file containing the | |
| 106 Orthanc Java SDK can be compiled as follows:: | |
| 107 | |
| 108 $ mkdir BuildJavaSDK | |
| 109 $ cd BuildJavaSDK | |
| 110 $ cmake ../JavaSDK | |
| 111 $ make | |
| 112 | |
| 113 This requires a JDK to be installed on your computer. This generates | |
| 114 the file ``OrthancJavaSDK.jar``. | |
| 115 | |
| 116 | |
| 117 Usage | |
| 118 ----- | |
| 119 | |
| 120 Here is a minimal example of a Java application for Orthanc: | |
| 121 | |
| 122 .. literalinclude:: java/HelloWorld.java | |
| 123 :language: java | |
| 124 | |
| 125 If both the :ref:`shared library <java_shared_library>` and the | |
| 126 :ref:`Java SDK <java_sdk>` are located in the current directory, here | |
| 127 is a :ref:`configuration file <configuration>` to run this sample Java | |
| 128 application on a GNU/Linux distribution: | |
| 129 | |
| 130 .. literalinclude:: java/HelloWorld.json | |
| 131 :language: json | |
| 132 | |
| 133 Orthanc can then be started as follows (the path to ``libjvm.so`` must | |
| 134 be adapted depending on your configuration):: | |
| 135 | |
| 136 $ javac HelloWorld.java -classpath ./OrthancJavaSDK.jar | |
| 137 $ LD_PRELOAD=/usr/lib/jvm/java-11-openjdk-amd64/lib/server/libjvm.so ./Orthanc ./HelloWorld.json | |
| 138 | |
| 139 On Microsoft Windows, one would use the following configuration file | |
| 140 (beware of the ``:`` that is replaced by ``;`` in the ``Classpath`` | |
| 141 option): | |
| 142 | |
| 143 .. literalinclude:: java/HelloWorldWindows.json | |
| 144 :language: json | |
| 145 | |
| 146 This example simply outputs a line in the logs of Orthanc. Indeed, the | |
| 147 ``static`` section of the class that is specified in the | |
| 148 ``InitializationClass`` option is executed during the initialization | |
| 149 of the plugin. | |
| 150 | |
| 151 You can find the full **Javadoc documentation of the Orthanc Java | |
| 152 SDK** `at the following location | |
| 153 <https://orthanc.uclouvain.be/javadoc/>`__. | |
| 154 | |
| 155 | |
| 156 Examples | |
| 157 -------- | |
| 158 | |
| 159 Adding a route in the REST API of Orthanc | |
| 160 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 161 | |
| 162 New routes can be added to the REST API of Orthanc as follows: | |
| 163 | |
| 164 .. literalinclude:: java/ExtendingRest.java | |
| 165 :language: java | |
| 166 | |
| 167 Reacting to events | |
| 168 ^^^^^^^^^^^^^^^^^^ | |
| 169 | |
| 170 Java applications can react to Orthanc events as follows: | |
| 171 | |
| 172 .. literalinclude:: java/Changes.java | |
| 173 :language: java | |
| 174 | |
| 175 | |
| 176 Additional samples | |
| 177 ^^^^^^^^^^^^^^^^^^ | |
| 178 | |
| 179 More advanced samples using Maven can be found `in the source | |
| 180 distribution of the Java plugin | |
| 181 <https://orthanc.uclouvain.be/hg/orthanc-java/file/default/Samples>`__. | |
| 182 | |
| 183 | |
| 184 FHIR server for Orthanc | |
| 185 ----------------------- | |
| 186 | |
| 187 Instructions for using the sample FHIR server for Orthanc that is | |
| 188 described in the `reference paper | |
| 189 <https://doi.org/10.5220/0012384600003657>`__ can be found in the | |
| 190 `source distribution | |
| 191 <https://orthanc.uclouvain.be/hg/orthanc-java/file/default/Samples/FHIR/NOTES.txt>`__. | |
| 192 | |
| 193 | |
| 999 | 194 Licensing |
| 195 --------- | |
| 196 | |
| 197 This plugin is licensed under the terms of the `GPLv3+ license | |
| 198 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__, | |
| 199 which is the same as the core of Orthanc. | |
| 200 | |
| 201 This has an important consequence: If you distribute Orthanc to | |
| 202 clients together with one Java plugin, you **must** disclose the | |
| 1077 | 203 source code of your Java plugins to the Orthanc community under the |
| 999 | 204 terms of the GPL or AGPL licenses. |
| 205 | |
| 1077 | 206 We suggest you to put the source code of your Java plugins on the |
| 999 | 207 dedicated `"OrthancContributed" repository on GitHub |
| 208 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__, | |
| 209 and/or to send it to the `Orthanc Users discussion forum | |
| 210 <https://discourse.orthanc-server.org>`__. | |
| 211 | |
| 212 Check out the :ref:`FAQ about licensing <licensing>` for more context. |