Qt Jambi Home

com.trolltech.qt.xml
Class QXmlDefaultHandler

java.lang.Object
  extended by com.trolltech.qt.QSignalEmitter
      extended by com.trolltech.qt.QtJambiObject
          extended by com.trolltech.qt.xml.QXmlDefaultHandler
All Implemented Interfaces:
QtJambiInterface, QXmlContentHandlerInterface, QXmlDeclHandlerInterface, QXmlDTDHandlerInterface, QXmlEntityResolverInterface, QXmlErrorHandlerInterface, QXmlLexicalHandlerInterface

public class QXmlDefaultHandler
extends QtJambiObject
implements QXmlContentHandlerInterface, QXmlErrorHandlerInterface, QXmlDTDHandlerInterface, QXmlEntityResolverInterface, QXmlLexicalHandlerInterface, QXmlDeclHandlerInterface

The QXmlDefaultHandler class provides a default implementation of all the XML handler classes.

This class gathers together the features of the specialized handler classes, making it a convenient starting point when implementing custom handlers for subclasses of QXmlReader, particularly QXmlSimpleReader. The virtual functions from each of the base classes are reimplemented in this class, providing sensible default behavior for many common cases. By subclassing this class, and overriding these functions, you can concentrate on implementing the parts of the handler relevant to your application.

The XML reader must be told which handler to use for different kinds of events during parsing. This means that, although QXmlDefaultHandler provides default implementations of functions inherited from all its base classes, we can still use specialized handlers for particular kinds of events.

For example, QXmlDefaultHandler subclasses both QXmlContentHandler and QXmlErrorHandler, so by subclassing it we can use the same handler for both of the following reader functions:

        xmlReader.setContentHandler(handler);
        xmlReader.setErrorHandler(handler);

Since the reader will inform the handler of parsing errors, it is necessary to reimplement QXmlErrorHandler::fatalError() if, for example, we want to stop parsing when such an error occurs:

    bool Handler::fatalError (const QXmlParseException & exception)
    {
        qWarning() << "Fatal error on line" << exception.lineNumber()
                   << ", column" << exception.columnNumber() << ":"
                   << exception.message();

        return false;
    }

The above function returns false, which tells the reader to stop parsing. To continue to use the same reader, it is necessary to create a new handler instance, and set up the reader to use it in the manner described above.

It is useful to examine some of the functions inherited by QXmlDefaultHandler, and consider why they might be reimplemented in a custom handler. Custom handlers will typically reimplement QXmlContentHandler::startDocument() to prepare the handler for new content. Document elements and the text within them can be processed by reimplementing QXmlContentHandler::startElement(), QXmlContentHandler::endElement(), and QXmlContentHandler::characters(). You may want to reimplement QXmlContentHandler::endDocument() to perform some finalization or validation on the content once the document has been read completely.

See Also:
QXmlDTDHandler, QXmlDeclHandler, QXmlContentHandler, QXmlEntityResolver, QXmlErrorHandler, QXmlLexicalHandler, to SAX2

Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.Signal0, QSignalEmitter.Signal1<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I>
 
Constructor Summary
QXmlDefaultHandler()
          Constructs a handler for use with subclasses of QXmlReader.
 
Method Summary
 boolean attributeDecl(java.lang.String eName, java.lang.String aName, java.lang.String type, java.lang.String valueDefault, java.lang.String value)
          

The reader calls this function to report an attribute type declaration.

 boolean characters(java.lang.String ch)
          

The reader calls this function when it has parsed a chunk of character data (either normal character data or character data inside a CDATA section; if you need to distinguish between those two types you must use QXmlLexicalHandler::startCDATA() and QXmlLexicalHandler::endCDATA()).

 boolean comment(java.lang.String ch)
          

The reader calls this function to report an XML comment anywhere in the document.

 boolean endCDATA()
          

The reader calls this function to report the end of a CDATA section.

 boolean endDocument()
          

The reader calls this function after it has finished parsing.

 boolean endDTD()
          

The reader calls this function to report the end of a DTD declaration, if any.

 boolean endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)
          

The reader calls this function when it has parsed an end element tag with the qualified name qName, the local name localName and the namespace URI namespaceURI.

 boolean endEntity(java.lang.String name)
          

The reader calls this function to report the end of an entity called name.

 boolean endPrefixMapping(java.lang.String prefix)
          

The reader calls this function to signal the end of a prefix mapping for the prefix prefix.

 boolean error(QXmlParseException exception)
          

A reader might use this function to report a recoverable error.

 java.lang.String errorString()
          

The reader calls this function to get an error string, e.g. if any of the handler functions returns false.

 boolean externalEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
          

