org.attoparser.IMarkupParser Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of attoparser Show documentation
Powerful, fast and easy to use HTML and XML parser for Java
There is a newer version: 2.0.7.RELEASE
/*
 * =============================================================================
 * 
 *   Copyright (c) 2012-2014, The ATTOPARSER team (http://www.attoparser.org)
 * 
 *   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 org.attoparser;

import java.io.Reader;


/**
 * 
 *   Interface to be implemented by all Markup Parsers.
 *   Default implementation is {@link org.attoparser.MarkupParser}.
 * 
 * 
 *   AttoParser markup parsers work as SAX-style parsers that need
 *   a markup handler object for handling parsing events. These handlers implement
 *   the {@link org.attoparser.IMarkupHandler} interface, and are normally developed by
 *   users in order to perform the operations they require for their applications.
 * 
 * 
 *   See the documentation of the {@link org.attoparser.IMarkupHandler} interface for more
 *   information on the event handler methods, and also on the handler implementations
 *   AttoParser provides out-of-the-box.
 * 
 * 
 *   Also, note there are two different specialized parsers that use
 *   {@link org.attoparser.MarkupParser} underneath, but which are oriented towards allowing
 *   an easy use of specific parsing features: {@link org.attoparser.dom.IDOMMarkupParser} for
 *   DOM-oriented parsing and {@link org.attoparser.simple.ISimpleMarkupParser} for using
 *   a simplified version of the handler interface ({@link org.attoparser.simple.ISimpleMarkupHandler}).
 * 
 * 
 *   Sample usage:
 * 
 * 
 *   // Obtain a java.io.Reader on the document to be parsed
 *   final Reader documentReader = ...;
 *
 *   // Create the handler instance. Extending the no-op AbstractMarkupHandler is a good start
 *   final IMarkupHandler handler = new AbstractMarkupHandler() {
 *       ... // some events implemented
 *   };
 *
 *   // Create or obtain the parser instance (can be reused). Example uses the default configuration for HTML
 *   final IMarkupParser parser = new MarkupParser(ParseConfiguration.htmlConfiguration());
 *
 *   // Parse it!
 *   parser.parse(documentReader, handler);
 * 
 * 
 *   Note that implementations of this interface should be thread-safe, and therefore parsers
 *   should be reusable through several parsing operations and any number of concurrent threads.
 * 
 *
 * @author Daniel Fernández
 * 
 * @since 2.0.0
 *
 */
public interface IMarkupParser {
    

    /**
     * 
     *   Parse a document using the specified {@link IMarkupHandler}.
     * 
     *
     * @param document the document to be parsed, as a String.
     * @param handler the handler to be used, an {@link IMarkupHandler} implementation.
     * @throws ParseException if the document cannot be parsed.
     */
    public void parse(final String document, final IMarkupHandler handler)
            throws ParseException;

    
    /**
     * 
     *   Parse a document using the specified {@link IMarkupHandler}.
     * 
     * 
     * @param document the document to be parsed, as a char[].
     * @param handler the handler to be used, an {@link IMarkupHandler} implementation.
     * @throws ParseException if the document cannot be parsed.
     */
    public void parse(final char[] document, final IMarkupHandler handler)
            throws ParseException;

    
    /**
     * 
     *   Parse a document using the specified {@link IMarkupHandler}.
     * 
     * 
     * @param document the document to be parsed, as a char[].
     * @param offset the offset to be applied on the char[] document to determine the
     *        start of the document contents.
     * @param len the length (in chars) of the document stored in the char[].
     * @param handler the handler to be used, an {@link IMarkupHandler} implementation.
     * @throws ParseException if the document cannot be parsed.
     */
    public void parse(final char[] document, final int offset, final int len, final IMarkupHandler handler)
            throws ParseException;
    
    
    /**
     * 
     *   Parse a document using the specified {@link IMarkupHandler}.
     * 
     * 
     *   Implementations of this interface must close the provided {@link Reader}
     *   object after parsing.   
     * 
     * 
     * @param reader a Reader on the document.
     * @param handler the handler to be used, an {@link IMarkupHandler} implementation.
     * @throws ParseException if the document cannot be parsed.
     */
    public void parse(final Reader reader, final IMarkupHandler handler)
            throws ParseException;


    
}