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 0 : 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 0 : 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 0 : getNodeValue( const sal_Char* _pAsciiPath ) const
142 : {
143 0 : 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 0 : 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 0 : bool isValid() const { return m_xHierarchyAccess.is(); }
193 :
194 : /// check whether the object is read-only of updatable
195 0 : 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 0 : 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 0 : 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 0 : OConfigurationTreeRoot(const OConfigurationTreeRoot& _rSource)
254 0 : :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: */
|
