Desktop Integration

SO/OO.o Q

Document - ID	Specification Owner	Last Change	Status
	Sarah Smith	2/27/04	Final
Conforms to	
Applies to	SO/OO.o backend configuration
Task ID(s)	114070
Category	Feature

Abstract

This specification details how the SO/OO.o desktop integration feature will be realized.

i-Team Members (The specification Owner is part of the i-Team)

	Name	E-mail Address
User Experience	Christian Jansen	christian.jansen@sun.com
Development	Sarah Smith	sarah.smith@sun.com
Quality Assurance	Stephan Wunderlich	stephan.wunderlich@sun.com
Documentation	Yvonne Jacoby	yvonne.jacoby@sun.com

Approved for Implementation

	Approved by	Date
User Experience		
Development		
Quality Assurance		
Documentation		
String Review		

Document Change History

Rev. Level	Change	Initials	Date
0.1	Initial Draft	SS	25/11/03
0.2	Updated after review by Dirk Grobler and Joerg Barthfurth. Included design into specification. Updated section 7.3 Performance/Resource Impact. Many minor additions.	SS	12/02/03
0.3	Updated to reflect actual implementation	SS	17/02/04
0.4	Updating with new com.sun.star.configuration.backend.LayerDescriber service	SS	27/02/04
1	Setting to final	SS	30/03/04

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	1

4	Requirements and Dependencies	1

4.1	Requirements	1

5	Technical Dependencies	2

6	Competitive Analyses	2

7	Detailed Specification	2

7.1	Existing Architecture	2

7.2	Proposed Solution	3

7.3	Performance/Resource Impact	8

7.4	Compatibility	8

7.5	Reference Implementation	9

7.6	Error Conditions	9

8	Future Tasks	9

9	Notes	9

10	References	9

Glossary

Term	Description
StarRegistry	Registry implementation for SO/OO.o
Entity	A logical object to which we can assign configuration data, e.g. User, Groups and Organizations are entities know to StarRegistry.
MultiStratum	Multiple layers of configuration data
Layer	The set of configuration data assigned to an entity.

Motivation

A new requirement for SO/OO.o-Q is that SO/OO.o has a higher level of system integration. What this means for the SO/OO.o application is that is must be able to access configuration data from an extensible number of varying external sources. Examples of such external sources are not limited to Gconf, Windows Registry or regular files.

To enable system integration there needs to be a framework provided by SO/OO.o to plug-in a number of additional backends that will provide access to the relevant configuration data. How the additional backends actually retrieve the configuration data is outside the scope of this feature, it is an implementation detail of the individual backend.

User Scenarios

With suitable system integration backends, the user's standard system settings are used by SO/OOo transparently. For example internet proxies configured in the system are used automatically, the UI or document language and currency selected in the system are honored or user data is read from an LDAP directory.

Goals

Provide a framework that permits additional backends to be plugged into the configmgr stack. The required backend implementations will be responsible for retrieving the actual configuration data.

Provide a framework that permits removal of backends from the configmgr stack

Provide a reference implementation of an example backend that fits into extended framework.

The extended framework must not impact on SO/OO.o startup performance.

Write-back to systems sources via the platform backends is not a goal of this feature. SO/OO.o will not write to system sources, any updates if permitted will be stored in user layer.

Requirements and Dependencies

Requirements

SO/OO.o Q will make increased use of information and infrastructure that is provided with the system instead of creating platform independent proprietary solutions.

Technical Dependencies

Competitive Analyses

Detailed Specification

Existing Architecture

The backend architecture described below is fully implemented and thus is categorised as existing, however it is not yet released in any SO/OO.o version, it will be made available from an upcoming 00.o 1.1.x release.

Currently in the configmgr stack there is a MultiStratum Backend Manager that co-ordinates access to a number of configurable backends.

The MultiStratum Backend Manager is configured using the configmgr.ini(rc), the bootsrap configuration file containing a list for all required backends. Each backend is responsible for retrieving layer(s) of configuration data. A layer is defined as the set of configuration data assigned to an entity.

Each configured backend comprises of an UNO object that implements a service that specifies one of following three Interfaces:

XSingleLayerStratum

This interface is used to access a component's configuration data that consists of a single layer from a single configuration data repository. This is the most usual case and will be the interface implemented by all the platform specific backends.

XMultiLayerStratum

