APIdia Launch Partner
Top Description Fields Constructors Methods
com.sun.org.apache.xml.internal.dtm

public abstract Class DTMManager

extends Object
Class Inheritance
Known Direct Subclasses
com.sun.org.apache.xpath.internal.XPathContext, com.sun.org.apache.xml.internal.dtm.ref.DTMManagerDefault
Imports
com.sun.org.apache.xml.internal.utils.PrefixResolver, .XMLStringFactory
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 "com.sun.org.apache.xml.internal.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

Modifier and TypeField and Description
private boolean
_overrideDefaultParser

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.

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.

public static final int
IDENT_MAX_DTMS

This is the maximum number of DTMs available.

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.

public boolean
m_incremental

public boolean
m_source_location

protected XMLStringFactory
m_xsf

Factory for creating XMLString objects.

Constructor Summary

AccessConstructor and Description
protected
DTMManager()

Default constructor is protected on purpose.

Method Summary

Modifier and TypeMethod and Description
public abstract DTM

Returns:

a non-null DTM reference.
createDocumentFragment()

Creates a DTM representing an empty DocumentFragment object.

public abstract DTMIterator

Returns:

The newly created DTMIterator.
createDTMIterator(Object
??? 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.
xpathCompiler, int
The position in the expression.
pos)

Create a new DTMIterator based on an XPath LocationPath or a UnionExpr.

public abstract DTMIterator

Returns:

The newly created DTMIterator.
createDTMIterator(String
Must be a valid string expressing a LocationPath or a UnionExpr.
xpathString, PrefixResolver
An object that can resolve prefixes to namespace URLs.
presolver)

Create a new DTMIterator based on an XPath LocationPath or a UnionExpr.

public abstract DTMIterator

Returns:

The newly created DTMIterator.
createDTMIterator(int
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.
whatToShow, DTMFilter
The NodeFilter to be used with this DTMFilter, or null to indicate no filter.
filter, boolean
The value of this flag determines whether entity reference nodes are expanded.
entityReferenceExpansion)

Create a new DTMIterator based only on a whatToShow and a DTMFilter.

public abstract DTMIterator

Returns:

The newly created DTMIterator.
createDTMIterator(int
The node handle that the DTMIterator will iterate to.
node)

Create a new DTMIterator that holds exactly one node.

public abstract DTM

Returns:

a non-null DTM reference.
getDTM(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.
source, boolean
true if the returned DTM must be unique, probably because it is going to be mutated.
unique, DTMWSFilter
Enables filtering of whitespace nodes, and may be null.
whiteSpaceFilter, boolean
true if the DTM should be built incrementally, if possible.
incremental, boolean
true if the caller considers it worth it to use indexing schemes.
doIndexing)

Get an instance of a DTM, loaded with the content from the specified source.

public abstract DTM

Returns:

a non-null DTM reference.
getDTM(int
the nodeHandle.
nodeHandle)

Get the instance of DTM that "owns" a node handle.

public abstract int

Returns:

a valid DTM handle.
getDTMHandleFromNode(Node
Non-null reference to a DOM node.
node)

Given a W3C DOM node, try and return a DTM handle.

public abstract int
getDTMIdentity(DTM dtm)

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

public int
getDTMIdentityMask()

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

public boolean

Returns:

incremental boolean.
getIncremental()

Get a flag indicating whether an incremental transform is desired

public int
getNodeIdentityMask()

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

public boolean

Returns:

source location boolean
getSource_location()

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

public XMLStringFactory

Returns:

a valid XMLStringFactory object, or null if it hasn't been set yet.
getXMLStringFactory()

Get the XMLStringFactory used for the DTMs.

public static DTMManager

Returns:

new DTMManager instance, never null.
newInstance(XMLStringFactory xsf)

Obtain a new instance of a DTMManager.

public boolean
overrideDefaultParser()

Return the state of the services mechanism feature.

public abstract boolean

Returns:

true if the DTM was removed, false if it was put back in a lru pool.
release(DTM
The DTM to be released.
dtm, boolean
True if the DTM should be removed no matter what.
shouldHardDelete)

Release a DTM either to a lru pool, or completely remove reference.

public void
setIncremental(boolean
boolean to use to set m_incremental.
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

public void
setOverrideDefaultParser(boolean flag)

Set the state of the services mechanism feature.

public void
setSource_location(boolean
boolean to use to set m_source_location
sourceLocation)

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

public void
setXMLStringFactory(XMLStringFactory
a valid XMLStringFactory object, should not be null.
xsf)

Set the XMLStringFactory used for the DTMs.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

_overrideDefaultParserback to summary
private boolean _overrideDefaultParser
IDENT_DTM_DEFAULTback to summary
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.

IDENT_DTM_NODE_BITSback to summary
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.)

