Scripting Framework Error Handling
OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Noel Power	10rd June 2004	Draft
Conforms to	
Applies to	Every Module of OpenOffice.org
Task ID(s)	i25260
Category	Enhancement

Abstract

The development of the Scripting Framework allows the user to develop macros in languages other than OpenOffice.org Basic. This document describes how errors encountered by ScriptProviders will be handled.

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

	Name	E-mail Address
User Experience	Bettina Haberer	bettina.haberer@sun.com
Development	Noel Power Tomas O'Connor	Noel.power@sun.com tomas.oconnor@sun.com
Quality Assurance	Jörg Skottke	Joerg.skottke@sun.com
Documentation	This specification does not have a documentation impact.	

Approved for Implementation

	Approved by	Date
User Experience	Bettina Haberer	16/06/04
Development	Noel Power	10/06/04
Development	Tomas O'Connor	16/06/04
Quality Assurance	Jörg Skottke	17/06/06
Documentation	This specification does not have a documentation impact.	
String Review	Paul Compton	17/06/04

Document Change History

Rev. Level	Change	Initials	Date
0.1	Initial draft for discussion	NP	10/06/04
0.2	Update with feedback from User Experience	TOC	16/06/04
1.0	Spec iTeam approved	TOC	17/06/04

Contents

1	Motivation	4

2	User Scenarios	4

2.1	Language Specific errors	4

2.2	Scripting Framework errors	4

3	Goals	5

4	Requirements and Dependencies	5

4.1	Requirements	5

4.2	Technical Dependencies	5

5	Competitive Analyses	5

6	Detailed Specification	6

6.1	Language Specific Errors	6

6.2	Scripting Framework Errors	7

6.3	ScriptProviders which do not have IDE support (Java/Python)	8

6.4	Error Type	8

6.5	String List	8

7	API impacts for Error detection/propagation	10

8	Notes	11

9	References	11

Glossary

Term	Description
Scripting Framework	An extensible framework provided by OpenOffice.org for the execution of code written in different languages such as Basic, JavaScript, BeanShell and Python.
Basic module	An object which contains OpenOffice Basic macros.
Basic library	An object which contains OpenOffice Basic modules or dialogs.
Script Library	An object that directly or indirectly contains macros (examples include OpenOffice Basic libraries and modules, or the equivalent for other Scripting Framework languages).
ScriptProvider	A component supporting the ScriptingFramework interfaces that provides for execution and display of scripts written in a specific language.
Rhino	Rhino an embeddable open-source implementation of JavaScript written entirely in Java. More defaults can be found at http://www.mozilla.org/rhino/
BeanShell	BeanShell is a small, open source, embeddable, Java source interpreter with object scripting language features, written in Java. It is used in the scripting framework to allow macros to be written in Java without having to precomile them. More details on the interpreter can be found at http://www.beanshell.org/

Motivation

The development of the Scripting Framework provides the user with the option of writing macros in languages other than OpenOffice Basic. Currently when errors occur for languages other than Basic these errors occur silently. The exception to this case is where the script is executed from within the IDE by pressing the Run button. Additionally at the present time two of the ScriptProviders do not include built in IDE support (Python and Java). In this case no error information is provided to the user at all.

The purpose of this specification is to address this issue and provide any available error information to the user. Additionally where an internal IDE is present the location of the error in the script will be indicated. Due to the limited resources available to the project and priority constraints a low cost/minimal effort solution is required.

User Scenarios

Errors generated by the ScriptingFramework can be divided into two classes:

Language Specific errors

These errors are generated by the ScriptProvider and are specific to the scripting language.

User A writes a macro and binds that macro to an event ( for example a menu item ). The IDE used to write that macro has been closed. User A invokes the macro and an error occurs. The user should be presented information related to the error in dialog box, the IDE should be raised and indicate on which line the error occurred.

User A has an IDE for one of the supported scripting language open and is editing a script. To test the script user presses the Run button. The user should be presented information related to the error in dialog box. In the IDE the line where the error occurred should be highlighted.

User A has an IDE for one of the supported scripting language open and is editing a script. The script is bound to an event ( for example a menu item ), User A invokes the script not from the IDE but from the binding. The IDE will present to the user detail of the error and indicate on which line the error occurred.

An error that occurs in a script escapes the ScriptProvider for example an uncaught exception generated from the script code. In this case an error will be presented to the user with whatever information is available from the exception.

Scripting Framework errors

These errors relate to problems with finding or executing the script and are not specific to the code of the particular script:

