gecko-dev/java/dom/README

Using the Java DOM API
----------------------

A Java component obtains a org.w3c.dom.Document by registering for
Document load notifications. The Document is passed in along with the
notifications. The preferred way for a Java component to register for
Document load notifications is to register via the DOMAccessor
class. However until OJI is used to obtain JNIEnv one has to apply
two patches

  webshell/src/nsWebShell.cpp.patch
  java/dom/jni/DocumentImpl.java.patch

The first one inits nsJavaDOM component and starts jvm. The second one 
registers a document load listener via DOMAccessor. 
Note:
  any class that implements the DocumentLoadListener interface may
  stand for TestDocLoadListener.
See the section on Building for instructions on how to apply the patches.


Makefiles
---------

You may have to set DEPTH to point to the mozilla CVS workspace root
in Makefile and jni/Makefile. SInce this stuff is not part of the
regular SeaMonkeyBuild, Makefiles are not generated from Makefile.in,
so just go ahead and hack the Makefile.

That is also why I have a separate Makefile.linux for Linux. (Does not
work with Linux... last time I checked, the Blackdown JDK had a
problem creating the JVM in
nsJavaDOMImpl.cpp::Initialize:CreateJavaVM).


Building
--------

After having done a configure at the top level of SeaMonkey, do a make
in the dom and the dom/jni directories. This will copy over a few
header files that are needed by the patch to nsWebShell. You can then
apply the patch to nsWebShell.cpp by executing 

`patch nsWebShell.cpp <nsWebShell.cpp.patch` 

Edit Makefile.in to add -DJAVA_DOM to the list of defines. Then do a
gmake in this directory.

Similarly apply the DocumetnImpl.java patch. Then recompile the
DocumentImpl class. No changes in makefiles needed.

Define JDKHOME so that $JDKHOME/bin points to javac.

You will also need to get the w3c DOM level 2 interfaces from
http://www.w3.org/TR/WD-DOM-Level-2/java-binding.zip
and put the class files in your CLASSPATH.


DOM2 events
------------

At the moment all DOM2 event-related interfaces are present
however they are not fully implemented yet
because Mozilla's core DOM does not support DOM2 events fully. 
Consequences:
  - some methods throws OperationUnsupportedException()
  - Some of key codes defined at DOM2 specs are never returned
     (they are not supported by core DOM)

The basic implementation architecture is following:
   - NodeImpl is extended to support EventTarget interface
   - for every addEventListener call special NativeDOMProxyListener object is 
       created and is registered with Mozilla's DOM 
     It's task is to propagate event notifications from Mozilla's DOM
       to target Java EventListener
   - In order to sucessfully unregister EventListeners we need to 
       save association between java EventListener and corresponding 
       NativeDOMProxyListener object. This is done by storing such
       associations Vector at NodeImpl
   - javaDOMEventsGlobals class is used much like javaDOMGlobals for caching
     (this code may be moved to javaDOMGlobals) 
     


NSPR Logging
------------

The NSPR Log module name is javadom. For instructions on how to enable
logging, see dist/include/prlog.h


Debug output
------------

The debug build of the Java DOM API creates the JVM with the verbose
and the verboseGC options turned on, to help in debugging. It also
creates two files in the current working directory, dom-java.txt and
dom-cpp.txt, which are simple dumps of the DOM, as printed from C++
and from Java. The two should be identical. The code to write these
files is, essentially, my regression test. Feel free to add to it.


OJI
---

Currently the nsJavaDOM component instantiates its own JVM. When an
OJI-compatible JVM is available, we will move over to using it.


Dependencies
------------

Currently tested on Solaris 7 only with Java 2 SDK 1.2.1. egcs-2.91.66, 
Sun Workshop C++ 4.2 and 5.0 have been know to compile this code
fine. gcc-2.8.1 does *not* work. I have not used anything
Java2-specific, and it works with JDK1.1.x too (I have been using JDK
1.1.6 too).


References
----------

I highly recommend reading Sheng Liang's new JNI book.