[doc] misc. fix & improvements
[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 * 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="ja"
21           xml:id="jims-getting-started">
22     <refnamediv>
23         <refname>入門 - 第1ステップ</refname>
24         <refpurpose>Java Scilab バインディングを使用するには?</refpurpose>
25     </refnamediv>
26     <refsection>
27         <title>説明</title>
28         <para>
29             このモジュールの目的は, Javaオブジェクトおよびデータ型を
30             読込み, 相互作用を行えるようにすることです.
31         </para>
32     </refsection>
33     <refsection>
34         <title>基本</title>
35         <para>
36             始める前に, 多くの重要な関数とその動作を知っておくと良いでしょう.
37             これらの多く使用される関数は, 以下のScilab関数です:
38             <itemizedlist>
39                 <listitem>
40                     <link linkend="jimport">jimport</link>: Javaクラスをインポート
41                 </listitem>
42                 <listitem>
43                     <link linkend="jimport">jinvoke</link>: Javaオブジェクトのメソッドをコール
44                 </listitem>
45             </itemizedlist>
46         </para>
47         <para>
48             jimport はjava命令 'import' の機能を模擬する関数で,
49             指定したクラス定義/指定したクラスのテンプレートをメモリに読込みます.
50             読み込まれた際, この定義が静的メソッド/メンバへのアクセス,
51             新規オブジェクト作成の際に使用されます.
52             k
53         </para>
54         <para>
55             jinvoke はjavaクラスまたはオブジェクトの指定したメソッドを
56             コール(invoke)する関数です.
57             このinvokeは,実際のメンバシグネチャと一致する
58             一連のオプションのパラメータを有します.
59             これは,同数のパラメータを指定し,これらの引数が正しい型を有している
60             必要があることを意味します.
61         </para>
62     </refsection>
63     <refsection>
64         <title>例1: 基底クラスを作成し, 簡単なメソッドをコール</title>
65         <para>
66             この最初の例では,Javaを動作させる3つの基本的な柱を扱います.
67             最初はクラスの読込みで,
68             次はインスタンスの構築,
69             最後はこのメソッドまたはメンバの一つをコールすることです.
70         </para>
71         <para>
72             例<literal>HelloWorld</literal>で示されたものと同様の基底クラスを考えます.
73             このクラスは,構築時にメッセージを生成するデフォルトのコンストラクタを有し,
74             コール時にメッセージを表示する公開メソッドを1つ有します.
75             このクラスは, javaバイトコードにコンパイルする必要があります.
76             コードを開発する際には, この部分は通常IDE(integrated development environment)
77             により処理されます.
78             外部ライブラリを使用する場合, プリコンパイル形式(JARでパックされた)のものが
79             利用可能です.
80         </para>
81         <programlisting role="java"><![CDATA[
82 // HelloWorld.javaという名前で保存
83 package com.foo;
84 public class HelloWorld {
85    public HelloWorld() {
86       System.err.println("HelloWorld constructed!");
87   }
88   public void message() {
89       System.err.println("Hello world!");
90   }
91 }
92       ]]></programlisting>
93         <programlisting role="example"><![CDATA[
94 // ScilabからJavaコードをコンパイルする方法
95 javacode=mgetl(fullfile(TMPDIR, 'HelloWorld.java'));
96 jcompile("com.foo.HelloWorld",javacode);
97       ]]></programlisting>
98         <para>
99             このJavaクラスのコンパイル版が既に存在する場合, Scilabを起動し,
100             Scilabに種々のメッセージを表示させることができます.
101             HelloWorldクラスをワークスペースにインポートすることができます.
102             これは, 前述のインポート手順により以下のように行うことができます:
103             <screen>
104
105 --> jimport com.foo.HelloWorld
106
107 --> HelloWorld
108 HelloWorld  =
109 class com.foo.HelloWorld
110
111 --> whos -name HelloWorld
112 Name                     Type           Size           Bytes
113 HelloWorld               _EClass        ?              168
114 </screen>
115             <para>
116                 完了後, HelloWorldという名前の変数が作成されています.
117                 これは, Javaにおけるクラスオブジェクトと等価です. このクラスオブジェクトから,
118                 HelloWorld型の新規オブジェクトを作成できます.
119             </para>
120             <para>
121                 オブジェクトのインスタンスの作成は,クラス定義に
122                 <link linkend="new">new</link>を呼び出すことで行います.
123                 このクラスの引数は, Javaコンストラクタに移譲されるパラメータです.
124                 この処理の結果は, Javaオブジェクトへのリファレンスで,
125                 後で使用するために変数に保存できます.
126             </para>
127             <screen>
128
129 --> object = HelloWorld.new();
130 HelloWorld constructed!
131
132 --> object
133 object  =
134 com.foo.HelloWorld@49aacd5f
135
136 --> whos -name object
137 Name                     Type           Size           Bytes
138 object                   _EObj          ?              160
139 </screen>
140             <para>
141                 <link linkend="new">new</link> 演算子が JClassでコールされた際,
142                 Javaコンストラクタが透過的に呼び出され, メッセージ"HelloWorld constructed!"が
143                 表示されます.
144                 生成されたHelloWorld オブジェクトは"object"変数に保存されます.
145                 このメッセージはHelloWorldクラスのtoStringメソッドをオーバーライドすることにより
146                 カスタマイズできます.
147             </para>
148             <para>
149                 ここで,特定のHelloWorldオブジェクトが作成され,
150                 宣言された公開メソッドがを以下のようにコールできるようになりました;
151                 <literal>HelloWorld\#message()</literal>.
152                 <link linkend="new">new</link>と同様な技法を
153                 メソッドを呼び出す際に使用できます:
154             </para>
155             <screen>
156 --> object.message();
157 Hello world!
158 </screen>
159             <para>
160                 ドット演算子 (オブジェクトとメッセージの間にドット)は
161                 便利なショートカットで,以下のようなScilabコードのスニペットを拡張します.
162                 このショートカットの仕様により,
163                 メソッドを呼び出したり,
164                 メンバ変数を取得したりすることがより簡単かつ明快になります.
165             </para>
166             <screen>
167 --> jinvoke(object, 'message');
168 Hello world!
169 </screen>
170         </para>
171     </refsection>
172     <refsection>
173         <title>例 2: Scilab と Java のプリミティブを相互変換</title>
174         <para>
175             この例は,基本的なデータ型と文字列をScilabとJavaの間で交換
176             する手法を扱います.
177             複数の型のオブジェクトをこれらの2つの言語の間で渡します.
178         </para>
179         <para>
180             ここでは,例となるクラス(Class Inspector 参照)が
181             オブジェクトを入出力するよう定義されます.
182             2つのメソッドが定義されています.
183             最初のメソッドは doubleを1つ引数とし,算術演算をして,
184             結果を返します: Inspector#eval(double).
185             もう一つのメソッドは, 任意のオブジェクトを引数とし,
186             基本的な情報を表示して,返します: Inspector#inspect(Object).
187         </para>
188         <programlisting role="java"><![CDATA[
189 // Inspector.java という名前で保存
190 package com.foo;
191 public class Inspector {
192     public double eval(double x) {
193         return x / 2.;
194     }
195     public Object inspect(Object prototype) {
196         System.err.println("Inspecting: '" + prototype + "'");
197         System.err.println("Class: " + prototype.getClass().getSimpleName());
198         return prototype;
199     }
200 }
201       ]]></programlisting>
202         <para>
203             前の例と同様に, このコードは使用前にコンパイルしておく必要があります.
204         </para>
205         <programlisting role="example"><![CDATA[
206 // Scilab から Javaコードをコンパイルする方法
207 javacode= mgetl(fullfile(TMPDIR, 'Inspector.java'));
208 jcompile("com.foo.Inspector",javacode);
209       ]]></programlisting>
210         まず, Inspectorクラスをインポートし,
211         Inspectorオブジェクトを作成します:
212         <screen>
213 --> jimport('com.foo.Inspector');
214
215 --> myInspector = Inspector.new()
216 myInspector  =
217 com.foo.Inspector@2a788315
218 </screen>
219         <para/>
220         これにより, 2つのシステム間で情報を交換できるようになります.任意のScilabデータ型をJavaに指定すると,
221         自動的に Javaの等価な型にラップ(<link linkend="jwrap">jwrap</link>参照)されます.まず,
222         Scilabで最も良く使用される型の使用例として, 実数(定数)を示します. 実数を渡すと, この型は自動的に
223         Scilab型doubleにマップされます. 試してみましょう;
224         <screen>
225 --> result = myInspector.eval(12.5)
226 result  =
227 6.25
228
229 --> result * 2
230 ans  =
231 12.5
232
233 --> whos -name result
234 Name                     Type           Size           Bytes
235 result                   constant       1 by 1         24
236 </screen>
237         <para/>
238 自動変換は, jautoUnwrap関数により制御されます. この関数を利用しない場合,全ての変換を陽に行う必要があります.
239 <screen>
240 --> result = myInspector.eval(12.5)
241 result  =
242 6.25
243
244 --> result * 2
245 ans  =
246 null
247
248 --> whos -name result
249 Name                     Type           Size           Bytes
250 result                   _EObj          ?              160
251 </screen>
252         <para/>
253         返された結果は一見して正しいように見えます ($12.5/2=6.25$). しかし, よく見ると,
254         関数コールから返された値は数値ではありません. 受けたものは, 別の Javaオブジェクト (この場合は Double)です.
255         再びScilabで指定したデータを使用できるようにするには, jautoUnwrapを trueに設定していない場合, 前述の
256         <link linkend="junwrap">junwrap</link>機能を使用できます.
257         この変換は Java型を等価な Scilab形式に戻します. これを行うと, 通常の数値を再度得ることができます:
258         <screen>
259 --> result = junwrap(result)
260 result  =
261 6.25
262
263 --> whos -name result
264 Name                     Type           Size           Bytes
265 result                   constant       1 by 1         24
266
267 --> result * 2
268 ans  =
269 12.5
270 </screen>
271         <para/>
272         この例から, doubleが Java VM により使用され,返される Doubleに自動的に変換される流れが明確になりました.
273         返された変数を指定して <link linkend="junwrap">junwrap</link>をコールした際, ネーティブなScilab型に戻されます.
274         しかし, 他の型の場合はどうでしょう? 他の基本型についても調べてみましょう;
275         <screen>
276 --> jautoUnwrap(%f) // 自動unwrapを無効にします
277
278 --> result = myInspector.inspect("Hello world!");
279 Inspecting: 'Hello world!'
280 Class: String
281
282 --> whos -name result
283 Name                     Type           Size           Bytes
284 result                   _EObj          ?              160
285
286 --> result = junwrap(result)
287 result  =
288 Hello world!
289
290 --> whos -name result
291 Name                     Type           Size           Bytes
292 result                   string         1 by 1         72
293 // 整数
294
295 --> result = myInspector.inspect(int32(150));
296 Inspecting: '150'
297 Class: Integer
298
299 --> result = junwrap(result)
300 result  =
301 150
302
303 --> whos -name result
304 Name                     Type           Size           Bytes
305 result                   int32          1 by 1         40
306 // 論理値
307
308 --> result = myInspector.inspect(%t);
309 Inspecting: 'true'
310 Class: Boolean
311
312 --> result = junwrap(result)
313 result  =
314 T
315
316 --> whos -name result
317 Name                     Type           Size           Bytes
318 result                   boolean        1 by 1         16
319 </screen>
320         <para/>
321         見てわかるように, 全ての関連するデータ型は Scilab と Java型の間で透過的に変換できます. しかし,
322         これはそのまま行列にも拡張できます;
323         <screen>
324 -->  jautoUnwrap(%t) // コールを自動unwrapするデフォルトのモードに戻します
325
326 --> result = myInspector.inspect(1:5)
327 Inspecting: '[D@b05236'
328 Class: double[]
329 result  =
330 1.    2.    3.    4.    5.
331
332 --> whos -name result
333 Name                     Type           Size           Bytes
334 result                   constant       1 by 5         56
335
336 --> result = myInspector.inspect(testmatrix('magi',3))
337 Inspecting: '[[D@11d13272'
338 Class: double[][]
339 result  =
340 8.    1.    6.
341 3.    5.    7.
342 4.    9.    2.
343
344 --> whos -name result
345 Name                     Type           Size           Bytes
346 result                   constant       3 by 3         88
347 </screen>
348         <para/>
349         これらのラップされた行列のクラスを見ると, Javaはこれらを適当な大きさの配列として保存していることがわかります.
350         2次元行列の場合, これに等価なJava配列は列優先(デフォルト)または行優先モードで保存されます.
351         列優先モードでは, 最初の配列が各列へのポインタを有します. 一方, 行優先モードでは, 最初の配列が各行のデータを有します.
352         詳細については,<link linkend="jautoTranspose">jautoTranspose</link>を参照ください.
353     </refsection>
354     <refsection>
355         <title>履歴</title>
356         <revhistory>
357             <revision>
358                 <revnumber>5.5.0</revnumber>
359                 <revremark>
360                     関数が導入されました. 'JIMS'モジュールに基づきます.
361                     JIMSモジュールとの動作上の主な違いは,
362                     <link linkend="jautoUnwrap">jautoUnwrap</link>がデフォルトで
363                     有効になっていることです.
364                 </revremark>
365             </revision>
366         </revhistory>
367     </refsection>
368 </refentry>