src/main/javadoc/overview.html
author Jaroslav Tulach <jaroslav.tulach@netbeans.org>
Wed, 26 Mar 2014 18:28:26 +0100
changeset 630 c7eaca4ac999
parent 625 7716002b1875
child 639 b4b0758904e2
permissions -rw-r--r--
Giving Ivar's demo more priviledged place in the documentation
jaroslav@550
     1
<!--
jaroslav@550
     2
jaroslav@550
     3
    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
jaroslav@550
     4
jaroslav@551
     5
    Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.
jaroslav@550
     6
jaroslav@550
     7
    Oracle and Java are registered trademarks of Oracle and/or its affiliates.
jaroslav@550
     8
    Other names may be trademarks of their respective owners.
jaroslav@550
     9
jaroslav@550
    10
    The contents of this file are subject to the terms of either the GNU
jaroslav@550
    11
    General Public License Version 2 only ("GPL") or the Common
jaroslav@550
    12
    Development and Distribution License("CDDL") (collectively, the
jaroslav@550
    13
    "License"). You may not use this file except in compliance with the
jaroslav@550
    14
    License. You can obtain a copy of the License at
jaroslav@550
    15
    http://www.netbeans.org/cddl-gplv2.html
jaroslav@550
    16
    or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
jaroslav@550
    17
    specific language governing permissions and limitations under the
jaroslav@550
    18
    License.  When distributing the software, include this License Header
jaroslav@550
    19
    Notice in each file and include the License file at
jaroslav@550
    20
    nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this
jaroslav@550
    21
    particular file as subject to the "Classpath" exception as provided
jaroslav@550
    22
    by Oracle in the GPL Version 2 section of the License file that
jaroslav@550
    23
    accompanied this code. If applicable, add the following below the
jaroslav@550
    24
    License Header, with the fields enclosed by brackets [] replaced by
jaroslav@550
    25
    your own identifying information:
jaroslav@550
    26
    "Portions Copyrighted [year] [name of copyright owner]"
jaroslav@550
    27
jaroslav@550
    28
    Contributor(s):
jaroslav@550
    29
jaroslav@550
    30
    The Original Software is NetBeans. The Initial Developer of the Original
jaroslav@551
    31
    Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.
jaroslav@550
    32
jaroslav@550
    33
    If you wish your version of this file to be governed by only the CDDL
jaroslav@550
    34
    or only the GPL Version 2, indicate your decision by adding
jaroslav@550
    35
    "[Contributor] elects to include this software in this distribution
jaroslav@550
    36
    under the [CDDL or GPL Version 2] license." If you do not indicate a
jaroslav@550
    37
    single choice of license, a recipient has the option to distribute
jaroslav@550
    38
    your version of this file under either the CDDL, the GPL Version 2 or
jaroslav@550
    39
    to extend the choice of license to its licensees as provided above.
jaroslav@550
    40
    However, if you add GPL Version 2 code and therefore, elected the GPL
jaroslav@550
    41
    Version 2 license, then the option applies only if the new code is
jaroslav@550
    42
    made subject to such option by the copyright holder.
jaroslav@550
    43
jaroslav@550
    44
-->
jaroslav@541
    45
<!DOCTYPE html>
jaroslav@541
    46
<html>
jaroslav@541
    47
    <head>
jaroslav@541
    48
        <title>HTML for Java APIs</title>
jaroslav@541
    49
        <meta charset="UTF-8">
jaroslav@541
    50
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
jaroslav@541
    51
    </head>
jaroslav@541
    52
    <body>
jaroslav@541
    53
        <p>
jaroslav@543
    54
         Use Java to write application logic; Use HTML5 to render the UI; 
jaroslav@630
    55
         {@link net.java.html.json.Model Animate an HTML page from Java}
jaroslav@630
    56
         (see <a href="http://dew.apidesign.org/dew/#7212206">Duke being rotated</a> by CSS);
jaroslav@543
    57
         Use {@link net.java.html.json.OnReceive REST} or
