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