org.testng
diff --git a/boot/src/main/java/net/java/html/boot/BrowserBuilder.java b/boot/src/main/java/net/java/html/boot/BrowserBuilder.java
index c732dc22e..9636398da 100644
--- a/boot/src/main/java/net/java/html/boot/BrowserBuilder.java
+++ b/boot/src/main/java/net/java/html/boot/BrowserBuilder.java
@@ -103,9 +103,9 @@ private BrowserBuilder(Object[] context) {
* {@link Contexts#newBuilder(java.lang.Object...) created}
* and can influence the selection
* of available technologies
- * (like {@link org.netbeans.html.json.spi.Technology},
- * {@link org.netbeans.html.json.spi.Transfer} or
- * {@link org.netbeans.html.json.spi.WSTransfer}) by name.
+ * (like {@code org.netbeans.html.json.spi.Technology},
+ * {@code org.netbeans.html.json.spi.Transfer} or
+ * {@code org.netbeans.html.json.spi.WSTransfer}) by name.
*
* @param context any instances that should be available to the builder -
* implementation dependant
diff --git a/boot/src/main/java/net/java/html/js/package.html b/boot/src/main/java/net/java/html/js/package.html
index 4523d234a..848059384 100644
--- a/boot/src/main/java/net/java/html/js/package.html
+++ b/boot/src/main/java/net/java/html/js/package.html
@@ -25,10 +25,10 @@
Mix your Java and JavaScript code seamlessly - perform calls from Java
to JavaScript and back with as much freedom as JavaScript gives you
and as much type safety you can get from Java. Execute your code
- in a headless testing environment or in a
- JavaFX WebView .
+ in a headless testing environment or in a
+ JavaFX WebView .
When done, deploy to real browsers .
-
+
Simple Meaning of World
The whole support is build around @JavaScriptBody
annotation. Use it to create parametrised JavaScript snippet easily
@@ -42,7 +42,7 @@ Simple Meaning of World
The meaning method now becomes a properly typed Java
surface to your JavaScript code which can be directly
called from the rest of your Java code:
-
+
public static void main(String... args) {
assert 42 == meaning(40, 2) : "Meaning of World should be 42!" ;
}
@@ -53,24 +53,24 @@ Simple Meaning of World
Bodies .
Editing hint: one can see the list of arguments of the
- meaning is now duplicated - it is once specified in Java,
- and once inside of the {@link net.java.html.js.JavaScriptBody}
- array of args. This is necessary to keep the names of
+ meaning is now duplicated - it is once specified in Java,
+ and once inside of the {@link net.java.html.js.JavaScriptBody}
+ array of args. This is necessary to keep the names of
arguments accessible during runtime. However don't despair - there
is a code completion for the value of args attribute!
Just type the Java signature first and then press Ctrl+Space and the
right parameter names will be inserted for you.
-
+
Including JavaScript Libraries
Large amount of JavaScript code is easier to be delivered in whole
files rather than {@link net.java.html.js.JavaScriptBody small code snippets} -
that is also possible thanks to {@link net.java.html.js.JavaScriptResource}
annotation. Imagine file mul.js with following content:
-
+
function mul (x, y) { return x * y; }
- Place the file next to your class and reference it with
+ Place the file next to your class and reference it with
{@link net.java.html.js.JavaScriptResource the annotation}:
{@code @}{@link net.java.html.js.JavaScriptResource}("mul.js") class Mul {
@@ -90,38 +90,38 @@ Simple Meaning of World
Real code tip:
this
- is the way
+ is the way
the knockout.js library
is included in its ko4j library.
-
+
Callback to Java
-
+
Often JavaScript code needs to call back into the Java classes.
For example when a button in a browser is pressed and your code would
like to invoke a runnable to handle such situation:
-
-{@code @}{@link net.java.html.js.JavaScriptBody}(args = {"id", "r"}, {@link net.java.html.js.JavaScriptBody#javacall() javacall} = true, body = "\n" +
-" document.getElementById(id).onclick = function() {\n" +
-" r.{@code @}java.lang.Runnable::run() ();\n" +
-" };\n" +
+
+{@code @}{@link net.java.html.js.JavaScriptBody}(args = {"id", "r"}, {@link net.java.html.js.JavaScriptBody#javacall() javacall} = true, body = "\n" +
+" document.getElementById(id).onclick = function() {\n" +
+" r.{@code @}java.lang.Runnable::run() ();\n" +
+" };\n" +
" ")
public static native void onClick(String id, Runnable r);
- As can be seen, there is a special syntax (starting with @ ) to
+ As can be seen, there is a special syntax (starting with @ ) to
properly identify the right Java method to call on a Java object passed
into the JavaScript interpreter. The syntax starts with a fully
- qualified name of the class, followed by :: and name of the
+ qualified name of the class, followed by :: and name of the
method including signature of its parameters. In case of runnable,
this is just () as the method has no parameters, but the
signature can be more complicated. For example in case of following method
static int compare(int i1, String s1, int i2, String s2)
-
+
it would be (ILjava/lang/String;ILjava/lang/String;) (btw. the
- return type is not included in the signature). The actual parameters
+ return type is not included in the signature). The actual parameters
then follows. The JavaScript call to such compare method would then
look like:
{@code @}the.pkg.Clazz::compare(ILjava/lang/String;ILjava/lang/String;)(1, 'One', 2, 'Two');
-
+
This syntax gives enough flexibility, helps to properly select one
of overloaded methods and follows the tradition of previous attempts to
provide JavaScript to Java calling conventions.
@@ -133,15 +133,15 @@ Callback to Java
[instance.]@classname::methodname(signature)(arguments)
- instance - must be present when calling an
- instance method and must be absent when calling a
+ instance - must be present when calling an
+ instance method and must be absent when calling a
static method
- classname - fully qualified name of the class in
- which the method is declared
+ classname - fully qualified name of the class in
+ which the method is declared
- signature - internal JVM method signature
- (as specified at
- JNI type Signatures )
+ signature - internal JVM method signature
+ (as specified at
+ JNI type Signatures )
without the trailing signature of the method return type
arguments - the actual values to pass to the called Java method
@@ -149,9 +149,9 @@ Callback to Java
Here is the JNI type signatures table
one can use to convert
- Java parameters to JVM's internal letter based
+ Java parameters to JVM's internal letter based
representation:
-
+
Type Signature
@@ -201,19 +201,19 @@ Callback to Java
Editing hint: The callback syntax may seem complicated at
- first, however there is an associated annotation processor
+ first, however there is an associated annotation processor
that checks the syntax and verifies the referenced class and
method with the requested signature exist. If it does not, the
- compilation fails offering correct alternatives .
+ compilation fails offering correct alternatives .
Thus don't despair seeing the syntax, make sure you get the
- fully qualified name of the callback class right.
- You'll get warning and help
+ fully qualified name of the callback class right.
+ You'll get warning and help
if there is a typo in the specified signature then -
during compilation of your code.
-
+
Overloaded Methods
-
- Specifying the actual callback signature is important in case of
+
+ Specifying the actual callback signature is important in case of
overloaded methods. Imagine a class:
package x.y.z;
@@ -227,8 +227,8 @@ Overloaded Methods
int pulse(long evenMore) {
return (int ) (5 + evenMore);
}
-}
- you then need to choose in {@link net.java.html.js.JavaScriptBody}
+}
+ you then need to choose in {@link net.java.html.js.JavaScriptBody}
the appropriate method to call:
{@code @}{@link net.java.html.js.JavaScriptBody}(args = { "h" }, javacall = true , // you want to process the @ syntax
@@ -242,17 +242,17 @@ Overloaded Methods
}
- To avoid ambiguity, the specification of the correct signature is
+ To avoid ambiguity, the specification of the correct signature is
required on every call. However, to simplify the development,
there is an annotation processor to
verify the signature really refers to an existing method.
-
+
Arrays by Copy
-
+
It is possible to exchange arrays between Java and JavaScript. Some
implementations can pass arrays by reference, however in some systems
- this is hard to achieve. To choose the least common denominator,
+ this is hard to achieve. To choose the least common denominator,
the TCK for behavior of {@link net.java.html.js.JavaScriptBody} requires
the arrays to be always transfered by a copy. As such following code:
@@ -262,33 +262,33 @@ Arrays by Copy
String[] hello = { "Hello", "World!" };
uselessModify(arr);
System.out.println(arr[0] + " " + arr[1]);
-}
+}
will still print Hello World! in spite the JavaScript code
sets the 0-th array element to null. Because the array
is passed as a copy, such assignment has no effect on the Java array.
- In case one needs to modify an array in a JavaScript and use its
+ In case one needs to modify an array in a JavaScript and use its
values in Java, one has to return the array back as a return value:
-
+
{@code @}{@link net.java.html.js.JavaScriptBody}(args = {"arr"}, body = "arr[0] = 'Ahoy'; return arr;")
private static native Object[] usefulModify(String[] arr);
public static void main(String... args) {
String[] hello = { "Hello", "World!" };
Object[] ret = usefulModify(arr);
System.out.println(ret[0] + " " + ret[1]);
-}
+}
now the program prints Ahoy World! as the modified array
is returned back and converted (by a copy) into a Java Object[]
(but of course the ret != hello). Usually the copy based
- passing of arrays works OK. It is however good to keep it in mind to
+ passing of arrays works OK. It is however good to keep it in mind to
avoid unwanted surprises.
-
+
Instance Reference to JavaScript Object
-
+
When writing wrappers around existing JavaScript libraries, it may be
- useful to hold a reference to some JavaScript object from a Java
+ useful to hold a reference to some JavaScript object from a Java
instance and use it later.
class WrapperAroundJsObj {
@@ -309,12 +309,12 @@ Instance Reference to JavaScript Object
args = { "js", "v" }, body = "js.value = v;", wait4js = false
)
private static native void setValue(Object js, int v);
-}
-
- The type of the Java reference is {@link java.lang.Object}.
+}
+
+ The type of the Java reference is {@link java.lang.Object}.
From a Java perspective it has no additional methods or fields, however
its properties can be manipulated from JavaScript. Send the object back
- to JavaScript by passing it as a parameter of some method
+ to JavaScript by passing it as a parameter of some method
(like the setValue one) and perform necessary JavaScript
calls or changes on it.
@@ -340,22 +340,26 @@ undefined === null
}
This is the behavior since version 1.4.
-
+
Post Process Classes
Classes with {@link net.java.html.js.JavaScriptBody} annotated methods need to
be post processed before they can be used - e.g. their native
- body needs to be generated to call into JavaScript (btw. the code is performed
+ body needs to be generated to call into JavaScript (btw. the call is performed
via {@link org.netbeans.html.boot.spi.Fn}). There are three ways
- such post processing can happen.
+ such a post processing can be achieved.
- Compile time processing - this is the preferred method that
- most of the Html Java APIs are using.
+
+ Compile time
+
+
+ The Compile time is the preferred method of post-processing that
+ most of the Html Java APIs are using.
Just include following plugin configuration into your pom.xml
and your classes will be ready for execution as soon as process-classes
Maven phase is over:
-
+
<plugin>
<groupId>org.netbeans.html</groupId>
<artifactId>html4j-maven-plugin</artifactId>
@@ -370,33 +374,49 @@ Post Process Classes
</executions>
</plugin>
- This plugin works in orchestration with
+ This plugin works in orchestration with
annotation
processor associated with {@link net.java.html.js.JavaScriptBody}
and {@link net.java.html.js.JavaScriptResource} - the processor creates
- list of files that need post-processing. The
+ list of files that need post-processing. The
Maven
- plugin reads these files, processes classes mentioned in them and
+ plugin reads these files, processes classes mentioned in them and
modifies (and deletes at the end) the files to not include classes
already processed.
- Instrumentation Agent - one can do processing in runtime
+
+ Instrumentation Agent
+
+
+ Instrumentation Agent can perform the post processing in runtime
using JDK's {@link java.lang.instrument.ClassFileTransformer instrumentation}
- abilities. The JAR artifact of org.netbeans.html:net.java.html.boot
- contains an Agent-Class and Premain-Class
- definitions in its manifest. As such one can launch the Java virtual
+ abilities. The JAR artifact of
+ org.netbeans.html:net.java.html.boot
+ contains an Agent-Class and Premain-Class
+ attributes in its manifest. As such one can launch the Java virtual
machine with
$ java -javaagent:jarpath=net.java.html.boot-x.y.jar
-
- and the runtime will take care of processing bytecode of classes
- not yet processed in compile time before they are loaded into the
- virtual machine.
+
+ and the runtime will take care of processing bytecode of classes
+ before they are loaded into the
+ virtual machine. Since version 1.8.2 this agent also changes retention
+ of {@link net.java.html.js.JavaScriptBody}
+ and {@link net.java.html.js.JavaScriptResource} annotations
+ to {@link java.lang.annotation.RetentionPolicy#RUNTIME}.
+ As such technologies that need
+ access to these annotations during runtime can do so by using the
+ -javaagent JVM switch.
- Special classloading - when booting your application with
+
+ Special classloading
+
+
+ There is a special implementation of dynamic classloader .
+ When booting your application with
{@link net.java.html.boot.BrowserBuilder} there is a 3rd option of
processing the classes. If there are some classes not yet processed
- (remember the files listing them generated by the
+ (remember the files listing them generated by the
annotation
processor ), the {@link net.java.html.boot.BrowserBuilder#showAndWait() launching method}
will create a special classloader to that does the processing before
@@ -406,16 +426,16 @@ Post Process Classes
processing needs to also include asm-5.0.jar on application
classpath), it is recommended
to perform the compile time processing.
-
+
Getting Started
-
- There are many ways to start developing
- Html for Java application.
+
+ There are many ways to start developing
+ Html for Java application.
However to be sure one chooses the most recent setup, it is recommended
- to switch to good old command line and use a
+ to switch to good old command line and use a
Maven archetype
associated with every version of this project. Just type:
-
+
$ mvn archetype:generate \
-DarchetypeGroupId=org.apidesign.html \
-DarchetypeArtifactId=knockout4j-archetype \
@@ -426,10 +446,10 @@ Getting Started
$ cd myfirstbrwsrpage
$ mvn process-classes exec:java
- In a few seconds (or minutes if
+ In a few seconds (or minutes if
Maven
- decides to download the whole Internet of dependencies) you should
- see a sample Hello World application. It is basically composed from one
+ decides to download the whole Internet of dependencies) you should
+ see a sample Hello World application. It is basically composed from one
Java and one HTML file:
$ ls src/main/java/**/DataModel.java
@@ -437,22 +457,22 @@ Getting Started
Play with them, modify them and enjoy
Html for Java !
-
+
Mixed Java/JavaScript Debugging
-
+
- The following video shows how easy it is to use
- NetBeans 8.0, JDK8 to debug an application that intermixes Java
- and JavaScript calls. One can put breakpoints into Java part,
- as well as JavaScript source code, inspect Java as well
- as JavaScript variables and switch between these two
+ The following video shows how easy it is to use
+ NetBeans 8.0, JDK8 to debug an application that intermixes Java
+ and JavaScript calls. One can put breakpoints into Java part,
+ as well as JavaScript source code, inspect Java as well
+ as JavaScript variables and switch between these two
languages without any restrictions.
-
- VIDEO