jaroslav@543
    58
         <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>;
jaroslav@543
    59
         interact with <a href="net/java/html/js/package-summary.html">JavaScript</a>;
jaroslav@543
    60
         Get the best of both worlds!
jaroslav@543
    61
         
jaroslav@541
    62
         The goal of these APIs is to use full featured Java runtime 
jaroslav@568
    63
         (like real <a href="http://wiki.apidesign.org/wiki/HotSpot">HotSpot VM</a>), 
jaroslav@541
    64
         but still rely on a very lightweight rendering technology 
jaroslav@541
    65
         (so it can potentially fit 
jaroslav@541
    66
         <a href="http://bck2brwsr.apidesign.org">Bck2Brwsr</a> and definitely
jaroslav@541
    67
         to various types of phones). What can be more lightweight 
jaroslav@541
    68
         (from a browser perspective) than 
jaroslav@541
    69
         <a href="http://wiki.apidesign.org/wiki/HTML">HTML</a>!?
jaroslav@541
    70
         By default we use {@link net.java.html.boot.fx JavaFX's WebView} 
jaroslav@541
    71
         component to display the <a href="http://wiki.apidesign.org/wiki/HTML">HTML</a>. 
jaroslav@541
    72
         We eliminate the need to manipulate the DOM directly, 
jaroslav@541
    73
         there is a special {@link net.java.html.json Java to Knockout.js binding}. 
jaroslav@617
    74
         As a result the <a href="http://knockoutjs.com">HTML uses Knockout.js syntax</a>, 
jaroslav@541
    75
         yet the application code can be written in Java.
jaroslav@541
    76
        </p>
jaroslav@541
    77
        
jaroslav@630
    78
        <h3>What's New in Version 0.8?</h3>
jaroslav@617
    79
        
jaroslav@617
    80
        <p>
jaroslav@617
    81
            {@link net.java.html.js.JavaScriptBody} annotation has new attribute
jaroslav@617
    82
            {@link net.java.html.js.JavaScriptBody#wait4js()} which allows
jaroslav@617
    83
            asynchronous execution. Libraries using
jaroslav@617
    84
            {@link net.java.html.js.JavaScriptBody} are urged to use this
jaroslav@617
    85
            new attribute as much as possible, as it can speed up execution
jaroslav@617
    86
            in certain environments.
jaroslav@617
    87
        </p>
jaroslav@617
    88
        
jaroslav@617
    89
        <p>
jaroslav@617
    90
            Use {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable)} in
jaroslav@617
    91
            multi-threaded environment to execute your code on the browser thread.
jaroslav@617
    92
            See example 
jaroslav@617
    93
            {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable) using Java timer}.
jaroslav@617
    94
        </p>
jaroslav@617
    95
        
jaroslav@541
    96
        <h3>Interesting Entry Points</h3>
jaroslav@541
    97
        
jaroslav@541
    98
        <p>Learn how to {@link net.java.html.json.Model animate an HTML page from Java}
jaroslav@541
    99
            without referencing single HTML element from the Java code.
jaroslav@541
   100
        </p>
jaroslav@541
   101
        <p>Use {@link net.java.html.json.OnReceive JSON} to communicate
jaroslav@541
   102
            with REST based server API.
jaroslav@541
   103
        </p>
jaroslav@541
   104
        <p>Use <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>
jaroslav@541
   105
            and JSON.
jaroslav@541
   106
        </p>
jaroslav@541
   107
        <p>Call JavaScript methods from Java and vice versa, via
jaroslav@541
   108
            <a href="net/java/html/js/package-summary.html">JavaScriptBody</a>.
jaroslav@541
   109
        </p>
jaroslav@541
   110
jaroslav@541
   111
        <h3>Getting Started</h3>
jaroslav@541
   112
jaroslav@541
   113
        There are many ways to start developing 
jaroslav@541
   114
        <a href="http://html.java.net">Html for Java</a> application. 
jaroslav@541
   115
        However to be sure one chooses the most recent setup, it is recommended