This interface is used to access a component's configuration data that consists of multiple layers from a single configuration data repository. The multiple layers of data associated with the component will need to be merged to ensure correct final result.

An example of multi layered configuration data is data retrieved from an LDAP directory server. The relationship between entities defines that a user can be a member of an organisation and thus configuration data can be associated with the organisation and the user entity providing us with two separate layers of configuration data.

XBackend

This interface is used to access a component's configuration data that consists of multiple layers. The difference between this interface and XMultiLayerStratum is that we don't need to provide layer ids to retrieve the associated configuration data. Using the XMultiLayerStratum Interface you need to supply a layer id identifying the layer ( e.g. LDAP DN of layer) to retrieve the associated data. Using the XBackend interface no such ids are needed thus enabling us to retrieve multiple layers associated with an entity using single request.

Class Diagram of Existing Architecture

Outlined below is a class diagram representing the current backend framework that exists in the configmgr stack, it depicts the type of objects in the system and the various kinds of static relationships that exist among them.

The current design is not suitable for the additional platform backends. To use the current framework would necessitate an overload of metaconfiguration data to be supplied and require a rewriting of the configmgr.ini(rc) file with the addition of every platform backend.

Below is default CFG_Strata entry used by MultiStratum Backend Manager to initialiase the required backends. The entry is static and does not require adjustment for normal SO/OO.o operation so rewriting this entry with each additional platform backend is not a viable option.

CFG_Strata=com.sun.star.comp.configuration.backend.LocalSingleStratum:$CFG_DefaultLayerUrl;com.sun.star.comp.configuration.backend.LocalSingleStratum:$CFG_UnoSharedPackages;com.sun.star.comp.configuration.backend.LocalSingleStratum:$CFG_UnoUserPackages;com.sun.star.comp.configuration.backend.LocalSingleStratum:$CFG_UserLayerUrl;

Proposed Solution

To extend our current backend framework to allow additional backends to be plugged into SO/OO.o Configmgr code stack we need a System Integration Backend Manager that manages the individual platform specific backends and their association to configuration components. The System Integration Backend Manager will be plugged into the existing MultiStratum Backend Manager.

Class Diagram of Proposed Solution

Outlined below is a class diagram representing the extended backend framework that facilitates the addition of platform specific backends. It depicts the type of objects in the system and the various kinds of static relationship that exist among them.

Platform Specific Backends

Each individual platform specific backend will be provided as an UNO component that implements the service PlatformStratum.The UNO component will be provided as a shared library. The PlatformStratum service will implement the SingleLayerStratum service which implements the XSingleLayerStratum interface.

The XSingleLayerStratum interface looks like:

interface XSingleLayerStratum : ::com::sun::star::uno::XInterface

{

XLayer getLayer( [in] string aComponent,

[in] string aTimestamp)

raises (BackendAccessException,

com::sun::star::lang::IllegalArgumentException) ;

XUpdatableLayer getUpdatableLayer([in] string aComponent)

raises (BackendAccessException,

com::sun::star::lang::NoSupportException,

com::sun::star::lang::IllegalArgumentException) ;

} ;

The method getLayer returns an XLayer object for a given component and thus all backends implementing the XSingleLayerStratum Interface will need to create and return a platform specific layer object that implements the XLayer Interface. For example a GconfBackend would return a GconfLayer, a WindowRegistryBackend would return a WindowsLayer.

At the backend level all access to configuration data is done on a component granularity, it will be the responsibility of the individual backends to maintain a mapping between configuration key names and their associated component names. How the backend implementations are configured with datasources and configuration keys is outside the scope of this task and should be dealt with by the individual backend implementations.

All backends must register their supported components into the Services.rdb file using the component_writeInfo() function, see example below.

/IMPLEMENTATIONS/com.sun.star.comp.configuration.backend.GconfBackend

/ UNO

/ ACTIVATOR

Value: Type = RG_VALUETYPE_STRING

Size = 34

Data = "com.sun.star.loader.SharedLibrary"

/ SERVICES

/ com.sun.star.configuration.backend.GconfBackend

/ com.sun.star.configuration.backend.PlatformBackend

/ LOCATION

Value: Type = RG_VALUETYPE_STRING

Size = 42

Data = "c:/staroffice8_m16/program/gconf1.uno.dll"

/ DATA

/ SupportedComponents

