org.safs.selenium.webdriver.lib.model

Class AbstractSelectable

java.lang.Object

org.safs.selenium.webdriver.lib.model.EmbeddedObject

org.safs.selenium.webdriver.lib.model.AbstractSelectable

All Implemented Interfaces:

IOperable, ISelectable, Supportable

Direct Known Subclasses:

AbstractHierarchicalSelectable, AbstractListSelectable

public abstract class AbstractSelectable
extends EmbeddedObject
implements ISelectable

History:

  Apr 25, 2014    (Lei Wang) Initial release.
  May 29, 2014    (Lei Wang) Use single-click for selectItem, double-click for activateItem.
  Oct 15, 2014    (Lei Wang) Modify showOnPage(): move the code 'test visiblility' to super class.
  Nov 05, 2014    (Lei Wang) Add waitAndVerifyItemSelected(): used to verify item selection.
  

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<org.openqa.selenium.WebElement,Element[]>	contentObjects A cache, which stores a pair(WebElement, Element[])
protected int	DEFAULT_WAIT_TIME

Fields inherited from class org.safs.selenium.webdriver.lib.model.EmbeddedObject

parent

Constructor Summary

Constructors

Constructor and Description
AbstractSelectable(Component parent)

Method Summary

Modifier and Type	Method and Description
void	activateItem(TextMatchingCriterion criterion, boolean verify, org.openqa.selenium.Keys key, java.awt.Point offset) Try to activate (double-click) the item according to the item's text (fully or partially given), and then verify if the item has been really selected according to the parameter 'verify'.
void	clearCache() clear the cache 'contentObjects'.
protected void	clickElement(Element element, org.openqa.selenium.Keys key, java.awt.Point offset, int mouseButtonNumber, int numberOfClick) Try to get the Selenium WebElement object from parameter 'element', then click that WebElement object. After calling this method, the parent of Element may become stale.
protected Element[]	getCacheableContent() Get the real-time content from WebElement. For some components like Tree, Menu etc.
Element[]	getContent() Try to get the cached content according to the WebElement. If no cached content can be found, then get the real-time content by calling getCacheableContent(), and put the content in the cache and return it. If subclass doesn't need this functionality, then just override this method. If subclass needs this functionality, then override method getCacheableContent()
void	selectItem(TextMatchingCriterion criterion, boolean verify, org.openqa.selenium.Keys key, java.awt.Point offset, int mouseButtonNumber) Try to select (single-click) the item according to the item's text (fully or partially given), and then verify if the item has been really selected according to the parameter 'verify'.
protected void	showOnPage(Element element) Make the element is in the container, and visible on the page. For example, some element may not be visible if there are too many elements in its container; User can scroll to make the element visible on the page. User may need to wait for a while so that the element related object can be updated (like position-onscreen, visibility etc.) This method gives a default implementation: it will scroll and align the top of element to the top of container. Before this method is called, it is suggested to call EmbeddedObject.isShowOnPage(Element) firstly.
void	verifyContains(TextMatchingCriterion criterion) Verify the item (specified by text, partialMatch and matchIndex) is contained.
protected void	verifyItemSelected(Element element) Note:In subclass, we need to update the 'selected' property of Element. Please call waitAndVerifyItemSelected(Element) instead to verify selection, as the first method will also try the wait for element to be ready and call EmbeddedObject.refresh(boolean).
protected void	verifyItemSelection(Element element, boolean expectSelected)
void	verifyItemSelection(TextMatchingCriterion criterion, boolean expectSelected) Verify the item (specified by text, partialMatch and matchIndex) is selected or un-selected.
protected void	waitAndVerifyItemSelected(Element element) Wait Item ready, and verify the item has been selected. Before verification, we need to refresh the parent if the page doesn't change.
protected void	waitElementReady(Element element) Wait for element ready, means that element's attribute has been updated. This method just wait 200 milliseconds, subclass may give a more detail implementation.
protected void	waitElementReady(Element element, int milliseconds) Wait for element ready, means that element's attribute has been updated. This method just wait some time, subclass may give a more detail implementation. When this method will be called? For example, before calling verifyItemSelected(Element), because verifyItemSelected(Element) needs to check element's attributes.

Methods inherited from class org.safs.selenium.webdriver.lib.model.EmbeddedObject

isShowOnPage, isSupported, refresh, webelement

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.safs.selenium.webdriver.lib.model.ISelectable

activateItem, getMatchedElement, selectItem, verifyItemSelection

