1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
|
/*************************************************************************
*
* OpenOffice.org - a multi-platform office productivity suite
*
* $RCSfile: confignode.hxx,v $
*
* $Revision: 1.6 $
*
* last change: $Author: rt $ $Date: 2005-09-09 09:28:56 $
*
* The Contents of this file are made available subject to
* the terms of GNU Lesser General Public License Version 2.1.
*
*
* GNU Lesser General Public License Version 2.1
* =============================================
* Copyright 2005 by Sun Microsystems, Inc.
* 901 San Antonio Road, Palo Alto, CA 94303, USA
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License version 2.1, as published by the Free Software Foundation.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston,
* MA 02111-1307 USA
*
************************************************************************/
#ifndef INCLUDED_UNOTOOLSDLLAPI_H
#include "unotools/unotoolsdllapi.h"
#endif
#ifndef _UNOTOOLS_CONFIGNODE_HXX_
#define _UNOTOOLS_CONFIGNODE_HXX_
#ifndef _COM_SUN_STAR_CONTAINER_XHIERARCHICALNAMEACCESS_HPP_
#include <com/sun/star/container/XHierarchicalNameAccess.hpp>
#endif
#ifndef _COM_SUN_STAR_CONTAINER_XNAMEACCESS_HPP_
#include <com/sun/star/container/XNameAccess.hpp>
#endif
#ifndef _COM_SUN_STAR_CONTAINER_XNAMECONTAINER_HPP_
#include <com/sun/star/container/XNameContainer.hpp>
#endif
#ifndef _COM_SUN_STAR_LANG_XMULTISERVICEFACTORY_HPP_
#include <com/sun/star/lang/XMultiServiceFactory.hpp>
#endif
#ifndef _COM_SUN_STAR_UTIL_XCHANGESBATCH_HPP_
#include <com/sun/star/util/XChangesBatch.hpp>
#endif
#ifndef _UNOTOOLS_EVENTLISTENERADAPTER_HXX_
#include <unotools/eventlisteneradapter.hxx>
#endif
//........................................................................
namespace utl
{
//........................................................................
//========================================================================
//= OConfigurationNode
//========================================================================
class OConfigurationTreeRoot;
/** a small wrapper around a configuration node.<p/>
Nodes in the terminology used herein are <em>inner</em> nodes of a configuration
tree, which means <em>no leafs</em>.
*/
class UNOTOOLS_DLLPUBLIC OConfigurationNode : public ::utl::OEventListenerAdapter
{
private:
::com::sun::star::uno::Reference< ::com::sun::star::container::XHierarchicalNameAccess >
m_xHierarchyAccess; /// accessing children grandchildren (mandatory interface of our UNO object)
::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >
m_xDirectAccess; /// accessing children (mandatory interface of our UNO object)
::com::sun::star::uno::Reference< ::com::sun::star::container::XNameReplace >
m_xReplaceAccess; /// replacing child values
::com::sun::star::uno::Reference< ::com::sun::star::container::XNameContainer >
m_xContainerAccess; /// modifying set nodes (optional interface of our UNO object)
::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >
m_xProvider; /// the configuration provider which supplied the nodes of the hierarchy we're a part of
sal_Bool m_bEscapeNames; /// escape names before accessing children ?
::rtl::OUString
m_sCompletePath;
OConfigurationNode insertNode(const ::rtl::OUString& _rName,const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _xNode) const throw();
protected:
/// constructs a node object with an interface representing a node
OConfigurationNode(
const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxNode,
const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxProvider);
public:
/// constructs an empty and invalid node object
OConfigurationNode() :m_bEscapeNames(sal_False) { }
/// copy ctor
OConfigurationNode(const OConfigurationNode& _rSource);
/// assigment
const OConfigurationNode& operator=(const OConfigurationNode& _rSource);
/// dtor
~OConfigurationNode();
/** open a sub node
@param _rPath access path of the to-be-opened sub node. May be a hierarchical path.
*/
OConfigurationNode openNode(const ::rtl::OUString& _rPath) const throw();
/** create a new child node<p/>
If the object represents a set node, this method may be used to create a new child. For non-set-nodes, the
method will fail.<br/>
Unless the respective operations on the pure configuration API, the to-be-created node immediately
becomes a part of it's hierarchy, no explicit insertion is necessary.
@param _rName name for the new child. Must be level-1-depth.
*/
OConfigurationNode createNode(const ::rtl::OUString& _rName) const throw();
/** appends a node under a new name <p/>
If the object represents a set node, this method may be used to create a new child. For non-set-nodes, the
method will fail.<br/>
Unless the respective operations on the pure configuration API, the to-be-created node immediately
becomes a part of it's hierarchy, no explicit insertion is necessary.
@param _rName name for the new child. Must be level-1-depth.
@param _aNewNode the node which should be appended
*/
OConfigurationNode appendNode(const ::rtl::OUString& _rName,const OConfigurationNode& _aNewNode) const throw();
/** remove an existent child node<p/>
If the object represents a set node, this method may be used to delete an existent child. For non-set-nodes,
the method will fail.
*/
sal_Bool removeNode(const ::rtl::OUString& _rName) const throw();
/** retrieves the content of a descendant<p/>
the returned value may contain anything from an interface (if <arg>_rPath</arg> refers to inner node of
the configuration tree) to any explicit value (e.g. string, integer) or even void.<br/>
Unfortunately, this implies that if a void value is returned, you won't have a clue if this means
"the path does not exist" (besides the assertion made :), or if the value is really void.
*/
::com::sun::star::uno::Any
getNodeValue(const ::rtl::OUString& _rPath) const throw();
/** write a node value<p/>
The value given is written into the node specified by the given relative path.<br/>
In opposite to <method>getNodeValue</method>, _rName must refer to a leaf in the configuration tree, not an inner
node.
@return sal_True if and only if the write was successfull.
*/
sal_Bool setNodeValue(const ::rtl::OUString& _rPath, const ::com::sun::star::uno::Any& _rValue) const throw();
/// return the names of the existing children
::com::sun::star::uno::Sequence< ::rtl::OUString >
getNodeNames() const throw();
/** enables or disables name escaping when accessing direct children<p/>
Escaping is disabled by default, usually you enable it for set nodes (e.g. with calling setEscape(isSetNode)).
Once escaping is enabled, you should not access indirect children (e.g. openNode("child/grandchild"), 'cause
escaping for such names may not be supported by the underlying API objects.
@see getEscape
*/
void setEscape(sal_Bool _bEnable = sal_True);
/** get the flag specifying the current escape behaviour
@see setEscape
*/
sal_Bool getEscape() const { return m_bEscapeNames; }
/** clone the object, creating a new hierarchy where the root represents the same node as the object
where this method is called does.<p/>
The new hierarchy does not share any updates with the one the object is a part of, i.e. any changes made
in the existing hierarchy are not visible to the newly created one until committed (and vice versa).
@param _rRoot out parameter. upon return, contains the object representing the root of the new hierarchy.
*/
OConfigurationTreeRoot cloneAsRoot() const throw();
/// invalidate the object
virtual void clear() throw();
// -----------------------
// meta informations about the node
/// checks whether or not the object represents a set node.
sal_Bool isSetNode() const;
/// checks whether or not a direct child with a given name exists
sal_Bool hasByName(const ::rtl::OUString& _rName) const throw();
/// checks whether or not a descendent (no matter if direct or indirect) with the given name exists
sal_Bool hasByHierarchicalName( const ::rtl::OUString& _rName ) const throw();
/// check if the objects represents a valid configuration node
sal_Bool isValid() const { return m_xHierarchyAccess.is(); }
/// check whether the object is read-only of updatable
sal_Bool isReadonly() const { return !m_xReplaceAccess.is(); }
protected:
// OEventListenerAdapter
virtual void _disposing( const ::com::sun::star::lang::EventObject& _rSource );
protected:
enum NAMEORIGIN
{
NO_CONFIGURATION, /// the name came from a configuration node
NO_CALLER /// the name came from a client of this class
};
::rtl::OUString normalizeName(const ::rtl::OUString& _rName, NAMEORIGIN _eOrigin) const;
};
//========================================================================
//= OConfigurationTreeRoot
//========================================================================
/** a specialized version of a OConfigurationNode, representing the root
of a configuration sub tree<p/>
Only this class is able to commit any changes made any any OConfigurationNode
objects.
*/
class UNOTOOLS_DLLPUBLIC OConfigurationTreeRoot : public OConfigurationNode
{
::com::sun::star::uno::Reference< ::com::sun::star::util::XChangesBatch >
m_xCommitter;
protected:
/** ctor<p/>
*/
OConfigurationTreeRoot(
const ::com::sun::star::uno::Reference< ::com::sun::star::util::XChangesBatch >& _rxRootNode,
const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxProvider);
/** ctor for a readonly node
*/
OConfigurationTreeRoot(
const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxRootNode,
const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxProvider);
public:
/// modes to used when creating a top-level node object
enum CREATION_MODE
{
CM_READONLY, /// open the node (i.e. sub tree) for read access only
CM_UPDATABLE, /// open the node (i.e. sub tree) for read and write access
CM_PREFER_UPDATABLE /// open the node (i.e. sub tree) for read and write access, if this fails, open it for read acces
};
public:
/** default ctor<p/>
The object constructed here is invalid (i.e. <method>isValid</method> will return sal_False).
*/
OConfigurationTreeRoot() :OConfigurationNode() { }
/// copy ctor
OConfigurationTreeRoot(const OConfigurationTreeRoot& _rSource)
:OConfigurationNode(_rSource), m_xCommitter(_rSource.m_xCommitter) { }
/** open a new top-level configuration node<p/>
opens a new node which is the root if an own configuration sub tree. This is what "top level" means: The
node does not have a parent. It does not mean that the node represents a module tree (like org.openoffice.Office.Writer
or such).<br/>
In opposite to <method>createWithServiceFactory</method>, createWithProvider expects a configuration provider
to work with.
@see createWithServiceFactory
@param _rxConfProvider configuration provider to use when retrieving the node.
@param _rPath path to the node the object should represent
@param _nDepth depth for node retrieval
@param _eMode specifies which privileges should be applied when retrieving the node
*/
static OConfigurationTreeRoot createWithProvider(const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxConfProvider,
const ::rtl::OUString& _rPath, sal_Int32 _nDepth = -1, CREATION_MODE _eMode = CM_PREFER_UPDATABLE, sal_Bool _bLazyWrite = sal_True);
/** open a new top-level configuration node<p/>
opens a new node which is the root if an own configuration sub tree. This is what "top level" means: The
node does not have a parent. It does not mean that the node represents a module tree (like org.openoffice.Office.Writer
or such).<br/>
In opposite to <method>createWithProvider</method>, createWithProvider expects a service factory. This factory
is used to create a configuration provider, and this provider is used to retrieve the node
@see createWithProvider
@param _rxORB service factory to use to create the configuration provider.
@param _rPath path to the node the object should represent
@param _nDepth depth for node retrieval
@param _eMode specifies which privileges should be applied when retrieving the node
*/
static OConfigurationTreeRoot createWithServiceFactory(const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxORB,
const ::rtl::OUString& _rPath, sal_Int32 _nDepth = -1, CREATION_MODE _eMode = CM_PREFER_UPDATABLE, sal_Bool _bLazyWrite = sal_True);
/** tolerant version of the <member>createWithServiceFactory</member>
<p>No assertions are thrown in case of an failure to initialize the configuration service, but once
the configuration could be initialized, errors in the creation of the specific node (e.g. because the
given node path does not exist) are still asserted.</p>
*/
static OConfigurationTreeRoot tryCreateWithServiceFactory( const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxORB,
const ::rtl::OUString& _rPath, sal_Int32 _nDepth = -1, CREATION_MODE _eMode = CM_PREFER_UPDATABLE, sal_Bool _bLazyWrite = sal_True );
/** commit all changes made on the subtree the object is the root for<p/>
All changes made on any <type>OConfigurationNode</type> object retrieved (maybe indirect) from this root
object are committed when calling this method.
@return sal_True if and only if the commit was successfull
*/
sal_Bool commit() const throw();
/// invalidate the object
virtual void clear() throw();
};
//........................................................................
} // namespace utl
//........................................................................
#endif // _UNOTOOLS_CONFIGNODE_HXX_
/*************************************************************************
* history:
* $Log: not supported by cvs2svn $
* Revision 1.5.34.1 2005/09/05 14:00:51 rt
* #i54170# Change license header: remove SISSL
*
* Revision 1.5 2005/04/13 12:24:31 obo
* INTEGRATION: CWS visibility03 (1.4.182); FILE MERGED
* 2005/02/28 04:33:52 mnicel 1.4.182.1: Issue number: 40092
* Part of visibility work
*
* Revision 1.4.182.1 2005/02/28 04:33:52 mnicel
* Issue number: 40092
* Part of visibility work
*
* Revision 1.4 2002/12/05 09:02:46 fs
* #104427# +tryCreateWithServiceFactory
*
* Revision 1.3 2001/08/21 12:40:00 fs
* #87721# +hasByHierarchicalName
*
* Revision 1.2 2001/07/26 09:13:23 oj
* #89831# new method to append an existing node with different name
*
* Revision 1.1 2001/06/13 16:26:04 fs
* initial checkin - non-UNO wrapper for configuration nodes
*
*
* Revision 1.0 13.06.01 17:04:40 fs
************************************************************************/
|