Qt Jambi Home

com.trolltech.qt.xml
Class QXmlSimpleReader

java.lang.Object
  extended by com.trolltech.qt.QSignalEmitter
      extended by com.trolltech.qt.QtJambiObject
          extended by com.trolltech.qt.xml.QXmlReader
              extended by com.trolltech.qt.xml.QXmlSimpleReader
All Implemented Interfaces:
QtJambiInterface

public class QXmlSimpleReader
extends QXmlReader

The QXmlSimpleReader class provides an implementation of a simple XML parser.

This XML reader is suitable for a wide range of applications. It is able to parse well-formed XML and can report the namespaces of elements to a content handler; however, it does not parse any external entities. For historical reasons, Attribute Value Normalization and End-of-Line Handling as described in the XML 1.0 specification is not performed.

The easiest pattern of use for this class is to create a reader instance, define an input source, specify the handlers to be used by the reader, and parse the data.

For example, we could use a QFile to supply the input. Here, we create a reader, and define an input source to be used by the reader:

        QXmlSimpleReader xmlReader;
        QXmlInputSource *source = new QXmlInputSource(file);

A handler lets us perform actions when the reader encounters certain types of content, or if errors in the input are found. The reader must be told which handler to use for each type of event. For many common applications, we can create a custom handler by subclassing QXmlDefaultHandler, and use this to handle both error and content events:

        Handler *handler = new Handler;
        xmlReader.setContentHandler(handler);
        xmlReader.setErrorHandler(handler);

If you don't set at least the content and error handlers, the parser will fall back on its default behavior---and will do nothing.

The most convenient way to handle the input is to read it in a single pass using the parse function with an argument that specifies the input source:

        bool ok = xmlReader.parse(source);

        if (!ok)
            std::cout << "Parsing failed." << std::endl;

If you can't parse the entire input in one go (for example, it is huge, or is being delivered over a network connection), data can be fed to the parser in pieces. This is achieved by telling parse to work incrementally, and making subsequent calls to the parseContinue function, until all the data has been processed.

A common way to perform incremental parsing is to connect the readyRead() signal of the input source to a slot, and handle the incoming data there. For example, the following code shows how a parser for RSS feeds can be used to incrementally parse data that it receives from a QHttp object:

    void RSSListing::readData(const QHttpResponseHeader &resp)
    {
        bool ok;

        if (resp.statusCode() != 200)
            http.abort();
        else {
            xmlInput.setData(http.readAll());

            if (newInformation) {
                ok = xmlReader.parse(&xmlInput, true);
                newInformation = false;
            }
            else
                ok = xmlReader.parseContinue();

            if (!ok)
                http.abort();
        }
    }

Aspects of the parsing behavior can be adapted using setFeature and setProperty(). For example, the following code could be used to enable reporting of namespace prefixes to the content handler:

    xmlReader.setFeature("http://xml.org/sax/features/namespace-prefixes", true);


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
QXmlSimpleReader()
          Constructs a simple XML reader.
 
Method Summary
 QXmlContentHandlerInterface contentHandler()
          

Returns the content handler or 0 if none was set.

 QXmlDeclHandlerInterface declHandler()
          

Returns the declaration handler or 0 if none was set.

 QXmlDTDHandlerInterface DTDHandler()
          

Returns the DTD handler or 0 if none was set.

 QXmlEntityResolverInterface entityResolver()
          

Returns the entity resolver or 0 if none was set.

 QXmlErrorHandlerInterface errorHandler()
          

Returns the error handler or 0 if none is set.

 boolean feature(java.lang.String name)
          Equivalent to feature(name, 0).
static QXmlSimpleReader fromNativePointer(QNativePointer nativePointer)
          This function returns the QXmlSimpleReader instance pointed to by nativePointer
 boolean hasFeature(java.lang.String name)
          

Returns true if the reader has the feature called name; otherwise returns false.

 boolean hasProperty(java.lang.String name)
          

Returns true if the reader has the property name; otherwise returns false.

 QXmlLexicalHandlerInterface lexicalHandler()
          

Returns the lexical handler or 0 if none was set.

 boolean parse(QXmlInputSource input)
          

Reads an XML document from input and parses it.

 boolean parse(QXmlInputSource input, boolean incremental)
          Reads an XML document from input and parses it.
 boolean parseContinue()
          Continues incremental parsing, taking input from the QXmlInputSource that was specified with the most recent call to parse.
 void setContentHandler(QXmlContentHandlerInterface handler)
          

Sets the content handler to handler.

 void setDeclHandler(QXmlDeclHandlerInterface handler)
          

Sets the declaration handler to handler.

 void setDTDHandler(QXmlDTDHandlerInterface handler)
          

Sets the DTD handler to handler.

 void setEntityResolver(QXmlEntityResolverInterface handler)
          

Sets the entity resolver to handler.

 void setErrorHandler(QXmlErrorHandlerInterface handler)
          

Sets the error handler to handler.

 void setFeature(java.lang.String name, boolean value)
          Turns on the feature name if value is true; otherwise turns it off.
 void setLexicalHandler(QXmlLexicalHandlerInterface handler)
          

Sets the lexical handler to handler.

 
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
 

Constructor Detail

QXmlSimpleReader

public QXmlSimpleReader()

Constructs a simple XML reader.

Method Detail

DTDHandler

public QXmlDTDHandlerInterface DTDHandler()

Returns the DTD handler or 0 if none was set.

Specified by:
DTDHandler in class QXmlReader
See Also:
setDTDHandler

contentHandler

public QXmlContentHandlerInterface contentHandler()

Returns the content handler or 0 if none was set.

Specified by:
contentHandler in class QXmlReader
See Also:
setContentHandler

declHandler

public QXmlDeclHandlerInterface declHandler()

Returns the declaration handler or 0 if none was set.

Specified by:
declHandler in class QXmlReader
See Also:
setDeclHandler

entityResolver

public QXmlEntityResolverInterface entityResolver()

Returns the entity resolver or 0 if none was set.

Specified by:
entityResolver in class QXmlReader
See Also:
setEntityResolver

errorHandler

public QXmlErrorHandlerInterface errorHandler()

Returns the error handler or 0 if none is set.

Specified by:
errorHandler in class QXmlReader
See Also:
setErrorHandler

feature

public boolean feature(java.lang.String name)

Equivalent to feature(name, 0).

Specified by:
feature in class QXmlReader
See Also:
setFeature

hasFeature

public boolean hasFeature(java.lang.String name)

Returns true if the reader has the feature called name; otherwise returns false.

Specified by:
hasFeature in class QXmlReader
See Also:
feature, setFeature

hasProperty

public boolean hasProperty(java.lang.String name)

Returns true if the reader has the property name; otherwise returns false.

Specified by:
hasProperty in class QXmlReader
See Also:
property, setProperty

lexicalHandler

public QXmlLexicalHandlerInterface lexicalHandler()

Returns the lexical handler or 0 if none was set.

Specified by:
lexicalHandler in class QXmlReader
See Also:
setLexicalHandler

parse

public boolean parse(QXmlInputSource input,
                     boolean incremental)

Reads an XML document from input and parses it. Returns true if the parsing is completed successfully; otherwise returns false, indicating that an error occurred.

If incremental is false, this function will return false if the XML file is not read completely. The parsing cannot be continued in this case.

If incremental is true, the parser does not return false if it reaches the end of the input before reaching the end of the XML file. Instead, it stores the state of the parser so that parsing can be continued later when more data is available. In such a case, you can use the function parseContinue to continue with parsing. This class stores a pointer to the input source input and the parseContinue function tries to read from that input source. Therefore, you should not delete the input source input until you no longer need to call parseContinue.

If this function is called with incremental set to true while an incremental parse is in progress, a new parsing session will be started, and the previous session will be lost.

See Also:
parseContinue, QTcpSocket

parse

public boolean parse(QXmlInputSource input)

Reads an XML document from input and parses it. Returns true if the parsing was successful; otherwise returns false.

Specified by:
parse in class QXmlReader

parseContinue

public boolean parseContinue()

Continues incremental parsing, taking input from the QXmlInputSource that was specified with the most recent call to parse. To use this function, you must have called parse with the incremental argument set to true.

Returns false if a parsing error occurs; otherwise returns true, even if the end of the XML file has not been reached. You can continue parsing at a later stage by calling this function again when there is more data available to parse.

Calling this function when there is no data available in the input source indicates to the reader that the end of the XML file has been reached. If the input supplied up to this point was not well-formed then a parsing error occurs, and false is returned. If the input supplied was well-formed, true is returned. It is important to end the input in this way because it allows you to reuse the reader to parse other XML files.

Calling this function after the end of file has been reached, but without available data will cause false to be returned whether the previous input was well-formed or not.

See Also:
parse, QXmlInputSource::data, QXmlInputSource::next

setContentHandler

public void setContentHandler(QXmlContentHandlerInterface handler)

Sets the content handler to handler.

Specified by:
setContentHandler in class QXmlReader
See Also:
contentHandler

setDTDHandler

public void setDTDHandler(QXmlDTDHandlerInterface handler)

Sets the DTD handler to handler.

Specified by:
setDTDHandler in class QXmlReader
See Also:
DTDHandler

setDeclHandler

public void setDeclHandler(QXmlDeclHandlerInterface handler)

Sets the declaration handler to handler.

Specified by:
setDeclHandler in class QXmlReader
See Also:
declHandler

setEntityResolver

public void setEntityResolver(QXmlEntityResolverInterface handler)

Sets the entity resolver to handler.

Specified by:
setEntityResolver in class QXmlReader
See Also:
entityResolver

setErrorHandler

public void setErrorHandler(QXmlErrorHandlerInterface handler)

Sets the error handler to handler. Clears the error handler if handler is 0.

Specified by:
setErrorHandler in class QXmlReader
See Also:
errorHandler

setFeature

public void setFeature(java.lang.String name,
                       boolean value)

Turns on the feature name if value is true; otherwise turns it off.

The name parameter must be one of the following strings:

FeatureDefaultNotes
http://xml.org/sax/features/namespacestrueIf enabled, namespaces are reported to the content handler.
http://xml.org/sax/features/namespace-prefixesfalseIf enabled, the original prefixed names and attributes used for namespace declarations are reported.
http://trolltech.com/xml/features/report-whitespace-only-CharDatatrueIf enabled, CharData that consist of only whitespace characters are reported using QXmlContentHandler::characters(). If disabled, whitespace is silently discarded.
http://trolltech.com/xml/features/report-start-end-entityfalseIf enabled, the parser reports QXmlContentHandler::startEntity() and QXmlContentHandler::endEntity() events, so character data might be reported in chunks. If disabled, the parser does not report these events, but silently substitutes the entities, and reports the character data in one chunk.

Specified by:
setFeature in class QXmlReader
See Also:
feature, hasFeature, Features

setLexicalHandler

public void setLexicalHandler(QXmlLexicalHandlerInterface handler)

Sets the lexical handler to handler.

Specified by:
setLexicalHandler in class QXmlReader
See Also:
lexicalHandler

fromNativePointer

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

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

Qt Jambi Home