05 June 2001

Appendix D: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model Core.

The Java files are also available as http://www.w3.org/TR/2001/WD-DOM-Level-3-Core-20010605/java-binding.zip

D.1: Java Binding Extension

Because the DOM only defines interfaces, applications have to rely on some implementation dependent API to start from. Typically, a Java application starts with a line of code such as:

    DOMImplementation impl = org.apache.xerces.dom.DOMImplementationImpl.getDOMImplementation();
   

Since there is no language independent way of "bootstrapping" a DOM implementation, this section describes a solution for Java. Hopefully, similar solutions could be defined for other language bindings.

The following defines a Java class called DOMImplementationRegistry from which an application can get, in a standard way a reference to a DOMImplementation, based on the set of features that is desired. The registry does not actually have a direct reference to the DOMImplementation objects. Instead it has a list of DOMImplementationSource objects to which the request can be forwarded. This allows DOMImplementation objects to be constructed dynamically based on the set of requested features. The registry is first initialized by the application or the implementation, depending on the context, through the Java system property "org.w3c.dom.DOMImplementationSourceList". The value of this property is a space separated list of names of available classes implementing the DOMImplementationSource interface.

org/w3c/dom/DOMImplementationRegistry.java:

package org.w3c.dom; 

import java.util.StringTokenizer;
import java.util.Vector;

/**
 * This class holds the list of registered DOMImplementations. It is first
 * initialized based on the content of the space separated list of classnames
 * contained in the System Property "org.w3c.dom.DOMImplementationSourceList".
 *
 * <p>Subsequentally, additional sources can be registered and implementations
 * can be queried based on a list of requested features.
 *
 * <p>This provides an application with an implementation independent starting
 * point.
 *
 * @see DOMImplementation
 * @see DOMImplementationSource
 */
public class DOMImplementationRegistry 
{ 

    // The system property to specify the DOMImplementationSource class names. 
    public static String PROPERTY = "org.w3c.dom.DOMImplementationSourceList";

    private static Vector sources = new Vector();
    private static boolean initialized = false;

    private static void initialize() throws ClassNotFoundException,
        InstantiationException, IllegalAccessException
    {
        initialized = true;
        String p = System.getProperty(PROPERTY);
        if (p == null) {
            return;
        }
        StringTokenizer st = new StringTokenizer(p);
        while (st.hasMoreTokens()) {
            Object source = Class.forName(st.nextToken()).newInstance();
            sources.addElement(source);
        }
    }

    /**
     * Return the first registered implementation that has the desired features,
     * or null if none is found.
     *
     * @param features The space separated list of requested features
     *                 along with their version numbers.<br>
     *                 This is something like: "XML 1.0 Traversal 2.0"
     */
    public static DOMImplementation getDOMImplementation(String features)
        throws ClassNotFoundException,
        InstantiationException, IllegalAccessException
    {
        if (!initialized) {
            initialize();
        }
        int len = sources.size(); 
        for (int i = 0; i < len; i++) {
            DOMImplementationSource source =
                (DOMImplementationSource) sources.elementAt(i);

            DOMImplementation impl = source.byFeature(features);
            if (impl != null) {
                return impl;
            }
        }
        return null;
    }

    /**
     * Register an implementation.
     */
    public static void addSource(DOMImplementationSource s)
        throws ClassNotFoundException,
        InstantiationException, IllegalAccessException
    {
        if (!initialized) {
            initialize();
        }
        sources.addElement(s);
        // update system property accordingly
        StringBuffer b = new StringBuffer(System.getProperty(PROPERTY));
        b.append(" " + s.getClass().getName());
        System.setProperty(PROPERTY, b.toString());
    }
}
   

The DOMImplementationSource interface accepts a string containing a list of space-separated feature strings and returns a DOMImplementation which implements the specified features or null if no DOMImplementation is available which implements the specified features.

Any number of DOMImplementationSource classes can be provided and registered. A source may return one or more DOMImplementation singletons or construct new DOMImplementation objects, depending upon whether the requested features require specialized state in the DOMImplementation object.

org/w3c/dom/DOMImplementationSource.java:

package org.w3c.dom;

interface DOMImplementationSource {

