Transparent Use of Office UNO Components

From Apache OpenOffice Wiki
Jump to: navigation, search

If some client code wants to use office UNO components, then a typical use case is that the client code first looks for an existing office installation. If an installation is found, the client checks if the office process is already running. If no office process is running, an office process is started. After that, the client code connects to the running office using remote UNO mechanisms in order to get the remote component context of that office. After this, the client code can use the remote component context to access arbitrary office UNO components. From the perspective of the client code, there is no difference between local and remote components.

The bootstrap method

Therefore, the remote office component context is provided in a more transparent way by the method, which bootstraps the component context from a UNO installation. A simple client application may then look like:

  // get the remote office component context
  XComponentContext xContext =;
  // get the remote office service manager
  XMultiComponentFactory xServiceManager =
  // get an instance of the remote office desktop UNO service
  Object desktop = xServiceManager.createInstanceWithContext(
      "", xContext );

The method first bootstraps a local component context and then tries to establish a named pipe connection to a running office. If no office is running, an office process is started. If the connection succeeds, the remote component context is returned.

Documentation note.png Note, that the method is only available since 1.1.2.

SDK tooling

For convenience, the Apache OpenOffice Software Development Kit (SDK) provides some tooling for writing Java client applications.

One of the requirements for a Java client application is that Java finds the class and all the UNO types (for example, UNO interfaces) and other Java UNO language binding classes (for example, used by the client code. A natural approach would be to add the UNO jar files to the Java CLASSPATH, but this requires the knowledge of the location of a UNO installation. Other approaches would be to use the Java extension mechanism or to deploy the jar files containing the UNO types in the client jar file. Both of those approaches have several drawbacks, the most important one is the problem of type conflicts, for example, if a deployed component adds new UNO types. The SDK tooling therefore provides a more dynamic approach, namely a customized class loader. The customized class loader has an extended search path, which also includes the path to a UNO installation. The UNO installation is auto-detected on the system by using a search algorithm.

Customized Class Loader

The concept is based on the requirement that every class that uses UNO types, or other classes that come with a office installation, gets loaded by a customized class loader. This customized class loader recognizes the location of a UNO installation and loads every class from a jar or class file that belongs to the office installation. That means that the customized class loader must be instantiated and initialized before the first class that uses UNO is loaded.

The SDK tooling allows to build a client jar file, which can be invoked by the following:

 java -jar SimpleBootstrap_java.jar

The client jar file contains the following files:


A client application created by using the SDK tooling will automatically load the class, which sets up the customized class loader for loading the application class. In order to achieve this, the SDK tooling creates a manifest file that contains the following Main-Class entry


The customized loader needs a special entry in the manifest file that specifies the name of the class that contains the client application code:

 Name: com/sun/star/lib/loader/Loader.class
 Application-Class: SimpleBootstrap_java

The implementation of reads this entry and calls the main method of the application class after the customized class loader has been created and set up properly. The SDK tooling will take over the task of writing the correct manifest entry for the application class.

Finding a UNO Installation

The location of a UNO installation can be specified by the Java system property The system property can be passed to the client application by using the -D flag, e.g

 -jar SimpleBootstrap_java.jar

In addition, it is possible to specify a UNO installation by setting the environment variable UNO_PATH to the program directory of a UNO installation, for example,

 setenv UNO_PATH /opt/

Documentation caution.png This does not work with Java 1.3.1 and Java 1.4, because environment variables are not supported in those Java versions.

If no UNO installation is specified by the user, the default UNO installation on the system is searched. The search algorithm is platform dependent.

On the Windows platform, the UNO installation is found by reading the default value of the key 'Software\\UNO\InstallPath' from the root key HKEY_CURRENT_USER in the Windows Registry. If this key is missing, the key is read from the root key HKEY_LOCAL_MACHINE. One of those keys is always written during the installation of an office. In a single user installation the key is written to HKEY_CURRENT_USER, in a multi-user installation of an administrator to HKEY_LOCAL_MACHINE. Note that the default installation is the last installed office, but with the restriction, that HKEY_CURRENT_USER has a higher priority than HKEY_LOCAL_MACHINE. The reading from the Windows Registry requires that the native library unowinreg.dll is part of the application jar file or can be found in the java.library.path. The SDK tooling automatically will put the native library into the jar file containing the client application.

On the Unix/Linux platforms, the UNO installation is found from the PATH environment variable. Note that for Java 1.3.1 and Java 1.4, the installation is found by using the which command, because environment variables are not supported with those Java versions. Both methods require that the soffice executable or a symbolic link is in one of the directories listed in the PATH environment variable. For older versions than 2.x the above described methods may fail. In this case the UNO installation is taken from the .sversionrc file in the user's home directory. The default installation is the last entry in the .sversionrc file which points to a UNO installation. Note that there won't be a .sversionrc file with 2.x anymore.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages