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. |