    /**
     * Return an implementation that has the desired features,
     * or null if this source finds none.
     *
     * @param features The space separated list of requested features
     *                 along with their version numbers.<br>
     *                 This is something like: "XML 1.0 Traversal 2.0"
     */
    public DOMImplementation byFeature(String features); 

}
   

With this, the first line of an application typically becomes something like (modulo exception handling):

    DOMImplementation impl = DOMImplementationRegistry.getDOMImplementation("XML 1.0");
   
Issue Level-3-Java-Bootstrap-1:
Should this provides for handling more than one implementation at a time?
Resolution: Yes.
Issue Level-3-Java-Bootstrap-2:
Should this be even simpler and force the implementation to provide this class (and not necessarily rely on any system property)?
Resolution: No.
Issue Level-3-Java-Bootstrap-3:
This requires all DOMImplementationSources to be pre-instantiated.
Issue Level-3-Java-Bootstrap-4:
Some people may like to be able to enumerate available implementations. DOMImplementation objects may be too dynamic to enumerate. We should explore any significant use case that cannot be solved by this proposal.
Resolution: No real need. Additional features can be used to further differentiate implementations.
Issue Level-3-Java-Bootstrap-5:
A space-separated feature string may not be the optimal way to pass a feature list. It was motivated by the lack of an array construct.
Issue Level-3-Java-Bootstrap-6:
Should "*" given as the version number be interprated as "any version". hasFeature() does not allow this, it requires a specific version to be given.

D.2: Other Core interfaces

org/w3c/dom/DOMException.java:

package org.w3c.dom;

public class DOMException extends RuntimeException {
    public DOMException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // ExceptionCode
    public static final short INDEX_SIZE_ERR            = 1;
    public static final short DOMSTRING_SIZE_ERR        = 2;
    public static final short HIERARCHY_REQUEST_ERR     = 3;
    public static final short WRONG_DOCUMENT_ERR        = 4;
    public static final short INVALID_CHARACTER_ERR     = 5;
    public static final short NO_DATA_ALLOWED_ERR       = 6;
    public static final short NO_MODIFICATION_ALLOWED_ERR = 7;
    public static final short NOT_FOUND_ERR             = 8;
    public static final short NOT_SUPPORTED_ERR         = 9;
    public static final short INUSE_ATTRIBUTE_ERR       = 10;
    public static final short INVALID_STATE_ERR         = 11;
    public static final short SYNTAX_ERR                = 12;
    public static final short INVALID_MODIFICATION_ERR  = 13;
    public static final short NAMESPACE_ERR             = 14;
    public static final short INVALID_ACCESS_ERR        = 15;

}

org/w3c/dom/DOMImplementation.java:

package org.w3c.dom;

public interface DOMImplementation {
    public boolean hasFeature(String feature, 
                              String version);

    public DocumentType createDocumentType(String qualifiedName, 
                                           String publicId, 
                                           String systemId)
                                           throws DOMException;

    public Document createDocument(String namespaceURI, 
                                   String qualifiedName, 
                                   DocumentType doctype)
                                   throws DOMException;

    public DOMImplementation getAs(String feature);

}

org/w3c/dom/DocumentFragment.java:

package org.w3c.dom;

public interface DocumentFragment extends Node {
}

org/w3c/dom/Document.java:

package org.w3c.dom;

public interface Document extends Node {
    public DocumentType getDoctype();

    public DOMImplementation getImplementation();

    public Element getDocumentElement();

    public Element createElement(String tagName)
                                 throws DOMException;

    public DocumentFragment createDocumentFragment();

    public Text createTextNode(String data);

    public Comment createComment(String data);

    public CDATASection createCDATASection(String data)
                                           throws DOMException;

    public ProcessingInstruction createProcessingInstruction(String target, 
                                                             String data)
                                                             throws DOMException;

    public Attr createAttribute(String name)
                                throws DOMException;

    public EntityReference createEntityReference(String name)
                                                 throws DOMException;

    public NodeList getElementsByTagName(String tagname);

    public Node importNode(Node importedNode, 
                           boolean deep)
                           throws DOMException;

    public Element createElementNS(String namespaceURI, 
                                   String qualifiedName)
                                   throws DOMException;

