gecko-dev/java/dom/README

Sources
=======

The sources are located in mozilla/java/dom.
Subdirectories 

    classes
    jni
    src
    tests

contain Java sources, Java native methods implementation, 
native c++ code and Java DOM API tests respectively.

Note: 
   Sources that work with mozilla PR1 and earlier
   versions should be checked out using DOM_PR1 tag.

   No tags are needed for the sources that work with
   the latest mozilla tree.

Building
========

   Requirenments:
   --------------
     Current mozilla build
     JDK1.2 or JDK1.3 
     Perl 5 must be in your path
     JDKHOME environment variable set to your JDK dir
     CLASSPATH environment cvariable set to contain 
	org.w3c.dom classes. The sources can be found at	
        http://www.w3.org/TR/2000/CR-DOM-Level-2-20000307/java-binding.html
	(for mozilla PR1 and earlie versions)
        http://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/java-binding.html
	(for the latest mozilla)

     Solaris specific
     ----------------
	Add following directories to LD_LIBRARY_PATH environment variable:
          $MOZILLA_FIVE_HOME
          $JDKHOME/jre/lib/$HOSTTYPE/native_threads
          $JDKHOME/jre/lib/$HOSTTYPE/classic
          $JDKHOME/jre/lib/$HOSTTYPE/

	goto mozilla/java/dom directory and type "gmake"
        

     Windows NT specific
     -------------------
	To enable OJI usage set environment variable JAVA_DOM_OJI_ENABLE=1
	Add following directories to PATH environment variable:
	  %MOZILLA_FIVE_HOME%
	  %JDKHOME%\jre\bin\classic (only in case you don't use OJI)

	goto mozilla/java/dom directory and type "nmake /f makefile.win"
        

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, this is possible only if OJI usage is enabled. This works
on Windows NT platform.

On Solaris currently the nsJavaDOM component instantiates its own JVM.
When an OJI-compatible JVM is available, we will move over to using it.
So, one has to apply two patches to

  mozilla/webshell/src/nsWebShell.cpp
  mozilla/java/dom/classes/org/mozilla/dom/DOMAccessor.java

They can be found at mozilla/java/dom directory.
The first one inits nsJavaDOM component and adds it as a
document load observer listener.

The second one registers a document load listener via DOMAccessor. 
Note:
  any class that implements the DocumentLoadListener interface may
  stand for GenericDocLoadListener.

After applying a patch to nsWebShell.cpp edit 
mozilla/webshell/src/Makefile.in to add -DJAVA_DOM to the list of 
defines. Then do a gmake in this directory.

After applying a patch to DOMAccessor.java go to mozilla/java/dom/classes
and do a gmake. No changes in makefiles are needed.

You can find examples of Java DOM API usage in 

   mozilla/java/dom/classes/org/mozilla/dom/util
   mozilla/java/dom/tests/src/applets


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()

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 successfully 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.


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.