Overview | Package | Class | Use | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## gnu.xml.util
Class XMLWriter

    java.lang.Object
      |
      +--gnu.xml.util.XMLWriter

All Implemented Interfaces:
  ContentHandler, DeclHandler, DTDHandler, LexicalHandler

Direct Known Subclasses:
  TextConsumer, XHTMLWriter

public class XMLWriter
extends java.lang.Object
implements ContentHandler, LexicalHandler, DTDHandler, DeclHandler

This class is a SAX handler which writes all its input as a well formed XML or XHTML document. If driven using SAX2 events, this output may include a recreated document type declaration, subject to limitations of SAX (no internal subset exposed) or DOM (the important declarations, with their documentation, are discarded).

By default, text is generated "as-is", but some optional modes are supported. Pretty-printing is supported, to make life easier for people reading the output. XHTML (1.0) output has can be made particularly pretty; all the built-in character entities are known. Canonical XML can also be generated, assuming the input is properly formed.

Some of the methods on this class are intended for applications to use directly, rather than as pure SAX2 event callbacks. Some of those methods access the JavaBeans properties (used to tweak output formats, for example canonicalization and pretty printing). Subclasses are expected to add new behaviors, not to modify current behavior, so many such methods are final.

The write*() methods may be slightly simpler for some applications to use than direct callbacks. For example, they support a simple policy for encoding data items as the content of a single element.

To reuse an XMLWriter you must provide it with a new Writer, since this handler closes the writer it was given as part of its endDocument() handling. (XML documents have an end of input, and the way to encode that on a stream is to close it.)

Note that any relative URIs in the source document, as found in entity and notation declarations, ought to have been fully resolved by the parser providing events to this handler. This means that the output text should only have fully resolved URIs, which may not be the desired behavior in cases where later binding is desired.

Note that due to SAX2 defaults, you may need to manually ensure that the input events are XML-conformant with respect to namespace prefixes and declarations. `NSFilter` is one solution to this problem, in the context of processing pipelines. Something as simple as connecting this handler to a parser might not generate the correct output. Another workaround is to ensure that the namespace-prefixes feature is always set to true, if you're hooking this directly up to some XMLReader implementation.

Version:
  $Date: 2001/11/20 01:15:45 $
Author:
  David Brownell
See Also:
  `TextConsumer`

Constructor Summary
`XMLWriter()` Constructs this handler with System.out used to write SAX events using the UTF-8 encoding.
`XMLWriter(java.io.OutputStream out)` Constructs a handler which writes all input to the output stream in the UTF-8 encoding, and closes it when endDocument is called.
`XMLWriter(java.io.Writer writer)` Constructs a handler which writes all input to the writer, and then closes the writer when the document ends.
`XMLWriter(java.io.Writer writer, java.lang.String encoding)` Constructs a handler which writes all input to the writer, and then closes the writer when the document ends.

