source: project/javahack/javahack.html @ 319

Last change on this file since 319 was 319, checked in by felix winkelmann, 14 years ago

several fixes

File size: 11.1 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.17  -->
3<html>
4<head>
5<title>Eggs Unlimited - javahack</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     }
29         DIV.section {
30                 margin-bottom: 1.5em;
31         }
32         a:link {
33                 color: #336;
34         }
35         a:visited { color: #666; }
36         a:active  { color: #966; }
37         a:hover   { color: #669; }
38         body { margin: 0; padding: 0; background: #fff; color: #000; font: 9pt "Lucida Grande", "Verdana", sans-serif; }
39         H2 {
40                 background: #336;
41                 color: #fff;
42                 padding-top: 0.5em;
43                 padding-bottom: 0.5em;
44                 padding-left: 16px;
45                 margin: 0 0 1em 0;
46        }
47        LI {
48                list-style: none;
49        }
50        TT {
51                font-family: "Andale Mono", monospace;
52                /* font-size: 1.2em; */
53        }
54        H3 {
55                color: #113;
56                margin-bottom: 0.5em;
57        }
58     DIV#eggheader {
59         text-align: center;
60                 float: right;
61                 margin-right: 2em;
62     }
63     DIV#header IMG {
64            /* display: block; margin-left: auto; margin-right: auto;  */
65            /* float: right; */
66            border: none;  /* firefox */
67     }
68     DIV#footer {
69                background: #bbd;
70                padding: 0.7em ;
71                border-top: 1px solid #cce;
72     }
73     DIV#footer hr {
74                display: none;
75     }
76     DIV#footer a {
77                float: left;
78     }
79     DIV#revision-history {
80         float: right;
81     }
82     
83     DIV#body {
84                 margin: 1em 1em 1em 16px;
85         }
86
87     DIV#examples PRE {
88       background: #eef;
89       padding: 0.1em;
90       border: 1px solid #aac;
91     }
92     PRE#license, DIV#examples PRE {
93       padding: 0.5em;
94     }
95     DIV#examples PRE {
96       /* font-size: 85%; */
97     }
98     PRE { font-family: "Andale Mono", monospace; }
99     TABLE {
100       background: #eef;
101       padding: 0.2em;
102       border: 1px solid #aac;
103       width: 100%;
104     }
105     TABLE.symbol-table TD.symbol {
106          width: 15em;
107          font-family: "Andale Mono", monospace;
108          /* font-size: 1.2em; */
109     }
110     TH {
111       border-bottom: 1px solid black;
112     } --></style></head>
113<body>
114<div id="header">
115<h2>javahack</h2>
116<div id="eggheader"><a href="index.html">
117<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
118<div id="body">
119<div class="section">
120<h3>Description</h3>
121<p>A simple interface to Java(tm)</p></div>
122<div class="section">
123<h3>Author</h3><a href="mailto:felix@call-with-current-continuation.org">felix</a></div>
124<div class="section">
125<h3>Version</h3>
126<ul>
127<li>1.0 Initial release</li></ul></div>
128<div class="section">
129<h3>Usage</h3><tt>(require-extension javahack)</tt></div>
130<div class="section">
131<h3>Download</h3><a href="javahack.egg">javahack.egg</a></div>
132<div class="section">
133<h3>Documentation</h3>
134<p>This library provides a simple and convenient interface to Java. By running java as a sub-process and reading/writing s-expressions, no JNI and OS-specific hacks are needed which makes this approach more portable and robust.</p>
135<p>On the Java side <a href="http://jscheme.sourceforge.net">jscheme</a> is used to parse expressions passed from CHICKEN and to convert results back into a Scheme-friendly format.</p>
136<p>(<tt>jscheme.jar</tt> version 6.1 is included in this egg)</p>
137<dl>
138<dt class="definition"><strong>macro:</strong> (java SYMBOL)</dt>
139<dd>
140<p>Returns the value represented by <tt>SYMBOL</tt> which should designate a Java class, field, or method, using `Java Dot' notation:</p>
141<table>
142<tr>
143<td>Syntax</td>
144<td>Type of Member</td>
145<td>Example</td></tr>
146<tr>
147<td>&quot;.&quot; at the end</td>
148<td>constructor</td>
149<td><code>((java Font.) NAME STYLE SIZE)</code></td></tr>
150<tr>
151<td>&quot;.&quot; at the beginning</td>
152<td>instance member</td>
153<td><code>((java .setFont) COMP FONT)</code></td></tr>
154<tr>
155<td>&quot;.&quot; at beginning and &quot;$&quot; at the end</td>
156<td>instance field</td>
157<td><code>(define (mycar x) ((java .first$) x))</code>
158<br /><code>(define (myset-car! x y) ((java .first$) x y))</code></td></tr>
159<tr>
160<td>&quot;.&quot; only in the middle</td>
161<td>static member</td>
162<td><code>((java Math.round) 123.456)</code></td></tr>
163<tr>
164<td>&quot;.class&quot; suffix</td>
165<td>Java class</td>
166<td><code>(java Font.class)</code></td></tr>
167<tr>
168<td>&quot;$&quot; at the end</td>
169<td>static field</td>
170<td><code>(java Font.BOLD$)</code>
171<br /><code>(set! (java &quot;U.useJavaSyntax$&quot;) #t)</code></td></tr>
172<tr>
173<td>&quot;$&quot; in the middle</td>
174<td>inner class</td>
175<td><code>(java java.awt.geom.Point2D$Double.class)</code></td></tr>
176<tr>
177<td>&quot;$&quot; at the beginning</td>
178<td>packageless class</td>
179<td><code>(java $ParseDemo.class)</code></td></tr>
180<tr>
181<td>&quot;#&quot; at the end</td>
182<td>allow private access</td>
183<td><code>((java .name$#) ((java Symbol.#) &quot;abc&quot;))</code></td></tr></table>
184<p>Notes:</p>
185<ul>
186<li>
187<p>Each evaluation of the <tt>java</tt> macro sends an expression to the java process and receives a result expression. Since most of the results will stay constant throughout the lifetime of the session (as they refer to classes, fields and methods), they are cached and subsequent evaluation of the same <tt>(java ...)</tt> expression will refer to the cached value instead. You can disable this caching (in case you are doing rather funky things) with thhe help of the <tt>java-enable-cache</tt> form (see below).</p></li>
188<li>
189<p>Setting static fields is supported through a <a href="http://srfi.schemers.org/srfi-17/srrfi-17.html">SRFI-17</a> setter, as in the example above. Since the field-name is evaluated before being sent to the java-process, pass the field as a string.</p></li>
190<li>
191<p>Java objects which are returned from the Java-side can be safely used and are only garbage collected when no more references exist.</p></li></ul></dd>
192<dt class="definition"><strong>macro:</strong> (java-enable-cache FLAG)</dt>
193<dd>
194<p>Enables or disables caching of results returned by the <tt>java</tt> macro. <tt>FLAG</tt> should be either the symbol <tt>on</tt> or <tt>off</tt>. Caching is enabled by default.</p></dd></dl>
195<dl>
196<dt class="definition"><strong>procedure:</strong> (java-run #!key java jar debug options classpath)</dt>
197<dd>
198<p>Starts the java-VM as a subprocess, with any additional arguments customizing the JVM invocation. <tt>java</tt> specifies the jvm executable and defaults to <tt>java</tt>. <tt>jar</tt> gives the location of the jscheme jar file, <tt>options</tt> and <tt>classpath</tt> can be used to customize where the JVM should search for support classes and libraries, together with JVM specific options.</p>
199<p>Passing <tt>#t</tt> for the <tt>debug</tt> parameter will print information about the message flow between CHICKEN and jscheme.</p></dd>
200<dt class="definition"><strong>procedure:</strong> (java-stop)</dt>
201<dd>
202<p>Terminates the java process.</p></dd>
203<dt class="definition"><strong>procedure:</strong> (java-send EXPR)</dt>
204<dd>
205<p>Send an expression to Java and returns whatever result is passed back.</p></dd>
206<dt class="definition"><strong>procedure:</strong> (java-import STRING ...)</dt>
207<dd>
208<p>Imports Java packages. <tt>STRING</tt> should be a qualified package identifier, like <tt>&quot;java.lang.*&quot;</tt>.</p></dd>
209<dt class="definition"><strong>procedure:</strong> (java-object? X)</dt>
210<dd>
211<p>Returns <tt>#t</tt> if <tt>X</tt> is a raw Java object (that can not be meaningfully converted into a Scheme value).</p></dd></dl>
212<div class="section">
213<h3>Examples</h3>
214<div id="examples">
215<pre>(use javahack)
216
217(java-run debug: #t)
218
219(define s (java String.class))
220(pp s)
221(define s1 ((java String.) &quot;hello!&quot;))
222(pp s1)
223(do ((n 2 (sub1 n))) ((zero? n))
224  (pp ((java .hashCode) s1)) )
225(set! s #f)
226(set! s1 #f)</pre>Another example, a minimal SWT application. It assumes <tt>swt.jar</tt> and all necessary native libraries are in the path, or in the current directory:
227<pre>(use javahack)
228
229(java-run debug: #t options: '(&quot;-Djava.library.path=.&quot;) classpath: &quot;swt.jar&quot;)
230
231(java-import &quot;org.eclipse.swt.*&quot;)
232(java-import &quot;org.eclipse.swt.widgets.*&quot;)
233(java-import &quot;org.eclipse.swt.graphics.*&quot;)
234(java-import &quot;org.eclipse.swt.layout.*&quot;)
235
236((java Display.setAppName) &quot;Hello&quot;)
237
238(define disp ((java Display.)))
239(define shell ((java Shell.) disp))
240
241((java .setLayout) shell ((java FillLayout.) (java SWT.VERTICAL$)))
242((java .setText) shell &quot;Hello, world!&quot;)
243
244(define label ((java Label.) shell (java SWT.CENTER$)))
245
246((java .setText) label &quot;Hello, world&quot;)
247((java .setSize) shell 300 300)
248((java .open) shell)
249
250(do () (((java .isDisposed) shell))
251  (unless ((java .readAndDispatch) disp) ((java .sleep) disp)) )
252
253((java .dispose) disp)</pre>Yet another example that performs a callback. The Java code performing the callback could look like this:
254<pre>public class Callback
255{
256    public static Object invoke(jsint.Procedure proc, Object x) {
257        return proc.apply(new jsint.Pair(x, jsint.Pair.EMPTY));
258    }
259}</pre>If you compile it with <tt>javac -classpath `chicken-setup -repository`/jscheme.jar Callback.java</tt> you will have a classfile in the current directory that in combination with the following example code will call back to the CHICKEN side:
260<pre>(use javahack)
261
262(java-run debug: #t classpath: &quot;.&quot;)
263
264(write
265  ((java Callback.invoke)
266    (lambda (x)
267      (print &quot;ok: &quot; x)
268      42)
269    &quot;something&quot;) )</pre></div></div></div>
270<div class="section">
271<h3>License</h3>
272<pre>The javahack extension is distributed under the modified
273BSD license and Copyright (c) 2006 Felix L. Winkelmann
274
275JScheme is
276Copyright (c) 2002 Ken R. Anderson, Timothy J. Hickey, Peter Norvig
277
278This software is provided 'as-is', without any express or
279implied warranty.
280
281In no event will the authors be held liable for any damages
282arising from the use of this software.
283
284Permission is granted to anyone to use this software for any
285purpose, including commercial applications, and to alter it
286and redistribute it freely, subject to the following
287restrictions:
288
2891. The origin of this software must not be misrepresented; you
290   must not claim that you wrote the original software. If you
291   use this software in a product, an acknowledgment in the
292   product documentation would be appreciated but is not
293   required.
294
2952. Altered source versions must be plainly marked as such, and
296   must not be misrepresented as being the original software.
297
2983. This notice may not be removed or altered from any source
299   distribution.</pre></div></div>
300<div id="footer">
301<hr /><a href="index.html">&lt; Egg index</a>
302<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracBrowser for help on using the repository browser.