@@ -71,6 +71,42 @@ that one can call in JavaScript
7171and for all practical purposes it will appear that Java is running.
7272
7373
74+ Method Disambiguation
75+ ---------------------
76+
77+ SwingJS has no problem with the overloading of methods, for example:
78+
79+ public void print(int b);
80+ public void print(float b);
81+
82+ JavaScript does not allow overloading of methods, and the common practice in
83+ Java of naming a field the same as a method -- isAllowed and isAllowed() -- is
84+ not possible in JavaScript. As a result, SwingJS implements "fully-qualified"
85+ method names using "$" parameter type separation. For example, in Java we see:
86+
87+ public void equals(Object o) {...}
88+
89+ Whereas in SwingJS we have:
90+
91+ Clazz.newMeth(C$, 'equals$O', function (o) {...}
92+
93+ And
94+
95+ this.getContentPane().add(bar, "North");
96+
97+ becomes
98+
99+ this.getContentPane$().add$java_awt_Component$O(bar, "North");
100+
101+
102+ Parameterless methods such as toString() are appended with "$" to become toString$().
103+ The one exception to this rule is private methods, which are saved in (truly) private
104+ array in the class (and are not accessible by reflection). Private parameterless
105+ methods retain their simple Java name, since they cannot conflict with field names.
106+
107+ This renaming of methods has a few consequences, which are discussed more fully below.
108+
109+
74110Applet vs. Application
75111----------------------
76112
@@ -174,6 +210,7 @@ myclass.xxx in Java (and JavaScript).
174210
175211This was done extensively in the Jalview project. See jalview.bin.Instance.
176212
213+
177214Helper Packages -- swingjs/ and javajs/
178215---------------------------------------
179216
@@ -202,8 +239,6 @@ See javajs.async.Async JavaDoc comments for a full description of
202239these useful classes.
203240
204241
205-
206-
207242Modal Dialogs
208243-------------
209244
@@ -297,6 +332,7 @@ a2s components, which in turn subclass JComponents. So no changes in code are ne
297332successfully transpiled over 500 applets using this strategy. (Kind of surprising, actually, that
298333the original Java developers did not see that option. But we have a hindsight advantage here.)
299334
335+
300336Working with Files
301337==================
302338
@@ -317,11 +353,15 @@ does not generate a pseudo-download to the user's machine.
317353UNIMPLEMENTED CLASSES BY DESIGN
318354===============================
319355
356+ The SwingJS implementation of the following classes are present
357+ in a way that gracefully bypasses their functionality:
358+
320359accessibility
321360security
322361serialization
323362
324363
364+
325365TODO LIST FOR UNIMPLEMENTED CLASSES
326366===================================
327367
@@ -341,7 +381,10 @@ Thread.currentThread() == dispatchThread
341381MINOR ISSUES--requiring some rewriting/refactoring outside of SwingJS
342382=====================================================================
343383
384+ See below for a full discussion.
344385
386+ Names with "$" and "_"
387+ positive integers do not add to give negative numbers
345388ArrayIndexOutOfBounds
346389java.awt.Color
347390native methods
@@ -362,7 +405,7 @@ MAJOR ISSUES--for Bob and Udo within SwingJS
362405fonts
363406OS-dependent classes
364407AWT component peers
365-
408+ some aspects of reflection
366409
367410MAJOR ISSUES--to be resolved by implementers
368411============================================
@@ -442,26 +485,24 @@ changed to JSToolkit.isDispatchThread()
442485MINOR ISSUES--requiring some rewriting/refactoring outside of SwingJS
443486=====================================================================
444487
445- primitive numerical types
446- -------------------------
488+ positive integers do not add to give negative numbers
489+ -----------------------------------------------------
447490
448- Large integers will never roll over to negative ones. They will
449- just get bigger.
450-
451- int newLength = lineBuf.length * 2;
452- /**
453- * @j2sIgnore
454- */
455- {
456- // never going to happen in JavaScript
457- if (newLength < 0) {
458- newLength = Integer.MAX_VALUE;
459- }
460- }
491+ In Java, the following is true:
461492
493+ 2000000000 + 2000000000 == -294967296
462494
463- Because "-1" in JavaScript is not 0xFFFFFFFF one must take care to not compare a negative
464- number with a 32-bit mask. So
495+ But in SwingJS, that will be 4000000000. So, for example, the following
496+ strategy will fail in SwingJS:
497+
498+ int newLength = lineBuf.length * 2;
499+ if (newLength < 0) {
500+ newLength = Integer.MAX_VALUE;
501+ }
502+
503+ "-1" in JavaScript is not 0xFFFFFFFF.
504+
505+ And one must take care to not compare a negative number with a 32-bit mask. So
465506
466507(b & 0xFF000000) == 0xFF000000
467508
@@ -476,6 +517,74 @@ The fix is that one must compare similar operations:
476517
477518if ((b & 0xFF000000) == (0xFF000000 & 0xFF000000)) .....
478519
520+ Importantly, the JavaScript Int32Array does behave properly. From
521+ the Firefox developer console:
522+
523+ >> x = new Int32Array(1)
524+ <- Int32Array(1) [ 0 ]
525+ >> x[0] = 4000000000
526+ <- 4000000000
527+ >> x[0]
528+ <- -294967296
529+
530+ Notice that, perhaps unexpectedly, the following two constructs produce
531+ different results in JavaScript:
532+
533+ x = new Int32Array(1);
534+ b = x[0] = 4000000000;
535+
536+ (b will be 4000000000)
537+
538+ and
539+
540+ x = new Int32Array(1);
541+ x[0] = 4000000000;
542+ b = x[0];
543+
544+ (b will be -294967296)
545+
546+
547+ SwingJS leverages array typing to handle all byte and short arithmetic so as
548+ to ensure that any byte or short operation in JavaScript does give the same
549+ result in Java. The design decision to not also do this with integer math was
550+ a trade-off between performance and handling edge cases.
551+
552+
553+ Names with "$" and "_"
554+ ----------------------
555+
556+ For the most part, this should be no problem.
557+
558+ Note that the use of $ and _ in Java field names has always been discouraged:
559+ [https://docs.oracle.com/javase/tutorial/java/nutsandbolts/variables.html]
560+
561+ You may find some situations where auto-generated names will contain the dollar sign,
562+ but your variable names should always avoid using it. A similar convention
563+ exists for the underscore character; while it's technically legal to begin your
564+ variable's name with "_", this practice is discouraged.
565+
566+ Some impacts of transpiling method names with full qualification:
567+
568+ 1) SwingJS will introduce fields that start with $ or _. These will not conflict
569+ if the above convention is followed.
570+
571+ 2) Fields that have the same Java name as a method are not an issue.
572+
573+ 3) Fields that have a Java name with $ that matches a transpiled method name,
574+ such as toString$, will need to be refactored in Java to not have that name collision.
575+
576+ 4) Fields in a subclass that have the same name as private fields in a superclass
577+ represent a name collision, because the superclass method needs to call its private
578+ field even if invoked from a subclass. The solution was to modify the subclass field
579+ name using one or more prepended $.
580+
581+ 5) Use of Class.getDeclaredMethods() reflection will return Method objects having the transpiled
582+ name, not the Java name. This could require some j2sNative adjustment
583+ to strip the $... parameters from the name if that is needed.
584+
585+ 6) Use of Method.getParameterTypes() should work fine, provided class names
586+ do not contain "_". This is because the transpiler converts "." to "_" when
587+ creating the fully qualified JavaScript name.
479588
480589
481590ArrayIndexOutOfBounds
@@ -1027,6 +1136,7 @@ The JS document model does not allow two text fields to address the same underly
10271136Formatter/Regex limitations
10281137---------------------------
10291138
1139+ Some browsers cannot process Regex "look-behind" process such as (?<=\W)
10301140java.util.regex.Matcher and Pattern use JavaScript's RegExp object rather than
10311141the native Java object. These are not identical. Only flags /igm are supported.
10321142Matcher.start(groupID) is not supported.
0 commit comments