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