Configuration Error Handling and Recovery

OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Joerg Barfurth	2004-07-06	Final
Conforms to	
Applies to	configmgr, desktop
Task ID(s)	i25939, i25940, i28654
Category	Feature

Abstract

In order to increase the robustness of the office application against corrupted configuration data, the configuration database will support automatic recovery from unusable data. Additionally diagnostic capabilities are provided that allow administrators or support services to obtain log output to identify the cause of configuration problems.

As an added benefit the mechanisms put in place can be used by any client of the UNO configuration API to provide meaningful and context-sensitive error handling for configuration failures.

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

	Name	E-mail Address
User Experience	Frank Löhmann (FL)	frank.loehmann@sun.com
Development	Jörg Barfurth (JB)	joerg.barfurth@sun.com
Quality Assurance	Andreas Treumann (ATR)	andreas.treumann@sun.com
Documentation	TBD	

Approved for Implementation

	Approved by	Date
User Experience	Frank Löhmann	June 25, 2004
Development	Jörg Barfurth	June 24, 2004
Quality Assurance	Andreas Treumann	June 25, 2004
Documentation	N/A	
String Review	Paul Compton	July 04, 2004

Document Change History

Rev. Level	Change	Initials	Date
0.1	Initial version	JB	2004-05-03
0.9	Incorporate string changes and typo corrections from FL	JB	2004-06-24
0.91	Incorporate typo correction from ATR. Set to approved.	JB	2004-06-25
1.0	String review done. Set to final.	JB	2004-07-06

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

2.1	Corrupted user preferences	1

2.2	Corrupted configuration data (other)	1

2.3	Support in case of corrupted configuration data	2

2.4	Corrupted data is encountered while loading configuration data on behalf of an API client.	2

3	Goals	2

4	Requirements and Dependencies	2

4.1	Requirements	2

4.2	Technical Dependencies	2

5	Competitive Analyses	3

6	Detailed Specification	3

6.1	Concepts	3

6.2	Error Handler Callback API	3

6.3	Standard Error Handlers	3

6.4	G11n	4

6.5	Error Conditions	4

6.6	Migration	4

7	Future Tasks	5

8	Notes	5

9	References	5

Glossary

Term	Description
UNO	Universal Network Objects – The component model used in OpenOffice.org
UNO Service	A component that delivers a specified service through an UNO interface
UNO Logger Service	An UNO Component that receives diagnostic messages and shows or collects them as a filtered log.

Motivation

Configuration data is handled mostly 'under the hood', invisible to users. Nevertheless broken or missing configuration data can make a feature – or the entire office application – unusable.

To address this situation the configuration database should be robust against broken data. For administration and support it should provide feedback and interfaces that allow diagnosing recurring problems. In the realm of programmability it should provide a facility to make the handling of errors dependent on the context of the operation according to the needs and possibilities of client code.

User Scenarios

Corrupted user preferences

When user preference data is corrupted or invalid and cannot be read, automatic recovery sets in. The file containing the broken data is moved to the side (for diagnostic investigation or manual recovery). Execution continues without any user-specific settings in the affected configuration component. Options set by the user are lost. A message box informs the user about this.

The ability to inform the user must be activated by client code. Initially this will be provided for a few key configuration accesses during application startup. In other cases the recovery will still be done silently.

Corrupted configuration data (other)

If configuration data other than user preferences is corrupted or invalid and cannot be read, automatic recovery is offered. A message box informs the user that configuration data is corrupted and offers to continue the operation nevertheless. The message alerts the user that this may cause reduced functionality. The user can choose to proceed without the corrupted data source, to retry loading the dat or to abort the operation. If the user chooses to continue ignoring the broken data, the configuration data merge skips the invalid data layer data. On subsequent accesses the cached merge result is used until a remerge becomes necessary, because some layer involved in the merge changes (this includes a fix to the broken data).

This capability must be activated by client code. Initially this will be provided for a few key configuration accesses during application startup. The initial set is the set of accesses that also supports a message box for the preceding scenario. The recovery will not be done silently.

Support in case of corrupted configuration data

A user reports configuration problems to support personnel (local administrator, contracted support, etc.). Possible problems include: The error messages from the preceding uses cases are reported by the user (once or regularly); other error messages report problems with configuration data acces; some user settings get lost regularly; some functionality that is documented to require configuration data does not work as expected; UNO packages that incorporate configuration data don't work as expected or cause error message s. The support persons needs to diagnose the problem.

In this case the support person can install an UNO Logger service, that logs to a well-known output device or location and register it as configuration logger. Pkgchk can be used to install and register such a package.

The log output can then be used to identify the cause of the problem or to provide vital information for quick resolution of a bug escalation.