jaroslav@541
   116
        to switch to good old command line and use a 
jaroslav@541
   117
        <a href="http://wiki.apidesign.org/wiki/Knockout4Java">Maven archetype</a>
jaroslav@610
   118
        associated with every version of this project. Make sure at least 
jaroslav@610
   119
        <em>JDK7</em> is your installed Java and type:
jaroslav@541
   120
        <pre>      
jaroslav@541
   121
$ mvn archetype:generate \
jaroslav@541
   122
 -DarchetypeGroupId=org.apidesign.html \
jaroslav@541
   123
 -DarchetypeArtifactId=knockout4j-archetype \
jaroslav@608
   124
 -DarchetypeVersion=0.7.5 <em># or newer version, if available</em>
jaroslav@541
   125
        </pre>
jaroslav@611
   126
        Answer few questions (for example choose myfirstbrwsrpage as artifactId) 
jaroslav@611
   127
        and then you can:
jaroslav@541
   128
        <pre>
jaroslav@541
   129
$ cd myfirstbrwsrpage
jaroslav@541
   130
$ mvn process-classes exec:java
jaroslav@541
   131
        </pre>
jaroslav@541
   132
        In a few seconds (or minutes if 
jaroslav@541
   133
        <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
jaroslav@541
   134
        decides to download the whole Internet of dependencies) you should 
jaroslav@611
   135
        see a sample Hello World application rendered in a 
jaroslav@611
   136
        <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
jaroslav@611
   137
        web view component (that of course requires your JDK to come
jaroslav@611
   138
        with <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>; 
jaroslav@611
   139
        <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK7 
jaroslav@611
   140
            and JDK8 from Oracle</a> contain everything that is needed). 
jaroslav@611
   141
        The generated application is built around one 
jaroslav@611
   142
        Java source (uses the {@link net.java.html.json.Model} annotation to
jaroslav@611
   143
        auto-generate another <code>Data.java</code> class during compilation)
jaroslav@611
   144
        and one HTML file (uses the <a href="http://knockoutjs.com">Knockout</a>
jaroslav@611
   145
        syntax to <code>data-bind</code> the HTML elements to the 
jaroslav@611
   146
        generated <code>Data</code> model):
jaroslav@541
   147
        <pre>
jaroslav@541
   148
$ ls src/main/java/**/DataModel.java
jaroslav@541
   149
$ ls src/main/webapp/pages/index.html
jaroslav@541
   150
        </pre>
jaroslav@611
   151
        That is all you need to get started. Play with the sources, 
jaroslav@611
   152
        modify them and enjoy
jaroslav@541
   153
        <a href="http://html.java.net">Html for Java</a>!
jaroslav@541
   154
        
jaroslav@614
   155
        <h2>IDE Support</h2>
jaroslav@614
   156
        
jaroslav@614
   157
        <p>
jaroslav@614
   158
            This API is part of <a target="_blank"
jaroslav@614
   159
            href="http://netbeans.org">NetBeans.org</a> project and as such
jaroslav@614
   160
            it works naturally with the <a target="_blank"
jaroslav@614
   161
            href="https://netbeans.org/features/index.html">NetBeans IDE</a>.
jaroslav@614
   162
            On the other hand, the API is using nothing NetBeans specific,
jaroslav@614
   163
            it builds on standard Java6 APIs and as such it shall work fine
jaroslav@614
   164
            in any IDE.
jaroslav@614
   165
        </p>
jaroslav@614
   166
        
jaroslav@614
   167
        <p>
jaroslav@614
   168
            A lot of work is done by 
jaroslav@614
   169
            <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">
jaroslav@614
   170
            annotation processors</a>
jaroslav@614
   171
            that generate various boiler plate code during compilation. This
jaroslav@614
   172
            is a standard part of Java since JDK6, but for example Eclipse
jaroslav@614
   173
            is known not to deal with processors well and developers using
jaroslav@614
   174
            it need to be careful. IntelliJ users hasn't reported any issues
