| The Android Open Source Project | 0eec464 | 2012-04-01 00:00:00 -0700 | [diff] [blame] | 1 | // Locator2.java - extended Locator |
| 2 | // http://www.saxproject.org |
| 3 | // Public Domain: no warranty. |
| 4 | // $Id: Locator2.java,v 1.5 2004/03/17 14:30:10 dmegginson Exp $ |
| 5 | |
| 6 | package org.xml.sax.ext; |
| 7 | |
| 8 | import org.xml.sax.Locator; |
| 9 | |
| 10 | |
| 11 | /** |
| 12 | * SAX2 extension to augment the entity information provided |
| 13 | * though a {@link Locator}. |
| 14 | * If an implementation supports this extension, the Locator |
| 15 | * provided in {@link org.xml.sax.ContentHandler#setDocumentLocator |
| 16 | * ContentHandler.setDocumentLocator() } will implement this |
| 17 | * interface, and the |
| 18 | * <em>http://xml.org/sax/features/use-locator2</em> feature |
| 19 | * flag will have the value <em>true</em>. |
| 20 | * |
| 21 | * <blockquote> |
| 22 | * <em>This module, both source code and documentation, is in the |
| 23 | * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> |
| 24 | * </blockquote> |
| 25 | * |
| 26 | * <p> XMLReader implementations are not required to support this |
| 27 | * information, and it is not part of core-only SAX2 distributions.</p> |
| 28 | * |
| 29 | * @since SAX 2.0 (extensions 1.1 alpha) |
| 30 | * @author David Brownell |
| 31 | * @version TBS |
| 32 | */ |
| 33 | public interface Locator2 extends Locator |
| 34 | { |
| 35 | /** |
| 36 | * Returns the version of XML used for the entity. This will |
| 37 | * normally be the identifier from the current entity's |
| 38 | * <em><?xml version='...' ...?></em> declaration, |
| 39 | * or be defaulted by the parser. |
| 40 | * |
| 41 | * @return Identifier for the XML version being used to interpret |
| 42 | * the entity's text, or null if that information is not yet |
| 43 | * available in the current parsing state. |
| 44 | */ |
| 45 | public String getXMLVersion (); |
| 46 | |
| 47 | /** |
| 48 | * Returns the name of the character encoding for the entity. |
| 49 | * If the encoding was declared externally (for example, in a MIME |
| 50 | * Content-Type header), that will be the name returned. Else if there |
| 51 | * was an <em><?xml ...encoding='...'?></em> declaration at |
| 52 | * the start of the document, that encoding name will be returned. |
| 53 | * Otherwise the encoding will been inferred (normally to be UTF-8, or |
| 54 | * some UTF-16 variant), and that inferred name will be returned. |
| 55 | * |
| 56 | * <p>When an {@link org.xml.sax.InputSource InputSource} is used |
| 57 | * to provide an entity's character stream, this method returns the |
| 58 | * encoding provided in that input stream. |
| 59 | * |
| 60 | * <p> Note that some recent W3C specifications require that text |
| 61 | * in some encodings be normalized, using Unicode Normalization |
| 62 | * Form C, before processing. Such normalization must be performed |
| 63 | * by applications, and would normally be triggered based on the |
| 64 | * value returned by this method. |
| 65 | * |
| 66 | * <p> Encoding names may be those used by the underlying JVM, |
| 67 | * and comparisons should be case-insensitive. |
| 68 | * |
| 69 | * @return Name of the character encoding being used to interpret |
| 70 | * * the entity's text, or null if this was not provided for a * |
| 71 | * character stream passed through an InputSource or is otherwise |
| 72 | * not yet available in the current parsing state. |
| 73 | */ |
| 74 | public String getEncoding (); |
| 75 | } |