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