09 April 2002

Appendix E: 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/2002/WD-DOM-Level-3-Core-20020409/java-binding.zip

E.1: Java Binding Extension

This section defines the DOMImplementationRegistry object, discussed in Bootstrapping, for Java.

The DOMImplementationRegistry 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>Subsequently, 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 A string that specifies which features are required.
     *                 This is a space separated list in which each feature is
     *                 specified by its name optionally followed by a space
     *                 and a version number.
     *                 This is something like: "XML 1.0 Traversal Events 2.0"
     * @return An implementation that has the desired features, or
     *   <code>null</code> if this source has none.
     */
    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.getDOMImplementation(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());
    }
}
 

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.
Resolution: Proposed: It's ok.
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.
Resolution: Proposed: It's ok.
Issue Level-3-Java-Bootstrap-6:
Should "*" given as the version number be interpreted as "any version". hasFeature() does not allow this, it requires a specific version to be given.
Resolution: No. (telcon xxxx)

E.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;
    public static final short VALIDATION_ERR            = 16;

}

org/w3c/dom/DOMImplementationSource.java:

package org.w3c.dom;

public interface DOMImplementationSource {
    public DOMImplementation getDOMImplementation(String features);

}

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 getInterface(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 String getVersion();
    public void setVersion(String version)
                                  throws DOMException;

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

    public DOMErrorHandler getErrorHandler();
    public void setErrorHandler(DOMErrorHandler errorHandler);

    public String getDocumentURI();
    public void setDocumentURI(String documentURI);

    public Node adoptNode(Node source)
                          throws DOMException;

    public void normalizeDocument();

    public boolean canSetNormalizationFeature(String name, 
                                              boolean state);

    public void setNormalizationFeature(String name, 
                                        boolean state)
                                        throws DOMException;

    public boolean getNormalizationFeature(String name)
                                           throws DOMException;

    public Node renameNode(Node n, 
                           String namespaceURI, 
                           String name)
                           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();

    // TreePosition
    public static final short TREE_POSITION_PRECEDING   = 0x01;
    public static final short TREE_POSITION_FOLLOWING   = 0x02;
    public static final short TREE_POSITION_ANCESTOR    = 0x04;
    public static final short TREE_POSITION_DESCENDANT  = 0x08;
    public static final short TREE_POSITION_EQUIVALENT  = 0x10;
    public static final short TREE_POSITION_SAME_NODE   = 0x20;
    public static final short TREE_POSITION_DISCONNECTED = 0x00;

    public short compareTreePosition(Node other);

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

    public boolean isSameNode(Node other);

    public String lookupNamespacePrefix(String namespaceURI, 
                                        boolean useDefault);

    public boolean isDefaultNamespace(String namespaceURI);

    public String lookupNamespaceURI(String prefix);

    public boolean isEqualNode(Node arg);

    public Node getInterface(String feature);

    public Object setUserData(String key, 
                              Object data, 
                              UserDataHandler handler);

    public Object getUserData(String key);

}

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/UserDataHandler.java:

package org.w3c.dom;

public interface UserDataHandler {
    // OperationType
    public static final short NODE_CLONED               = 1;
    public static final short NODE_IMPORTED             = 2;
    public static final short NODE_DELETED              = 3;
    public static final short NODE_RENAMED              = 4;

    public void handle(short operation, 
                       String key, 
                       Object data, 
                       Node src, 
                       Node dst);

}

org/w3c/dom/DOMError.java:

package org.w3c.dom;

public interface DOMError {
    public static final short SEVERITY_WARNING          = 0;
    public static final short SEVERITY_ERROR            = 1;
    public static final short SEVERITY_FATAL_ERROR      = 2;
    public short getSeverity();

    public String getMessage();

    public Object getRelatedException();

    public DOMLocator getLocation();

}

org/w3c/dom/DOMErrorHandler.java:

package org.w3c.dom;

public interface DOMErrorHandler {
    public boolean handleError(DOMError error);

}

org/w3c/dom/DOMLocator.java:

package org.w3c.dom;

public interface DOMLocator {
    public int getLineNumber();

    public int getColumnNumber();

    public int getOffset();

    public Node getErrorNode();

    public String getUri();

}

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;

}