    public Attr createAttributeNS(String namespaceURI, 
                                  String qualifiedName)
                                  throws DOMException;

    public NodeList getElementsByTagNameNS(String namespaceURI, 
                                           String localName);

    public Element getElementById(String elementId);

    public String getActualEncoding();
    public void setActualEncoding(String actualEncoding);

    public String getEncoding();
    public void setEncoding(String encoding);

    public boolean getStandalone();
    public void setStandalone(boolean standalone);

    public boolean getStrictErrorChecking();
    public void setStrictErrorChecking(boolean strictErrorChecking);

    public String getVersion();
    public void setVersion(String version);

    public Node adoptNode(Node source)
                          throws DOMException;

    public void setBaseURI(String baseURI)
                           throws DOMException;

}

org/w3c/dom/Node.java:

package org.w3c.dom;

public interface Node {
    // NodeType
    public static final short ELEMENT_NODE              = 1;
    public static final short ATTRIBUTE_NODE            = 2;
    public static final short TEXT_NODE                 = 3;
    public static final short CDATA_SECTION_NODE        = 4;
    public static final short ENTITY_REFERENCE_NODE     = 5;
    public static final short ENTITY_NODE               = 6;
    public static final short PROCESSING_INSTRUCTION_NODE = 7;
    public static final short COMMENT_NODE              = 8;
    public static final short DOCUMENT_NODE             = 9;
    public static final short DOCUMENT_TYPE_NODE        = 10;
    public static final short DOCUMENT_FRAGMENT_NODE    = 11;
    public static final short NOTATION_NODE             = 12;

    public String getNodeName();

    public String getNodeValue()
                           throws DOMException;
    public void setNodeValue(String nodeValue)
                           throws DOMException;

    public short getNodeType();

    public Node getParentNode();

    public NodeList getChildNodes();

    public Node getFirstChild();

    public Node getLastChild();

    public Node getPreviousSibling();

    public Node getNextSibling();

    public NamedNodeMap getAttributes();

    public Document getOwnerDocument();

    public Node insertBefore(Node newChild, 
                             Node refChild)
                             throws DOMException;

    public Node replaceChild(Node newChild, 
                             Node oldChild)
                             throws DOMException;

    public Node removeChild(Node oldChild)
                            throws DOMException;

    public Node appendChild(Node newChild)
                            throws DOMException;

    public boolean hasChildNodes();

    public Node cloneNode(boolean deep);

    public void normalize();

    public boolean isSupported(String feature, 
                               String version);

    public String getNamespaceURI();

    public String getPrefix();
    public void setPrefix(String prefix)
                               throws DOMException;

    public String getLocalName();

    public boolean hasAttributes();

    public String getBaseURI();


    // _DocumentOrder
    public static final short DOCUMENT_ORDER_PRECEDING = 1;
    public static final short DOCUMENT_ORDER_FOLLOWING = 2;
    public static final short DOCUMENT_ORDER_SAME      = 3;
    public static final short DOCUMENT_ORDER_UNORDERED = 4;

    public short compareDocumentOrder(Node other)
                                      throws DOMException;


    // _TreePosition
    public static final short TREE_POSITION_PRECEDING  = 1;
    public static final short TREE_POSITION_FOLLOWING  = 2;
    public static final short TREE_POSITION_ANCESTOR   = 3;
    public static final short TREE_POSITION_DESCENDANT = 4;
    public static final short TREE_POSITION_SAME       = 5;
    public static final short TREE_POSITION_UNORDERED  = 6;

    public short compareTreePosition(Node other)
                                     throws DOMException;

    public String getTextContent();
    public void setTextContent(String textContent);

    public boolean isSameNode(Node other);

    public String lookupNamespacePrefix(String namespaceURI);

    public String lookupNamespaceURI(String prefix);

    public void normalizeNS();

    public Object getKey();

    public boolean equalsNode(Node arg, 
                              boolean deep);

    public Node getAs(String feature);

}

org/w3c/dom/NodeList.java:

package org.w3c.dom;

public interface NodeList {
    public Node item(int index);

    public int getLength();

}

org/w3c/dom/NamedNodeMap.java:

package org.w3c.dom;

public interface NamedNodeMap {
    public Node getNamedItem(String name);

