org.apache.xml.dtm

## Class DTMManager

- java.lang.Object
- - org.apache.xml.dtm.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 <emph>must</emph> 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
`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.
`boolean` `m_incremental`
`boolean` `m_source_location`

### Method Summary

Methods
`abstract DTM` `createDocumentFragment()` Creates a DTM representing an empty `DocumentFragment` object.
`abstract DTMIterator` `createDTMIterator(int node)` Create a new `DTMIterator` that holds exactly one node.
`abstract DTMIterator` `createDTMIterator(int whatToShow, DTMFilter filter, boolean entityReferenceExpansion)` Create a new `DTMIterator` based only on a whatToShow and a DTMFilter.
`abstract DTMIterator` `createDTMIterator(java.lang.Object xpathCompiler, int pos)` Create a new `DTMIterator` based on an XPath UnionExpr.
`abstract DTMIterator` `createDTMIterator(java.lang.String xpathString, PrefixResolver presolver)` Create a new `DTMIterator` based on an XPath UnionExpr.
`abstract DTM` `getDTM(int nodeHandle)` Get the instance of DTM that "owns" a node handle.
`abstract DTM` `getDTM(Source source, boolean unique, DTMWSFilter whiteSpaceFilter, boolean incremental, boolean doIndexing)` Get an instance of a DTM, loaded with the content from the specified source.
`abstract int` `getDTMHandleFromNode(Node node)` Given a W3C DOM node, try and return a DTM handle.
`abstract int` `getDTMIdentity(DTM dtm)` %TBD% Doc NEEDSDOC @param dtm NEEDSDOC ($objectName$) @return
`int` `getDTMIdentityMask()` %TBD% Doc NEEDSDOC ($objectName$) @return
`boolean` `getIncremental()` Get a flag indicating whether an incremental transform is desired
`int` `getNodeIdentityMask()` %TBD% Doc NEEDSDOC ($objectName$) @return
`boolean` `getSource_location()` Get a flag indicating whether the transformation phase should keep track of line and column numbers for the input source document.
`XMLStringFactory` `getXMLStringFactory()` Get the XMLStringFactory used for the DTMs.
`static DTMManager` `newInstance(XMLStringFactory xsf)` Obtain a new instance of a `DTMManager`.
`abstract boolean` `release(DTM dtm, boolean shouldHardDelete)` Release a DTM either to a lru pool, or completely remove reference.
`void` `setIncremental(boolean incremental)` Set a flag indicating whether an incremental transform is desired This flag should have the same value as the FEATURE_INCREMENTAL feature which is set by the TransformerFactory.setAttribut() method before a DTMManager is created
`void` `setSource_location(boolean sourceLocation)` Set a flag indicating whether the transformation phase should keep track of line and column numbers for the input source document.
`void` `setXMLStringFactory(XMLStringFactory xsf)` Set the XMLStringFactory used for the DTMs.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### m_incremental

    public boolean m_incremental

#### m_source_location

    public boolean m_source_location

#### 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

### Method Detail

#### getXMLStringFactory

    public XMLStringFactory getXMLStringFactory()

Get the XMLStringFactory used for the DTMs.

Returns:
  a valid XMLStringFactory object, or null if it hasn't been set yet.

#### setXMLStringFactory

    public void setXMLStringFactory(XMLStringFactory xsf)

Set the XMLStringFactory used for the DTMs.

Parameters:
  `xsf` - a valid XMLStringFactory object, should not be null.

#### newInstance

    public static DTMManager newInstance(XMLStringFactory xsf)
                                  throws DTMConfigurationException

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.apache.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.apache.xml.dtm.DTMManager` in jars available to the runtime.
- Use the default `DTMManager` classname, which is `org.apache.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.
Throws:
  `DTMConfigurationException` - if the implementation is not available or cannot be instantiated.

#### getDTM

    public abstract DTM getDTM(Source source,
             boolean unique,
             DTMWSFilter whiteSpaceFilter,
             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.
  `whiteSpaceFilter` - Enables filtering of whitespace nodes, and may be null.
  `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(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.

#### createDocumentFragment

    public abstract DTM createDocumentFragment()

Creates a DTM representing an empty `DocumentFragment` object.

Returns:
  a non-null DTM reference.

#### release

    public abstract boolean release(DTM dtm,
                  boolean shouldHardDelete)

Release a DTM either to a lru pool, or completely remove reference. DTMs without system IDs are always hard deleted. State: experimental.

Parameters:
  `dtm` - The DTM to be released.
  `shouldHardDelete` - True if the DTM should be removed no matter what.
Returns:
  true if the DTM was removed, false if it was put back in a lru pool.

#### createDTMIterator

    public abstract DTMIterator createDTMIterator(java.lang.Object xpathCompiler,
                                int pos)

Create a new `DTMIterator` based on an XPath UnionExpr.

Parameters:
  `xpathCompiler` - ??? Somehow we need to pass in a subpart of the expression. I hate to do this with strings, since the larger expression has already been parsed.
  `pos` - The position in the expression.
Returns:
  The newly created `DTMIterator`.

#### createDTMIterator

    public abstract DTMIterator createDTMIterator(java.lang.String xpathString,
                                PrefixResolver presolver)

Create a new `DTMIterator` based on an XPath UnionExpr.

Parameters:
  `xpathString` - Must be a valid string expressing a UnionExpr.
  `presolver` - An object that can resolve prefixes to namespace URLs.
Returns:
  The newly created `DTMIterator`.

#### createDTMIterator

    public abstract DTMIterator createDTMIterator(int whatToShow,
                                DTMFilter filter,
                                boolean entityReferenceExpansion)

Create a new `DTMIterator` based only on a whatToShow and a DTMFilter. The traversal semantics are defined as the descendant access.

Note that DTMIterators may not be an exact match to DOM NodeIterators. They are initialized and used in much the same way as a NodeIterator, but their response to document mutation is not currently defined.

Parameters:
  `whatToShow` - This flag specifies which node types may appear in the logical view of the tree presented by the iterator. See the description of `NodeFilter` for the set of possible `SHOW_` values.These flags can be combined using `OR`.
  `filter` - The `NodeFilter` to be used with this `DTMFilter`, or `null` to indicate no filter.
  `entityReferenceExpansion` - The value of this flag determines whether entity reference nodes are expanded.
Returns:
  The newly created `DTMIterator`.

#### createDTMIterator

    public abstract DTMIterator createDTMIterator(int node)

Create a new `DTMIterator` that holds exactly one node.

Parameters:
  `node` - The node handle that the DTMIterator will iterate to.
Returns:
  The newly created `DTMIterator`.

#### getIncremental

    public boolean getIncremental()

Get a flag indicating whether an incremental transform is desired

Returns:
  incremental boolean.

#### setIncremental

    public void setIncremental(boolean incremental)

Set a flag indicating whether an incremental transform is desired This flag should have the same value as the FEATURE_INCREMENTAL feature which is set by the TransformerFactory.setAttribut() method before a DTMManager is created

Parameters:
  `incremental` - boolean to use to set m_incremental.

#### getSource_location

    public boolean getSource_location()

Get a flag indicating whether the transformation phase should keep track of line and column numbers for the input source document.

Returns:
  source location boolean

#### setSource_location

    public void setSource_location(boolean sourceLocation)

Set a flag indicating whether the transformation phase should keep track of line and column numbers for the input source document. This flag should have the same value as the FEATURE_SOURCE_LOCATION feature which is set by the TransformerFactory.setAttribut() method before a DTMManager is created

Parameters:
  `sourceLocation` - boolean to use to set m_source_location

#### getDTMIdentity

    public abstract int getDTMIdentity(DTM dtm)

%TBD% Doc NEEDSDOC @param dtm NEEDSDOC ($objectName$) @return

#### getDTMIdentityMask

    public int getDTMIdentityMask()

%TBD% Doc NEEDSDOC ($objectName$) @return

#### getNodeIdentityMask

    public int getNodeIdentityMask()

%TBD% Doc NEEDSDOC ($objectName$) @return