com.jauntium

Class Elements

java.lang.Object

com.jauntium.Elements

All Implemented Interfaces:

Iterable<Element>

public class Elements
extends Object
implements Iterable<Element>

A container class for holding Element objects that are search results, which is itself searchable using the tagQuery syntax. Each child element within the container represents a single search result.

Author:

Tom Cervenka

Method Summary

Modifier and Type	Method and Description
Elements	findEach(String query) Searches descendant elements and retrieves elements that were found to match the query, however for every matching element is found, the search does not continue into that element's descendants.
Elements	findEvery(String query)
Element	findFirst(String query) Searches all descendant elements and retrieves the first one found to match the query.
Elements	getEach(String query) Searches child elements (not all descendants) and retrieves those that were found to match the query.
Element	getElement(int index) Returns the element at the specified index.
Element	getFirst(String query) Searches only child elements (not all descendants) and retrieves the first child element that was found to match the query.
String	innerHTML() Returns a String representation of the container and its child elements as HTML, where the container itself is represented as an element who's tagName is #elements.
String	innerHTML(int indent)
Iterator<Element>	iterator() Returns an iterator over the child Elements.
String	outerHTML() Returns a String representation of the child elements as HTML.
String	outerHTML(int indent)
int	size() Returns the number of child Elements.
List<Element>	toList() Returns the child Elements as a List.
String	toString() Returns a partial HTML representation of this container and its children (not including descendants)

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

findEvery

public Elements findEvery(String query)

findEach

public Elements findEach(String query)

Searches descendant elements and retrieves elements that were found to match the query, however for every matching element is found, the search does not continue into that element's descendants.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

a container of type Elements holding the elements that were found by the search.

getEach

public Elements getEach(String query)

Searches child elements (not all descendants) and retrieves those that were found to match the query.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

a container of type Elements holding the elements that were found by the search.

findFirst

public Element findFirst(String query)
                  throws Exception

Searches all descendant elements and retrieves the first one found to match the query.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

first child that matches the specified parameters, or throws a NotFound Exception if one is not found.

Throws:

Exception

getFirst

public Element getFirst(String query)
                 throws Exception

Searches only child elements (not all descendants) and retrieves the first child element that was found to match the query.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

first child that matches the query, or throws a NotFound Exception if one is not found.

Throws:

Exception

toList

public List<Element> toList()

Returns the child Elements as a List.

Returns:

a List of the child elements.

iterator

public Iterator<Element> iterator()

Returns an iterator over the child Elements.

Specified by:

iterator in interface Iterable<Element>

size

public int size()

Returns the number of child Elements.

innerHTML

public String innerHTML()

Returns a String representation of the container and its child elements as HTML, where the container itself is represented as an element who's tagName is #elements.

innerHTML

public String innerHTML(int indent)

outerHTML

public String outerHTML()

Returns a String representation of the child elements as HTML.

outerHTML

public String outerHTML(int indent)

getElement

public Element getElement(int index)
                   throws IndexOutOfBoundsException

Returns the element at the specified index.

Parameters:

index - the index of the child element to be returned, where the first child has an index of 0.

Throws:

IndexOutOfBoundsException

toString

public String toString()

Returns a partial HTML representation of this container and its children (not including descendants)

Overrides:

toString in class Object