Value: Type = RG_VALUETYPE_STRINGLIST

Size = 61

Len = 2

Data = 0 = "org.openoffice.Office.Common"

1 = "org.openoffice.Inet

Platform Specific Layer Design

Outlined below is the design of the PlatformLayer.

The PlatfromLayer implements the XLayer Interface and is responsible for reading the configuration data from the external system sources and describing the contents of the layer to an XLayerHandler object.

The PlatfromLayer must construct a sequece of com.sun.star.configuration.backend.PropertyInfo structs.The com.sun.star.configuration.backend.PropertyInfo struct contains the following information; the property name, the property value, the property type and whether the property is protected (cannot be overwritten in subsequent layers). The property name must be the full SO/OO.o name as in /org.openoffice.Inet/Settings/ooInetHTTPProxyName for the HTTP proxy name. Each PropertyInfo struct represents a single SO/OO.o property.

The PlatformLayer initializes the BackendHelper object by creating an instance of the com.sun.star.configuration.backend.LayerDescriber service to describe the contents of the PlatformLayer to the XLayerHandler object.

The PlatformLayer calls the BackendHelper object's describeLayer function passing in the PropertyInfo structs and the XLayerHandler Object.

See Sequence diagram ReadData for object interactions.

The reference implementation will clearly demonstrate how to use the extended framework.

The PlatformLayer must also implement the XTimeStamped Interface to ensure compatibility with SO/OO.o's BinaryCache feature. See section 7.4 Compatibility.

Backend Helper Design

The BackendHelper implements the com.sun.star.configuration.backend.LayerDescriber service which realises the XLayerContentDescriber interface. The BackendHelper will be provided as a separate UNO component that all platform backend implementations can use. The XLayerContentDescriber has a single method describeLayer which is called by the PlatformLayer object to describe the contents of the PlatformLayer to the XLayerHandler object. The PlatformLayer will pass the BackendHelper a list of PropertyInfo structures containing all the information needed to describe the layer and the XLayerHandler object.

See Sequence diagram ReadData for object interactions.

System Integration Backend Manager

The System Integration Backend Manager will be similar to the MultiStratum Backend Manager, it will implement the XBackend Interface. It will differ in how it initializes the individual backends. The System Integration Backend Manager will not be configurable via a ini/rc file. The System Integration Manager Initialization function will build a lookup table containing component names and their related XSingleComponentFactory objects. The System Integration Manager will retrieve the XSingleComponentFactory objects by querying the Service Manager for all implementations of the PlatformBackend Service. Using the returned XSingleComponentFactory object the related components can be retrieved by getting the ImplementationKey, a new key that was added to allow metaconfiguration data to be added to a service in the the .rdb file. When the System Integration Manager receives a request for component data it does a lookup to find the associated Platform backend, it then initializes the backend and forwards the request to it.

There is no prioritization among the individual platform specific backends initialized by the System Integration Backend Manager. It is assumed that only one platform backend will return configuration data associated with a specific configuration key, multiple values for the same key will not be returned. Result are undefined if more that one platform backend returns configuration data.

Some aspects of backend selection (e.g. which of several concurrently installed platform backend to use , GNOME/KDE/CDE) can't be solved in this scope, custom factories or contest singletons might be used to solve this.

The System Integration Backend Manager and individual backend implementations will be provided as UNO components.

How the UNO components get registered/deregistered into the registration database 'services.rdb' is beyond the scope of this document and will be taken care of by SO/OO.o's setup procedure. All backends that get registered into the registration database will be initialized by the System Integration Backend Manager when their associated component is requested.

Sequence Diagrams

ListLayers

The MultiStratumBackend forwards the listLayers() request to the SystemIntegrationManager. The SystemIngetrationManager initializes the correct platform by performing a table look-up on the requested component. The System Integration Manager then calls getLayer() on the PlatformBackend. The PlatformBackend will create a new PlatformLayer. It will be responsibility of the PlatformBackend to configure the Platform Layer with its associated configured configuration keys, how it does this is outside the current scope of this feature.

ReadData

The readData() function is invoked on the PlatformLayer(XLayer) object form the merge() function of the BackendAccess object. The PlatformLayer invokes readsConfigData(), this function is responsible for reading the configuration data from the external datasource. The values that are read are put into a list of com.sun.star.configuration.backend.PropertyInfo structures and passed with the XLayerHandler object to the describeLayer() function of BackendHelper class. The BackendHelper (XlayerContentDescriber) will build a tree out of the list of PropertyInfo structures and then iterate over the tree describing its contents to the LayerMerger (XlayerHandler) object.

