com.gargoylesoftware.htmlunit.html
Class HtmlPage

java.lang.Object
  com.gargoylesoftware.htmlunit.html.DomNode
      com.gargoylesoftware.htmlunit.html.HtmlPage

All Implemented Interfaces:

Page, java.io.Serializable, java.lang.Cloneable

public final class HtmlPage
extends DomNode
implements Page, java.lang.Cloneable

A representation of an HTML page returned from a server. This class is the DOM Document implementation.

Version:

$Revision: 1.3 $

Author:

Mike Bowler, Alex Nikiforoff, Noboru Sinohara, David K. Taylor, Andreas Hangler, Christian Sell, Chris Erskine, Marc Guillemot, Ahmed Ashour

See Also:

Serialized Form

Field Summary

Fields inherited from class com.gargoylesoftware.htmlunit.html.DomNode

PROPERTY_ELEMENT, READY_STATE_COMPLETE, READY_STATE_INTERACTIVE, READY_STATE_LOADED, READY_STATE_LOADING, READY_STATE_UNINITIALIZED

Constructor Summary

HtmlPage(java.net.URL originatingUrl, WebResponse webResponse, WebWindow webWindow)
Create an instance of HtmlPage

Method Summary

void	addHtmlAttributeChangeListener(HtmlAttributeChangeListener listener) Adds an HtmlAttributeChangeListener to the listener list.
void	assertAllAccessKeyAttributesUnique() Many html components can have an "accesskey" attribute which defines a hot key for keyboard navigation.
void	assertAllIdAttributesUnique() Each html element can have an id attribute and by definition, all ids must be unique within the document.
void	assertAllTabIndexAttributesSet() Many html elements are "tabbable" and can have a "tabindex" attribute that determines the order in which the components are navigated when pressing the tab key.
java.lang.String	asXml() Return a string representation of the xml document from this element and all it's children (recursively).
void	cleanUp() Clean up this page.
DomNode	cloneNode(boolean deep) Override cloneNode to add cloned elements to the clone, not to the original.
DomDocumentFragment	createDomDocumentFragment() Creates an empty DomDocumentFragment object.
HtmlElement	createHtmlElement(java.lang.String tagName) Create a new HTML element with the given tag name.
HtmlElement	createHtmlElementNS(java.lang.String namespaceURI, java.lang.String qualifiedName) Create a new HtmlElement with the given namespace and qualified name.
void	deregisterFramesIfNeeded() Deregister frames that are no longer in use.
ScriptResult	executeJavaScriptFunctionIfPossible(org.mozilla.javascript.Function function, org.mozilla.javascript.Scriptable thisObject, java.lang.Object[] args, DomNode htmlElementScope) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
ScriptResult	executeJavaScriptIfPossible(java.lang.String sourceCode, java.lang.String sourceName, HtmlElement htmlElement) Execute the specified javascript if a javascript engine was successfully instantiated.
HtmlAnchor	getAnchorByHref(java.lang.String href) Return the HtmlAnchor with the specified href
HtmlAnchor	getAnchorByName(java.lang.String name) Return the HtmlAnchor with the specified name
java.util.List	getAnchors() Return a list of all anchors contained in this page.
HtmlElement	getDocumentHtmlElement() Get the root HtmlElement of this document.
FocusableElement	getElementWithFocus() Return the element with the focus or null if no element has the focus.
WebWindow	getEnclosingWindow() Return the window that this page is sitting inside.
HtmlAnchor	getFirstAnchorByText(java.lang.String text) Return the first anchor that contains the specified text.
HtmlForm	getFormByName(java.lang.String name) Return the first form that matches the specified name
java.util.List	getForms() Return a list of all the forms in the page.
FrameWindow	getFrameByName(java.lang.String name) Returns the first frame contained in this page with the specified name.
java.util.List	getFrames() Return a list containing all the frames (from frame and iframe tags) in this page.
java.net.URL	getFullyQualifiedUrl(java.lang.String relativeUrl) Given a relative url (ie /foo), return a fully qualified url based on the url that was used to load this page
HtmlElement	getHtmlElementByAccessKey(char accessKey) Return the html element that is assigned to the specified access key.
HtmlElement	getHtmlElementById(java.lang.String id) Returns the HTML element with the specified ID.
java.util.List	getHtmlElementsByAccessKey(char accessKey) Return all the html elements that are assigned to the specified access key.
java.util.List	getHtmlElementsByName(java.lang.String name) Returns the HTML elements with the specified name attribute.
java.lang.String	getNodeName() Get the name for the current node.
short	getNodeType() Get the type of the current node.
HtmlPage	getPage() Return the HtmlPage that contains this node
java.lang.String	getPageEncoding() Return the charset used in the page.
java.lang.String	getResolvedTarget(java.lang.String elementTarget) Given a target attribute value, resolve the target using a base target for the page.
java.util.List	getTabbableElementIds() Return a list of ids (strings) that correspond to the tabbable elements in this page.
java.util.List	getTabbableElements() Return a list of all elements that are tabbable in the order that will be used for tabbing.
java.lang.String	getTitleText() Return the title of this page or an empty string if the title wasn't specified.
WebClient	getWebClient() Return the WebClient that originally loaded this page
WebResponse	getWebResponse() Return the web response that was originally used to create this page.
void	initialize() Initialize this page.
static boolean	isJavaScript(java.lang.String typeAttribute, java.lang.String languageAttribute) INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
boolean	moveFocusToElement(FocusableElement newElement) Move the focus to the specified component.
HtmlElement	pressAccessKey(char accessKey) Simulate pressing an access key.
void	removeHtmlAttributeChangeListener(HtmlAttributeChangeListener listener) Removes an HtmlAttributeChangeListener from the listener list.
void	setEnclosingWindow(WebWindow window) Set the window that contains this page.
void	setTitleText(java.lang.String message) Set the text for the title of this page.
HtmlElement	tabToNextElement() Move the focus to the next element in the tab order.
HtmlElement	tabToPreviousElement() Move the focus to the previous element in the tab order.
java.lang.String	toString() Gives a basic representation for debugging purposes

