/*
*
*
* Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version
* 2 only, as published by the Free Software Foundation.
*
* 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 version 2 for more details (a copy is
* included at /legal/license.txt).
*
* You should have received a copy of the GNU General Public License
* version 2 along with this work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
// SAX locator interface for document events.
package org.xml.sax;
/**
* Interface for associating a SAX event with a document location.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>If a SAX parser provides location information to the SAX
* application, it does so by implementing this interface and then
* passing an instance to the application using the content
* handler's {@link org.xml.sax.helpers.DefaultHandler#setDocumentLocator
* setDocumentLocator} method. The application can use the
* object to obtain the location of any other content handler event
* in the XML source document.</p>
*
* <p>Note that the results returned by the object will be valid only
* during the scope of each content handler method: the application
* will receive unpredictable results if it attempts to use the
* locator at any other time.</p>
*
* <p>SAX parsers are not required to supply a locator, but they are
* very strongly encouraged to do so. If the parser supplies a
* locator, it must do so before reporting any other document events.
* If no locator has been set by the time the application receives
* the startDocument event, the application should assume that a locator
* is not available.</p>
*
* @since SAX 1.0
*
* @version 2.0
*/
public interface Locator {
/**
* Return the public identifier for the current document event.
*
* <p>The return value is the public identifier of the document
* entity or of the external parsed entity in which the markup
* triggering the event appears.</p>
*
* @return A string containing the public identifier, or
* null if none is available.
* @see #getSystemId
*/
public abstract String getPublicId ();
/**
* Return the system identifier for the current document event.
*
* <p>The return value is the system identifier of the document
* entity or of the external parsed entity in which the markup
* triggering the event appears.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before passing it to the application.</p>
*
* @return A string containing the system identifier, or null
* if none is available.
* @see #getPublicId
*/
public abstract String getSystemId ();
/**
* Return the line number where the current document event ends.
*
* <p><strong>Warning:</strong> The return value from the method
* is intended only as an approximation for the sake of error
* reporting; it is not intended to provide sufficient information
* to edit the character content of the original XML document.</p>
*
* <p>The return value is an approximation of the line number
* in the document entity or external parsed entity where the
* markup triggering the event appears.</p>
*
* <p>If possible, the SAX driver should provide the line position
* of the first character after the text associated with the document
* event. The first line in the document is line 1.</p>
*
* @return The line number, or -1 if none is available.
* @see #getColumnNumber
*/
public abstract int getLineNumber ();
/**
* Return the column number where the current document event ends.
*
* <p><strong>Warning:</strong> The return value from the method
* is intended only as an approximation for the sake of error
* reporting; it is not intended to provide sufficient information
* to edit the character content of the original XML document.</p>
*
* <p>The return value is an approximation of the column number
* in the document entity or external parsed entity where the
* markup triggering the event appears.</p>
*
* <p>If possible, the SAX driver should provide the line position
* of the first character after the text associated with the document
* event. The first column in each line is column 1.</p>
*
* @return The column number, or -1 if none is available.
* @see #getLineNumber
*/
public abstract int getColumnNumber ();
}
// end of Locator.java
|