The reader calls this function to report a parsed external entity declaration.

 boolean fatalError(QXmlParseException exception)
          

A reader must use this function to report a non-recoverable error.

static QXmlDefaultHandler fromNativePointer(QNativePointer nativePointer)
          This function returns the QXmlDefaultHandler instance pointed to by nativePointer
 boolean ignorableWhitespace(java.lang.String ch)
          

Some readers may use this function to report each chunk of whitespace in element content.

 boolean internalEntityDecl(java.lang.String name, java.lang.String value)
          

The reader calls this function to report an internal entity declaration.

 boolean notationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
          

The reader calls this function when it has parsed a notation declaration.

 boolean processingInstruction(java.lang.String target, java.lang.String data)
          

The reader calls this function when it has parsed a processing instruction.

 boolean resolveEntity(java.lang.String publicId, java.lang.String systemId, QXmlInputSource ret)
          

The reader calls this function before it opens any external entity, except the top-level document entity.

 void setDocumentLocator(QXmlLocator locator)
          

The reader calls this function before it starts parsing the document.

 boolean skippedEntity(java.lang.String name)
          

Some readers may skip entities if they have not seen the declarations (e.g. because they are in an external DTD).

 boolean startCDATA()
          

The reader calls this function to report the start of a CDATA section.

 boolean startDocument()
          

The reader calls this function when it starts parsing the document.

 boolean startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
          

The reader calls this function to report the start of a DTD declaration, if any.

 boolean startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, QXmlAttributes atts)
          

The reader calls this function when it has parsed a start element tag.

 boolean startEntity(java.lang.String name)
          

The reader calls this function to report the start of an entity called name.

 boolean startPrefixMapping(java.lang.String prefix, java.lang.String uri)
          

The reader calls this function to signal the begin of a prefix-URI namespace mapping scope.

 boolean unparsedEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notationName)
          

The reader calls this function when it finds an unparsed entity declaration.

 boolean warning(QXmlParseException exception)
          

A reader might use this function to report a warning.

 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QXmlDefaultHandler

public QXmlDefaultHandler()

Constructs a handler for use with subclasses of QXmlReader.

Method Detail

attributeDecl

public boolean attributeDecl(java.lang.String eName,
                             java.lang.String aName,
                             java.lang.String type,
                             java.lang.String valueDefault,
                             java.lang.String value)

The reader calls this function to report an attribute type declaration. Only the effective (first) declaration for an attribute is reported.

The reader passes the name of the associated element in eName and the name of the attribute in aName. It passes a string that represents the attribute type in type and a string that represents the attribute default in valueDefault. This string is one of "#IMPLIED", "#REQUIRED", "#FIXED" or an empty string (if none of the others applies). The reader passes the attribute's default value in value. If no default value is specified in the XML file, value is an empty string.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
attributeDecl in interface QXmlDeclHandlerInterface

characters

public boolean characters(java.lang.String ch)

The reader calls this function when it has parsed a chunk of character data (either normal character data or character data inside a CDATA section; if you need to distinguish between those two types you must use QXmlLexicalHandler::startCDATA() and QXmlLexicalHandler::endCDATA()). The character data is reported in ch.

Some readers report whitespace in element content using the ignorableWhitespace function rather than using this one.

A reader may report the character data of an element in more than one chunk; e.g. a reader might want to report "a<b" in three characters events ("a ", "<" and " b").

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
characters in interface QXmlContentHandlerInterface

comment

public boolean comment(java.lang.String ch)

The reader calls this function to report an XML comment anywhere in the document. It reports the text of the comment in ch.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
comment in interface QXmlLexicalHandlerInterface

endCDATA

public boolean endCDATA()

The reader calls this function to report the end of a CDATA section.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
endCDATA in interface QXmlLexicalHandlerInterface
See Also:
startCDATA, QXmlContentHandler::characters

endDTD

public boolean endDTD()

The reader calls this function to report the end of a DTD declaration, if any.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
endDTD in interface QXmlLexicalHandlerInterface
See Also:
startDTD

endDocument

public boolean endDocument()

The reader calls this function after it has finished parsing. It is called just once, and is the last handler function called. It is called after the reader has read all input or has abandoned parsing because of a fatal error.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
endDocument in interface QXmlContentHandlerInterface
See Also:
startDocument

endElement

public boolean endElement(java.lang.String namespaceURI,
                          java.lang.String localName,
                          java.lang.String qName)

The reader calls this function when it has parsed an end element tag with the qualified name qName, the local name localName and the namespace URI namespaceURI.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
endElement in interface QXmlContentHandlerInterface
See Also:
startElement, Support via Features