Methods inherited from interface org.safs.selenium.webdriver.lib.model.Supportable

getSupportedClassNames

Field Detail

DEFAULT_WAIT_TIME

protected int DEFAULT_WAIT_TIME

contentObjects

protected java.util.Map<org.openqa.selenium.WebElement,Element[]> contentObjects

A cache, which stores a pair(WebElement, Element[])

Constructor Detail

AbstractSelectable

public AbstractSelectable(Component parent)
                   throws SeleniumPlusException

Throws:

SeleniumPlusException

Method Detail

getContent

public Element[] getContent()
                     throws SeleniumPlusException

Try to get the cached content according to the WebElement.
If no cached content can be found, then get the real-time content by calling getCacheableContent(),
and put the content in the cache and return it.
If subclass doesn't need this functionality, then just override this method.
If subclass needs this functionality, then override method getCacheableContent()

Specified by:

getContent in interface ISelectable

Returns:

Element[] an array of the element

Throws:

SeleniumPlusException

See Also:

getCacheableContent()

getCacheableContent

protected Element[] getCacheableContent()
                                 throws SeleniumPlusException

Get the real-time content from WebElement.
For some components like Tree, Menu etc. it is time-consuming to retrieve content,
user may implement this method instead of getContent() so that the retrived content
will be kept in cache, and getContent() will use the content in the cache.

Throws:

SeleniumPlusException

See Also:

getContent()

clearCache

public void clearCache()

clear the cache 'contentObjects'.

Specified by:

clearCache in interface IOperable

selectItem

public void selectItem(TextMatchingCriterion criterion,
                       boolean verify,
                       org.openqa.selenium.Keys key,
                       java.awt.Point offset,
                       int mouseButtonNumber)
                throws SeleniumPlusException

Description copied from interface: ISelectable

Try to select (single-click) the item according to the item's text (fully or partially given), and then verify if the item has been really selected according to the parameter 'verify'. If the parameter key is provided, the selection will happen with that key pressed at the same time. If the parameter offset is provided, then click at offset relative to the top-left corner of view; otherwise at the center. The parameter mouseButtonNumber decides right-click or left-click.
Note: There are maybe some callback methods associated with the item-container, but setting select text MAY NOT invoke them, in the implementation of this method we should make sure those callbacks are invoked (we can fire some events.)

Specified by:

selectItem in interface ISelectable

Parameters:

criterion - TextMatchingCriterion, containing text, partialMatch, matchedIndex as search-criterion.

verify - boolean, if true then verify the selection;

key - org.openqa.selenium.Keys, it is the key to press during selection.
for example Keys.SHIFT, or Keys.CONTROL.
If user doesn't want any key pressed, please provide null

offset - Point, the position relative to the up-left corner to click at
If user provides null, then the center of the item will be used

mouseButtonNumber - int, the mouse-button-number representing right, middle, or left button.
it can be WDLibrary.MOUSE_BUTTON_LEFT or WDLibrary.MOUSE_BUTTON_RIGHT
or WDLibrary.MOUSE_BUTTON_MIDDLE.

Throws:

SeleniumPlusException

activateItem

public void activateItem(TextMatchingCriterion criterion,
                         boolean verify,
                         org.openqa.selenium.Keys key,
                         java.awt.Point offset)
                  throws SeleniumPlusException

Description copied from interface: ISelectable

Try to activate (double-click) the item according to the item's text (fully or partially given), and then verify if the item has been really selected according to the parameter 'verify'. If the parameter key is provided, the selection will happen with that key pressed at the same time.

Specified by:

activateItem in interface ISelectable

Parameters:

criterion - TextMatchingCriterion, containing text, partialMatch, matchedIndex as search-criterion.

verify - boolean, if true then verify the selection;

key - org.openqa.selenium.Keys, it is the key to press during selection.
for example Keys.SHIFT, or Keys.CONTROL.
If user doesn't want any key pressed, please provide null

offset - Point, the position relative to the up-left corner to click at
If user provides null, then the center of the item will be used

Throws:

SeleniumPlusException

verifyContains

public void verifyContains(TextMatchingCriterion criterion)
                    throws SeleniumPlusException

Description copied from interface: ISelectable

Verify the item (specified by text, partialMatch and matchIndex) is contained.

Specified by:

verifyContains in interface ISelectable

Parameters:

criterion - TextMatchingCriterion, containing text, partialMatch, matchedIndex as search-criterion.

Throws:

SeleniumPlusException - if the verification fails.

verifyItemSelection

