documenthandler.java

实现了一个基于j2me移动gps定位系统

// SAX document handler.
// No warranty; no copyright -- use this as you will.

/*
 * $Id: DocumentHandler.java 257 2008-07-17 11:56:07Z khanh.lnq $
 * $URL: https://jvnmobilegis.googlecode.com/svn/trunk/src/org/xml/sax/DocumentHandler.java $
 * $Author: khanh.lnq $
 * $Revision: 257 $
 * $Date: 2008-07-17 18:56:07 +0700 (Thu, 17 Jul 2008) $
 *
 * ====================================================================
 *
 * Copyright (C) 2006-2007 by JVNGIS
 *
 * All copyright notices regarding JVNMobileGIS MUST remain
 * intact in the Java codes and resource files.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Support can be obtained from project homepage at:
 * http://code.google.com/p/jvnmobilegis/
 *
 * Correspondence and Marketing Questions can be sent to:
 * khanh.lnq AT gmail.com
 * 
 * @version: 1.0
 * @author: Khanh Le
 * @Date Created: 22 Jun 2007
 */

package org.xml.sax;

/**
 * Receive notification of general document events. <p/> This is the main
 * interface that most SAX applications implement: if the application needs to
 * be informed of basic parsing events, it implements this interface and
 * registers an instance with the SAX parser using the setDocumentHandler
 * method. The parser uses the instance to report basic document-related events
 * like the start and end of elements and character data. </p> <p/> The order of
 * events in this interface is very important, and mirrors the order of
 * information in the document itself. For example, all of an element's content
 * (character data, processing instructions, and/or subelements) will appear, in
 * order, between the startElement event and the corresponding endElement event.
 * </p> <p/> Application writers who do not want to implement the entire
 * interface can derive a class from HandlerBase, which implements the default
 * functionality; parser writers can instantiate HandlerBase to obtain a default
 * handler. The application can find the location of any document event using
 * the Locator interface supplied by the Parser through the setDocumentLocator
 * method. </p>
 * 
 * @author David Megginson ([e-mail])
 * @version 1.0
 * @see org.xml.sax.Parser#setDocumentHandler
 * @see org.xml.sax.Locator
 * @see org.xml.sax.HandlerBase
 */
public interface DocumentHandler {

    /**
     * Receive an object for locating the origin of SAX document events. <p/>
     * SAX parsers are strongly encouraged (though not absolutely required) to
     * supply a locator: if it does so, it must supply the locator to the
     * application by invoking this method before invoking any of the other
     * methods in the DocumentHandler interface. </p> <p/> The locator allows
     * the application to determine the end position of any document-related
     * event, even if the parser is not reporting an error. Typically, the
     * application will use this information for reporting its own errors (such
     * as character content that does not match an application's business
     * rules). The information returned by the locator is probably not
     * sufficient for use with a search engine. </p> <p/> Note that the locator
     * will return correct information only during the invocation of the events
     * in this interface. The application should not attempt to use it at any
     * other time. </p>
     * 
     * @param locator
     *            An object that can return the location of any SAX document
     *            event.
     * @see org.xml.sax.Locator
     */
    public abstract void setDocumentLocator(Locator locator);

    /**
     * Receive notification of the beginning of a document. <p/> The SAX parser
     * will invoke this method only once, before any other methods in this
     * interface or in DTDHandler (except for setDocumentLocator). </p>
     * 
     * @throws org.xml.sax.SAXException
     *             Any SAX exception, possibly wrapping another exception.
     */
    public abstract void startDocument() throws SAXException;

    /**
     * Receive notification of the end of a document. <p/> The SAX parser will
     * invoke this method only once, and it will be the last method invoked
     * during the parse. The parser shall not invoke this method until it has
     * either abandoned parsing (because of an unrecoverable error) or reached
     * the end of input. </p>
     * 
     * @throws org.xml.sax.SAXException
     *             Any SAX exception, possibly wrapping another exception.
     */
    public abstract void endDocument() throws SAXException;

