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