22 October 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-20021022/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:

/**
 * This class holds the list of registered DOMImplementations. The contents 
 * of the registry are drawn from the System Property 
 * <code>org.w3c.dom.DOMImplementationSourceList</code>, which must contain a 
 * white-space delimited sequence of the names of classes implementing 
 * <code>DOMImplementationSource</code>.
 * Applications may also register DOMImplementationSource
 * implementations by using a method on this class. They may then
 * query instances of the registry for implementations supporting
 * specific features.</p>
 *
 * <p>This provides an application with an implementation-independent 
 * starting point.
 *
 * @see DOMImplementation
 * @see DOMImplementationSource
 */

package org.w3c.dom;

import java.lang.reflect.Method;
import java.lang.reflect.InvocationTargetException;
import java.lang.ClassLoader;
import java.lang.String;
import java.util.StringTokenizer;
import java.util.Enumeration;
import java.util.Hashtable;

import org.w3c.dom.DOMImplementationSource;
import org.w3c.dom.DOMImplementation;

public class DOMImplementationRegistry { 

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

    private Hashtable sources;

    // deny construction by other classes
    private DOMImplementationRegistry() {
    }

    // deny construction by other classes
    private DOMImplementationRegistry(Hashtable srcs) {
        sources = srcs;
    }


    /* 
     * This method queries the System property
     * <code>org.w3c.dom.DOMImplementationSourceList</code>. If it is
     * able to read and parse the property, it attempts to instantiate
     * classes according to each space-delimited substring. Any
     * exceptions it encounters are thrown to the application. An application
     * must call this method before using the class.
     * @return  an initialized instance of DOMImplementationRegistry
     */ 
    public static DOMImplementationRegistry newInstance()       
            throws ClassNotFoundException, InstantiationException, 
            IllegalAccessException
    {
        Hashtable sources = new Hashtable();    

        // fetch system property:
        String p = System.getProperty(PROPERTY);
        if (p != null) {
            StringTokenizer st = new StringTokenizer(p);
            while (st.hasMoreTokens()) {
                String sourceName = st.nextToken();
                // Use context class loader, falling back to Class.forName
                // if and only if this fails...
                Object source = getClass(sourceName).newInstance();
                sources.put(sourceName, source);
            }
        }
        return new DOMImplementationRegistry(sources);
    }


    /**
     * 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 DOMImplementation getDOMImplementation(String features)
            throws ClassNotFoundException,
            InstantiationException, IllegalAccessException, ClassCastException
    {
        Enumeration names = sources.keys();
        String name = null;
        while(names.hasMoreElements()) {
            name = (String)names.nextElement();
            DOMImplementationSource source =
                (DOMImplementationSource) sources.get(name);

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

    /**
     * Register an implementation.
     */
    public void addSource(DOMImplementationSource s)
            throws ClassNotFoundException,
            InstantiationException, IllegalAccessException
    {
        String sourceName = s.getClass().getName(); 
        sources.put(sourceName, s);
    }

    private static Class getClass (String className)
                throws ClassNotFoundException, IllegalAccessException,
                InstantiationException {
        Method m = null;
        ClassLoader cl = null;

        try {
            m = Thread.class.getMethod("getContextClassLoader", null);
        } catch (NoSuchMethodException e) {
            // Assume that we are running JDK 1.1, use the current ClassLoader
            cl = DOMImplementationRegistry.class.getClassLoader();
        }

        if (cl == null ) {
            try {
                cl = (ClassLoader) m.invoke(Thread.currentThread(), null);
            } catch (IllegalAccessException e) {
                // assert(false)
                throw new UnknownError(e.getMessage());
            } catch (InvocationTargetException e) {
                // assert(e.getTargetException() instanceof SecurityException)
                throw new UnknownError(e.getMessage());
            }
        }
        if (cl == null) { 
            // fall back to Class.forName
            return Class.forName(className);
        }
        try { 
            return cl.loadClass(className);
        } catch (ClassNotFoundException e) {
            return Class.forName(className);
        }
    }
}
 

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 String getDocumentURI();
    public void setDocumentURI(String documentURI);

    public Node adoptNode(Node source)
                          throws DOMException;

    public DOMConfiguration getConfig();

    public void normalizeDocument();

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

    // DocumentPosition
    public static final short DOCUMENT_POSITION_DISCONNECTED = 0x00;
    public static final short DOCUMENT_POSITION_PRECEDING = 0x01;
    public static final short DOCUMENT_POSITION_FOLLOWING = 0x02;
    public static final short DOCUMENT_POSITION_CONTAINS = 0x04;
    public static final short DOCUMENT_POSITION_IS_CONTAINED = 0x08;
    public static final short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x10;

    public short compareDocumentPosition(Node other)
                                         throws DOMException;

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

    public boolean isSameNode(Node other);

    public String lookupPrefix(String namespaceURI);

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

    public TypeInfo getSchemaType();

    public boolean getIsId();

}

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

    public TypeInfo getSchemaType();

    public void setIdAttribute(String name)
                               throws DOMException;

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

    public void setIdAttributeNode(Attr idAttr)
                                   throws DOMException;

}

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

package org.w3c.dom;

public interface TypeInfo {
    public String getName();

    public String getNamespace();

}

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 {
    // ErrorSeverity
    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 String getType();

    public Object getRelatedException();

    public Object getRelatedData();

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

    public String getUri();

}

org/w3c/dom/DOMConfiguration.java:

package org.w3c.dom;

public interface DOMConfiguration {
    public void setBooleanParameter(String name, 
                                    boolean state)
                                    throws DOMException;

    public boolean getBooleanParameter(String name)
                                       throws DOMException;

    public boolean canSetBooleanParameter(String name, 
                                          boolean state);

    public void setParameter(String name, 
                             Object value)
                             throws DOMException;

    public Object getParameter(String name)
                               throws DOMException;

    public boolean canSetParameter(String name, 
                                   Object value);

}

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;

}