abbot.script
Class ComponentReference

java.lang.Object
  abbot.script.ComponentReference

All Implemented Interfaces:

XMLConstants, XMLifiable, Comparable

public class ComponentReference
extends Object
implements XMLConstants, XMLifiable, Comparable

Encapsulate as much information as is available to identify a GUI component. Usage:

<component id="..." class="..." [...]>


The component reference ID may be used in scripts in place of the actual component to which this reference refers. The conversion will be made when the actual component is needed. The ID is arbitrary, and may be changed in scripts to any unique string (just remember to change all references to the ID in other places in the script as well).

A number of optional tags are supported to provide an increasingly precise specification of the desired component:

• weighted refers to the name of an available attribute which should be weighted more heavily in comparisons, e.g. the label on a JButton.
  
• parent the reference id of this component's parent.
  

ComponentReferences may be created in one of three ways, each of which has slightly different implications.

• Resolver.addComponent(Component) - creates a reference if one doesn't already exist and modifiers the Resolver to include it.
• getReference(Resolver, Component, Map) - create a reference only if a matching one does not exist, but does not modify the Resolver.
• ComponentReference - create a new reference.

Field Summary

(package private) static String	ANON_INNER_CLASS
(package private) static boolean	cacheOnCreation Disable immediate cacheing of components when a reference is created based on a Component.
static int	MW_FAILURE Match weight corresponding to no possible match.
static String	SHARED_FRAME_ID

Fields inherited from interface abbot.script.XMLConstants

TAG_ACTION, TAG_APPLETVIEWER, TAG_ARCHIVE, TAG_ARGS, TAG_ASSERT, TAG_AWT, TAG_AWTTESTSCRIPT, TAG_BORDER_TITLE, TAG_CALL, TAG_CLASS, TAG_CLASSPATH, TAG_CODE, TAG_CODEBASE, TAG_COMMENT, TAG_COMPONENT, TAG_COUNT, TAG_DELEGATE, TAG_DESC, TAG_DOCBASE, TAG_EVENT, TAG_EXPR, TAG_FILENAME, TAG_FIXTURE, TAG_FORKED, TAG_HEIGHT, TAG_HORDER, TAG_ICON, TAG_ID, TAG_INDEX, TAG_INVERT, TAG_INVOKER, TAG_KEYCHAR, TAG_KEYCODE, TAG_KIND, TAG_LABEL, TAG_LAUNCH, TAG_METHOD, TAG_MODIFIERS, TAG_NAME, TAG_PARAMS, TAG_PARENT, TAG_POLL_INTERVAL, TAG_PROPERTY, TAG_ROOT, TAG_SAMPLE, TAG_SCRIPT, TAG_SEQUENCE, TAG_SLOW, TAG_STOP_ON_ERROR, TAG_STOP_ON_FAILURE, TAG_TAG, TAG_TERMINATE, TAG_TEXT, TAG_THREADED, TAG_TIMEOUT, TAG_TITLE, TAG_TRIGGER, TAG_TYPE, TAG_VALUE, TAG_VMARGS, TAG_VORDER, TAG_WAIT, TAG_WEIGHTED, TAG_WIDTH, TAG_WINDOW, TAG_X, TAG_Y

Constructor Summary

ComponentReference(Resolver resolver, Class cls, Map attributes)
Create a reference to an instance of the given class, given a Map of attributes.

ComponentReference(Resolver r, Class cls, String[][] attributes)
Create a reference to an instance of the given class, given an array of name/value pairs of attributes.

ComponentReference(Resolver resolver, Component comp)
Create a reference based on the given component.

ComponentReference(Resolver resolver, Component comp, Map newReferences)
Create a reference based on the given component.

ComponentReference(Resolver resolver, Element el)
For creation from XML.

Method Summary

int	compareTo(Object o)
boolean	equals(Object obj) Two ComponentReferences with identical XML representations should be equal.
(package private) boolean	expressionMatch(String pattern, String actual) Return whether the given pattern matches the given string.
void	fromXML(String input) Deprecated.
String	getAttribute(String key)
Map	getAttributes()
(package private) Component	getCachedLookup(Hierarchy hierarchy) Return the cached component match, if any.
Component	getComponent() Return the component in the current Hierarchy that best matches this reference.
Component	getComponent(Hierarchy hierarchy) Return the component in the given Hierarchy that best matches this reference.
String	getDescriptiveName() Return a suitably descriptive name for this reference, for use as an ID (returns the ID itself if already set).
static String	getDescriptiveName(Component c) Deprecated. Use Robot.getDescriptiveName(Component) instead
String	getID()
ComponentReference	getInvokerReference(Map newReferences)
(package private) int	getMatchWeight(Component comp) Return a measure of how well the given component matches the given component reference.
(package private) static String	getOrder(Component original, Component[] matchList, boolean horizontal) Return the order of the given component among the array given, sorted by horizontal or vertical screen position.
ComponentReference	getParentReference(Map newRefs)
String	getRefClassName()
static ComponentReference	getReference(Resolver r, Component comp, Map newReferences) Returns a reference to the given component, preferring an existing reference if a matching one is available or creating a new one if not.
String	getUniqueID(Map refs)
ComponentReference	getWindowReference(Map newReferences) Reference ID of this component's parent window (optional).
boolean	isAssignableFrom(Class cls) Return whether this reference has the same class or is a superclass of the given component's class.
static ComponentReference	matchExisting(Component comp, Collection existing) Match the given component against an existing set of references.
static ComponentReference	matchExisting(Component comp, Collection existing, Map newReferences) Match the given component against an existing set of references.
void	setAttribute(String key, String value)
String	toEditableString() Deprecated. Used to be used to edit XML in a text editor.
String	toString() Return a human-readable representation.
Element	toXML() Generate an XML representation of this object.
String	toXMLString()