endEntity

public boolean endEntity(java.lang.String name)

The reader calls this function to report the end of an entity called name.

For every startEntity call, there is a corresponding endEntity call. The calls to startEntity and endEntity are properly nested.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
endEntity in interface QXmlLexicalHandlerInterface
See Also:
startEntity, QXmlContentHandler::skippedEntity, QXmlSimpleReader::setFeature

endPrefixMapping

public boolean endPrefixMapping(java.lang.String prefix)

The reader calls this function to signal the end of a prefix mapping for the prefix prefix.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
endPrefixMapping in interface QXmlContentHandlerInterface
See Also:
startPrefixMapping, Support via Features

error

public boolean error(QXmlParseException exception)

A reader might use this function to report a recoverable error. A recoverable error corresponds to the definiton of "error" in section 1.2 of the XML 1.0 specification. Details of the error are stored in exception.

The reader must continue to provide normal parsing events after invoking this function.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
error in interface QXmlErrorHandlerInterface

errorString

public java.lang.String errorString()

The reader calls this function to get an error string, e.g. if any of the handler functions returns false.

Specified by:
errorString in interface QXmlContentHandlerInterface
Specified by:
errorString in interface QXmlDeclHandlerInterface
Specified by:
errorString in interface QXmlDTDHandlerInterface
Specified by:
errorString in interface QXmlEntityResolverInterface
Specified by:
errorString in interface QXmlErrorHandlerInterface
Specified by:
errorString in interface QXmlLexicalHandlerInterface

externalEntityDecl

public boolean externalEntityDecl(java.lang.String name,
                                  java.lang.String publicId,
                                  java.lang.String systemId)

The reader calls this function to report a parsed external entity declaration. Only the effective (first) declaration for each entity is reported.

The reader passes the name of the entity in name, the public identifier in publicId and the system identifier in systemId. If there is no public identifier specified, it passes an empty string in publicId.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
externalEntityDecl in interface QXmlDeclHandlerInterface

fatalError

public boolean fatalError(QXmlParseException exception)

A reader must use this function to report a non-recoverable error. Details of the error are stored in exception.

If this function returns true the reader might try to go on parsing and reporting further errors, but no regular parsing events are reported.

Specified by:
fatalError in interface QXmlErrorHandlerInterface

ignorableWhitespace

public boolean ignorableWhitespace(java.lang.String ch)

Some readers may use this function to report each chunk of whitespace in element content. The whitespace is reported in ch.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
ignorableWhitespace in interface QXmlContentHandlerInterface

internalEntityDecl

public boolean internalEntityDecl(java.lang.String name,
                                  java.lang.String value)

The reader calls this function to report an internal entity declaration. Only the effective (first) declaration is reported.

The reader passes the name of the entity in name and the value of the entity in value.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
internalEntityDecl in interface QXmlDeclHandlerInterface

notationDecl

public boolean notationDecl(java.lang.String name,
                            java.lang.String publicId,
                            java.lang.String systemId)

The reader calls this function when it has parsed a notation declaration.

The argument name is the notation name, publicId is the notation's public identifier and systemId is the notation's system identifier.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
notationDecl in interface QXmlDTDHandlerInterface

processingInstruction

public boolean processingInstruction(java.lang.String target,
                                     java.lang.String data)

The reader calls this function when it has parsed a processing instruction.

target is the target name of the processing instruction and data is the data in the processing instruction.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
processingInstruction in interface QXmlContentHandlerInterface

resolveEntity

public boolean resolveEntity(java.lang.String publicId,
                             java.lang.String systemId,
                             QXmlInputSource ret)

The reader calls this function before it opens any external entity, except the top-level document entity. The application may request the reader to resolve the entity itself (ret is 0) or to use an entirely different input source (ret points to the input source).

The reader deletes the input source ret when it no longer needs it, so you should allocate it on the heap with new.

The argument publicId is the public identifier of the external entity, systemId is the system identifier of the external entity and ret is the return value of this function. If ret is 0 the reader should resolve the entity itself, if it is non-zero it must point to an input source which the reader uses instead.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
resolveEntity in interface QXmlEntityResolverInterface

setDocumentLocator

public void setDocumentLocator(QXmlLocator locator)

The reader calls this function before it starts parsing the document. The argument locator is a pointer to a QXmlLocator which allows the application to get the parsing position within the document.

Do not destroy the locator; it is destroyed when the reader is destroyed. (Do not use the locator after the reader is destroyed).

Specified by:
setDocumentLocator in interface QXmlContentHandlerInterface

skippedEntity

public boolean skippedEntity(java.lang.String name)

