Xerces2-j 2.12.2 · org.apache.html.dom.HTMLCollectionImpl

Implements org.w3c.dom.html.HTMLCollection to traverse any named elements on a org.w3c.dom.html.HTMLDocument. The elements type to look for is identified in the constructor by code. This collection is not optimized for traversing large trees.

The collection has to meet two requirements: it has to be live, and it has to traverse depth first and always return results in that order. As such, using an object container (such as java.util.Vector) is expensive on insert/remove operations. Instead, the collection has been implemented using three traversing functions. As a result, operations on large documents will result in traversal of the entire document tree and consume a considerable amount of time.

Note that synchronization on the traversed document cannot be achieved. The document itself cannot be locked, and locking each traversed node is likely to lead to a dead lock condition. Therefore, there is a chance of the document being changed as results are fetched; in all likelihood, the results might be out dated, but not erroneous.

Field Summary

Modifier and Type	Field and Description
private short	_lookingFor Indicates what this collection is looking for.
private Element	_topLevel This is the top level element underneath which the collection exists.
pack-priv static final short	ANCHOR Request collection of all anchors in document: <A> elements that have a `name` attribute.
pack-priv static final short	APPLET Request collection of all Applets in document: <APPLET> and <OBJECT> elements (<OBJECT> must contain an Applet).
pack-priv static final short	AREA Request collection of all areas in map: <AREA> element in <MAP> (non recursive).
pack-priv static final short	CELL Request collection of all cells in row: <TD> and <TH> elements in <TR> (non recursive).
pack-priv static final short	ELEMENT Request collection of all form elements: <INPUT>, <BUTTON>, <SELECT>, and <TEXTAREA> elements inside form <FORM>.
pack-priv static final short	FORM Request collection of all forms in document: <FORM> elements.
pack-priv static final short	IMAGE Request collection of all images in document: <IMG> elements.
pack-priv static final short	LINK Request collection of all links in document: <A> and <AREA> elements (must have a `href` attribute).
pack-priv static final short	OPTION Request collection of all options in selection: <OPTION> elements in <SELECT> or <OPTGROUP>.
pack-priv static final short	ROW Request collection of all rows in table: <TR> elements in table or table section.
private static final long	serialVersionUID
pack-priv static final short	TBODY Request collection of all table bodies in table: <TBODY> element in table <TABLE> (non recursive).

Access	Constructor and Description
pack-priv	HTMLCollectionImpl(HTMLElement The element underneath which the collection exists topLevel, short Code indicating what elements to look for lookingFor) Construct a new collection that retrieves element of the specific type (`lookingFor`) from the specific document portion (`topLevel`).

Method Summary

Modifier and Type	Method and Description
protected boolean	Returns: The element matches what we're looking for collectionMatch(Element The current element elem, String The identifier name or null name) Determines if current element matches based on what we're looking for.
public final int	Returns: Length of the collection getLength() Implements org.w3c.dom.html.HTMLCollection.getLength. Returns the length of the collection.
private int	Returns: Number of elements getLength(Element Top level element from which to scan topLevel) Recursive function returns the number of elements of a particular type that exist under the top level element.
public final Node	Returns: The specified node or null if no such node found item(int The index of the node to return index) Implements org.w3c.dom.html.HTMLCollection.item. Retrieves the indexed node from the collection.
private Node	Returns: Number of elements item(Element Top level element from which to scan topLevel, CollectionIndex The index of the item to retreive index) Recursive function returns the numbered element of a particular type that exist under the top level element.
public final Node	Returns: The specified node or null if no such node found namedItem(String The name of the node to return name) Implements org.w3c.dom.html.HTMLCollection.namedItem. Retrieves the named node from the collection.
private Node	Returns: The first named element found namedItem(Element Top level element from which to scan topLevel, String The named element to look for name) Recursive function returns an element of a particular type with the specified name (`id` attribute).
protected boolean	Returns: True if methods should recurse to traverse entire tree recurse() Returns true if scanning methods should iterate through the collection.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

