001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 // SAX locator interface for document events.
027 // http://www.saxproject.org
028 // No warranty; no copyright -- use this as you will.
029 // $Id: Locator.java,v 1.2 2004/11/03 22:55:32 jsuttor Exp $
030 package org.xml.sax;
031
032 /**
033 * Interface for associating a SAX event with a document location.
034 *
035 * <blockquote>
036 * <em>This module, both source code and documentation, is in the
037 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
038 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
039 * for further information.
040 * </blockquote>
041 *
042 * <p>If a SAX parser provides location information to the SAX
043 * application, it does so by implementing this interface and then
044 * passing an instance to the application using the content
045 * handler's {@link org.xml.sax.ContentHandler#setDocumentLocator
046 * setDocumentLocator} method. The application can use the
047 * object to obtain the location of any other SAX event
048 * in the XML source document.</p>
049 *
050 * <p>Note that the results returned by the object will be valid only
051 * during the scope of each callback method: the application
052 * will receive unpredictable results if it attempts to use the
053 * locator at any other time, or after parsing completes.</p>
054 *
055 * <p>SAX parsers are not required to supply a locator, but they are
056 * very strongly encouraged to do so. If the parser supplies a
057 * locator, it must do so before reporting any other document events.
058 * If no locator has been set by the time the application receives
059 * the {@link org.xml.sax.ContentHandler#startDocument startDocument}
060 * event, the application should assume that a locator is not
061 * available.</p>
062 *
063 * @since SAX 1.0
064 * @author David Megginson
065 * @version 2.0.1 (sax2r2)
066 * @see org.xml.sax.ContentHandler#setDocumentLocator
067 */
068 public interface Locator {
069
070 /**
071 * Return the public identifier for the current document event.
072 *
073 * <p>The return value is the public identifier of the document
074 * entity or of the external parsed entity in which the markup
075 * triggering the event appears.</p>
076 *
077 * @return A string containing the public identifier, or
078 * null if none is available.
079 * @see #getSystemId
080 */
081 public abstract String getPublicId();
082
083 /**
084 * Return the system identifier for the current document event.
085 *
086 * <p>The return value is the system identifier of the document
087 * entity or of the external parsed entity in which the markup
088 * triggering the event appears.</p>
089 *
090 * <p>If the system identifier is a URL, the parser must resolve it
091 * fully before passing it to the application. For example, a file
092 * name must always be provided as a <em>file:...</em> URL, and other
093 * kinds of relative URI are also resolved against their bases.</p>
094 *
095 * @return A string containing the system identifier, or null
096 * if none is available.
097 * @see #getPublicId
098 */
099 public abstract String getSystemId();
100
101 /**
102 * Return the line number where the current document event ends.
103 * Lines are delimited by line ends, which are defined in
104 * the XML specification.
105 *
106 * <p><strong>Warning:</strong> The return value from the method
107 * is intended only as an approximation for the sake of diagnostics;
108 * it is not intended to provide sufficient information
109 * to edit the character content of the original XML document.
110 * In some cases, these "line" numbers match what would be displayed
111 * as columns, and in others they may not match the source text
112 * due to internal entity expansion. </p>
113 *
114 * <p>The return value is an approximation of the line number
115 * in the document entity or external parsed entity where the
116 * markup triggering the event appears.</p>
117 *
118 * <p>If possible, the SAX driver should provide the line position
119 * of the first character after the text associated with the document
120 * event. The first line is line 1.</p>
121 *
122 * @return The line number, or -1 if none is available.
123 * @see #getColumnNumber
124 */
125 public abstract int getLineNumber();
126
127 /**
128 * Return the column number where the current document event ends.
129 * This is one-based number of Java <code>char</code> values since
130 * the last line end.
131 *
132 * <p><strong>Warning:</strong> The return value from the method
133 * is intended only as an approximation for the sake of diagnostics;
134 * it is not intended to provide sufficient information
135 * to edit the character content of the original XML document.
136 * For example, when lines contain combining character sequences, wide
137 * characters, surrogate pairs, or bi-directional text, the value may
138 * not correspond to the column in a text editor's display. </p>
139 *
140 * <p>The return value is an approximation of the column number
141 * in the document entity or external parsed entity where the
142 * markup triggering the event appears.</p>
143 *
144 * <p>If possible, the SAX driver should provide the line position
145 * of the first character after the text associated with the document
146 * event. The first column in each line is column 1.</p>
147 *
148 * @return The column number, or -1 if none is available.
149 * @see #getLineNumber
150 */
151 public abstract int getColumnNumber();
152
153 }
154
155 // end of Locator.java
|