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