[doc] misc. fix & improvements
[scilab.git] / scilab / modules / external_objects_java / help / en_US / 01-getting-started.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 *
4 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
5 * Copyright (C) 2013 - S/E - Sylvestre Ledru
6 * Copyright (C) 2012 - CNES - Simon Billemont
7 *
8 * Copyright (C) 2012 - 2016 - Scilab Enterprises
9 *
10 * This file is hereby licensed under the terms of the GNU GPL v2.0,
11 * pursuant to article 5.3.4 of the CeCILL v.2.1.
12 * This file was originally licensed under the terms of the CeCILL v2.1,
13 * and continues to be available under such terms.
14 * For more information, see the COPYING file which you should have received
15 * along with this program.
16 *
17 *
18 -->
19 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
20           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
21           xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en"
22           xml:id="jims-getting-started">
23     <refnamediv>
24         <refname>Getting started - Beginning</refname>
25         <refpurpose>How to use the Java Scilab binding?</refpurpose>
26     </refnamediv>
27     <refsection>
28         <title>Description</title>
29         <para>The goal is this module is to allow the load and interaction on Java objects and datatypes.
30         </para>
31     </refsection>
32     <refsection>
33         <title>Basic</title>
34         <para>
35             Before starting, it is convenient to know the most important functions and what they do.
36             These frequently used functions are the following Scilab functions:
37             <itemizedlist>
38                 <listitem>
39                     <link linkend="jimport">jimport</link>: Import a Java class
40                 </listitem>
41                 <listitem>
42                     <link linkend="jimport">jinvoke</link>: Invoke a method of a Java object
43                 </listitem>
44             </itemizedlist>
45         </para>
46         <para>
47             jimport is the function that mirrors the functionality of the java statement 'import',
48             and loads the specified class definition/template of a given class in memory.
49             When loaded, this definition is used to accesses static methods/members,
50             and create new objects.
51         </para>
52         <para>
53             jinvoke is a function that calls (invokes) a specified method on a java class or object.
54             This invoke has an optional set of parameters that must coincide with the actual member
55             signature. This means you must pass the same number of arguments, and these arguments
56             must have the correct type.
57         </para>
58     </refsection>
59     <refsection>
60         <title>Example 1: Creating a basic class and calling a simple method</title>
61         <para>
62             In this first example, the three basic pillars of working with Java are treated.
63             The first is to load a class, then an instance is constructed and finally the invocation
64             or calling of one of this methods or members.
65         </para>
66         <para>
67             Consider a basic class as presented in the example <literal>HelloWorld</literal>.
68             It has a default constructor generating a message upon construction and one
69             public method which also shows a message when it has been called.
70             This class should now be compiled into java byte-code. When developing your own code,
71             then this section is usually handled by your IDE (integrated development environment).
72             If you plan to use external libraries, these will available in precompiled form
73             (packed in a JAR).
74         </para>
75         <programlisting role="java"><![CDATA[
76 // Save under the name HelloWorld.java
77 package com.foo;
78 public class HelloWorld {
79    public HelloWorld() {
80       System.err.println("HelloWorld constructed!");
81   }
82
83   public void message() {
84       System.err.println("Hello world!");
85   }
86 }
87       ]]></programlisting>
88         <programlisting role="example"><![CDATA[
89 // How to compile the Java code from Scilab
90 javacode=mgetl(fullfile(TMPDIR, 'HelloWorld.java'));
91 jcompile("com.foo.HelloWorld",javacode);
92       ]]></programlisting>
93         <para>Once the compiled version of this Java class exists, we can start Scilab and try
94             to get Scilab to show us the various messages.
95             Now the HelloWorld class can be imported into our workspace. This is done using the
96             already mentioned jimport:
97             <screen>
98 --> jimport com.foo.HelloWorld
99
100 --> HelloWorld
101 HelloWorld  =
102 class com.foo.HelloWorld
103
104 --> whos -name HelloWorld
105 Name                     Type           Size           Bytes
106 HelloWorld               _EClass        ?              168
107 </screen>
108             <para>
109                 Upon competition, an additional variable named HelloWorld has been created.
110                 This is equivalent to a Class object in java. From this class object,
111                 new objects of the HelloWorld type can be created.
112             </para>
113             <para>
114                 Creating such an object instance can be done by invoking <link linkend="new">new</link>
115                 on the class definition. The arguments to this function are the parameters that are
116                 delegated to the Java constructor.
117                 The result of this operation is a new Java object reference which can be stored
118                 in a variable for later use.
119             </para>
120             <screen>
121 --> object = HelloWorld.new();
122 HelloWorld constructed!
123
124 --> object
125 object  =
126 com.foo.HelloWorld@49aacd5f
127
128 --> whos -name object
129 Name                     Type           Size           Bytes
130 object                   _EObj          ?              160
131 </screen>
132             <para>
133                 What one sees when the <link linkend="new">new</link> operator is called on the
134                 JClass, it transparently invokes the Java constructor, and our
135                 "HelloWorld constructed!" message appears. The resulting HelloWorld object is
136                 stored in the "object" variable. When the variable name is reentered in the
137                 command line, the details of its reference are shown. This message can be
138                 customized by overriding the toString method in the HelloWorld class.
139             </para>
140             <para>
141                 Now that a specific HelloWorld object has been created, one can try to call
142                 the public method that has been declared; <literal>HelloWorld\#message()</literal>.
143                 The same natural technique as with <link linkend="new">new</link> can then be
144                 applied to invoke the method:
145             </para>
146             <screen>
147 --> object.message();
148 Hello world!
149 </screen>
150             <para>
151                 The dot operator (dot between object and message) is actually a handy shortcut
152                 and expands the following snippet of Scilab code. The use of this shortcut
153                 makes it simpler and cleaner to invoke methods/get member variables.
154             </para>
155             <screen>
156 --> jinvoke(object, 'message');
157 Hello world!
158 </screen>
159         </para>
160     </refsection>
161     <refsection>
162         <title>Example 2: Exchanging Scilab and Java primitives</title>
163         <para>
164             This example treats the way you can exchange primitive data types and strings between
165             Scilab and Java. We will be passing various types of objects between these two languages.
166         </para>
167         <para>
168             For this an example class (see Class Inspector) has been defined that takes and
169             returns objects.
170             There are two methods defined. The first takes a double does some arithmetic and
171             returns a result: Inspector#eval(double). The other methods takes any object,
172             shows some basic information and returns it: Inspector#inspect(Object).
173         </para>
174         <programlisting role="java"><![CDATA[
175 // Save under the name Inspector.java
176 package com.foo;
177 public class Inspector {
178     public double eval(double x) {
179         return x / 2.;
180     }
181
182     public Object inspect(Object prototype) {
183         System.err.println("Inspecting: '" + prototype + "'");
184         System.err.println("Class: " + prototype.getClass().getSimpleName());
185         return prototype;
186     }
187 }
188       ]]></programlisting>
189         <para>
190             As in the previous example, this code must be compiled to Java byte-code before
191             it can be used directly.
192         </para>
193         <programlisting role="example"><![CDATA[
194 // How to compile the Java code from Scilab
195 javacode= mgetl(fullfile(TMPDIR, 'Inspector.java'));
196 jcompile("com.foo.Inspector",javacode);
197       ]]></programlisting>
198         To start, import the Inspector class and create an Inspector object:
199         <screen>
200 --> jimport('com.foo.Inspector');
201
202 --> myInspector = Inspector.new()
203 myInspector  =
204 com.foo.Inspector@2a788315
205 </screen>
206         Now information between the two systems can be passing along.
207         When passing along any of the Scilab data types into Java, it is automatically wrapped
208         (see <link linkend="jwrap">jwrap</link>) to its Java equivalent.
209         First, an example using the most used data type in Scilab; reals (constant) is given.
210         When passing along a real, this type gets automatically mapped to the Scilab type double.
211         Let's try;
212         <screen>
213 --> result = myInspector.eval(12.5)
214 result  =
215 6.25
216
217 --> result * 2
218 ans  =
219 12.5
220
221 --> whos -name result
222 Name                     Type           Size           Bytes
223 result                   constant       1 by 1         24
224 </screen>
225         <para/>
226         The automatic convert is controlled by the jautoUnwrap function.
227         Without this function, all the conversions have to be done explicitly.
228         <screen>
229 --> result = myInspector.eval(12.5)
230 result  =
231 6.25
232
233 --> result * 2
234 ans  =
235 null
236
237 --> whos -name result
238 Name                     Type           Size           Bytes
239 result                   _EObj          ?              160
240         </screen>
241         <para/>
242         The result that is returned seems to be correct at first glance ($12.5/2=6.25$).
243         However upon closer inspection, notice that what is returned from our function call
244         is not a number. What we received is another Java object (Double in this case).
245         To be able to use the given data in again in Scilab, the already mentioned
246         <link linkend="junwrap">junwrap</link> functionality can be used if the jautoUnwrap
247         is not set to true.
248         This transforms Java types back to there equivalent Scilab form. From then onward we
249         have a normal number again:
250         <screen>
251 --> result = junwrap(result)
252 result  =
253 6.25
254
255 --> whos -name result
256 Name                     Type           Size           Bytes
257 result                   constant       1 by 1         24
258
259 --> result * 2
260 ans  =
261 12.5
262 </screen>
263         <para/>
264         From this example is clear how doubles get automatically transformed into a Double,
265         which is used by the Java VM and returned back.
266         When calling <link linkend="junwrap">junwrap</link> on the returned variable, it is
267         transformed back into a native Scilab type. But how do other types work? Let's inspect
268         several of the other primitive types;
269         <screen>
270 --> jautoUnwrap(%f) // Make sure we disable the auto Unwrap
271
272 --> result = myInspector.inspect("Hello world!");
273 Inspecting: 'Hello world!'
274 Class: String
275
276 --> whos -name result
277 Name                     Type           Size           Bytes
278 result                   _EObj          ?              160
279
280 --> result = junwrap(result)
281 result  =
282 Hello world!
283
284 --> whos -name result
285 Name                     Type           Size           Bytes
286 result                   string         1 by 1         72
287
288 // An Integer
289 --> result = myInspector.inspect(int32(150));
290 Inspecting: '150'
291 Class: Integer
292
293 --> result = junwrap(result)
294 result  =
295 150
296
297 --> whos -name result
298 Name                     Type           Size           Bytes
299 result                   int32          1 by 1         40
300
301 // A boolean
302 --> result = myInspector.inspect(%t);
303 Inspecting: 'true'
304 Class: Boolean
305
306 --> result = junwrap(result)
307 result  =
308 T
309
310 --> whos -name result
311 Name                     Type           Size           Bytes
312 result                   boolean        1 by 1         16
313 </screen>
314         <para/>
315         As can be seen, all relevant data types are can be transformed transparently between
316         Scilab and Java type. However this also extends without any additional effort to matrices;
317         <screen>
318 --> jautoUnwrap(%t) // Make sure we come back in the default mode where Scilab auto unwrap all calls
319
320 --> result = myInspector.inspect(1:5)
321 Inspecting: '[D@b05236'
322 Class: double[]
323 result  =
324 1.    2.    3.    4.    5.
325
326 --> whos -name result
327 Name                     Type           Size           Bytes
328 result                   constant       1 by 5         56
329
330 --> result = myInspector.inspect(testmatrix('magi',3))
331 Inspecting: '[[D@11d13272'
332 Class: double[][]
333 result  =
334 8.    1.    6.
335 3.    5.    7.
336 4.    9.    2.
337
338 --> whos -name result
339 Name                     Type           Size           Bytes
340 result                   constant       3 by 3         88
341 </screen>
342         <para/>
343         When looking at the class of these wrapped matrices, it is clear that Java stores them
344         as arrays of the appropriate size. When working with 2D matrices, the data in these
345         equivalent Java arrays can be stored in are column-major (default) or row-major mode.
346         In column-major mode, the first array contains a pointer to each of the columns.
347         Whereas in row-major mode, the first array contains the pointers to each row of data.
348         For more information see <link linkend="jautoTranspose">jautoTranspose</link>.
349     </refsection>
350     <refsection>
351         <title>History</title>
352         <revhistory>
353             <revision>
354                 <revnumber>5.5.0</revnumber>
355                 <revremark>
356                     Function introduced. Based on the 'JIMS' module. The main difference in the
357                     behavior compared to the JIMS module is that
358                     <link linkend="jautoUnwrap">jautoUnwrap</link> is enabled by default.
359                 </revremark>
360             </revision>
361         </revhistory>
362     </refsection>
363 </refentry>
364