3 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
5 Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.
7 Oracle and Java are registered trademarks of Oracle and/or its affiliates.
8 Other names may be trademarks of their respective owners.
10 The contents of this file are subject to the terms of either the GNU
11 General Public License Version 2 only ("GPL") or the Common
12 Development and Distribution License("CDDL") (collectively, the
13 "License"). You may not use this file except in compliance with the
14 License. You can obtain a copy of the License at
15 http://www.netbeans.org/cddl-gplv2.html
16 or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
17 specific language governing permissions and limitations under the
18 License. When distributing the software, include this License Header
19 Notice in each file and include the License file at
20 nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
21 particular file as subject to the "Classpath" exception as provided
22 by Oracle in the GPL Version 2 section of the License file that
23 accompanied this code. If applicable, add the following below the
24 License Header, with the fields enclosed by brackets [] replaced by
25 your own identifying information:
26 "Portions Copyrighted [year] [name of copyright owner]"
30 The Original Software is NetBeans. The Initial Developer of the Original
31 Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.
33 If you wish your version of this file to be governed by only the CDDL
34 or only the GPL Version 2, indicate your decision by adding
35 "[Contributor] elects to include this software in this distribution
36 under the [CDDL or GPL Version 2] license." If you do not indicate a
37 single choice of license, a recipient has the option to distribute
38 your version of this file under either the CDDL, the GPL Version 2 or
39 to extend the choice of license to its licensees as provided above.
40 However, if you add GPL Version 2 code and therefore, elected the GPL
41 Version 2 license, then the option applies only if the new code is
42 made subject to such option by the copyright holder.
48 <title>HTML for Java APIs</title>
49 <meta charset="UTF-8">
50 <meta name="viewport" content="width=device-width, initial-scale=1.0">
51 <style type="text/css">
57 border: 1px solid black;
59 table.field td.UNKNOWN {
60 background-color: #D6E4E1;
63 table.field td.EXPLOSION {
64 background-color: #A31E39;
66 table.field td.DISCOVERED {
67 background-color: #9DB2B1;
73 Use Java to write application logic; Use HTML5 to render the UI;
74 {@link net.java.html.json.Model Animate an HTML page from Java}
75 (see <a target="_blank" href="http://dew.apidesign.org/dew/#7212206">Duke being rotated</a> by CSS);
76 Use {@link net.java.html.json.OnReceive REST} or
77 <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>;
78 interact with <a href="net/java/html/js/package-summary.html">JavaScript</a>;
79 Get the best of both worlds!
81 The goal of these APIs is to use full featured Java runtime
82 (like real <a target="_blank" href="http://wiki.apidesign.org/wiki/HotSpot">HotSpot VM</a>),
83 but still rely on a very lightweight rendering technology
84 (so it can potentially fit
85 <a target="_blank" href="http://bck2brwsr.apidesign.org">Bck2Brwsr</a> and definitely
86 to various types of phones). What can be more lightweight
87 (from a browser perspective) than
88 <a target="_blank" href="http://wiki.apidesign.org/wiki/HTML">HTML</a>!?
89 By default we use {@link net.java.html.boot.fx JavaFX's WebView}
90 component to display the <a target="_blank" href="http://wiki.apidesign.org/wiki/HTML">HTML</a>.
91 We eliminate the need to manipulate the DOM directly,
92 there is a special {@link net.java.html.json Java to Knockout.js binding}.
93 As a result the <a target="_blank" href="http://knockoutjs.com">HTML uses Knockout.js syntax</a>,
94 yet the application code can be written in Java.
97 <h3>Improvements in version 1.3</h3>
99 {@link net.java.html.json.Model Model classes} can have
100 {@link net.java.html.json.Model#instance() per-instance private data}.
101 {@link net.java.html.json.Model Model classes} can generate
102 builder-like construction methods if builder
103 {@link net.java.html.json.Model#builder() prefix} is specified.
104 {@link net.java.html.json.Property#mutable} can be <code>false</code>
105 to define a non-mutable (almost constant) property. That
106 in case of <em>Knockout</em> bindings means: the property is
107 represented by a plain value rather than an observable in the JavaScript
108 object. The <em>JavaFX</em> presenter can be executed in headless mode -
109 just specify <code>-Dfxpresenter.headless=true</code> when launching
110 its virtual machine and no window will be shown. This is particularly
111 useful for testing. Configure your <em>surefire</em> or <em>failsafe</em>
114 <groupId>org.apache.maven.plugins</groupId>
115 <artifactId>maven-surefire-plugin</artifactId>
116 <version>2.13</version>
117 <configuration>
118 <systemPropertyVariables>
119 <fxpresenter.headless>true</fxpresenter.headless>
120 </systemPropertyVariables>
121 </configuration>
124 OSGi headers are now <a target="_blank" href="https://netbeans.org/bugzilla/show_bug.cgi?id=256696">
125 enterprise OSGi ready</a>.
126 Switched to <a target="_blank" href="https://netbeans.org/bugzilla/show_bug.cgi?id=257130">minified version 3.4.0</a>
127 of <a target="_blank" href="http://knockoutjs.com">knockout.js</a>.
128 Better support for <a target="_blank" href="https://netbeans.org/bugzilla/show_bug.cgi?id=257348">
129 recursive @Model definitions</a>.
130 <h3>What's Been Improved in Version 1.2.3?</h3>
132 One can control {@link net.java.html.json.OnReceive#headers() HTTP request headers}
133 when connecting to server using the {@link net.java.html.json.OnReceive}
134 annotation. It is possible to have
135 {@link net.java.html.json.ComputedProperty#write() writable computed properties}.
136 There is an easy way to enable <a target="_blank" href="http://getfirebug.com/">Firebug</a> in
137 the JavaFX based Web View -
138 just run with <code>-Dfirebug.lite=true</code> as
139 <a target="_blank" href="https://www.youtube.com/watch?v=2rxwY-QJiLo">this video</a>
141 Bugfix of issues <a target="_blank" href='https://netbeans.org/bugzilla/show_bug.cgi?id=250503'>250503</a>,
142 <a target="_blank" href='https://netbeans.org/bugzilla/show_bug.cgi?id=252987'>252987</a>.
144 <h3>What's New in Version 1.1?</h3>
147 The content of a {@link net.java.html.BrwsrCtx context}
148 can be selected by registering implementations under specific
149 {@link org.netbeans.html.context.spi.Contexts.Id technology identifiers}
150 and requesting them during
151 {@link org.netbeans.html.context.spi.Contexts#newBuilder(java.lang.Object...) construction}
152 of the context. <code>org.netbeans.html:ko4j</code> module's implementation
153 offers <b>ko4j</b>, <b>xhr</b> and <b>websocket</b> identifiers
154 for its registered services
155 (e.g. {@link org.netbeans.html.json.spi.Technology},
156 {@link org.netbeans.html.json.spi.Transfer} and
157 {@link org.netbeans.html.json.spi.WSTransfer}).
158 <code>org.netbeans.html:ko-ws-tyrus</code>
160 {@link org.netbeans.html.json.spi.Transfer Java based JSON} and
161 {@link org.netbeans.html.json.spi.WSTransfer WebSocket} implementations
162 under the name <b>tyrus</b>.
165 A particular DOM subtree
166 that a <a target="_blank" href="http://knockoutjs.com">knockout.js</a> model gets
167 applied to can be selected by using
168 {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)
169 Models.applyBindings(m, id)} with an id of an HTML element.
170 There is new {@link net.java.html.json.Model#targetId()} attribute
171 which controls behavior of the generated <code>applyBindings</code> method.
172 If <em>specified and non-empty</em>, then the generated method
173 will call {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)}
174 with <code>this</code> and the provided {@link net.java.html.json.Model#targetId() target id}.
175 If <em>specified, but left empty</em>, then the generated method
176 calls {@link net.java.html.json.Models#applyBindings(java.lang.Object)}.
177 <em>If unspecified</em>, the method will <b>not</b> be generated at all
178 (a change with respect to older versions). However one can
179 still use {@link net.java.html.json.Models#applyBindings(java.lang.Object)}
180 or {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)}
181 to perform the association of any model with the page element.
184 Memory model when using Knockout bindings has been improved
185 (required additions of two new methods:
186 {@link org.netbeans.html.json.spi.PropertyBinding#weak()} and
187 {@link org.netbeans.html.json.spi.FunctionBinding#weak()}) and
188 now the Java {@link net.java.html.json.Model models} can garbage collect,
189 when no longer used. Library writers that use
190 {@link net.java.html.js.JavaScriptBody} annotation can also
191 control garbage collection behavior of method arguments by
192 setting {@link net.java.html.js.JavaScriptBody#keepAlive() keepAlive=false}
196 <h3>What's New in Version 1.0?</h3>
199 {@link net.java.html.json.Property#array() Array properties} are now
200 mutable from the <a href="http://knockoutjs.com">knockout.js</a>
201 point of view (required {@link org.netbeans.html.json.spi.Proto.Type#replaceValue one SPI change}).
202 The page lookup mechanism can use {@link net.java.html.boot.BrowserBuilder#locale(java.util.Locale) locale}
203 to load localized a page with appropriate suffix.
204 All SPI were moved under the NetBeans namespace - e.g.
205 {@link org.netbeans.html.boot.spi},
206 {@link org.netbeans.html.context.spi},
207 {@link org.netbeans.html.json.spi},
208 {@link org.netbeans.html.sound.spi}, and also
209 {@link org.netbeans.html.json.tck}. Methods annotated
210 with {@link net.java.html.js.JavaScriptBody} annotation and
211 without fallback Java code now throw {@link java.lang.IllegalStateException}
212 with a message suggesting to switch to proper
213 {@link net.java.html.BrwsrCtx#execute browser context} to
214 prevent endless debugging when one forgets to do so.
218 What's new in older versions? Click the
219 <a href="#" onclick="return showHistoric(true)">link</a>
221 <a href="#" onclick="return showHistoric(true)">historic changes</a> below:
224 <a name="historic.changes"></a>
225 <div id="historic.changes">
227 function showHistoric(show) {
228 var e = document.getElementById("historic.changes");
230 e.style.display="block";
232 e.style.display="none";
239 <h3>What's New in Version 0.9?</h3>
242 System can run in {@link net.java.html.boot.BrowserBuilder#classloader(java.lang.ClassLoader) Felix OSGi container} (originally only Equinox).
243 {@link net.java.html.json.ComputedProperty Derived properties}
244 now deeply check changes in other {@link net.java.html.json.Model model
245 classes} they depend on and recompute their values accordingly.
246 <a target="_blank" href="http://knockoutjs.com">Knockout.js</a> library has been updated
250 <h3>What's New in 0.8.x Versions?</h3>
253 Setters or array properties on classes generated by {@link net.java.html.json.Model}
254 annotation can be accessed from any thread. {@link org.netbeans.html.sound.spi.AudioEnvironment}
255 can be registered into {@link net.java.html.BrwsrCtx}. There is
256 a {@link net.java.html.json.Models#parse(net.java.html.BrwsrCtx, java.lang.Class, java.io.InputStream, java.util.Collection) method}
257 to parse a JSON array and convert it into
258 {@link net.java.html.json.Model model classes}.
259 Improved behavior of <code>enum</code> values in
260 {@link net.java.html.json.Model knockout bindings}.
264 Few bugfixes for better portability.
265 New API for {@link net.java.html.boot.script.Scripts headless execution}
266 on top of <em>Nashorn</em> - does not run <em>knockout for Java</em>
268 (reported as <a href="https://bugs.openjdk.java.net/browse/JDK-8046013">JDK-8046013</a>),
269 however even in current state it is quite
270 {@link net.java.html.boot.script.Scripts useful for testing}
272 {@link net.java.html.js Java/JavaScript interactions}.
276 {@link net.java.html.boot.fx.FXBrowsers} has been extended
277 with new helper methods to make it easier to use HTML+Java
278 API in existing JavaFX applications.
279 The annotation processor is made
280 more robust with respect to errors in callback syntax of
281 {@link net.java.html.js.JavaScriptBody} body parameter.
282 Javadoc of {@link net.java.html.BrwsrCtx#execute} method
283 has been improved based on a failure of its usability study.
284 There can be additional parameters to methods annotated by
285 {@link net.java.html.json.OnReceive} that allows one to
286 pass state when a JSON call is made and use it when it finishes.
287 The mechanism of discovery of sibling HTML page has been
288 extended to work on systems that don't support
289 {@link java.lang.Class#getProtectionDomain}.
293 The first argument of method annotated by
294 {@link net.java.html.json.OnReceive} annotation has to
295 be the associated {@link net.java.html.json.Model model class}.
299 {@link net.java.html.json.OnReceive} annotation now accepts
300 {@link java.util.List} of data values as second argument
301 (previously required an array).
305 <h3>What's New in 0.7.x Versions?</h3>
308 {@link net.java.html.js.JavaScriptBody} annotation has new attribute
309 {@link net.java.html.js.JavaScriptBody#wait4js()} which allows
310 asynchronous execution. Libraries using
311 {@link net.java.html.js.JavaScriptBody} are urged to use this
312 new attribute as much as possible, as it can speed up execution
313 in certain environments.
317 Use {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable)} in
318 multi-threaded environment to execute your code on the browser thread.
320 {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable) using Java timer}.
324 <h3>Interesting Entry Points</h3>
326 <p>Learn how to {@link net.java.html.json.Model animate an HTML page from Java}
327 without referencing single HTML element from the Java code.
329 <p>Use {@link net.java.html.json.OnReceive JSON} to communicate
330 with REST based server API.
332 <p>Use <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>
335 <p>Call JavaScript methods from Java and vice versa, via
336 <a href="net/java/html/js/package-summary.html">JavaScriptBody</a>.
339 <h3>Getting Started</h3>
341 There are <a href="http://wiki.apidesign.org/wiki/DukeScriptInNetBeans">many ways</a>
343 <a href="http://html.java.net">Html for Java</a> application.
344 However to be sure one chooses the most recent setup, it is recommended
345 to switch to good old command line and use a
346 <a href="http://wiki.apidesign.org/wiki/Knockout4Java">Maven archetype</a>
347 associated with every version of this project. Make sure at least
348 <em>JDK7</em> is your installed Java and type:
350 $ mvn archetype:generate \
351 -DarchetypeGroupId=org.apidesign.html \
352 -DarchetypeArtifactId=knockout4j-archetype \
353 -DarchetypeVersion=0.8 <em># or newer version, if available</em>
355 Answer few questions (for example choose myfirstbrwsrpage as artifactId)
358 $ cd myfirstbrwsrpage
359 $ mvn process-classes exec:java
361 In a few seconds (or minutes if
362 <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
363 decides to download the whole Internet of dependencies) you should
364 see a sample Hello World application rendered in a
365 <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
366 web view component (that of course requires your JDK to come
367 with <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>;
368 <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK7
369 and JDK8 from Oracle</a> contain everything that is needed).
370 The generated application is built around one
371 Java source (uses the {@link net.java.html.json.Model} annotation to
372 auto-generate another <code>Data.java</code> class during compilation)
373 and one HTML file (uses the <a href="http://knockoutjs.com">Knockout</a>
374 syntax to <code>data-bind</code> the HTML elements to the
375 generated <code>Data</code> model):
377 $ ls src/main/java/**/DataModel.java
378 $ ls src/main/webapp/pages/index.html
380 That is all you need to get started. Play with the sources,
381 modify them and enjoy
382 <a href="http://html.java.net">Html for Java</a>!
387 This API is part of <a target="_blank"
388 href="http://netbeans.org">NetBeans.org</a> project and as such
389 it works naturally with the <a target="_blank"
390 href="https://netbeans.org/features/index.html">NetBeans IDE</a>.
391 On the other hand, the API is using nothing NetBeans specific,
392 it builds on standard Java6 APIs and as such it shall work fine
397 A lot of work is done by
398 <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">
399 annotation processors</a>
400 that generate various boiler plate code during compilation. This
401 is a standard part of Java since JDK6, but for example Eclipse
402 is known not to deal with processors well and developers using
403 it need to be careful. IntelliJ users hasn't reported any issues
404 and of course, NetBeans IDE support for
405 <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">processors</a>
410 When using {@link net.java.html.js.JavaScriptBody} annotation, it is
411 useful to do a bit of post processing of classes. There is a
412 <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
414 NetBeans IDE will invoke it when doing a build. Other IDEs may
415 need some hint to do so.
416 Anyway: If one does not see all (generated) sources or is getting
417 {@link java.lang.LinkageError}s when executing the application,
418 switch to command line and do clean build
421 <pre>$ mvn clean install</pre>
423 If that succeeds, your IDE of choice will hopefully
424 pick the generated sources up and present the result of the build
426 <a href="https://netbeans.org/downloads/">download NetBeans</a>,
427 you will be pleasantly
428 surprised - for example with our excellent
429 <a href="net/java/html/js/package-summary.html#debugging">Java/JavaScript
430 debugging</a> support.
434 <h2>Deploy Your Application</h2>
438 It is not goal of this documentation to list all possible ways
439 to package and deploy applications which use this API. However it is
440 important for new comers to see the benefits of using the
441 <a href="http://html.java.net">HTML for Java</a> API and as such
442 let's list at least few bundling options, known to work at the time of writing
447 First of all, this is a <em>client technology</em>. You write client applications
448 with it which may, but need not connect to a server. You don't need
449 Tomcat or WebLogic to deploy
450 <a href="http://html.java.net">HTML for Java</a> applications.
454 <img src='resources/javafx_logo.jpg' width="64"
455 height="64" align="left"/>
456 The sample project generated by
457 <code>org.apidesign.html knockout4j-archetype</code> is configured
458 to use <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
459 as the rendering technology. This setup is primarily suitable for
460 development - it needs no special packaging, starts quickly and
461 allows you to use classical HotSpot VM debuggers. A final
462 artifact from the build is also a ZIP file which you can use
463 and distribute to your users. Good for desktop applications.
467 <img src='resources/netbeans_logo.jpg' width="64"
468 height="64" align="right"/>
469 <img src='resources/eclipse_logo.png' width="64"
470 height="64" align="right"/>
471 All the <a href="http://html.java.net">HTML for Java</a> libraries
472 are packaged as <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
473 bundles and as such they can easily be run in NetBeans as well as
474 in Eclipse. As a result one can use
475 <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
476 and have a common module system for both platforms. In addition to that
478 HTML and have a common UI in both platforms. In such case
479 your application would be packaged as a set of
480 <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a> bundles.
482 <a href="http://wiki.apidesign.org/wiki/HTML">more</a>...
486 <img src='resources/chrome_logo.png' width="64"
487 height="64" align="left"/>
488 <img src='resources/safari_logo.png' width="64"
489 height="64" align="left"/>
490 <img src='resources/ie_logo.png' width="64"
491 height="64" align="left"/>
492 <img src='resources/firefox_logo.png' width="64"
493 height="64" align="left"/>
495 There is more and more attempts to execute Java bytecode
496 in a browser, without any special Java plugin installed.
497 The <a href="http://html.java.net">HTML for Java</a> is
498 carefully designed to produce lightweight, well performing
499 applications even on such restricted environments. It uses
500 no reflection calls and that allows to statically pre-compile
501 the applications into JavaScript. One of such environments
502 is called <a href="http://wiki.apidesign.org/wiki/Bck2Brwsr">Bck2Brwsr</a>,
503 another <a href="http://wiki.apidesign.org/wiki/TeaVM">TeaVM</a>. Both support the
504 {@link net.java.html.js.JavaScriptBody} annotation. Read
505 <a href="http://wiki.apidesign.org/wiki/Bck2BrwsrViaCLI">more</a> or play
506 a minesweeper game packaged for your browser
507 (of course <a target="_blank"
508 href="http://source.apidesign.org/hg/html~demo/file/ea79b73d590a/minesweeper/src/main/java/org/apidesign/demo/minesweeper/MinesModel.java">
509 written</a> in Java):
512 <script type="text/html" id="field">
513 <table class="field">
515 <!-- ko foreach: rows -->
517 <!-- ko foreach: columns -->
518 <td data-bind="css: style, click: $parents[1].click" >
519 <div data-bind='html: html'></div>
528 <div data-bind="template: { name : 'field', if: fieldShowing }"></div>
530 <!-- boot bck2brwsr -->
531 <script type="text/javascript" src="resources/teavm.js"></script>
534 vm.loadClass('org.apidesign.demo.minesweeper.MainBrwsr');
538 <img src='resources/ios_logo.jpg' width="64"
539 height="64" align="right"/>
540 <img src='resources/android_logo.jpg' width="64"
541 height="64" align="right"/>
543 Now when we have seen that the
544 <a href="http://html.java.net">HTML for Java</a> applications
545 can run on any modern browser, we can ask whether they can also
546 fit into a phone!? Yes, they can and especially to phones
547 that can execute Java code already! Just by changing your
548 packaging you can create an APK file and deploy it to your
550 Read <a target="_blank" href="http://wiki.apidesign.org/wiki/DlvkBrwsr">more</a>...
551 In case you'd like your application to reach out to second biggest
552 group of smartphone users, don't despair: It
553 seems the set of devices that can execute
554 <a href="http://html.java.net">HTML for Java</a> applications
555 has been extended to <em>iPads</em> and <em>iPhones</em>. Get the
556 <a target="_blank" href="http://wiki.apidesign.org/wiki/IBrwsr">details here</a>
557 and deploy everywhere!
560 Convinced it makes sense to use
561 <a href="http://html.java.net">HTML for Java</a>
562 APIs for writing applications that are
563 <em>written once, displayed anywhere</em>? Or do you have an
564 environment which is not supported? In such case you can bring
565 <a href="http://html.java.net">HTML for Java</a>
566 to your environment yourself. Just implement your own
567 {@link org.netbeans.html.boot.spi.Fn.Presenter}!
570 <h2>Other Resources</h2>
572 <img src="net/java/html/json/doc-files/DukeHTML.png" width="256" height="184" alt="Duke and HTML5. Together at last!" align="right"/>
574 The javadoc for latest and previous versions is also available
577 <li>Current <a target="_blank" href="http://bits.netbeans.org/html+java/dev/">development</a> version
578 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/1.2.3">1.2.3</a>
579 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/1.1">1.1</a>
580 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/1.0">1.0</a>
581 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.9">0.9</a>
582 and historic ones (<a target="_blank" href="http://bits.netbeans.org/html+java/0.8.3">0.8.3</a>,
583 <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.2">0.8.2</a>,
584 <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.1">0.8.1</a>,
585 <a target="_blank" href="http://bits.netbeans.org/html+java/0.8">0.8</a>, and
586 <a target="_blank" href="http://bits.netbeans.org/html+java/0.7.5">0.7.5</a>)