001: // SAX locator interface for document events.
002: // http://www.saxproject.org
003: // No warranty; no copyright -- use this as you will.
004: // $Id: Locator.java,v 1.6 2002/02/01 20:06:20 db Exp $
005:
006: package org.xml.sax;
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: * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
015: * for further information.
016: * </blockquote>
017: *
018: * <p>If a SAX parser provides location information to the SAX
019: * application, it does so by implementing this interface and then
020: * passing an instance to the application using the content
021: * handler's {@link org.xml.sax.ContentHandler#setDocumentLocator
022: * setDocumentLocator} method. The application can use the
023: * object to obtain the location of any other SAX event
024: * in the XML source document.</p>
025: *
026: * <p>Note that the results returned by the object will be valid only
027: * during the scope of each callback method: the application
028: * will receive unpredictable results if it attempts to use the
029: * locator at any other time, or after parsing completes.</p>
030: *
031: * <p>SAX parsers are not required to supply a locator, but they are
032: * very strongly encouraged to do so. If the parser supplies a
033: * locator, it must do so before reporting any other document events.
034: * If no locator has been set by the time the application receives
035: * the {@link org.xml.sax.ContentHandler#startDocument startDocument}
036: * event, the application should assume that a locator is not
037: * available.</p>
038: *
039: * @since SAX 1.0
040: * @author David Megginson
041: * @version 2.0.1 (sax2r2)
042: * @see org.xml.sax.ContentHandler#setDocumentLocator
043: */
044: public interface Locator {
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: * Return the system identifier for the current document event.
061: *
062: * <p>The return value is the system identifier of the document
063: * entity or of the external parsed entity in which the markup
064: * triggering the event appears.</p>
065: *
066: * <p>If the system identifier is a URL, the parser must resolve it
067: * fully before passing it to the application. For example, a file
068: * name must always be provided as a <em>file:...</em> URL, and other
069: * kinds of relative URI are also resolved against their bases.</p>
070: *
071: * @return A string containing the system identifier, or null
072: * if none is available.
073: * @see #getPublicId
074: */
075: public abstract String getSystemId();
076:
077: /**
078: * Return the line number where the current document event ends.
079: * Lines are delimited by line ends, which are defined in
080: * the XML specification.
081: *
082: * <p><strong>Warning:</strong> The return value from the method
083: * is intended only as an approximation for the sake of diagnostics;
084: * it is not intended to provide sufficient information
085: * to edit the character content of the original XML document.
086: * In some cases, these "line" numbers match what would be displayed
087: * as columns, and in others they may not match the source text
088: * due to internal entity expansion. </p>
089: *
090: * <p>The return value is an approximation of the line number
091: * in the document entity or external parsed entity where the
092: * markup triggering the event appears.</p>
093: *
094: * <p>If possible, the SAX driver should provide the line position
095: * of the first character after the text associated with the document
096: * event. The first line is line 1.</p>
097: *
098: * @return The line number, or -1 if none is available.
099: * @see #getColumnNumber
100: */
101: public abstract int getLineNumber();
102:
103: /**
104: * Return the column number where the current document event ends.
105: * This is one-based number of Java <code>char</code> values since
106: * the last line end.
107: *
108: * <p><strong>Warning:</strong> The return value from the method
109: * is intended only as an approximation for the sake of diagnostics;
110: * it is not intended to provide sufficient information
111: * to edit the character content of the original XML document.
112: * For example, when lines contain combining character sequences, wide
113: * characters, surrogate pairs, or bi-directional text, the value may
114: * not correspond to the column in a text editor's display. </p>
115: *
116: * <p>The return value is an approximation of the column number
117: * in the document entity or external parsed entity where the
118: * markup triggering the event appears.</p>
119: *
120: * <p>If possible, the SAX driver should provide the line position
121: * of the first character after the text associated with the document
122: * event. The first column in each line is column 1.</p>
123: *
124: * @return The column number, or -1 if none is available.
125: * @see #getLineNumber
126: */
127: public abstract int getColumnNumber();
128:
129: }
130:
131: // end of Locator.java
|