    public Node setNamedItem(Node arg)
                             throws DOMException;

    public Node removeNamedItem(String name)
                                throws DOMException;

    public Node item(int index);

    public int getLength();

    public Node getNamedItemNS(String namespaceURI, 
                               String localName);

    public Node setNamedItemNS(Node arg)
                               throws DOMException;

    public Node removeNamedItemNS(String namespaceURI, 
                                  String localName)
                                  throws DOMException;

}

org/w3c/dom/CharacterData.java:

package org.w3c.dom;

public interface CharacterData extends Node {
    public String getData()
                                  throws DOMException;
    public void setData(String data)
                                  throws DOMException;

    public int getLength();

    public String substringData(int offset, 
                                int count)
                                throws DOMException;

    public void appendData(String arg)
                           throws DOMException;

    public void insertData(int offset, 
                           String arg)
                           throws DOMException;

    public void deleteData(int offset, 
                           int count)
                           throws DOMException;

    public void replaceData(int offset, 
                            int count, 
                            String arg)
                            throws DOMException;

}

org/w3c/dom/Attr.java:

package org.w3c.dom;

public interface Attr extends Node {
    public String getName();

    public boolean getSpecified();

    public String getValue();
    public void setValue(String value)
                            throws DOMException;

    public Element getOwnerElement();

}

org/w3c/dom/Element.java:

package org.w3c.dom;

public interface Element extends Node {
    public String getTagName();

    public String getAttribute(String name);

    public void setAttribute(String name, 
                             String value)
                             throws DOMException;

    public void removeAttribute(String name)
                                throws DOMException;

    public Attr getAttributeNode(String name);

    public Attr setAttributeNode(Attr newAttr)
                                 throws DOMException;

    public Attr removeAttributeNode(Attr oldAttr)
                                    throws DOMException;

    public NodeList getElementsByTagName(String name);

    public String getAttributeNS(String namespaceURI, 
                                 String localName);

    public void setAttributeNS(String namespaceURI, 
                               String qualifiedName, 
                               String value)
                               throws DOMException;

    public void removeAttributeNS(String namespaceURI, 
                                  String localName)
                                  throws DOMException;

    public Attr getAttributeNodeNS(String namespaceURI, 
                                   String localName);

    public Attr setAttributeNodeNS(Attr newAttr)
                                   throws DOMException;

    public NodeList getElementsByTagNameNS(String namespaceURI, 
                                           String localName);

    public boolean hasAttribute(String name);

    public boolean hasAttributeNS(String namespaceURI, 
                                  String localName);

}

org/w3c/dom/Text.java:

package org.w3c.dom;

public interface Text extends CharacterData {
    public Text splitText(int offset)
                          throws DOMException;

    public boolean getIsWhitespaceInElementContent();

    public String getWholeText();

    public Text replaceWholeText(String content)
                                 throws DOMException;

}

org/w3c/dom/Comment.java:

package org.w3c.dom;

public interface Comment extends CharacterData {
}

org/w3c/dom/CDATASection.java:

package org.w3c.dom;

public interface CDATASection extends Text {
}

org/w3c/dom/DocumentType.java:

package org.w3c.dom;

public interface DocumentType extends Node {
    public String getName();

    public NamedNodeMap getEntities();

    public NamedNodeMap getNotations();

    public String getPublicId();

    public String getSystemId();

    public String getInternalSubset();

}

org/w3c/dom/Notation.java:

package org.w3c.dom;

public interface Notation extends Node {
    public String getPublicId();

    public String getSystemId();

}

org/w3c/dom/Entity.java:

package org.w3c.dom;

public interface Entity extends Node {
    public String getPublicId();

    public String getSystemId();

    public String getNotationName();

    public String getActualEncoding();
    public void setActualEncoding(String actualEncoding);

    public String getEncoding();
    public void setEncoding(String encoding);

    public String getVersion();
    public void setVersion(String version);

}

org/w3c/dom/EntityReference.java:

package org.w3c.dom;

public interface EntityReference extends Node {
}

org/w3c/dom/ProcessingInstruction.java:

package org.w3c.dom;

public interface ProcessingInstruction extends Node {
    public String getTarget();

    public String getData();
    public void setData(String data)
                                 throws DOMException;

}