Mercurial > hg > orthanc-book
comparison 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 |
comparison
equal
deleted
inserted
replaced
1076:416c04974966 | 1077:df28170c2af3 |
---|---|
13 This plugin can be used to write :ref:`Orthanc plugins | 13 This plugin can be used to write :ref:`Orthanc plugins |
14 <creating-plugins>` using the `Java programming language | 14 <creating-plugins>` using the `Java programming language |
15 <https://en.wikipedia.org/wiki/Java_(programming_language)>`__ instead | 15 <https://en.wikipedia.org/wiki/Java_(programming_language)>`__ instead |
16 of the more complex C/C++ programming languages. | 16 of the more complex C/C++ programming languages. |
17 | 17 |
18 Java plugins have access to more features and a more consistent SDK | 18 Java applications for Orthanc have access to more features and a more |
19 than :ref:`Lua scripts <lua>`. The largest part of the Java API is | 19 consistent SDK than :ref:`Lua scripts <lua>`. The largest part of the |
20 automatically generated from the `Orthanc plugin SDK in C | 20 Java API is automatically generated from the `Orthanc plugin SDK in C |
21 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.4/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ | 21 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.4/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ |
22 using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler | 22 using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler |
23 front-end. | 23 front-end. |
24 | 24 |
25 As of release 1.0 of the plugin, the coverage of the C SDK is about | 25 As of release 1.0 of the plugin, the coverage of the C SDK is about |
38 | 38 |
39 * Link to the `code repository | 39 * Link to the `code repository |
40 <https://orthanc.uclouvain.be/hg/orthanc-java/>`__. | 40 <https://orthanc.uclouvain.be/hg/orthanc-java/>`__. |
41 | 41 |
42 | 42 |
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 | |
43 Licensing | 194 Licensing |
44 --------- | 195 --------- |
45 | 196 |
46 This plugin is licensed under the terms of the `GPLv3+ license | 197 This plugin is licensed under the terms of the `GPLv3+ license |
47 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__, | 198 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__, |
48 which is the same as the core of Orthanc. | 199 which is the same as the core of Orthanc. |
49 | 200 |
50 This has an important consequence: If you distribute Orthanc to | 201 This has an important consequence: If you distribute Orthanc to |
51 clients together with one Java plugin, you **must** disclose the | 202 clients together with one Java plugin, you **must** disclose the |
52 source code of your Java script to the Orthanc community under the | 203 source code of your Java plugins to the Orthanc community under the |
53 terms of the GPL or AGPL licenses. | 204 terms of the GPL or AGPL licenses. |
54 | 205 |
55 We suggest you to put the source code of your Java scripts on the | 206 We suggest you to put the source code of your Java plugins on the |
56 dedicated `"OrthancContributed" repository on GitHub | 207 dedicated `"OrthancContributed" repository on GitHub |
57 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__, | 208 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__, |
58 and/or to send it to the `Orthanc Users discussion forum | 209 and/or to send it to the `Orthanc Users discussion forum |
59 <https://discourse.orthanc-server.org>`__. | 210 <https://discourse.orthanc-server.org>`__. |
60 | 211 |
61 Check out the :ref:`FAQ about licensing <licensing>` for more context. | 212 Check out the :ref:`FAQ about licensing <licensing>` for more context. |
62 | |
63 | |
64 Usage | |
65 ----- | |
66 | |
67 | |
68 FHIR server | |
69 ----------- | |
70 |