jaroslav@614
   175
            and of course, NetBeans IDE support for 
jaroslav@614
   176
            <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">processors</a>
jaroslav@614
   177
            is outstanding.
jaroslav@614
   178
        </p>
jaroslav@614
   179
        
jaroslav@614
   180
        <p>
jaroslav@614
   181
            When using {@link net.java.html.js.JavaScriptBody} annotation, it is
jaroslav@614
   182
            useful to do a bit of post processing of classes. There is a
jaroslav@614
   183
            <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a> 
jaroslav@614
   184
            plugin for that.
jaroslav@614
   185
            NetBeans IDE will invoke it when doing a build. Other IDEs may 
jaroslav@614
   186
            need some hint to do so. 
jaroslav@614
   187
            Anyway: If one does not see all (generated) sources or is getting
jaroslav@614
   188
            {@link java.lang.LinkageError}s when executing the application, 
jaroslav@614
   189
            switch to command line and do clean build
jaroslav@614
   190
            from there:
jaroslav@614
   191
        </p>
jaroslav@614
   192
        <pre>$ mvn clean install</pre>
jaroslav@614
   193
        <p>
jaroslav@614
   194
            If that succeeds, your IDE of choice will hopefully
jaroslav@614
   195
            pick the generated sources up and present the result of the build 
jaroslav@614
   196
            properly. If not, 
jaroslav@614
   197
            <a href="https://netbeans.org/downloads/">download NetBeans</a>, 
jaroslav@614
   198
            you will be pleasantly 
jaroslav@614
   199
            surprised - for example with our excellent 
jaroslav@614
   200
            <a href="net/java/html/js/package-summary.html#debugging">Java/JavaScript 
jaroslav@614
   201
            debugging</a> support.
jaroslav@614
   202
        </p>
jaroslav@614
   203
        
jaroslav@615
   204
        <a name="deploy">
jaroslav@615
   205
        <h2>Deploy Your Application</h2>
jaroslav@615
   206
        </a>
jaroslav@615
   207
        
jaroslav@615
   208
        <p>
jaroslav@615
   209
        It is not goal of this documentation to list all possible ways
jaroslav@615
   210
        to package and deploy applications which use this API. However it is 
jaroslav@615
   211
        important for new comers to see the benefits of using the
jaroslav@615
   212
        <a href="http://html.java.net">HTML for Java</a> API and as such
jaroslav@615
   213
        let's list at least few bundling options, known to work at the time of writing 
jaroslav@615
   214
        this documentation.
jaroslav@615
   215
        </p>
jaroslav@615
   216
        
jaroslav@615
   217
        <p>
jaroslav@615
   218
        First of all, this is a <em>client technology</em>. You write client applications
jaroslav@615
   219
        with it which may, but need not connect to a server. You don't need
jaroslav@615
   220
        Tomcat or WebLogic to deploy 
jaroslav@615
   221
        <a href="http://html.java.net">HTML for Java</a> applications.
jaroslav@615
   222
        </p>
jaroslav@615
   223
        
jaroslav@615
   224
        <p>
jaroslav@615
   225
            <img src='resources/javafx_logo.jpg' width="64"
jaroslav@615
   226
                 height="64" align="left"/>
jaroslav@615
   227
            The sample project generated by
jaroslav@615
   228
            <code>org.apidesign.html knockout4j-archetype</code> is configured
jaroslav@615
   229
            to use <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
jaroslav@615
   230
            as the rendering technology. This setup is primarily suitable for 
jaroslav@615
   231
            development - it needs no special packaging, starts quickly and
jaroslav@615
   232
            allows you to use classical HotSpot VM debuggers. A final 
jaroslav@615
   233
            artifact from the build is also a ZIP file which you can use
jaroslav@615
   234
            and distribute to your users. Good for desktop applications.
jaroslav@615
   235
        </p>
jaroslav@615
   236
        
jaroslav@615
   237
        <p>
jaroslav@615
   238
            <img src='resources/netbeans_logo.jpg' width="64"