Method Summary
`void` | `attributeDecl(java.lang.String eName, java.lang.String aName, java.lang.String type, java.lang.String mode, java.lang.String value)` SAX2: called on attribute declarations
`void` | `characters(char[] ch, int start, int length)` SAX1: reports content characters
`void` | `comment(char[] ch, int start, int length)` SAX2: called when comments are parsed.
`void` | `elementDecl(java.lang.String name, java.lang.String model)` SAX2: called on element declarations
`void` | `endCDATA()` SAX2: called after parsing CDATA characters
`void` | `endDocument()` SAX1: indicates the completion of a parse.
`void` | `endDTD()` SAX2: called after the doctype is parsed
`void` | `endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)` SAX2: indicates the end of an element
`void` | `endEntity(java.lang.String name)` SAX2: called after parsing a general entity in content
`void` | `endPrefixMapping(java.lang.String prefix)` SAX2: ignored.
`void` | `externalEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)` SAX2: called on external entity declarations
`protected void` | `fatal(java.lang.String message, java.lang.Exception e)` Used internally and by subclasses, this encapsulates the logic involved in reporting fatal errors.
`void` | `flush()` Flushes the output stream.
`void` | `ignorableWhitespace(char[] ch, int start, int length)` SAX1: reports ignorable whitespace
`void` | `internalEntityDecl(java.lang.String name, java.lang.String value)` SAX2: called on internal entity declarations
`boolean` | `isCanonical()` Returns value of flag controlling canonical output.
`boolean` | `isExpandingEntities()` Returns true if the output will have no entity references; returns false (the default) otherwise.
`boolean` | `isPrettyPrinting()` Returns value of flag controlling pretty printing.
`boolean` | `isXhtml()` Returns true if the output attempts to echo the input following "transitional" XHTML rules and matching the "HTML Compatibility Guidelines" so that an HTML version 3 browser can read the output as HTML; returns false (the default) othewise.
`void` | `notationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)` SAX1: called on notation declarations
`void` | `processingInstruction(java.lang.String target, java.lang.String data)` SAX1: reports a PI.
`void` | `setCanonical(boolean value)` Sets the output style to be canonicalized.
`void` | `setDocumentLocator(Locator l)` SAX1: provides parser status information
`void` | `setEOL(java.lang.String eolString)` Assigns the line ending style to be used on output.
`void` | `setErrorHandler(ErrorHandler handler)` Assigns the error handler to be used to present most fatal errors.
`void` | `setExpandingEntities(boolean value)` Controls whether the output text contains references to entities (the default), or instead contains the expanded values of those entities.
`void` | `setPrettyPrinting(boolean value)` Controls pretty-printing, which by default is not enabled (and currently is most useful for XHTML output).
`void` | `setWriter(java.io.Writer writer, java.lang.String encoding)` Resets the handler to write a new text document.
`void` | `setXhtml(boolean value)` Controls whether the output should attempt to follow the "transitional" XHTML rules so that it meets the "HTML Compatibility Guidelines" appendix in the XHTML specification.
`void` | `skippedEntity(java.lang.String name)` SAX1: indicates a non-expanded entity reference
`void` | `startCDATA()` SAX2: called before parsing CDATA characters
`void` | `startDocument()` SAX1: indicates the beginning of a document parse.
`void` | `startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)` SAX2: called when the doctype is partially parsed Note that this, like other doctype related calls, is ignored when XHTML is in use.
`void` | `startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, Attributes atts)` SAX2: indicates the start of an element.
`void` | `startEntity(java.lang.String name)` SAX2: called before parsing a general entity in content
`void` | `startPrefixMapping(java.lang.String prefix, java.lang.String uri)` SAX2: ignored.
`void` | `unparsedEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notationName)` SAX1: called on unparsed entity declarations
`void` | `write(java.lang.String data)` Writes the string as if characters() had been called on the contents of the string.
`void` | `writeElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, Attributes atts, int content)` Writes an element that has content consisting of a single integer, encoded as a decimal string.
`void` | `writeElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, Attributes atts, java.lang.String content)` Writes an element that has content consisting of a single string.
`void` | `writeEmptyElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, Attributes atts)` Writes an empty element.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### XMLWriter

    public XMLWriter()
              throws java.io.IOException

  Constructs this handler with System.out used to write SAX events using the UTF-8 encoding. Avoid using this except when you know it's safe to close System.out at the end of the document.

### XMLWriter

    public XMLWriter(java.io.OutputStream out)
              throws java.io.IOException

  Constructs a handler which writes all input to the output stream in the UTF-8 encoding, and closes it when endDocument is called. (Yes it's annoying that this throws an exception -- but there's really no way around it, since it's barely possible a JDK may exist somewhere that doesn't know how to emit UTF-8.)

### XMLWriter

    public XMLWriter(java.io.Writer writer)

  Constructs a handler which writes all input to the writer, and then closes the writer when the document ends. If an XML declaration is written onto the output, and this class can determine the name of the character encoding for this writer, that encoding name will be included in the XML declaration.

  See the description of the constructor which takes an encoding name for imporant information about selection of encodings.

  Parameters:
    `writer` - XML text is written to this writer.

