libjava/org/xml/sax/Locator.java

   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.4.2.5 2002/01/29 21:34:14 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