Options Dialog/Java Panel

OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Joachim Lingner	April 15, 2004	Final
Conforms to	
Applies to	All applications
Task ID(s)	i20052
Category	Feature

Abstract

A new panel in the options dialog will be introduced allowing to determine what Java shall be used by OpenOffice.org. A set off additional arguments which are passed to the selected Java VM during its creation can be specified by the user.

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

	Name	E-mail Address
User Experience	Christian Jansen (CJ)	
Development	Joachim Lingner (JL) Hans-Peter Burow (PB)	joachim.lingner@sun.com pb@openoffice.org
Quality Assurance	Thorsten Martens (TM)	Thorsten.Martens@sun.com
Documentation	Uwe Fischer (UF)	Uwe.Fischer@sun.com

Approved for Implementation

	Approved by	Date
User Experience	Christian Jansen	04/16/2004
Development	Hans-Peter Burow	04/16/2004
Quality Assurance	Thorsten Martens	04/16/2004
Documentation	Uwe Fischer	04/16/2004
String Review	Elizabeth Matthis	04/29/2004 and 21.07.04 and 23.07.04

Document Change History

Rev. Level	Change	Initials	Date
1.0	Initial version	JL	04/16/2004
2.0	Added string to string list,clarified behaviour when adding an archive to the class path which has already been added	JL	04/22/2004
3.0	String tables updated	JL	04/29/2004
3.1	Fixed wrong paragraph numbering	JL	05/19/2004
4	Issue 31411	JL	07/13/2004
5	Issue 31947	JL	07/22/04

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	1

4	Requirements and Dependencies	2

4.1	Requirements	2

4.2	Technical Dependencies	2

5	Competitive Analyses	2

6	Detailed Specification	3

6.1	Placement of new Java Panel	3

6.2	Automatic selection of Java installation	3

6.3	Switching Java On/Off	3

6.4	Manually Selecting a Java from a List	4

6.5	Manually Selecting a Java by Using a File Dialog	5

6.6	Providing Start Parameter	6

6.7	Class Path	7

6.8	Quitting the Options Dialog	8

6.9	Error Conditions	9

6.9.1	No Java Found	9

6.9.2	Invalid Java Settings	9

6.9.3	Java Disabled	9

6.9.4	Creation of Java Virtual Machine failed	10

6.9.5	Restart Needed	10

7	Future Tasks	11

8	Notes	11

9	References	11

Glossary

Term	Description
JVM	Short for Java Virtual Machine
Java panel	The part of the options dialog that contains the Java settings
Java framework	The Java framework consists of a bunch of libraries, executables, and configuration files whose job is to detect a suitable Java and run Java.
JRE	Java runtime environment

Motivation

For OOo 2.0 it is planned to use native installers. The setup of OOo 1.1 allows to choose a Java installation which is later used by the office. The native installers will not support this feature. Therefore, these setting should be done from a running office, preferably the options dialog.

In OO1.1 there is no official way to pass additional arguments to the Java Virtual Machine (JVM). This is for example necessary to debug Java components.

User Scenarios

An office is installed on a system that does not have a Java. To prevent the office to search for a suitable Java a flag can be set in the Java panel that indicates that no Java is to be used.

When the office needs Java it attempts to find a suitable Java unless this has been done successfully before. If now a newer Java is available then users may wish to have the office use it. In case the office once located a suitable Java then it will continue to use it and disregard a subsequently installed Java. Then a user may use the Java panel to select the newer Java manually.

A user may wish to set a Java which was not automatically found. For example, the detection of Java installations is done by software components (libraries) which may be supplied by a third party. These libraries may not find all Java installations. Then a user has the choice to search for a particular Java installation through a file dialog. This dialog will be accessed through the Java panel.

A Java installation may be damaged or was removed. When the office finds a Java it is not guaranteed that the Java functions properly. If now the office uses Java dependent functionality then the creation of the JVM may fail. Then the user would be prompted with a message, saying that something is wrong and he may choose a different Java. If the user clicks the “choose” button then the options dialog shall come up presenting the Java panel.

Goals

The main goals are:

