Latest revision as of 21:57, 24 March 2010

DRAFT

See also FastParser, XFastAttributeList

Abstract

A XFastContextHandler returned for an xml element will get the start, end and character events for that xml element. If will also get create child events for direct child elements. You can also return an empty reference. The parser will not send any events for this element and all its child elements. This is a simple way to skip elements that are not needed for import.

IDL

module com {  module sun {  module star {  module xml {  module sax {  
 
/** receives notification of sax document events from a
	<type>XFastParser</type>.
	
	@see XFastDocumentHandler
 */
interface XFastContextHandler: com::sun::star::uno::XInterface
{ 
	/** receives notification of the beginning of an element .

		@param Element
			contains the integer token from the <type>XFastTokenHandler</type>
			registered at the <type>XFastParser</type>.<br>

			If the element has a namespace that was registered with the
			<type>XFastParser</type>, <param>Element</param> contains the integer
			token of the elements local name from the <type>XFastTokenHandler</type>
			and the integer token of the namespace combined with an arithmetic
			<b>or</b> operation.

		@param Attribs
			Contains a <type>XFastAttrbitueList</type> to access the attributes
			from the element.

	*/
	void startFastElement( [in] long Element, [in] XFastAttributeList Attribs ) 
			raises( com::sun::star::xml::sax::SAXException ); 

	/** receives notification of the beginning of an unknown element .

		@param Namespace
			contains the namespace url (not the prefix!) of this element.
		@param Name
			contains the elements local name.
		@param Attribs
			Contains a <type>XFastAttrbitueList</type> to access the attributes
			from the element.
	 */
	void startUnknownElement( [in] string Namespace, [in] string Name, [in] XFastAttributeList Attribs ) 
			raises( com::sun::star::xml::sax::SAXException ); 

	/** receives notification of the end of an known element.
		@see startFastElement
	 */
	void endFastElement( [in] long Element ) 
			raises( com::sun::star::xml::sax::SAXException ); 

	/** receives notification of the end of an kown element.
		@see startUnknownElement
	 */
	void endUnknownElement( [in] string Namespace, [in] string Name ) 
			raises( com::sun::star::xml::sax::SAXException ); 
 
	/** receives notification of the beginning of a known child element.

		@param Element
			contains the integer token from the <type>XFastTokenHandler</type>
			registered at the <type>XFastParser</type>.

			<br>If the element has a namespace that was registered with the
			<type>XFastParser</type>, <param>Element</param> contains the
			integer token of the elements local name from the
			<type>XFastTokenHandler</type> and the integer token of the
			namespace combined with an arithmetic <b>or</b> operation.

		@param Attribs
			Contains a <type>XFastAttrbitueList</type> to access the attributes
			from the element.
	 */
	XFastContextHandler createFastChildContext( [in] long Element, [in] XFastAttributeList Attribs ) 
			raises( com::sun::star::xml::sax::SAXException ); 

	/** receives notification of the beginning of a unknown child element .

		@param Namespace
			contains the namespace url (not the prefix!) of this element.
		@param Name
			contains the elements local name.
		@param Attribs
			Contains a <type>XFastAttrbitueList</type> to access the attributes
			the element.
	 */
	XFastContextHandler createUnknownChildContext( [in] string Namespace, [in] string Name, [in] XFastAttributeList Attribs ) 
			raises( com::sun::star::xml::sax::SAXException ); 

	/** receives notification of character data.
	 */
	void characters( [in] string aChars ) 
			raises( com::sun::star::xml::sax::SAXException ); 
  }; 

}; }; }; }; };  

About fast and unknown events

Like the old sax document handler the fast sax context handles the start, end and characters events. Additionally it handles the new create child event. Except for the characters event there is a 'fast' and an 'unknown' version for each one:

The fast versions are called for elements where

• the local name is known to the XFastTokenHandler registered at the FastParser
• if the element has a namespace, its url was registered at the FastParser

if a fast element also has a namespace, the identifier of the namespace is combined with the local name identifier with the arithmetically or operation. This enables switch case operations on elements with namespaces, for example:

void AnimationNodeContext::startFastElement( sal_Int32 Element, const Reference< XFastAttributeList >& Attribs )
{
	switch( Element )
	{
	case NMSP_ANIMATION|XML_PAR:
		...
		break;
	case NMSP_SMIL|XML_NODE:
		...
		break;
	}
}

For unknown elements or elements with unknown namespaces, the unknown methods are called which uses strings for namespace url and local names.