Some readers may skip entities if they have not seen the declarations (e.g. because they are in an external DTD). If they do so they report that they skipped the entity called name by calling this function.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
skippedEntity in interface QXmlContentHandlerInterface

startCDATA

public boolean startCDATA()

The reader calls this function to report the start of a CDATA section. The content of the CDATA section is reported through the QXmlContentHandler::characters() function. This function is intended only to report the boundary.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
startCDATA in interface QXmlLexicalHandlerInterface
See Also:
endCDATA

startDTD

public boolean startDTD(java.lang.String name,
                        java.lang.String publicId,
                        java.lang.String systemId)

The reader calls this function to report the start of a DTD declaration, if any. It reports the name of the document type in name, the public identifier in publicId and the system identifier in systemId.

If the public identifier is missing, publicId is set to an empty string. If the system identifier is missing, systemId is set to an empty string. Note that it is not valid XML to have a public identifier but no system identifier; in such cases a parse error will occur.

All declarations reported through QXmlDTDHandler or QXmlDeclHandler appear between the startDTD and endDTD calls.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
startDTD in interface QXmlLexicalHandlerInterface
See Also:
endDTD

startDocument

public boolean startDocument()

The reader calls this function when it starts parsing the document. The reader calls this function just once, after the call to setDocumentLocator, and before any other functions in this class or in the QXmlDTDHandler class are called.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
startDocument in interface QXmlContentHandlerInterface
See Also:
endDocument

startElement

public boolean startElement(java.lang.String namespaceURI,
                            java.lang.String localName,
                            java.lang.String qName,
                            QXmlAttributes atts)

The reader calls this function when it has parsed a start element tag.

There is a corresponding endElement call when the corresponding end element tag is read. The startElement and endElement calls are always nested correctly. Empty element tags (e.g. <x/>) cause a startElement call to be immediately followed by an endElement call.

The attribute list provided only contains attributes with explicit values. The attribute list contains attributes used for namespace declaration (i.e. attributes starting with xmlns) only if the namespace-prefix property of the reader is true.

The argument namespaceURI is the namespace URI, or an empty string if the element has no namespace URI or if no namespace processing is done. localName is the local name (without prefix), or an empty string if no namespace processing is done, qName is the qualified name (with prefix) and atts are the attributes attached to the element. If there are no attributes, atts is an empty attributes object.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
startElement in interface QXmlContentHandlerInterface
See Also:
endElement, Support via Features

startEntity

public boolean startEntity(java.lang.String name)

The reader calls this function to report the start of an entity called name.

Note that if the entity is unknown, the reader reports it through QXmlContentHandler::skippedEntity() and not through this function.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
startEntity in interface QXmlLexicalHandlerInterface
See Also:
endEntity, QXmlSimpleReader::setFeature

startPrefixMapping

public boolean startPrefixMapping(java.lang.String prefix,
                                  java.lang.String uri)

The reader calls this function to signal the begin of a prefix-URI namespace mapping scope. This information is not necessary for normal namespace processing since the reader automatically replaces prefixes for element and attribute names.

Note that startPrefixMapping and endPrefixMapping calls are not guaranteed to be properly nested relative to each other: all startPrefixMapping events occur before the corresponding startElement event, and all endPrefixMapping events occur after the corresponding endElement event, but their order is not otherwise guaranteed.

The argument prefix is the namespace prefix being declared and the argument uri is the namespace URI the prefix is mapped to.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
startPrefixMapping in interface QXmlContentHandlerInterface
See Also:
endPrefixMapping, Support via Features

unparsedEntityDecl

public boolean unparsedEntityDecl(java.lang.String name,
                                  java.lang.String publicId,
                                  java.lang.String systemId,
                                  java.lang.String notationName)

The reader calls this function when it finds an unparsed entity declaration.

The argument name is the unparsed entity's name, publicId is the entity's public identifier, systemId is the entity's system identifier and notationName is the name of the associated notation.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
unparsedEntityDecl in interface QXmlDTDHandlerInterface

warning

public boolean warning(QXmlParseException exception)

A reader might use this function to report a warning. Warnings are conditions that are not errors or fatal errors as defined by the XML 1.0 specification. Details of the warning are stored in exception.

If this function returns false the reader stops parsing and reports an error. The reader uses the function errorString to get the error message.

Specified by:
warning in interface QXmlErrorHandlerInterface

fromNativePointer

public static QXmlDefaultHandler fromNativePointer(QNativePointer nativePointer)
This function returns the QXmlDefaultHandler instance pointed to by nativePointer

Parameters:
nativePointer - the QNativePointer of which object should be returned.

Qt Jambi Home