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 Been Improved in Version 1.2?</h3>
80 One can control {@link net.java.html.json.OnReceive#headers() HTTP request headers}
81 when connecting to server using the {@link net.java.html.json.OnReceive}
82 annotation. It is possible to have
83 {@link net.java.html.json.ComputedProperty#write() writable computed properties}.
84 Bugfix of issues <a target="_blank" href='https://netbeans.org/bugzilla/show_bug.cgi?id=250503'>250503</a>,
85 <a target="_blank" href='https://netbeans.org/bugzilla/show_bug.cgi?id=252987'>252987</a>.
87 <h3>What's New in Version 1.1?</h3>
90 The content of a {@link net.java.html.BrwsrCtx context}
91 can be selected by registering implementations under specific
92 {@link org.netbeans.html.context.spi.Contexts.Id technology identifiers}
93 and requesting them during
94 {@link org.netbeans.html.context.spi.Contexts#newBuilder(java.lang.Object...) construction}
95 of the context. <code>org.netbeans.html:ko4j</code> module's implementation
96 offers <b>ko4j</b>, <b>xhr</b> and <b>websocket</b> identifiers
97 for its registered services
98 (e.g. {@link org.netbeans.html.json.spi.Technology},
99 {@link org.netbeans.html.json.spi.Transfer} and
100 {@link org.netbeans.html.json.spi.WSTransfer}).
101 <code>org.netbeans.html:ko-ws-tyrus</code>
103 {@link org.netbeans.html.json.spi.Transfer Java based JSON} and
104 {@link org.netbeans.html.json.spi.WSTransfer WebSocket} implementations
105 under the name <b>tyrus</b>.
108 A particular DOM subtree
109 that a <a target="_blank" href="http://knockoutjs.com">knockout.js</a> model gets
110 applied to can be selected by using
111 {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)
112 Models.applyBindings(m, id)} with an id of an HTML element.
113 There is new {@link net.java.html.json.Model#targetId()} attribute
114 which controls behavior of the generated <code>applyBindings</code> method.
115 If <em>specified and non-empty</em>, then the generated method
116 will call {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)}
117 with <code>this</code> and the provided {@link net.java.html.json.Model#targetId() target id}.
118 If <em>specified, but left empty</em>, then the generated method
119 calls {@link net.java.html.json.Models#applyBindings(java.lang.Object)}.
120 <em>If unspecified</em>, the method will <b>not</b> be generated at all
121 (a change with respect to older versions). However one can
122 still use {@link net.java.html.json.Models#applyBindings(java.lang.Object)}
123 or {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)}
124 to perform the association of any model with the page element.
127 Memory model when using Knockout bindings has been improved
128 (required additions of two new methods:
129 {@link org.netbeans.html.json.spi.PropertyBinding#weak()} and
130 {@link org.netbeans.html.json.spi.FunctionBinding#weak()}) and
131 now the Java {@link net.java.html.json.Model models} can garbage collect,
132 when no longer used. Library writers that use
133 {@link net.java.html.js.JavaScriptBody} annotation can also
134 control garbage collection behavior of method arguments by
135 setting {@link net.java.html.js.JavaScriptBody#keepAlive() keepAlive=false}
139 <h3>What's New in Version 1.0?</h3>
142 {@link net.java.html.json.Property#array() Array properties} are now
143 mutable from the <a href="http://knockoutjs.com">knockout.js</a>
144 point of view (required {@link org.netbeans.html.json.spi.Proto.Type#replaceValue one SPI change}).
145 The page lookup mechanism can use {@link net.java.html.boot.BrowserBuilder#locale(java.util.Locale) locale}
146 to load localized a page with appropriate suffix.
147 All SPI were moved under the NetBeans namespace - e.g.
148 {@link org.netbeans.html.boot.spi},
149 {@link org.netbeans.html.context.spi},
150 {@link org.netbeans.html.json.spi},
151 {@link org.netbeans.html.sound.spi}, and also
152 {@link org.netbeans.html.json.tck}. Methods annotated
153 with {@link net.java.html.js.JavaScriptBody} annotation and
154 without fallback Java code now throw {@link java.lang.IllegalStateException}
155 with a message suggesting to switch to proper
156 {@link net.java.html.BrwsrCtx#execute browser context} to
157 prevent endless debugging when one forgets to do so.
161 What's new in older versions? Click the
162 <a href="#" onclick="return showHistoric(true)">link</a>
164 <a href="#" onclick="return showHistoric(true)">historic changes</a> below:
167 <a name="historic.changes"></a>
168 <div id="historic.changes">
170 function showHistoric(show) {
171 var e = document.getElementById("historic.changes");
173 e.style.display="block";
175 e.style.display="none";
182 <h3>What's New in Version 0.9?</h3>
185 System can run in {@link net.java.html.boot.BrowserBuilder#classloader(java.lang.ClassLoader) Felix OSGi container} (originally only Equinox).
186 {@link net.java.html.json.ComputedProperty Derived properties}
187 now deeply check changes in other {@link net.java.html.json.Model model
188 classes} they depend on and recompute their values accordingly.
189 <a target="_blank" href="http://knockoutjs.com">Knockout.js</a> library has been updated
193 <h3>What's New in 0.8.x Versions?</h3>
196 Setters or array properties on classes generated by {@link net.java.html.json.Model}
197 annotation can be accessed from any thread. {@link org.netbeans.html.sound.spi.AudioEnvironment}
198 can be registered into {@link net.java.html.BrwsrCtx}. There is
199 a {@link net.java.html.json.Models#parse(net.java.html.BrwsrCtx, java.lang.Class, java.io.InputStream, java.util.Collection) method}
200 to parse a JSON array and convert it into
201 {@link net.java.html.json.Model model classes}.
202 Improved behavior of <code>enum</code> values in
203 {@link net.java.html.json.Model knockout bindings}.
207 Few bugfixes for better portability.
208 New API for {@link net.java.html.boot.script.Scripts headless execution}
209 on top of <em>Nashorn</em> - does not run <em>knockout for Java</em>
211 (reported as <a href="https://bugs.openjdk.java.net/browse/JDK-8046013">JDK-8046013</a>),
212 however even in current state it is quite
213 {@link net.java.html.boot.script.Scripts useful for testing}
215 {@link net.java.html.js Java/JavaScript interactions}.
219 {@link net.java.html.boot.fx.FXBrowsers} has been extended
220 with new helper methods to make it easier to use HTML+Java
221 API in existing JavaFX applications.
222 The annotation processor is made
223 more robust with respect to errors in callback syntax of
224 {@link net.java.html.js.JavaScriptBody} body parameter.
225 Javadoc of {@link net.java.html.BrwsrCtx#execute} method
226 has been improved based on a failure of its usability study.
227 There can be additional parameters to methods annotated by
228 {@link net.java.html.json.OnReceive} that allows one to
229 pass state when a JSON call is made and use it when it finishes.
230 The mechanism of discovery of sibling HTML page has been
231 extended to work on systems that don't support
232 {@link java.lang.Class#getProtectionDomain}.
236 The first argument of method annotated by
237 {@link net.java.html.json.OnReceive} annotation has to
238 be the associated {@link net.java.html.json.Model model class}.
242 {@link net.java.html.json.OnReceive} annotation now accepts
243 {@link java.util.List} of data values as second argument
244 (previously required an array).
248 <h3>What's New in 0.7.x Versions?</h3>
251 {@link net.java.html.js.JavaScriptBody} annotation has new attribute
252 {@link net.java.html.js.JavaScriptBody#wait4js()} which allows
253 asynchronous execution. Libraries using
254 {@link net.java.html.js.JavaScriptBody} are urged to use this
255 new attribute as much as possible, as it can speed up execution
256 in certain environments.
260 Use {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable)} in
261 multi-threaded environment to execute your code on the browser thread.
263 {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable) using Java timer}.
267 <h3>Interesting Entry Points</h3>
269 <p>Learn how to {@link net.java.html.json.Model animate an HTML page from Java}
270 without referencing single HTML element from the Java code.
272 <p>Use {@link net.java.html.json.OnReceive JSON} to communicate
273 with REST based server API.
275 <p>Use <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>
278 <p>Call JavaScript methods from Java and vice versa, via
279 <a href="net/java/html/js/package-summary.html">JavaScriptBody</a>.
282 <h3>Getting Started</h3>
284 There are <a href="http://wiki.apidesign.org/wiki/DukeScriptInNetBeans">many ways</a>
286 <a href="http://html.java.net">Html for Java</a> application.
287 However to be sure one chooses the most recent setup, it is recommended
288 to switch to good old command line and use a
289 <a href="http://wiki.apidesign.org/wiki/Knockout4Java">Maven archetype</a>
290 associated with every version of this project. Make sure at least
291 <em>JDK7</em> is your installed Java and type:
293 $ mvn archetype:generate \
294 -DarchetypeGroupId=org.apidesign.html \
295 -DarchetypeArtifactId=knockout4j-archetype \
296 -DarchetypeVersion=0.8 <em># or newer version, if available</em>
298 Answer few questions (for example choose myfirstbrwsrpage as artifactId)
301 $ cd myfirstbrwsrpage
302 $ mvn process-classes exec:java
304 In a few seconds (or minutes if
305 <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
306 decides to download the whole Internet of dependencies) you should
307 see a sample Hello World application rendered in a
308 <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
309 web view component (that of course requires your JDK to come
310 with <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>;
311 <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK7
312 and JDK8 from Oracle</a> contain everything that is needed).
313 The generated application is built around one
314 Java source (uses the {@link net.java.html.json.Model} annotation to
315 auto-generate another <code>Data.java</code> class during compilation)
316 and one HTML file (uses the <a href="http://knockoutjs.com">Knockout</a>
317 syntax to <code>data-bind</code> the HTML elements to the
318 generated <code>Data</code> model):
320 $ ls src/main/java/**/DataModel.java
321 $ ls src/main/webapp/pages/index.html
323 That is all you need to get started. Play with the sources,
324 modify them and enjoy
325 <a href="http://html.java.net">Html for Java</a>!
330 This API is part of <a target="_blank"
331 href="http://netbeans.org">NetBeans.org</a> project and as such
332 it works naturally with the <a target="_blank"
333 href="https://netbeans.org/features/index.html">NetBeans IDE</a>.
334 On the other hand, the API is using nothing NetBeans specific,
335 it builds on standard Java6 APIs and as such it shall work fine
340 A lot of work is done by
341 <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">
342 annotation processors</a>
343 that generate various boiler plate code during compilation. This
344 is a standard part of Java since JDK6, but for example Eclipse
345 is known not to deal with processors well and developers using
346 it need to be careful. IntelliJ users hasn't reported any issues
347 and of course, NetBeans IDE support for
348 <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">processors</a>
353 When using {@link net.java.html.js.JavaScriptBody} annotation, it is
354 useful to do a bit of post processing of classes. There is a
355 <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
357 NetBeans IDE will invoke it when doing a build. Other IDEs may
358 need some hint to do so.
359 Anyway: If one does not see all (generated) sources or is getting
360 {@link java.lang.LinkageError}s when executing the application,
361 switch to command line and do clean build
364 <pre>$ mvn clean install</pre>
366 If that succeeds, your IDE of choice will hopefully
367 pick the generated sources up and present the result of the build
369 <a href="https://netbeans.org/downloads/">download NetBeans</a>,
370 you will be pleasantly
371 surprised - for example with our excellent
372 <a href="net/java/html/js/package-summary.html#debugging">Java/JavaScript
373 debugging</a> support.
377 <h2>Deploy Your Application</h2>
381 It is not goal of this documentation to list all possible ways
382 to package and deploy applications which use this API. However it is
383 important for new comers to see the benefits of using the
384 <a href="http://html.java.net">HTML for Java</a> API and as such
385 let's list at least few bundling options, known to work at the time of writing
390 First of all, this is a <em>client technology</em>. You write client applications
391 with it which may, but need not connect to a server. You don't need
392 Tomcat or WebLogic to deploy
393 <a href="http://html.java.net">HTML for Java</a> applications.
397 <img src='resources/javafx_logo.jpg' width="64"
398 height="64" align="left"/>
399 The sample project generated by
400 <code>org.apidesign.html knockout4j-archetype</code> is configured
401 to use <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
402 as the rendering technology. This setup is primarily suitable for
403 development - it needs no special packaging, starts quickly and
404 allows you to use classical HotSpot VM debuggers. A final
405 artifact from the build is also a ZIP file which you can use
406 and distribute to your users. Good for desktop applications.
410 <img src='resources/netbeans_logo.jpg' width="64"
411 height="64" align="right"/>
412 <img src='resources/eclipse_logo.png' width="64"
413 height="64" align="right"/>
414 All the <a href="http://html.java.net">HTML for Java</a> libraries
415 are packaged as <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
416 bundles and as such they can easily be run in NetBeans as well as
417 in Eclipse. As a result one can use
418 <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
419 and have a common module system for both platforms. In addition to that
421 HTML and have a common UI in both platforms. In such case
422 your application would be packaged as a set of
423 <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a> bundles.
425 <a href="http://wiki.apidesign.org/wiki/HTML">more</a>...
429 <img src='resources/chrome_logo.png' width="64"
430 height="64" align="left"/>
431 <img src='resources/safari_logo.png' width="64"
432 height="64" align="left"/>
433 <img src='resources/ie_logo.png' width="64"
434 height="64" align="left"/>
435 <img src='resources/firefox_logo.png' width="64"
436 height="64" align="left"/>
438 There is more and more attempts to execute Java bytecode
439 in a browser, without any special Java plugin installed.
440 The <a href="http://html.java.net">HTML for Java</a> is
441 carefully designed to produce lightweight, well performing
442 applications even on such restricted environments. It uses
443 no reflection calls and that allows to statically pre-compile
444 the applications into JavaScript. One of such environments
445 is called <a href="http://wiki.apidesign.org/wiki/Bck2Brwsr">Bck2Brwsr</a>,
446 another <a href="http://wiki.apidesign.org/wiki/TeaVM">TeaVM</a>. Both support the
447 {@link net.java.html.js.JavaScriptBody} annotation. Read
448 <a href="http://wiki.apidesign.org/wiki/Bck2BrwsrViaCLI">more</a> or play
449 a minesweeper game packaged for your browser
450 (of course <a target="_blank"
451 href="http://source.apidesign.org/hg/html~demo/file/ea79b73d590a/minesweeper/src/main/java/org/apidesign/demo/minesweeper/MinesModel.java">
452 written</a> in Java):
455 <script type="text/html" id="field">
456 <table class="field">
458 <!-- ko foreach: rows -->
460 <!-- ko foreach: columns -->
461 <td data-bind="css: style, click: $parents[1].click" >
462 <div data-bind='html: html'></div>
471 <div data-bind="template: { name : 'field', if: fieldShowing }"></div>
473 <!-- boot bck2brwsr -->
474 <script type="text/javascript" src="resources/teavm.js"></script>
477 vm.loadClass('org.apidesign.demo.minesweeper.MainBrwsr');
481 <img src='resources/ios_logo.jpg' width="64"
482 height="64" align="right"/>
483 <img src='resources/android_logo.jpg' width="64"
484 height="64" align="right"/>
486 Now when we have seen that the
487 <a href="http://html.java.net">HTML for Java</a> applications
488 can run on any modern browser, we can ask whether they can also
489 fit into a phone!? Yes, they can and especially to phones
490 that can execute Java code already! Just by changing your
491 packaging you can create an APK file and deploy it to your
493 Read <a target="_blank" href="http://wiki.apidesign.org/wiki/DlvkBrwsr">more</a>...
494 In case you'd like your application to reach out to second biggest
495 group of smartphone users, don't despair: It
496 seems the set of devices that can execute
497 <a href="http://html.java.net">HTML for Java</a> applications
498 has been extended to <em>iPads</em> and <em>iPhones</em>. Get the
499 <a target="_blank" href="http://wiki.apidesign.org/wiki/IBrwsr">details here</a>
500 and deploy everywhere!
503 Convinced it makes sense to use
504 <a href="http://html.java.net">HTML for Java</a>
505 APIs for writing applications that are
506 <em>written once, displayed anywhere</em>? Or do you have an
507 environment which is not supported? In such case you can bring
508 <a href="http://html.java.net">HTML for Java</a>
509 to your environment yourself. Just implement your own
510 {@link org.netbeans.html.boot.spi.Fn.Presenter}!
513 <h2>Other Resources</h2>
515 <img src="net/java/html/json/doc-files/DukeHTML.png" width="256" height="184" alt="Duke and HTML5. Together at last!" align="right"/>
517 The javadoc for latest and previous versions is also available
520 <li>Current <a target="_blank" href="http://bits.netbeans.org/html+java/dev/">development</a> version
521 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/1.1">1.1</a>
522 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/1.0">1.0</a>
523 <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.9">0.9</a>
524 and historic ones (<a target="_blank" href="http://bits.netbeans.org/html+java/0.8.3">0.8.3</a>,
525 <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.2">0.8.2</a>,
526 <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.1">0.8.1</a>,
527 <a target="_blank" href="http://bits.netbeans.org/html+java/0.8">0.8</a>, and
528 <a target="_blank" href="http://bits.netbeans.org/html+java/0.7.5">0.7.5</a>)
532 <style type="text/css">
538 border: 1px solid black;
540 table.field td.UNKNOWN {
541 background-color: #D6E4E1;
544 table.field td.EXPLOSION {
545 background-color: #A31E39;
547 table.field td.DISCOVERED {
548 background-color: #9DB2B1;