Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/java.rst @ 1113:a588960a72e5 default tip
spelling
| author | Alain Mazy <am@orthanc.team> |
|---|---|
| date | Mon, 28 Oct 2024 09:23:08 +0100 |
| parents | 9fdd3714efc1 |
| children |
| 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 | |
| 1090 | 25 As of release 1.0 of the plugin, **the coverage of the C SDK is about |
| 26 74%** (122 functions are automatically wrapped in Java out of a total | |
| 27 of 165 functions from the Orthanc SDK 1.10.0). | |
| 999 | 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 |
|
1081
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
33 How to get it ? |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
34 --------------- |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
35 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
36 Binaries are included in: |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
37 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
38 - The `orthancteam/orthanc Docker image <https://hub.docker.com/r/orthancteam/orthanc>`__ |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
39 - The `Windows Installer <https://www.orthanc-server.com/download-windows.php>`__ |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
40 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
41 Release notes are available `here <https://orthanc.uclouvain.be/hg/orthanc-java/file/tip/NEWS>`__. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
42 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
43 Compilation instructions are available below. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
44 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
45 |
| 999 | 46 Source code |
| 47 ----------- | |
| 48 | |
| 49 * Link to the `official releases of this plugin | |
| 50 <https://orthanc.uclouvain.be/downloads/sources/orthanc-java/index.html>`__. | |
| 51 | |
| 52 * Link to the `code repository | |
| 53 <https://orthanc.uclouvain.be/hg/orthanc-java/>`__. | |
| 54 | |
| 55 | |
| 1077 | 56 Compilation |
| 57 ----------- | |
| 58 | |
| 59 The Java plugin for Orthanc implies the compilation of two modules: | |
| 60 | |
| 61 - The **plugin shared library**, which is needed for all users to run | |
| 62 Java applications from within Orthanc, and | |
| 63 | |
| 64 - The **Orthanc Java SDK**, which is needed for developers of Java | |
| 65 applications for Orthanc. | |
| 66 | |
| 67 | |
| 68 .. _java_shared_library: | |
| 69 | |
| 70 Shared library | |
| 71 ^^^^^^^^^^^^^^ | |
| 72 | |
| 73 .. highlight:: text | |
| 74 | |
| 75 If targeting **GNU/Linux distributions**, compiling the shared library | |
| 76 of the Java plugin (which is written in C++) works as follows:: | |
| 77 | |
| 78 $ mkdir BuildPlugin | |
| 79 $ cd BuildPlugin | |
| 80 $ cmake ../Plugin -DCMAKE_BUILD_TYPE=Release | |
| 81 $ make | |
| 82 | |
| 83 This requires the `JNI (Java Native Interface) | |
| 84 <https://en.wikipedia.org/wiki/Java_Native_Interface>`__ to be | |
| 85 installed on your system (on Ubuntu setups, you can simply install the | |
| 86 ``default-jdk`` package). This produces the ``libOrthancJava.so`` | |
| 87 shared library. This shared library depends on the very specific | |
| 88 configuration of your system, so precompiled binaries are not | |
| 89 available. | |
| 90 | |
| 91 If targeting **Microsoft Windows**, the supported way of compiling the | |
| 92 plugin consists in using the MinGW toolchains to cross-compile the | |
| 93 shared library on a GNU/Linux host:: | |
| 94 | |
| 95 $ mkdir BuildWindows64 | |
| 96 $ cd BuildWindows64 | |
| 97 $ cmake ../Plugin -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release \ | |
| 98 -DCMAKE_TOOLCHAIN_FILE=../Resources/Orthanc/Toolchains/MinGW-W64-Toolchain64.cmake | |
| 99 $ make | |
| 100 | |
| 101 This produces the ``libOrthancJava.dll`` shared library. Contrarily to | |
| 102 GNU/Linux distributions, precompiled binaries are available: | |
| 103 | |
| 104 * For `Microsoft Windows 32 <https://orthanc.uclouvain.be/downloads/windows-32/orthanc-java/index.html>`__, and | |
| 105 * For `Microsoft Windows 64 <https://orthanc.uclouvain.be/downloads/windows-64/orthanc-java/index.html>`__. | |
| 106 | |
| 107 | |
| 108 .. _java_sdk: | |
| 109 | |
| 110 Java SDK | |
| 111 ^^^^^^^^ | |
| 112 | |
| 113 In addition to the shared library that is needed by all the users, the | |
| 114 developers of Java applications for Orthanc need a set of Java classes | |
| 115 that provide access to the native functions of the Orthanc plugin SDK. | |
| 116 | |
| 117 The Orthanc Java SDK is available in the folder ``JavaSDK`` of the | |
| 1078 | 118 source distribution. A ``.jar`` file containing the Orthanc Java SDK |
| 119 can be compiled as follows:: | |
| 1077 | 120 |
| 121 $ mkdir BuildJavaSDK | |
| 122 $ cd BuildJavaSDK | |
| 123 $ cmake ../JavaSDK | |
| 124 $ make | |
| 125 | |
| 126 This requires a JDK to be installed on your computer. This generates | |
| 1078 | 127 the file ``OrthancJavaSDK.jar``. Alternatively, this cross-platform |
| 128 ``.jar`` library is available in a precompiled form at: | |
| 129 | |
| 130 * The `following location | |
| 131 <https://orthanc.uclouvain.be/downloads/cross-platform/orthanc-java/index.html>`__ | |
| 132 (evidently, make sure to download the version that matches your | |
| 133 version of the ``libOrthancJava.so|.dll`` shared library). | |
| 1077 | 134 |
| 135 | |
| 136 Usage | |
| 137 ----- | |
| 138 | |
| 139 Here is a minimal example of a Java application for Orthanc: | |
| 140 | |
| 141 .. literalinclude:: java/HelloWorld.java | |
| 142 :language: java | |
| 143 | |
| 144 If both the :ref:`shared library <java_shared_library>` and the | |
| 145 :ref:`Java SDK <java_sdk>` are located in the current directory, here | |
| 146 is a :ref:`configuration file <configuration>` to run this sample Java | |
| 147 application on a GNU/Linux distribution: | |
| 148 | |
| 149 .. literalinclude:: java/HelloWorld.json | |
| 150 :language: json | |
| 151 | |
| 152 Orthanc can then be started as follows (the path to ``libjvm.so`` must | |
| 153 be adapted depending on your configuration):: | |
| 154 | |
| 155 $ javac HelloWorld.java -classpath ./OrthancJavaSDK.jar | |
| 156 $ LD_PRELOAD=/usr/lib/jvm/java-11-openjdk-amd64/lib/server/libjvm.so ./Orthanc ./HelloWorld.json | |
| 157 | |
| 158 On Microsoft Windows, one would use the following configuration file | |
| 159 (beware of the ``:`` that is replaced by ``;`` in the ``Classpath`` | |
| 160 option): | |
| 161 | |
| 162 .. literalinclude:: java/HelloWorldWindows.json | |
| 163 :language: json | |
| 164 | |
| 165 This example simply outputs a line in the logs of Orthanc. Indeed, the | |
| 166 ``static`` section of the class that is specified in the | |
| 167 ``InitializationClass`` option is executed during the initialization | |
| 168 of the plugin. | |
| 169 | |
| 170 You can find the full **Javadoc documentation of the Orthanc Java | |
| 171 SDK** `at the following location | |
| 172 <https://orthanc.uclouvain.be/javadoc/>`__. | |
| 173 | |
| 174 | |
|
1081
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
175 Troubleshooting |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
176 --------------- |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
177 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
178 Microsoft Windows |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
179 ................. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
180 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
181 Pre-compiled binaries for Microsoft Windows are now part of the |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
182 `Windows installers <https://www.orthanc-server.com/download-windows.php>`__ |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
183 but not installed by default. They are also `available here |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
184 <https://orthanc.uclouvain.be/downloads/windows-64/orthanc-java/index.html>`__. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
185 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
186 Pay also attention to pick the right 32/64 bits version. If you are |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
187 running Orthanc 64bits, install Java in 64bits and select the 64bits |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
188 Java plugin too. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
189 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
190 When you install Java on your Windows machine, make sure to add the path to |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
191 ``jvm.dll`` to your ``Path`` environment variable for at ``System`` level, not user level. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
192 E.g: ``C:\Program Files\Java\jre-1.8\bin\server\``. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
193 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
194 If you get the following error:: |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
195 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
196 LoadLibrary(C:\Program Files\Orthanc Server\Plugins\OrthancJava.dll) failed: Error 126 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
197 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
198 This very likely means that OrthancJava.dll can not find the ``jvm.dll``. Check your system ``Path``. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
199 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
200 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
201 If you get the following errors:: |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
202 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
203 LoadLibrary(C:\Program Files\Orthanc Server\Plugins\OrthancJava.dll) failed: Error 193 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
204 Error while using a shared library (plugin): You are most probably trying to load a 32bit plugin into a 64bit version of Orthanc |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
205 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
206 This very likely means that Java 32bits has been installed on a 64bits version of Windows. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
207 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
208 `Process Monitor <https://learn.microsoft.com/en-us/sysinternals/downloads/procmon>`__ |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
209 should allow you to debug this type of errors. |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
210 |
|
649d180ed8ad
Java binaries + windows troubleshooting
Alain Mazy <am@orthanc.team>
parents:
1078
diff
changeset
|
211 |
| 1077 | 212 Examples |
| 213 -------- | |
| 214 | |
| 215 Adding a route in the REST API of Orthanc | |
| 216 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 217 | |
| 218 New routes can be added to the REST API of Orthanc as follows: | |
| 219 | |
| 220 .. literalinclude:: java/ExtendingRest.java | |
| 221 :language: java | |
| 222 | |
| 223 Reacting to events | |
| 224 ^^^^^^^^^^^^^^^^^^ | |
| 225 | |
| 226 Java applications can react to Orthanc events as follows: | |
| 227 | |
| 228 .. literalinclude:: java/Changes.java | |
| 229 :language: java | |
| 230 | |
| 231 | |
| 232 Additional samples | |
| 233 ^^^^^^^^^^^^^^^^^^ | |
| 234 | |
| 235 More advanced samples using Maven can be found `in the source | |
| 236 distribution of the Java plugin | |
| 237 <https://orthanc.uclouvain.be/hg/orthanc-java/file/default/Samples>`__. | |
| 238 | |
| 239 | |
| 240 FHIR server for Orthanc | |
| 241 ----------------------- | |
| 242 | |
| 243 Instructions for using the sample FHIR server for Orthanc that is | |
| 244 described in the `reference paper | |
| 245 <https://doi.org/10.5220/0012384600003657>`__ can be found in the | |
| 246 `source distribution | |
| 1078 | 247 <https://orthanc.uclouvain.be/hg/orthanc-java/file/default/Samples/FHIR/>`__. |
| 248 | |
| 249 A precompiled version of the FHIR server is also available at the | |
| 250 `following location | |
| 251 <https://orthanc.uclouvain.be/downloads/cross-platform/orthanc-java/index.html>`__. | |
| 252 | |
| 1077 | 253 |
| 254 | |
| 999 | 255 Licensing |
| 256 --------- | |
| 257 | |
| 258 This plugin is licensed under the terms of the `GPLv3+ license | |
| 259 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__, | |
| 260 which is the same as the core of Orthanc. | |
| 261 | |
| 262 This has an important consequence: If you distribute Orthanc to | |
| 263 clients together with one Java plugin, you **must** disclose the | |
| 1077 | 264 source code of your Java plugins to the Orthanc community under the |
| 999 | 265 terms of the GPL or AGPL licenses. |
| 266 | |
| 1077 | 267 We suggest you to put the source code of your Java plugins on the |
| 999 | 268 dedicated `"OrthancContributed" repository on GitHub |
| 269 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__, | |
| 270 and/or to send it to the `Orthanc Users discussion forum | |
| 271 <https://discourse.orthanc-server.org>`__. | |
| 272 | |
| 273 Check out the :ref:`FAQ about licensing <licensing>` for more context. |