LCOV - code coverage report
Current view: top level - include/unotools - confignode.hxx (source / functions) Hit Total Coverage
Test: commit 10e77ab3ff6f4314137acd6e2702a6e5c1ce1fae Lines: 9 15 60.0 %
Date: 2014-11-03 Functions: 9 15 60.0 %
Legend: Lines: hit not hit

          Line data    Source code
       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           0 :             getUNONode() const { return m_xDirectAccess; }
      74             : 
      75             :     public:
      76             :         /// constructs an empty and invalid node object
      77         472 :         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       14870 :         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           0 :         OConfigurationNode  openNode( const sal_Char* _pAsciiPath ) const
      99             :         {
     100           0 :             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       38876 :                             getNodeValue( const sal_Char* _pAsciiPath ) const
     142             :         {
     143       38876 :             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           0 :         bool            setNodeValue( const sal_Char* _pAsciiPath, const ::com::sun::star::uno::Any& _rValue ) const
     155             :         {
     156           0 :             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       87428 :         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           0 :         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       23292 :         bool isValid() const { return m_xHierarchyAccess.is(); }
     193             : 
     194             :         /// check whether the object is read-only of updatable
     195         172 :         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        2778 :     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         106 :         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: */

Generated by: LCOV version 1.10