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