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