Methods inherited from class java.lang.Object

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

Field Detail

SHARED_FRAME_ID

public static final String SHARED_FRAME_ID

See Also:

Constant Field Values

MW_FAILURE

public static final int MW_FAILURE

Match weight corresponding to no possible match.

See Also:

Constant Field Values

ANON_INNER_CLASS

static final String ANON_INNER_CLASS

See Also:

Constant Field Values

cacheOnCreation

static boolean cacheOnCreation

Disable immediate cacheing of components when a reference is created based on a Component. Cacheing will first be done when the reference is resolved for the first time after creation. For testing purposes only.

Constructor Detail

ComponentReference

public ComponentReference(Resolver resolver,
                          Element el)
                   throws InvalidScriptException

For creation from XML.

Throws:

InvalidScriptException

ComponentReference

public ComponentReference(Resolver r,
                          Class cls,
                          String[][] attributes)

Create a reference to an instance of the given class, given an array of name/value pairs of attributes.

ComponentReference

public ComponentReference(Resolver resolver,
                          Class cls,
                          Map attributes)

Create a reference to an instance of the given class, given a Map of attributes.

ComponentReference

public ComponentReference(Resolver resolver,
                          Component comp)

Create a reference based on the given component. Will not use or create any ancestor components/references.

ComponentReference

public ComponentReference(Resolver resolver,
                          Component comp,
                          Map newReferences)

Create a reference based on the given component. May recursively create other components required to identify this one.

Method Detail

getComponent

public Component getComponent()
                       throws ComponentNotFoundException,
                              MultipleComponentsFoundException

Return the component in the current Hierarchy that best matches this reference.

Throws:

ComponentNotFoundException

MultipleComponentsFoundException

getComponent

public Component getComponent(Hierarchy hierarchy)
                       throws ComponentNotFoundException,
                              MultipleComponentsFoundException

Return the component in the given Hierarchy that best matches this reference.

Throws:

ComponentNotFoundException

MultipleComponentsFoundException

getDescriptiveName

public static String getDescriptiveName(Component c)

Deprecated. Use Robot.getDescriptiveName(Component) instead

Return a descriptive name for the given component for use in UI text (may be localized if appropriate and need not be re-usable across locales.

getDescriptiveName

public String getDescriptiveName()

Return a suitably descriptive name for this reference, for use as an ID (returns the ID itself if already set). Will never return an empty String.

getID

public String getID()

getRefClassName

public String getRefClassName()

getAttribute

public String getAttribute(String key)

getAttributes

public Map getAttributes()

setAttribute

public void setAttribute(String key,
                         String value)

isAssignableFrom

public boolean isAssignableFrom(Class cls)

Return whether this reference has the same class or is a superclass of the given component's class. Simply compare class names to avoid class loader conflicts. Note that this does not take into account interfaces (which is okay, since with GUI components we're only concerned with class inheritance).

getParentReference

public ComponentReference getParentReference(Map newRefs)

getWindowReference

public ComponentReference getWindowReference(Map newReferences)

Reference ID of this component's parent window (optional).

getInvokerReference

public ComponentReference getInvokerReference(Map newReferences)

fromXML

public void fromXML(String input)
             throws InvalidScriptException,
                    IOException

Deprecated.

Set all options based on the given XML.

Throws:

InvalidScriptException

IOException

toXML

public Element toXML()

Generate an XML representation of this object.

Specified by:

toXML in interface XMLifiable

toEditableString

public String toEditableString()

Deprecated. Used to be used to edit XML in a text editor.

Description copied from interface: XMLifiable

Provide an editable string representation of the object. Usually will be a String form of the XML, but may be something simpler if it doesn't make sense to provide the full XML.

Specified by:

toEditableString in interface XMLifiable

equals

public boolean equals(Object obj)

Two ComponentReferences with identical XML representations should be equal.

Overrides:

equals in class Object

toString

public String toString()

Return a human-readable representation.

Overrides:

toString in class Object

toXMLString

public String toXMLString()

getOrder

static String getOrder(Component original,
                       Component[] matchList,
                       boolean horizontal)

Return the order of the given component among the array given, sorted by horizontal or vertical screen position. All components with the same effective value will have the same order.

getMatchWeight

int getMatchWeight(Component comp)

Return a measure of how well the given component matches the given component reference. The weight performs two functions; one is to loosely match so that we can find a component even if some of its attributes have changed. The other is to distinguish between similar components.

In general, we want to match if we get any weight at all, and there's only one component that matches.

getReference

public static ComponentReference getReference(Resolver r,
                                              Component comp,
                                              Map newReferences)

Returns a reference to the given component, preferring an existing reference if a matching one is available or creating a new one if not. The new references are not added to the resolver.

matchExisting

public static ComponentReference matchExisting(Component comp,
                                               Collection existing)

Match the given component against an existing set of references.

matchExisting

public static ComponentReference matchExisting(Component comp,
                                               Collection existing,
                                               Map newReferences)

Match the given component against an existing set of references. Extended method that also takes in a list of new references that might have been created in this cycle

expressionMatch

boolean expressionMatch(String pattern,
                        String actual)

Return whether the given pattern matches the given string. Performs variable substitution on the pattern.

getCachedLookup

Component getCachedLookup(Hierarchy hierarchy)

Return the cached component match, if any.

compareTo

public int compareTo(Object o)

Specified by:

compareTo in interface Comparable

getUniqueID

public String getUniqueID(Map refs)