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