include/unotools/confignode.hxx

   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 INCLUDED_UNOTOOLS_CONFIGNODE_HXX
  20 #define INCLUDED_UNOTOOLS_CONFIGNODE_HXX
  21
  22 #include <unotools/unotoolsdllapi.h>
  23 #include <com/sun/star/container/XHierarchicalNameAccess.hpp>
  24 #include <com/sun/star/container/XNameAccess.hpp>
  25 #include <com/sun/star/container/XNameContainer.hpp>
  26 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  27 #include <com/sun/star/util/XChangesBatch.hpp>
  28 #include <com/sun/star/uno/XComponentContext.hpp>
  29 #include <unotools/eventlisteneradapter.hxx>
  30
  31 namespace comphelper
  32 {
  33     class ComponentContext;
  34 }
  35
  36 namespace utl
  37 {
  38
  39     //= OConfigurationNode
  40
  41     class OConfigurationTreeRoot;
  42     /** a small wrapper around a configuration node.<p/>
  43         Nodes in the terminology used herein are <em>inner</em> nodes of a configuration
  44         tree, which means <em>no leafs</em>.
  45     */
  46     class UNOTOOLS_DLLPUBLIC OConfigurationNode : public ::utl::OEventListenerAdapter
  47     {
  48     private:
  49         ::com::sun::star::uno::Reference< ::com::sun::star::container::XHierarchicalNameAccess >
  50                     m_xHierarchyAccess;     /// accessing children grandchildren (mandatory interface of our UNO object)
  51         ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >
  52                     m_xDirectAccess;        /// accessing children  (mandatory interface of our UNO object)
  53         ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameReplace >
  54                     m_xReplaceAccess;       /// replacing child values
  55         ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameContainer >
  56                     m_xContainerAccess;     /// modifying set nodes  (optional interface of our UNO object)
  57         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
  58                     m_xDummy;
  59         bool    m_bEscapeNames;         /// escape names before accessing children ?
  60
  61         OUString
  62                     m_sCompletePath;
  63
  64         OConfigurationNode  insertNode(const OUString& _rName,const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _xNode) const throw();
  65
  66     protected:
  67         /// constructs a node object with an interface representing a node
  68         OConfigurationNode(
  69             const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxNode
  70         );
  71
  72         const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >&
  73             getUNONode() const { return m_xDirectAccess; }
  74
  75     public:
  76         /// constructs an empty and invalid node object
  77         OConfigurationNode() :m_bEscapeNames(false) { }
  78         /// copy ctor
  79         OConfigurationNode(const OConfigurationNode& _rSource);
  80
  81         /// assigment
  82         const OConfigurationNode& operator=(const OConfigurationNode& _rSource);
  83
  84         /// dtor
  85         virtual ~OConfigurationNode() {}
  86
  87         /// returns the local name of the node
  88         OUString     getLocalName() const;
  89
  90         /// returns the fully qualified path of the node
  91         OUString     getNodePath() const;
  92
  93         /** open a sub node
  94             @param      _rPath      access path of the to-be-opened sub node. May be a hierarchical path.
  95         */
  96         OConfigurationNode  openNode(const OUString& _rPath) const throw();
  97
  98         OConfigurationNode  openNode( const sal_Char* _pAsciiPath ) const
  99         {
 100             return openNode( OUString::createFromAscii( _pAsciiPath ) );
 101         }
 102
 103         /** create a new child node
 104
 105             If the object represents a set node, this method may be used to create a new child. For non-set-nodes, the
 106             method will fail.<br/>
 107             Unless the respective operations on the pure configuration API, the to-be-created node immediately
 108             becomes a part of it's hierarchy, no explicit insertion is necessary.
 109             @param      _rName      name for the new child. Must be level-1-depth.
 110         */
 111         OConfigurationNode  createNode(const OUString& _rName) const throw();
 112
 113         OConfigurationNode  createNode( const sal_Char* _pAsciiName ) const
 114         {
 115             return createNode( OUString::createFromAscii( _pAsciiName ) );
 116         }
 117
 118         /** remove an existent child nod
 119
 120             If the object represents a set node, this method may be used to delete an existent child. For non-set-nodes,
 121             the method will fail.
 122         */
 123         bool            removeNode(const OUString& _rName) const throw();
 124
 125         bool            removeNode( const sal_Char* _pAsciiName ) const
 126         {
 127             return removeNode( OUString::createFromAscii( _pAsciiName ) );
 128         }
 129
 130         /** retrieves the content of a descendant
 131
 132             the returned value may contain anything from an interface (if <arg>_rPath</arg> refers to inner node of
 133             the configuration tree) to any explicit value (e.g. string, integer) or even void.<br/>
 134             Unfortunately, this implies that if a void value is returned, you won't have a clue if this means
 135             "the path does not exist" (besides the assertion made :), or if the value is really void.
 136         */
 137         ::com::sun::star::uno::Any
 138                             getNodeValue(const OUString& _rPath) const throw();
 139
 140         ::com::sun::star::uno::Any
 141                             getNodeValue( const sal_Char* _pAsciiPath ) const
 142         {
 143             return getNodeValue( OUString::createFromAscii( _pAsciiPath ) );
 144         }
 145
 146         /** write a node value<p/>
 147             The value given is written into the node specified by the given relative path.<br/>
 148             In opposite to <method>getNodeValue</method>, _rName must refer to a leaf in the configuration tree, not an inner
 149             node.
 150             @return     sal_True if and only if the write was successful.
 151         */
 152         bool            setNodeValue(const OUString& _rPath, const ::com::sun::star::uno::Any& _rValue) const throw();
 153
 154         bool            setNodeValue( const sal_Char* _pAsciiPath, const ::com::sun::star::uno::Any& _rValue ) const
 155         {
 156             return setNodeValue( OUString::createFromAscii( _pAsciiPath ), _rValue );
 157         }
 158
 159         /// return the names of the existing children
 160         ::com::sun::star::uno::Sequence< OUString >
 161                             getNodeNames() const throw();
 162
 163         /** enables or disables name escaping when accessing direct children<p/>
 164             Escaping is disabled by default, usually you enable it for set nodes (e.g. with calling setEscape(isSetNode)).
 165             Once escaping is enabled, you should not access indirect children (e.g. openNode("child/grandchild"), 'cause
 166             escaping for such names may not be supported by the underlying API objects.
 167             @see getEscape
 168         */
 169         void        setEscape(bool _bEnable = true);
 170         /** get the flag specifying the current escape behaviour
 171             @see setEscape
 172         */
 173         bool    getEscape() const { return m_bEscapeNames; }
 174
 175         /// invalidate the object
 176         virtual void clear() throw();
 177
 178         // meta information about the node
 179
 180         /// checks whether or not the object represents a set node.
 181         bool isSetNode() const;
 182
 183         /// checks whether or not a direct child with a given name exists
 184         bool hasByName(const OUString& _rName) const throw();
 185         bool hasByName( const sal_Char* _pAsciiName ) const { return hasByName( OUString::createFromAscii( _pAsciiName ) ); }
 186
 187         /// checks whether or not a descendent (no matter if direct or indirect) with the given name exists
 188         bool hasByHierarchicalName( const OUString& _rName ) const throw();
 189         bool hasByHierarchicalName( const sal_Char* _pAsciiName ) const { return hasByHierarchicalName( OUString::createFromAscii( _pAsciiName ) ); }
 190
 191         /// check if the objects represents a valid configuration node
 192         bool isValid() const { return m_xHierarchyAccess.is(); }
 193
 194         /// check whether the object is read-only of updatable
 195         bool isReadonly() const { return !m_xReplaceAccess.is(); }
 196
 197     protected:
 198         // OEventListenerAdapter
 199         virtual void _disposing( const ::com::sun::star::lang::EventObject& _rSource ) SAL_OVERRIDE;
 200
 201     protected:
 202         enum NAMEORIGIN
 203         {
 204             NO_CONFIGURATION,       /// the name came from a configuration node
 205             NO_CALLER               /// the name came from a client of this class
 206         };
 207         OUString normalizeName(const OUString& _rName, NAMEORIGIN _eOrigin) const;
 208     };
 209
 210     //= OConfigurationTreeRoot
 211
 212     /** a specialized version of a OConfigurationNode, representing the root
 213         of a configuration sub tree<p/>
 214         Only this class is able to commit any changes made any any OConfigurationNode
 215         objects.
 216     */
 217     class UNOTOOLS_DLLPUBLIC OConfigurationTreeRoot : public OConfigurationNode
 218     {
 219         ::com::sun::star::uno::Reference< ::com::sun::star::util::XChangesBatch >
 220                                 m_xCommitter;
 221     protected:
 222         /** ctor for a readonly node
 223         */
 224         OConfigurationTreeRoot(
 225             const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxRootNode
 226         );
 227
 228     public:
 229         /// modes to use when creating a top-level node object
 230         enum CREATION_MODE
 231         {
 232             /// open the node (i.e. sub tree) for read access only
 233             CM_READONLY,
 234             /// open the node (i.e. sub tree) for read and write access, fall back to read-only if write access is not possible
 235             CM_UPDATABLE
 236         };
 237
 238     public:
 239         /** default ctor<p/>
 240             The object constructed here is invalid (i.e. <method>isValid</method> will return sal_False).
 241         */
 242         OConfigurationTreeRoot() :OConfigurationNode() { }
 243
 244         /** creates a configuration tree for the given path in the given mode
 245         */
 246         OConfigurationTreeRoot(
 247             const css::uno::Reference<css::uno::XComponentContext> & i_rContext,
 248             const OUString& i_rNodePath,
 249             const bool i_bUpdatable
 250         );
 251
 252         /// copy ctor
 253         OConfigurationTreeRoot(const OConfigurationTreeRoot& _rSource)
 254             :OConfigurationNode(_rSource), m_xCommitter(_rSource.m_xCommitter) { }
 255
 256         /** open a new top-level configuration node
 257
 258             opens a new node which is the root if an own configuration sub tree. This is what "top level" means: The
 259             node does not have a parent. It does not mean that the node represents a module tree (like org.openoffice.Office.Writer
 260             or such).<br/>
 261             In opposite to <method>createWithServiceFactory</method>, createWithProvider expects a configuration provider
 262             to work with.
 263
 264             @param      _rxConfProvider configuration provider to use when retrieving the node.
 265             @param      _rPath          path to the node the object should represent
 266             @param      _nDepth         depth for node retrieval
 267             @param      _eMode          specifies which privileges should be applied when retrieving the node
 268
 269             @see    createWithServiceFactory
 270         */
 271         static OConfigurationTreeRoot createWithProvider(
 272                 const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxConfProvider,
 273                 const OUString& _rPath,
 274                 sal_Int32 _nDepth = -1,
 275                 CREATION_MODE _eMode = CM_UPDATABLE,
 276                 bool _bLazyWrite = true
 277             );
 278
 279         /** open a new top-level configuration node<p/>
 280             opens a new node which is the root if an own configuration sub tree. This is what "top level" means: The
 281             node does not have a parent. It does not mean that the node represents a module tree (like org.openoffice.Office.Writer
 282             or such).<br/>
 283             In opposite to <method>createWithProvider</method>, createWithProvider expects a service factory. This factory
 284             is used to create a configuration provider, and this provider is used to retrieve the node
 285             @see    createWithProvider
 286             @param      _rxContext      service factory to use to create the configuration provider.
 287             @param      _rPath          path to the node the object should represent
 288             @param      _nDepth         depth for node retrieval
 289             @param      _eMode          specifies which privileges should be applied when retrieving the node
 290         */
 291         static OConfigurationTreeRoot createWithComponentContext(const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >& _rxContext,
 292             const OUString& _rPath, sal_Int32 _nDepth = -1, CREATION_MODE _eMode = CM_UPDATABLE, bool _bLazyWrite = true);
 293
 294         /** tolerant version of the <member>createWithServiceFactory</member>
 295
 296             <p>No assertions are thrown in case of an failure to initialize the configuration service, but once
 297             the configuration could be initialized, errors in the creation of the specific node (e.g. because the
 298             given node path does not exist) are still asserted.</p>
 299         */
 300         static OConfigurationTreeRoot tryCreateWithComponentContext( const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >& rxContext,
 301             const OUString& _rPath, sal_Int32 _nDepth = -1, CREATION_MODE _eMode = CM_UPDATABLE, bool _bLazyWrite = true );
 302
 303         /** commit all changes made on the subtree the object is the root for<p/>
 304             All changes made on any OConfigurationNode object retrieved (maybe indirect) from this root
 305             object are committed when calling this method.
 306             @return     sal_True if and only if the commit was successful
 307         */
 308         bool commit() const throw();
 309
 310         /// invalidate the object
 311         virtual void clear() throw() SAL_OVERRIDE;
 312     };
 313
 314 }   // namespace utl
 315
 316 #endif // INCLUDED_UNOTOOLS_CONFIGNODE_HXX
 317
 318 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */