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">
54 Use Java to write application logic; Use HTML5 to render the UI;
55 {@link net.java.html.json.Model Animate an HTML page from Java}
56 (see <a target="_blank" href="http://dew.apidesign.org/dew/#7212206">Duke being rotated</a> by CSS);
57 Use {@link net.java.html.json.OnReceive REST} or
58 <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>;
59 interact with <a href="net/java/html/js/package-summary.html">JavaScript</a>;
60 Get the best of both worlds!
62 The goal of these APIs is to use full featured Java runtime
63 (like real <a href="http://wiki.apidesign.org/wiki/HotSpot">HotSpot VM</a>),
64 but still rely on a very lightweight rendering technology
65 (so it can potentially fit
66 <a href="http://bck2brwsr.apidesign.org">Bck2Brwsr</a> and definitely
67 to various types of phones). What can be more lightweight
68 (from a browser perspective) than
69 <a href="http://wiki.apidesign.org/wiki/HTML">HTML</a>!?
70 By default we use {@link net.java.html.boot.fx JavaFX's WebView}
71 component to display the <a href="http://wiki.apidesign.org/wiki/HTML">HTML</a>.
72 We eliminate the need to manipulate the DOM directly,
73 there is a special {@link net.java.html.json Java to Knockout.js binding}.
74 As a result the <a href="http://knockoutjs.com">HTML uses Knockout.js syntax</a>,
75 yet the application code can be written in Java.
78 <h3>What's New in Version 1.1?</h3>
81 The content of a {@link net.java.html.BrwsrCtx context}
82 can be selected by registering implementations under specific
83 {@link org.netbeans.html.context.spi.Contexts.Id technology identifiers}
84 and requesting them during
85 {@link org.netbeans.html.context.spi.Contexts#newBuilder(java.lang.Object...) construction}
86 of the context. <code>org.netbeans.html:ko4j</code> module's implementation
87 offers <b>ko4j</b>, <b>xhr</b> and <b>websocket</b> identifiers
88 for its registered services
89 (e.g. {@link org.netbeans.html.json.spi.Technology},
90 {@link org.netbeans.html.json.spi.Transfer} and
91 {@link org.netbeans.html.json.spi.WSTransfer}).
92 <code>org.netbeans.html:ko-ws-tyrus</code>
94 {@link org.netbeans.html.json.spi.Transfer Java based JSON} and
95 {@link org.netbeans.html.json.spi.WSTransfer WebSocket} implementations
96 under the name <b>tyrus</b>.
99 <h3>What's New in Version 1.0?</h3>
102 {@link net.java.html.json.Property#array() Array properties} are now
103 mutable from the <a href="http://knockoutjs.com">knockout.js</a>
104 point of view (required {@link org.netbeans.html.json.spi.Proto.Type#replaceValue one SPI change}).
105 The page lookup mechanism can use {@link net.java.html.boot.BrowserBuilder#locale(java.util.Locale) locale}
106 to load localized a page with appropriate suffix.
107 All SPI were moved under the NetBeans namespace - e.g.
108 {@link org.netbeans.html.boot.spi},
109 {@link org.netbeans.html.context.spi},
110 {@link org.netbeans.html.json.spi},
111 {@link org.netbeans.html.sound.spi}, and also
112 {@link org.netbeans.html.json.tck}. Methods annotated
113 with {@link net.java.html.js.JavaScriptBody} annotation and
114 without fallback Java code now throw {@link java.lang.IllegalStateException}
115 with a message suggesting to switch to proper
116 {@link net.java.html.BrwsrCtx#execute browser context} to
117 prevent endless debugging when one forgets to do so.
121 What's new in older versions? Click the
122 <a href="#" onclick="return showHistoric(true)">link</a>
124 <a href="#" onclick="return showHistoric(true)">historic changes</a> below:
127 <a name="historic.changes"></a>
128 <div id="historic.changes">
130 function showHistoric(show) {
131 var e = document.getElementById("historic.changes");
133 e.style.display="block";
135 e.style.display="none";
142 <h3>What's New in Version 0.9?</h3>
145 System can run in {@link net.java.html.boot.BrowserBuilder#classloader(java.lang.ClassLoader) Felix OSGi container} (originally only Equinox).
146 {@link net.java.html.json.ComputedProperty Derived properties}
147 now deeply check changes in other {@link net.java.html.json.Model model
148 classes} they depend on and recompute their values accordingly.
149 <a target="_blank" href="http://knockoutjs.com">Knockout.js</a> library has been updated
153 <h3>What's New in 0.8.x Versions?</h3>
156 Setters or array properties on classes generated by {@link net.java.html.json.Model}
157 annotation can be accessed from any thread. {@link org.netbeans.html.sound.spi.AudioEnvironment}
158 can be registered into {@link net.java.html.BrwsrCtx}. There is
159 a {@link net.java.html.json.Models#parse(net.java.html.BrwsrCtx, java.lang.Class, java.io.InputStream, java.util.Collection) method}
160 to parse a JSON array and convert it into
161 {@link net.java.html.json.Model model classes}.
162 Improved behavior of <code>enum</code> values in
163 {@link net.java.html.json.Model knockout bindings}.
167 Few bugfixes for better portability.
168 New API for {@link net.java.html.boot.script.Scripts headless execution}
169 on top of <em>Nashorn</em> - does not run <em>knockout for Java</em>
171 (reported as <a href="https://bugs.openjdk.java.net/browse/JDK-8046013">JDK-8046013</a>),
172 however even in current state it is quite
173 {@link net.java.html.boot.script.Scripts useful for testing}
175 {@link net.java.html.js Java/JavaScript interactions}.
179 {@link net.java.html.boot.fx.FXBrowsers} has been extended
180 with new helper methods to make it easier to use HTML+Java
181 API in existing JavaFX applications.
182 The annotation processor is made
183 more robust with respect to errors in callback syntax of
184 {@link net.java.html.js.JavaScriptBody} body parameter.
185 Javadoc of {@link net.java.html.BrwsrCtx#execute} method
186 has been improved based on a failure of its usability study.
187 There can be additional parameters to methods annotated by
188 {@link net.java.html.json.OnReceive} that allows one to
189 pass state when a JSON call is made and use it when it finishes.
190 The mechanism of discovery of sibling HTML page has been
191 extended to work on systems that don't support
192 {@link java.lang.Class#getProtectionDomain}.
196 The first argument of method annotated by
197 {@link net.java.html.json.OnReceive} annotation has to
198 be the associated {@link net.java.html.json.Model model class}.
202 {@link net.java.html.json.OnReceive} annotation now accepts
203 {@link java.util.List} of data values as second argument
204 (previously required an array).
208 <h3>What's New in 0.7.x Versions?</h3>
211 {@link net.java.html.js.JavaScriptBody} annotation has new attribute
212 {@link net.java.html.js.JavaScriptBody#wait4js()} which allows
213 asynchronous execution. Libraries using
214 {@link net.java.html.js.JavaScriptBody} are urged to use this
215 new attribute as much as possible, as it can speed up execution
216 in certain environments.
220 Use {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable)} in
221 multi-threaded environment to execute your code on the browser thread.
223 {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable) using Java timer}.
227 <h3>Interesting Entry Points</h3>
229 <p>Learn how to {@link net.java.html.json.Model animate an HTML page from Java}
230 without referencing single HTML element from the Java code.
232 <p>Use {@link net.java.html.json.OnReceive JSON} to communicate
233 with REST based server API.
235 <p>Use <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>
238 <p>Call JavaScript methods from Java and vice versa, via
239 <a href="net/java/html/js/package-summary.html">JavaScriptBody</a>.
242 <h3>Getting Started</h3>
244 There are <a href="http://wiki.apidesign.org/wiki/DukeScriptInNetBeans">many ways</a>
246 <a href="http://html.java.net">Html for Java</a> application.
247 However to be sure one chooses the most recent setup, it is recommended
248 to switch to good old command line and use a
249 <a href="http://wiki.apidesign.org/wiki/Knockout4Java">Maven archetype</a>
250 associated with every version of this project. Make sure at least
251 <em>JDK7</em> is your installed Java and type:
253 $ mvn archetype:generate \
254 -DarchetypeGroupId=org.apidesign.html \
255 -DarchetypeArtifactId=knockout4j-archetype \
256 -DarchetypeVersion=0.8 <em># or newer version, if available</em>
258 Answer few questions (for example choose myfirstbrwsrpage as artifactId)
261 $ cd myfirstbrwsrpage
262 $ mvn process-classes exec:java
264 In a few seconds (or minutes if
265 <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
266 decides to download the whole Internet of dependencies) you should
267 see a sample Hello World application rendered in a
268 <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
269 web view component (that of course requires your JDK to come
270 with <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>;
271 <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK7
272 and JDK8 from Oracle</a> contain everything that is needed).
273 The generated application is built around one
274 Java source (uses the {@link net.java.html.json.Model} annotation to
275 auto-generate another <code>Data.java</code> class during compilation)
276 and one HTML file (uses the <a href="http://knockoutjs.com">Knockout</a>
277 syntax to <code>data-bind</code> the HTML elements to the
278 generated <code>Data</code> model):
280 $ ls src/main/java/**/DataModel.java
281 $ ls src/main/webapp/pages/index.html
283 That is all you need to get started. Play with the sources,
284 modify them and enjoy
285 <a href="http://html.java.net">Html for Java</a>!
290 This API is part of <a target="_blank"
291 href="http://netbeans.org">NetBeans.org</a> project and as such
292 it works naturally with the <a target="_blank"
293 href="https://netbeans.org/features/index.html">NetBeans IDE</a>.
294 On the other hand, the API is using nothing NetBeans specific,
295 it builds on standard Java6 APIs and as such it shall work fine
300 A lot of work is done by
301 <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">
302 annotation processors</a>
303 that generate various boiler plate code during compilation. This
304 is a standard part of Java since JDK6, but for example Eclipse
305 is known not to deal with processors well and developers using
306 it need to be careful. IntelliJ users hasn't reported any issues
307 and of course, NetBeans IDE support for
308 <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">processors</a>
313 When using {@link net.java.html.js.JavaScriptBody} annotation, it is
314 useful to do a bit of post processing of classes. There is a
315 <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
317 NetBeans IDE will invoke it when doing a build. Other IDEs may
318 need some hint to do so.
319 Anyway: If one does not see all (generated) sources or is getting
320 {@link java.lang.LinkageError}s when executing the application,
321 switch to command line and do clean build
324 <pre>$ mvn clean install</pre>
326 If that succeeds, your IDE of choice will hopefully
327 pick the generated sources up and present the result of the build
329 <a href="https://netbeans.org/downloads/">download NetBeans</a>,
330 you will be pleasantly
331 surprised - for example with our excellent
332 <a href="net/java/html/js/package-summary.html#debugging">Java/JavaScript
333 debugging</a> support.
337 <h2>Deploy Your Application</h2>
341 It is not goal of this documentation to list all possible ways
342 to package and deploy applications which use this API. However it is
343 important for new comers to see the benefits of using the
344 <a href="http://html.java.net">HTML for Java</a> API and as such
345 let's list at least few bundling options, known to work at the time of writing
350 First of all, this is a <em>client technology</em>. You write client applications
351 with it which may, but need not connect to a server. You don't need
352 Tomcat or WebLogic to deploy
353 <a href="http://html.java.net">HTML for Java</a> applications.
357 <img src='resources/javafx_logo.jpg' width="64"
358 height="64" align="left"/>
359 The sample project generated by
360 <code>org.apidesign.html knockout4j-archetype</code> is configured
361 to use <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
362 as the rendering technology. This setup is primarily suitable for
363 development - it needs no special packaging, starts quickly and
364 allows you to use classical HotSpot VM debuggers. A final
365 artifact from the build is also a ZIP file which you can use
366 and distribute to your users. Good for desktop applications.
370 <img src='resources/netbeans_logo.jpg' width="64"
371 height="64" align="right"/>
372 <img src='resources/eclipse_logo.png' width="64"
373 height="64" align="right"/>
374 All the <a href="http://html.java.net">HTML for Java</a> libraries
375 are packaged as <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
376 bundles and as such they can easily be run in NetBeans as well as
377 in Eclipse. As a result one can use
378 <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
379 and have a common module system for both platforms. In addition to that
381 HTML and have a common UI in both platforms. In such case
382 your application would be packaged as a set of
383 <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a> bundles.
385 <a href="http://wiki.apidesign.org/wiki/HTML">more</a>...
389 <img src='resources/chrome_logo.png' width="64"
390 height="64" align="left"/>
391 <img src='resources/safari_logo.png' width="64"
392 height="64" align="left"/>
393 <img src='resources/ie_logo.png' width="64"
394 height="64" align="left"/>
395 <img src='resources/firefox_logo.png' width="64"
396 height="64" align="left"/>
398 There is more and more attempts to execute Java bytecode
399 in a browser, without any special Java plugin installed.
400 The <a href="http://html.java.net">HTML for Java</a> is
401 carefully designed to produce lightweight, well performing
402 applications even on such restricted environments. It uses
403 no reflection calls and that allows to statically pre-compile
404 the applications into JavaScript. One of such environments
405 is called <a href="http://wiki.apidesign.org/wiki/Bck2Brwsr">Bck2Brwsr</a>,
406 another <a href="http://wiki.apidesign.org/wiki/TeaVM">TeaVM</a>. Both support the
407 {@link net.java.html.js.JavaScriptBody} annotation. Read
408 <a href="http://wiki.apidesign.org/wiki/Bck2BrwsrViaCLI">more</a> or play
409 a minesweeper game packaged for your browser
410 (of course <a target="_blank"
411 href="http://source.apidesign.org/hg/html~demo/file/ea79b73d590a/minesweeper/src/main/java/org/apidesign/demo/minesweeper/MinesModel.java">
412 written</a> in Java):
415 <script type="text/html" id="field">
416 <table class="field">
418 <!-- ko foreach: rows -->
420 <!-- ko foreach: columns -->
421 <td data-bind="css: style, click: $parents[1].click" >
422 <div data-bind='html: html'></div>
431 <div data-bind="template: { name : 'field', if: fieldShowing }"></div>
433 <!-- boot bck2brwsr -->
434 <script type="text/javascript" src="resources/teavm.js"></script>
437 vm.loadClass('org.apidesign.demo.minesweeper.MainBrwsr');
441 <img src='resources/ios_logo.jpg' width="64"
442 height="64" align="right"/>
443 <img src='resources/android_logo.jpg' width="64"
444 height="64" align="right"/>
446 Now when we have seen that the
447 <a href="http://html.java.net">HTML for Java</a> applications
448 can run on any modern browser, we can ask whether they can also
449 fit into a phone!? Yes, they can and especially to phones
450 that can execute Java code already! Just by changing your
451 packaging you can create an APK file and deploy it to your
453 Read <a target="_blank" href="http://wiki.apidesign.org/wiki/DlvkBrwsr">more</a>...
454 In case you'd like your application to reach out to second biggest
455 group of smartphone users, don't despair: It
456 seems the set of devices that can execute
457 <a href="http://html.java.net">HTML for Java</a> applications
458 has been extended to <em>iPads</em> and <em>iPhones</em>. Get the
459 <a target="_blank" href="http://wiki.apidesign.org/wiki/IBrwsr">details here</a>
460 and deploy everywhere!
463 Convinced it makes sense to use
464 <a href="http://html.java.net">HTML for Java</a>
465 APIs for writing applications that are
466 <em>written once, displayed anywhere</em>? Or do you have an
467 environment which is not supported? In such case you can bring
468 <a href="http://html.java.net">HTML for Java</a>
469 to your environment yourself. Just implement your own
470 {@link org.netbeans.html.boot.spi.Fn.Presenter}!
473 <h2>Other Resources</h2>
475 <img src="net/java/html/json/doc-files/DukeHTML.png" width="256" height="184" alt="Duke and HTML5. Together at last!" align="right"/>
477 The javadoc for latest and previous versions is also available
480 <li>Current <a target="_blank" href="http://bits.netbeans.org/html+java/dev/">development</a> version
481 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.3">0.8.3</a>
482 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.2">0.8.2</a>
483 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.1">0.8.1</a>
484 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.8">0.8</a>
485 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.7.5">0.7.5</a>
488 <style type="text/css">
494 border: 1px solid black;
496 table.field td.UNKNOWN {
497 background-color: #D6E4E1;
500 table.field td.EXPLOSION {
501 background-color: #A31E39;
503 table.field td.DISCOVERED {
504 background-color: #9DB2B1;