DescribeLayer pseudo code

BackendHelper::describeLayer(XHandler, vector<PropertyInfo> )

Begin

nodes = PlatformLayerInfo.getParentNode()

xHandler->startLayer(PlatformLayerInfo.getComponentName())

Loop thru nodes

xHandler->overideNode(node[i], 0)

end Loop

Loop thru properties

attribute = PropertyInfo[i].bProtected

xHandler->overrideProperty(PropertyInfo[i].aPropertyName, attribute)

xHandler->setPropertyValue(PropertyInfo[i].aPropertyValue)

end Loop

End

Performance/Resource Impact

The extended framework must not impact SO/OO.o performance especially in the area of startup.

Access on Demand

Some of the individual platform specific backends have the potential to impact SO/OO.o startup performance because of the necessary initialisation overheads, they might require loading of additional system libraries or access a slow datasource. To combat this factor all backend initialisation will be only be done when an associated component is requested from that backend. The System Integration Backend Manager will only instantiate the backend if the platform backend's associated component is requested, the backends are only initialised on demand.

To facilitate this requirement, the System Integration Backend Manager must be able to retrieve the platform backends associated component name(s) before object instantiation. Every UNO component exports the function component_writeInfo(), this function will write information about the service implementation into an registry file(.rdb). Using this function we can add the associated component name(s) to the registry file which can be later queried to ensure that the correct platform backend is initialised.

Compatibility

Binary Cache

The Binary Cache feature enables SO/OO.o to reads its configuration data in an already parsed and merged state if none of the layers have changed since the previous read cycle. This feature significantly improves SO/OO.o startup performance.

In order for the new individual backends to be compatible with SO/OO.o's binary cache feature, the layer objects returned will have to implement the util::XTimeStamped Interface. If a timestamp cannot be retrieved from the layer, the binary cache will assume the layer is always uptodate and thus always retrieve the value from it cache. Any updates to the layer will thus be lost.

For caching it remains to be determined if we expect to encounter backends with frequently chaining values. For them another solution (a second non-cached) stratum may be needed, this is out of the scope of this task.

Notifications

Notification support has been added to the backend framework, as stated earlier this framework has yet to become available in any SO/OO.o release, it is categorised as current as it is fully implemented.

Currently SO/OO.o empties its main cache every 15 minutes. In order to keep the cache in sync with the backends, the current backend framework supports backend notifications.

A backend that supports notification will notify the cachecontroller of any changes in the backend data causing a reload of the data into the cache. The cachecontroller will inturn notify all higher layers (view/api) of the changes.

The individual backend implementations may support the XBackendChangesNotifier Interface to enable the registration of listener objects to detect changes. It will be up to the individual backend implementations as to how they detect the changes. Whether the platform backends support notification is entirely the responsibility of the backend implementator.

Reference Implementation

The reference backend implementation provided will read configuration data from Gconf. It will clearly outline how the configuration data that is read from the external source is mapped in the layer structure and thus deployable throughout the configmgr stack.

Error Conditions

This is a preliminary list of failure modes

Any platform backend that fails to return the requested configuration data will be ignored and the default value form SO/OO.o's default layer will be used.

Future Tasks

A number of platform backend implementations that can be plugged into the configmgr stack.

Notes

References

http://api.openoffice.org/docs/common/ref/com/sun/star/configuration/backend/XBackend.html

http://api.openoffice.org/docs/common/ref/com/sun/star/configuration/backend/XSingleLayerStratum.html

http://api.openoffice.org/docs/common/ref/com/sun/star/configuration/backend/XMultiLayerStratum.html

http://api.openoffice.org/docs/common/ref/com/sun/star/configuration/backend/XLayerHandler.html

http://api.openoffice.org/docs/common/ref/com/sun/star/configuration/backend/XLayer.html

Required - Give references to related documentation, such as engineering designs, technical specs, and other sources for related units. Also include links to documents that other sections in this spec need to refer to, such as user opinions usability test reports.

Desktop-Integration Specification

Page 4

<Required - Path to specification>

2003-11-25T11:56:40