001: /* Copyright 2000 - 2001 Quadcap Software. All rights reserved.
002: *
003: * This software is distributed under the Quadcap Free Software License.
004: * This software may be used or modified for any purpose, personal or
005: * commercial. Open Source redistributions are permitted. Commercial
006: * redistribution of larger works derived from, or works which bundle
007: * this software requires a "Commercial Redistribution License"; see
008: * http://www.quadcap.com/purchase.
009: *
010: * Redistributions qualify as "Open Source" under one of the following terms:
011: *
012: * Redistributions are made at no charge beyond the reasonable cost of
013: * materials and delivery.
014: *
015: * Redistributions are accompanied by a copy of the Source Code or by an
016: * irrevocable offer to provide a copy of the Source Code for up to three
017: * years at the cost of materials and delivery. Such redistributions
018: * must allow further use, modification, and redistribution of the Source
019: * Code under substantially the same terms as this license.
020: *
021: * Redistributions of source code must retain the copyright notices as they
022: * appear in each source code file, these license terms, and the
023: * disclaimer/limitation of liability set forth as paragraph 6 below.
024: *
025: * Redistributions in binary form must reproduce this Copyright Notice,
026: * these license terms, and the disclaimer/limitation of liability set
027: * forth as paragraph 6 below, in the documentation and/or other materials
028: * provided with the distribution.
029: *
030: * The Software is provided on an "AS IS" basis. No warranty is
031: * provided that the Software is free of defects, or fit for a
032: * particular purpose.
033: *
034: * Limitation of Liability. Quadcap Software shall not be liable
035: * for any damages suffered by the Licensee or any third party resulting
036: * from use of the Software.
037: */
038:
039: // SAX locator interface for document events.
040: // No warranty; no copyright -- use this as you will.
041: // $Id: Locator.java,v 1.3 2001/01/06 06:11:02 stan Exp $
042: package org.xml.sax;
043:
044: /**
045: * Interface for associating a SAX event with a document location.
046: *
047: * <p>If a SAX parser provides location information to the SAX
048: * application, it does so by implementing this interface and then
049: * passing an instance to the application using the document
050: * handler's setDocumentLocator method. The application can use the
051: * object to obtain the location of any other document handler event
052: * in the XML source document.</p>
053: *
054: * <p>Note that the results returned by the object will be valid only
055: * during the scope of each document handler method: the application
056: * will receive unpredictable results if it attempts to use the
057: * locator at any other time.</p>
058: *
059: * <p>SAX parsers are not required to supply a locator, but they are
060: * very strong encouraged to do so. If the parser supplies a
061: * locator, it must do so before reporting any other document events.
062: * If no locator has been set by the time the application receives
063: * the startDocument event, the application should assume that a
064: * locator is not available.</p>
065: *
066: * @author David Megginson (ak117@freenet.carleton.ca)
067: * @version 1.0
068: * @see org.xml.sax.DocumentHandler#setDocumentLocator
069: */
070: public interface Locator {
071:
072: /**
073: * Return the public identifier for the current document event.
074: * <p>This will be the public identifier
075: * @return A string containing the public identifier, or
076: * null if none is available.
077: * @see #getSystemId
078: */
079: public abstract String getPublicId();
080:
081: /**
082: * Return the system identifier for the current document event.
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: * Note that this is the line position of the first character
096: * after the text associated with the document event.
097: * @return The line number, or -1 if none is available.
098: * @see #getColumnNumber
099: */
100: public abstract int getLineNumber();
101:
102: /**
103: * Return the column number where the current document event ends.
104: * Note that this is the column number of the first
105: * character after the text associated with the document
106: * event. The first column in a line is position 1.
107: * @return The column number, or -1 if none is available.
108: * @see #getLineNumber
109: */
110: public abstract int getColumnNumber();
111:
112: }
|