Author: [EMAIL PROTECTED]
Date: Mon Oct 27 15:45:49 2008
New Revision: 3875
Modified:
wiki/DesignOOPHM.wiki
Log:
Update documentation to match current branches/oophm.
Patch by: t.broyer
Review by: jat
Modified: wiki/DesignOOPHM.wiki
==============================================================================
--- wiki/DesignOOPHM.wiki (original)
+++ wiki/DesignOOPHM.wiki Mon Oct 27 15:45:49 2008
@@ -67,8 +67,8 @@
Executing this code in the hosted mode browser requires the following
steps:
# *!JavaScript:* the browser plugin sends a {{{LoadModuleMessage}}} with
the module name.
- # *Java:* the hosted mode server receives the {{{LoadModuleMessage}}},
loads the module and invokes the {{{onModuleLoad}}} in the
corresponding !EntryPoints. In this case {{{MyEntryPoint::onModuleLoad}}}
is called. When {{{onModuleLoad}}} invokes {{{jsniMethod}}} an
{{{InvokeMessage}}} is sent.
- # *!JavaScript:* This is the key part of the example. The !JavaScript
engine is currently awaiting a return from the {{{LoadModuleMessage}}} it
sent, but it must be in a position to invoke the call to
{{{MyEntryPoint::jsniMethod}}} on the same thread. This is accomplished by
having the thread enter a read-and-dispatch routine following every remote
invocation. In this case, the thread receives the {{{InvokeMessage}}},
invokes {{{jsniMethod}}} and sends a {{{ReturnMessage}}} containing the
value 1.
+ # *Java:* the hosted mode server receives the {{{LoadModuleMessage}}},
loads the module and invokes the {{{onModuleLoad}}} in the
corresponding !EntryPoints. In this case {{{MyEntryPoint::onModuleLoad}}}
is called. When {{{MyEntryPoint}}} is compiled, a {{{LoadJsniMessage}}} is
sent to create browser-side !JavaScript functions for each JSNI method,
then when {{{onModuleLoad}}} invokes {{{jsniMethod}}} an
{{{InvokeMessage}}} is sent.
+ # *!JavaScript:* This is the key part of the example. The !JavaScript
engine is currently awaiting a return from the {{{LoadModuleMessage}}} it
sent, but it must be in a position to invoke the call to
{{{MyEntryPoint::jsniMethod}}} on the same thread. This is accomplished by
having the thread enter a read-and-dispatch routine following every remote
invocation. In this case, the thread receives the {{{LoadJsniMessage}}} and
{{{InvokeMessage}}} messages, invokes {{{jsniMethod}}} and sends a
{{{ReturnMessage}}} containing the value 1.
# *Java:* The read-and-dispatch routine receives the {{{ReturnMessage}}}
and knows to return from the call to {{{jsniMethod}}}. Having fully
executed the {{{onModuleLoad}}} method it sends a {{{ReturnMessage}}} and
falls back into a top level read-and-dispatch loop. (Since all calls
originate from the browser's UI event dispatch, only the hosted mode server
needs to remain in a read-and-dispatch routine during idle time. The
browser simply returns control by exiting the !JavaScript function that was
originally called.)
To further illustrate this functionality, the following is a simplified
state diagram shows how the messaging scheme simulates method invocation
over an asynchronous messaging channel.
@@ -78,57 +78,77 @@
The wire format for the communications protocol is a simple binary
format. A need may arise for something more elaborate at a later date, but
we have elected for the simplest possible scheme that works for now. The
details of each message's binary format is given below along with formats
for primitive data types.
==== Messages ====
- NOTE: This is likely not a complete list of the messages that exist in
the system.
+ NOTE: This is likely not a complete list of the messages that exist in
the system, and values given for some fields are likely to change.
_!LoadModuleMessage:_ requests that the hosted mode server load and
begin executing a module.
- || type (byte) || version (int) || module name (string) || user agent
(string) ||
+ || type (byte) =2 || version (int) =1 || module name (string) || user
agent (string) ||
- _!InvokeMessage:_ used to do method invocation on Java and !JavaScript
objects.
- || type (byte) || method (string) || this (Value) || number of args
(int) || args (Value[]) ||
+ _!InvokeMessage:_ used to do method invocation on Java and !JavaScript
objects. This message's format is asymmetric.
+ From server to client (invoke a method on a !JavaScript object):
+ || type (byte) =0 || method name (string) || this (Value) || number of
args (int) || args (Value[]) ||
+ From client to server (invoke a method on a Java object):
+ || type (byte) =0 || method dispatch id (int) || this (Value) || number
of args (int) || args (Value[]) ||
- _!EvaluateMessage:_ used to evaluate !JavaScript code in the browser.
- || type (byte) || this (Value) || js code (string) ||
+ _!LoadJsniMessage:_ used to evaluate !JavaScript code in the browser to
initialize JSNI methods.
+ || type (byte) =4 || js code (string) ||
_!QuitMessage:_ used to cooperatively shutdown the browser channel.
- || type (byte) ||
+ || type (byte) =3 ||
- _!ReturnMessage:_ - used to send the return values associated with
invoke and evaluate messages.
- || type (byte) || return value (Value) ||
+ _!ReturnMessage:_ - used to send the return values associated with
Invoke, !InvokeSpecial and !LoadModule messages.
+ || type (byte) =1 || is exception (boolean) || return value (Value) ||
- _!ExceptionMessage:_ - used to throw exceptions associted with invoke
and evaluate messages.
- || type (byte) || exception reference (Value) ||
+ _!InvokeSpecialMessage:_ - used to access Java object properties (fields
or method _pointers_) from the browser side.
+ || type (byte) =5 || special method (byte) || number of args (int) ||
args (Value[]) ||
+
+ _!FreeValueMessage:_ - used to tell the other side it can free its Java
(server-side) or !JavaScript (browser-side) objects
+ || type (byte) =6 || number of ref ids (int) || ref ids (int[]) ||
`*` all strings are encoded as a length, n, followed by n bytes of data
containing the string in utf8 encoding.
`*``*` the encoding of values is given below.
==== Values ====
+ NOTE: the _tag_ part is only needed for generic {{{Value}}}s passed in
Invoke, !InvokeSpecial and Return messages.
+
_null_
- || tag (byte) ||
+ || tag (byte) =0 ||
+
+ _undefined_ (also used for {{{void}}} returns)
+ || tag (byte) =12 ||
_boolean_
- || tag (byte) || value (8 bit signed) ||
+ || tag (byte) =1 || value (8 bit signed) ||
_byte_
- || tag (byte) || value (8 bit signed) ||
+ || tag (byte) =2 || value (8 bit signed) ||
_char_
- || tag (byte) || value (16 bit signed) ||
+ || tag (byte) =3 || value (16 bit signed) ||
+
+ _short_
+ || tag (byte) =4 || value (16 bit signed) ||
+
+ _int_
+ || tag (byte) =5 || value (32 bit signed) ||
+
+ _long_ (unused!)
+ || tag (byte) =6 || value (64 bit signed) ||
_float_
- || tag (byte) || value (32 bit IEEE 754 ) ||
+ || tag (byte) =7 || value (32 bit IEEE 754 ) ||
_double_
- || tag (byte) || value (64 bit IEEE 754 ) ||
+ || tag (byte) =8 || value (64 bit IEEE 754 ) ||
_string_
- || tag (byte) || length (32 bit signed) || data (utf8 data, variable
length) ||
+ || tag (byte) =9 || length (32 bit signed) || data (utf8 data, variable
length) ||
_java object (this is an instance that exists in the JVM process)_
- || tag (byte) || ref id (32 bit signed) ||
+ || tag (byte) =10 || ref id (32 bit signed) ||
_javascript object (this is an instance that exists in the browser
process)_
- || tag (byte) || ref id (32 bit signed) ||
+ || tag (byte) =11 || ref id (32 bit signed) ||
=== Browser Plugin ===
The browser plugin is responsible for handling and dispatch messages in
the browser and also for interacting with the browser's !JavaScript engine.
Each plugin consists of two conceptual parts: browser-specific
functionality for interacting with the !JavaScript engine and a set of
shared C++ classes that implement the communication channel and message
serialization. We continue to make every effort to implement the plugins
using common and standard APIs (like NPAPI/npruntime), but where that is
insufficient we rely on proprietary (but public) plugin APIs. Below is a
list of the supported browsers and the APIs we are using, or planning to
use.
--~--~---------~--~----~------------~-------~--~----~
http://groups.google.com/group/Google-Web-Toolkit-Contributors
-~----------~----~----~----~------~----~------~--~---
