source: branches/1.2.x/contrib/jss/README.markdown

Last change on this file was 14532, checked in by Mark Evenson, 9 years ago

1.2.1: branches/1.2.x now builds abcl-1.2.1-rc-0

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