jaroslav@615
   239
                 height="64" align="right"/>
jaroslav@615
   240
            <img src='resources/eclipse_logo.png' width="64"
jaroslav@615
   241
                 height="64" align="right"/>
jaroslav@615
   242
            All the <a href="http://html.java.net">HTML for Java</a> libraries
jaroslav@615
   243
            are package as <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
jaroslav@615
   244
            bundles and as such they can easily be run in NetBeans as well as
jaroslav@615
   245
            in Eclipse. As a result one can use 
jaroslav@615
   246
            <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
jaroslav@615
   247
            and have a common module system for both platforms and render using
jaroslav@615
   248
            HTML and have a common UI in both platforms. In such case
jaroslav@615
   249
            your application would be packaged as a set of
jaroslav@615
   250
            <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a> bundles.
jaroslav@615
   251
            Read 
jaroslav@615
   252
            <a href="http://wiki.apidesign.org/wiki/HTML">more</a>...
jaroslav@615
   253
        </p>
jaroslav@615
   254
        
jaroslav@615
   255
        <p>
jaroslav@615
   256
            <img src='resources/chrome_logo.png' width="64"
jaroslav@615
   257
                 height="64" align="left"/>
jaroslav@615
   258
            <img src='resources/safari_logo.png' width="64"
jaroslav@615
   259
                 height="64" align="left"/>
jaroslav@615
   260
            <img src='resources/ie_logo.png' width="64"
jaroslav@615
   261
                 height="64" align="left"/>
jaroslav@615
   262
            <img src='resources/firefox_logo.png' width="64"
jaroslav@615
   263
                 height="64" align="left"/>
jaroslav@615
   264
            
jaroslav@615
   265
            There is more and more attempts to execute Java bytecode
jaroslav@615
   266
            in any browser, without any special Java plugin installed.
jaroslav@615
   267
            The <a href="http://html.java.net">HTML for Java</a> is
jaroslav@615
   268
            carefully designed to produce lightweight, well performing
jaroslav@615
   269
            applications even on such restricted environments. It uses
jaroslav@615
   270
            no reflection calls and that allows to statically pre-compile
jaroslav@615
   271
            the applications into JavaScript. One of such environments
jaroslav@615
   272
            is called <em>Bck2Brwsr</em>, another <em>TeaVM</em>. Both support the
jaroslav@615
   273
            {@link net.java.html.js.JavaScriptBody} annotation. Read 
jaroslav@615
   274
            <a href="http://wiki.apidesign.org/wiki/Bck2BrwsrViaCLI">more</a> or play
jaroslav@616
   275
            a minesweeper game packaged for your browser 
jaroslav@616
   276
            (of course <a target="_blank"
jaroslav@616
   277
                href="http://source.apidesign.org/hg/html~demo/file/ea79b73d590a/minesweeper/src/main/java/org/apidesign/demo/minesweeper/MinesModel.java">
jaroslav@616
   278
                written</a> in Java):
jaroslav@615
   279
        </p>
jaroslav@616
   280
        
jaroslav@616
   281
        <script type="text/html" id="field">
jaroslav@616
   282
            <table class="field">
jaroslav@616
   283
                <tbody>
jaroslav@616
   284
                    <!-- ko foreach: rows -->
jaroslav@616
   285
                    <tr>
jaroslav@616
   286
                        <!-- ko foreach: columns -->
jaroslav@616
   287
                        <td data-bind="css: style, click: $parents[1].click" >
jaroslav@616
   288
                            <div data-bind='html: html'></div>
jaroslav@616
   289
                        </td>
jaroslav@616
   290
                        <!-- /ko -->
jaroslav@616
   291
                    </tr>
jaroslav@616
   292
                    <!-- /ko -->
jaroslav@616
   293
                </tbody>
jaroslav@616
   294
            </table>
jaroslav@616
   295
        </script>
jaroslav@616
   296
jaroslav@616
   297
        <div data-bind="template: { name : 'field', if: fieldShowing }"></div>
