[doc] misc. fix & improvements
[scilab.git] / scilab / modules / external_objects_java / help / en_US / 02-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 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
19           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
20           xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en"
21           xml:id="jims-getting-started-2">
22     <refnamediv>
23         <refname>Getting started - Second step</refname>
24         <refpurpose>How to use the Java Scilab binding?</refpurpose>
25     </refnamediv>
26     <refsection>
27         <title>Description</title>
28         <para>
29             This tutorial follows the <link linkend="jims-getting-started">First step</link>.
30         </para>
31     </refsection>
32     <refsection>
33         <title>Example 3: Working with Java objects in Scilab</title>
34         <para>
35             For this example, we define a set of higher abstraction Java objects.
36             Then we will use Scilab as a sort of Java scripting language apply various operations on
37             these objects. A wide variation of Java functionality will be showcased such as; static
38             methods (Factory construct), Enums, simple polymorphism, and scope of members/methods.
39         </para>
40         <para>
41             This wide variety of functionality will be demonstrated using a set of
42             7 simple classes that describe a simple house;
43         </para>
44         <programlisting role="java"><![CDATA[
45 // Save under the name House.java
46 package com.foo;
47
48 import java.util.Arrays;
49 import java.util.LinkendList;
50 import java.util.List;
51
52 public class House {
53
54     private Color           color;
55     private Door            door;
56     private List<IWindow>   windows = new LinkendList<IWindow>();
57
58     public House(Color color, Door door, IWindow... windows) {
59         this.color = color;
60         this.door = door;
61         this.windows.addAll(Arrays.asList(windows));
62     }
63
64     public void repaint() {
65         swapDoorHouseColor();
66     }
67
68     private void swapDoorHouseColor() {
69         Color doorColor = door.getColor();
70         door.repaint(color);
71         color = doorColor;
72     }
73
74     public void addWindow(IWindow window) {
75         windows.add(window);
76     }
77
78     public void replaceDoor(Door newDoor) {
79         this.door = newDoor;
80     }
81
82     @Override
83     public String toString() {
84         return String.format(
85                 "This is a house painted in %s, has a %s door, and %d windows",
86                 color.getDescr(), door.getColor().getDescr(), windows.size());
87     }
88 }
89       ]]></programlisting>
90         <para/>
91         <programlisting role="java"><![CDATA[
92 package com.foo;
93
94 public class HouseFactory {
95
96     public static House basicHouse() {
97         Door door = new Door(Color.WHITE);
98         IWindow window = new RectangularWindow(2, 0.8);
99         return new House(Color.WHITE, door, window);
100     }
101
102     public static House flashyHouse() {
103         Door door = new Door(Color.random());
104         IWindow window = new CircularWindow(1.2);
105         return new House(Color.random(), door, window);
106     }
107 }
108       ]]></programlisting>
109         <para/>
110         <programlisting role="java"><![CDATA[
111 package com.foo;
112
113 import java.util.Random;
114
115 public enum Color {
116
117     BLACK("black"), BLUE("blue"), BROWN("brown"), GREEN("green"),
118     ORANGE("orange"), RED("red"), WHITE("white"), YELLOW("yellow");
119
120     public String   descr;
121
122     private Color(String s) {
123         descr = s;
124     }
125
126     public String getDescr() {
127         return descr;
128     }
129
130     public static Color random() {
131         Color[] allColors = values();
132         return allColors[new Random().nextInt(values().length)];
133     }
134 }      ]]></programlisting>
135         <para/>
136         <programlisting role="java"><![CDATA[
137
138 package com.foo;
139
140 public class Door {
141
142     private Color   color;
143
144     public Door(Color color) {
145         this.color = color;
146     }
147
148     public Color getColor() {
149         return color;
150     }
151
152     public void repaint(Color newColor) {
153         color = newColor;
154     }
155 }
156       ]]></programlisting>
157         <para/>
158         <programlisting role="java"><![CDATA[
159 package com.foo;
160
161 public interface IWindow {
162
163     double getWindowArea();
164
165 }
166       ]]></programlisting>
167         <para/>
168         <programlisting role="java"><![CDATA[
169 package com.foo;
170
171 public class RectangularWindow implements IWindow {
172
173     double  length;
174     double  width;
175
176     public RectangularWindow(double length, double width) {
177         this.length = length;
178         this.width = width;
179     }
180
181     public double getWindowArea() {
182         return length * width;
183     }
184 }
185       ]]></programlisting>
186         <para/>
187         <programlisting role="java"><![CDATA[
188 package com.foo;
189
190 public class CircularWindow implements IWindow {
191
192     double  radius;
193
194     public CircularWindow(double radius) {
195         this.radius = radius;
196     }
197
198     public double getWindowArea() {
199         return Math.PI * radius * radius;
200     }
201 }
202       ]]></programlisting>
203         <para/>
204         <programlisting role="example"><![CDATA[
205 // The examples are shipped in the Scilab distribution.
206 directory=SCI+"/modules/external_objects_java/examples/com/foo/"
207 // Compile of all them
208 jcompile(ls(directory + "/*.java"))
209       ]]></programlisting>
210         <para>
211             First, let's construct a basic factory house. For this, the HouseFactory should be
212             imported and the static method basicHouse() should be invoked.
213         </para>
214         <screen>
215 --> jimport("com.foo.HouseFactory")
216
217 --> house = HouseFactory.basicHouse()
218 house  =
219 This is a house painted in white, has a white door, and 1 windows
220 </screen>
221         <para>
222             This shows that static methods can be called as one would in Java.
223             Also keep in mind that this is equivalent to "jinvoke(HouseFactory, 'basicHouse')"
224
225             Also the message of the object has changed from something like:
226             <screen>
227 com.foo.House@ae8022
228 To
229 This is a house painted in white, has a white door, and 1 windows
230 </screen>
231             This is due to the fact that the House class has a non-default \cmd[toString] method.
232             This <literal>toString</literal> is used to generate this representation.
233             We can still get the actual type (class) of our House object by invoking
234             <link linkend="jgetclassname">jgetclassname</link>
235             <screen>
236 --> jgetclassname(house)
237 ans  =
238 com.foo.House
239 </screen>
240             What is also interesting to know is that we now have a description of a house,
241             without having to import House into Scilab directly!
242             Now that a house has been constructed, it is time to add another window to that house.
243             For this purpose we need to create a new window and add it to the house using the
244             function <literal>addWindow(IWindow)</literal>. <literal>IWindow</literal> is an
245             abstract description of what a window should be and cannot be instantiated directly.
246             There are however two implementations available that we can construct;
247             <literal>RectangularWindow</literal> and <literal>CircularWindow</literal>.
248             Since the house starts with a <literal>RectangularWindow</literal> from the factory,
249             a new <literal>CircularWindow</literal> shall be made.
250         </para>
251         <screen>
252 --> jimport("com.foo.IWindow")
253
254 --> IWindow.new()
255 !--error 999
256 Method invocation: An error occurred: Exception when calling Java method : No such constructor in the class com.foo.IWindow.
257
258 --> jimport("com.foo.CircularWindow")
259
260 -->  newWindow = CircularWindow.new(0.5)
261 newWindow  =
262 com.foo.CircularWindow@3e389405
263
264 --> house.addWindow(newWindow);
265
266 --> house
267 house  =
268 This is a house painted in white, has a white door, and 2 windows
269 </screen>
270         <para>
271             A new window was made, and it's reference stored in the "newWindow" variable.
272             Next, the window was directly added to the house, without any need to wrap the variable.
273             It basically works as one would expect it to work.
274             Finally, we notice that our house now has 2 windows.
275         </para>
276         <para>
277             However, we don't like the door, so let's change the door. To create a door,
278             a color for that door needs to be picked. Color is of the Java Enum class type.
279             Again as before, first the required variables need to be imported,
280             new instances created and then the door of the house needs to be swapped out.
281         </para>
282         <screen>
283 --> jimport("com.foo.Color")
284
285 --> jimport("com.foo.Door")
286
287 --> newDoor = Door.new(Color.RED)
288 newDoor  =
289 com.foo.Door@54a5f709
290
291 --> house.replaceDoor(newDoor);
292
293 --> house
294 house  =
295 This is a house painted in white, has a red door, and 2 windows
296 </screen>
297         <para>
298             Using Enum types is as straightforward as using classes! Their methods and members
299             are subject to the same principles:
300         </para>
301         <screen>
302 --> c = Color.random()
303 c  =
304 BLACK
305
306 --> c = Color.random()
307 c  =
308 BLUE
309
310 --> c.getDescr()
311 ans  =
312 blue
313 </screen>
314         <para>
315             The list of windows kept by that house is of type <literal>IWindow</literal>.
316             From this it follows that under normal circumstances only windows may be added to the list.
317             To test this, let's see what happens when a <literal>Door</literal> is added in Scilab.
318         </para>
319         <screen>
320 --> house.addWindow(newDoor);
321 !--error 999
322 Method invocation: An error occurred: Exception when calling Java method : No method addWindow in the class com.foo.House or bad arguments type.
323 </screen>
324         <para>
325             The same as using Java Reflection, the JVM security measures prevent us from disobeying
326             the Java polymorthism rules. The same goes for private methods and members.
327         </para>
328         <screen>
329 --> c.descr
330 ans  =
331 blue
332
333 --> house.door
334 !--error 999
335 %_EObj_e: An error occurred: Exception when calling Java method : Invalid field door
336
337 --> house.repaint();
338
339 --> house
340 house  =
341 This is a house painted in red, has a white door, and 2 windows
342
343 --> house.swapDoorHouseColor()
344 !--error 999
345 %_EObj_e: An error occurred: Exception when calling Java method : Invalid field swapDoorHouseColor
346 </screen>
347         <para>
348             Concluding, the JIMS package does the job of hiding the Java JNI interface with Scilab,
349             and make it very clear and transparent to use Java libraries under Scilab.
350             All the normal JVM functionality is present and the Scilab syntax is clear and natural
351             to use.
352         </para>
353         <para>
354             From this point you should understand how to interface Scilab and Java libraries,
355             utilize the full power of Java under the Scilab scripting environment.
356         </para>
357     </refsection>
358     <refsection>
359         <title>History</title>
360         <revhistory>
361             <revision>
362                 <revnumber>5.5.0</revnumber>
363                 <revremark>
364                     Function introduced. Based on the 'JIMS' module. The main difference in the
365                     behavior compared to the JIMS module is that
366                     <link linkend="jautoUnwrap">jautoUnwrap</link> is enabled by default.
367                 </revremark>
368             </revision>
369         </revhistory>
370     </refsection>
371 </refentry>
372