1 // SAX locator interface for document events. 2 // http://www.saxproject.org 3 // No warranty; no copyright -- use this as you will. 4 // $Id: Locator.java,v 1.8 2002/01/30 21:13:47 dbrownell Exp $ 5 6 package org.xml.sax; 7 8 9 /** 10 * Interface for associating a SAX event with a document location. 11 * 12 * <blockquote> 13 * <em>This module, both source code and documentation, is in the 14 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 15 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 16 * for further information. 17 * </blockquote> 18 * 19 * <p>If a SAX parser provides location information to the SAX 20 * application, it does so by implementing this interface and then 21 * passing an instance to the application using the content 22 * handler's {@link org.xml.sax.ContentHandler#setDocumentLocator 23 * setDocumentLocator} method. The application can use the 24 * object to obtain the location of any other SAX event 25 * in the XML source document.</p> 26 * 27 * <p>Note that the results returned by the object will be valid only 28 * during the scope of each callback method: the application 29 * will receive unpredictable results if it attempts to use the 30 * locator at any other time, or after parsing completes.</p> 31 * 32 * <p>SAX parsers are not required to supply a locator, but they are 33 * very strongly encouraged to do so. If the parser supplies a 34 * locator, it must do so before reporting any other document events. 35 * If no locator has been set by the time the application receives 36 * the {@link org.xml.sax.ContentHandler#startDocument startDocument} 37 * event, the application should assume that a locator is not 38 * available.</p> 39 * 40 * @since SAX 1.0 41 * @author David Megginson 42 * @version 2.0.1 (sax2r2) 43 * @see org.xml.sax.ContentHandler#setDocumentLocator 44 */ 45 public interface Locator { 46 47 48 /** 49 * Return the public identifier for the current document event. 50 * 51 * <p>The return value is the public identifier of the document 52 * entity or of the external parsed entity in which the markup 53 * triggering the event appears.</p> 54 * 55 * @return A string containing the public identifier, or 56 * null if none is available. 57 * @see #getSystemId 58 */ 59 public abstract String getPublicId (); 60 61 62 /** 63 * Return the system identifier for the current document event. 64 * 65 * <p>The return value is the system identifier of the document 66 * entity or of the external parsed entity in which the markup 67 * triggering the event appears.</p> 68 * 69 * <p>If the system identifier is a URL, the parser must resolve it 70 * fully before passing it to the application. For example, a file 71 * name must always be provided as a <em>file:...</em> URL, and other 72 * kinds of relative URI are also resolved against their bases.</p> 73 * 74 * @return A string containing the system identifier, or null 75 * if none is available. 76 * @see #getPublicId 77 */ 78 public abstract String getSystemId (); 79 80 81 /** 82 * Return the line number where the current document event ends. 83 * Lines are delimited by line ends, which are defined in 84 * the XML specification. 85 * 86 * <p><strong>Warning:</strong> The return value from the method 87 * is intended only as an approximation for the sake of diagnostics; 88 * it is not intended to provide sufficient information 89 * to edit the character content of the original XML document. 90 * In some cases, these "line" numbers match what would be displayed 91 * as columns, and in others they may not match the source text 92 * due to internal entity expansion. </p> 93 * 94 * <p>The return value is an approximation of the line number 95 * in the document entity or external parsed entity where the 96 * markup triggering the event appears.</p> 97 * 98 * <p>If possible, the SAX driver should provide the line position 99 * of the first character after the text associated with the document 100 * event. The first line is line 1.</p> 101 * 102 * @return The line number, or -1 if none is available. 103 * @see #getColumnNumber 104 */ 105 public abstract int getLineNumber (); 106 107 108 /** 109 * Return the column number where the current document event ends. 110 * This is one-based number of Java <code>char</code> values since 111 * the last line end. 112 * 113 * <p><strong>Warning:</strong> The return value from the method 114 * is intended only as an approximation for the sake of diagnostics; 115 * it is not intended to provide sufficient information 116 * to edit the character content of the original XML document. 117 * For example, when lines contain combining character sequences, wide 118 * characters, surrogate pairs, or bi-directional text, the value may 119 * not correspond to the column in a text editor's display. </p> 120 * 121 * <p>The return value is an approximation of the column number 122 * in the document entity or external parsed entity where the 123 * markup triggering the event appears.</p> 124 * 125 * <p>If possible, the SAX driver should provide the line position 126 * of the first character after the text associated with the document 127 * event. The first column in each line is column 1.</p> 128 * 129 * @return The column number, or -1 if none is available. 130 * @see #getLineNumber 131 */ 132 public abstract int getColumnNumber (); 133 134 } 135 136 // end of Locator.java 137
