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
  20
  21 module com {  module sun {  module star {  module xml {  module sax {
  22
  23
  24 /** specifies a SAX parser that uses integer values for known XML names
  25     (elements, attributes and attribute values). The parser also handles
  26     namespaces and allows to have individual contexts for each XML element.
  27
  28     <p>Before parsing is possible you have to set your
  29     XFastDocumentHandler using setFastDocumentHandler().
  30
  31     <p>Parsing starts with calling parseStream(). If the parser
  32     finds a valid XML file with the given InputSource, it calls
  33     XFastDocumentHandler::startDocument() first.
  34
  35     <p>This parser generates either "fast" events that use integer token
  36     values for namespaces, elements and attributes or "unknown" events for
  37     elements that are unknown.
  38
  39     <p>A namespace is unknown if the namespace URL was not registered with
  40     registerNamespace().
  41
  42     <p>An element is unknown if no XFastTokenHandler is set
  43     or if the XFastTokenHandler does not return a valid
  44     identifier for the elements local name. An element is also unknown if
  45     the elements local name is known but it uses a namespace that is unknown.
  46
  47     <p>Setting a XFastTokenHandler with setTokenHandler()
  48     is optional, but without a XFastTokenHandler you will only
  49     get unknown sax events. This can be useful if you are only interested
  50     in the namespace handling and/or the context feature.
  51
  52     <p>For each element the parser sends a create child element event to the
  53     elements parent context by calling
  54     XFastContextHandler::createFastChildContext() for known
  55     elements or XFastContextHandler::createUnknownChildContext()
  56     for unknown elements.
  57     <br>The parent context for the root element is the XFastDocumentHandler
  58     itself.
  59
  60     <p>If the parent context returns an empty reference, no further events for
  61     the element and all of its children are created.
  62
  63     <p>If a valid context is returned this context gets a start event by a call to
  64     XFastContextHandler::startFastElement() for known elements or
  65     XFastContextHandler::startUnknownElement() for unknown elements.
  66
  67     <p>After processing all its child elements the context gets an end event by a call to
  68     XFastContextHandler::endFastElement() for known elements or
  69     XFastContextHandler::endUnknownElement() for unknown elements.
  70
  71     <p>It is valid to return one instance of XFastContextHandler more
  72     than once. It is even possible to only use the XFastDocumentHandler
  73     by always returning a reference to itself for each create child context event.
  74
  75     <p>After the last element is processed the parser generates an end document
  76     event at the XFastDocumentHandler by calling
  77     XFastDocumentHandler::endDocument().
  78
  79     @see http://wiki.openoffice.org/wiki/FastParser
  80 */
  81 interface XFastParser: com::sun::star::uno::XInterface
  82 {
  83     /** parses an XML document from a stream.
  84
  85         <p>Set the desired handlers before calling this method.</p>
  86      */
  87     void parseStream( [in] InputSource aInputSource )
  88             raises( SAXException, com::sun::star::io::IOException );
  89
  90
  91     /** Application must register a document event handler to get
  92         sax events for the parsed stream.
  93      */
  94     void setFastDocumentHandler( [in] XFastDocumentHandler Handler );
  95
  96
  97     /** must be registered to translate known XML names to integer tokens.
  98      */
  99     void setTokenHandler( [in] XFastTokenHandler Handler );
 100
 101
 102     /** registers a known namespace url with the given integer token.<br>
 103         @param NamespaceURL the namespace URL.
 104         @param NamespaceToken
 105             an integer token that must be greater than FastToken::NAMESPACE.
 106      */
 107     void registerNamespace( [in] string NamespaceURL, [in] long NamespaceToken )
 108         raises( com::sun::star::lang::IllegalArgumentException );
 109
 110     /** allows an application to register an error event handler.
 111
 112         <p>Note that the error handler can throw an exception when an error or
 113         warning occurs.  Note that an exception is thrown by the parser when
 114         an unrecoverable (fatal) error occurs.</p>
 115      */
 116     void setErrorHandler( [in] XErrorHandler Handler );
 117
 118     /** allows an application to register a DTD-Handler.
 119      */
 120     void setEntityResolver( [in] XEntityResolver Resolver );
 121
 122     /** sets a locale specified for localization of warnings and error messages.
 123
 124         <p>Set the language of the error messages. Useful when the parsing
 125         errors will be presented to the user.</p>
 126      */
 127     void setLocale( [in] com::sun::star::lang::Locale locale );
 128
 129     /** Gets the namespace url string.
 130       */
 131     string getNamespaceURL( [in] string prefix )
 132         raises( com::sun::star::lang::IllegalArgumentException );
 133
 134     /** @since LibreOffice 5.3 */
 135     void setNamespaceHandler( [in] XFastNamespaceHandler Handler);
 136
 137     /**
 138       * Simulate a DTD file.
 139       * Will allow to use customized entity references like &infin; .
 140       * @since LibreOffice 7.1
 141       */
 142     void setCustomEntityNames( [in] sequence< beans::Pair<string,string> > replacements);
 143 };
 144
 145
 146 }; }; }; }; };
 147
 148 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */