Source for org.xml.sax.Locator

   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