public void verifyItemSelection(TextMatchingCriterion criterion,
                                boolean expectSelected)
                         throws SeleniumPlusException

Description copied from interface: ISelectable

Verify the item (specified by text, partialMatch and matchIndex) is selected or un-selected.

Specified by:

verifyItemSelection in interface ISelectable

Parameters:

criterion - TextMatchingCriterion, containing text, partialMatch, matchedIndex as search-criterion.

expectSelected - boolean, true if the item is expected 'selected'; false if expected 'unselected'.

Throws:

SeleniumPlusException - if the verification fails.

verifyItemSelection

protected void verifyItemSelection(Element element,
                                   boolean expectSelected)
                            throws SeleniumPlusException

Parameters:

element - Element, the element to check.

expectSelected - boolean, true if the element is expected 'selected'; false if expected 'unselected'.

Throws:

SeleniumPlusException - if the verification fails.

clickElement

protected void clickElement(Element element,
                            org.openqa.selenium.Keys key,
                            java.awt.Point offset,
                            int mouseButtonNumber,
                            int numberOfClick)
                     throws SeleniumPlusException

Try to get the Selenium WebElement object from parameter 'element', then click that WebElement object.
After calling this method, the parent of Element may become stale. We may need to call EmbeddedObject.refresh(boolean).
Atter calling this method, user may need to verify that element has been selected. Please call waitAndVerifyItemSelected(Element)
instead of verifyItemSelected(Element), as the first method will also try the wait for element
to be ready and call EmbeddedObject.refresh(boolean).

Parameters:

element - Element, the element to select

key - org.openqa.selenium.Keys, it is the key to press during selection.
for example Keys.SHIFT, or Keys.CONTROL.
If user doesn't want any key pressed, please provide null.

offset - Point, the position relative to the up-left corner to click at

mouseButtonNumber - int, the mouse-button-number representing right, middle, or left button. it can be WDLibrary.MOUSE_BUTTON_LEFT or WDLibrary.MOUSE_BUTTON_RIGHT
or WDLibrary.MOUSE_BUTTON_MIDDLE.

numberOfClick - int, 1 means single-click, 2 means double-click

Throws:

SeleniumPlusException

See Also:

#refresh(boolean)}, waitAndVerifyItemSelected(Element)

showOnPage

protected void showOnPage(Element element)
                   throws SeleniumPlusException

Make the element is in the container, and visible on the page.
For example, some element may not be visible if there are too many elements in its container;
User can scroll to make the element visible on the page.
User may need to wait for a while so that the element related object can be updated (like position-onscreen, visibility etc.)

This method gives a default implementation:
it will scroll and align the top of element to the top of container.
Before this method is called, it is suggested to call EmbeddedObject.isShowOnPage(Element) firstly.

Parameters:

element - Element, the element needs to be visible on page

Throws:

SeleniumPlusException

See Also:

#isShowOnPage(Element)}

waitElementReady

protected void waitElementReady(Element element,
                                int milliseconds)
                         throws SeleniumPlusException

Wait for element ready, means that element's attribute has been updated.
This method just wait some time, subclass may give a more detail implementation.
When this method will be called?
For example, before calling verifyItemSelected(Element), because
verifyItemSelected(Element) needs to check element's attributes.

Parameters:

element - Element, the element needs to be ready

milliseconds - int, the time to wait

Throws:

SeleniumPlusException

See Also:

#verifyItemSelected(Element)}

waitElementReady

protected void waitElementReady(Element element)
                         throws SeleniumPlusException

Wait for element ready, means that element's attribute has been updated.
This method just wait 200 milliseconds, subclass may give a more detail implementation.

Parameters:

element - Element, the element needs to be ready

Throws:

SeleniumPlusException

waitAndVerifyItemSelected

protected void waitAndVerifyItemSelected(Element element)
                                  throws SeleniumPlusException

Wait Item ready, and verify the item has been selected.
Before verification, we need to refresh the parent if the page doesn't change.

Parameters:

element - Element, the element has been selected or clicked or double-clicked.

Throws:

SeleniumPlusException

See Also:

#verifyItemSelected(Element)}

verifyItemSelected

protected void verifyItemSelected(Element element)
                           throws SeleniumPlusException

Note:In subclass, we need to update the 'selected' property of Element.
Please call waitAndVerifyItemSelected(Element) instead to verify selection,
as the first method will also try the wait for element to be ready and call EmbeddedObject.refresh(boolean).

Parameters:

element - Element, the element to verify that it is selected.

Throws:

SeleniumPlusException