Corrupted data is encountered while loading configuration data on behalf of an API client.

The client sets up an UNO callback object (into the UNO CurrentContext) before attempting access to configuration data. If an error condition occurs while loading and parsing the configuration data. the callback is called to decide how to resolve the issue. The options include: Retry the merge of the data; abort processing (reporting an exception for the entire access) or remerge without the corrupted data. For user preference data, if recovery (remerge) is chosen, the (possibly) corrupted data is moved away to the side. The callback may present UI to the interactive user to solicit an explicit choice.

Goals

Provide end-users a simple way to recover from corrupted configuration data-

Provide administrators the means to diagnose and repair – if possible – configuration problems.

Provide UNO developers an interface to inject a customized, context-sensitive error-handling strategy into configuration data processing.

Requirements and Dependencies

Requirements

No dead ends for the user, when configuration data is corrupted.

Handle problems in configuration layers that provide only read-only file access or that provide calculated configuration values appropriately.

Fully transparent: client code need not change.

Reasonable default behavior, that doesn't negatively affect security-relevant default (shared) settings.

API clients can provide tailored error handling, which may involve showing a GUI to the user.

Technical Dependencies

The following features are not currently available, but are necessary prerequisites for fully leveraging this feature. These features can be separately and gradually introduced:

Full support of the new error handling facilities in all parts of the OOo application requires that all clients of the configuration API provide error handlers that are tailored to the context.

There currently is no UNO Logger service available as part of the OpenOffice.org (or StarOffice) product. A separate feature to create such an implementation and provide way to install/activate it on demand needs to be implemented to allow users to take advantage of the new logging facility.

Full inter-process transparency for error handling callbacks requires extensions in the UNO/UDK implementation to allow transporting the 'current context' across UNO bridges. A related extension of the concept may also be necessary in order to achieve better thread transparency.

Competitive Analyses

N/A

Detailed Specification

Concepts

The configuration management services will provide an API to allow for context dependent error handling. A - direct or indirect – client of the configuration services can provide an error handler callback object. This error handler can serve as an interaction handler. The handler is provided to the configuration services in the UNO CurrentContext, which is tied to the current thread of execution. The error handler is invoked by the configuration services when an error occurs while loading and parsing configuration data from the backend. The handler can select one of several continuation options, which include raising an exception for the error as well as recovering from the error by ignoring the invalid data item or layer.

The default handler, which is used if no handler has been set up in the current context, will provide a reasonable default behavior. The default is targeted at maintaining the ability to continue execution without compromising system policies.

There will also be a simple error handler that provides a GUI. This standard error handler will show a message box if an error occurs, soliciting a decision from the user. This error handler will be activated for some key places in the application startup sequence to provide user feedback and control for configuration errors that could prevent startup of the OpenOffice.org application.

Both these error handlers are available as UNO services and can be used and adapted in additional client code to provide more context-specific error handling and recovery capabilities.

Additionally the configuration services will support logging information about problems and events that happen during configuration data processing. Information will be logged to an UNO Logger Service that is installed as UNO singleton under a well-known name in the UNO ComponentContext under which the configuration services are running. The information logged includes events that cannot be reported to the error handler due to lack of an appropriate context (e.g. happening in a background thread) as well as additional detail for errors that could be handled through that mechanism.

Users (e.g. system administrators or support personnel) can install a Logger Service, e.g. via pkgchk, when they want to investigate configuration problems.

Error Handler Callback API

The configuration management services, in particular the code that access the backends and parses data looks in the current context for a value named com.sun.star.configuration.InteractionHandler. This value must hold an object implementing service com.sun.star.configuration.InteractionHandler, which primarily supports the well-known interface com.sun.star.task.XInteractionHandler.

When an error occurs method XInteractionHandler::handle() is called with an interaction request that supplies information about the kind of error and the error context.

Supported continuations are in most cases XInteractionApprove to approve automatic recovery and XInteractionDisapprove or XInteractionAbort to deny automatic recovery. In case of XInteractionAbort the current operation will be aborted via an exception. In some cases XInteractionRetry is also supported and allows restarting the current operation without any recovery action.

More detailed information about the interaction requests that may occur is supplied with the service specification for service com.sun.star.configuration.InteractionHandler.

If the interaction handler does not select a continuation (e.g. because it does not support the interaction request) the default error handler will be invoked.

Standard Error Handlers

The standard error handlers are implementations of UNO service com.sun.star.configuration.InteractionHandler that are available in

Default Error Handler

The default error handler need not be provided as an explicit object. Instead if the active interaction handler fails to select a continuation, this error handler is used.

This handler will automatically select the following continuations for some standard requests:

