Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## au.id.jericho.lib.html
Class Element

    java.lang.Object
      Segment
          Element

All Implemented Interfaces:
  java.lang.CharSequence, java.lang.Comparable, HTMLElementName

public final class Element
extends Segment
implements HTMLElementName

Represents an element in a specific source document, which encompasses a start tag, an optional end tag and all content in between.

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 `StartTag` "`<p>`", the `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 start tag with a type of `StartTagType.NORMAL`. This comprises all HTML elements and non-HTML elements.

`Element` instances are obtained using one of the following methods:

- `StartTag.getElement()`
- `EndTag.getElement()`
- `Segment.findAllElements()`
- `Segment.findAllElements(String name)`
- `Segment.findAllElements(StartTagType)`

See also the `HTMLElements` class, and the XML 1.0 specification for elements.

### Element Structure

The three possible structures of an element are listed below:

Single Tag Element:
  Example:
  `<img src="mypicture.jpg">`

  The element consists only of a single start tag and has no element content (although the start tag itself may have tag content).
  `getEndTag()``==null`
  `isEmpty()``==true`
  `getEnd()``==``getStartTag()``.``getEnd()`

  This occurs in the following situations:

  - An HTML element for which the end tag is forbidden.
  - An HTML element for which the end tag is required, but the end tag is not present in the source document.
  - An HTML element for which the end tag is optional, where the implicitly terminating tag is situated immediately after the element's start tag.
  - An empty element tag
  - A non-HTML element that is not an empty element tag but is missing its end tag.
  - An element with a start tag of a type that does not define a corresponding end tag type.
  - An element with a start tag of a type that does define a corresponding end tag type but is missing its end tag.
Explicitly Terminated Element:
  Example:
  `<p>This is a sample paragraph.</p>`

  The element consists of a start tag, content, and an end tag.
  `getEndTag()``!=null`.
  `isEmpty()``==false` (provided the end tag doesn't immediately follow the start tag)
  `getEnd()``==``getEndTag()``.``getEnd()`.

  This occurs in the following situations, assuming the start tag's matching end tag is present in the source document:

  - An HTML element for which the end tag is either required or optional.
  - A non-HTML element that is not an empty element tag.
  - An element with a start tag of a type that defines a corresponding end tag type.
Implicitly Terminated Element:
  Example:
  `<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 start tag and content, but no end tag.
  `getEndTag()``==null`.
  `isEmpty()``==false`
  `getEnd()``!=``getStartTag()``.``getEnd()`.

  This only occurs in an HTML element for which the 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 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 `HTMLElements.getEndTagOptionalElementNames()` method.

### Element Parsing Rules

The following rules describe the algorithm used in the `StartTag.getElement()` method to construct an element. The detection of the start tag's matching end tag or other terminating tags always takes into account the possible nesting of elements.

- If the start tag has a type of `StartTagType.NORMAL`:
  - If the name of the start tag matches one of the recognised HTML element names (indicating an HTML element):
    - If the end tag for an element of this name is forbidden, the parser does not conduct any search for an end tag and a single tag element is created.
    - If the end tag for an element of this name is required, the parser searches for the start tag's matching end tag.
      - If the matching end tag is found, an explicitly terminated element is created.
      - If no matching end tag is found, the source document is not valid HTML and the incident is logged as a missing required end tag. In this situation a single tag element is created.
    - If the end tag for an element of this name is optional, the parser searches not only for the start tag's matching end tag, but also for any other tag that implicitly terminates the element.
      For each tag (T2) following the start tag (ST1) of this element (E1):
      - If T2 is a start tag:
        - If the name of T2 is in the list of non-terminating element names for E1, then continue evaluating tags from the end of T2's corresponding element.
        - If the name of T2 is in the list of terminating start tag names for E1, then E1 ends at the beginning of T2. If T2 follows immediately after ST1, a single tag element is created, otherwise an implicitly terminated element is created.
      - If T2 is an end tag:
        - If the name of T2 is the same as that of ST1, an explicitly terminated element is created.
        - If the name of T2 is in the list of terminating end tag names for E1, then E1 ends at the beginning of T2. If T2 follows immediately after ST1, a single tag element is created, otherwise an implicitly terminated element is created.
      - If no more tags are present in the source document, then E1 ends at the end of the file, and an implicitly terminated element is created.
    Note that the syntactical indication of an empty-element tag in the start tag is ignored when determining the end of HTML elements. See the documentation of the `isEmptyElementTag()` method for more information.
  - If the name of the start tag does not match one of the recognised HTML element names (indicating a non-HTML element):
    - If the start tag is an empty-element tag, the parser does not conduct any search for an end tag and a single tag element is created.
    - Otherwise, section 3.1 of the XML 1.0 specification states that a matching end tag MUST be present, and the parser searches for the start tag's matching end tag.
      - If the matching end tag is found, an explicitly terminated element is created.
      - If no matching end tag is found, the source document is not valid XML and the incident is logged as a missing required end tag. In this situation a single tag element is created.
