Package org.attoparser.simple

Interface ISimpleMarkupHandler

All Known Implementing Classes:

AbstractSimpleMarkupHandler

public interface ISimpleMarkupHandler

Interface to be implemented by all simple Markup Handlers. The events declared in this interface are a simplified version of the ones in IMarkupHandler.

Markup handlers are the objects that receive the events produced during parsing and perform the operations the users need.

Markup handlers can be stateful, which means that a new instance of the markup handler class should be created for each parsing operation. In such case, it is not required that these implementations are thread-safe.

There is an abstract, basic, no-op implementation of this interface called AbstractSimpleMarkupHandler which can be used for easily creating new handlers by overriding only the relevant event handling methods.

Since:

2.0.0

Author:

Daniel Fernández

Method Summary

Modifier and Type	Method	Description
void	handleAutoCloseElement(String elementName, int line, int col)	Called when a close element (a close tag) is needed in order to correctly balance the markup.
void	handleAutoOpenElement(String elementName, java.util.Map<String,String> attributes, int line, int col)	Called when an element (an open tag) is automatically added in order to shape markup according to the spec (made for HTML parsing).
void	handleCDATASection(char[] buffer, int offset, int len, int line, int col)	Called when a CDATA section is found.
void	handleCloseElement(String elementName, int line, int col)	Called when a close element (a close tag) is found.
void	handleComment(char[] buffer, int offset, int len, int line, int col)	Called when a comment is found.
void	handleDocType(String elementName, String publicId, String systemId, String internalSubset, int line, int col)	Called when a DOCTYPE clause is found.
void	handleDocumentEnd(long endTimeNanos, long totalTimeNanos, int line, int col)	Called at the end of document parsing.
void	handleDocumentStart(long startTimeNanos, int line, int col)	Called at the beginning of document parsing.
void	handleOpenElement(String elementName, java.util.Map<String,String> attributes, int line, int col)	Called when an open element (an open tag) is found.
void	handleProcessingInstruction(String target, String content, int line, int col)	Called when a Processing Instruction is found.
void	handleStandaloneElement(String elementName, java.util.Map<String,String> attributes, boolean minimized, int line, int col)	Called when a standalone element (an element with no closing tag) is found.
void	handleText(char[] buffer, int offset, int len, int line, int col)	Called when a text artifact is found.
void	handleUnmatchedCloseElement(String elementName, int line, int col)	Called when a close element (a close tag) appears without a corresponding open element.
void	handleXmlDeclaration(String version, String encoding, String standalone, int line, int col)	Called when an XML Declaration is found.

Method Detail

handleDocumentStart

void handleDocumentStart(long startTimeNanos,
                         int line,
                         int col)
                  throws ParseException

Called at the beginning of document parsing.

Parameters:

startTimeNanos - the current time (in nanoseconds) obtained when parsing starts.

line - the line of the document where parsing starts (usually number 1).

col - the column of the document where parsing starts (usually number 1).

Throws:

ParseException - if any exceptions occur during handling.

handleDocumentEnd

void handleDocumentEnd(long endTimeNanos,
                       long totalTimeNanos,
                       int line,
                       int col)
                throws ParseException

Called at the end of document parsing.

Parameters:

endTimeNanos - the current time (in nanoseconds) obtained when parsing ends.

totalTimeNanos - the difference between current times at the start and end of parsing (in nanoseconds)

line - the line of the document where parsing ends (usually the last one)

col - the column of the document where the parsing ends (usually the last one)

Throws:

ParseException - if any exceptions occur during handling.

handleXmlDeclaration

void handleXmlDeclaration(String version,
                          String encoding,
                          String standalone,
                          int line,
                          int col)
                   throws ParseException

Called when an XML Declaration is found.

Parameters:

version - the version value specified (cannot be null).

encoding - the encoding value specified (can be null).

standalone - the standalone value specified (can be null).

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleDocType

void handleDocType(String elementName,
                   String publicId,
                   String systemId,
                   String internalSubset,
                   int line,
                   int col)
            throws ParseException

Called when a DOCTYPE clause is found.

Parameters:

elementName - the root element name present in the DOCTYPE clause (e.g. "html").

publicId - the public ID specified, if present (might be null).

systemId - the system ID specified, if present (might be null).

internalSubset - the internal subset specified, if present (might be null).

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleCDATASection

void handleCDATASection(char[] buffer,
                        int offset,
                        int len,
                        int line,
                        int col)
                 throws ParseException

Called when a CDATA section is found.