Methods inherited from class com.gargoylesoftware.htmlunit.html.DomNode

addDomChangeListener, appendDomChild, asText, cloneDomNode, getAllHtmlChildElements, getByXPath, getChildIterator, getEndColumnNumber, getEndLineNumber, getEventHandler, getFirstDomChild, getLastDomChild, getNextDomSibling, getNodeValue, getParentDomNode, getPreviousDomSibling, getReadyState, getScriptObject, getStartColumnNumber, getStartLineNumber, insertBefore, remove, removeAllChildren, removeDomChangeListener, removeEventHandler, replace, setEventHandler, setEventHandler, setNodeValue, setReadyState, setScriptObject

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HtmlPage

public HtmlPage(java.net.URL originatingUrl,
                WebResponse webResponse,
                WebWindow webWindow)

Create an instance of HtmlPage

Parameters:

originatingUrl - The url that was used to load this page.

webResponse - The web response that was used to create this page

webWindow - The window that this page is being loaded into.

Method Detail

addHtmlAttributeChangeListener

public void addHtmlAttributeChangeListener(HtmlAttributeChangeListener listener)

Adds an HtmlAttributeChangeListener to the listener list. The listener is registered for all attributes of all HtmlElements contained in this page.

Parameters:

listener - the attribute change listener to be added.

See Also:

removeHtmlAttributeChangeListener(HtmlAttributeChangeListener)

assertAllAccessKeyAttributesUnique

public void assertAllAccessKeyAttributesUnique()

Many html components can have an "accesskey" attribute which defines a hot key for keyboard navigation. Assert that all access keys (mnemonics) in this page are unique. If they aren't then throw an exception as per WebClient.assertionFailed(String)

assertAllIdAttributesUnique

public void assertAllIdAttributesUnique()

Each html element can have an id attribute and by definition, all ids must be unique within the document.

Assert that all ids in this page are unique. If they aren't then throw an exception as per WebClient.assertionFailed(String)

assertAllTabIndexAttributesSet

public void assertAllTabIndexAttributesSet()

Many html elements are "tabbable" and can have a "tabindex" attribute that determines the order in which the components are navigated when pressing the tab key. To ensure good usability for keyboard navigation, all tabbable elements should have the tabindex attribute set.

Assert that all tabbable elements have a valid value set for "tabindex". If they don't then throw an exception as per WebClient.assertionFailed(String)

asXml

public java.lang.String asXml()

Return a string representation of the xml document from this element and all it's children (recursively).

Overrides:

asXml in class DomNode

Returns:

The xml string.

cleanUp

public void cleanUp()
             throws java.io.IOException

Clean up this page.