- If the start tag has any type other than `StartTagType.NORMAL`:
  - If the start tag's type does not define a corresponding end tag type, the parser does not conduct any search for an end tag and a single tag element is created.
  - If the start tag's type does define a corresponding end tag type, the parser assumes that a matching end tag is required and searches for it.
    - If the matching end tag is found, an explicitly terminated element is created.
    - If no matching end tag is found, the missing required end tag is logged and a single tag element is created.

See Also:
  `HTMLElements`

Field Summary

Fields inherited from interface HTMLElementName
`A, ABBR, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BDO, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DEL, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, ISINDEX, KBD, LABEL, LEGEND, LI, LINK, MAP, MENU, META, NOFRAMES, NOSCRIPT, OBJECT, OL, OPTGROUP, OPTION, P, PARAM, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR`

Method Summary
`Attributes` | `getAttributes()` Returns the attributes specified in this element's start tag.
`java.lang.String` | `getAttributeValue(java.lang.String attributeName)` Returns the decoded value of the attribute with the specified name (case insensitive).
`java.util.List` | `getChildElements()` Returns a list of the immediate children of this element in the document element hierarchy.
`Segment` | `getContent()` Returns the segment representing the content of the element.
`java.lang.String` | `getDebugInfo()` Returns a string representation of this object useful for debugging purposes.
`int` | `getDepth()` Returns the nesting depth of this element in the document element hierarchy.
`EndTag` | `getEndTag()` Returns the end tag of the element.
`FormControl` | `getFormControl()` Returns the `FormControl` defined by this element.
`java.lang.String` | `getName()` Returns the name of the start tag of this element, always in lower case.
`Element` | `getParentElement()` Returns the parent of this element in the document element hierarchy.
`StartTag` | `getStartTag()` Returns the start tag of the element.
`boolean` | `isEmpty()` Indicates whether this element has zero-length content.
`boolean` | `isEmptyElementTag()` Indicates whether this element is an empty-element tag.

Methods inherited from class Segment
`charAt, compareTo, encloses, encloses, equals, extractText, extractText, findAllCharacterReferences, findAllElements, findAllElements, findAllElements, findAllElements, findAllStartTags, findAllStartTags, findAllStartTags, findAllTags, findAllTags, findFormControls, findFormFields, getBegin, getEnd, getRenderer, getTextExtractor, hashCode, ignoreWhenParsing, isWhiteSpace, isWhiteSpace, length, parseAttributes, subSequence, toString`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Method Detail

### getParentElement

    public Element getParentElement()

  Returns the parent of this element in the document element hierarchy.

  The `Source.fullSequentialParse()` method should be called after construction of the `Source` object if this method is to be used.

  This method returns `null` for a top-level element, as well as any element formed from a server tag, regardless of whether it is nested inside a normal element.

  See the `Source.getChildElements()` method for more details.

  Returns:
    the parent of this element in the document element hierarchy, or `null` if this element is a top-level element.
  See Also:
    `getChildElements()`

### getChildElements

    public final java.util.List getChildElements()

  Returns a list of the immediate children of this element in the document element hierarchy.

  The objects in the list are all of type `Element`.

  See the `Source.getChildElements()` method for more details.

  Overrides:
    `getChildElements` in class `Segment`
  Returns:
    a list of the immediate children of this element in the document element hierarchy, guaranteed not `null`.
  See Also:
    `getParentElement()`

