001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: // SAX locator interface for document events.
028: package org.xml.sax;
029:
030: /**
031: * Interface for associating a SAX event with a document location.
032: *
033: * <blockquote>
034: * <em>This module, both source code and documentation, is in the
035: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
036: * </blockquote>
037: *
038: * <p>If a SAX parser provides location information to the SAX
039: * application, it does so by implementing this interface and then
040: * passing an instance to the application using the content
041: * handler's {@link org.xml.sax.helpers.DefaultHandler#setDocumentLocator
042: * setDocumentLocator} method. The application can use the
043: * object to obtain the location of any other content handler event
044: * in the XML source document.</p>
045: *
046: * <p>Note that the results returned by the object will be valid only
047: * during the scope of each content handler method: the application
048: * will receive unpredictable results if it attempts to use the
049: * locator at any other time.</p>
050: *
051: * <p>SAX parsers are not required to supply a locator, but they are
052: * very strongly encouraged to do so. If the parser supplies a
053: * locator, it must do so before reporting any other document events.
054: * If no locator has been set by the time the application receives
055: * the startDocument event, the application should assume that a locator
056: * is not available.</p>
057: *
058: * @since SAX 1.0
059: *
060: * @version 2.0
061: */
062: public interface Locator {
063:
064: /**
065: * Return the public identifier for the current document event.
066: *
067: * <p>The return value is the public identifier of the document
068: * entity or of the external parsed entity in which the markup
069: * triggering the event appears.</p>
070: *
071: * @return A string containing the public identifier, or
072: * null if none is available.
073: * @see #getSystemId
074: */
075: public abstract String getPublicId();
076:
077: /**
078: * Return the system identifier for the current document event.
079: *
080: * <p>The return value is the system identifier of the document
081: * entity or of the external parsed entity in which the markup
082: * triggering the event appears.</p>
083: *
084: * <p>If the system identifier is a URL, the parser must resolve it
085: * fully before passing it to the application.</p>
086: *
087: * @return A string containing the system identifier, or null
088: * if none is available.
089: * @see #getPublicId
090: */
091: public abstract String getSystemId();
092:
093: /**
094: * Return the line number where the current document event ends.
095: *
096: * <p><strong>Warning:</strong> The return value from the method
097: * is intended only as an approximation for the sake of error
098: * reporting; it is not intended to provide sufficient information
099: * to edit the character content of the original XML document.</p>
100: *
101: * <p>The return value is an approximation of the line number
102: * in the document entity or external parsed entity where the
103: * markup triggering the event appears.</p>
104: *
105: * <p>If possible, the SAX driver should provide the line position
106: * of the first character after the text associated with the document
107: * event. The first line in the document is line 1.</p>
108: *
109: * @return The line number, or -1 if none is available.
110: * @see #getColumnNumber
111: */
112: public abstract int getLineNumber();
113:
114: /**
115: * Return the column number where the current document event ends.
116: *
117: * <p><strong>Warning:</strong> The return value from the method
118: * is intended only as an approximation for the sake of error
119: * reporting; it is not intended to provide sufficient information
120: * to edit the character content of the original XML document.</p>
121: *
122: * <p>The return value is an approximation of the column number
123: * in the document entity or external parsed entity where the
124: * markup triggering the event appears.</p>
125: *
126: * <p>If possible, the SAX driver should provide the line position
127: * of the first character after the text associated with the document
128: * event. The first column in each line is column 1.</p>
129: *
130: * @return The column number, or -1 if none is available.
131: * @see #getLineNumber
132: */
133: public abstract int getColumnNumber();
134:
135: }
136:
137: // end of Locator.java
|