### XMLWriter

    public XMLWriter(java.io.Writer writer,
                     java.lang.String encoding)

  Constructs a handler which writes all input to the writer, and then closes the writer when the document ends. If an XML declaration is written onto the output, this class will use the specified encoding name in that declaration. If no encoding name is specified, no encoding name will be declared unless this class can otherwise determine the name of the character encoding for this writer.

  At this time, only the UTF-8 ("UTF8") and UTF-16 ("Unicode") output encodings are fully lossless with respect to XML data. If you use any other encoding you risk having your data be silently mangled on output, as the standard Java character encoding subsystem silently maps non-encodable characters to a question mark ("?") and will not report such errors to applications.

  For a few other encodings the risk can be reduced. If the writer is a java.io.OutputStreamWriter, and uses either the ISO-8859-1 ("8859_1", "ISO8859_1", etc) or US-ASCII ("ASCII") encodings, content which can't be encoded in those encodings will be written safely. Where relevant, the XHTML entity names will be used; otherwise, numeric character references will be emitted.

  However, there remain a number of cases where substituting such entity or character references is not an option. Such references are not usable within a DTD, comment, PI, or CDATA section. Neither may they be used when element, attribute, entity, or notation names have the problematic characters.

  Parameters:
    `writer` - XML text is written to this writer.
    `encoding` - if non-null, and an XML declaration is written, this is the name that will be used for the character encoding.

Method Detail

### setWriter

    public final void setWriter(java.io.Writer writer,
                                java.lang.String encoding)

  Resets the handler to write a new text document.
  Parameters:
    `writer` - XML text is written to this writer.
    `encoding` - if non-null, and an XML declaration is written, this is the name that will be used for the character encoding.
  Throws:
    `IllegalStateException` - if the current document hasn't yet ended (with `endDocument()`)

### setEOL

    public final void setEOL(java.lang.String eolString)

  Assigns the line ending style to be used on output.
  Parameters:
    `eolString` - null to use the system default; else "\n", "\r", or "\r\n".

### setErrorHandler

    public void setErrorHandler(ErrorHandler handler)

  Assigns the error handler to be used to present most fatal errors.

### fatal

    protected void fatal(java.lang.String message,
                         java.lang.Exception e)
                  throws SAXException

  Used internally and by subclasses, this encapsulates the logic involved in reporting fatal errors. It uses locator information for good diagnostics, if available, and gives the application's ErrorHandler the opportunity to handle the error before throwing an exception.

### setXhtml

    public final void setXhtml(boolean value)

  Controls whether the output should attempt to follow the "transitional" XHTML rules so that it meets the "HTML Compatibility Guidelines" appendix in the XHTML specification. A "transitional" Document Type Declaration (DTD) is placed near the beginning of the output document, instead of whatever DTD would otherwise have been placed there, and XHTML empty elements are printed specially. When writing text in US-ASCII or ISO-8859-1 encodings, the predefined XHTML internal entity names are used (in preference to character references) when writing content characters which can't be expressed in those encodings.

  When this option is enabled, it is the caller's responsibility to ensure that the input is otherwise valid as XHTML. Things to be careful of in all cases, as described in the appendix referenced above, include:

  - Element and attribute names must be in lower case, both in the document and in any CSS style sheet.
  - All XML constructs must be valid as defined by the XHTML "transitional" DTD (including all familiar constructs, even deprecated ones).
  - The root element must be "html".
  - Elements that must be empty (such as <br> must have no content.
  - Use both lang and xml:lang attributes when specifying language.
  - Similarly, use both id and name attributes when defining elements that may be referred to through URI fragment identifiers ... and make sure that the value is a legal NMTOKEN, since not all such HTML 4.0 identifiers are valid in XML.
  - Be careful with character encodings; make sure you provide a <meta http-equiv="Content-type" content="text/xml;charset=..." /> element in the HTML "head" element, naming the same encoding used to create this handler. Also, if that encoding is anything other than US-ASCII, make sure that if the document is given a MIME content type, it has a charset=... attribute with that encoding.

  Additionally, some of the oldest browsers have additional quirks, to address with guidelines such as:

  - Processing instructions may be rendered, so avoid them. (Similarly for an XML declaration.)
  - Embedded style sheets and scripts should not contain XML markup delimiters: &, <, and ]]> are trouble.
  - Attribute values should not have line breaks or multiple consecutive white space characters.
  - Use no more than one of the deprecated (transitional) <isindex> elements.
  - Some boolean attributes (such as compact, checked, disabled, readonly, selected, and more) confuse some browsers, since they only understand minimized versions which are illegal in XML.

  Also, some characteristics of the resulting output may be a function of whether the document is later given a MIME content type of text/html rather than one indicating XML (application/xml or text/xml). Worse, some browsers ignore MIME content types and prefer to rely URI name suffixes -- so an "index.xml" could always be XML, never XHTML, no matter its MIME type.

