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

     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 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 0.8?</h3>

    80         <p>

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

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

    83             asynchronous execution. Libraries using

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

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

    86             in certain environments.

    87         </p>

    89         <p>

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

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

    92             See example

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

    94         </p>

    96         <h3>Interesting Entry Points</h3>

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

    99             without referencing single HTML element from the Java code.

   100         </p>

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

   102             with REST based server API.

   103         </p>

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

   105             and JSON.

   106         </p>

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

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

   109         </p>

   111         <h3>Getting Started</h3>

   113         There are many ways to start developing

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

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

   116         to switch to good old command line and use a

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

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

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

   120         <pre>

   121 $ mvn archetype:generate \

   122  -DarchetypeGroupId=org.apidesign.html \

   123  -DarchetypeArtifactId=knockout4j-archetype \

   124  -DarchetypeVersion=0.7.5 <em># or newer version, if available</em>

   125         </pre>

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

   127         and then you can:

   128         <pre>

   129 $ cd myfirstbrwsrpage

   130 $ mvn process-classes exec:java

   131         </pre>

   132         In a few seconds (or minutes if

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

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

   135         see a sample Hello World application rendered in a

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

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

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

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

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

   141         The generated application is built around one

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

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

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

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

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

   147         <pre>

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

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

   150         </pre>

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

   152         modify them and enjoy

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

   155         <h2>IDE Support</h2>

   157         <p>

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

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

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

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

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

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

   164             in any IDE.

   165         </p>

   167         <p>

   168             A lot of work is done by

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

   170             annotation processors</a>

   171             that generate various boiler plate code during compilation. This

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

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

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

   175             and of course, NetBeans IDE support for

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

   177             is outstanding.

   178         </p>

   180         <p>

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

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

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

   184             plugin for that.

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

   186             need some hint to do so.

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

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

   189             switch to command line and do clean build

   190             from there:

   191         </p>

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

   193         <p>

   194             If that succeeds, your IDE of choice will hopefully

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

   196             properly. If not,

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

   198             you will be pleasantly

   199             surprised - for example with our excellent

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

   201             debugging</a> support.

   202         </p>

   204         <a name="deploy">

   205         <h2>Deploy Your Application</h2>

   206         </a>

   208         <p>

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

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

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

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

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

   214         this documentation.

   215         </p>

   217         <p>

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

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

   220         Tomcat or WebLogic to deploy

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

   222         </p>

   224         <p>

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

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

   227             The sample project generated by

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

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

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

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

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

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

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

   235         </p>

   237         <p>

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

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

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

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

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

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

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

   245             in Eclipse. As a result one can use

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

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

   248             one can render using

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

   250             your application would be packaged as a set of

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

   252             Read

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

   254         </p>

   256         <p>

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

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

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

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

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

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

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

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

   266             There is more and more attempts to execute Java bytecode

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

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

   269             carefully designed to produce lightweight, well performing

   270             applications even on such restricted environments. It uses

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

   272             the applications into JavaScript. One of such environments

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

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

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

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

   277             a minesweeper game packaged for your browser

   278             (of course <a target="_blank"

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

   280                 written</a> in Java):

   281         </p>

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

   284             <table class="field">

   285                 <tbody>

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

   287                     <tr>

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

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

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

   291                         </td>

   292                         <!-- /ko -->

   293                     </tr>

   294                     <!-- /ko -->

   295                 </tbody>

   296             </table>

   297         </script>

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

   301         <!-- boot bck2brwsr -->

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

   303         <script>

   304             var vm = new VM();

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

   306         </script>

   308         <p>

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

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

   312             Now when we have seen that the

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

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

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

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

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

   318             Android phone.

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

   320         </p>

   321         <p>

   322             Convinced it makes sense to use

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

   324             APIs for writing applications that are

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

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

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

   328             to your environment yourself. Just implement your own

   329             {@link org.apidesign.html.boot.spi.Fn.Presenter}!

   330         </p>

   332         <h2>Other Resources</h2>

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

   336         The javadoc for latest and previous versions is also available

   337         online:

   338         <ul>

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

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

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

   342         </ul>

   344 <style type="text/css">

   345 table.field td {

   346     padding: 4px;

   347     width: 18px;

   348     height: 18px;

   349     font-size: 1.5em;

   350     border: 1px solid black;

   351 }

   352 table.field td.UNKNOWN {

   353     background-color: #D6E4E1;

   354     cursor: pointer;

   355 }

   356 table.field td.EXPLOSION {

   357     background-color: #A31E39;

   358 }

   359 table.field td.DISCOVERED {

   360     background-color: #9DB2B1;

   361 }

   362 </style>

   363     </body>

   364 </html>

author	Jaroslav Tulach <jaroslav.tulach@netbeans.org>
	Wed, 26 Mar 2014 18:57:05 +0100
changeset 639	b4b0758904e2
parent 630	c7eaca4ac999
parent 638	e4c01c8287f1
child 647	989ce2017405
permissions	-rw-r--r--