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