### isXhtml

    public final boolean isXhtml()

  Returns true if the output attempts to echo the input following "transitional" XHTML rules and matching the "HTML Compatibility Guidelines" so that an HTML version 3 browser can read the output as HTML; returns false (the default) othewise.

### setExpandingEntities

    public final void setExpandingEntities(boolean value)

  Controls whether the output text contains references to entities (the default), or instead contains the expanded values of those entities.

### isExpandingEntities

    public final boolean isExpandingEntities()

  Returns true if the output will have no entity references; returns false (the default) otherwise.

### setPrettyPrinting

    public final void setPrettyPrinting(boolean value)

  Controls pretty-printing, which by default is not enabled (and currently is most useful for XHTML output). Pretty printing enables structural indentation, sorting of attributes by name, line wrapping, and potentially other mechanisms for making output more or less readable.

  At this writing, structural indentation and line wrapping are enabled when pretty printing is enabled and the xml:space attribute has the value default (its other legal value is preserve, as defined in the XML specification). The three XHTML element types which use another value are recognized by their names (namespaces are ignored).

  Also, for the record, the "pretty" aspect of printing here is more to provide basic structure on outputs that would otherwise risk being a single long line of text. For now, expect the structure to be ragged ... unless you'd like to submit a patch to make this be more strictly formatted!

  Throws:
    `IllegalStateException` - thrown if this method is invoked after output has begun.

### isPrettyPrinting

    public final boolean isPrettyPrinting()

  Returns value of flag controlling pretty printing.