compensate for loss of functionality (Java settings) provided by setup of OO 1.1

provide custom Java startup parameters

Requirements and Dependencies

Requirements

The requirements arise from Q-PCD i20052.

Technical Dependencies

The logic of finding and selecting a suitable Java needs to be build into the office. This solution should take into account that there are Java distributions of several vendors. OO 1.1 is not designed to use Java distributions of different vendors, rather it relies on Java distributions from Sun Microsystems Inc.

Competitive Analyses

Applications which internally use Java and are not written themselves in Java are rare. One example, however, is Eclipse. The following pictures show the Java related dialogs:

Because Eclipse uses Java differently than OOo the concepts of how a Java is selected cannot be compared.

Detailed Specification

Please note: Mock-ups used in this document shall only give an idea of the dialogs. The final appearance and especially the strings may be different. As for the strings, the strings specified in the string tables are decicive.

Placement of new Java Panel

The panel shall be reached by selecting the item StarOffice/Java in the tree view of the options dialog (Figure 1)

.

Automatic selection of Java installation

In OOo1.1 a user selects a Java during the setup. This Java is later used by the office. With OOo2.0 users do not need to select a Java manually. When Java is needed then the office determines itself what Java is to be used. This is done by the Java framework which is not covered in this document.

Switching Java On/Off

The Java panel will have a check box, which effects that Java is not used when it is not checked. In OOo 1.1 there is already a checkbox on the StarOffice/Security panel. This checkbox will be removed and is functionally replaced by the checkbox on the Java panel.

If the user switches Java off, then all other ui elements in this panel which are used to provide Java related settings will be disabled. That is, the table as well as the buttons to the right are disabled. Also the label underneath shall be disabled.

The settings made before the “Use Java” check box was unchecked remain intact and are saved if the user presses the “Ok” button.

Manually Selecting a Java from a List

In the Java panel there will be a list where each entry represents a Java installation found on the system or on a mapped / mounted network drive. The process of finding the Java locations is performed by the Java framework. The list should display on each line these information:

selected/not selected (there can only be one)

Vendor

Version

Features, such as accessibility

Although the figure contains check boxes in the first column of the table, it shall contain radio button or the check boxes shall behave like radio buttons.

Figure 1 New Java Options panel

String list

Item	English	German	Comments
Title Bar	Java	Java	
Tree View Item	Java	Java	
Label	Java options	Java Optionen	
Check Box Label	~Use a Java runtime environment	~Eine Java-Laufzeitumgebung (Java runtime environment) verwenden	
Table Caption Label	~Java runtime environments (JRE) already installed:	~Bereits installierte Java-Laufzeitumgebungen (JRE):	
Column Caption Label	Vendor	Hersteller	
Column Caption Label	Version	Version	
Column Caption Label	Features	Besondere Merkmale	
Label	Location:	Speicherort:	
Button Label	~Add...	~Hinzufügen...	
Button Label	~Parameters...	~Parameter...	
Button Label	~Class Path...	~Class Path...	
Table Cell Label	with accessibility support	mit Unterstützung der Zugänglichkeit	This label appears in the features column if the belonging JRE supports accessibility

In the Java Panel the currently used JRE is initially marked by the radio button in the first column. By checking a different radio button and pressing “Ok” the Java represented by that line that contains the checked radio button will be used in the future.

Strings like “SDK”, “JRE” are not displayed. The caption of the listbox should indicate, that the listbox displays Java runtimes.

The location of the Java installation is an important information. Because the paths can be very long the location of the Java which is currently selected in the list shall be displayed beneath the list. A JRE is said to be selected if the radio button in the same line is selected. The location string changes according to the currently selected item..

The items in the list are not ordered and the list need not support ordering according to column values. The order of appearance is mainly determined by the java framework which supplies the information about available JREs.-

A JRE must meet certain requirements (e.g. minimum version) in order to show up in the list. What these requirements are is determined by the Java framework.

Manually Selecting a Java by Using a File Dialog

