source: branches/1.0.x/abcl/contrib/jss/README.markdown @ 13652

Last change on this file since 13652 was 13652, checked in by Mark Evenson, 10 years ago

Correctly spell Alan Ruttenberg's name.

File size: 3.5 KB
Line 
1JSS
2===
3
4Created by Alan Ruttenberg
5
6
7JSS stands for either "Java Simple Syntax" or "Java Syntax Sucks",
8depending on your mood.
9
10The dynamic dispatch of the java.lang.reflect package is used to make
11it real easy, if perhaps less efficient, to write Java code since you
12don't need to be bothered with imports, or with figuring out which
13method to call.  The only time that you need to know a class name is
14when you want to call a static method, or a constructor, and in those
15cases, you only need to know enough of the class name that is unique
16wrt to the classes on your classpath.
17
18Java methods look like this: #"toString". Java classes are represented
19as symbols, which are resolved to the appropriate java class
20name. When ambiguous, you need to be more specific. A simple example:
21
22    (let ((sw (new 'StringWriter)))
23       (#"write" sw "Hello ")
24       (#"write" sw "World")
25       (print (#"toString" sw)))
26
27What's happened here? First, all the classes in all the jars in the
28classpath have been collected.  For each class a.b.C.d, we have
29recorded that b.c.d, b.C.d, C.d, c.d, and d potentially refer to this
30class. In your call to new, as long as the symbol can refer to only
31one class, we use that class. In this case, it is
32java.io.StringWriter. You could also have written
33
34     (new 'io.stringwriter)
35
36or     
37     (new '|io.StringWriter|)
38
39or     
40     (new 'java.io.StringWriter)
41
42The call
43
44     (#"write" sw "Hello ")
45     
46uses the code in invoke.java to call the method named "write" with
47the arguments sw and "Hello ".  JSS figures out the right java method
48to call, and calls it.
49
50Static calls are possible as well with the #" macro, but the
51first argument MUST BE A SYMBOL to distinguish
52
53     (#"getProperties" "java.lang.System")
54     
55from
56
57     (#"getProperties" 'java.lang.System)     
58     
59The first attempts to call a method on the java.lang.String object
60with the contents "java.lang.System", which results in an error, while
61the second invokes the static java.lang.System.getProperties() method.     
62
63If you want to do a raw java call, use #0"toString". Raw calls
64return their results as Java objects, avoiding doing the usual Java
65object to Lisp object conversions that ABCL does.
66
67
68    (with-constant-signature ((name jname raw?)*) &body body)
69   
70binds a macro which expands to a jcall, promising that the same method
71will be called every time. Use this if you are making a lot of calls and
72want to avoid the overhead of a the dynamic dispatch.
73e.g.
74 
75    (with-constant-signature ((tostring "toString"))
76        (time (dotimes (i 10000) (tostring "foo"))))
77
78runs about three times faster than
79 
80    (time (dotimes (i 10000) (#"toString" "foo")))
81
82
83    (with-constant-signature ((tostring "toString" t)) ...)
84   
85will cause the toString to be a raw java call. See
86JSS::GET-ALL-JAR-CLASSNAMES for an example.
87 
88Implementation is that the first time the function is called, the
89method is looked up based on the arguments passed, and thereafter
90that method is called directly.  Doesn't work for static methods at
91the moment (lazy)
92
93(japropos string) finds all class names matching string
94
95(jcmn class-name) lists the names of all methods for the class
96
97
98Compatibility
99-------------
100
101The function ENSURE-COMPATIBILITY attempts to provide a compatibility
102mode to existing users of JSS by importing the necessary symbols into
103CL-USER.
104
105Some notes on other compatibilty issues:
106
107*classpath-manager*
108
109   Since we are no longer using Beanshell, this is no longer present.
110   For obtaining the current classloader use JAVA:*CLASSLOADER*.
111   
Note: See TracBrowser for help on using the repository browser.