### setCanonical

    public final void setCanonical(boolean value)

  Sets the output style to be canonicalized. Input events must meet requirements that are slightly more stringent than the basic well-formedness ones, and include:
  - Namespace prefixes must not have been changed from those in the original document. (This may only be ensured by setting the SAX2 XMLReader namespace-prefixes feature flag; by default, it is cleared.)
  - Redundant namespace declaration attributes have been removed. (If an ancestor element defines a namespace prefix and that declaration hasn't been overriden, an element must not redeclare it.)
  - If comments are not to be included in the canonical output, they must first be removed from the input event stream; this Canonical XML with comments by default.
  - If the input character encoding was not UCS-based, the character data must have been normalized using Unicode Normalization Form C. (UTF-8 and UTF-16 are UCS-based.)
  - Attribute values must have been normalized, as is done by any conformant XML processor which processes all external parameter entities.
  - Similarly, attribute value defaulting has been performed.

  Note that fragments of XML documents, as specified by an XPath node set, may be canonicalized. In such cases, elements may need some fixup (for xml:* attributes and application-specific context).

  Throws:
    `java.lang.IllegalArgumentException` - if the output encoding is anything other than UTF-8.

### isCanonical

    public final boolean isCanonical()

  Returns value of flag controlling canonical output.

### flush

    public final void flush()
                     throws java.io.IOException

  Flushes the output stream. When this handler is used in long lived pipelines, it can be important to flush buffered state, for example so that it can reach the disk as part of a state checkpoint.

### write

    public final void write(java.lang.String data)
                     throws SAXException

  Writes the string as if characters() had been called on the contents of the string. This is particularly useful when applications act as producers and write data directly to event consumers.

### writeElement

    public void writeElement(java.lang.String uri,
                             java.lang.String localName,
                             java.lang.String qName,
                             Attributes atts,
                             java.lang.String content)
                      throws SAXException

  Writes an element that has content consisting of a single string.
  See Also:
    `writeEmptyElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`, `startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`

### writeElement

    public void writeElement(java.lang.String uri,
                             java.lang.String localName,
                             java.lang.String qName,
                             Attributes atts,
                             int content)
                      throws SAXException

  Writes an element that has content consisting of a single integer, encoded as a decimal string.
  See Also:
    `writeEmptyElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`, `startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`

### setDocumentLocator

    public final void setDocumentLocator(Locator l)

  SAX1: provides parser status information
  Specified by:
    `setDocumentLocator` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `locator` - An object that can return the location of any SAX document event.
  See Also:
    `Locator`

### startDocument

    public void startDocument()
                       throws SAXException

  SAX1: indicates the beginning of a document parse. If you're writing (well formed) fragments of XML, neither this nor endDocument should be called.
  Specified by:
    `startDocument` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `ContentHandler.endDocument()`

### endDocument

    public void endDocument()
                     throws SAXException

  SAX1: indicates the completion of a parse. Note that all complete SAX event streams make this call, even if an error is reported during a parse.
  Specified by:
    `endDocument` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `ContentHandler.startDocument()`

### startPrefixMapping

    public final void startPrefixMapping(java.lang.String prefix,
                                         java.lang.String uri)

  SAX2: ignored.
  Specified by:
    `startPrefixMapping` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `prefix` - The Namespace prefix being declared.
    `uri` - The Namespace URI the prefix is mapped to.
  Throws:
    `SAXException` - The client may throw an exception during processing.
  See Also:
    `ContentHandler.endPrefixMapping(java.lang.String)`, `ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`

### endPrefixMapping

    public final void endPrefixMapping(java.lang.String prefix)

  SAX2: ignored.
  Specified by:
    `endPrefixMapping` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `prefix` - The prefix that was being mapping.
  Throws:
    `SAXException` - The client may throw an exception during processing.
  See Also:
    `ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)`, `ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)`

### startElement

    public final void startElement(java.lang.String uri,
                                   java.lang.String localName,
                                   java.lang.String qName,
                                   Attributes atts)
                            throws SAXException

  SAX2: indicates the start of an element. When XHTML is in use, avoid attribute values with line breaks or multiple whitespace characters, since not all user agents handle them correctly.
  Specified by:
    `startElement` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `uri` - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
    `localName` - The local name (without prefix), or the empty string if Namespace processing is not being performed.
    `qName` - The qualified name (with prefix), or the empty string if qualified names are not available.
    `atts` - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)`, `Attributes`

### writeEmptyElement

    public void writeEmptyElement(java.lang.String uri,
                                  java.lang.String localName,
                                  java.lang.String qName,
                                  Attributes atts)
                           throws SAXException

  Writes an empty element.
  See Also:
    `startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`

### endElement

    public final void endElement(java.lang.String uri,
                                 java.lang.String localName,
                                 java.lang.String qName)
                          throws SAXException

  SAX2: indicates the end of an element
  Specified by:
    `endElement` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `uri` - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
    `localName` - The local name (without prefix), or the empty string if Namespace processing is not being performed.
    `qName` - The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### characters

    public final void characters(char[] ch,
                                 int start,
                                 int length)
                          throws SAXException

  SAX1: reports content characters
  Specified by:
    `characters` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `ch` - The characters from the XML document.
    `start` - The start position in the array.
    `length` - The number of characters to read from the array.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `ContentHandler.ignorableWhitespace(char[], int, int)`, `Locator`

### ignorableWhitespace

    public final void ignorableWhitespace(char[] ch,
                                          int start,
                                          int length)
                                   throws SAXException

  SAX1: reports ignorable whitespace
  Specified by:
    `ignorableWhitespace` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `ch` - The characters from the XML document.
    `start` - The start position in the array.
    `length` - The number of characters to read from the array.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `ContentHandler.characters(char[], int, int)`

### processingInstruction

    public final void processingInstruction(java.lang.String target,
                                            java.lang.String data)
                                     throws SAXException

  SAX1: reports a PI. This doesn't check for illegal target names, such as "xml" or "XML", or namespace-incompatible ones like "big:dog"; the caller is responsible for ensuring those names are legal.
  Specified by:
    `processingInstruction` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `target` - The processing instruction target.
    `data` - The processing instruction data, or null if none was supplied. The data does not include any whitespace separating it from the target.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### skippedEntity

    public void skippedEntity(java.lang.String name)
                       throws SAXException

  SAX1: indicates a non-expanded entity reference
  Specified by:
    `skippedEntity` in interface `ContentHandler`
  Following copied from interface: `org.xml.sax.ContentHandler`
  Parameters:
    `name` - The name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]".
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### startCDATA

    public final void startCDATA()
                          throws SAXException

  SAX2: called before parsing CDATA characters
  Specified by:
    `startCDATA` in interface `LexicalHandler`
  Following copied from interface: `org.xml.sax.ext.LexicalHandler`
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `LexicalHandler.endCDATA()`

### endCDATA

    public final void endCDATA()
                        throws SAXException

  SAX2: called after parsing CDATA characters
  Specified by:
    `endCDATA` in interface `LexicalHandler`
  Following copied from interface: `org.xml.sax.ext.LexicalHandler`
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `LexicalHandler.startCDATA()`

### startDTD

    public final void startDTD(java.lang.String name,
                               java.lang.String publicId,
                               java.lang.String systemId)
                        throws SAXException

  SAX2: called when the doctype is partially parsed Note that this, like other doctype related calls, is ignored when XHTML is in use.
  Specified by:
    `startDTD` in interface `LexicalHandler`
  Following copied from interface: `org.xml.sax.ext.LexicalHandler`
  Parameters:
    `name` - The document type name.
    `publicId` - The declared public identifier for the external DTD subset, or null if none was declared.
    `systemId` - The declared system identifier for the external DTD subset, or null if none was declared. (Note that this is not resolved against the document base URI.)
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `LexicalHandler.endDTD()`, `LexicalHandler.startEntity(java.lang.String)`

### endDTD

    public final void endDTD()
                      throws SAXException

  SAX2: called after the doctype is parsed
  Specified by:
    `endDTD` in interface `LexicalHandler`
  Following copied from interface: `org.xml.sax.ext.LexicalHandler`
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `LexicalHandler.startDTD(java.lang.String, java.lang.String, java.lang.String)`

### startEntity

    public final void startEntity(java.lang.String name)
                           throws SAXException

  SAX2: called before parsing a general entity in content
  Specified by:
    `startEntity` in interface `LexicalHandler`
  Following copied from interface: `org.xml.sax.ext.LexicalHandler`
  Parameters:
    `name` - The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `LexicalHandler.endEntity(java.lang.String)`, `DeclHandler.internalEntityDecl(java.lang.String, java.lang.String)`, `DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)`

### endEntity

    public final void endEntity(java.lang.String name)
                         throws SAXException

  SAX2: called after parsing a general entity in content
  Specified by:
    `endEntity` in interface `LexicalHandler`
  Following copied from interface: `org.xml.sax.ext.LexicalHandler`
  Parameters:
    `name` - The name of the entity that is ending.
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `LexicalHandler.startEntity(java.lang.String)`

### comment

    public final void comment(char[] ch,
                              int start,
                              int length)
                       throws SAXException

  SAX2: called when comments are parsed. When XHTML is used, the old HTML tradition of using comments to for inline CSS, or for JavaScript code is discouraged. This is because XML processors are encouraged to discard, on the grounds that comments are for users (and perhaps text editors) not programs. Instead, use external scripts
  Specified by:
    `comment` in interface `LexicalHandler`
  Following copied from interface: `org.xml.sax.ext.LexicalHandler`
  Parameters:
    `ch` - An array holding the characters in the comment.
    `start` - The starting position in the array.
    `length` - The number of characters to use from the array.
  Throws:
    `SAXException` - The application may raise an exception.

### notationDecl

    public final void notationDecl(java.lang.String name,
                                   java.lang.String publicId,
                                   java.lang.String systemId)
                            throws SAXException

  SAX1: called on notation declarations
  Specified by:
    `notationDecl` in interface `DTDHandler`
  Following copied from interface: `org.xml.sax.DTDHandler`
  Parameters:
    `name` - The notation name.
    `publicId` - The notation's public identifier, or null if none was given.
    `systemId` - The notation's system identifier, or null if none was given.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)`, `Attributes`

