Framework for Use of Different Java Distributions

Revision 5.1

Last change: 6th Dec 2004

Authors: Joachim Lingner (jl@openoffice.org)

Table of Contents

1Objectives	1

2Abstract	2

3Parts of the Framework	2

3.1Overview	2

3.2JavaVendorPlugin	4

3.3JavaPreparationTool	5

3.4javavendors.xml	5

4Configuring the Framework	9

Objectives

OpenOffice.org needs a Java runtime environment in order to be fully operative. Java distributions are available from different vendors. However, OOo 1.x expects a Java from Sun Microsystems Inc. or a Java that is 100 % compatible. The framework is intended to allow the use of those Java distributions which are not from Sun. It shall also be possible to specify version requirements for particular vendors and different platforms.

A client of the framework can obtain a Java Virtual Machine without knowing the particular details about location, version, vendor and creation details for that JRE.

It is not the task of the framework to provide access to any tools which may come with a JRE or SDK, nor does it provide a way to render Java graphics to a native window (e.g. displaying applets).

Abstract

If a Java runtime environment (JRE) from a vendor other than Sun is to be used than it must provide a Java API and a Java Native Interface which are compatible with the respective APIs of a Sun JRE. Apart from that, the JREs may differ in

the way the VM is created

the locations where they are installed

the directory structure of the installation

the names of libraries and executables

