source: project/jni/jni.html @ 1714

Last change on this file since 1714 was 1714, checked in by Kon Lovett, 13 years ago

Fixed syntax-error msg, support for easyffi.

File size: 10.0 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<!-- Generated by eggdoc Revision: 1.20  -->
3<html>
4<head>
5<title>Eggs Unlimited - jni</title><style type="text/css"> <!--
6      CODE {
7            color: #666666;
8          }
9/*   DT.definition EM { font-weight: bold; font-style: normal; } */
10
11     DT.definition { 
12                   background: #eee;
13                   color: black;
14                   padding: 0.2em 1em 0.2em 0.7em;
15                   margin-left: 0.2em;
16border: 1px solid #bbc;
17                   font-family: "Andale Mono", monospace;
18                   /* font-size: 1.2em; */
19                   
20                 }
21     DD {
22                   margin-top: 0.8em;
23                   margin-bottom: 0.8em;
24     }
25     DIV.subsection {
26                    border-top: 1px solid #448;
27                    padding-left: 1em;
28                    margin-bottom: 1.2em;
29     }
30     DIV.subsubsection {
31                    border-top: 1px dotted #99c;
32                    /* border-left: 1px solid #99c; */
33                    padding-left: 1em;
34                    margin-bottom: 1.2em;
35     }
36     DIV.subsubsubsection {
37                    border-top: 1px solid #ddf;
38                    padding-left: 1em;
39                    margin-bottom: 1.2em;
40     }
41
42         DIV.section {
43                 margin-bottom: 1.5em;
44         }
45         a:link {
46                 color: #336;
47         }
48         a:visited { color: #666; }
49         a:active  { color: #966; }
50         a:hover   { color: #669; }
51         body { margin: 0; padding: 0; background: #fff; color: #000; font: 9pt "Lucida Grande", "Verdana", sans-serif; }
52         H2 {
53                 background: #336;
54                 color: #fff;
55                 padding-top: 0.5em;
56                 padding-bottom: 0.5em;
57                 padding-left: 16px;
58                 margin: 0 0 1em 0;
59        }
60        UL LI {
61                list-style: none;
62        }
63        TT {
64                font-family: "Andale Mono", monospace;
65                /* font-size: 1.2em; */
66        }
67        H3 {
68                color: #113;
69                margin-bottom: 0.5em;
70        }
71        H4, H5, H6 {
72                color: #113;
73                margin-bottom: 1.0em;
74        }
75        H5 {
76                font-weight: normal;
77                font-style: italic;
78                font-size: 100%;
79                margin-top: 1.2em;
80        }
81        H6 {
82                font-weight: bold;
83                font-size: 85%;
84                margin-top: 1.2em;
85        }
86     DIV#eggheader {
87         text-align: center;
88                 float: right;
89                 margin-right: 2em;
90     }
91     DIV#header IMG {
92            /* display: block; margin-left: auto; margin-right: auto;  */
93            /* float: right; */
94            border: none;  /* firefox */
95     }
96     DIV#footer {
97                background: #bbd;
98                padding: 0.7em ;
99                border-top: 1px solid #cce;
100     }
101     DIV#footer hr {
102                display: none;
103     }
104     DIV#footer a {
105                float: left;
106     }
107     DIV#revision-history {
108         float: right;
109     }
110     
111     DIV#body {
112                 margin: 1em 1em 1em 16px;
113         }
114
115     DIV#examples PRE {
116       background: #eef;
117       padding: 0.1em;
118       border: 1px solid #aac;
119     }
120     PRE#license, DIV#examples PRE {
121       padding: 0.5em;
122     }
123     DIV#examples PRE {
124       /* font-size: 85%; */
125     }
126     PRE { font-family: "Andale Mono", monospace; }
127     TABLE {
128       background: #eef;
129       padding: 0.2em;
130       border: 1px solid #aac;
131       border-collapse: collapse;
132       width: 100%;
133     }
134     TABLE.symbol-table TD.symbol {
135          width: 15em;
136          font-family: "Andale Mono", monospace;
137          /* font-size: 1.2em; */
138     }
139     TH {
140       text-align: left;
141       border-bottom: 1px solid #aac;
142       padding: 0.25em 0.5em 0.25em 0.5em;
143     } 
144     TD { padding: 0.25em 0.5em 0.25em 0.5em; }
145     --></style></head>
146<body>
147<div id="header">
148<h2>jni</h2>
149<div id="eggheader"><a href="index.html">
150<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
151<div id="body">
152<div class="section">
153<h3>Description</h3>
154<p>An interface to the Java(tm) VM</p></div>
155<div class="section">
156<h3>Author</h3>Daishi Kato and felix</div>
157<div class="section">
158<h3>Version</h3>
159<ul>
160<li>0.1 Initial release</li></ul></div>
161<div class="section">
162<h3>Usage</h3><tt>(require-extension jni)</tt></div>
163<div class="section">
164<h3>Download</h3><a href="jni.egg">jni.egg</a></div>
165<div class="section">
166<h3>Documentation</h3>
167<p>This extension uses the Java(tm) native interface (JNI) to run a Java(tm) from Scheme code.</p>
168<p>To build this extension you should set some environment variables before invoking <tt>chicken-setup</tt>:</p>
169<ul>
170<li>for GCJ, set <tt>CHICKEN_JNI_USE_GCJ</tt> to some non-empty value</li>
171<li>for Linux, set <tt>JNI_H_PATH</tt> and <tt>JNI_LIB_PATH</tt> to the directories where <tt>jni.h</tt> and <tt>libvjm</tt> are situated</li></ul>
172<dl>
173<dt class="definition"><strong>macro:</strong> (define-java-classes NAME ...)</dt>
174<dd>
175<p>Defines the variables <tt>NAME ...</tt>, holding pointers to the Java classes of the same name. <tt>NAME</tt> may be either a symbol or a list of the form <tt>(VARIABLE CLASSNAME)</tt>.</p>
176<p><tt>(define-java-classes Foo Bar)</tt> is equivalent to <tt>(begin (define Foo (jni:find-class &quot;Foo&quot;)) (define Bar (jni:find-class &quot;Bar&quot;)))</tt></p></dd></dl>
177<dl>
178<p>The following JNI procedures are provided:</p>
179<pre>(jni:find-class STRING) -&gt; CLASS
180(jni:define-class STRING LOADER BYTE-VECTOR LENGTH) -&gt; CLASS
181(jni:get-version) -&gt; INT
182(jni:get-superclass CLASS) -&gt; SUPERCLASS
183(jni:is-assignable-from? CLASS SUPERCLASS) -&gt; BOOL
184(jni:throw THROWABLE) -&gt; INT
185(jni:throw-new CLASS STRING) -&gt; INT
186(jni:exception-occurred) -&gt; THROWABLE
187(jni:exception-describe)
188(jni:exception-clear)
189(jni:fatal-error STRING)
190(jni:is-same-object? OBJECT1 OBJECT2) -&gt; BOOL
191(jni:get-object-class OBJECT) -&gt; CLASS
192(jni:is-instance-of? OBJECT CLASS) -&gt; BOOL
193(jni:exception-check) -&gt; BOOL
194(jni:monitor-enter OBJECT) -&gt; INT
195(jni:monitor-exit OBJECT) -&gt; INT
196(jni:get-array-length OBJECT) -&gt; INT
197(jni:new-object-array LENGTH CLASS OBJECT) -&gt; OBJECT'
198(jni:get-object-array-element OBJECT' INT) -&gt; OBJECT
199(jni:set-object-array-element! OBJECT' INT OBJECT)
200(jni:string-&gt;jstring STRING) -&gt; OBJECT
201(jni:jstring-&gt;string OBJECT) -&gt; STRING</pre>
202<p>Arguments named <tt>OBJECT, CLASS</tt> and <tt>THROWABLE</tt> should be Java objects.</p></dl>
203<dl>
204<dt class="definition"><strong>procedure:</strong> (jni:object? X)</dt>
205<dd>
206<p>Returns <tt>#t</tt> if <tt>X</tt> is a Java object or <tt>#f</tt> otherwise.</p></dd>
207<dt class="definition"><strong>procedure:</strong> (jni:method RETURN-TYPE CLASS NAME TYPELIST [SAFE?])</dt>
208<dd>
209<p>Returns a procedure that, when called, will invoke the Java method <tt>NAME</tt> (which should be a string or symbol) and that has the result-type <tt>RETURN-TYPE</tt> and the argument-types given in <tt>TYPELIST</tt>. <tt>CLASS</tt> should be a Java object representing a class. If <tt>SAFE?</tt> is given and true, then the method may invoke callbacks into Scheme.</p>
210<p>The returned procedure takes the receiver object as its first argument, followed by zero or more method arguments.</p></dd>
211<dt class="definition"><strong>procedure:</strong> (jni:nonvirtual-method RETURN-TYPE CLASS NAME TYPELIST [SAFE?])</dt>
212<dd>
213<p>Similar to <tt>jni:method</tt> but returns a procedure that will call a  method looked up in a specific class.</p></dd>
214<dt class="definition"><strong>procedure:</strong> (jni:static-method RETURN-TYPE CLASS NAME TYPELIST [SAFE?])</dt>
215<dd>
216<p>Similar to <tt>jni:method</tt> but returns a procedure that will call a static method. The procedure does not take an additional argument beyond the arguments that are expected by the static method.</p></dd>
217<dt class="definition"><strong>procedure:</strong> (jni:constructor CLASS TYPELIST [SAFE?])</dt>
218<dd>
219<p>Similar to <tt>jni:method</tt> but returns a procedure that will call a constructor method.</p></dd>
220<dt class="definition"><strong>procedure:</strong> (jni:field CLASS TYPE NAME)</dt>
221<dd>
222<p>Returns a procedure that can be used to access the field <tt>NAME</tt> (a string or symbol). The accessor-procedure accepts a single argument: the instance from which the field value should be retrieved. The returned procedure has a setter, so to modify the field, execute <tt>(set! (&lt;ACCESSOR&gt; &lt;OBJECT&gt;) &lt;VALUE&gt;)</tt>.</p></dd>
223<dt class="definition"><strong>procedure:</strong> (jni:static-field CLASS TYPE NAME)</dt>
224<dd>
225<p>Returns a procedure that can be used to access the static field <tt>NAME</tt> (a string or symbol). The accessor-procedure takes zero arguments. The returned procedure has a setter, so to modify the  field, execute <tt>(set! (&lt;ACCESSOR&gt;) &lt;VALUE&gt;)</tt>.</p></dd></dl>
226<div class="subsection">
227<h4>Limitations</h4>
228<ul>
229<li>There appear to be stack-related problems on certain platforms, which are currently not entirely understood. For this reason the jni extension should be considered alpha quality.</li>
230<li>Primitive arrays are not supported.</li>
231<li>No exception handling.</li></ul></div></div>
232<div class="section">
233<h3>License</h3>
234<pre>Copyright (c) 2005, Daishi Kato and Felix Winkelmann.  All rights reserved.
235
236Permission is hereby granted, free of charge, to any person obtaining a
237copy of this software and associated documentation files (the Software),
238to deal in the Software without restriction, including without limitation
239the rights to use, copy, modify, merge, publish, distribute, sublicense,
240and/or sell copies of the Software, and to permit persons to whom the
241Software is furnished to do so, subject to the following conditions:
242
243The above copyright notice and this permission notice shall be included
244in all copies or substantial portions of the Software.
245
246THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
247IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
248FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
249THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
250OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
251ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
252OTHER DEALINGS IN THE SOFTWARE.</pre></div></div>
253<div id="footer">
254<hr /><a href="index.html">&lt; Egg index</a>
255<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracBrowser for help on using the repository browser.