gecko-dev/java/dom/blackconnect/dom

About the project
=================

The goal is to provide access to the DOM API provided
by the mozilla browser using the java to xpcom bridge(Blackconnect).

The implementation currently consists of stubs between mozilla core DOM 
interfaces and  core DOM interfaces defined in dom.idl (blackconnect
requires scriptable interfaces), java interfaces generated from
dom.idl and a DOMAccessor as an example of using the DOM API.


Sources
=======

The sources are located in mozilla/java/dom
Subdirectories 

   classes  - contains classes generated automatically from
              idl definition of core DOM interfaces (stubs/dom.idl)             
              using xpidl compiler (mozilla/java/xpcom/java/xpidl)
              and a sample DOMTreeDumper class that dumps an html
              document source using its DOM tree.

   stubs    - stubs between mozilla core DOM interfaces and 
              core DOM interfaces defined in dom.idl

   accessor - a sample java component which demonstrates the
              use of the DOM API from java via blackconnect


Building
========
   Requirenments:
   --------------
   - you need to build the blackconnect bridge
     mozilla/java/xpcom and to have all the
     environment variables set required for
     building blackconnect
   - mozilla_Netscape_20000922_BRANCH mozilla build
   - JDK1.3 
   - Perl 5 must be in your path
   - JDKHOME environment variable set to your JDK dir
   - CLASSPATH environment variable set to contain 
     mozilla/dist/classes directory and 
	 org.w3c.dom.DOMException class. The source can be found at	
     http://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/java-binding.html

   Solaris and Linux:
   ------------------
   goto mozilla/java/dom directory and type "gmake"

   Windows NT:
   -----------
   goto mozilla/java/dom directory and type "nmake /f makefile.win"


Running
=======
   After building a component run a mozilla browser. The document
   sources will be dumped into console.

Using the Java DOM API
======================
   
   Directory accessor contains a sample java component which
   becomes a document load listener and dumps sources of documents 
   being displayed in mozilla using their DOM trees.

   if you have a C++ pointer to any core DOM mozilla interface nsIDOM<...>
   you need to wrap it into a corresponding scriptable stub interface
   bc<...> (e.g. nsIDOMDocument into bcDocument using 
   bcDocument::bcDocument(nsIDOMDocument* ptr) constructor) and you
   can use it to pass to java as a class instance which implements 
   a org.mozill.dom.Document interface using blackconnect.

   An example works this way: 
   A C++ implementation of a component gets a call via NSGetModule method, 
   registrates itself as a document load listener, gets a reference to
   a java component and then pass references to all documents being 
   displayed into a java component.

Notes:
   - Since exception passing mechanism is not yet implemented in blackconnect
     no DOMExceptions are raised.
    
   - The mechanism used in a sample allows to modify any documents in any
     way provided by the DOM API, so there are no security restrictions at all.