org.enhydra.apache.html.dom
Class HTMLCollectionImpl

java.lang.Object
  |
  +--org.enhydra.apache.html.dom.HTMLCollectionImpl
All Implemented Interfaces:
HTMLCollection

class HTMLCollectionImpl
extends Object
implements HTMLCollection

Implements HTMLCollection to traverse any named elements on a 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 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.

Version:
$Revision: 1.2 $ $Date: 2005/01/26 08:28:44 $
Author:
Assaf Arkin
See Also:
HTMLCollection

Field Summary
(package private) static short ANCHOR
          Request collection of all anchors in document: <A> elements that have a name attribute.
(package private) static short APPLET
          Request collection of all Applets in document: <APPLET> and <OBJECT> elements (<OBJECT> must contain an Applet).
(package private) static short AREA
          Request collection of all areas in map: <AREA> element in <MAP> (non recursive).
(package private) static short CELL
          Request collection of all cells in row: <TD> elements in <TR> (non recursive).
(package private) static short ELEMENT
          Request collection of all form elements: <INPUT>, <BUTTON>, <SELECT>, <TEXT> and <TEXTAREA> elements inside form <FORM>.
(package private) static short FORM
          Request collection of all forms in document: <FORM> elements.
(package private) static short IMAGE
          Request collection of all images in document: <IMAGE> elements.
(package private) static short LINK
          Request collection of all links in document: <A> and <AREA> elements (must have a href attribute).
(package private) static short OPTION
          Request collection of all options in selection: <OPTION> elments in <SELECT> or <OPTGROUP>.
(package private) static short ROW
          Request collection of all rows in table: <TR> elements in table or table section.
(package private) static short TBODY
          Request collection of all table bodies in table: <TBODY> element in table <TABLE> (non recursive).
 
Constructor Summary
(package private) HTMLCollectionImpl(HTMLElement topLevel, short lookingFor)
          Construct a new collection that retrieves element of the specific type (lookingFor) from the specific document portion (topLevel).
 
Method Summary
protected  boolean collectionMatch(Element elem, String name)
          Determines if current element matches based on what we're looking for.
 int getLength()
          Returns the length of the collection.
 Node item(int index)
          Retrieves the indexed node from the collection.
 Node namedItem(String name)
          Retrieves the named node from the collection.
protected  boolean recurse()
          Returns true if scanning methods should iterate through the collection.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ANCHOR

static final short ANCHOR
Request collection of all anchors in document: <A> elements that have a name attribute.

FORM

static final short FORM
Request collection of all forms in document: <FORM> elements.

IMAGE

static final short IMAGE
Request collection of all images in document: <IMAGE> elements.

APPLET

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

LINK

static final short LINK
Request collection of all links in document: <A> and <AREA> elements (must have a href attribute).

OPTION

static final short OPTION
Request collection of all options in selection: <OPTION> elments in <SELECT> or <OPTGROUP>.

ROW

static final short ROW
Request collection of all rows in table: <TR> elements in table or table section.

ELEMENT

static final short ELEMENT
Request collection of all form elements: <INPUT>, <BUTTON>, <SELECT>, <TEXT> and <TEXTAREA> elements inside form <FORM>.

AREA

static final short AREA
Request collection of all areas in map: <AREA> element in <MAP> (non recursive).

TBODY

static final short TBODY
Request collection of all table bodies in table: <TBODY> element in table <TABLE> (non recursive).

CELL

static final short CELL
Request collection of all cells in row: <TD> elements in <TR> (non recursive).
Constructor Detail

HTMLCollectionImpl

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 - The element underneath which the collection exists
lookingFor - Code indicating what elements to look for
Method Detail

getLength

public final int getLength()
Returns the length of the collection. This method might traverse the entire document tree.
Specified by:
getLength in interface HTMLCollection
Returns:
Length of the collection

item

public final Node item(int index)
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.
Specified by:
item in interface HTMLCollection
Parameters:
index - The index of the node to return
Returns:
The specified node or null if no such node found

namedItem

public final Node namedItem(String name)
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.
Specified by:
namedItem in interface HTMLCollection
Parameters:
name - The name of the node to return
Returns:
The specified node or null if no such node found

recurse

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:
True if methods should recurse to traverse entire tree

collectionMatch

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 - The current element
name - The identifier name or null
Returns:
The element matches what we're looking for


Copyright © 1999 The Apache Software Foundation. All Rights reserved.