In JAXP1.0.1 any entities became nodes with type ENTITY_REFERENCE_NODE.

In Merlin (which has some classes/packages of the same name as JAXP
classes) the entities become part of the surrounding text node.

This makes it impossible to interpret entities in any special way
(as my application does; it wants to substitute various values into
output text for the entities, values that are other than what the
DTD declares the entity value to be; I can explain this in more
detail to anybody that's interested, it's a real interesting app).

The following example doesn't demonstrate what my application does,
but it does illustrate the difference between JAXP 1.0.1 and Merlin.
The enclosed application contains a simple tree dumper routine to
display the DOM tree contents.

Given this XML input
====================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE doc SYSTEM 'test.dtd'>
<doc>
  <p>This is some text and an &entity; and more text</p>
  &entity;
  &entity;text
</doc>

And the DTD
===========
<!ELEMENT doc (#PCDATA)>
<!ELEMENT p (#PCDATA)>
<!ENTITY entity "entity-ref">

JAXP 1.0.1 outputs
==================
% /usr/local/java/jdk1.3/solaris/bin/java -classpath .:/home/dherron/work/jaxp1.0.1/jaxp.jar:/home/dherron/work/jaxp1.0.1/parser.jar EntityBug test.xml
name=doc; type=1; value=null
    name=#text; type=3; value=
  
    name=p; type=1; value=null
        name=#text; type=3; value=This is some text and an
        name=entity; type=5; value=null
            name=#text; type=3; value=entity-ref
        name=#text; type=3; value= and more text
    name=#text; type=3; value=
  
    name=entity; type=5; value=null
        name=#text; type=3; value=entity-ref
    name=#text; type=3; value=
  
    name=entity; type=5; value=null
        name=#text; type=3; value=entity-ref
    name=#text; type=3; value=text

Merlin output
=============
java EntityBug test.xml
name=doc; type=1; value=null
    name=#text; type=3; value=
  
    name=p; type=1; value=null
        name=#text; type=3; value=This is some text and an entity-ref and more text
    name=#text; type=3; value=
  entity-ref
  entity-reftext


Source code
===========

import org.w3c.dom.*;
//import javax.xml.parsers.*;
import java.io.File;

import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.DocumentBuilder;

public class EntityBug {

  String fn;

  DocumentBuilderFactory factory = null;
  DocumentBuilder builder = null;
  Document document = null;

  public EntityBug(String fn) {
    this.fn = fn;
    factory = DocumentBuilderFactory.newInstance();
    try {
      builder = factory.newDocumentBuilder();
      document = builder.parse( new File(fn) );
      dumpTree(document.getDocumentElement());
    } catch (Exception e) {
      System.out.println(e.toString());
      e.printStackTrace();
    }
  }

  // dumpTree - pretty-print dump of an XML tree.

  void dumpTree(Node n) { dumpTree(n, 0); }

  void dumpTree(Node n, int indent) {
    if (n == null) { System.out.println("dumptree null node\n"); return; }
    for (; n != null; n = n.getNextSibling()) {
      // indent for this node
      for (int i = 0; i < indent; i++) System.out.print(" ");
      // print info on this node
      System.out.println("name=" + n.getNodeName() +
"; type=" + Short.toString(n.getNodeType()) +
"; value=" + n.getNodeValue());
      // if any children, recurse
      Node n2 = n.getFirstChild();
      if (n2 != null) dumpTree(n2, indent + 4);
    }
  }
    
  public static void main(String args[]) {
    new EntityBug(args[0]);
  }

}