338dd5d8932194e8d57755f2e4a65d9290a1fea5
[scilab.git] / scilab / modules / external_objects_java / help / ja_JP / 01-getting-started.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2
3 <!--
4 *
5 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
6 * Copyright (C) 2013 - S/E - Sylvestre Ledru
7 * Copyright (C) 2012 - CNES - Simon Billemont
8 *
9  * Copyright (C) 2012 - 2016 - Scilab Enterprises
10  *
11  * This file is hereby licensed under the terms of the GNU GPL v2.0,
12  * pursuant to article 5.3.4 of the CeCILL v.2.1.
13  * This file was originally licensed under the terms of the CeCILL v2.1,
14  * and continues to be available under such terms.
15  * For more information, see the COPYING file which you should have received
16  * along with this program.
17 *
18 *
19 -->
20
21 <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="ja" xml:id="jims-getting-started">
22
23     <refnamediv>
24
25         <refname>入門 - 第1ステップ</refname>
26
27         <refpurpose>Java Scilab バインディングを使用するには?</refpurpose>
28
29     </refnamediv>
30
31     <refsection>
32
33         <title>説明</title>
34
35         <para>
36
37             このモジュールの目的は, Javaオブジェクトおよびデータ型を
38
39             読込み, 相互作用を行えるようにすることです.
40
41         </para>
42
43     </refsection>
44
45     <refsection>
46
47         <title>基本</title>
48
49         <para>
50
51             始める前に, 多くの重要な関数とその動作を知っておくと良いでしょう.
52
53             これらの多く使用される関数は, 以下のScilab関数です:
54
55             <itemizedlist>
56
57                 <listitem>
58
59                     <link linkend="jimport">jimport</link>: Javaクラスをインポート
60
61                 </listitem>
62
63                 <listitem>
64
65                     <link linkend="jimport">jinvoke</link>: Javaオブジェクトのメソッドをコール
66
67                 </listitem>
68
69             </itemizedlist>
70
71         </para>
72
73         <para>
74
75             jimport はjava命令 'import' の機能を模擬する関数で,
76
77             指定したクラス定義/指定したクラスのテンプレートをメモリに読込みます.
78
79             読み込まれた際, この定義が静的メソッド/メンバへのアクセス,
80
81             新規オブジェクト作成の際に使用されます.
82
83             k
84         </para>
85
86         <para>
87
88             jinvoke はjavaクラスまたはオブジェクトの指定したメソッドを
89
90             コール(invoke)する関数です.
91
92             このinvokeは,実際のメンバシグネチャと一致する
93
94             一連のオプションのパラメータを有します.
95
96             これは,同数のパラメータを指定し,これらの引数が正しい型を有している
97
98             必要があることを意味します.
99
100         </para>
101
102     </refsection>
103
104     <refsection>
105
106         <title>例1: 基底クラスを作成し, 簡単なメソッドをコール</title>
107
108         <para>
109
110             この最初の例では,Javaを動作させる3つの基本的な柱を扱います.
111
112             最初はクラスの読込みで,
113
114             次はインスタンスの構築,
115
116             最後はこのメソッドまたはメンバの一つをコールすることです.
117
118         </para>
119
120         <para>
121
122             例<literal>HelloWorld</literal>で示されたものと同様の基底クラスを考えます.
123
124             このクラスは,構築時にメッセージを生成するデフォルトのコンストラクタを有し,
125
126             コール時にメッセージを表示する公開メソッドを1つ有します.
127
128             このクラスは, javaバイトコードにコンパイルする必要があります.
129
130             コードを開発する際には, この部分は通常IDE(integrated development environment)
131
132             により処理されます.
133
134             外部ライブラリを使用する場合, プリコンパイル形式(JARでパックされた)のものが
135
136             利用可能です.
137
138         </para>
139
140         <programlisting role="java"><![CDATA[
141 // HelloWorld.javaという名前で保存
142 package com.foo;
143 public class HelloWorld {
144    public HelloWorld() {
145       System.err.println("HelloWorld constructed!");
146   }
147
148   public void message() {
149       System.err.println("Hello world!");
150   }
151 }
152       ]]></programlisting>
153
154         <programlisting role="example"><![CDATA[
155 // ScilabからJavaコードをコンパイルする方法
156 javacode=mgetl(fullfile(TMPDIR, 'HelloWorld.java'));
157 jcompile("com.foo.HelloWorld",javacode);
158       ]]></programlisting>
159
160         <para>
161
162             このJavaクラスのコンパイル版が既に存在する場合, Scilabを起動し,
163
164             Scilabに種々のメッセージを表示させることができます.
165
166             HelloWorldクラスをワークスペースにインポートすることができます.
167
168             これは, 前述のインポート手順により以下のように行うことができます:
169
170             <screen>
171
172                 -->jimport com.foo.HelloWorld
173
174
175
176                 -->HelloWorld
177
178                 HelloWorld  =
179
180
181
182                 class com.foo.HelloWorld
183
184
185
186                 -->whos -name HelloWorld
187
188                 Name                     Type           Size           Bytes
189
190
191
192                 HelloWorld               _EClass        ?              168
193
194             </screen>
195
196             <para>
197
198                 完了後, HelloWorldという名前の変数が作成されています.
199
200                 これは, Javaにおけるクラスオブジェクトと等価です. このクラスオブジェクトから,
201
202                 HelloWorld型の新規オブジェクトを作成できます.
203
204             </para>
205
206             <para>
207
208                 オブジェクトのインスタンスの作成は,クラス定義に
209
210                 <link linkend="new">new</link>を呼び出すことで行います.
211
212                 このクラスの引数は, Javaコンストラクタに移譲されるパラメータです.
213
214                 この処理の結果は, Javaオブジェクトへのリファレンスで,
215
216                 後で使用するために変数に保存できます.
217
218             </para>
219
220             <screen>
221
222                 -->object = HelloWorld.new();
223
224                 HelloWorld constructed!
225
226
227
228                 -->object
229
230                 object  =
231
232
233
234                 com.foo.HelloWorld@49aacd5f
235
236
237
238                 -->whos -name object
239
240                 Name                     Type           Size           Bytes
241
242
243
244                 object                   _EObj          ?              160
245
246             </screen>
247
248             <para>
249
250                 <link linkend="new">new</link> 演算子が JClassでコールされた際,
251
252                 Javaコンストラクタが透過的に呼び出され, メッセージ"HelloWorld constructed!"が
253
254                 表示されます.
255
256                 生成されたHelloWorld オブジェクトは"object"変数に保存されます.
257
258                 このメッセージはHelloWorldクラスのtoStringメソッドをオーバーライドすることにより
259
260                 カスタマイズできます.
261
262             </para>
263
264             <para>
265
266                 ここで,特定のHelloWorldオブジェクトが作成され,
267
268                 宣言された公開メソッドがを以下のようにコールできるようになりました;
269
270                 <literal>HelloWorld\#message()</literal>.
271
272                 <link linkend="new">new</link>と同様な技法を
273
274                 メソッドを呼び出す際に使用できます:
275
276             </para>
277
278             <screen>
279
280                 -->object.message();
281
282                 Hello world!
283
284             </screen>
285
286             <para>
287
288                 ドット演算子 (オブジェクトとメッセージの間にドット)は
289
290                 便利なショートカットで,以下のようなScilabコードのスニペットを拡張します.
291
292                 このショートカットの仕様により,
293
294                 メソッドを呼び出したり,
295
296                 メンバ変数を取得したりすることがより簡単かつ明快になります.
297
298             </para>
299
300             <screen>
301
302                 -->jinvoke(object, 'message');
303
304                 Hello world!
305
306             </screen>
307
308         </para>
309
310     </refsection>
311
312     <refsection>
313
314         <title>例 2: Scilab と Java のプリミティブを相互変換</title>
315
316         <para>
317
318             この例は,基本的なデータ型と文字列をScilabとJavaの間で交換
319
320             する手法を扱います.
321
322             複数の型のオブジェクトをこれらの2つの言語の間で渡します.
323
324         </para>
325
326         <para>
327
328             ここでは,例となるクラス(Class Inspector 参照)が
329
330             オブジェクトを入出力するよう定義されます.
331
332             2つのメソッドが定義されています.
333
334             最初のメソッドは doubleを1つ引数とし,算術演算をして,
335
336             結果を返します: Inspector#eval(double).
337
338             もう一つのメソッドは, 任意のオブジェクトを引数とし,
339
340             基本的な情報を表示して,返します: Inspector#inspect(Object).
341
342         </para>
343
344         <programlisting role="java"><![CDATA[
345 // Inspector.java という名前で保存
346 package com.foo;
347 public class Inspector {
348         public double eval(double x) {
349                 return x / 2.;
350         }
351
352         public Object inspect(Object prototype) {
353                 System.err.println("Inspecting: '" + prototype + "'");
354                 System.err.println("Class: " + prototype.getClass().getSimpleName());
355                 return prototype;
356         }
357 }
358       ]]></programlisting>
359
360         <para>
361
362             前の例と同様に, このコードは使用前にコンパイルしておく必要があります.
363
364         </para>
365
366         <programlisting role="example"><![CDATA[
367 // Scilab から Javaコードをコンパイルする方法
368 javacode= mgetl(fullfile(TMPDIR, 'Inspector.java'));
369 jcompile("com.foo.Inspector",javacode);
370       ]]></programlisting>
371
372         まず, Inspectorクラスをインポートし,
373
374         Inspectorオブジェクトを作成します:
375
376         <screen>
377
378             -->jimport('com.foo.Inspector');
379
380
381
382             -->myInspector = Inspector.new()
383
384             myInspector  =
385
386
387
388             com.foo.Inspector@2a788315
389
390         </screen>
391
392         これにより, 2つのシステム間で情報を交換できるようになります.任意のScilabデータ型をJavaに指定すると, 自動的に Javaの等価な型にラップ(<link linkend="jwrap">jwrap</link>参照)されます.まず, Scilabで最も良く使用される型の使用例として, 実数(定数)を示します. 実数を渡すと, この型は自動的に Scilab型doubleにマップされます. 試してみましょう;
393
394         <screen>
395
396             -->result = myInspector.eval(12.5)
397
398             result  =
399
400
401
402             6.25
403
404
405
406             -->result * 2
407
408             ans  =
409
410
411
412             12.5
413
414
415
416             -->whos -name result
417
418             Name                     Type           Size           Bytes
419
420
421
422             result                   constant       1 by 1         24
423
424         </screen>
425
426         自動変換は, jautoUnwrap関数により制御されます. この関数を利用しない場合,全ての変換を陽に行う必要があります.
427
428         <screen>
429
430             -->result = myInspector.eval(12.5)
431
432             result  =
433
434
435
436             6.25
437
438
439
440             -->result * 2
441
442             ans  =
443
444
445
446             null
447
448
449
450             -->whos -name result
451
452             Name                     Type           Size           Bytes
453
454
455
456             result                   _EObj          ?              160
457
458         </screen>
459
460         返された結果は一見して正しいように見えます ($12.5/2=6.25$). しかし, よく見ると, 関数コールから返された値は数値ではありません. 受けたものは, 別の Javaオブジェクト (この場合は Double)です. 再びScilabで指定したデータを使用できるようにするには, jautoUnwrapを trueに設定していない場合, 前述の <link linkend="junwrap">junwrap</link>機能を使用できます.
461
462         この変換は Java型を等価な Scilab形式に戻します. これを行うと, 通常の数値を再度得ることができます:
463
464         <screen>
465
466             -->result = junwrap(result)
467
468             result  =
469
470
471
472             6.25
473
474
475
476             -->whos -name result
477
478             Name                     Type           Size           Bytes
479
480
481
482             result                   constant       1 by 1         24
483
484
485
486             -->result * 2
487
488             ans  =
489
490
491
492             12.5
493
494         </screen>
495
496
497
498         この例から, doubleが Java VM により使用され,返される Doubleに自動的に変換される流れが明確になりました. 返された変数を指定して <link linkend="junwrap">junwrap</link>をコールした際, ネーティブなScilab型に戻されます.しかし, 他の型の場合はどうでしょう? 他の基本型についても調べてみましょう;
499
500         <screen>
501
502             -->jautoUnwrap(%f) // 自動unwrapを無効にします
503
504
505
506             -->result = myInspector.inspect("Hello world!");
507
508             Inspecting: 'Hello world!'
509
510             Class: String
511
512
513
514             -->whos -name result
515
516             Name                     Type           Size           Bytes
517
518
519
520             result                   _EObj          ?              160
521
522
523
524             -->result = junwrap(result)
525
526             result  =
527
528
529
530             Hello world!
531
532
533
534             -->whos -name result
535
536             Name                     Type           Size           Bytes
537
538
539
540             result                   string         1 by 1         72
541
542
543
544             // 整数
545
546             -->result = myInspector.inspect(int32(150));
547
548             Inspecting: '150'
549
550             Class: Integer
551
552
553
554             -->result = junwrap(result)
555
556             result  =
557
558
559
560             150
561
562
563
564             -->whos -name result
565
566             Name                     Type           Size           Bytes
567
568
569
570             result                   int32          1 by 1         40
571
572
573
574             // 論理値
575
576             -->result = myInspector.inspect(%t);
577
578             Inspecting: 'true'
579
580             Class: Boolean
581
582
583
584             -->result = junwrap(result)
585
586             result  =
587
588
589
590             T
591
592
593
594             -->whos -name result
595
596             Name                     Type           Size           Bytes
597
598
599
600             result                   boolean        1 by 1         16
601
602
603
604         </screen>
605
606
607
608         見てわかるように, 全ての関連するデータ型は Scilab と Java型の間で透過的に変換できます. しかし, これはそのまま行列にも拡張できます;
609
610         <screen>
611
612             --> jautoUnwrap(%t) // コールを自動unwrapするデフォルトのモードに戻します
613
614
615
616             -->result = myInspector.inspect(1:5)
617
618             Inspecting: '[D@b05236'
619
620             Class: double[]
621
622             result  =
623
624
625
626             1.    2.    3.    4.    5.
627
628
629
630             -->whos -name result
631
632             Name                     Type           Size           Bytes
633
634
635
636             result                   constant       1 by 5         56
637
638
639
640             -->result = myInspector.inspect(testmatrix('magi',3))
641
642             Inspecting: '[[D@11d13272'
643
644             Class: double[][]
645
646             result  =
647
648
649
650             8.    1.    6.
651
652             3.    5.    7.
653
654             4.    9.    2.
655
656
657
658             -->whos -name result
659
660             Name                     Type           Size           Bytes
661
662
663
664             result                   constant       3 by 3         88
665
666         </screen>
667
668         これらのラップされた行列のクラスを見ると, Javaはこれらを適当な大きさの配列として保存していることがわかります. 2次元行列の場合, これに等価なJava配列は列優先(デフォルト)または行優先モードで保存されます. 列優先モードでは, 最初の配列が各列へのポインタを有します. 一方, 行優先モードでは, 最初の配列が各行のデータを有します. 詳細については,<link linkend="jautoTranspose">jautoTranspose</link>を参照ください.
669
670     </refsection>
671
672     <refsection>
673
674         <title>履歴</title>
675
676         <revhistory>
677
678             <revision>
679
680                 <revnumber>5.5.0</revnumber>
681
682                 <revremark>
683
684                     関数が導入されました. 'JIMS'モジュールに基づきます.
685
686                     JIMSモジュールとの動作上の主な違いは,
687
688                     <link linkend="jautoUnwrap">jautoUnwrap</link>がデフォルトで
689
690                     有効になっていることです.
691
692                 </revremark>
693
694             </revision>
695
696         </revhistory>
697
698     </refsection>
699
700 </refentry>
701
702
703