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

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

abcl-1.2.0-rc-0-1: additional non-functional changes in project metadata.

There should be no direct mention of previous hosting URIs in the
current sources and binaries.

Hopefully clarified licensing for those distributors who choose to
emit the classpath exception to the overarching GPL.

Update README.

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