the applied versioning scheme (different syntax of the version string, or versions completely unrelated to Sun's JRE releases.

Using the framework an office can be adapted to run with a Java distribution from a particular vendor by supplying a “vendor extension” which consists of

a shared library, which implements a specified API

an executable, which is used from the start script and which prepares the environment before office process runs (optional)

a start script (on Linux and Solaris there is already a start script which can be adapted) which runs the executable (see previous item)

a configuration file (e.g.javavendors.xml)

Parts of the Framework

Overview

The following diagram gives an overview about the involved entities.

Illustration 1 Framework overview

The VendorSupportExtension package represents the part which is to be realized by the people who want to use a Java of a particular vendor.

Here is an overview of the displayed items:

com.sun.star.java.JavaVirtualMachine: This service is internally used by the office whenever a running Java is required. It does not create a Java VM itself. Instead it relies on the JavaFramework to provide a JavaVM pointer. The JavaFramework in turn uses a JavaVendorPlugin to create the VM.

OptionsDialog: The options dialog will allow a subsequent configuration of Java.

JavaFramework: This library contains the framework that allows to plug in support for Java distributions of other vendors.

OfficeStartScript: In case a Java needs to have a prepared environment or some configuration has to be done before the office process runs, then executables, which are instances of JavaPreparationTool, can be called from the start script (on Linux this is the soffice script). The script may be adapted to the special needs of that executable. For example, the javaldx is a JavaPreparationTool for Sun Java on Linux and Solaris. It writes path of certain directories of a JRE to stdout which is used by the script to set the LD_LIBRARY_PATH.

JavaInfo: An instance of this class represents exactly one JRE. It contains all necessary data to create a Java VM. However, only the JavaVendorPlugin that produced the JavaInfo object may be able to create a VM from that data.

Java: Represents a JRE.

JavaVendorPlugin: A library that provides information about available JREs and it creates Java VMs.

JavaPreparationTool: An executable that is run before the office process and which performs preparations to run the Java which has been selected to be used with the office.

javavendors.xml: These files contain entries about the available JavaVendorPlugins and information about what versions from a particular Java distribution can be used.

JavaVendorPlugin

A JavaVendorPlugin delivers information about JREs and creates the VM. A plug-in may provide information about JREs from different vendors. OpenOffice.org initially comes with a plug-in, named sunjavaplugin.[dll | so] that can be used with JREs from Sun Microsystems Inc. and will be available on these platforms:

Windows

Linux, X86

Solaris, Sparc

Solaris, X86

The plug-in also supports JREs from Blackdown, IBM and Mac, albeit in a limited way. Currently (Nov. 8, 2004) one cannot control which versions are to be used. In particular the values for the minimum (minVersion) and maximum (maxVersion) versions are ignored and it cannot be specified if a version shall not be used at all (exclude Version). As for the latter, the javavendors.xml must not even contain a value in the excludeVersion element for that particular vendor.

The plug-in provides three C - functions, one that provides information about all JREs, one that provides information about a JRE which is located at a specified path, and one that creates a VM.

javaPluginError jfw_plugin_getAllJavaInfos(

rtl_uString *sVendor,

rtl_uString *sMinVersion,

rtl_uString *sMaxVersion,

rtl_uString * * arExcludeList,

sal_Int32 nSizeExcludeList,

JavaInfo*** parJavaInfo,

sal_Int32 *nSizeJavaInfo);

javaPluginError jfw_plugin_getJavaInfoByPath(

rtl_uString *sLocation,

rtl_uString *sVendor,

rtl_uString *sMinVersion,

rtl_uString *sMaxVersion,

rtl_uString * *arExcludeList,

sal_Int32 nSizeExcludeList,

JavaInfo ** ppInfo);

javaPluginError jfw_plugin_startJavaVirtualMachine(

const JavaInfo *pInfo,

const JavaVMOption *arOptions,

sal_Int32 nSizeOptions,

JavaVM ** ppVM,

JNIEnv ** ppEnv);

These functions and documentation can be found in udk/jvmfwk/inc/jvmfwk/vendorplugin.h. The source code of the plug-in is located in udk/jvmfwk/plugins/sunmajor/pluginlib.

JavaPreparationTool

Some JREs may require a particular environment in order to run properly. If this environment needs to be prepared before the office process runs, then the JavaPreparationTool along with the OfficeStartScript do the preparations. What is done in particular depends on the respective Java requirements. For example, a JRE from Sun needs to have the LD_LIBRARY_PATH set (Linux/Solaris). This is achieved by running the executable javaldx which prints the respective paths to stdout. The script uses these path to set up the proper LD_LIBRARY_PATH.

The OfficeStartScript may contain multiple JavaPreparationTools which are run one after another. Each one belongs to a JavaVendorPlugin and both parts work on behalf of one vendor. Therefore only one of the JavaPreparationTools must perform the needed environment setup. Otherwise the different executables would interfere with one another.

A JavaPreparationTool uses the JavaFramework to retrieve a JavaInfo object which represents the selected Java which is to be used with the office.

Based on the information contained in the JavaInfo the JavaPreparationTool recognizes if the object originated from the belonging plug-in. If so it can use the information to perform necessary preparations.

If no JRE has been selected yet and Java is enabled, then the JavaPreparationTool must select one. The framework provides an easy function for this.

Please have a look at the source code for javaldx which is located at udk/jvmfwk/plugins/sunmajor/javaenvsetup/javaldx.cxx.

javavendors.xml

Before OOo 2 it was not possible to specify version requirements for JREs of different vendors. The javavendors.xml changes this. It is also possible to have different requirements for different platforms.

This xml file contains information about

versions and vendors of JREs which can be used and which cannot

the locations of the plug-in libraries, which are used to detect JREs

when the file was created or modified.This information is used to determine if a new javavendors.xml was installed by a product update. Then the version requirements may have changed, so that the currently selected JRE may not meet those requirements anymore.

The javavendors.xml is provided by the distributors of the office. It is typically installed in the <OOo>/share/config directory and hence it applies for all users. It is the distributor's decision what Java distributions are supported, that is, what vendors and versions are allowed. This decisions is based on whether the distributors are able to provide the respective VendorSupportExtension (JavaVendorPlugin, JavaPreparationTool etc.), what the required Java functionalities are and if a Java works reliably with the office. The office distributors should make sure that the office was thoroughly tested with the Java versions which the office is supposed to run with.

It may be necessary to adapt the javavendors.xml for each platform. This can be caused if for example a particular version of a JRE works on one platform but does not work on the other one. Then this version can be “excluded” in the javavendors.xml.

Although version and vendor information are provided, the javavendors.xml does not contain hints as to where JREs are located. This knowledge is implemented in the plug-in libraries.

The JavaVendorPlugins and JavaPreparationTool must not access the javavendors.xml. It is intended to be used only by the JavaFramework library.

Here are examples of the javavendors.xml:

<?xml version="1.0" encoding="UTF-8"?>

<javaSelection xmlns="http://openoffice.org/2004/java/framework/1.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<updated>2004-01-30</updated>

<vendorInfos>

<vendor name="Sun Microsystems Inc.">

<minVersion>1.5.0</minVersion>

<maxVersion>1.5.0</maxVersion>

</vendor>

</vendorInfos>

<plugins>

<library vendor="Sun Microsystems Inc.">sunjavaplugin.dll</library>

</plugins>

</javaSelection>

The previous file will effect that only a Sun Java with the version 1.5.0 is used with the office.

<?xml version="1.0" encoding="UTF-8"?>

<javaSelection xmlns="http://openoffice.org/2004/java/framework/1.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<updated>2004-01-30</updated>

<vendorInfos>

<vendor name="Sun Microsystems Inc.">

<minVersion>1.4.2</minVersion>

<excludeVersions>

<version>1.4.2_01a</version>

</excludeVersions>

</vendor>

<plugins>

<library vendor="Sun Microsystems Inc.">sunjavaplugin.dll</library>

</plugins>

</javaSelection>

Here, only Sun Java distributions are supported. A JRE is only used if it has at least a version of 1.4.2 and is not 1.4.2_01a.

<javaSelection xmlns="http://openoffice.org/2004/java/framework/1.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<updated>2004-01-30</updated>

<vendorInfos>

<vendor name="Sun Microsystems Inc.">

<minVersion>1.4.2</minVersion>

<maxVersion>1.5.0</maxVersion>

<excludeVersions>

<version>1.4.3</version>

<version>1.4.3_01</version>

</excludeVersions>

</vendor>

<vendor name="VendorX">

<minVersion>1.4.2</minVersion>

</vendor>

</vendorInfos>

<plugins>

<library vendor="Sun Microsystems Inc.">sunjavaplugin.dll</library>

<library vendor="VendorX">pluginDir/vendorx.dll</library>

</plugins>

</javaSelection>

This example allows Java distributions of two vendors to be used. The order of the library elements determines the preference. Only if the sunjavaplugin.dll does not provide a Java that meets the requirements then vendorx.dll is used to obtain a suitable JRE.

It follows a description of the xml elements. The elements are represented as XPath expressions and it is assumed that the prefix “jf” represents the default namespace as used in the previous examples.

/jf:javaSelection : The root element.

/jf:javaSelection/jf:updated : Represents the date when this file became effective. If the value changes, then the JavaFramework will run the Java configuration again.

/jf:javaSelection/jf:vendorInfos : The element contains information about different vendors and the versions of their Java distributions.

/jf:javaSelection/jf:vendorInfos/jf:vendor The element represents exactly one vendor and the restrictions concerning the respective Java versions. If a vendor element is present then the respective /jf:javaSelection/jf:plugins/jf:library element must also exist.

/jf:javaSelection/jf:vendorInfos/jf:vendor@name: The name of the vendor. It must be same as the Java system property java.vendor.

/jf:javaSelection/jf:vendorInfos/jf:vendor/jf:minVersion : The value of this element represents the minimum Java version. Only JREs with the same or higher version are used with the office.

/jf:javaSelection/jf:vendorInfos/jf:vendor/jf:maxVersion : This is the maximum Java version. JREs with a higher version are not used with the office.

/jf:javaSelection/jf:vendorInfos/jf:vendor/jf:excludeVersions : The elements contains all the versions which are to be disregarded because they do not work with the office properly. If a minVersion element is present, then excludeVersion should not contain versions which are smaller then minVersion. Likewise, if maxVersion is present then excludeVersion should not contain version which are greater then maxVersion.

/jf:javaSelection/jf:vendorInfos/jf:vendor/jf:excludeVersions/jf:version : The value of this element represent exactly one version which is not to be used.

/jf:javaSelection/jf:plugins : Contains all the plug-ins which are used to locate JREs. The order of the contained library children determines the vendor preference. That is, only if the first plug-in does not yield a suitable Java then the second is used and so on.

/jf:javaSelection/jf:plugins/jf:library : Contains the relative URL to the plug-in -library starting from the directory of the executable. If only the name is provided and the library is not found next to executable, then it is tried to locate the library by using search routines particular to the platform. For example, on Windows the PATH environment variable is used and it it looked into the Windows/system32 directory among other things.

This is the respective XML Schema:

<?xml version="1.0" encoding="UTF-8"?>

<schema targetNamespace="http://openoffice.org/2004/java/framework/1.0"

xmlns:jf="http://openoffice.org/2004/java/framework/1.0"

xmlns="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified">

<element name="javaSelection" type="jf:JavaSelectionType">

<unique name="dummy1">

<selector xpath="jf:plugins/jf:library"/>

<field xpath="@vendor"/>

</unique>

<keyref name="dummy2" refer="jf:pluginKey">

<selector xpath="jf:vendorInfos/jf:vendor"/>

<field xpath="@name"/>

</keyref>

<unique name="dummy3">

<selector xpath="jf:vendorInfos/jf:vendor"/>

<field xpath="@name"/>

</unique>

<key name="pluginKey">

<selector xpath="jf:plugins/jf:library"/>

<field xpath="@vendor"/>

</key>

</element>

<complexType name="JavaSelectionType">

<sequence>

<element name="updated" type="date"/>

<element name="vendorInfos" type="jf:VendorInfoType"/>

<element name="plugins" type="jf:PluginType"/>

</sequence>

</complexType>

<complexType name="VendorInfoType">

<sequence>

<element name="vendor" type="jf:VendorType" minOccurs="0"

maxOccurs="unbounded"/>

</sequence>

</complexType>

<complexType name="PluginType">

<sequence>

<element name="library" type="jf:LibraryType" minOccurs="0"

maxOccurs="unbounded"/>

</sequence>

</complexType>

<complexType name="LibraryType">

<simpleContent>

<extension base="string">

<attribute name="vendor" use="required" type="string"/>

</extension>

</simpleContent>

</complexType>

<complexType name="VendorType">

<sequence>

<element name="minVersion" type="string" minOccurs="0"/>

<element name="maxVersion" type="string" minOccurs="0"/>

<element name="excludeVersions" minOccurs="0">

<complexType>

<sequence>

<element name="version" type="string" minOccurs="0"

maxOccurs="unbounded"/>

</sequence>

</complexType>

</element>

</sequence>

<attribute name="name" use="required" type="string"/>

</complexType>

</schema>

The javavendors.xml for OpenOffice.org is located at udk/jvmfwk/distributions/OpenOfficeorg. There are several files, such as javavendors_wnt.xml and javavendors_unx.xml. According to the platform one of them is copied into bin directory, e.g. udk/jvmfwk/unxlngi5/bin/javavendors_ooo.xml. (Have a look at the makefile).

Configuring the Framework

The framework can be configured using bootstrap variables. Information about using bootstrap variables can be found at

http://udk.openoffice.org/common/man/concept/default_bootstrapping.html

and

http://udk.openoffice.org/common/man/concept/micro_deployment.html

For details and latest information about what variables are supported refer to the header file:

udk/jvmfwk/inc/jvmfwk/framework.h

As stated in the framework.h the framework knows two modes, application mode and direct mode. Application mode is used in OOo. It implies that the Java settings are made persistent as is the case with all other settings in OOo. Settings can be stored on behalf of a particular user or for all users. Therefore it must be determined where this data is stored, which is done by specifying the bootstrap parameter UNO_JAVA_JFW_USER_DATA and UNO_JAVA_JFW_SHARED_DATA. In an office installation these parameter are determined in the jvmfwk3.ini (Windows) or jvmfwk3rc (UNIX, Linux, etc.). The file belongs to the jvmfwk3.dll or jvmfwk3.so respectively which are the libraries containing the framework. Lets have a look at this file:

[Bootstrap]

BaseInstallation=${$ORIGIN/bootstrap.ini:BaseInstallation}

UserInstallation=${$ORIGIN/bootstrap.ini:UserInstallation}

UNO_JAVA_JFW_USER_DATA=$UserInstallation/user/config/javasettings_${_OS}_${_ARCH}.xml

UNO_JAVA_JFW_SHARED_DATA=$BaseInstallation/share/config/javasettings_${_OS}_${_ARCH}.xml

UNO_JAVA_JFW_VENDOR_SETTINGS=$BaseInstallation/share/config/javavendors.xml

UNO_JAVA_JFW_CLASSPATH_URLS=${${$ORIGIN/uno.ini:PKG_UserUnoFile}:UNO_JAVA_CLASSPATH} ${${$ORIGIN/uno.ini:PKG_SharedUnoFile}:UNO_JAVA_CLASSPATH} $ORIGIN/classes/jurt.jar $ORIGIN/classes/ridl.jar $ORIGIN/classes/java_uno.jar $ORIGIN/classes/sandbox.jar $ORIGIN/classes/bsh.jar $ORIGIN/classes/classes.jar $ORIGIN/classes/commonwizards.jar $ORIGIN/classes/docbook.jar $ORIGIN/classes/htmlsoff.jar $ORIGIN/classes/java_uno_accessbridge.jar $ORIGIN/classes/js.jar $ORIGIN/classes/juh.jar $ORIGIN/classes/jut.jar $ORIGIN/classes/letter.jar $ORIGIN/classes/officebean.jar $ORIGIN/classes/query.jar $ORIGIN/classes/report.jar $ORIGIN/classes/ScriptFramework.jar $ORIGIN/classes/ScriptProviderForBeanShell.jar $ORIGIN/classes/ScriptProviderForJava.jar $ORIGIN/classes/ScriptProviderForJavaScript.jar $ORIGIN/classes/tutorial.jar $ORIGIN/classes/unoil.jar $ORIGIN/classes/web.jar $ORIGIN/classes/XFlatXml.jar $ORIGIN/classes/xmerge.jar $ORIGIN/classes/XMergeBridge.jar $ORIGIN/classes/XSLTFilter.jar $ORIGIN/classes/XSLTValidate.jar $ORIGIN/classes/xt.jar $ORIGIN/classes/activation.jar $ORIGIN/classes/agenda.jar $ORIGIN/classes/aportisdoc.jar $ORIGIN/classes/avmedia.jar $ORIGIN/classes/email.jar $ORIGIN/classes/fax.jar $ORIGIN/classes/pexcel.jar $ORIGIN/classes/pocketword.jar $ORIGIN/classes/mail.jar

As one can see the UNO_JAVA_JFW_USER_DATA and UNO_JAVA_JFW_SHARED_DATA use the same “user installation” and “base installation” as OOo itself. The _OS macros expand to the name of the operating system and _ARCH expands to the architecture. On Linux the expanded strings could be:

UNO_JAVA_JFW_USER_DATA=file:///home/username/.OpenOffice/user/config/javasettings_Linux_x86.xml

UNO_JAVA_JFW_SHARED_DATA=file:///opt/openoffice/share/config/javasettings_Linux_x86.xml

For Windows the value could be

UNO_JAVA_JFW_DATA=file:///c:/Documents%20And%20Settings/user/Application%20Data/StarOffice8/user/config/javasettings_Windows_x86.xml

UNO_JAVA_JFW_SHARED_DATA=file:///c:/Program%20Files/StarOffice%208/share/config/javasettings_Windows_x86.xml

What's important here is that the paths have to be valid file URLs. That explains the use of “%20” for spaces. One could specify a completely different file here with the exception that is has to have the extension “xml”. The file is created by the framework itself.

UNO_JAVA_JFW_VENDOR_SETTINGS determines the javavendors.xml files. The value must also be a file URL. In case of OOo the expanded value points into the actual installation. As with the previous parameters one could specify a different xml file as long as the content is valid.

UNO_JAVA_JFW_CLASSPATH_URLS contains URLs of jar files which shall be put in the class path. The URLs must be separated by spaces. The value

${${$ORIGIN/uno.ini:PKG_UserUnoFile}:UNO_JAVA_CLASSPATH}

expands to a string of file URLs of jar files which have been added by the unopkg tool or the package manager (menu extras, item package manager).

The jvmfwk.[ini|rc] can be adapted by different office distributors to fit their needs. For StarOffice/OpenOffice the contents of the file are determined in the project scp. and the file is created during installation.

The direct mode of the framework is used within the build environment. Java is needed there in order to register Java UNO components with the regcomp tool. Direct mode means that no settings are written or read. That is the parameters UNO_JAVA_JFW_USER_DATA and UNO_JAVA_JFW_SHARED_DATA are not used. In the build environment the framework library is in the library directory. In the same directory is a jvmfwk3.ini or jvmfwk3rc so it can be located by the framework. The contents read:

[Bootstrap]

UNO_JAVA_JFW_ENV_JREHOME=true

UNO_JAVA_JFW_ENV_CLASSPATH=true

UNO_JAVA_JFW_VENDOR_SETTINGS=javavendors.xml

In the build environment the environment variables JAVA_HOME and CLASSPATH are set and the parameter UNO_JAVA_JFW_ENV_JREHOME=true and UNO_JAVA_JFW_ENV_CLASSPATH=true

tell the framework to use these variables.

UNO_JAVA_JFW_VENDOR_SETTINGS specifies the javavendors.xml file that is to be used. In this case it is a relative URL.

Another example for using the direct mode is the SDK. The SDK uses the libraries from the office installation. When an SDK is configured then one specifies what Java is to be used. This Java shall then be used for all task which require Java including registration of UNO components. In order to override the java settings of the office the script which prepares the SDK environment sets these environment variables:

UNO_JAVA_JFW_JREHOME=<file_URL_to_selected_Java>

UNO_JAVA_JFW_ENV_CLASSPATH=true

UNO_JAVA_JFW_VENDOR_SETTINGS=<file_URL_to_javavendors.xml_from_OOo>

By setting UNO_JAVA_JFW_JREHOME the framework is switched into direct mode and the office settings are disregarded.

Page11 of 11

Joachim Lingner

2004-03-08T14:54:26