    /**
     * Receive notification of the beginning of an element. <p/> The Parser will
     * invoke this method at the beginning of every element in the XML document;
     * there will be a corresponding endElement() event for every startElement()
     * event (even when the element is empty). All of the element's content will
     * be reported, in order, before the corresponding endElement() event. </p>
     * <p/> If the element name has a namespace prefix, the prefix will still be
     * attached. Note that the attribute list provided will contain only
     * attributes with explicit values (specified or defaulted): #IMPLIED
     * attributes will be omitted. </p>
     * 
     * @param name
     *            The element type name.
     * @param atts
     *            The attributes attached to the element, if any.
     * @throws org.xml.sax.SAXException
     *             Any SAX exception, possibly wrapping another exception.
     * @see #endElement
     * @see org.xml.sax.AttributeList
     */
    public abstract void startElement(String name, AttributeList atts)
            throws SAXException;

    /**
     * Receive notification of the end of an element. <p/> The SAX parser will
     * invoke this method at the end of every element in the XML document; there
     * will be a corresponding startElement() event for every endElement() event
     * (even when the element is empty). </p> <p/> If the element name has a
     * namespace prefix, the prefix will still be attached to the name. </p>
     * 
     * @param name
     *            The element type name
     * @throws org.xml.sax.SAXException
     *             Any SAX exception, possibly wrapping another exception.
     */
    public abstract void endElement(String name) throws SAXException;

    /**
     * Receive notification of character data. <p/> The Parser will call this
     * method to report each chunk of character data. SAX parsers may return all
     * contiguous character data in a single chunk, or they may split it into
     * several chunks; however, all of the characters in any single event must
     * come from the same external entity, so that the Locator provides useful
     * information. </p> <p/> The application must not attempt to read from the
     * array outside of the specified range. </p> <p/> Note that some parsers
     * will report whitespace using the ignorableWhitespace() method rather than
     * this one (validating parsers must do so). </p>
     * 
     * @param ch
     *            The characters from the XML document.
     * @param start
     *            The start position in the array.
     * @param length
     *            The number of characters to read from the array.
     * @throws org.xml.sax.SAXException
     *             Any SAX exception, possibly wrapping another exception.
     * @see #ignorableWhitespace
     * @see org.xml.sax.Locator
     */
    public abstract void characters(char ch[], int start, int length)
            throws SAXException;

    /**
     * Receive notification of ignorable whitespace in element content. <p/>
     * Validating Parsers must use this method to report each chunk of ignorable
     * whitespace (see the W3C XML 1.0 recommendation, section 2.10):
     * non-validating parsers may also use this method if they are capable of
     * parsing and using content models. </p> <p/> SAX parsers may return all
     * contiguous whitespace in a single chunk, or they may split it into
     * several chunks; however, all of the characters in any single event must
     * come from the same external entity, so that the Locator provides useful
     * information. </p> <p/> The application must not attempt to read from the
     * array outside of the specified range. </p>
     * 
     * @param ch
     *            The characters from the XML document.
     * @param start
     *            The start position in the array.
     * @param length
     *            The number of characters to read from the array.
     * @throws org.xml.sax.SAXException
     *             Any SAX exception, possibly wrapping another exception.
     * @see #characters
     */
    public abstract void ignorableWhitespace(char ch[], int start, int length)
            throws SAXException;

    /**
     * Receive notification of a processing instruction. <p/> The Parser will
     * invoke this method once for each processing instruction found: note that
     * processing instructions may occur before or after the main document
     * element. </p> <p/> A SAX parser should never report an XML declaration
     * (XML 1.0, section 2.8) or a text declaration (XML 1.0, section 4.3.1)
     * using this method. </p>
     * 
     * @param target
     *            The processing instruction target.
     * @param data
     *            The processing instruction data, or null if none was supplied.
     * @throws org.xml.sax.SAXException
     *             Any SAX exception, possibly wrapping another exception.
     */
    public abstract void processingInstruction(String target, String data)
            throws SAXException;

}