Describing postprocessing and a way to get started. Fixing other parts of Javadoc
1.1 --- a/boot/pom.xml Wed Feb 05 13:37:51 2014 +0100
1.2 +++ b/boot/pom.xml Thu Feb 06 09:28:25 2014 +0100
1.3 @@ -24,6 +24,7 @@
1.4 <configuration>
1.5 <instructions>
1.6 <Agent-Class>org.netbeans.html.boot.impl.JsAgent</Agent-Class>
1.7 + <Premain-Class>org.netbeans.html.boot.impl.JsAgent</Premain-Class>
1.8 <Eclipse-BuddyPolicy>dependent</Eclipse-BuddyPolicy>
1.9 </instructions>
1.10 </configuration>
2.1 --- a/boot/src/main/java/net/java/html/boot/package.html Wed Feb 05 13:37:51 2014 +0100
2.2 +++ b/boot/src/main/java/net/java/html/boot/package.html Thu Feb 06 09:28:25 2014 +0100
2.3 @@ -45,6 +45,10 @@
2.4 <!DOCTYPE html>
2.5 <html>
2.6 <body>
2.7 - <div>Builder class to bootstrap your Java/HTML based application</div>
2.8 + <div>Builder class to bootstrap your Java/HTML based application.</div>
2.9 + See {@link net.java.html.boot.BrowserBuilder} for description how to
2.10 + launch your application. Look at {@link net.java.html.js.JavaScriptBody}
2.11 + and its usage in case you want to directly talk between Java and
2.12 + JavaScript.
2.13 </body>
2.14 </html>
3.1 --- a/boot/src/main/java/net/java/html/js/package.html Wed Feb 05 13:37:51 2014 +0100
3.2 +++ b/boot/src/main/java/net/java/html/js/package.html Thu Feb 06 09:28:25 2014 +0100
3.3 @@ -197,9 +197,98 @@
3.4 passing of arrays works OK. It is however good to keep it in mind to
3.5 avoid unwanted surprises.
3.6
3.7 - <!--
3.8 <h3>Post Process Classes</h3>
3.9 - -->
3.10 +
3.11 + Classes with {@link net.java.html.js.JavaScriptBody} annotated methods need to
3.12 + be post processed before they can be used - e.g. their <code>native</code>
3.13 + body needs to be generated to call into JavaScript (btw. the code is performed
3.14 + via {@link org.apidesign.html.boot.spi.Fn}). There are three ways
3.15 + such post processing can happen.
3.16 + <p></p>
3.17 + <b>Compile time</b> processing - this is the preferred method that
3.18 + most of the <a href="http://html.java.net">Html Java APIs</a> are using.
3.19 + Just include following plugin configuration into your <code>pom.xml</code>
3.20 + and your classes will be ready for execution as soon as <em>process-classes</em>
3.21 + <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a> phase is over:
3.22 +<pre>
3.23 +<plugin>
3.24 + <groupId>org.netbeans.html</groupId>
3.25 + <artifactId>html4j-maven-plugin</artifactId>
3.26 + <version>${net.java.html.version}</version>
3.27 + <executions>
3.28 + <execution>
3.29 + <id>js-classes</id>
3.30 + <goals>
3.31 + <goal>process-js-annotations</goal>
3.32 + </goals>
3.33 + </execution>
3.34 + </executions>
3.35 +</plugin>
3.36 +</pre>
3.37 + This plugin works in orchestration with
3.38 + <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">annotation
3.39 + processor</a> associated with {@link net.java.html.js.JavaScriptBody}
3.40 + and {@link net.java.html.js.JavaScriptResource} - the processor creates
3.41 + list of files that need post-processing. The
3.42 + <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
3.43 + plugin reads these files, processes classes mentioned in them and
3.44 + modifies (and deletes at the end) the files to not include classes
3.45 + already processed.
3.46 + <p></p>
3.47 + <b>Instrumentation Agent</b> - one can do processing in runtime
3.48 + using JDK's {@link java.lang.instrument.ClassFileTransformer instrumentation}
3.49 + abilities. The JAR artifact of <code>org.netbeans.html:net.java.html.boot</code>
3.50 + contains an <code>Agent-Class</code> and <code>Premain-Class</code>
3.51 + definitions in its manifest. As such one can launch the Java virtual
3.52 + machine with
3.53 +<pre>
3.54 +$ java -javaagent:jarpath=net.java.html.boot-x.y.jar
3.55 +</pre>
3.56 + and the runtime will take care of processing bytecode of classes
3.57 + not yet processed in compile time before they are loaded into the
3.58 + virtual machine.
3.59 + <p></p>
3.60 + <b>Special classloading</b> - when booting your application with
3.61 + {@link net.java.html.boot.BrowserBuilder} there is a 3rd option of
3.62 + processing the classes. If there are some classes not yet processed
3.63 + (remember the files listing them generated by the
3.64 + <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">annotation
3.65 + processor</a>), the {@link net.java.html.boot.BrowserBuilder#showAndWait() launching method}
3.66 + will create a special classloader to that does the processing before
3.67 + loading the bytecode into the virtual machine.
3.68 + <p></p>
3.69 + The options are rich, however to avoid any troubles, it is recommended
3.70 + to perform the <b>compile time</b> processing.
3.71
3.72 + <h3>Getting Started</h3>
3.73 +
3.74 + There are many ways to start developing
3.75 + <a href="http://html.java.net">Html for Java</a> application.
3.76 + However to be sure one chooses the most recent setup, it is recommended
3.77 + to switch to good old command line and use a
3.78 + <a href="http://wiki.apidesign.org/wiki/Knockout4Java">Maven archetype</a>
3.79 + associated with every version of this project. Just type:
3.80 +<pre>
3.81 +$ mvn archetype:generate \
3.82 + -DarchetypeGroupId=org.apidesign.html \
3.83 + -DarchetypeArtifactId=knockout4j-archetype \
3.84 + -DarchetypeVersion=x.y
3.85 +</pre>
3.86 + Answer few questions (for example choose myfirstbrwsrpage as artifactId) and then you can:
3.87 +<pre>
3.88 +$ cd myfirstbrwsrpage
3.89 +$ mvn process-classes exec:java
3.90 +</pre>
3.91 + In a few seconds (or minutes if
3.92 + <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
3.93 + decides to download the whole Internet of dependencies) you should
3.94 + see a sample Hello World application. It is basically composed from one
3.95 + Java and one HTML file:
3.96 +<pre>
3.97 +$ ls src/main/java/**/DataModel.java
3.98 +$ ls src/main/webapp/pages/index.html
3.99 +</pre>
3.100 + Play with them, modify them and enjoy
3.101 + <a href="http://html.java.net">Html for Java</a>!
3.102 </body>
3.103 </html>
4.1 --- a/boot/src/main/java/org/apidesign/html/boot/spi/Fn.java Wed Feb 05 13:37:51 2014 +0100
4.2 +++ b/boot/src/main/java/org/apidesign/html/boot/spi/Fn.java Thu Feb 06 09:28:25 2014 +0100
4.3 @@ -194,9 +194,9 @@
4.4 public abstract Object invoke(Object thiz, Object... args) throws Exception;
4.5
4.6 /** Provides the function implementation access to the presenter provided
4.7 - * in {@link #Fn(org.apidesign.html.boot.spi.Fn.Presenter) the constructor).
4.8 + * in {@link #Fn(org.apidesign.html.boot.spi.Fn.Presenter) the constructor}.
4.9 *
4.10 - * @return presenter passed in in the constructor (may be, but should not be <code>null</code>)
4.11 + * @return presenter passed in the constructor (may be, but should not be <code>null</code>)
4.12 * @since 0.7
4.13 */
4.14 protected final Presenter presenter() {
5.1 --- a/boot/src/main/java/org/apidesign/html/boot/spi/package.html Wed Feb 05 13:37:51 2014 +0100
5.2 +++ b/boot/src/main/java/org/apidesign/html/boot/spi/package.html Thu Feb 06 09:28:25 2014 +0100
5.3 @@ -46,5 +46,9 @@
5.4 <html>
5.5 <body>
5.6 <div>Interfaces for integrators of various execution environments.</div>
5.7 + Not really interesting for clients. The clients should rather use
5.8 + {@link net.java.html.boot.BrowserBuilder} to launch their applications,
5.9 + or (if they need to do some JavaScript calls themselves) look at
5.10 + {@link net.java.html.js.JavaScriptBody} annotation and its usage.
5.11 </body>
5.12 </html>
6.1 --- a/boot/src/main/java/org/netbeans/html/boot/impl/JsAgent.java Wed Feb 05 13:37:51 2014 +0100
6.2 +++ b/boot/src/main/java/org/netbeans/html/boot/impl/JsAgent.java Thu Feb 06 09:28:25 2014 +0100
6.3 @@ -52,6 +52,10 @@
6.4 * @author Jaroslav Tulach <jtulach@netbeans.org>
6.5 */
6.6 public final class JsAgent implements ClassFileTransformer {
6.7 + public static void premain(String args, Instrumentation instr) {
6.8 + instr.addTransformer(new JsAgent());
6.9 + }
6.10 +
6.11 public static void agentmain(String args, Instrumentation instr) {
6.12 instr.addTransformer(new JsAgent());
6.13 }