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

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