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