1/************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27#ifndef __com_sun_star_xml_sax_XFastParser_idl__ 28#define __com_sun_star_xml_sax_XFastParser_idl__ 29 30#ifndef __com_sun_star_uno_XInterface_idl__ 31#include <com/sun/star/uno/XInterface.idl> 32#endif 33 34#ifndef __com_sun_star_xml_sax_InputSource_idl__ 35#include <com/sun/star/xml/sax/InputSource.idl> 36#endif 37 38#ifndef __com_sun_star_xml_sax_SAXException_idl__ 39#include <com/sun/star/xml/sax/SAXException.idl> 40#endif 41 42#ifndef __com_sun_star_io_IOException_idl__ 43#include <com/sun/star/io/IOException.idl> 44#endif 45 46#ifndef __com_sun_star_xml_sax_XFastDocumentHandler_idl__ 47#include <com/sun/star/xml/sax/XFastDocumentHandler.idl> 48#endif 49 50#ifndef __com_sun_star_xml_sax_XFastTokenHandler_idl__ 51#include <com/sun/star/xml/sax/XFastTokenHandler.idl> 52#endif 53 54#ifndef __com_sun_star_xml_sax_XErrorHandler_idl__ 55#include <com/sun/star/xml/sax/XErrorHandler.idl> 56#endif 57 58#ifndef __com_sun_star_xml_sax_XDTDHandler_idl__ 59#include <com/sun/star/xml/sax/XDTDHandler.idl> 60#endif 61 62#ifndef __com_sun_star_xml_sax_XEntityResolver_idl__ 63#include <com/sun/star/xml/sax/XEntityResolver.idl> 64#endif 65 66#ifndef __com_sun_star_lang_Locale_idl__ 67#include <com/sun/star/lang/Locale.idl> 68#endif 69 70#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ 71#include <com/sun/star/lang/IllegalArgumentException.idl> 72#endif 73 74//============================================================================= 75 76module com { module sun { module star { module xml { module sax { 77 78//============================================================================= 79 80/** specifies a SAX parser that uses integer values for known xml names 81 (elements, attributes and attribute values). The parser also handles 82 namespaces and allows to have individual contexts for each xml element. 83 84 <p>Before parsing is possible you have to set your 85 <type>XFastDocumentHandler</type> using <member>setFastDocumentHandler</member>. 86 87 <p>Parsing starts with calling <member>parseStream</member>. If the parser 88 finds a valid xml file with the given <type>InputSource</type>, it calls 89 <member>XFastDocumentHandler::startDocument</member> first. 90 91 <p>This parser generates either 'fast' events that use integer token 92 values for namespaces, elements and attributes or 'unknown' events for 93 elements that are unknown. 94 95 <p>A namespace is unknown if the namespace URL was not registered with 96 <member>registerNamespace</member>. 97 98 <p>An element is unknown if no <type>XFastTokenHandler</type> is set 99 or if the <type>XFastTokenHandler</type> does not return a valid 100 identifier for the elements local name. An element is also unknown if 101 the elements local name is known but it uses a namespace that is unknown. 102 103 <p>Setting a <type>XFastTokenHandler</type> with <member>setTokenHandler</member> 104 is optional, but without a <type>XFastTokenHandler</type> you will only 105 get unknown sax events. This can be usefull if you are only interested 106 in the namespace handling and/or the context feature. 107 108 <p>For each element the parser sends a create child element event to the 109 elements parent context by calling 110 <member>XFastContextHandler::createFastChildContext</member> for known 111 elements or <member>XFastContextHandler::createUnknownChildContext</member> 112 for unknown elements. 113 <br>The parent context for the root element is the <type>XFastDocumentHandler</type> 114 itself. 115 116 <p>If the parent context returns an empty reference, no further events for 117 the element and all of its childs are created. 118 119 <p>If a valid context is returned this context gets a start event by a call to 120 <member>XFastContextHandler::startFastElement</member> for known elements or 121 <member>XFastContextHandler::startUnknownElement</member> for unknown elements. 122 123 <p>After processing all its child elements the context gets an end event by a call to 124 <member>XFastContextHandler::endFastElement</member> for known elements or 125 <member>XFastContextHandler::endUnknownElement</member> for unknown elements. 126 127 <p>It is valid to return one instance of <type>XFastContextHandler</type> more 128 than once. It is even possible to only use the <type>XFastDocumentHandler</type> 129 by always returning a reference to itself for each create child context event. 130 131 <p>After the last element is processed the parser generates an end document 132 event at the <type>XFastDocumentHandler</type> by calling 133 <member>XFastDocumentHandler::endDocument</member>. 134 135 @see http://wiki.services.openoffice.org/wiki/FastParser 136*/ 137interface XFastParser: com::sun::star::uno::XInterface 138{ 139 //------------------------------------------------------------------------- 140 /** parses an XML document from a stream. 141 142 <p>Set the desired handlers before calling this method.</p> 143 */ 144 void parseStream( [in] InputSource aInputSource ) 145 raises( SAXException, com::sun::star::io::IOException ); 146 147 //------------------------------------------------------------------------- 148 149 /** Application must register a document event handler to get 150 sax events for the parsed stream. 151 */ 152 void setFastDocumentHandler( [in] XFastDocumentHandler Handler ); 153 154 //------------------------------------------------------------------------- 155 156 /** must be registered to translate known xml names to integer tokens. 157 */ 158 void setTokenHandler( [in] XFastTokenHandler Handler ); 159 160 //------------------------------------------------------------------------- 161 162 /** registers a known namespace url with the given integer token.<br> 163 @param NamespaceToken 164 an integer token that must be greater than FastToken::NAMESPACE. 165 */ 166 void registerNamespace( [in] string NamespaceURL, [in] long NamespaceToken ) 167 raises( com::sun::star::lang::IllegalArgumentException ); 168 169 //------------------------------------------------------------------------- 170 /** allows an application to register an error event handler. 171 172 <p>Note that the error handler can throw an exception when an error or 173 warning occurs. Note that an exception is thrown by the parser when 174 an unrecoverable (fatal) error occurs.</p> 175 */ 176 void setErrorHandler( [in] XErrorHandler Handler ); 177 178 //------------------------------------------------------------------------- 179 /** allows an application to register a DTD-Handler. 180 */ 181 void setEntityResolver( [in] XEntityResolver Resolver ); 182 183 //------------------------------------------------------------------------- 184 /** sets a locale specified for localization of warnings and error messages. 185 186 <p>Set the language of the error messages. Useful when the parsing 187 errors will be presented to the user.</p> 188 */ 189 void setLocale( [in] com::sun::star::lang::Locale locale ); 190}; 191 192//============================================================================= 193 194}; }; }; }; }; 195 196#endif 197