1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Using SIDL arrays with Java</TITLE>
<META NAME="description" CONTENT="Using SIDL arrays with Java">
<META NAME="keywords" CONTENT="users_guide">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="users_guide.css">
<LINK REL="next" HREF="node156.html">
<LINK REL="previous" HREF="node154.html">
<LINK REL="up" HREF="node148.html">
<LINK REL="next" HREF="node156.html">
</HEAD>
<BODY >
<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html3025"
HREF="node156.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html3019"
HREF="node148.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html3013"
HREF="node154.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html3021"
HREF="node14.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html3023"
HREF="node317.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html3026"
HREF="node156.html">Interfaces and Abstract Classes</A>
<B> Up:</B> <A NAME="tex2html3020"
HREF="node148.html">Java Bindings</A>
<B> Previous:</B> <A NAME="tex2html3014"
HREF="node154.html">Out and Inout arguments</A>
<B> <A NAME="tex2html3022"
HREF="node14.html">Contents</A></B>
<B> <A NAME="tex2html3024"
HREF="node317.html">Index</A></B>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION03570000000000000000"></A>
<A NAME="9082"></A>
<BR>
Using SIDL arrays with Java
</H1>
<P>
Every object and type defined in SIDL can be put into a SIDL array of
that type. Arrays are a fairly complex topic, and the specifics of
the Babel Array API are discussed earlier in Section <A HREF="node59.html#s:arrays">5.4</A>.
Suffice to say that the entire API is available in Java, except for
<A NAME="9084"></A><A NAME="9085"></A>
<A NAME="9086"></A><A NAME="9087"></A>
<P>
<TT>ensure</TT>, <TT>borrow</TT>, and <TT>first</TT>, all of which have no
real use in Java. <TT>addRef</TT> and <TT>deleteRef</TT> exist in Java,
but shouldn't be used, because the Java decrements the reference count
itself when it garbage collects a SIDL object or array.
If it is necessary to <TT>deleteRef</TT> an array, you
should use the <TT>destroy()</TT> array function instead.
<P>
More to the point are the specifics of the Java implementation. Each
SIDL type and class includes a static inner class named <TT>Array</TT>.
This is the main Array class, and in order to support up to 7
dimensional arrays, every method takes either 7 array indices, or an
array of indices. For example, in order to get the element (2,3) from a 2
dimensional array, we would type <TT>arry._get(2,3,0,0,0,0,0)</TT>.
<P>
<A NAME="9097"></A>Since typing all those zeros can get a little tedious, we also
implemented a set of subclasses of Array. One subclass for each
dimension. So, if we had and <TT>Array2</TT> instead of an <TT>Array</TT>
we could simply type <TT>arry2._get(2,3)</TT> to get the correct
element.
<P>
These numbered Array subclasses improve on the Array API usability
somewhat, but that do have a side effect. <A NAME="9101"></A>
In order to avoid conflicts
between the Array superclass and the numbered Array subclass
functions, all other basic Array methods found in the Array superclass
are preceded by an underscore '_'. For example, in order to get an
array's dimension, you can type <TT>arry._dim()</TT>. The numbered
arrays all inherit these methods, so <TT>arry2._dim()</TT> will also
work, although in this case, the answer should be obvious.
<P>
Furthermore, there is another underscore rule for Arrays in Java. All
numbered arrays have two <TT>get</TT> and two <TT>set</TT> functions. The
<TT>_get</TT> and <TT>_set</TT> functions are the same in Array and all
the Array# subclasses, they simply pass the arguments of the
<TT>_get</TT> call down to the underlying implementation. However, the
underscore-less <TT>get</TT> and <TT>set</TT> do bounds checking in Java
before calling the underlying implementation, and, if there is a
problem, throw an <TT>ArrayIndexOutOfBoundsException</TT>.
<P>
Because the numbered arrays are subclasses of <TT>Array</TT>, if necessary you
can Java cast an <TT>Array#</TT> to an <TT>Array</TT>. However, some
functions return an <TT>Array</TT>. <A NAME="9116"></A>
In order to convert an <TT>Array</TT>
to the correctly numbered array, we provided a function in
<TT>Array</TT> called <TT>_dcast()</TT>. In order to cast an <TT>Array</TT>
object to a numbered array, simply call <TT>_dcast()</TT> on it.
For example, assume we have a 1 dimensional array of type
<TT>foo.Bar</TT> called <TT>arry</TT>
that is represented by the Java class <TT>Array</TT>. In order to get a
correctly numbered array type:
<P>
<BR>
<PRE CLASS="verbatim">foo.Bar.Array1 arry1 = arry._dcast();
</PRE></td></tr></table></blockquote>
<P>
After this cast we have 2 references to the same array, <TT>arry</TT>
and <TT>arry1</TT>.
<P>
Finally, the Java array constructors are slightly different then they
are in other languages. This is the constructor definition for
<TT>Array</TT>.
<P>
<BR>
<PRE CLASS="verbatim">public Array(int dim, int[] lower, int[] upper, boolean isRow)
</PRE></td></tr></table></blockquote>
<P>
<A NAME="9130"></A>
This constructor creates and array of dimension <TT>dim</TT>. It takes
two arrays of integers to define the lower and upper bounds of each
dimension in the array. If lower or upper has fewer elements than
there are dimensions in the array, or any element in lower is larger
than the corresponding element in upper, this constructor will throw
an exception. Finally, this constructor takes a boolean <TT>isRow</TT>.
If <TT>isRow</TT> is true, this constructor will create a SIDL array in
row-major order, if it is false, it will create an array in
column-major order.
<P>
The constructors for numbered arrays are simpler. Here's the
constructor for a 2 dimensional array:
<P>
<BR>
<PRE CLASS="verbatim">public Array2( int l0, int l1, int u0, int u1, boolean isRow)
</PRE></td></tr></table></blockquote>
<P>
The dimension argument is no longer necessary, and it is no longer
necessary to create arrays of bounds to pass into the constructor.
<TT>l0</TT> and <TT>l1</TT> are the lower bounds. and <TT>u0</TT> and
<TT>u1</TT> are the upper bounds. This constructor still includes the
choice between column and row major orders.
<P>
If all your lower bounds are 0, you can use an even simpler
constructor:
<P>
<BR>
<PRE CLASS="verbatim">public Array2( int s0, int s1, boolean isRow)
</PRE></td></tr></table></blockquote>
<P>
Another alternate way to construct sidl arrays is present in numbered
arrays. The following constructor takes a Java 2 dimensional array,
and copies it into a SIDL 2 dimensional array:
<P>
<BR>
<PRE CLASS="verbatim">public Array2(foo.Bar[][] array, boolean isRow)
</PRE></td></tr></table></blockquote>
<P>
If you already have a numbered SIDL array of the correct dimension,
you can copy a java array into it with the method <TT>fromArray</TT>.
The method takes the same arguments as the constructor above, and
returns nothing.
<P>
If you wish to go the other way, to copy a sidl array into a Java array,
you may use the numbered array function <TT>toArray</TT>. <TT>toArray</TT>
takes no arguments, and returns a new Java array with the SIDL array
elements copied into it.
<P>
<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html3025"
HREF="node156.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html3019"
HREF="node148.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html3013"
HREF="node154.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html3021"
HREF="node14.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html3023"
HREF="node317.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html3026"
HREF="node156.html">Interfaces and Abstract Classes</A>
<B> Up:</B> <A NAME="tex2html3020"
HREF="node148.html">Java Bindings</A>
<B> Previous:</B> <A NAME="tex2html3014"
HREF="node154.html">Out and Inout arguments</A>
<B> <A NAME="tex2html3022"
HREF="node14.html">Contents</A></B>
<B> <A NAME="tex2html3024"
HREF="node317.html">Index</A></B> </DIV>
<!--End of Navigation Panel-->
<ADDRESS>
<br><br>babel-0.10.2<br>users_guide Last Modified 2005-03-23<br><br><a href="http://www.llnl.gov/CASC/components">http://www.llnl.gov/CASC/components</a><br><a href="mailto:components@llnl.gov">components@llnl.gov</a>
</ADDRESS>
</BODY>
</HTML>
|