jaroslav@616
   298
jaroslav@616
   299
        <!-- boot bck2brwsr -->
jaroslav@616
   300
        <script type="text/javascript" src="resources/teavm.js"></script>
jaroslav@616
   301
        <script>
jaroslav@616
   302
            var vm = new VM();
jaroslav@616
   303
            vm.loadClass('org.apidesign.demo.minesweeper.MainBrwsr');
jaroslav@616
   304
        </script>
jaroslav@616
   305
jaroslav@615
   306
        <p>
jaroslav@615
   307
            <img src='resources/android_logo.jpg' width="64"
jaroslav@615
   308
                 height="64" align="right"/>
jaroslav@615
   309
            
jaroslav@615
   310
            Now when we have seen that the 
jaroslav@615
   311
            <a href="http://html.java.net">HTML for Java</a> applications 
jaroslav@615
   312
            can run on any modern browser, we can ask whether they can also
jaroslav@615
   313
            fit into a phone!? Yes, they can and especially to phones 
jaroslav@615
   314
            that can execute Java code already! Just by changing your
jaroslav@615
   315
            packaging you can create an APK file and deploy it to your
jaroslav@615
   316
            Android phone. 
jtulach@624
   317
            Read <a target="_blank" href="http://wiki.apidesign.org/wiki/DlvkBrwsr">more</a>...
jaroslav@615
   318
        </p>
jaroslav@615
   319
        <p>
jaroslav@615
   320
            Convinced it makes sense to use 
jaroslav@615
   321
            <a href="http://html.java.net">HTML for Java</a>
jaroslav@615
   322
            APIs for writing applications that are 
jaroslav@615
   323
            <em>written once, displayed anywhere</em>? Or do you have an
jaroslav@615
   324
            environment which is not supported? In such case you can bring
jaroslav@615
   325
            <a href="http://html.java.net">HTML for Java</a>
jaroslav@615
   326
            to your environment yourself. Just implement your own
jaroslav@615
   327
            {@link org.apidesign.html.boot.spi.Fn.Presenter}!
jaroslav@615
   328
        </p>
jaroslav@615
   329
        
jaroslav@607
   330
        <h2>Other Resources</h2>
jaroslav@607
   331
        
jaroslav@607
   332
        <img src="net/java/html/json/doc-files/DukeHTML.png" width="256" height="184" alt="Duke and HTML5. Together at last!" align="right"/>
jaroslav@607
   333
        
jaroslav@607
   334
        The javadoc for latest and previous versions is also available
jaroslav@607
   335
        online:
jaroslav@607
   336
        <ul>
jaroslav@607
   337
            <li>Current <a target="_blank" href="http://bits.netbeans.org/html+java/dev/">development</a> version
jtulach@625
   338
            <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.7.6">0.7.6</a>
jaroslav@607
   339
            <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.7.5">0.7.5</a>
jaroslav@607
   340
        </ul>
jaroslav@616
   341
        
jaroslav@616
   342
<style type="text/css">
jaroslav@616
   343
table.field td {
jaroslav@616
   344
    padding: 4px;
jaroslav@616
   345
    width: 18px;
jaroslav@616
   346
    height: 18px;
jaroslav@616
   347
    font-size: 1.5em;
jaroslav@616
   348
    border: 1px solid black;
jaroslav@616
   349
}
jaroslav@616
   350
table.field td.UNKNOWN {
jaroslav@616
   351
    background-color: #D6E4E1;
jaroslav@616
   352
    cursor: pointer;
jaroslav@616
   353
}
jaroslav@616
   354
table.field td.EXPLOSION {
jaroslav@616
   355
    background-color: #A31E39;
jaroslav@616
   356
}
jaroslav@616
   357
table.field td.DISCOVERED {
jaroslav@616
   358
    background-color: #9DB2B1;
jaroslav@616
   359
}
jaroslav@616
   360
</style>        
jaroslav@541
   361
    </body>
jaroslav@541
   362
</html>