001// Locator2.java - extended Locator 002// http://www.saxproject.org 003// Public Domain: no warranty. 004// $Id: Locator2.java,v 1.1 2004/12/23 22:38:42 mark Exp $ 005 006package org.xml.sax.ext; 007 008import org.xml.sax.Locator; 009 010 011/** 012 * SAX2 extension to augment the entity information provided 013 * though a {@link Locator}. 014 * If an implementation supports this extension, the Locator 015 * provided in {@link org.xml.sax.ContentHandler#setDocumentLocator 016 * ContentHandler.setDocumentLocator() } will implement this 017 * interface, and the 018 * <em>http://xml.org/sax/features/use-locator2</em> feature 019 * flag will have the value <em>true</em>. 020 * 021 * <blockquote> 022 * <em>This module, both source code and documentation, is in the 023 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 024 * </blockquote> 025 * 026 * <p> XMLReader implementations are not required to support this 027 * information, and it is not part of core-only SAX2 distributions.</p> 028 * 029 * @since SAX 2.0 (extensions 1.1 alpha) 030 * @author David Brownell 031 * @version TBS 032 */ 033public interface Locator2 extends Locator 034{ 035 /** 036 * Returns the version of XML used for the entity. This will 037 * normally be the identifier from the current entity's 038 * <em><?xml version='...' ...?></em> declaration, 039 * or be defaulted by the parser. 040 * 041 * @return Identifier for the XML version being used to interpret 042 * the entity's text, or null if that information is not yet 043 * available in the current parsing state. 044 */ 045 public String getXMLVersion (); 046 047 /** 048 * Returns the name of the character encoding for the entity. 049 * If the encoding was declared externally (for example, in a MIME 050 * Content-Type header), that will be the name returned. Else if there 051 * was an <em><?xml ...encoding='...'?></em> declaration at 052 * the start of the document, that encoding name will be returned. 053 * Otherwise the encoding will been inferred (normally to be UTF-8, or 054 * some UTF-16 variant), and that inferred name will be returned. 055 * 056 * <p>When an {@link org.xml.sax.InputSource InputSource} is used 057 * to provide an entity's character stream, this method returns the 058 * encoding provided in that input stream. 059 * 060 * <p> Note that some recent W3C specifications require that text 061 * in some encodings be normalized, using Unicode Normalization 062 * Form C, before processing. Such normalization must be performed 063 * by applications, and would normally be triggered based on the 064 * value returned by this method. 065 * 066 * <p> Encoding names may be those used by the underlying JVM, 067 * and comparisons should be case-insensitive. 068 * 069 * @return Name of the character encoding being used to interpret 070 * * the entity's text, or null if this was not provided for a * 071 * character stream passed through an InputSource or is otherwise 072 * not yet available in the current parsing state. 073 */ 074 public String getEncoding (); 075}