Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/java.rst @ 1077:df28170c2af3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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