- * This module, both source code and documentation, is in the - * Public Domain, and comes with NO WARRANTY. - *- * - *
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.ContentHandler#setDocumentLocator - * setDocumentLocator} method. The application can use the - * object to obtain the location of any other content handler event - * in the XML source document.
- * - *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.
- * - *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 {@link org.xml.sax.ContentHandler#startDocument startDocument} - * event, the application should assume that a locator is not - * available.
- * - * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @version 2.0 - * @see org.xml.sax.ContentHandler#setDocumentLocator - */ -public interface Locator { - - - /** - * Return the public identifier for the current document event. - * - *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.
- * - * @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. - * - *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.
- * - *If the system identifier is a URL, the parser must resolve it - * fully before passing it to the application.
- * - * @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. - * - *Warning: 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.
- * - *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.
- * - *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.
- * - * @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. - * - *Warning: 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.
- * - *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.
- * - *If possible, the SAX driver should provide the line position - * of the first character after the text associated with the document - * event.
- * - *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.
- * - * @return The column number, or -1 if none is available. - * @see #getLineNumber - */ - public abstract int getColumnNumber (); - -} - -// end of Locator.java