_lookingFor	back to summary
private short _lookingFor Indicates what this collection is looking for. Holds one of the enumerated values and used by `collectionMatch`. Set by the constructor and determine the collection's use for its life time.

_topLevel	back to summary
private Element _topLevel This is the top level element underneath which the collection exists.

ANCHOR	back to summary
pack-priv static final short ANCHOR Request collection of all anchors in document: <A> elements that have a `name` attribute.

APPLET	back to summary
pack-priv static final short APPLET Request collection of all Applets in document: <APPLET> and <OBJECT> elements (<OBJECT> must contain an Applet).

AREA	back to summary
pack-priv static final short AREA Request collection of all areas in map: <AREA> element in <MAP> (non recursive).

CELL	back to summary
pack-priv static final short CELL Request collection of all cells in row: <TD> and <TH> elements in <TR> (non recursive).

ELEMENT	back to summary
pack-priv static final short ELEMENT Request collection of all form elements: <INPUT>, <BUTTON>, <SELECT>, and <TEXTAREA> elements inside form <FORM>.

FORM	back to summary
pack-priv static final short FORM Request collection of all forms in document: <FORM> elements.

IMAGE	back to summary
pack-priv static final short IMAGE Request collection of all images in document: <IMG> elements.

LINK	back to summary
pack-priv static final short LINK Request collection of all links in document: <A> and <AREA> elements (must have a `href` attribute).

OPTION	back to summary
pack-priv static final short OPTION Request collection of all options in selection: <OPTION> elements in <SELECT> or <OPTGROUP>.

ROW	back to summary
pack-priv static final short ROW Request collection of all rows in table: <TR> elements in table or table section.

serialVersionUID	back to summary
private static final long serialVersionUID

TBODY	back to summary
pack-priv static final short TBODY Request collection of all table bodies in table: <TBODY> element in table <TABLE> (non recursive).

Constructor Detail

HTMLCollectionImpl back to summary

HTMLCollectionImpl	back to summary
pack-priv HTMLCollectionImpl(HTMLElement topLevel, short lookingFor) Construct a new collection that retrieves element of the specific type (`lookingFor`) from the specific document portion (`topLevel`). Parameters topLevel:HTMLElement The element underneath which the collection exists lookingFor:short Code indicating what elements to look for

pack-priv HTMLCollectionImpl(HTMLElement topLevel, short lookingFor)

Construct a new collection that retrieves element of the specific type (lookingFor) from the specific document portion (topLevel).

Parameters

topLevel:HTMLElement: The element underneath which the collection exists
lookingFor:short: Code indicating what elements to look for

Method Detail

collectionMatch back to summary

collectionMatch	back to summary
protected boolean collectionMatch(Element elem, String name) Determines if current element matches based on what we're looking for. The element is passed along with an optional identifier name. If the element is the one we're looking for, return true. If the name is also specified, the name must match the `id` attribute (match `name` first for anchors). Parameters elem:Element The current element name:String The identifier name or null Returns:boolean The element matches what we're looking for

protected boolean collectionMatch(Element elem, String name)

Determines if current element matches based on what we're looking for. The element is passed along with an optional identifier name. If the element is the one we're looking for, return true. If the name is also specified, the name must match the id attribute (match name first for anchors).

Parameters

elem:Element: The current element
name:String: The identifier name or null

Returns:boolean

The element matches what we're looking for

getLength	back to summary
public final int getLength() Implements org.w3c.dom.html.HTMLCollection.getLength. Returns the length of the collection. This method might traverse the entire document tree. Returns:int Length of the collection

getLength

back to summary

public final int getLength()

Implements org.w3c.dom.html.HTMLCollection.getLength.

Returns the length of the collection. This method might traverse the entire document tree.

Returns:int: Length of the collection

getLength	back to summary
private int getLength(Element topLevel) Recursive function returns the number of elements of a particular type that exist under the top level element. This is a recursive function and the top level element is passed along. Parameters topLevel:Element Top level element from which to scan Returns:int Number of elements

