001// SAX locator interface for document events.
002// No warranty; no copyright -- use this as you will.
003// $Id: Locator.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $
004
005package org.xml.sax;
006
007
008/**
009 * Interface for associating a SAX event with a document location.
010 *
011 * <blockquote>
012 * <em>This module, both source code and documentation, is in the
013 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
014 * </blockquote>
015 *
016 * <p>If a SAX parser provides location information to the SAX
017 * application, it does so by implementing this interface and then
018 * passing an instance to the application using the content
019 * handler's {@link org.xml.sax.ContentHandler#setDocumentLocator
020 * setDocumentLocator} method.  The application can use the
021 * object to obtain the location of any other content handler event
022 * in the XML source document.</p>
023 *
024 * <p>Note that the results returned by the object will be valid only
025 * during the scope of each content handler method: the application
026 * will receive unpredictable results if it attempts to use the
027 * locator at any other time.</p>
028 *
029 * <p>SAX parsers are not required to supply a locator, but they are
030 * very strongly encouraged to do so.  If the parser supplies a
031 * locator, it must do so before reporting any other document events.
032 * If no locator has been set by the time the application receives
033 * the {@link org.xml.sax.ContentHandler#startDocument startDocument}
034 * event, the application should assume that a locator is not 
035 * available.</p>
036 *
037 * @since SAX 1.0
038 * @author David Megginson, 
039 *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>
040 * @version 2.0
041 * @see org.xml.sax.ContentHandler#setDocumentLocator 
042 */
043public interface Locator {
044    
045    
046    /**
047     * Return the public identifier for the current document event.
048     *
049     * <p>The return value is the public identifier of the document
050     * entity or of the external parsed entity in which the markup
051     * triggering the event appears.</p>
052     *
053     * @return A string containing the public identifier, or
054     *         null if none is available.
055     * @see #getSystemId
056     */
057    public abstract String getPublicId ();
058    
059    
060    /**
061     * Return the system identifier for the current document event.
062     *
063     * <p>The return value is the system identifier of the document
064     * entity or of the external parsed entity in which the markup
065     * triggering the event appears.</p>
066     *
067     * <p>If the system identifier is a URL, the parser must resolve it
068     * fully before passing it to the application.</p>
069     *
070     * @return A string containing the system identifier, or null
071     *         if none is available.
072     * @see #getPublicId
073     */
074    public abstract String getSystemId ();
075    
076    
077    /**
078     * Return the line number where the current document event ends.
079     *
080     * <p><strong>Warning:</strong> The return value from the method
081     * is intended only as an approximation for the sake of error
082     * reporting; it is not intended to provide sufficient information
083     * to edit the character content of the original XML document.</p>
084     *
085     * <p>The return value is an approximation of the line number
086     * in the document entity or external parsed entity where the
087     * markup triggering the event appears.</p>
088     *
089     * <p>If possible, the SAX driver should provide the line position 
090     * of the first character after the text associated with the document 
091     * event.  The first line in the document is line 1.</p>
092     *
093     * @return The line number, or -1 if none is available.
094     * @see #getColumnNumber
095     */
096    public abstract int getLineNumber ();
097    
098    
099    /**
100     * Return the column number where the current document event ends.
101     *
102     * <p><strong>Warning:</strong> The return value from the method
103     * is intended only as an approximation for the sake of error
104     * reporting; it is not intended to provide sufficient information
105     * to edit the character content of the original XML document.</p>
106     *
107     * <p>The return value is an approximation of the column number
108     * in the document entity or external parsed entity where the
109     * markup triggering the event appears.</p>
110     *
111     * <p>If possible, the SAX driver should provide the line position 
112     * of the first character after the text associated with the document 
113     * event.</p>
114     *
115     * <p>If possible, the SAX driver should provide the line position 
116     * of the first character after the text associated with the document 
117     * event.  The first column in each line is column 1.</p>
118     *
119     * @return The column number, or -1 if none is available.
120     * @see #getLineNumber
121     */
122    public abstract int getColumnNumber ();
123    
124}
125
126// end of Locator.java