### unparsedEntityDecl

    public final void unparsedEntityDecl(java.lang.String name,
                                         java.lang.String publicId,
                                         java.lang.String systemId,
                                         java.lang.String notationName)
                                  throws SAXException

  SAX1: called on unparsed entity declarations
  Specified by:
    `unparsedEntityDecl` in interface `DTDHandler`
  Following copied from interface: `org.xml.sax.DTDHandler`
  Parameters:
    `name` - The unparsed entity's name.
    `publicId` - The entity's public identifier, or null if none was given.
    `systemId` - The entity's system identifier.
    `notationName` - The name of the associated notation.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `DTDHandler.notationDecl(java.lang.String, java.lang.String, java.lang.String)`, `Attributes`

### attributeDecl

    public final void attributeDecl(java.lang.String eName,
                                    java.lang.String aName,
                                    java.lang.String type,
                                    java.lang.String mode,
                                    java.lang.String value)
                             throws SAXException

  SAX2: called on attribute declarations
  Specified by:
    `attributeDecl` in interface `DeclHandler`
  Following copied from interface: `org.xml.sax.ext.DeclHandler`
  Parameters:
    `eName` - The name of the associated element.
    `aName` - The name of the attribute.
    `type` - A string representing the attribute type.
    `mode` - A string representing the attribute defaulting mode ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if none of these applies.
    `value` - A string representing the attribute's default value, or null if there is none.
  Throws:
    `SAXException` - The application may raise an exception.