getLength

back to summary

private int getLength(Element topLevel)

Recursive function returns the number of elements of a particular type that exist under the top level element. This is a recursive function and the top level element is passed along.

Parameters

topLevel:Element: Top level element from which to scan

Returns:int

Number of elements

item	back to summary
public final Node item(int index) Implements org.w3c.dom.html.HTMLCollection.item. Retrieves the indexed node from the collection. Nodes are numbered in tree order - depth-first traversal order. This method might traverse the entire document tree. Parameters index:int The index of the node to return Returns:Node The specified node or null if no such node found

item

back to summary

public final Node item(int index)

Implements org.w3c.dom.html.HTMLCollection.item.

Retrieves the indexed node from the collection. Nodes are numbered in tree order - depth-first traversal order. This method might traverse the entire document tree.

Parameters

index:int: The index of the node to return

Returns:Node

The specified node or null if no such node found

item back to summary

item	back to summary
private Node item(Element topLevel, CollectionIndex index) Recursive function returns the numbered element of a particular type that exist under the top level element. This is a recursive function and the top level element is passed along. Note that this function must call itself with an index and get back both the element (if one was found) and the new index which is decremeneted for any like element found. Since integers are only passed by value, this function makes use of a separate class (`CollectionIndex`) to hold that index. Parameters topLevel:Element Top level element from which to scan index:CollectionIndex The index of the item to retreive Returns:Node Number of elements See Also `CollectionIndex`

private Node item(Element topLevel, CollectionIndex index)

Recursive function returns the numbered element of a particular type that exist under the top level element. This is a recursive function and the top level element is passed along.

Note that this function must call itself with an index and get back both the element (if one was found) and the new index which is decremeneted for any like element found. Since integers are only passed by value, this function makes use of a separate class (CollectionIndex) to hold that index.

Parameters

topLevel:Element: Top level element from which to scan
index:CollectionIndex: The index of the item to retreive

Returns:Node

Number of elements

See Also

CollectionIndex

namedItem back to summary

namedItem	back to summary
public final Node namedItem(String name) Implements org.w3c.dom.html.HTMLCollection.namedItem. Retrieves the named node from the collection. The name is matched case sensitive against the `id` attribute of each element in the collection, returning the first match. The tree is traversed in depth-first order. This method might traverse the entire document tree. Parameters name:String The name of the node to return Returns:Node The specified node or null if no such node found

public final Node namedItem(String name)

Implements org.w3c.dom.html.HTMLCollection.namedItem.

Retrieves the named node from the collection. The name is matched case sensitive against the id attribute of each element in the collection, returning the first match. The tree is traversed in depth-first order. This method might traverse the entire document tree.

Parameters

name:String: The name of the node to return

Returns:Node

The specified node or null if no such node found

namedItem back to summary

namedItem	back to summary
private Node namedItem(Element topLevel, String name) Recursive function returns an element of a particular type with the specified name (`id` attribute). Parameters topLevel:Element Top level element from which to scan name:String The named element to look for Returns:Node The first named element found

private Node namedItem(Element topLevel, String name)

Recursive function returns an element of a particular type with the specified name (id attribute).

Parameters

topLevel:Element: Top level element from which to scan
name:String: The named element to look for

Returns:Node

The first named element found

recurse	back to summary
protected boolean recurse() Returns true if scanning methods should iterate through the collection. When looking for elements in the document, recursing is needed to traverse the full document tree. When looking inside a specific element (e.g. for a cell inside a row), recursing can lead to erroneous results. Returns:boolean True if methods should recurse to traverse entire tree

recurse

back to summary

protected boolean recurse()

Returns true if scanning methods should iterate through the collection. When looking for elements in the document, recursing is needed to traverse the full document tree. When looking inside a specific element (e.g. for a cell inside a row), recursing can lead to erroneous results.

Returns:boolean: True if methods should recurse to traverse entire tree

pack-priv Class HTMLCollectionImpl

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail