com.sun.xml.parser
Class Parser

java.lang.Object
  |
  +--com.sun.xml.parser.Parser
Direct Known Subclasses:
ValidatingParser

public class Parser
extends java.lang.Object
implements Parser

This implements a fast non-validating SAX parser. This one always processes external parsed entities, strictly adheres to the XML 1.0 specification, and provides useful diagnostics. It supports an optimization allowing faster processing of valid standalone XML documents. For multi-language applications (such as web servers using XML processing to create dynamic content), a method supports choosing a locale for parser diagnostics which is both understood by the message recipient and supported by the parser.

This conforms to the XML 1.0 specification. To configure an XML processor which tests document conformance against XML Namespaces, provide a DtdEventListener which examines declarations of entities and notations, and have your document listener check other constraints such as ensuring xmlns* attribute values properly declare all namespace prefixes. (Only element and attribute names may contain colons, and even then the name prefix before the colon must be properly declared.)

SAX parsers produce a stream of parse events, which applications process to create an object model which is specific to their tasks. Applications which do not want to process event streams in that way should use an API producing a standardized object model, such as the W3C's Document Object Model (DOM). This parser supports building fully conformant DOM Document objects, through use of DtdEventListener extensions to SAX in conjunction with an appropriate implementation of a SAX DocumentHandler. In addition, it supports some features (exposing comments, CDATA sections, and entity references) which are allowed by DOM but not required to be reported by conformant XML processors. (As usual, the default handler for parsing events other than fatal errors ignores them.)

See Also:
ValidatingParser

Constructor Summary
Parser()
          Constructs a SAX parser object.
 
Method Summary
 java.util.Locale chooseLocale(java.lang.String[] languages)
          Chooses a client locale to use for diagnostics, using the first language specified in the list that is supported by this parser.
 DocumentHandler getDocumentHandler()
          Returns the application being driven by the parser.
 DTDHandler getDTDHandler()
          Returns the handler used to deliver unparsed entity information.
 EntityResolver getEntityResolver()
          Returns the object used to resolve entities
 ErrorHandler getErrorHandler()
          Returns the object used for error handling
 java.util.Locale getLocale()
          Returns the diagnostic locale.
 boolean isFastStandalone()
          Returns true if standalone documents skip processing of all external DTD information.
 void parse(InputSource in)
          SAX: Parse a document.
 void parse(java.lang.String uri)
          SAX: Parse a document.
 void pushInputBuffer(char[] buf, int offset, int len)
          In support of the HTML DOM model of client side <xhtml:script> tag processing, this method permits data to be spliced into the input stream.
 void setDocumentHandler(DocumentHandler handler)
          SAX: The primary application hook into the parser, this assigns the handler for the basic SAX document events as well as the extended "lexical" events.
 void setDTDHandler(DTDHandler handler)
          SAX: Used by applications to see unparsed entity information, this assigns the handler for the basic SAX DTD events as well as the extended "DtdEventListener" events.
 void setEntityResolver(EntityResolver r)
          SAX: Lets applications control entity resolution.
 void setErrorHandler(ErrorHandler handler)
          SAX: Used to override default error handling; for example, to ensure that validity errors abort parsing, or to report errors through the correct channels.
 void setFastStandalone(boolean value)
          Setting this flag enables faster processing of valid standalone documents: external DTD information is not processed, and no attribute normalization or defaulting is done.
 void setLocale(java.util.Locale l)
          SAX: Used by applications to request locale for diagnostics.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Parser

public Parser()
Constructs a SAX parser object.
Method Detail

setLocale

public void setLocale(java.util.Locale l)
               throws SAXException
SAX: Used by applications to request locale for diagnostics.
Specified by:
setLocale in interface Parser
Parameters:
l - The locale to use, or null to use system defaults (which may include only message IDs).
Throws:
SAXException - If no diagnostic messages are available in that locale.

getLocale

public java.util.Locale getLocale()
Returns the diagnostic locale.

chooseLocale

public java.util.Locale chooseLocale(java.lang.String[] languages)
                              throws SAXException
Chooses a client locale to use for diagnostics, using the first language specified in the list that is supported by this parser. That locale is then set using setLocale(). Such a list could be provided by a variety of user preference mechanisms, including the HTTP Accept-Language header field.
Parameters:
languages - Array of language specifiers, ordered with the most preferable one at the front. For example, "en-ca" then "fr-ca", followed by "zh_CN". Both RFC 1766 and Java styles are supported.
Returns:
The chosen locale, or null.
See Also:
MessageCatalog

setEntityResolver

public void setEntityResolver(EntityResolver r)
SAX: Lets applications control entity resolution.
Specified by:
setEntityResolver in interface Parser

getEntityResolver

public EntityResolver getEntityResolver()
Returns the object used to resolve entities

setDTDHandler

public void setDTDHandler(DTDHandler handler)
SAX: Used by applications to see unparsed entity information, this assigns the handler for the basic SAX DTD events as well as the extended "DtdEventListener" events. If the specified handler supports the extended events, it receives those events; otherwise, they are ignored.
Specified by:
setDTDHandler in interface Parser
See Also:
DtdEventListener

getDTDHandler

public DTDHandler getDTDHandler()
Returns the handler used to deliver unparsed entity information.

setDocumentHandler

public void setDocumentHandler(DocumentHandler handler)
SAX: The primary application hook into the parser, this assigns the handler for the basic SAX document events as well as the extended "lexical" events. If the specified handler supports the extended events, it receives those events; otherwise, they are ignored.
Specified by:
setDocumentHandler in interface Parser
See Also:
LexicalEventListener

getDocumentHandler

public DocumentHandler getDocumentHandler()
Returns the application being driven by the parser.

setErrorHandler

public void setErrorHandler(ErrorHandler handler)
SAX: Used to override default error handling; for example, to ensure that validity errors abort parsing, or to report errors through the correct channels.
Specified by:
setErrorHandler in interface Parser

getErrorHandler

public ErrorHandler getErrorHandler()
Returns the object used for error handling

parse

public void parse(InputSource in)
           throws SAXException,
                  java.io.IOException
SAX: Parse a document.
Specified by:
parse in interface Parser

parse

public void parse(java.lang.String uri)
           throws SAXException,
                  java.io.IOException
SAX: Parse a document.
Specified by:
parse in interface Parser

setFastStandalone

public void setFastStandalone(boolean value)
Setting this flag enables faster processing of valid standalone documents: external DTD information is not processed, and no attribute normalization or defaulting is done. This optimization is only permitted in non-validating parsers; for validating parsers, this mode is silently disabled.

For documents which are declared as standalone, but which are not valid, a fatal error may be reported for references to externally defined entities. That could happen in any nonvalidating parser which did not read externally defined entities. Also, if any attribute values need normalization or defaulting, it will not be done.


isFastStandalone

public boolean isFastStandalone()
Returns true if standalone documents skip processing of all external DTD information.

pushInputBuffer

public void pushInputBuffer(char[] buf,
                            int offset,
                            int len)
                     throws SAXException
In support of the HTML DOM model of client side <xhtml:script> tag processing, this method permits data to be spliced into the input stream. This method would normally be called from an endElement callback to put the buffered result of calls such as DOM HTMLDocument.write into the input stream.


Submit Feedback to xml-feedback@java.sun.com