Configuration Management

From Apache OpenOffice Wiki
Jump to: navigation, search

PDF Icon.gif Download as a PDF or ODT


The Apache OpenOffice configuration management component provides a uniform interface to get and set Apache OpenOffice configuration data in an organized manner, independent of the physical data store used for the data.

The configuration API can be used to get and set existing configuration options. Additionally, you can extend the configuration with new settings for your own purposes. For details, see Customizing Configuration Data.


Apache OpenOffice configuration data describes the state or environment of a UNO component or the Apache OpenOffice application. There are different kinds of configuration data:

  • Static configuration: This is data that describes the configuration of the software and hardware environment. This data is set by a setup tool and does not change at runtime. An example of static configuration data is information about installed filters.
  • Explicit settings: This is preference data that can be controlled by the user explicitly. There is a dedicated UI to change these settings. An example of explicit settings are the settings controlled through the Tools → Options dialogs in Apache OpenOffice.
  • Implicit settings: This is status information that is also controlled by the user, but the user does not change explicitly. The application tracks this state in the background, making it persistent across application sessions. An example of implicit settings are window positions and states, or a list of the recently used documents.

This list is not comprehensive, but indicates the range of data characteristically stored by configuration management.

The configuration management component organizes the configuration data in a hierarchical structure. The hierarchical structure and the names and data types of entries in this database are described by a schema. Only data that conforms to one of the installed schemas is stored in the database.

The hierarchical database stores any hierarchical information that can be described as a configuration schema, but it is optimized to work with the data needed for application configuration and preferences. Small data items having a well-defined data type are supported efficiently, whereas large, unspecific binary objects should not be stored in the configuration database. These objects should be stored in separate files so that the configuration keeps the URLs of these files only.

Configuration schemas are provided by the authors of applications and components that use the data. When a component is installed, the corresponding configuration schemas are installed into the configuration management system.

Configuration data is stored in a backend data store. In Apache OpenOffice, that data store consists of XML files in various places within the directory hierarchy.

Configuration layers

For a given schema, multiple layers of data may exist that are merged together at runtime. One or more of these layers define default settings, possibly shared by several users. Additionally, there is a layer specific to a single user that contains personal preferences overriding the shared settings. All changes to data affect only this user-specific layer.

Access to the merged configuration data for a user is managed by a object.

This provider provides views on the configuration data. A view is a subset of the entire configuration that can be navigated as an object hierarchy. The objects in this hierarchy represent nodes of the configuration hierarchy to navigate to other nodes and access values of data items.

All configuration items have a fixed type and a name.

The type is prescribed by the schema. The following kinds of items are available:

  • 'Properties' are data items that contain a single data value or an array of values from a limited set of basic types.
  • 'Groups' are structural nodes that contain a collection of child items of various types. The number and names of children, as well as their types, are fixed by the schema. Structural and data items can be mixed within one group.
  • 'Sets' are structural nodes that serve as dynamic containers for a variable number of elements. These elements must be all data or all structural items, and they must all be uniform. In the first case, all values have the same basic type, and in the latter case, all the sub-trees have the same structure. The schema contains templates for container elements, which are prototypes of the element structure.

Properties hold the actual data. Group nodes form the structural skeleton defined in the schema. Set nodes are used to dynamically add and remove configuration data within the confines of the schema. Taken together, they can be used to build hierarchical structures of arbitrary complexity.

Each configuration item has a name that uniquely identifies the item within its parent, that is, the node in the hierarchical tree that immediately contains the item under consideration. Paths spanning multiple levels of the hierarchy are built similarly to UNIX file system paths. The separator for individual name components in paths is a forward slash ('/'). Paths that begin with a slash are considered 'absolute paths' and must completely specify the location of an item within the hierarchy. Paths that start directly with a name are relative paths and describe the location of an item within one of its ancestors in the hierarchy.

The top-level subdivisions of the configuration hierarchy are called configuration modules. Each configuration module has a schema that describes the data items available within that module. Modules are the unit of schema installation. The name of a configuration module must be globally unique. The names of configuration modules have an internal hierarchical structure using a dot ('.') as a separator, similar to Java package names. The predefined configuration modules of Apache OpenOffice use package names from the super-package "org.openoffice.*".

The names of container elements are specified when data items are added to a container. Data item names in the schema are limited to ASCII letters, digits and a few punctuation marks, but there are no restrictions applied to the names of container elements. This requires special handling when referring to a container element in a path. A path component addressing a container element takes the form <template-pattern>['<escaped-name>']. Here <template-pattern> can be the name of the template describing the element or an asterisk "*" to match any template. The <escaped-name> is a representation of the name of the element where a few forbidden characters are represented in an escaped form borrowed from XML. The quotes delimiting the <escaped-name> may alternatively be double quote characters "". The following character escapes are used:

Character Escape
& &amp;
" &quot;
' &apos;

In the table below, are some escaped forms for invented entries in the Set node /org.openoffice.Office.TypeDetection/Filters for (fictitious) filters:

Filter Name Path Component
Plain Text Filter['Plain Text']
Q & A Book *["Q &amp; A Book"]
Bob's Filter *['Bob&apos;s Filter']

The UIName value of the last example filter would have an absolute path of /org.openoffice.Office.TypeDetection/Filters/Filter['Bob's Filter']/UIName.

In several places in the configuration management, API arguments are passed to a newly created object instance as Sequence, for example, in the argument to createInstanceWithArguments. Such arguments are type

Documentation note.png For compatibility with older versions, arguments of type are accepted as well. Only the Name and Value fields need to be filled.
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages