Language:

The Free and Open Productivity Suite
Apache OpenOffice 4.1.4 released

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


:: com :: sun :: star :: xml :: sax ::

unpublished interface XFastParser
Usage Restrictions
not published
Description
specifies a SAX parser that uses integer values for known xml names (elements, attributes and attribute values). The parser also handles namespaces and allows to have individual contexts for each xml element.

Before parsing is possible you have to set your XFastDocumentHandler using setFastDocumentHandler.

Parsing starts with calling parseStream. If the parser finds a valid xml file with the given InputSource, it calls XFastDocumentHandler::startDocument first.

This parser generates either 'fast' events that use integer token values for namespaces, elements and attributes or 'unknown' events for elements that are unknown.

A namespace is unknown if the namespace URL was not registered with registerNamespace.

An element is unknown if no XFastTokenHandler is set or if the XFastTokenHandler does not return a valid identifier for the elements local name. An element is also unknown if the elements local name is known but it uses a namespace that is unknown.

Setting a XFastTokenHandler with setTokenHandler is optional, but without a XFastTokenHandler you will only get unknown sax events. This can be usefull if you are only interested in the namespace handling and/or the context feature.

For each element the parser sends a create child element event to the elements parent context by calling XFastContextHandler::createFastChildContext for known elements or XFastContextHandler::createUnknownChildContext for unknown elements.
The parent context for the root element is the XFastDocumentHandler itself.

If the parent context returns an empty reference, no further events for the element and all of its childs are created.

If a valid context is returned this context gets a start event by a call to XFastContextHandler::startFastElement for known elements or XFastContextHandler::startUnknownElement for unknown elements.

After processing all its child elements the context gets an end event by a call to XFastContextHandler::endFastElement for known elements or XFastContextHandler::endUnknownElement for unknown elements.

It is valid to return one instance of XFastContextHandler more than once. It is even possible to only use the XFastDocumentHandler by always returning a reference to itself for each create child context event.

After the last element is processed the parser generates an end document event at the XFastDocumentHandler by calling XFastDocumentHandler::endDocument.

See also
http://wiki.services.openoffice.org/wiki/FastParser

Methods' Summary
parseStream parses an XML document from a stream.  
setFastDocumentHandler Application must register a document event handler to get sax events for the parsed stream.  
setTokenHandler must be registered to translate known xml names to integer tokens.  
registerNamespace registers a known namespace url with the given integer token.
 
setErrorHandler allows an application to register an error event handler.  
setEntityResolver allows an application to register a DTD-Handler.  
setLocale sets a locale specified for localization of warnings and error messages.  
Methods' Details
parseStream
void
parseStream( [in] InputSource  aInputSource )
raises( SAXException,
::com::sun::star::io::IOException );

Description
parses an XML document from a stream.

Set the desired handlers before calling this method.

setFastDocumentHandler
void
setFastDocumentHandler( [in] XFastDocumentHandler  Handler );

Description
Application must register a document event handler to get sax events for the parsed stream.
setTokenHandler
void
setTokenHandler( [in] XFastTokenHandler  Handler );

Description
must be registered to translate known xml names to integer tokens.
registerNamespace
void
registerNamespace( [in] string  NamespaceURL,
[in] long  NamespaceToken )
raises( ::com::sun::star::lang::IllegalArgumentException );

Description
registers a known namespace url with the given integer token.
Parameter NamespaceToken
an integer token that must be greater than FastToken::NAMESPACE.
setErrorHandler
void
setErrorHandler( [in] XErrorHandler  Handler );

Description
allows an application to register an error event handler.

Note that the error handler can throw an exception when an error or warning occurs. Note that an exception is thrown by the parser when an unrecoverable (fatal) error occurs.

setEntityResolver
void
setEntityResolver( [in] XEntityResolver  Resolver );

Description
allows an application to register a DTD-Handler.
setLocale
void
setLocale( [in] ::com::sun::star::lang::Locale  locale );

Description
sets a locale specified for localization of warnings and error messages.

Set the language of the error messages. Useful when the parsing errors will be presented to the user.

Top of Page

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache and the Apache feather logo are trademarks of The Apache Software Foundation. OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.