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

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

    80         <p>

    81             Few bugfixes for better portability.

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

    83             on top of <em>Nashorn</em>. Does not run <em>knockout for Java</em>

    84             fully yet

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

    86             however even in current state it is quite

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

    88             of

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

    90         </p>

    92         <h3>What's New in Version 0.8.1?</h3>

    94         <p>

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

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

    97             API in existing JavaFX applications.

    98             The annotation processor is made

    99             more robust with respect to errors in callback syntax of

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

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

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

   103             There can be additional parameters to methods annotated by

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

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

   106             The mechanism of discovery of sibling HTML page has been

   107             extended to work on systems that don't support

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

   109         </p>

   111         <h3>What's New in Version 0.8?</h3>

   113         <p>

   114             The first argument of method annotated by

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

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

   117         </p>

   119         <p>

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

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

   122             (previously required an array).

   123         </p>

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

   128         <p>

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

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

   131             asynchronous execution. Libraries using

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

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

   134             in certain environments.

   135         </p>

   137         <p>

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

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

   140             See example

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

   142         </p>

   144         <h3>Interesting Entry Points</h3>

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

   147             without referencing single HTML element from the Java code.

   148         </p>

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

   150             with REST based server API.

   151         </p>

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

   153             and JSON.

   154         </p>

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

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

   157         </p>

   159         <h3>Getting Started</h3>

   161         There are many ways to start developing

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

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

   164         to switch to good old command line and use a

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

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

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

   168         <pre>

   169 $ mvn archetype:generate \

   170  -DarchetypeGroupId=org.apidesign.html \

   171  -DarchetypeArtifactId=knockout4j-archetype \

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

   173         </pre>

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

   175         and then you can:

   176         <pre>

   177 $ cd myfirstbrwsrpage

   178 $ mvn process-classes exec:java

   179         </pre>

   180         In a few seconds (or minutes if

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

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

   183         see a sample Hello World application rendered in a

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

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

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

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

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

   189         The generated application is built around one

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

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

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

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

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

   195         <pre>

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

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

   198         </pre>

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

   200         modify them and enjoy

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

   203         <h2>IDE Support</h2>

   205         <p>

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

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

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

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

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

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

   212             in any IDE.

   213         </p>

   215         <p>

   216             A lot of work is done by

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

   218             annotation processors</a>

   219             that generate various boiler plate code during compilation. This

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

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

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

   223             and of course, NetBeans IDE support for

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

   225             is outstanding.

   226         </p>

   228         <p>

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

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

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

   232             plugin for that.

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

   234             need some hint to do so.

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

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

   237             switch to command line and do clean build

   238             from there:

   239         </p>

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

   241         <p>

   242             If that succeeds, your IDE of choice will hopefully

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

   244             properly. If not,

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

   246             you will be pleasantly

   247             surprised - for example with our excellent

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

   249             debugging</a> support.

   250         </p>

   252         <a name="deploy">

   253         <h2>Deploy Your Application</h2>

   254         </a>

   256         <p>

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

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

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

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

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

   262         this documentation.

   263         </p>

   265         <p>

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

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

   268         Tomcat or WebLogic to deploy

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

   270         </p>

   272         <p>

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

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

   275             The sample project generated by

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

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

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

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

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

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

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

   283         </p>

   285         <p>

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

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

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

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

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

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

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

   293             in Eclipse. As a result one can use

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

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

   296             one can render using

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

   298             your application would be packaged as a set of

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

   300             Read

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

   302         </p>

   304         <p>

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

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

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

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

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

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

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

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

   314             There is more and more attempts to execute Java bytecode

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

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

   317             carefully designed to produce lightweight, well performing

   318             applications even on such restricted environments. It uses

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

   320             the applications into JavaScript. One of such environments

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

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

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

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

   325             a minesweeper game packaged for your browser

   326             (of course <a target="_blank"

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

   328                 written</a> in Java):

   329         </p>

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

   332             <table class="field">

   333                 <tbody>

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

   335                     <tr>

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

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

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

   339                         </td>

   340                         <!-- /ko -->

   341                     </tr>

   342                     <!-- /ko -->

   343                 </tbody>

   344             </table>

   345         </script>

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

   349         <!-- boot bck2brwsr -->

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

   351         <script>

   352             var vm = new VM();

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

   354         </script>

   356         <p>

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

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

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

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

   362             Now when we have seen that the

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

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

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

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

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

   368             Android phone.

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

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

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

   372             seems the set of devices that can execute

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

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

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

   376             and deploy everywhere!

   377         </p>

   378         <p>

   379             Convinced it makes sense to use

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

   381             APIs for writing applications that are

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

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

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

   385             to your environment yourself. Just implement your own

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

   387         </p>

   389         <h2>Other Resources</h2>

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

   393         The javadoc for latest and previous versions is also available

   394         online:

   395         <ul>

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

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

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

   399         </ul>

   401 <style type="text/css">

   402 table.field td {

   403     padding: 4px;

   404     width: 18px;

   405     height: 18px;

   406     font-size: 1.5em;

   407     border: 1px solid black;

   408 }

   409 table.field td.UNKNOWN {

   410     background-color: #D6E4E1;

   411     cursor: pointer;

   412 }

   413 table.field td.EXPLOSION {

   414     background-color: #A31E39;

   415 }

   416 table.field td.DISCOVERED {

   417     background-color: #9DB2B1;

   418 }

   419 </style>

   420     </body>

   421 </html>

author	Jaroslav Tulach <jtulach@netbeans.org>
	Mon, 09 Jun 2014 10:01:06 +0200
changeset 702	e6f275887b20
parent 668	f0f27e06ceed
child 703	6da3da4c61a0
permissions	-rw-r--r--