Repository: incubator-netbeans-html4j Updated Branches: refs/heads/master 9032affbe -> 926c9a0b6
Adding a readme file Project: http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/commit/926c9a0b Tree: http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/tree/926c9a0b Diff: http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/diff/926c9a0b Branch: refs/heads/master Commit: 926c9a0b6dd62e918dfb17b10a779b7b55bf8cc8 Parents: 9032aff Author: Jaroslav Tulach <jaroslav.tul...@oracle.com> Authored: Fri Oct 6 15:10:41 2017 +0200 Committer: Jaroslav Tulach <jaroslav.tul...@oracle.com> Committed: Fri Oct 6 15:10:41 2017 +0200 ---------------------------------------------------------------------- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/blob/926c9a0b/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md new file mode 100644 index 0000000..9b29791 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +== HTML/Java API == + +In need of cross platform, client side interaction between Java and JavaScript? +The HTML/Java library provides [basic building blocks](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/js/package-summary.html) +as well as advanced [high level concepts](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/json/Model.html) +to make communication between JavaScript and Java as smooth as possible. + +Read more in the [latest javadoc](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/) documentation. + +== Portability == + +Every browser widget Java API offers ways for communication between Java and +JavaScript running in such widget. However, each of them is unique - e.g. one +writes different code when communicating with [JavaFX WebView](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/web/WebView.html), +different one when communicating with [Android WebView](https://developer.android.com/reference/android/webkit/WebView.html), +yet another one when talking to [iOS WebView](https://developer.apple.com/documentation/uikit/uiwebview). + +The goal of HTML/Java API is to **unify this communication**. By providing simple +and highly portable [building blocks](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/js/package-summary.html) +one can create sophisticated APIs that can be embedded into +[Swing or JavaFX applications](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/boot/fx/FXBrowsers.html), +executed [headlessly on a server](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/boot/script/Scripts.html). + +Various ports of this rendering pipeline were built including support for +pure [webkit desktop rendring](https://github.com/dukescript/dukescript-presenters/), +[Android WebView](https://dukescript.com/javadoc/presenters/com/dukescript/presenters/Android.html) +and [iOS WebView](https://dukescript.com/javadoc/presenters/com/dukescript/presenters/iOS.html) +developed by [DukeScript project](https://dukescript.com/). + +This technology has also been adopted by some Java bytecode to JavaScript +transpilers - for example [Bck2Brwsr VM](https://github.com/jtulach/bck2brwsr/) - +as such you can also run the same Java application in a pluginless browser. + +Porting of HTML/Java rendering pipeline is as easy as implementing +[Fn.Presenter](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/org/netbeans/html/boot/spi/Fn.Presenter.html) +interface and passing the [technology compatibility kit](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/org/netbeans/html/json/tck/package-summary.html). + +== Contributing == + +You can contribute to development of this library by forking +its [GitHub repository](https://github.com/apache/incubator-netbeans-html4j). +Change, modify, test: + +```bash +$ mvn clean install +``` + +and create a pull request, which may then be merged into the +official [Apache repository](https://git-wip-us.apache.org/repos/asf?p=incubator-netbeans-html4j.git). + +=== Full History === + +The origins of the code in this repository are older than +its Apache existance. As such significant part of the history +(before the code has been donated to Apache) is kept in an +independent repository. To fully understand the code you may +want to merge the modern and ancient versions together: + +```bash +$ git clone https://github.com/apache/incubator-netbeans-html4j.git html+java+both +$ cd html+java+both +$ git log boot/src/main/java/net/java/html/boot/BrowserBuilder.java +``` + +This gives you just few log entries including the initial checkin and change of the +file headers to Apache. But then the magic comes: + +```bash +$ git remote add emilian https://github.com/emilianbold/netbeans-html4j.git +$ git fetch emilian +$ git replace 408363d d029b8e +``` + +When you search the log, or use the blame tool, the full history is +available: + +```bash +$ git log boot/src/main/java/net/java/html/boot/BrowserBuilder.java +$ git blame boot/src/main/java/net/java/html/boot/BrowserBuilder.java +``` + +Many thanks to Emilian Bold who converted the ancient history to +[his Git repository](https://github.com/emilianbold/netbeans-html4j) +and made the magic possible!