This artifact is returned as a char[] instead of a String because its contents can be large (so creating a String is avoided if it is not considered relevant). In order to convert it to a String, just do new String(buffer, offset, len).

Please note the returned char[] buffer should never be modified.

Parameters:

buffer - the document buffer.

offset - the offset of the artifact in the document buffer.

len - the length (in chars) of the artifact.

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleComment

void handleComment(char[] buffer,
                   int offset,
                   int len,
                   int line,
                   int col)
            throws ParseException

Called when a comment is found.

This artifact is returned as a char[] instead of a String because its contents can be large (so creating a String is avoided if it is not considered relevant). In order to convert it to a String, just do new String(buffer, offset, len).

Please note the returned char[] buffer should never be modified.

Parameters:

buffer - the document buffer.

offset - the offset of the artifact in the document buffer.

len - the length (in chars) of the artifact.

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleText

void handleText(char[] buffer,
                int offset,
                int len,
                int line,
                int col)
         throws ParseException

Called when a text artifact is found.

A sequence of chars is considered to be text when no structures of any kind are contained inside it. This means no tags (a.k.a. elements), DOCTYPE's, processing instructions, etc. are contained in the sequence.

Text sequences might include any number of new line and/or control characters.

This artifact is returned as a char[] instead of a String because its contents can be large (so creating a String is avoided if it is not considered relevant). In order to convert it to a String, just do new String(buffer, offset, len).

Please note the returned char[] buffer should never be modified.

Parameters:

buffer - the document buffer (not copied)

offset - the offset (position in buffer) where the text artifact starts.

len - the length (in chars) of the text artifact, starting in offset.

line - the line in the original document where this text artifact starts.

col - the column in the original document where this text artifact starts.

Throws:

ParseException - if any exceptions occur during handling.

handleStandaloneElement

void handleStandaloneElement(String elementName,
                             java.util.Map<String,String> attributes,
                             boolean minimized,
                             int line,
                             int col)
                      throws ParseException

Called when a standalone element (an element with no closing tag) is found.

Note that the element attributes map can be null if no attributes are present.

Parameters:

elementName - the element name (e.g. "<img src="logo.png">" -> "img").

attributes - the element attributes map, or null if no attributes are present.

minimized - whether the element has been found minimized (<element/>)in code or not.

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleOpenElement

void handleOpenElement(String elementName,
                       java.util.Map<String,String> attributes,
                       int line,
                       int col)
                throws ParseException

Called when an open element (an open tag) is found.

Note that the element attributes map can be null if no attributes are present.

Parameters:

elementName - the element name (e.g. "<div class="content">" -> "div").

attributes - the element attributes map, or null if no attributes are present.

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleAutoOpenElement

void handleAutoOpenElement(String elementName,
                           java.util.Map<String,String> attributes,
                           int line,
                           int col)
                    throws ParseException

Called when an element (an open tag) is automatically added in order to shape markup according to the spec (made for HTML parsing). See ParseConfiguration.ElementBalancing.AUTO_OPEN_CLOSE for more info.

Note that the element attributes map can be null if no attributes are present.

Parameters:

elementName - the element name (e.g. "<div class="content">" -> "div").

attributes - the element attributes map, or null if no attributes are present.

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleCloseElement

void handleCloseElement(String elementName,
                        int line,
                        int col)
                 throws ParseException

Called when a close element (a close tag) is found.

Parameters:

elementName - the element name (e.g. "</div>" -> "div").

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleAutoCloseElement

void handleAutoCloseElement(String elementName,
                            int line,
                            int col)
                     throws ParseException

Called when a close element (a close tag) is needed in order to correctly balance the markup. This is called auto-closing.

Implementors might choose to ignore these autoclosing events.

Parameters:

elementName - the element name (e.g. "</div>" -> "div").

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleUnmatchedCloseElement

void handleUnmatchedCloseElement(String elementName,
                                 int line,
                                 int col)
                          throws ParseException

Called when a close element (a close tag) appears without a corresponding open element.

Implementors might choose to ignore these events.

Parameters:

elementName - the element name (e.g. "</div>" -> "div").

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.

handleProcessingInstruction

void handleProcessingInstruction(String target,
                                 String content,
                                 int line,
                                 int col)
                          throws ParseException

Called when a Processing Instruction is found.

Parameters:

target - the target specified in the processing instruction.

content - the content of the processing instruction, if specified (might be null).

line - the line in the document where this elements appears.

col - the column in the document where this element appears.

Throws:

ParseException - if any exceptions occur during handling.