Relocatable Office Installation

Author:	Kai Sommerfeld, kso@sun.com

Date:	May 4, 2004

Keywords:	Q-PCD ConfigAdminDeploy-53: relocatable office installation (#i23104#)

Table of Contents

Relocatable Office Installation	1

Scope	1

Motivation	1

Requirements	1

Relocatable base installation	1

Relocatable office user data	2

What's out	2

Concept	2

Usage scenarios	2

Scenario 1 – Shared base installation directory	2

Scenario 2 – Shared user data directory	2

Rules for Developers	3

Helpers for Developers	3

service com.sun.star.util.PathSubstitution	3

service com.sun.star.util.MacroExpander	4

Scope

This document discusses the feature of a relocatable OpenOffice.org installation. It is intended to be read by every OpenOffice.org contributor who introduces or writes or reads Office configuration data. The document contains rules that must be obeyed by everyone in order to keep the Office installation relocatable.

Motivation

Customers sometimes have to move OpenOffice.org network installation directories or OpenOffice.org user data directories to a new location, due to hardware, software or organizational changes. This is not necessarily limited to moving directories physically. It also includes logical movement, means to make the directories visible at different locations in the file system (different mount points) of the OpenOffice.org client machines without physically moving the directories.

Requirements

Starting with OpenOffice.org 2.0, it must be possible to relocate the Office base installation directory and the Office user data directory without loss of functionality.

Relocatable base installation

The directory containing the Office base installation directory can be moved physically to another location without loss of functionality of the Office.

An Office base installation directory shared between different client machines can be mounted at any location in the files system of the client machine. For example, the Office might have been installed on server machine S in /export/bin/OpenOffice.org 2.0. On client A this installation might get visible for instance as /opt/OpenOffice.org 2.0 and on client B as /net/appserver/OpenOffice.org 2.0.

Relocatable office user data

The Office user data (e.g. personal settings, user dictionaries, personal document templates) are still valid and complete after physical move of the directory containing the data.

The Office user data directory might appear at different locations at different client machines without loss of functionality.

What's out

It will not be possible to relocate parts of the Office installation directory or parts of the user data directory.

The Office itself will be fully functional after relocating, but on Windows the system integration is broken afterwards. This problem might be addressed with one the next OpenOffice.org releases. Main focus for OpenOffice.org 2.0 lies on Solaris and Linux. The system integration for CDE, GNOME and KDE will work after relocation as long as the Office base installation path can be found in the PATH environment variable.

Concurrent access of different base installations to user data will not be possible. Shared Office user data might be used subsequently only.

Concept

The idea to achieve a relocatable Office installation is simple. There must not exist any Office configuration data containing the absolute path to an Office installation directory (base installation and user data). It doesn't matter where the configuration data are actually stored (e.g. somewhere inside the Office base installation tree or somewhere in the Office user data directory tree or at any other location, like the Windows registry).

Usage scenarios

Scenario 1 – Shared base installation directory

Different user data directories are used together with one Office installation. The office installation is accessible via the network and is used by different client machines or by different users on the same client machine. The path to the Office installation can be different on the server and the client machines.

To make this work there must not appear the hard coded path to the Office installation directory in any Office configuration data.

Scenario 2 – Shared user data directory

Different Office base installations share user data directories. There could be different client machines each with a local Office installation. Different users may use this client machine. User's Office user data are located at a network directory. The same user always utilizes the same user data directory, regardless and which machine he's working and at what location the user data directory will appear in the client machine's file system.

To get this working there must not appear the hard coded path to the Office installation directory or to the Office user data directory in any Office configuration data.

Rules for Developers

The following ruleset is available to deal with the problem whether and how to store references to an Office installation:

R1: Think twice. If it's not absolutely necessary to store data containing a reference to an Office installation directory simply don't do it.

R2: If it is necessary to store data containing a reference to an Office installation directory, do not store that reference directly as an absolute path or URL. Store the data in a form that allows it to apply a mechanism to calculate the absolute path or URL at runtime (e.g. use a placeholder).

R3: If it is necessary to store data containing a reference to an Office installation directory, and R2 cannot be applied, for example, because the code that stores the absolute reference is 3rd party, it must be ensured that the code that uses this data still works after relocating the installation. An example would be a cache that automatically will be rebuilt after relocation. The user must have write access to these data which means that the data are user data. But even then, this should be avoided whenever possible, because it will often cause performance problems in an environment where the user data are shared and appear at different locations at different client machines.

R4: To be used, if neither R1 nor R2 nor R3 are applicable. Means, configuration data which contain an absolute reference to an Office installation directory and which cannot be avoided or cannot be changed to be relocatable or which not get repaired automatically. Avoid usage of such data under all circumstances, because they break the relocatability feature. At the time of writing this document those configuration data are only allowed to appear as part of the Windows system integration.

Helpers for Developers

Office application code that actually needs to write data containing a reference to the Office installation directory or Office user data directory must never store this path directly (R3). A way to realize this is to store a placeholder for the Office installation directory instead of the absolute path. There are different UNO services available that are of help here:

service com.sun.star.util.PathSubstitution

This service can be used to create relocatable strings from strings containing non-relocatable directory references and vice versa. Relocatable strings produced by this service can be made persistent safely without danger to break the relocatability of the Office installation. Actually this service is even more powerful, because it is able to handle much more path variables than just for the Office base installation directory and the Office user data directory. Extended documentation can be found here: http://api.openoffice.org/docs/DevelopersGuide/OfficeDev/OfficeDev.htm in chapter Path Organization.

using namespace com::sun::star; ... uno::Reference< uno::XComponentContext > xCtx = ...; uno::Reference< lang::XMultiComponentFactory > xFactory
= xCtx->getServiceManager(); uno::Reference< util::XStringSubstitution > xSubst( xFactory->createInstanceWithContext(
rtl::OUString(RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.util.PathSubstitution")),
xCtx), uno::UNO_QUERY); // make path relocatable rtl::OUString aNonRelocatablePath = ... rtl::OUString aRelocatablePath = xSubst->reSubstituteVariables(aNonRelocatablePath); // store relocatable path aMyDataStore.store(..., aRelocatablePath); // ... and reload again aRelocatablePath = aMyDataStore.load(...); // make path absolute aNonRelocatablePath = xSubst->substituteVariables(aRelocatablePath, sal_True);

service com.sun.star.util.MacroExpander

For lower-level code that has no access to com.sun.star.util.PathSubstitution (should never be the case in Office code), there is a singleton named “/singletons/com.star.util.theMacroExpander” available that can be used to obtain the absolute path to the office installation directories at runtime.

The code storing the reference to the office installation directory needs to determine whether the directory to store points to the current Office installation directory or Office user data directory. If so, the directory string must be replaced by a suitable placeholder of choice.

The code reading the data simply needs to replace all occurrences of the place holders with the current Office installation directory or Office user data directory.

using namespace com::sun::star; ... uno::Reference< uno::XComponentContext > xCtx =...; uno::Reference< util::XMacroExpander > xExpander; xCtx->getValueByName(
rtl::OUString(RTL_CONSTASCII_USTRINGPARAM(
"/singletons/com.sun.star.util.theMacroExpander"))) >>= xExpander; // Note: returns a URL, not a path in system dependent notation!
rtl::OUString aOfficeDir
= xExpander->expandMacros( rtl::OUString(RTL_CONSTASCII_USTRINGPARAM(
"${$SYSBINDIR/" SAL_CONFIGFILE("bootstrap") ":BaseInstallation}"
))); // URL may be relative; make it absolute osl::FileBase::getAbsoluteFileURL(rtl::OUString(), aOfficeDir, aOfficeDir); // Note: returns a URL, not a path in system dependent notation!
rtl::OUString aUserDir
= xExpander->expandMacros( rtl::OUString(RTL_CONSTASCII_USTRINGPARAM(
"${$SYSBINDIR/" SAL_CONFIGFILE("bootstrap") ":UserInstallation}"
))); // URL may be relative; make it absolute osl::FileBase::getAbsoluteFileURL(rtl::OUString(), aUserDir, aUserDir);

Kai Sommerfeld

2004-03-26T11:44:29