The JREs displayed in the list of the Java panel are detected by the Java framework. This framework does not guarantee to find all available Java installation. By using the file dialog one can navigate to the location of a JRE. After closing the file dialog by clicking “Ok”, the just selected JRE shall show up at the top of the list and the list item shall be selected. If the alleged JRE directory is actually no JRE then a message box appears::

Message type: info

String list

Item	English	German	Comments
Title Bar	Select a Java Runtime Environment	Java-Laufzeitumgebung auswählen	
Label	The folder you selected does not contain a Java runtime environment. Please select a different folder.	Der von Ihnen gewählte Order enthält keine Java-Laufzeitumgebung. Bitte wählen Sie einen anderen Ordner.	
Button Label	OK	OK	

The selected directory may be a JRE but has the wrong version. In this case this message should show up:

Message type: info

String list

dialog title	Different JRE Required	Andere JRE ist erforderlich	
Label	The Java runtime environment you selected is not the required version. Please select a different folder.	Die ausgewählte Java-Laufzeitumgebung hat nicht die erforderliche Version. Bitte wählen Sie einen anderen Ordner.	
Button Label	OK	OK	

In both cases the dialog shall remain open until the user chooses a proper JRE or clicks the cancel button.

If the dialog is closed and the selected folder was recognized as valid JRE then it is added to the end of the list of JREs in the Java Panel and the belonging radio button is selected. Hence a JRE chosen by this dialog will automatically become the “selected” JRE unless the user changes the selection.

In OOo1.1 the “Browse...” button in the Java setup had three purposes, to select a JRE independent of version requirements, to select a JRE from a vendor other than Sun Microsystems Inc. and to select a Java that has not been found (e.g. is not present in the list).

The first two issues arouse from the fact that the setup could only make sure that Sun JREs are detected properly. Also the version requirements were only valid for Sun JREs. With the upcoming Java framework these problems are solved. If an office distributor chooses to support particular JREs from different vendors then he must adapt the Java framework accordingly.

In OOo2.0 the sole purpose of the “Browse...” button is to locate JREs which have not been found by the Java framework.

Providing Start Parameters

Some user may wish to pass parameters to the JVM. These parameters may be different from vendor to vendor and even between versions of one vendor.

To enter these parameters a list shall be contained in a separate panel or dialog. This dialog should appear if a user clicks the “Parameters” button on the Java panel. The user may enter a new argument in a text field and click the “Assign” button. Then the text field entry is put into the list and the text field clears. The parameter have to be entered exactly the same way as one would do at the command prompt. For example, in order to enable debugging one could enter:

-Xdebug

and

-Xrunjdwp:transport=dt_socket,server=y,address=8000

In case the parameter string contains spaces then the string must not be put into quotation marks as is done in shells. Also no escaping of the spaces is allowed. For example, a Java program may be started in a shell:

java “-Dpathproperty=c:\My Settings” MyApp

The parameter “-Dpathproperty=c:\My Settings” would be entered as

-Dpathproperty=c:\My Settings

in the parameters dialog.

An example of how a parameter is specified should be contained in the dialog. The example should be placed below the listbox that shows all added parameters.

For easier editing of already assigned parameters, that is those which are contained in the list, it shall be possible to move them to the text field (where the parameters are added) by double - clicking the respective line. Then the list entry is copied into the text field and overwrites its current entry if existing.

When a user modifies the start parameters and presses ok and a Java Virtual Machine is running then a message box shall pop up saying that the office needs to be restarted for the new settings to take effect. See the chapter “Error Conditions” for the respective message box.

This dialog shall look like in figure 2:

Figure 2 Users can add start parameters to the JRE

String list

Item	English	German	Comments
Title Bar	Java Start Parameters	Java Startparameter	
Text Edit Label	Java start ~parameter-	Java Start~parameter	
Text Edit Label	Assig~ned start parameters	Zuge~wiesene Startparameter	
Button Label	~Assign	~Zuweisen	
Button Label	~Remove	~Entfernen	
Button Label	OK	OK	
Button Label	Cancel	Abbrechen	
Button Label	Help	Hilfe	
Label	For example: -Dmyprop=c:\program files\java	Zum Beispiel: -Dmyprop=c:\program files\java	

The”Remove” button is only enabled if a line in the listbox is selected. Clicking the button will remove the entry.

The settings made in this dialog are not bound to a particular JRE. That is, they are effective for any JRE that may be used.

Class Path

In OO 1.1 the options dialog contains a text field for the class path in the panel StarOffice/Security. It also contains a “browse” button which opens a dialog which is used to compile a list of jar files and directories. The selected files and directories are then added to the class path when a Java VM is started. These UI elements are necessary since users need to specify jar files or classes which are used for JDBC database access as well as for applets.

In OOo 2.0 the class path related UI elements will be removed from the security panel. Setting the class path shall then be possible from the Java panel. Therefore, the Java panel shall contain a button, labeled “Class Path”, which opens up a dialog. From here users can add *.jar & *.zip files by clicking 'Add Archives...'. This shall open a file picker with the following default settings:

Files of type shall be 'Archives (*.jar; *.zip)' (this is the default) & All Files (*.*)

By default the file picker shall show to the location where the selected Java is installed.

Adding a folder shall be possible by clicking 'Add Folder...' - this shall open a Folder browse dialog pointing by default to the location where the selected Java is installed.

When a user modifies the class path and presses ok and a Java Virtual Machine is running then a message box shall pop up saying that the office needs to be restarted for the new settings to take effect. See the chapter “Error Conditions” for the respective message box.

Figure 3 Renewed Class Path dialog

String list

Item	English	German	Comments
Title Bar	Class Path	Class Path	
List Box Label	Assigned folders and archives	Zugewiesenen Ordner und Archive	
Button Label	~Add Archive...	~Archiv hinzufügen	
Button Label	Add ~Folder...	~Ordner hinzufügen	
Button Label	~Remove	~Entfernen	
Button Label	OK	OK	
Button Label	Cancel	Abbrechen	
Button Label	Help	Hilfe	

If an archive or folder is being added that is already contained in the list of assigned paths then the action is ignored silently. That is, nothing is added to the list.

The class path is not bound to a particular JRE. That is, it is effective for any JRE that may be used.

Quitting the Options Dialog

The user can leave the dialog by clicking the “Cancel” or “Ok” button. In the first case all changes made in the Java panel are discarded. In the latter case the changes are made persistent. Then there are two cases in which the user needs to be notified:

A Java VM is running. Currently it is not supported to have multiple VMs in one process. Once a VM was started it lives on until the office is terminated. Hence the new settings do not influence the running VM.

The newly selected JRE requires a prepared environment which has to be done prior to running the office. This is currently done on Solaris and Linux where the office is started by a script which performs additional preparatory work. In that case the VM from that JRE must not be started in this process. If no VM is running already then no Java will be available in this process.

In both cases a information message shall be presented to the user:

Message type: info

String list

dialog title	Restart Required	Neustart ist erforderlich	
Label	You have to restart %PRODUCTNAME for the changes to take effect.	Die Änderungen werden erst wirksam nachdem Sie %PRODUCTNAME neugestartet haben.	

Error Conditions

No Java Found

If no Java has been configured before and the office requires Java at one point then the com.sun.star.java.JavaVirtualMachine service will attempt to find a suitable Java installation. If that fails then this error occurs.

Error type: Warning.

String list

dialog title	JRE Required	JRE ist erforderlich	
Label	%PRODUCTNAME requires a Java runtime environment (JRE) to perform this task. Please install a JRE and restart %PRODUCTNAME.	%PRODUCTNAME benötigt eine Java-Laufzeitumgebung (JRE), um diese Aufgabe durchführen zu können. Bitte installieren Sie eine JRE und starten Sie dann %PRODUCTNAME neu.	
Button	OK	OK	

Invalid Java Settings

The distributor of an office can determine requirements as to what Java is to be used. If these settings have changed, because the respective file which contains these requirements, has been overwritten (e.g.during a product update) then the current Java selection is regarded as invalid. Changing the Java requirements during a product update could lead to problems with already existing Java components. Therefore this should not be done.

Error type: Warning

String list

