Object Model
The centralized entry point for configuration access is a com.sun.star.configuration.ConfigurationProvider object. This object represents a connection to a single configuration data source providing access to configuration data for a single user.
The com.sun.star.configuration.ConfigurationProvider serves as a factory for configuration views. A configuration view provides access to the structure and data of a subset of the configuration database. This subset is accessible as a hierarchical object tree. When creating a configuration view, parameters are provided that describe the subset of the data to retrieve. In the simplest case, the only argument is an absolute configuration path that identifies a structural configuration item. This parameter is given as an argument named "nodepath". The configuration view then encompasses the sub-tree which is rooted in the indicated item.
A configuration view is not represented by a single object, but as an object hierarchy formed by all the items that are part of the selected sub-tree. The object that comes closest to representing the view as a whole is the root element of that tree. This object is the one returned by the factory method of the com.sun.star.configuration.ConfigurationProvider. In addition to the simple node-oriented interfaces, it also supports interfaces that apply to the view as a whole.
Within a configuration view, UNO objects with access interfaces are used to represent all structural items. Value items are not represented as objects, but retrieved as types, usually wrapped inside an any.
The following types are supported for data items:
string
|
Plain Text (Sequence of [printable] Unicode characters) |
boolean
|
Boolean value (true/false) |
short
|
16-bit integer number |
int
|
32-bit integer number |
long
|
64-bit integer number |
double
|
Floating point number |
binary
|
Sequence of uninterpreted octets |
Value items contain a single value, or a sequence or array of one of the basic types. The arrays must be homogeneous, that is, mixed arrays are not supported. The configuration API treats array types as atomic items, there is no built-in support for accessing or modifying individual array elements.
 |
Binary values should be used only for small chunks of data that cannot easily be stored elsewhere. For large BLOBs it is recommended to store links, for example, as URLs, in the configuration.
For example, bitmaps for small icons might be stored in the configuration, whereas large images are stored externally. |
All of the structural objects implement the service com.sun.star.configuration.ConfigurationAccess that specifies interfaces to navigate the hierarchy and access values within the view. Different instances of this service support different sets of interfaces. The interfaces that an object supports depends on its structural type, that is, is it a group or a set, and context, that is, is it a group member, an element of a set or the root of the view.
A configuration view can be read-only or updatable. This is determined by the access requested when creating the view, but updatability may also be restricted by access rights specified in the schema or data. The basic com.sun.star.configuration.ConfigurationAccess service specifies read-only operations. If an object is part of an updatable view and is not marked read-only in the schema or the data, it implements the extended service com.sun.star.configuration.ConfigurationUpdateAccess. This service adds interfaces to change values and modify set nodes.
These service names are also used to create the configuration views. To create a view for read access, call createInstanceWithArguments at the com.sun.star.configuration.ConfigurationProvider to request a com.sun.star.configuration.ConfigurationAccess. To obtain an updatable view, the service com.sun.star.configuration.ConfigurationUpdateAccess must be requested.
The object initially returned when creating a configuration view represents the root node of the view. The choice of services and interfaces it supports depends on the type of configuration item it represents. The root object has additional interfaces pertaining to the view as a whole. For example, updates of configuration data within a view are combined into batches of related changes, which exhibit transaction-like behavior. This functionality is controlled by the root object of the view.
| Content on this page is licensed under the Public Documentation License (PDL). |
