231 lines
8.6 KiB
Text
231 lines
8.6 KiB
Text
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
|
|
/*
|
|
* This file is part of the LibreOffice project.
|
|
*
|
|
* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
*
|
|
* This file incorporates work covered by the following license notice:
|
|
*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed
|
|
* with this work for additional information regarding copyright
|
|
* ownership. The ASF licenses this file to you under the Apache
|
|
* License, Version 2.0 (the "License"); you may not use this file
|
|
* except in compliance with the License. You may obtain a copy of
|
|
* the License at http://www.apache.org/licenses/LICENSE-2.0 .
|
|
*/
|
|
|
|
|
|
module com { module sun { module star { module configuration {
|
|
|
|
/** manages one, or more, complete sets of configuration data and serves as a
|
|
factory for objects that provide access to a subset of the configuration.
|
|
|
|
<p>An implementation is usually obtained from a
|
|
com::sun::star::lang::ServiceManager. The arguments passed to
|
|
com::sun::star::lang::XMultiComponentFactory::createInstanceWithArgumentsAndContext()
|
|
select the configuration data source. Arguments must be provided as
|
|
com::sun::star::beans::NamedValue
|
|
or com::sun::star::beans::PropertyValue.
|
|
If the parameters given are incomplete missing values are taken
|
|
from the context or the environment. If an instance already exists for the
|
|
given set of arguments, the existing instance may be reused.
|
|
In particular, instantiating a provider without explicit arguments to access
|
|
the default configuration data will always yield the same
|
|
com::sun::star::configuration::DefaultProvider object.
|
|
</p>
|
|
<p>Some arguments for
|
|
com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
|
|
may be given default values during creation of this service. In particular
|
|
this applies to the parameters <code>"Locale"</code> and <code>"EnableAsync"</code>.
|
|
</p>
|
|
|
|
@deprecated Use theDefaultProvider instead.
|
|
*/
|
|
published service ConfigurationProvider
|
|
{
|
|
/** allows creating access objects for specific views such as subsets and fragments
|
|
of the configuration.
|
|
|
|
<p>The parameter <var>aServiceSpecifier</var> passed to
|
|
com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
|
|
supports at least the service specifiers
|
|
<code>"com.sun.star.configuration.ConfigurationAccess"</code> and
|
|
<code>"com.sun.star.configuration.ConfigurationUpdateAccess"</code>.
|
|
</p>
|
|
|
|
<p>Using the first of these service specifiers requests a read-only view of
|
|
the configuration.
|
|
The object that is created implements service ConfigurationAccess.
|
|
To reflect its <em>element role</em> as root of the view, it implements
|
|
service AccessRootElement.
|
|
</p>
|
|
|
|
<p>Using the second form requests an updatable view of the configuration.
|
|
The object that is created should implement service
|
|
ConfigurationUpdateAccess. To reflect its <em>element role</em>
|
|
which includes controlling updates for the whole view, it implements
|
|
service UpdateRootElement.
|
|
<BR />If the root element of the view is marked read-only (as indicated
|
|
by com::sun::star::beans::PropertyAttributes::READONLY),
|
|
the implementation may either raise an exception or return a (read-only)
|
|
ConfigurationAccess/AccessRootElement instead.
|
|
</p>
|
|
|
|
<p>The arguments passed to
|
|
com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
|
|
in parameter <var>aArguments</var> specify the view of the configuration that
|
|
should be created. That is, they determine the subset of elements that can be
|
|
accessed starting from the returned object. Each element of the argument
|
|
sequence should be a com::sun::star::beans::PropertyValue
|
|
or a com::sun::star::beans::NamedValue,
|
|
so that the parameters can be identified by name rather than by position.
|
|
</p>
|
|
|
|
<p>What combinations of arguments are supported depends on the service name.
|
|
</p>
|
|
|
|
<p>With both of the standard service-specifiers above, an implementation must
|
|
accept a single argument named <code>nodepath</code> of type `string`.
|
|
This argument must contain the absolute path to an element of the
|
|
configuration. The view that is selected consists of the named element and
|
|
all its descendants.
|
|
</p>
|
|
|
|
<p>Other arguments can be used to control the behavior of the view. These
|
|
are different for different implementations. Whether and how they are used
|
|
may also depend on the configuration store and configuration that were
|
|
selected when the provider was created.
|
|
</p>
|
|
|
|
<p>An implementation must ignore unknown arguments.</p>
|
|
|
|
<p>Some parameters that are commonly supported are:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<strong>Selecting data into a view:</strong>
|
|
<dl>
|
|
<dt><code>"nodepath"</code> : `string`</dt>
|
|
<dd>specifies the location of the view root in the configuration.</dd>
|
|
<dt><code>"depth"</code> : `short`</dt>
|
|
<dd>specifies that elements of the hierarchy that are more than the given
|
|
number of nesting levels away from the root need not be included in the
|
|
view.
|
|
</dd>
|
|
<dt><code>"locale"</code> : com::sun::star::lang::Locale</dt>
|
|
<dd>specifies the locale for which localized values should be
|
|
retrieved.
|
|
</dd>
|
|
</dl>
|
|
|
|
<p><strong>Example:</strong> In the hierarchy
|
|
<BR /><pre>
|
|
A - B1 - C1
|
|
|
|
|
- B2 - C2 (localized: de, en, fr, ..)
|
|
| |
|
|
| - C3 - D1
|
|
| | |
|
|
| | - D2 - E1
|
|
| |
|
|
| - C4 - D3 - E2 - F1
|
|
| | |
|
|
| | - F2
|
|
| |
|
|
| - C5
|
|
|
|
|
- B3
|
|
|
|
|
- B4 - C6 - D4 - E3
|
|
|
|
</pre>
|
|
<BR />selecting a view with <code>nodepath = "/A/B2"</code>,
|
|
<code>depth = 2</code> and <code>locale = <Locale for en_US></code>
|
|
would result in the tree fragment
|
|
<BR /><pre>
|
|
(A-) B2 - C2 (en)
|
|
|
|
|
- C3 - D1
|
|
| |
|
|
| - D2 (..)
|
|
|
|
|
- C4 - D3 (..)
|
|
|
|
|
- C5
|
|
|
|
</pre>
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<strong>Controlling cache behavior:</strong> (with providers that
|
|
cache configuration data)
|
|
<dl>
|
|
<dt><code>"enableasync"</code> : `boolean`</dt>
|
|
<dd>controls how updates are handled in the cache. If `TRUE`, the
|
|
cache may operate in <em>write-back</em> mode, where updates at
|
|
first only affect the cache and are written to persistent storage
|
|
at some later time. If `FALSE`, the cache must operate in
|
|
<em>write-through</em> mode, where updates are written to persistent
|
|
storage at once - that is before
|
|
com::sun::star::util::XChangesBatch::commitChanges()
|
|
returns.
|
|
<p><em>This parameter was formerly called <code>"lazywrite"</code>.
|
|
The old name should still be supported for compatibility.
|
|
</em></p>
|
|
</dd>
|
|
|
|
<dt><code>"nocache"</code> : `boolean`</dt>
|
|
<dd>This deprecated parameter
|
|
specifies that data for the view is not taken from the cache, but
|
|
read directly from storage. This may entail that future changes that
|
|
become visible in the cache are not reflected in this view and that
|
|
changes done through this view are not reflected in the cache.
|
|
<BR /><strong>Use with caution !</strong>
|
|
<p><em>This parameter is not supported by all implementations and may be
|
|
silently ignored !
|
|
</em></p>
|
|
</dd>
|
|
</dl>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>com::sun::star::lang::XMultiServiceFactory::createInstance()
|
|
may be unusable. Only an implementation that supports service names that can be
|
|
used with no further arguments support this method. It should return the
|
|
same result as if
|
|
com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
|
|
had been called using an empty sequence of arguments.
|
|
</p>
|
|
*/
|
|
interface com::sun::star::lang::XMultiServiceFactory;
|
|
|
|
|
|
/** allows controlling or observing the lifetime of the configuration.
|
|
|
|
<p>The owner of the provider may dispose of this object
|
|
using com::sun::star::lang::XComponent::dispose().
|
|
Note that the default provider is owned by the
|
|
com::sun::star::lang::ServiceManager and should not be
|
|
disposed of by user code.
|
|
</p>
|
|
|
|
<p>Views created by the provider generally refer to data that is managed by
|
|
the provider. Therefore, disposing of the provider will cause all objects
|
|
belonging to these views to be disposed of as well. This does not apply to
|
|
<em>snapshot</em> views that have their own copy of the data, if available.
|
|
</p>
|
|
|
|
*/
|
|
interface com::sun::star::lang::XComponent;
|
|
|
|
};
|
|
|
|
|
|
}; }; }; };
|
|
|
|
|
|
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|