source: trunk/abcl/contrib/jss/README.markdown @ 13813

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

jss readme: Balance parenthesis. Normalize symbols to keywords.

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