Class DTMManager

  • Direct Known Subclasses:
    DTMManagerDefault, XPathContext

    public abstract class DTMManager
    extends java.lang.Object
    A DTMManager instance can be used to create DTM and DTMIterator objects, and manage the DTM objects in the system.

    The system property that determines which Factory implementation to create is named "org.apache.xml.utils.DTMFactory". This property names a concrete subclass of the DTMFactory abstract class. If the property is not defined, a platform default is be used.

    An instance of this class must be safe to use across thread instances. It is expected that a client will create a single instance of a DTMManager to use across multiple threads. This will allow sharing of DTMs across multiple processes.

    Note: this class is incomplete right now. It will be pretty much modeled after javax.xml.transform.TransformerFactory in terms of its factory support.

    State: In progress!!

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int IDENT_DTM_DEFAULT
      When this bitmask is ANDed with a DTM node handle number, the result is the DTM's document identity number.
      static int IDENT_DTM_NODE_BITS
      This value, set at compile time, controls how many bits of the DTM node identifier numbers are used to identify a node within a document, and thus sets the maximum number of nodes per document.
      static int IDENT_MAX_DTMS
      This is the maximum number of DTMs available.
      static int IDENT_NODE_DEFAULT
      When this bitmask is ANDed with a DTM node handle number, the result is the low bits of the node's index number within that DTM.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected DTMManager()
      Default constructor is protected on purpose.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract DTM getDTM​(int nodeHandle)
      Get the instance of DTM that "owns" a node handle.
      abstract DTM getDTM​(javax.xml.transform.Source source, boolean unique, boolean incremental, boolean doIndexing)
      Get an instance of a DTM, loaded with the content from the specified source.
      abstract int getDTMHandleFromNode​(org.w3c.dom.Node node)
      Given a W3C DOM node, try and return a DTM handle.
      static DTMManager newInstance()
      Obtain a new instance of a DTMManager.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • IDENT_DTM_NODE_BITS

        public static final int IDENT_DTM_NODE_BITS
        This value, set at compile time, controls how many bits of the DTM node identifier numbers are used to identify a node within a document, and thus sets the maximum number of nodes per document. The remaining bits are used to identify the DTM document which contains this node.

        If you change IDENT_DTM_NODE_BITS, be sure to rebuild _ALL_ the files which use it... including the IDKey testcases.

        (FuncGenerateKey currently uses the node identifier directly and thus is affected when this changes. The IDKEY results will still be _correct_ (presuming no other breakage), but simple equality comparison against the previous "golden" files will probably complain.)

        See Also:
        Constant Field Values
      • IDENT_NODE_DEFAULT

        public static final int IDENT_NODE_DEFAULT
        When this bitmask is ANDed with a DTM node handle number, the result is the low bits of the node's index number within that DTM. To obtain the high bits, add the DTM ID portion's offset as assigned in the DTM Manager.
        See Also:
        Constant Field Values
      • IDENT_DTM_DEFAULT

        public static final int IDENT_DTM_DEFAULT
        When this bitmask is ANDed with a DTM node handle number, the result is the DTM's document identity number.
        See Also:
        Constant Field Values
      • IDENT_MAX_DTMS

        public static final int IDENT_MAX_DTMS
        This is the maximum number of DTMs available. The highest DTM is one less than this.
        See Also:
        Constant Field Values
    • Constructor Detail

      • DTMManager

        protected DTMManager()
        Default constructor is protected on purpose.
    • Method Detail

      • newInstance

        public static DTMManager newInstance()
        Obtain a new instance of a DTMManager. This static method creates a new factory instance This method uses the following ordered lookup procedure to determine the DTMManager implementation class to load:
        • Use the org.htmlunit.xpath.xml.dtm.DTMManager system property.
        • Use the JAVA_HOME(the parent directory where jdk is installed)/lib/xalan.properties for a property file that contains the name of the implementation class keyed on the same value as the system property defined above.
        • Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/org.htmlunit.xpath.xml.dtm.DTMManager in jars available to the runtime.
        • Use the default DTMManager classname, which is org.htmlunit.xpath.xml.dtm.ref.DTMManagerDefault.
        Once an application has obtained a reference to a DTMManager it can use the factory to configure and obtain parser instances.
        Returns:
        new DTMManager instance, never null.
      • getDTM

        public abstract DTM getDTM​(javax.xml.transform.Source source,
                                   boolean unique,
                                   boolean incremental,
                                   boolean doIndexing)
        Get an instance of a DTM, loaded with the content from the specified source. If the unique flag is true, a new instance will always be returned. Otherwise it is up to the DTMManager to return a new instance or an instance that it already created and may be being used by someone else.

        (More parameters may eventually need to be added for error handling and entity resolution, and to better control selection of implementations.)

        Parameters:
        source - the specification of the source object, which may be null, in which case it is assumed that node construction will take by some other means.
        unique - true if the returned DTM must be unique, probably because it is going to be mutated.
        incremental - true if the DTM should be built incrementally, if possible.
        doIndexing - true if the caller considers it worth it to use indexing schemes.
        Returns:
        a non-null DTM reference.
      • getDTM

        public abstract DTM getDTM​(int nodeHandle)
        Get the instance of DTM that "owns" a node handle.
        Parameters:
        nodeHandle - the nodeHandle.
        Returns:
        a non-null DTM reference.
      • getDTMHandleFromNode

        public abstract int getDTMHandleFromNode​(org.w3c.dom.Node node)
        Given a W3C DOM node, try and return a DTM handle. Note: calling this may be non-optimal.
        Parameters:
        node - Non-null reference to a DOM node.
        Returns:
        a valid DTM handle.