| Frames | No Frames |
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.1 2004/12/23 22:38:42 mark 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