User A receives a document containing a macro written in Python, the document contains a binding to invoke the script via a button present as a form control. User A's installation doesn't have Python support but presses the form control button. User A will be presented with a modal error Dialog detailing the reason for failure to execute the script contained in the document.

Goals

To provide the user with useful feedback when an error occurs.

Note: it is not the intention of this specification to specify the individual error types for different scripting languages. The intention is to provide a specification of how, when and the format of the error information to be presented to the user.

Requirements and Dependencies

Requirements

The current error handling functionality for Basic must remain.

When an error occurs any useful contextual error information available from the ScriptProvider must be presented to the user.

When an error occurs in a supported scripting language and a supported/integrated IDE for that scripting langauge exists, the line causing the error should be indicated to the user in the IDE.

Technical Dependencies

The quality of error information available is dependent on the ScriptProviders. The additional languages supported for OO2.0 are Java, BeanShell, JavaScript and Python. The ScriptProvider implementations are based on the open source core language runtimes for those languages which are sourced externally. As such, the range, type, scope and the textual content for those errors are not under the control of this project.

Additionally any external IDE's for example the Rhino Debugger which is used as the IDE for JavaScript will have their own format and style for presenting errors to the user. For ease of implementation the de-facto behavior of a supported IDE will be used to present error information to the user.

Where no localization is present for the error information available from a ScriptProvider it will be presented to the user in the available/default language. This is consistent with the decision by the pteam that external IDEs integrated for ScriptProviders do not have to be localized in OpenOffice.org 2.0.

Competitive Analyses

For the purposes of this specification the error handling behaviour of OpenOffice.org Basic has been studied and the behaviour for the other Scripting Framework languages will attempt to mimic this behaviour as much as possible.

Detailed Specification

Language Specific Errors

User Scenario 1

User A writes a macro and binds that macro to an event ( for example a menu item ). The IDE used to write that macro has been closed. User A invokes the macro and an error occurs. The user should be presented information related to the error in dialog box, the IDE should be raised and indicate on which line the error occurred. The dialog that is presented to the user is shown below:

Illustration 1BeanShell error message

When [OK] is pressed the IDE shall be raised and given focus with the line where the error occurred indicated to the user The illustration below shows this behaviour for BeanShell:

l Illustration 2IDE (Beanshell) raised, error line indicated

User Scenario 2

User A has an IDE from one of the supported ScriptProviders open and is editing a script. To test the script user presses the Run button. The user is presented information related to the error in dialog box. In the IDE the line where the error occurred should be highlighted.

When Run is pressed from the IDE, the IDE handles the error in its default way eg. in the case of the BeanShell IDE a Java Dialog is raised as shown here:

Illustration 3IDE specific error

User Scenario 3

User A has an IDE for one of the supported ScriptProviders open and is editing a script. The script is bound to an event ( for example a menu item ), User A invokes the script not from the IDE but from a binding. The IDE will present to the user detail of the error and indicate on which line the error occurred.

If the IDE for a script is open and that same script is invoked from a binding ( not from the IDE ) then behavior shall be as if the Run button had been pressed from the IDE, that is the IDE specific error handling shall be displayed.

User Scenario 4

An error that occurs in a script escapes the ScriptProvider for example an uncaught exception generated from the script code. In this case an error will be presented to the user with whatever information is available from the exception:

Illustration 4Exception not caught by ScriptProvider

Scripting Framework Errors

User Scenario 1

User A receives a document containing a macro written in Python, the document contains a binding to invoke the script via a button present as a form control. User A's installation doesn't have Python support but presses the form control button. User A will be presented with a modal error Dialog detailing the reason for failure to execute the script contained in the document:

Illustration 5ScriptingFramework error

ScriptProviders which do not have IDE support (Java/Python)

For the Java and Python languages the error dialogs displayed are the same with the respective language indicated. As there are no IDEs involved none of the IDE error handling behavior described above is relevant.

Error Type

As indicated above, each language has its own types and classes of errors. Where it is possible to distinguish that an error is of a particular type this will by indicated by a field labelled Type: in the Error dialog. Examples of this are shown in the illustrations above.

String List