If a (mandatory) backend is inaccessible, ABORT is selected (like in prior versions).

If shared configuration data is corrupted, ABORT is selected (like in prior versions).

If user configuration data is corrupted, Recovery is performed.

Simple GUI Error Handler

This handler will display error message boxes for the following interactions:

A (mandatory) backend is inaccessible

Shared configuration data is corrupted

User configuration data is corrupted

The default button (OK or Cancel) of the error boxes is chose to coincide with the Default Error Handler Action.

String lists

All error message boxes share elements that already are in use by existing configuration error message boxes.

Item	English	German	Comments
Titlebar	%PRODUCTNAME% %PRODUCTVERSION%	Existing message box title.

The error message shown is composed from an error report that is specific to the situation and a question about continuation that is common to all situations.

Item	English	German	Comments
Text	The personal configuration file %URL% is corrupted and must be deleted to continue. Some of your personal settings may be lost.	Die persönliche Konfigurationsdatei %URL% ist beschädigt und muss gelöscht werden. Einige Ihrer persönlichen Einstellungen gehen dabei verloren.	User data corrupted. OK
Text	Configuration data in %URL% is corrupted. Without this data some functions may not operate correctly.	Konfigurationsdaten aus %URL% sind beschädigt. Ohne diese beschädigten Daten können einige Funktionen nicht korrekt ausgeführt werden.	Shared data is corrupted OK
Text	Do you want to continue startup of %PRODUCTNAME% without the corrupted configuration data?	Soll %PRODUCTNAME% ohne die beschädigten Konfigurationdaten starten?	Answered with Yes/No
Text	The configuration data source %URL% is unavailable. Without this data some functions may not operate correctly.\n Do you want to continue startup of %PRODUCTNAME% without the missing configuration data?	Die Konfigurationsdaten quelle %URL% ist nicht verfügbar. Ohne diese fehlenden Daten können einige Funktionen nicht korrekt ausgeführt werden.\n Soll %PRODUCTNAME% ohne die fehlenden Konfigurationdaten starten?	A non-optional backend cannot be accessed. Answered with Yes/No

Initial applications

Unless the office is started with command line options that suppress an initial GUI, the Simple GUI handler will be installed into the UNO CurrentContext of the OpenOffice.org main thread during OpenOffice.org startup. This activates the Standard recovery UI for most configuration data reads in the application.

Logging of Configuration Errors

The configuration services will provide log a range of information into an UNO Logger Service. It will use a logger that is installed as UNO singleton in the component context of the configuration components under the name “/singletons/com.sun.star.configuration.theLogger”. The logger must support the com.sun.star.util.logging.Logger API service specification

The information logged includes

Technical detail about externally visible errors (corrupted data reported to the error handler, exceptions raised) that includes the detailed failure cause and location.

Internal errors that are not visible externally, because they occur asynchronously (e.g. failure during deferred, asynchronous writes)

Warnings about non-normal conditions for which a defined behavior exists.

Informational messages about high-level service lifecycle events.

Additional messages that can be used to trace actual behavior and diagnose unexpected or faulty behavior.

Users – the expected target audience are support personnel and system administrators – need to install an UNO Logger service and register it as singleton under the documented name in order to make use of this function.

G11n

N/A

Error Conditions

This feature is about handling error conditions in existing features, which may or may not be ready to handle error conditions correctly.

If auto-recovery is canceled, existing error handling mechanisms (if any) in each usage context are triggered.

If auto-recovery of shared settings is triggered this may cause followup errors, if the context gets insufficient configuration data. It should be tested, that this is handled no worse than the case of outright failure.

If auto-recovery of user settings is selected, user settings and some state that is stored in the configuration transparently may be lost. Affected components in this case function the same as during first start of the office application.

If the attempted recovery fails recovery is retried with the affected data left out as well. If that ultimately fails, the normal error handling of the application code is used as if no recovery had been attempted.

Migration

N/A

Future Tasks

An overview of configuration components anf their load contexts should be gathered to identify all contexts where this feature could apply.

More sophisticated error handlers with a specialized GUI that are better adapted to different contexts can be provided for special contexts. Error handlers with or without GUI can be supplied for configuration accesses that are not covered currently.

Logger Service implementations for various customer groups can be provided. There may also be Logger services for system integration (i.e. that log to a system-specific application event log).

A more general concept for handling failures in low-level UI-less OpenOffice.org components is desirable. The current solution could be an initial step for a more general solution.

Notes

N/A

References

N/A

Configuration Error Handling and Recovery

Page 4

http://specs.openoffice.org/appwide/configuration/configuration_robustness_spec.sxw

Configuration Error Handling and Recovery

Jörg Barfurth

2004-05-03T13:36:12