hg/html~html4j: src/main/javadoc/overview.html@bdc3d696dd4a

     1 <!--

     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]"

    28     Contributor(s):

    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.

    44 -->

    45 <!DOCTYPE html>

    46 <html>

    47     <head>

    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     </head>

    52     <body>

    53         <p>

    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.

    76         </p>

    78         <h3>What's New in Version 1.0?</h3>

    80         <p>

    81             {@link net.java.html.json.Property#array() Array properties} are now

    82             mutable from the <a href="http://knockoutjs.com">knockout.js</a>

    83             point of view (required {@link org.netbeans.html.json.spi.Proto.Type#replaceValue one SPI change}).

    84             The page lookup mechanism can use {@link net.java.html.boot.BrowserBuilder#locale(java.util.Locale) locale}

    85             to load localized a page with appropriate suffix.

    86         </p>

    88         <h3>What's New in Version 0.9?</h3>

    90         <p>

    91             System can run in {@link net.java.html.boot.BrowserBuilder#classloader(java.lang.ClassLoader) Felix OSGi container} (originally only Equinox).

    92             {@link net.java.html.json.ComputedProperty Derived properties}

    93             now deeply check changes in other {@link net.java.html.json.Model model

    94             classes} they depend on and recompute their values accordingly.

    95             <a target="_blank" href="http://knockoutjs.com">Knockout.js</a> library has been updated

    96             to version 3.2.0.

    97         </p>

    99         <h3>What's New in 0.8.x Versions?</h3>

   101         <p>

   102             Setters or array properties on classes generated by {@link net.java.html.json.Model}

   103             annotation can be accessed from any thread. {@link org.netbeans.html.sound.spi.AudioEnvironment}

   104             can be registered into {@link net.java.html.BrwsrCtx}. There is

   105             a {@link net.java.html.json.Models#parse(net.java.html.BrwsrCtx, java.lang.Class, java.io.InputStream, java.util.Collection)  method}

   106             to parse a JSON array and convert it into

   107             {@link net.java.html.json.Model model classes}.

   108             Improved behavior of <code>enum</code> values in

   109             {@link net.java.html.json.Model knockout bindings}.

   110         </p>

   112         <p>

   113             Few bugfixes for better portability.

   114             New API for {@link net.java.html.boot.script.Scripts headless execution}

   115             on top of <em>Nashorn</em> - does not run <em>knockout for Java</em>

   116             fully yet

   117             (reported as <a href="https://bugs.openjdk.java.net/browse/JDK-8046013">JDK-8046013</a>),

   118             however even in current state it is quite

   119             {@link net.java.html.boot.script.Scripts useful for testing}

   120             of

   121             {@link net.java.html.js Java/JavaScript interactions}.

   122         </p>

   124         <p>

   125             {@link net.java.html.boot.fx.FXBrowsers} has been extended

   126             with new helper methods to make it easier to use HTML+Java

   127             API in existing JavaFX applications.

   128             The annotation processor is made

   129             more robust with respect to errors in callback syntax of

   130             {@link net.java.html.js.JavaScriptBody} body parameter.

   131             Javadoc of {@link net.java.html.BrwsrCtx#execute} method

   132             has been improved based on a failure of its usability study.

   133             There can be additional parameters to methods annotated by

   134             {@link net.java.html.json.OnReceive} that allows one to

   135             pass state when a JSON call is made and use it when it finishes.

   136             The mechanism of discovery of sibling HTML page has been

   137             extended to work on systems that don't support

   138             {@link java.lang.Class#getProtectionDomain}.

   139         </p>

   141         <p>

   142             The first argument of method annotated by

   143             {@link net.java.html.json.OnReceive} annotation has to

   144             be the associated {@link net.java.html.json.Model model class}.

   145         </p>

   147         <p>

   148             {@link net.java.html.json.OnReceive} annotation now accepts

   149             {@link java.util.List} of data values as second argument

   150             (previously required an array).

   151         </p>

   154         <h3>What's New in Older Versions?</h3>

   156         <p>

   157             {@link net.java.html.js.JavaScriptBody} annotation has new attribute

   158             {@link net.java.html.js.JavaScriptBody#wait4js()} which allows

   159             asynchronous execution. Libraries using

   160             {@link net.java.html.js.JavaScriptBody} are urged to use this

   161             new attribute as much as possible, as it can speed up execution

   162             in certain environments.

   163         </p>

   165         <p>

   166             Use {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable)} in

   167             multi-threaded environment to execute your code on the browser thread.

   168             See example

   169             {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable) using Java timer}.

   170         </p>

   172         <h3>Interesting Entry Points</h3>

   174         <p>Learn how to {@link net.java.html.json.Model animate an HTML page from Java}

   175             without referencing single HTML element from the Java code.

   176         </p>

   177         <p>Use {@link net.java.html.json.OnReceive JSON} to communicate

   178             with REST based server API.

   179         </p>

   180         <p>Use <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>

   181             and JSON.

   182         </p>

   183         <p>Call JavaScript methods from Java and vice versa, via

   184             <a href="net/java/html/js/package-summary.html">JavaScriptBody</a>.

   185         </p>

   187         <h3>Getting Started</h3>

   189         There are <a href="http://wiki.apidesign.org/wiki/DukeScriptInNetBeans">many ways</a>

   190         to start developing

   191         <a href="http://html.java.net">Html for Java</a> application.

   192         However to be sure one chooses the most recent setup, it is recommended

   193         to switch to good old command line and use a

   194         <a href="http://wiki.apidesign.org/wiki/Knockout4Java">Maven archetype</a>

   195         associated with every version of this project. Make sure at least

   196         <em>JDK7</em> is your installed Java and type:

   197         <pre>

   198 $ mvn archetype:generate \

   199  -DarchetypeGroupId=org.apidesign.html \

   200  -DarchetypeArtifactId=knockout4j-archetype \

   201  -DarchetypeVersion=0.8 <em># or newer version, if available</em>

   202         </pre>

   203         Answer few questions (for example choose myfirstbrwsrpage as artifactId)

   204         and then you can:

   205         <pre>

   206 $ cd myfirstbrwsrpage

   207 $ mvn process-classes exec:java

   208         </pre>

   209         In a few seconds (or minutes if

   210         <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>

   211         decides to download the whole Internet of dependencies) you should

   212         see a sample Hello World application rendered in a

   213         <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>

   214         web view component (that of course requires your JDK to come

   215         with <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>;

   216         <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK7

   217             and JDK8 from Oracle</a> contain everything that is needed).

   218         The generated application is built around one

   219         Java source (uses the {@link net.java.html.json.Model} annotation to

   220         auto-generate another <code>Data.java</code> class during compilation)

   221         and one HTML file (uses the <a href="http://knockoutjs.com">Knockout</a>

   222         syntax to <code>data-bind</code> the HTML elements to the

   223         generated <code>Data</code> model):

   224         <pre>

   225 $ ls src/main/java/**/DataModel.java

   226 $ ls src/main/webapp/pages/index.html

   227         </pre>

   228         That is all you need to get started. Play with the sources,

   229         modify them and enjoy

   230         <a href="http://html.java.net">Html for Java</a>!

   232         <h2>IDE Support</h2>

   234         <p>

   235             This API is part of <a target="_blank"

   236             href="http://netbeans.org">NetBeans.org</a> project and as such

   237             it works naturally with the <a target="_blank"

   238             href="https://netbeans.org/features/index.html">NetBeans IDE</a>.

   239             On the other hand, the API is using nothing NetBeans specific,

   240             it builds on standard Java6 APIs and as such it shall work fine

   241             in any IDE.

   242         </p>

   244         <p>

   245             A lot of work is done by

   246             <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">

   247             annotation processors</a>

   248             that generate various boiler plate code during compilation. This

   249             is a standard part of Java since JDK6, but for example Eclipse

   250             is known not to deal with processors well and developers using

   251             it need to be careful. IntelliJ users hasn't reported any issues

   252             and of course, NetBeans IDE support for

   253             <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">processors</a>

   254             is outstanding.

   255         </p>

   257         <p>

   258             When using {@link net.java.html.js.JavaScriptBody} annotation, it is

   259             useful to do a bit of post processing of classes. There is a

   260             <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>

   261             plugin for that.

   262             NetBeans IDE will invoke it when doing a build. Other IDEs may

   263             need some hint to do so.

   264             Anyway: If one does not see all (generated) sources or is getting

   265             {@link java.lang.LinkageError}s when executing the application,

   266             switch to command line and do clean build

   267             from there:

   268         </p>

   269         <pre>$ mvn clean install</pre>

   270         <p>

   271             If that succeeds, your IDE of choice will hopefully

   272             pick the generated sources up and present the result of the build

   273             properly. If not,

   274             <a href="https://netbeans.org/downloads/">download NetBeans</a>,

   275             you will be pleasantly

   276             surprised - for example with our excellent

   277             <a href="net/java/html/js/package-summary.html#debugging">Java/JavaScript

   278             debugging</a> support.

   279         </p>

   281         <a name="deploy">

   282         <h2>Deploy Your Application</h2>

   283         </a>

   285         <p>

   286         It is not goal of this documentation to list all possible ways

   287         to package and deploy applications which use this API. However it is

   288         important for new comers to see the benefits of using the

   289         <a href="http://html.java.net">HTML for Java</a> API and as such

   290         let's list at least few bundling options, known to work at the time of writing

   291         this documentation.

   292         </p>

   294         <p>

   295         First of all, this is a <em>client technology</em>. You write client applications

   296         with it which may, but need not connect to a server. You don't need

   297         Tomcat or WebLogic to deploy

   298         <a href="http://html.java.net">HTML for Java</a> applications.

   299         </p>

   301         <p>

   302             <img src='resources/javafx_logo.jpg' width="64"

   303                  height="64" align="left"/>

   304             The sample project generated by

   305             <code>org.apidesign.html knockout4j-archetype</code> is configured

   306             to use <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>

   307             as the rendering technology. This setup is primarily suitable for

   308             development - it needs no special packaging, starts quickly and

   309             allows you to use classical HotSpot VM debuggers. A final

   310             artifact from the build is also a ZIP file which you can use

   311             and distribute to your users. Good for desktop applications.

   312         </p>

   314         <p>

   315             <img src='resources/netbeans_logo.jpg' width="64"

   316                  height="64" align="right"/>

   317             <img src='resources/eclipse_logo.png' width="64"

   318                  height="64" align="right"/>

   319             All the <a href="http://html.java.net">HTML for Java</a> libraries

   320             are packaged as <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>

   321             bundles and as such they can easily be run in NetBeans as well as

   322             in Eclipse. As a result one can use

   323             <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>

   324             and have a common module system for both platforms. In addition to that

   325             one can render using

   326             HTML and have a common UI in both platforms. In such case

   327             your application would be packaged as a set of

   328             <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a> bundles.

   329             Read

   330             <a href="http://wiki.apidesign.org/wiki/HTML">more</a>...

   331         </p>

   333         <p>

   334             <img src='resources/chrome_logo.png' width="64"

   335                  height="64" align="left"/>

   336             <img src='resources/safari_logo.png' width="64"

   337                  height="64" align="left"/>

   338             <img src='resources/ie_logo.png' width="64"

   339                  height="64" align="left"/>

   340             <img src='resources/firefox_logo.png' width="64"

   341                  height="64" align="left"/>

   343             There is more and more attempts to execute Java bytecode

   344             in a browser, without any special Java plugin installed.

   345             The <a href="http://html.java.net">HTML for Java</a> is

   346             carefully designed to produce lightweight, well performing

   347             applications even on such restricted environments. It uses

   348             no reflection calls and that allows to statically pre-compile

   349             the applications into JavaScript. One of such environments

   350             is called <a href="http://wiki.apidesign.org/wiki/Bck2Brwsr">Bck2Brwsr</a>,

   351             another <a href="http://wiki.apidesign.org/wiki/TeaVM">TeaVM</a>. Both support the

   352             {@link net.java.html.js.JavaScriptBody} annotation. Read

   353             <a href="http://wiki.apidesign.org/wiki/Bck2BrwsrViaCLI">more</a> or play

   354             a minesweeper game packaged for your browser

   355             (of course <a target="_blank"

   356                 href="http://source.apidesign.org/hg/html~demo/file/ea79b73d590a/minesweeper/src/main/java/org/apidesign/demo/minesweeper/MinesModel.java">

   357                 written</a> in Java):

   358         </p>

   360         <script type="text/html" id="field">

   361             <table class="field">

   362                 <tbody>

   363                     <!-- ko foreach: rows -->

   364                     <tr>

   365                         <!-- ko foreach: columns -->

   366                         <td data-bind="css: style, click: $parents[1].click" >

   367                             <div data-bind='html: html'></div>

   368                         </td>

   369                         <!-- /ko -->

   370                     </tr>

   371                     <!-- /ko -->

   372                 </tbody>

   373             </table>

   374         </script>

   376         <div data-bind="template: { name : 'field', if: fieldShowing }"></div>

   378         <!-- boot bck2brwsr -->

   379         <script type="text/javascript" src="resources/teavm.js"></script>

   380         <script>

   381             var vm = new VM();

   382             vm.loadClass('org.apidesign.demo.minesweeper.MainBrwsr');

   383         </script>

   385         <p>

   386             <img src='resources/ios_logo.jpg' width="64"

   387                  height="64" align="right"/>

   388             <img src='resources/android_logo.jpg' width="64"

   389                  height="64" align="right"/>

   391             Now when we have seen that the

   392             <a href="http://html.java.net">HTML for Java</a> applications

   393             can run on any modern browser, we can ask whether they can also

   394             fit into a phone!? Yes, they can and especially to phones

   395             that can execute Java code already! Just by changing your

   396             packaging you can create an APK file and deploy it to your

   397             Android phone.

   398             Read <a target="_blank" href="http://wiki.apidesign.org/wiki/DlvkBrwsr">more</a>...

   399             In case you'd like your application to reach out to second biggest

   400             group of smartphone users, don't despair: It

   401             seems the set of devices that can execute

   402             <a href="http://html.java.net">HTML for Java</a> applications

   403             has been extended to <em>iPads</em> and <em>iPhones</em>. Get the

   404             <a target="_blank" href="http://wiki.apidesign.org/wiki/IBrwsr">details here</a>

   405             and deploy everywhere!

   406         </p>

   407         <p>

   408             Convinced it makes sense to use

   409             <a href="http://html.java.net">HTML for Java</a>

   410             APIs for writing applications that are

   411             <em>written once, displayed anywhere</em>? Or do you have an

   412             environment which is not supported? In such case you can bring

   413             <a href="http://html.java.net">HTML for Java</a>

   414             to your environment yourself. Just implement your own

   415             {@link org.netbeans.html.boot.spi.Fn.Presenter}!

   416         </p>

   418         <h2>Other Resources</h2>

   420         <img src="net/java/html/json/doc-files/DukeHTML.png" width="256" height="184" alt="Duke and HTML5. Together at last!" align="right"/>

   422         The javadoc for latest and previous versions is also available

   423         online:

   424         <ul>

   425             <li>Current <a target="_blank" href="http://bits.netbeans.org/html+java/dev/">development</a> version

   426             <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.3">0.8.3</a>

   427             <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.2">0.8.2</a>

   428             <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.1">0.8.1</a>

   429             <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.8">0.8</a>

   430             <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.7.5">0.7.5</a>

   431         </ul>

   433 <style type="text/css">

   434 table.field td {

   435     padding: 4px;

   436     width: 18px;

   437     height: 18px;

   438     font-size: 1.5em;

   439     border: 1px solid black;

   440 }

   441 table.field td.UNKNOWN {

   442     background-color: #D6E4E1;

   443     cursor: pointer;

   444 }

   445 table.field td.EXPLOSION {

   446     background-color: #A31E39;

   447 }

   448 table.field td.DISCOVERED {

   449     background-color: #9DB2B1;

   450 }

   451 </style>

   452     </body>

   453 </html>

author	Jaroslav Tulach <jtulach@netbeans.org>
	Tue, 26 Aug 2014 18:13:30 +0200
changeset 838	bdc3d696dd4a
parent 834	5b6567dcc966
child 841	e673fd71b81b
permissions	-rw-r--r--