IDENT_MAX_DTMSback to summary
public static final int IDENT_MAX_DTMS

This is the maximum number of DTMs available. The highest DTM is one less than this.

IDENT_NODE_DEFAULTback to summary
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.

m_incrementalback to summary
public boolean m_incremental
m_source_locationback to summary
public boolean m_source_location
m_xsfback to summary
protected XMLStringFactory m_xsf

Factory for creating XMLString objects. %TBD% Make this set by the caller.

Constructor Detail

DTMManagerback to summary
protected DTMManager()

Default constructor is protected on purpose.

Method Detail

createDocumentFragmentback to summary
public abstract DTM createDocumentFragment()

Creates a DTM representing an empty DocumentFragment object.

Returns:DTM

a non-null DTM reference.

createDTMIteratorback to summary
public abstract DTMIterator createDTMIterator(Object xpathCompiler, int pos)

Create a new DTMIterator based on an XPath LocationPath or a UnionExpr.

Parameters
xpathCompiler:Object

??? 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:int

The position in the expression.

Returns:DTMIterator

The newly created DTMIterator.

createDTMIteratorback to summary
public abstract DTMIterator createDTMIterator(String xpathString, PrefixResolver presolver)

Create a new DTMIterator based on an XPath LocationPath or a UnionExpr.

Parameters
xpathString:String

Must be a valid string expressing a LocationPath or a UnionExpr.

presolver:PrefixResolver

An object that can resolve prefixes to namespace URLs.

Returns:DTMIterator

The newly created DTMIterator.

createDTMIteratorback to summary
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:int

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:DTMFilter

The NodeFilter to be used with this DTMFilter, or null to indicate no filter.

entityReferenceExpansion:boolean

The value of this flag determines whether entity reference nodes are expanded.

Returns:DTMIterator

The newly created DTMIterator.

createDTMIteratorback to summary
public abstract DTMIterator createDTMIterator(int node)

Create a new DTMIterator that holds exactly one node.

Parameters
node:int

The node handle that the DTMIterator will iterate to.

Returns:DTMIterator

The newly created DTMIterator.

getDTMback to summary
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: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:boolean

true if the returned DTM must be unique, probably because it is going to be mutated.

whiteSpaceFilter:DTMWSFilter

Enables filtering of whitespace nodes, and may be null.

incremental:boolean

true if the DTM should be built incrementally, if possible.

doIndexing:boolean

true if the caller considers it worth it to use indexing schemes.

Returns:DTM

a non-null DTM reference.

getDTMback to summary
public abstract DTM getDTM(int nodeHandle)

Get the instance of DTM that "owns" a node handle.

Parameters
nodeHandle:int

the nodeHandle.

Returns:DTM

a non-null DTM reference.

getDTMHandleFromNodeback to summary
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:Node

Non-null reference to a DOM node.

Returns:int

a valid DTM handle.

getDTMIdentityback to summary
public abstract int getDTMIdentity(DTM dtm)

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

getDTMIdentityMaskback to summary
public int getDTMIdentityMask()

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

getIncrementalback to summary
public boolean getIncremental()

Get a flag indicating whether an incremental transform is desired

Returns:boolean

incremental boolean.

getNodeIdentityMaskback to summary
public int getNodeIdentityMask()

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

getSource_locationback to summary
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:boolean

source location boolean

getXMLStringFactoryback to summary
public XMLStringFactory getXMLStringFactory()

Get the XMLStringFactory used for the DTMs.

Returns:XMLStringFactory

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

newInstanceback to summary
public static DTMManager newInstance(XMLStringFactory xsf) throws DTMException

Obtain a new instance of a DTMManager. This static method creates a new factory instance using the default DTMManager implementation, which is com.sun.org.apache.xml.internal.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:DTMManager

new DTMManager instance, never null.

Exceptions
DTMException:
if the implementation is not available or cannot be instantiated.
overrideDefaultParserback to summary
public boolean overrideDefaultParser()

Return the state of the services mechanism feature.

releaseback to summary
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:DTM

The DTM to be released.

shouldHardDelete:boolean

True if the DTM should be removed no matter what.

Returns:boolean

true if the DTM was removed, false if it was put back in a lru pool.

setIncrementalback to summary
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

boolean to use to set m_incremental.

setOverrideDefaultParserback to summary
public void setOverrideDefaultParser(boolean flag)

Set the state of the services mechanism feature.

setSource_locationback to summary
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

boolean to use to set m_source_location

setXMLStringFactoryback to summary
public void setXMLStringFactory(XMLStringFactory xsf)

Set the XMLStringFactory used for the DTMs.

Parameters
xsf:XMLStringFactory

a valid XMLStringFactory object, should not be null.