### getDepth

    public int getDepth()

  Returns the nesting depth of this element in the document element hierarchy.

  The `Source.fullSequentialParse()` method should be called after construction of the `Source` object if this method is to be used.

  A top-level element has a nesting depth of `0`.

  An element formed from a server tag always have a nesting depth of `0`, regardless of whether it is nested inside a normal element.

  See the `Source.getChildElements()` method for more details.

  Returns:
    the nesting depth of this element in the document element hierarchy.
  See Also:
    `getParentElement()`

### getContent

    public Segment getContent()

  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.

  Note that before version 2.0 this method returned `null` if the element was empty, whereas now a zero-length segment is returned.

  Returns:
    the segment representing the content of the element, guaranteed not `null`.

### getStartTag

    public StartTag getStartTag()

  Returns the start tag of the element.

  Returns:
    the start tag of the element.

### getEndTag

    public EndTag getEndTag()

  Returns the end tag of the element.

  If the element has no end tag this method returns `null`.

  Returns:
    the end tag of the element, or `null` if the element has no end tag.

### getName

    public java.lang.String getName()

  Returns the name of the start tag of this element, always in lower case.

  This is equivalent to `getStartTag()``.``getName()`.

  See the `Tag.getName()` method for more information.

  Returns:
    the name of the start tag of this element, always in lower case.

### isEmpty

    public boolean isEmpty()

  Indicates whether this element has zero-length content.

  This is equivalent to `getContent()``.``length()``==0`.

  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 forbidden, and the XML definition of an empty element, which is "either a start-tag immediately followed by an end-tag, or an empty-element tag". The other possibility covered by this property is the case of an HTML element with an optional end tag that is immediately followed by another tag that implicitly terminates the element.

  Returns:
    `true` if this element has zero-length content, otherwise `false`.
  See Also:
    `isEmptyElementTag()`

### isEmptyElementTag

    public boolean isEmptyElementTag()

  Indicates whether this element is an empty-element tag.

  It is signified by an empty element with the characters "`/>`" at the end of the start tag.

  This is equivalent to `isEmpty()``&&` `getStartTag()``.``isEmptyElementTag()`.

  The `StartTag.isEmptyElementTag()` property only checks whether the start tag syntactically an empty-element tag, whereas this property also makes sure the element is in fact empty.

  A syntactical empty-element tag that is not actually empty can occur if the end tag of an HTML element is either required or optional, but the start tag is erroneously terminated with the characters "`/>`" in the source document. All major browsers ignore the syntactical hint of an empty element in this case, even in an XHTML document, so this parser does the same.

  Returns:
    `true` if this element is an empty-element tag, otherwise `false`.

### getAttributes

    public Attributes getAttributes()

  Returns the attributes specified in this element's start tag.

  This is equivalent to `getStartTag()``.``getAttributes()`.

  Returns:
    the attributes specified in this element's start tag.
  See Also:
    `StartTag.getAttributes()`

### getAttributeValue

    public java.lang.String getAttributeValue(java.lang.String attributeName)

  Returns the decoded value of the attribute with the specified name (case insensitive).

  Returns `null` if the start tag of this element does not have attributes, no attribute with the specified name exists or the attribute has no value.

  This is equivalent to `getStartTag()``.``getAttributeValue(attributeName)`.

  Parameters:
    `attributeName` - the name of the attribute to get.
  Returns:
    the decoded value of the attribute with the specified name, or `null` if the attribute does not exist or has no value.

### getFormControl

    public FormControl getFormControl()

  Returns the `FormControl` defined by this element.

  Returns:
    the `FormControl` defined by this element, or `null` if it is not a control.

### getDebugInfo

    public java.lang.String getDebugInfo()

  Description copied from class: `Segment`
  Returns a string representation of this object useful for debugging purposes.

  Overrides:
    `getDebugInfo` in class `Segment`
  Returns:
    a string representation of this object useful for debugging purposes.

Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD