offapi/com/sun/star/xml/sax/XFastParser.idl

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