[icedtea-web] RFC: Replace PDF with editable HTML documentation
Deepak Bhole
dbhole at redhat.com
Tue Mar 29 07:21:37 PDT 2011
* Dr Andrew John Hughes <ahughes at redhat.com> [2011-03-29 08:50]:
> The plugin/docs directory in IcedTea-Web includes an uneditable PDF
> file npplugin_liveconnect_design.pdf which prevents developers from
> changing the document and breaks the packaging guidelines for some
> distributions. The attached patch replaces the PDF with an editable
> HTML version, while also fixing a number of minor issues (duplication
> of one slide, minor grammar issues).
>
> I did notice that the PDF (and thus this HTML version) are incomplete.
> Deepak, do you plan to complete this documentation?
>
> Patches for 1.0 and HEAD are attached. They are identical, bar the
> addition of a NEWS entry in the 1.0 version, as I expect this to
> appear in 1.0.2. As there are a number of other fixes on the 1.0
> branch, I think we are due for another 1.0.x release and the current
> 1.0.1 release can not be packaged due to this PDF file.
>
Okay for both branches.
Cheers,
Deepak
> HEAD ChangeLog:
>
> 2010-03-29 Andrew John Hughes <ahughes at redhat.com>
>
> * plugin/docs/npplugin_liveconnect_design.html:
> Replace binary PDF documentation with editable HTML.
> * plugin/docs/npplugin_liveconnect_design.pdf: Removed.
>
> 1.0 ChangeLog:
>
> 2010-03-29 Andrew John Hughes <ahughes at redhat.com>
>
> * NEWS: Updated.
> * plugin/docs/npplugin_liveconnect_design.html:
> Replace binary PDF documentation with editable HTML.
> * plugin/docs/npplugin_liveconnect_design.pdf: Removed.
>
> Ok to push to both branches?
> --
> Andrew :)
>
> Free Java Software Engineer
> Red Hat, Inc. (http://www.redhat.com)
>
> Support Free Java!
> Contribute to GNU Classpath and IcedTea
> http://www.gnu.org/software/classpath
> http://icedtea.classpath.org
> PGP Key: F5862A37 (https://keys.indymedia.org/)
> Fingerprint = EA30 D855 D50F 90CD F54D 0698 0713 C3ED F586 2A37
> diff -r 1a2f329bdd26 NEWS
> --- a/NEWS Thu Mar 03 17:56:00 2011 -0500
> +++ b/NEWS Tue Mar 29 13:42:02 2011 +0100
> @@ -13,6 +13,7 @@
> - PR638: JNLPClassLoader.loadClass(String name) can return null
> * Plugin
> - PR612: NetDania application ends on java.security.AccessControlException: access denied (java.util.PropertyPermission browser read)
> + - Replace binary PDF documentation with editable HTML version.
>
> New in release 1.0.1 (2011-02-15):
>
> diff -r 1a2f329bdd26 plugin/docs/npplugin_liveconnect_design.html
> --- /dev/null Thu Jan 01 00:00:00 1970 +0000
> +++ b/plugin/docs/npplugin_liveconnect_design.html Tue Mar 29 13:42:02 2011 +0100
> @@ -0,0 +1,117 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
> + <head>
> + <title>IcedTeaNPPlugin LiveConnect Design</title>
> + </head>
> + <body>
> + <h1>IcedTeaNPPlugin LiveConnect Design</h1>
> + <h2>Plugin Architecture</h2>
> + <ul>
> + <li>Divided into C++ and Java components</li>
> + <li><ul>
> + <li>C++ side talks to the browser</li>
> + <li>Java side talks to the JVM</li>
> + <li>Linked via a FIFO link</li>
> + <li>Common string exchange format (UTF-8)</li>
> + </ul></li>
> + <li>Over 95% of changes in NPPlugin have been on the C++ side</li>
> + <li>Java side has been reused as much as possible to re-use the proven stable code</li>
> + </ul>
> + <h2>C++ Architecture</h2>
> + <ul>
> + <li>Encompassing classes from the LiveConnect engine (which previously resided in Mozilla
> + and was exposed via OJI)</li>
> + <li>Each JavaScript var corresponding to a Java object has a corresponding
> + <code>IcedTeaScriptableJavaObject</code></li>
> + <li>Engine controls the object life and services all requests (get field, set field,
> + invoke method, etc.)</li>
> + </ul>
> + <h2>C++ Architecture (Browser Interface)</h2>
> + <ul>
> + <li>Browser interface consists primarily of <code>IcedTeaScriptableJavaPackageObject</code>,
> + <code>IcedTeaScriptableJavaObject</code> and <code>IcedTeaPluginRequestProcessor</code>.</li>
> + <li>Above classes are unaware of Java interactions and delegate to the Java interfaces
> + for Java interaction.</li>
> + <li>They process all requests coming from the browser and going to the browser (<code>getMember</code>,
> + <code>call</code>, <code>eval</code>, etc.)</li>
> + </ul>
> + <h2>C++ Architecture (Java Interface)</h2>
> + <ul>
> + <li>Java interface consists primarily of <code>IcedTeaJavaRequestProcessor</code>.</li>
> + <li>This class has full knowledge of how the Java side works, and constructs appropriate
> + requests to get all information from Java.</li>
> + <li>The class processes all requests to the JVM.</li>
> + </ul>
> + <h2>Java Architecture</h2>
> + <ul>
> + <li>Java side has two core classes aside from helpers: <code>PluginAppletViewer</code>
> + and <code>PluginAppletSecurityContext</code>.</li>
> + <li><code>PluginAppletViewer</code> is an interface to NetX and processes JS-related
> + requests to and from NetX (the applet).</li>
> + <li><code>PluginAppletSecurityContext</code> is a direct reflection-based interface
> + to the VM. It processes all LiveConnect requests to and from the JVM.</li>
> + <li>Request processing is asynchronous, with scalable generic request processing workers.</li>
> + </ul>
> + <h2>Java Architecture (<code>PluginAppletViewer</code>)</h2>
> + <ul>
> + <li>Control of applet (initialize, resize, destroy, etc.) from browser.</li>
> + <li>Access to JavaScript from the applet (<code>getMember</code>, <code>setMember</code>,
> + <code>call</code>, <code>eval</code>, etc.)</li>
> + </ul>
> + <h2>Java Architecture (<code>PluginAppletSecurityContext</code>)</h2>
> + <ul>
> + <li>Direct access to the JVM from the browser (LiveConnect) via reflection.</li>
> + <li>All reflection is built-in, so C++ side never needs to be aware of the complexities,
> + unlike how OJI was.</li>
> + <li>All VM calls are inside a sandbox, so JavaScript can not do things that the default
> + sandboxed VM can't.</li>
> + </ul>
> + <h2>MessageBus Architecture (C++)</h2>
> + <ul>
> + <li>The link to Java is exposed to the rest of the code via a uniform "MessageBus" interface.</li>
> + <li>Since the code is unaware of the link specifics and has no synchronicity guarantee, the communication
> + medium can be switched relatively easily.</li>
> + <li>Classes interested in the messages implement a <code>BusSubscriber</code> class and subscribe to
> + the bus of interest.</li>
> + <li>When messages come in, the bus notifies all subscribers.</li>
> + </ul>
> + <h2>Example JS->Java Workflow</h2>
> + <ul>
> + <li>Example shows how <code>NPP_HasProperty()</code> works</li>
> + <li>Browser has a link to an <code>IcedTeaScriptableJavaObject</code> representing a Java
> + object instance.</li>
> + <li>It call <code>IcedTeaScriptableJavaObject::HasProperty()</code></li>
> + <li><code>HasProperty()</code> creates an <code>IcedTeaJavaRequestProcessor</code>
> + ("Java processor")</li>
> + <li>The Java processor exposes all necessary APIs to the VM, including <code>hasProperty</code>
> + (called <code>hasField</code> for Java naming consistency).</li>
> + <li>Before making a <code>hasField</code> request, the processor subscribes itself
> + to the "from Java" bus, so that it can read the response.</li>
> + <li>The <code>hasField</code> request is made by the processor and posted to the
> + "to Java" bus.</li>
> + <li>The processor waits for either a response or a timeout.</li>
> + <li>Once a response is received, the processor unsubscribes itself from the
> + "from Java" bus, performs post-processing and returns.</li>
> + <li>The <code>IcedTeaScriptableJavaObject</code> object reads the response and
> + sends it to the browser.</li>
> + </ul>
> + <h2>Example Java->JS Workflow</h2>
> + <ul>
> + <li>All access to JS is via <code>JSObject</code> instances as defined in the
> + LiveConnect specification.</li>
> + <li>If an applet wants to access a member of <code>JSObject</code>, "window"
> + for example, it will call <code>getMember</code> on the window's <code>JSObject</code>.</li>
> + <li><code>getMember</code> calls a similarly named function in
> + <code>PluginAppletViewer</code>.</li>
> + <li><code>PluginAppletViewer</code> constructs a request for the C++ side and
> + posts it on the FIFO link.</li>
> + <li>On the C++ side, <code>IcedTeaPluginRequestProcessor</code> (the plugin
> + processor) is always subscribed to the "from Java" bus.</li>
> + <li>When the <code>getMember</code> request comes through, the plugin processor
> + gets notified.</li>
> + <li>The embedded request</li>
> + </ul>
> + </body>
> +</html>
> +
> diff -r 1a2f329bdd26 plugin/docs/npplugin_liveconnect_design.pdf
> Binary file plugin/docs/npplugin_liveconnect_design.pdf has changed
> diff -r c04136b79d4a plugin/docs/npplugin_liveconnect_design.html
> --- /dev/null Thu Jan 01 00:00:00 1970 +0000
> +++ b/plugin/docs/npplugin_liveconnect_design.html Tue Mar 29 13:19:07 2011 +0100
> @@ -0,0 +1,117 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
> + <head>
> + <title>IcedTeaNPPlugin LiveConnect Design</title>
> + </head>
> + <body>
> + <h1>IcedTeaNPPlugin LiveConnect Design</h1>
> + <h2>Plugin Architecture</h2>
> + <ul>
> + <li>Divided into C++ and Java components</li>
> + <li><ul>
> + <li>C++ side talks to the browser</li>
> + <li>Java side talks to the JVM</li>
> + <li>Linked via a FIFO link</li>
> + <li>Common string exchange format (UTF-8)</li>
> + </ul></li>
> + <li>Over 95% of changes in NPPlugin have been on the C++ side</li>
> + <li>Java side has been reused as much as possible to re-use the proven stable code</li>
> + </ul>
> + <h2>C++ Architecture</h2>
> + <ul>
> + <li>Encompassing classes from the LiveConnect engine (which previously resided in Mozilla
> + and was exposed via OJI)</li>
> + <li>Each JavaScript var corresponding to a Java object has a corresponding
> + <code>IcedTeaScriptableJavaObject</code></li>
> + <li>Engine controls the object life and services all requests (get field, set field,
> + invoke method, etc.)</li>
> + </ul>
> + <h2>C++ Architecture (Browser Interface)</h2>
> + <ul>
> + <li>Browser interface consists primarily of <code>IcedTeaScriptableJavaPackageObject</code>,
> + <code>IcedTeaScriptableJavaObject</code> and <code>IcedTeaPluginRequestProcessor</code>.</li>
> + <li>Above classes are unaware of Java interactions and delegate to the Java interfaces
> + for Java interaction.</li>
> + <li>They process all requests coming from the browser and going to the browser (<code>getMember</code>,
> + <code>call</code>, <code>eval</code>, etc.)</li>
> + </ul>
> + <h2>C++ Architecture (Java Interface)</h2>
> + <ul>
> + <li>Java interface consists primarily of <code>IcedTeaJavaRequestProcessor</code>.</li>
> + <li>This class has full knowledge of how the Java side works, and constructs appropriate
> + requests to get all information from Java.</li>
> + <li>The class processes all requests to the JVM.</li>
> + </ul>
> + <h2>Java Architecture</h2>
> + <ul>
> + <li>Java side has two core classes aside from helpers: <code>PluginAppletViewer</code>
> + and <code>PluginAppletSecurityContext</code>.</li>
> + <li><code>PluginAppletViewer</code> is an interface to NetX and processes JS-related
> + requests to and from NetX (the applet).</li>
> + <li><code>PluginAppletSecurityContext</code> is a direct reflection-based interface
> + to the VM. It processes all LiveConnect requests to and from the JVM.</li>
> + <li>Request processing is asynchronous, with scalable generic request processing workers.</li>
> + </ul>
> + <h2>Java Architecture (<code>PluginAppletViewer</code>)</h2>
> + <ul>
> + <li>Control of applet (initialize, resize, destroy, etc.) from browser.</li>
> + <li>Access to JavaScript from the applet (<code>getMember</code>, <code>setMember</code>,
> + <code>call</code>, <code>eval</code>, etc.)</li>
> + </ul>
> + <h2>Java Architecture (<code>PluginAppletSecurityContext</code>)</h2>
> + <ul>
> + <li>Direct access to the JVM from the browser (LiveConnect) via reflection.</li>
> + <li>All reflection is built-in, so C++ side never needs to be aware of the complexities,
> + unlike how OJI was.</li>
> + <li>All VM calls are inside a sandbox, so JavaScript can not do things that the default
> + sandboxed VM can't.</li>
> + </ul>
> + <h2>MessageBus Architecture (C++)</h2>
> + <ul>
> + <li>The link to Java is exposed to the rest of the code via a uniform "MessageBus" interface.</li>
> + <li>Since the code is unaware of the link specifics and has no synchronicity guarantee, the communication
> + medium can be switched relatively easily.</li>
> + <li>Classes interested in the messages implement a <code>BusSubscriber</code> class and subscribe to
> + the bus of interest.</li>
> + <li>When messages come in, the bus notifies all subscribers.</li>
> + </ul>
> + <h2>Example JS->Java Workflow</h2>
> + <ul>
> + <li>Example shows how <code>NPP_HasProperty()</code> works</li>
> + <li>Browser has a link to an <code>IcedTeaScriptableJavaObject</code> representing a Java
> + object instance.</li>
> + <li>It call <code>IcedTeaScriptableJavaObject::HasProperty()</code></li>
> + <li><code>HasProperty()</code> creates an <code>IcedTeaJavaRequestProcessor</code>
> + ("Java processor")</li>
> + <li>The Java processor exposes all necessary APIs to the VM, including <code>hasProperty</code>
> + (called <code>hasField</code> for Java naming consistency).</li>
> + <li>Before making a <code>hasField</code> request, the processor subscribes itself
> + to the "from Java" bus, so that it can read the response.</li>
> + <li>The <code>hasField</code> request is made by the processor and posted to the
> + "to Java" bus.</li>
> + <li>The processor waits for either a response or a timeout.</li>
> + <li>Once a response is received, the processor unsubscribes itself from the
> + "from Java" bus, performs post-processing and returns.</li>
> + <li>The <code>IcedTeaScriptableJavaObject</code> object reads the response and
> + sends it to the browser.</li>
> + </ul>
> + <h2>Example Java->JS Workflow</h2>
> + <ul>
> + <li>All access to JS is via <code>JSObject</code> instances as defined in the
> + LiveConnect specification.</li>
> + <li>If an applet wants to access a member of <code>JSObject</code>, "window"
> + for example, it will call <code>getMember</code> on the window's <code>JSObject</code>.</li>
> + <li><code>getMember</code> calls a similarly named function in
> + <code>PluginAppletViewer</code>.</li>
> + <li><code>PluginAppletViewer</code> constructs a request for the C++ side and
> + posts it on the FIFO link.</li>
> + <li>On the C++ side, <code>IcedTeaPluginRequestProcessor</code> (the plugin
> + processor) is always subscribed to the "from Java" bus.</li>
> + <li>When the <code>getMember</code> request comes through, the plugin processor
> + gets notified.</li>
> + <li>The embedded request</li>
> + </ul>
> + </body>
> +</html>
> +
> diff -r c04136b79d4a plugin/docs/npplugin_liveconnect_design.pdf
> Binary file plugin/docs/npplugin_liveconnect_design.pdf has changed
More information about the distro-pkg-dev
mailing list