dialog title	Select JRE	JRE auswählen	
Label	The %PRODUCTNAME configuration has been changed. Under Tools - Options - %PRODUCTNAME - Java, select the Java runtime environment you want to have used by %PRODUCTNAME.	Die %PRODUCTNAME-Konfiguration wurde geändert. Unter Extras - Optionen - %PRODUCTNAME - Java wählen Sie eine Java-Laufzeitumgebung aus, die von %PRODUCTNAME benutzt werden soll.	
Button Label	OK	OK	

Java Disabled

It is possible to switch off the use of Java in the Java panel of the options dialog. If this was done and Java is needed, then this error occurs. The dialog shall contain a button which allows the user to switch on the use of Java right from this error dialog. If this button is used then the office shall try to create Java again. Depending on the selected Java a “Restart Needed” error may occur.

Error type: Question

String list

dialog title	Enable JRE	JRE aktivieren	
Label	%PRODUCTNAME requires a Java runtime environment (JRE) to perform this task. However, use of a JRE has been disabled. Do you want to enable the use of a JRE now?	%PRODUCTNAME benötigt eine Java-Laufzeitumgebung (JRE), um diese Aufgabe durchführen zu können. Jedoch ist die Benutzung einer JRE deaktiviert. Möchten Sie die Benutzung von einer JRE jetzt aktivieren?	The use of JRE is enabled/disabled by the checkbox in which has the label: “Use a Java runtime environment”.
Button	Yes	Ja	Default
Button	No	Nein	

Creation of Java Virtual Machine failed

Creation of a VM failed. This can be caused by a broken Java installation. Experience showed that in this case it is dangerous to attempt to create a VM a second time. Therefore we will recommend to restart the office after choosing a different Java.

Error type: Error.

String list

Dialog title	JRE is Defective	JRE ist defekt	
Label	%PRODUCTNAME requires a Java runtime environment (JRE) to perform this task. The selected JRE is defective. Please select another version or install a new JRE and select it under Tools - Options - %PRODUCTNAME - Java.	%PRODUCTNAME benötigt eine Java-Laufzeitumgebung (JRE), um diese Aufgabe durchführen zu können. Die ausgewählte JRE ist defekt. Bitte wählen Sie eine andere Version oder installieren Sie eine neue JRE und aktivieren Sie sie unter Extras - Optionen - %PRODUCTNAME - Java.	
	OK	OK	

Restart Needed

Some JREs need to have a prepared environment, which needs to be set up before the office runs. If someone selects such a JRE, then it must not be started in the same office process because that Java may crash the office.

Error type: Warning

String list

Dialog title	Restart Required	Neustart ist erforderlich	
Label	For the selected Java runtime environment to work properly, %PRODUCTNAME must be restarted. Please restart %PRODUCTNAME now.	Damit die ausgewählte Java-Laufzeitumgebung richtig funktioniert, muss %PRODUCTNAME neugestartet werden. Bitte starten Sie %PRODUCTNAME neu.	Error message “Restart needed”
	OK	OK	

Restart Needed for Parameters

Java Parameters, which can be added by the Parameter and Class Path dialogs, have to be passed to the Java VM when it is being created. If there is a running VM then changing the parameters will not be effective. Only after a restart of the office the new parameters to the VM when it is started again.

Error type: Warning

String list

Dialog title	Restart Required	Neustart ist erforderlich	
Label	You have to restart %PRODUCTNAME so the new or modified values can take effect. Please restart %PRODUCTNAME now.	Damit die geänderten Werte benutzt werden, muss %PRODUCTNAME neugestartet werden. Bitte starten Sie %PRODUCTNAME neu.	
	OK	OK	

Future Tasks

<If there are features which couldn't be implemented but have to be implemented in the future. State these in here with a description why the feature couldn't be implemented right now.>

Notes

<Questions will arise during the writing of the specification. State these in here.>

References

<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.>

Options Dialog/Java Panel

Page 12

http://specs.openoffice.org/appwide/java/java_options_dialog_spec.sxw

Joachim Lingner

2004-03-24T10:56:31

Matthis Elizabeth