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

Last change on this file was 15084, checked in by mevenson, 3 months ago

Miscellaneous fixups to source locations and documentation

Build 1.6.0-SNAPSHOT via Maven.

Fix various ABCL-CONTRIB documentation quirks.

Move Netbeans/Ant? integration into a subdirectory.

File size: 4.6 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
21from CL-USER:
22
23    (require :jss)
24    (let ((sw (new 'StringWriter)))
25       (#"write" sw "Hello ")
26       (#"write" sw "World")
27       (print (#"toString" sw)))
28
29What's happened here? First, all the classes in all the jars in the
30classpath have been collected.  For each class a.b.C.d, we have
31recorded that b.c.d, b.C.d, C.d, c.d, and d potentially refer to this
32class. In your call to new, as long as the symbol can refer to only
33one class, we use that class. In this case, it is
34java.io.StringWriter. You could also have written
35
36     (new 'io.stringwriter)
37
38or     
39     (new '|io.StringWriter|)
40
41or     
42     (new 'java.io.StringWriter)
43
44The call
45
46    (#"write" sw "Hello ")
47     
48uses the code in invoke.java to call the method named "write" with
49the arguments sw and "Hello ".  JSS figures out the right java method
50to call, and calls it.
51
52An interactive restart is available to resolve class ambiguity.
53
54Static calls are possible as well with the SHARPSIGN-QUOTATION_MARK
55macro, but the first argument *must* be a symbol to distinguish
56
57     (#"getProperties" "java.lang.System")
58     
59from
60
61     (#"getProperties" 'java.lang.System)     
62     
63The first attempts to call a method on the java.lang.String object
64with the contents "java.lang.System", which results in an error, while
65the second invokes the static java.lang.System.getProperties() method.     
66
67If you want to do a raw java call, use #0"toString". Raw calls
68return their results as Java objects, avoiding doing the usual Java
69object to Lisp object conversions that ABCL does.
70
71
72    (with-constant-signature ((name jname raw?)*) &body body)
73   
74binds a macro which expands to a jcall, promising that the same method
75will be called every time. Use this if you are making a lot of calls and
76want to avoid the overhead of a the dynamic dispatch.
77e.g.
78 
79    (with-constant-signature ((tostring "toString"))
80      (time (dotimes (i 10000) (tostring "foo"))))
81
82runs about three times faster than
83 
84    (time (dotimes (i 10000) (#"toString" "foo")))
85
86So, something like
87
88    (with-constant-signature
89      ((tostring "toString" t)) ...)
90   
91will cause the toString to be a raw java call. See
92JSS::GET-ALL-JAR-CLASSNAMES for an example.
93 
94Implementation is that the first time the function is called, the
95method is looked up based on the arguments passed, and thereafter
96that method is called directly.  Doesn't work for static methods at
97the moment (lazy)
98
99    (japropos string)
100
101finds all class names matching STRING.
102
103    (jcmn class-name)
104   
105lists the names of all methods for the CLASS-NAME.
106
107Java static fields may be addressed via the SHARPSIGN-QUOTATION_MARK macro as
108 
109    (#"{java.lang.System}.{fileSeparator}")
110 
111### Javaparser
112
113On the reference of the JAVAPARSER system, one may use a Java DSL to
114specify invocation and chains:
115
116    (asdf:make :javaparser)
117    (#1"new ByteBuddy()
118      .subclass(Object.class,t)
119      .method(ElementMatchers.named("toString"))
120      .intercept(FixedValue.value("Hello World!"))
121      .make()
122      .load(getClass().getClassLoader())
123      .getLoaded()"
124   
125# Compatibility
126
127The function ENSURE-COMPATIBILITY attempts to provide a compatibility
128mode to existing users of JSS by importing the necessary symbols into
129CL-USER.
130
131Some notes on other compatibility issues:
132
133*classpath-manager*
134
135   Since we are no longer using Beanshell, this is no longer present.
136   For obtaining the current classloader use JAVA:*CLASSLOADER*.
137   
138# API
139
140  1.0
141    Equivalent to Alan Ruttenberg's version included with the original
142    [lsw2](). 
143   
144[lsw]: http://mumble.net:8080/svn/lsw/trunk/
145[lsw2]: https://github.com/alanruttenberg/lsw2
146   
147
148  3.0
149     The results the of having JSS package loaded from [abcl-contrib][]
150     
151[abcl-contrib]: http://abcl.org/svn/trunk/abcl/contrib/
152
153# Colophon
154
155    <> dc:created "2005" ;
156       dc:author "Mark <evenson.not.org@gmail.com>";
157       dc:revised "11-JUN-2017" .
158
159
160   
Note: See TracBrowser for help on using the repository browser.