Item	English	German	Comments
Dialog Title	%PRODUCTNAME Error	%PRODUCTNAME Fehler	%PRODUCTNAME is a placeholder and will be replaced at runtime
Text	The scripting language %LANGUAGENAME is not supported.	Die Skriptsprache %LANGUAGENAME wird nicht unterstützt.	%LANGUAGENAME is a placeholder and will be replaced at runtime
Text	An error occurred while running the %LANGUAGENAME script %SCRIPTNAME.	Ein Fehler trat während der Ausführung von %LANGUAGENAME script %SCRIPTNAME auf.	%LANGUAGENAME and %SCRIPTNAME not to be translated, these are placeholders.
Text	An exception occurred while running the %LANGUAGENAME script %SCRIPTNAME.	Ein Ausnahmefehler trat während der Ausführung von %LANGUAGENAME script %SCRIPTNAME auf.	%LANGUAGENAME and %SCRIPTNAME not to be translated, these are placeholders.
Text	A Scripting Framework error occurred while running the %LANGUAGENAME script %SCRIPTNAME.	Ein Scripting Framework Fehler trat während der Ausführung von %LANGUAGENAME script %SCRIPTNAME auf.	%LANGUAGENAME and %SCRIPTNAME not to be translated, these are placeholders.
Text	An error occurred while running the %LANGUAGENAME script %SCRIPTNAME at line: %LINENUMBER.	Ein Fehler trat während der Ausführung von %LANGUAGENAME script %SCRIPTNAME in Zeile: %LINENUMBER auf.	%LANGUAGENAME, %SCRIPTNAME and %LINENUMBER are placeholders and will be replaced at runtime.
Text	An exception occurred while running the %LANGUAGENAME script %SCRIPTNAME at line: %LINENUMBER.	Ein Ausnahmefehler trat während der Ausführung von %LANGUAGENAME script %SCRIPTNAME in Zeile: %LINENUMBER auf.	%LANGUAGENAME, %SCRIPTNAME and %LINENUMBER are placeholders and will be replaced at runtime.
Text	A Scripting Framework error occurred while running the %LANGUAGENAME script %SCRIPTNAME at line: %LINENUMBER.	Ein Scripting Framework Fehler trat während der Ausführung von %LANGUAGENAME script %SCRIPTNAME in Zeile: % LINENUMBER auf.	%LANGUAGENAME, %SCRIPTNAME and %LINENUMBER are placeholders and will be replaced at runtime.
Text	Type:	Typ:	
Text	Message:	Meldung:	
Text	A file of the proposed name already exists.	Eine Datei mit diesem Namen existiert bereits.	
Text	Access to this file is denied.	Der Zugriff auf diese Datei wird verweigert.	##PC: Have I understood this correctly?
Text	The requested file was not found.	Die Datei wurde nicht gefunden.	

API impacts for Error detection/propagation

How do we distinguish between an error thrown from the Framework and an error raised by the script language itself? In general a Framework error which is certainly anything thrown by the Framework APII before resolution of the script to an XScript object.

There is a possibility of a Framework error occurring during the invoke stage prior to the point where control is passed to the language runtime itself. The framework code will need to be reviewed to ensure that the existing exception specification is obeyed here. I think the specification for the invoke method on XScript is generic enough at this point.

any invoke(

[in] sequence<any> aParams,

[out] sequence<short> aOutParamIndex,

[out] sequence<any> aOutParam ) raises(

::com::sun::star::lang::IllegalArgumentException,

::com::sun::star::script::CannotConvertException,

::com::sun::star::reflection::InvocationTargetException);

where the first two exceptions can definitely be deemed to indicate a ScriptingFramework error. The third possible exception type InvocationTargeException is broad enough and isn't really sufficient to distinguish between a possible framework error and a real error from the language runtime.

I would suggest we change to specification to be

::com::sun::star::reflection::WrappedTargetException

where the TargetException Member can be either

a) css::reflection::InvocationTargetException indicating that the error is from the language runtime

Note the InvocationTargetException member TargetException member is expected to be a ScriptErrorRaisedException exception or ScriptExcepionRaisedException.

Exception ScriptErrorRaisedException :: css::uno::Exception

{

String scriptName;

long lineNum

}

Exception ScriptExceptionRaisedException :: ScriptErrorRaised

{

String ExceptionType;

}

It is intended that the ScriptProvider will provider will export its errors to clients of the provider via the mechanism described above. Additionally the Message member of the ScriptErrorRaisedException and ScriptExceptionRaisedException should contain localized error messages.

Note: For OO2.0 Beanshell and JavaScript ScriptProviders will NOT provide localized error messages

b) arbitary exception thrown from the framework, could be css::uno::IOException etc.

ScriptFramework specific errors need to be handled at the MasterScriptProvider and appropriate error dialogs raised from this point.

Notes

References

Scripting Framework Specification:

http://specs.openoffice.org/scripting_framework/ScriptingFrameworkSpecification.sxw

Script Organizer Specification

Page

http://specs.openoffice.org/scripting_framework/ErrorHandlingSpecification.sxw

Christian Jansen

2003-11-04T09:09:03