org.eclipse.actf.model.locate
Interface INodeLocator

All Known Implementing Classes:
AbstractNodeLocator, AccessibleNodeLocator, DomNodeLocator, MozillaDomNodeLocator

public interface INodeLocator

an interface to aid processing engines in locating or describing components of a model during a process. Implementations perform two primary functions:

Implementations are model-specific and should be defined within model configuration files. They should also not implement this interface directly, but extend AbstractNodeLocator.

Author:
Mike Squillace
See Also:
AbstractNodeLocator

Method Summary
 Properties describe(Object element)
          describe the specified element.
 Object find(String path, Object startNode)
          finds an object in a model given the specified path.
 Object[] findAll(String path, Object startNode)
          finds all objects in a model that match the specified path.
 String locate(Object element, Object root)
          locate a component within a model from the given root.
 

Method Detail

locate

String locate(Object element,
              Object root)
locate a component within a model from the given root. The returned string represents an XPath location path that uniquely determines the component's location within the graph starting with the given root. This method can be used in conjunction with describey to provide a richer description of the component.

Parameters:
element - element within a graph to be located
root - - root from which element is to be located or null if element is to be found from a start node in the graph
Returns:
string that uniquely locates element within the model
See Also:
XPath specification

find

Object find(String path,
            Object startNode)
finds an object in a model given the specified path. The path must be a valid XPath expression according to the XPath 1.0 specification. A path that is returned by locate is just such a path.

If a startNode is specified, the path is assumed to have that startNode as its context node. If the startNode is null, the model's start nodes will be used as supplying potential context nodes for the path.

The parameters for searching for a node can be defined in the Configuration.MODEL_ID symbol pool using the public symbolic constants of this interface.

Parameters:
path - - path to desired node in the model
startNode - - context for the path (may be null)
Returns:
desired node or null if no object in the model matches the given path
See Also:
XPath 1.0 Specification

findAll

Object[] findAll(String path,
                 Object startNode)
finds all objects in a model that match the specified path. The path must be a valid XPath expression according to the XPath 1.0 specification. A path that is returned by locate is just such a path.

If a startNode is specified, the path is assumed to have that startNode as its context node. If the startNode is null, the model's start nodes will be used as supplying potential context nodes for the path.

The parameters for searching for a node can be defined in the Configuration.MODEL_ID symbol pool using the public symbolic constants of this interface.

Parameters:
path - - path to desired nodes in the model
startNode - - context for the path (may be null)
Returns:
desired nodes or an empty array if no objects in the model match the given path
See Also:
XPath 1.0 Specification

describe

Properties describe(Object element)
describe the specified element. Identification may occur by providing the element's name, id, location on screen, textual content, and the like. The primary goal of this method is to return a set of properties that will aid developers or testers in finding the element in the context in which it was originally created, defined, or rendered. Thus, the returned set of properties is usually meant to be displayed.

Parameters:
element - element to be described or distinguished
Returns:
set of properties distinguishing the element