* Take the following HTML segment as an example: *
* <p>This is a sample paragraph.</p>
*
* The whole segment is represented by an Element object. This is comprised of the {@link StartTag} "<p>",
* the {@link EndTag} "</p>", as well as the text in between.
* An element may also contain other elements between its start and end tags.
*
* The term normal element refers to an element having a {@linkplain #getStartTag() start tag} * with a {@linkplain StartTag#getStartTagType() type} of {@link StartTagType#NORMAL}. * This comprises all {@linkplain HTMLElements HTML elements} and non-HTML elements. *
* Element instances are obtained using one of the following methods:
*
* The three possible structures of an element are listed below: *
<img src="mypicture.jpg">
*
* The element consists only of a single {@linkplain #getStartTag() start tag} and has no {@linkplain #getContent() element content}
* (although the start tag itself may have {@linkplain StartTag#getTagContent() tag content}).
*
{@link #getEndTag()}==null
*
{@link #isEmpty()}==true
*
{@link #getEnd() getEnd()}=={@link #getStartTag()}.{@link #getEnd() getEnd()}
*
* This occurs in the following situations: *
<p>This is a sample paragraph.</p>
*
* The element consists of a {@linkplain #getStartTag() start tag}, {@linkplain #getContent() content},
* and an {@linkplain #getEndTag() end tag}.
*
{@link #getEndTag()}!=null.
*
{@link #isEmpty()}==false (provided the end tag doesn't immediately follow the start tag)
*
{@link #getEnd() getEnd()}=={@link #getEndTag()}.{@link #getEnd() getEnd()}.
*
* This occurs in the following situations, assuming the start tag's matching end tag is present in the source document: *
<p>This text is included in the paragraph element even though no end tag is present.<p>This is the next paragraph.
*
* The element consists of a {@linkplain #getStartTag() start tag} and {@linkplain #getContent() content},
* but no {@linkplain #getEndTag() end tag}.
*
{@link #getEndTag()}==null.
*
{@link #isEmpty()}==false
*
{@link #getEnd() getEnd()}!={@link #getStartTag()}.{@link #getEnd() getEnd()}.
*
* This only occurs in an HTML element for which the * {@linkplain HTMLElements#getEndTagOptionalElementNames() end tag is optional}. *
* The element ends at the start of a tag which implies the termination of the element, called the implicitly terminating tag. * If the implicitly terminating tag is situated immediately after the element's {@linkplain #getStartTag() start tag}, * the element is classed as a single tag element. *
* See the element parsing rules for HTML elements with optional end tags * for details on which tags can implicitly terminate a given element. *
* See also the documentation of the {@link HTMLElements#getEndTagOptionalElementNames()} method. *
*
* The {@link Source#fullSequentialParse()} method must be called (either explicitly or implicitly) immediately after construction of the Source object if this method is to be used.
* An IllegalStateException is thrown if a full sequential parse has not been performed or if it was performed after this element was found.
*
* This method returns null for a top-level element,
* as well as any element formed from a {@linkplain TagType#isServerTag() server tag}, regardless of whether it is nested inside a normal element.
*
* See the {@link Source#getChildElements()} method for more details.
*
* @return the parent of this element in the document element hierarchy, or null if this element is a top-level element.
* @throws IllegalStateException if a {@linkplain Source#fullSequentialParse() full sequential parse} has not been performed or if it was performed after this element was found.
* @see #getChildElements()
*/
public Element getParentElement() {
if (parentElement==Element.NOT_CACHED) {
if (!source.wasFullSequentialParseCalled()) throw new IllegalStateException("This operation is only possible after a full sequential parse has been performed");
if (startTag.isOrphaned()) throw new IllegalStateException("This operation is only possible if a full sequential parse was performed immediately after construction of the Source object");
source.getChildElements();
if (parentElement==Element.NOT_CACHED) parentElement=null;
}
return parentElement;
}
/**
* Returns a list of the immediate children of this element in the document element hierarchy.
*
* The objects in the list are all of type {@link Element}. *
* See the {@link Source#getChildElements()} method for more details.
*
* @return a list of the immediate children of this element in the document element hierarchy, guaranteed not
* The {@link Source#fullSequentialParse()} method must be called (either explicitly or implicitly) after construction of the
* A top-level element has a nesting depth of
* An element formed from a {@linkplain TagType#isServerTag() server tag} always have a nesting depth of
* See the {@link Source#getChildElements()} method for more details.
*
* @return the nesting depth of this element in the document element hierarchy.
* @throws IllegalStateException if a {@linkplain Source#fullSequentialParse() full sequential parse} has not been performed or if it was performed after this element was found.
* @see #getParentElement()
*/
public int getDepth() {
if (depth==-1) {
getParentElement();
if (depth==-1) depth=0;
}
return depth;
}
/**
* Returns the segment representing the content of the element.
*
* This segment spans between the end of the start tag and the start of the end tag.
* If the end tag is not present, the content reaches to the end of the element.
*
* A zero-length segment is returned if the element is {@linkplain #isEmpty() empty},
*
* @return the segment representing the content of the element, guaranteed not
* If the element has no end tag this method returns
* This is equivalent to {@link #getStartTag()}
* See the {@link Tag#getName()} method for more information.
*
* @return the name of the {@linkplain #getStartTag() start tag} of this element, always in lower case.
*/
public String getName() {
return startTag.getName();
}
/**
* Indicates whether this element has zero-length {@linkplain #getContent() content}.
*
* This is equivalent to {@link #getContent()}
* Note that this is a broader definition than that of both the
* HTML definition of an empty element,
* which is only those elements whose end tag is {@linkplain HTMLElements#getEndTagForbiddenElementNames() forbidden}, and the
* XML definition of an empty element,
* which is "either a start-tag immediately followed by an end-tag, or an {@linkplain #isEmptyElementTag() empty-element tag}".
* The other possibility covered by this property is the case of an HTML element with an
* {@linkplain HTMLElements#getEndTagOptionalElementNames() optional} end tag that is immediately followed by another tag that implicitly
* terminates the element.
*
* @return
* This is equivalent to {@link #getStartTag()}
* This is equivalent to {@link #getStartTag()}
* Returns
* This is equivalent to {@link #getStartTag()}null.
* @see #getParentElement()
*/
@Override public final ListSource object if this method is to be used.
* An IllegalStateException is thrown if a full sequential parse has not been performed or if it was performed after this element was found.
* 0.
* 0,
* regardless of whether it is nested inside a normal element.
* null.
*/
public Segment getContent() {
if (content==null) content=new Segment(source,startTag.end,getContentEnd());
return content;
}
/**
* Returns the start tag of the element.
* @return the start tag of the element.
*/
public StartTag getStartTag() {
return startTag;
}
/**
* Returns the end tag of the element.
* null.
*
* @return the end tag of the element, or null if the element has no end tag.
*/
public EndTag getEndTag() {
return endTag;
}
/**
* Returns the {@linkplain StartTag#getName() name} of the {@linkplain #getStartTag() start tag} of this element, always in lower case.
* .{@link StartTag#getName() getName()}.
* .{@link Segment#length() length()}==0.
* true if this element has zero-length {@linkplain #getContent() content}, otherwise false.
* @see #isEmptyElementTag()
*/
public boolean isEmpty() {
return startTag.end==getContentEnd();
}
/**
* Indicates whether this element is an empty-element tag.
* .{@link StartTag#isEmptyElementTag() isEmptyElementTag()}.
*
* @return true if this element is an empty-element tag, otherwise false.
*/
public boolean isEmptyElementTag() {
return startTag.isEmptyElementTag();
}
/**
* Returns the attributes specified in this element's start tag.
* .{@link StartTag#getAttributes() getAttributes()}.
*
* @return the attributes specified in this element's start tag.
* @see StartTag#getAttributes()
*/
public Attributes getAttributes() {
return getStartTag().getAttributes();
}
/**
* Returns the {@linkplain CharacterReference#decode(CharSequence) decoded} value of the attribute with the specified name (case insensitive).
* null if the {@linkplain #getStartTag() start tag of this element} does not
* {@linkplain StartTagType#hasAttributes() have attributes},
* no attribute with the specified name exists or the attribute {@linkplain Attribute#hasValue() has no value}.
* .{@link StartTag#getAttributeValue(String) getAttributeValue(attributeName)}.
*
* @param attributeName the name of the attribute to get.
* @return the {@linkplain CharacterReference#decode(CharSequence) decoded} value of the attribute with the specified name, or null if the attribute does not exist or {@linkplain Attribute#hasValue() has no value}.
*/
public String getAttributeValue(final String attributeName) {
return getStartTag().getAttributeValue(attributeName);
}
/**
* Returns the {@link FormControl} defined by this element.
* @return the {@link FormControl} defined by this element, or null if it is not a control.
*/
public FormControl getFormControl() {
return FormControl.construct(this);
}
public String getDebugInfo() {
if (this==NOT_CACHED) return "NOT_CACHED";
final StringBuilder sb=new StringBuilder();
sb.append("Element ");
startTag.appendDebugTag(sb);
if (!isEmpty()) sb.append('-');
if (endTag!=null) sb.append(endTag);
sb.append(' ');
startTag.appendDebugTagType(sb);
sb.append(super.getDebugInfo());
return sb.toString();
}
int getContentEnd() {
return endTag!=null ? endTag.begin : end;
}
}