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