com.vaadin.client.componentlocator.LocatorStrategy Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of vaadin-client Show documentation
Show all versions of vaadin-client Show documentation
Vaadin is a web application framework for Rich Internet Applications (RIA).
Vaadin enables easy development and maintenance of fast and
secure rich web
applications with a stunning look and feel and a wide browser support.
It features a server-side architecture with the majority of the logic
running
on the server. Ajax technology is used at the browser-side to ensure a
rich
and interactive user experience.
/*
* Copyright 2000-2016 Vaadin Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.vaadin.client.componentlocator;
import java.util.List;
import com.google.gwt.dom.client.Element;
/**
* This interface should be implemented by all locator strategies. A locator
* strategy is responsible for generating and decoding a string that identifies
* an element in the DOM. A strategy can implement its own syntax for the
* locator string, which may be completely different from any other strategy's
* syntax.
*
* @since 7.2
* @author Vaadin Ltd
*/
public interface LocatorStrategy {
/**
* Test the given input path for formatting errors. If a given path can not
* be validated, the locator strategy will not be attempted.
*
* @param path
* a locator path expression
* @return true, if the implementing class can process the given path,
* otherwise false
*/
boolean validatePath(String path);
/**
* Generates a String locator which uniquely identifies the target element.
* The {@link #getElementByPath(String)} method can be used for the inverse
* operation, i.e. locating an element based on the return value from this
* method.
*
* Note that getElementByPath(getPathForElement(element)) == element is not
* always true as #getPathForElement(Element) can return a path to another
* element if the widget determines an action on the other element will give
* the same result as the action on the target element.
*
*
* @param targetElement
* The element to generate a path for.
* @return A String locator that identifies the target element or null if a
* String locator could not be created.
*/
String getPathForElement(Element targetElement);
/**
* Locates an element using a String locator (path) which identifies a DOM
* element. The {@link #getPathForElement(Element)} method can be used for
* the inverse operation, i.e. generating a string expression for a DOM
* element.
*
* @param path
* The String locator which identifies the target element.
* @return The DOM element identified by {@code path} or null if the element
* could not be located.
*/
Element getElementByPath(String path);
/**
* Locates an element using a String locator (path) which identifies a DOM
* element. The path starts from the specified root element.
*
* @see #getElementByPath(String)
*
* @param path
* The String locator which identifies the target element.
* @param root
* The element that is at the root of the path.
* @return The DOM element identified by {@code path} or null if the element
* could not be located.
*/
Element getElementByPathStartingAt(String path, Element root);
/**
* Locates all elements that match a String locator (path) which identifies
* DOM elements.
*
* This functionality is limited in {@link LegacyLocatorStrategy}.
*
* @param path
* The String locator which identifies target elements.
* @return List that contains all matched elements. Empty list if none
* found.
*/
List getElementsByPath(String path);
/**
* Locates all elements that match a String locator (path) which identifies
* DOM elements. The path starts from the specified root element.
*
* This functionality is limited in {@link LegacyLocatorStrategy}.
*
* @see #getElementsByPath(String)
*
* @param path
* The String locator which identifies target elements.
* @param root
* The element that is at the root of the path.
* @return List that contains all matched elements. Empty list if none
* found.
*/
List getElementsByPathStartingAt(String path, Element root);
}