### elementDecl

    public final void elementDecl(java.lang.String name,
                                  java.lang.String model)
                           throws SAXException

  SAX2: called on element declarations
  Specified by:
    `elementDecl` in interface `DeclHandler`
  Following copied from interface: `org.xml.sax.ext.DeclHandler`
  Parameters:
    `name` - The element type name.
    `model` - The content model as a normalized string.
  Throws:
    `SAXException` - The application may raise an exception.

### externalEntityDecl

    public final void externalEntityDecl(java.lang.String name,
                                         java.lang.String publicId,
                                         java.lang.String systemId)
                                  throws SAXException

  SAX2: called on external entity declarations
  Specified by:
    `externalEntityDecl` in interface `DeclHandler`
  Following copied from interface: `org.xml.sax.ext.DeclHandler`
  Parameters:
    `name` - The name of the entity. If it is a parameter entity, the name will begin with '%'.
    `publicId` - The declared public identifier of the entity, or null if none was declared.
    `systemId` - The declared system identifier of the entity.
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `DeclHandler.internalEntityDecl(java.lang.String, java.lang.String)`, `DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)`

### internalEntityDecl

    public final void internalEntityDecl(java.lang.String name,
                                         java.lang.String value)
                                  throws SAXException

  SAX2: called on internal entity declarations
  Specified by:
    `internalEntityDecl` in interface `DeclHandler`
  Following copied from interface: `org.xml.sax.ext.DeclHandler`
  Parameters:
    `name` - The name of the entity. If it is a parameter entity, the name will begin with '%'.
    `value` - The replacement text of the entity.
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)`, `DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)`

Overview | Package | Class | Use | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Source code is under GPL (with library exception) in the JAXP project at http://www.gnu.org/software/classpathx/jaxp
This documentation was derived from that source code on 2001-11-20.