Specified by:

cleanUp in interface Page

Throws:

java.io.IOException - If an IO problem occurs.

cloneNode

public DomNode cloneNode(boolean deep)

Override cloneNode to add cloned elements to the clone, not to the original. Make a clone of this node

Overrides:

cloneNode in class DomNode

Parameters:

deep - if true, the clone will be propagated to the whole subtree below this one. Otherwise, the new node will not have any children. The page reference will always be the same as this node's.

Returns:

a new node

createDomDocumentFragment

public DomDocumentFragment createDomDocumentFragment()

Creates an empty DomDocumentFragment object.

Returns:

a newly created DomDocumentFragment.

createHtmlElement

public HtmlElement createHtmlElement(java.lang.String tagName)

Create a new HTML element with the given tag name.

Parameters:

tagName - The tag name, preferably in lowercase

Returns:

the new HTML element.

createHtmlElementNS

public HtmlElement createHtmlElementNS(java.lang.String namespaceURI,
                                       java.lang.String qualifiedName)

Create a new HtmlElement with the given namespace and qualified name.

Parameters:

namespaceURI - the URI that identifies an XML namespace.

qualifiedName - The qualified name of the element type to instantiate

Returns:

the new HTML element.

deregisterFramesIfNeeded

public void deregisterFramesIfNeeded()

Deregister frames that are no longer in use.

executeJavaScriptFunctionIfPossible

public ScriptResult executeJavaScriptFunctionIfPossible(org.mozilla.javascript.Function function,
                                                        org.mozilla.javascript.Scriptable thisObject,
                                                        java.lang.Object[] args,
                                                        DomNode htmlElementScope)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Execute a Function in the given context.

Parameters:

function - The javascript Function to call.

thisObject - The "this" object to be used during invocation.

args - The arguments to pass into the call.

htmlElementScope - The html element for which this script is being executed. This element will be the context during the javascript execution. If null, the context will default to the page.

Returns:

A ScriptResult which will contain both the current page (which may be different than the previous page and a javascript result object.

executeJavaScriptIfPossible

public ScriptResult executeJavaScriptIfPossible(java.lang.String sourceCode,
                                                java.lang.String sourceName,
                                                HtmlElement htmlElement)

Execute the specified javascript if a javascript engine was successfully instantiated. If this javascript causes the current page to be reloaded (through location="" or form.submit()) then return the new page. Otherwise return the current page.

Please note: Although this method is public, it is not intended for general execution of javascript. Users of HtmlUnit should interact with the pages as a user would by clicking on buttons or links and having the javascript event handlers execute as needed..

Parameters:

sourceCode - The javascript code to execute.

sourceName - The name for this chunk of code. This name will be displayed in any error messages.

htmlElement - The html element for which this script is being executed. This element will be the context during the javascript execution. If null, the context will default to the window.

Returns:

A ScriptResult which will contain both the current page (which may be different than the previous page and a javascript result object.

getAnchorByHref

public HtmlAnchor getAnchorByHref(java.lang.String href)
                           throws ElementNotFoundException

Return the HtmlAnchor with the specified href

Parameters:

href - The string to search by

Returns:

The HtmlAnchor

Throws:

ElementNotFoundException - If the anchor could not be found.

getAnchorByName

public HtmlAnchor getAnchorByName(java.lang.String name)
                           throws ElementNotFoundException

Return the HtmlAnchor with the specified name

Parameters:

name - The name to search by

Returns:

See above

Throws:

ElementNotFoundException - If the anchor could not be found.

getAnchors

public java.util.List getAnchors()

Return a list of all anchors contained in this page.

Returns:

the list of HtmlAnchor in this page.

getDocumentHtmlElement

public HtmlElement getDocumentHtmlElement()

Get the root HtmlElement of this document.

Returns:

The root element

getElementWithFocus

public FocusableElement getElementWithFocus()

Return the element with the focus or null if no element has the focus.

Returns:

The element with focus or null.

See Also:

moveFocusToElement(FocusableElement)

getEnclosingWindow

public WebWindow getEnclosingWindow()

Return the window that this page is sitting inside.

Specified by:

getEnclosingWindow in interface Page

Returns:

The enclosing frame or null if this page isn't inside a frame.

getFirstAnchorByText

public HtmlAnchor getFirstAnchorByText(java.lang.String text)
                                throws ElementNotFoundException

Return the first anchor that contains the specified text.

Parameters:

text - The text to search for

Returns:

The first anchor that was found.

Throws:

ElementNotFoundException - If no anchors are found with the specified text

getFormByName

public HtmlForm getFormByName(java.lang.String name)
                       throws ElementNotFoundException

Return the first form that matches the specified name

Parameters:

name - The name to search for

Returns:

The first form.

Throws:

ElementNotFoundException - If no forms match the specified result.

getForms

public java.util.List getForms()

Return a list of all the forms in the page.

Returns:

All the forms.

getFrameByName

public FrameWindow getFrameByName(java.lang.String name)
                           throws ElementNotFoundException

Returns the first frame contained in this page with the specified name.

Parameters:

name - The name to search for

Returns:

The first frame found.

Throws:

ElementNotFoundException - If no frame exist in this page with the specified name.

getFrames

public java.util.List getFrames()

Return a list containing all the frames (from frame and iframe tags) in this page.

Returns:

a list of FrameWindow

getFullyQualifiedUrl

public java.net.URL getFullyQualifiedUrl(java.lang.String relativeUrl)
                                  throws java.net.MalformedURLException

Given a relative url (ie /foo), return a fully qualified url based on the url that was used to load this page

Parameters:

relativeUrl - The relative url

Returns:

See above

Throws:

java.net.MalformedURLException - If an error occurred when creating a URL object

getHtmlElementByAccessKey

public HtmlElement getHtmlElementByAccessKey(char accessKey)

Return the html element that is assigned to the specified access key. An access key (aka mnemonic key) is used for keyboard navigation of the page.

Only the following html elements may have accesskey's defined: A, AREA, BUTTON, INPUT, LABEL, LEGEND, and TEXTAREA.

Parameters:

accessKey - The key to look for

Returns:

The html element that is assigned to the specified key or null if no elements can be found that match the specified key.

getHtmlElementById

public HtmlElement getHtmlElementById(java.lang.String id)
                               throws ElementNotFoundException

Returns the HTML element with the specified ID. If more than one element has this ID (not allowed by the HTML spec), then this method returns the first one.

Parameters:

id - the ID value to search by

Returns:

the HTML element with the specified ID

Throws:

ElementNotFoundException - if no element was found that matches the id

getHtmlElementsByAccessKey

public java.util.List getHtmlElementsByAccessKey(char accessKey)

Return all the html elements that are assigned to the specified access key. An access key (aka mnemonic key) is used for keyboard navigation of the page.

The html specification seems to indicate that one accesskey cannot be used for multiple elements however Internet Explorer does seem to support this. It's worth noting that Mozilla does not support multiple elements with one access key so you are making your html browser specific if you rely on this feature.

Only the following html elements may have accesskey's defined: A, AREA, BUTTON, INPUT, LABEL, LEGEND, and TEXTAREA.

Parameters:

accessKey - The key to look for

Returns:

A list of html elements that are assigned to the specified accesskey.

getHtmlElementsByName

public java.util.List getHtmlElementsByName(java.lang.String name)

Returns the HTML elements with the specified name attribute. If there are no elements with the specified name, this method returns an empty list. Please note that the lists returned by this method are immutable.

Parameters:

name - the name value to search by

Returns:

the HTML elements with the specified name attribute

getNodeName

public java.lang.String getNodeName()

Get the name for the current node.

Specified by:

getNodeName in class DomNode

Returns:

The node name

getNodeType

public short getNodeType()

Get the type of the current node.

Specified by:

getNodeType in class DomNode

Returns:

The node type

getPage

public HtmlPage getPage()

Description copied from class: DomNode

Return the HtmlPage that contains this node

Overrides:

getPage in class DomNode

Returns:

this page

getPageEncoding

public java.lang.String getPageEncoding()

Return the charset used in the page. The sources of this information are from 1).meta element which http-equiv attribute value is 'content-type', or if not from the response header.

Returns:

the value of charset.

getResolvedTarget

public java.lang.String getResolvedTarget(java.lang.String elementTarget)

Given a target attribute value, resolve the target using a base target for the page.

Parameters:

elementTarget - The target specified as an attribute of the element.

Returns:

The resolved target to use for the element.

getTabbableElementIds

public java.util.List getTabbableElementIds()

Return a list of ids (strings) that correspond to the tabbable elements in this page. Return them in the same order specified in getTabbableElements()

Returns:

The list of id's

getTabbableElements

public java.util.List getTabbableElements()

Return a list of all elements that are tabbable in the order that will be used for tabbing.

The rules for determing tab order are as follows:

1. Those elements that support the tabindex attribute and assign a positive value to it are navigated first. Navigation proceeds from the element with the lowest tabindex value to the element with the highest value. Values need not be sequential nor must they begin with any particular value. Elements that have identical tabindex values should be navigated in the order they appear in the character stream.
2. Those elements that do not support the tabindex attribute or support it and assign it a value of "0" are navigated next. These elements are navigated in the order they appear in the character stream.
3. Elements that are disabled do not participate in the tabbing order.

Additionally, the value of tabindex must be within 0 and 32767. Any values outside this range will be ignored.

The following elements support the tabindex attribute: A, AREA, BUTTON, INPUT, OBJECT, SELECT, and TEXTAREA.

Returns:

A list containing all the tabbable elements in proper tab order.

getTitleText

public java.lang.String getTitleText()

Return the title of this page or an empty string if the title wasn't specified.

Returns:

the title of this page or an empty string if the title wasn't specified.

getWebClient

public WebClient getWebClient()

Return the WebClient that originally loaded this page

Returns:

See above

getWebResponse

public WebResponse getWebResponse()

Return the web response that was originally used to create this page.

Specified by:

getWebResponse in interface Page

Returns:

The web response

initialize

public void initialize()
                throws java.io.IOException,
                       FailingHttpStatusCodeException

Initialize this page.

Specified by:

initialize in interface Page

Throws:

java.io.IOException - If an IO problem occurs.

FailingHttpStatusCodeException - If the server returns a failing status code AND the property WebClient.setThrowExceptionOnFailingStatusCode(boolean) is set to true.

isJavaScript

public static boolean isJavaScript(java.lang.String typeAttribute,
                                   java.lang.String languageAttribute)

INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Return true if a script with the specified type and language attributes is actually JavaScript. According to W3C recommendation are content types case insensitive.

Parameters:

typeAttribute - The type attribute specified in the script tag.

languageAttribute - The language attribute specified in the script tag.

Returns:

true if the script is javascript

moveFocusToElement

public boolean moveFocusToElement(FocusableElement newElement)

Move the focus to the specified component. This will trigger any relevant javascript event handlers.

Parameters:

newElement - The element that will receive the focus, use null to remove focus from any element

Returns:

true if the specified element now has the focus.

See Also:

getElementWithFocus(), tabToNextElement(), tabToPreviousElement(), pressAccessKey(char), assertAllTabIndexAttributesSet()

pressAccessKey

public HtmlElement pressAccessKey(char accessKey)
                           throws java.io.IOException

Simulate pressing an access key. This may change the focus, may click buttons and may invoke javascript.

Parameters:

accessKey - The key that will be pressed.

Returns:

The element that has the focus after pressing this access key or null if no element has the focus.

Throws:

java.io.IOException - If an io error occurs during the processing of this access key. This would only happen if the access key triggered a button which in turn caused a page load.

removeHtmlAttributeChangeListener

public void removeHtmlAttributeChangeListener(HtmlAttributeChangeListener listener)

Removes an HtmlAttributeChangeListener from the listener list. This method should be used to remove HtmlAttributeChangeListener that were registered for all attributes of all HtmlElements contained in this page.

Parameters:

listener - the attribute change listener to be removed.

See Also:

addHtmlAttributeChangeListener(HtmlAttributeChangeListener)

setEnclosingWindow

public void setEnclosingWindow(WebWindow window)

Set the window that contains this page.

Parameters:

window - The new frame or null if this page is being removed from a frame.

setTitleText

public void setTitleText(java.lang.String message)

Set the text for the title of this page. If there is not a title element on this page, then one has to be generated.

Parameters:

message - The new text

tabToNextElement

public HtmlElement tabToNextElement()

Move the focus to the next element in the tab order. To determine the specified tab order, refer to getTabbableElements()

Returns:

The element that has focus after calling this method.

tabToPreviousElement

public HtmlElement tabToPreviousElement()

Move the focus to the previous element in the tab order. To determine the specified tab order, refer to getTabbableElements()

Returns:

The element that has focus after calling this method.

toString

public java.lang.String toString()

Gives a basic representation for debugging purposes

Overrides:

toString in class java.lang.Object

Returns:

a basic representation