Return-Path: X-Original-To: apmail-incubator-ooo-commits-archive@minotaur.apache.org Delivered-To: apmail-incubator-ooo-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id A86727274 for ; Sun, 27 Nov 2011 22:50:44 +0000 (UTC) Received: (qmail 71694 invoked by uid 500); 27 Nov 2011 22:50:44 -0000 Delivered-To: apmail-incubator-ooo-commits-archive@incubator.apache.org Received: (qmail 71670 invoked by uid 500); 27 Nov 2011 22:50:44 -0000 Mailing-List: contact ooo-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: ooo-dev@incubator.apache.org Delivered-To: mailing list ooo-commits@incubator.apache.org Received: (qmail 71663 invoked by uid 99); 27 Nov 2011 22:50:44 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 27 Nov 2011 22:50:44 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 27 Nov 2011 22:50:35 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 7D3D42388AB9; Sun, 27 Nov 2011 22:50:12 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1206895 [5/12] - in /incubator/ooo/ooo-site/trunk/content/udk/common: ./ man/ man/concept/ man/draft/ man/draft/scripting/ man/draft/scripting/DesignDoc/ man/images/ man/spec/ man/tasks/ man/tutorial/ Date: Sun, 27 Nov 2011 22:50:08 -0000 To: ooo-commits@incubator.apache.org From: kschenk@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20111127225012.7D3D42388AB9@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ThreadingSoln.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ThreadingSoln.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ThreadingSoln.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ThreadingSoln.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,265 @@ + + + + Threading Solution + + + + + + +

Introduction

+ The goals of the threading solution research are:
+ +
    +
  • To establish how threading currently works in OpenOffice
    • +
  • To investigate issues related to running multiple scripts simultaneously +in OpenOffice
    • +
  • To suggest how IDEs would be able to attach to OpenOffice scripts +
    +
    • + +
+ +

+ +

Contents

+ + + Also of interest are these initial thoughts on the thread management topic +posted to openoffice.org + +
+

Current StarBasic script threading behaviour

+ +

Run the macro from the "Macro" dialogbox.

+ +
    +
  • No frozen document you can work on any documents
    • +
  • Macro running in background
    • +
  • No macro can be run
    • + +
+ Assign the macro to the "F10" key. Press that key. +
    +
  • Active document is frozen
    • +
  • Other document are not frozen
    • +
  • Can't run any macro on other document while the macro is still running +even from the "Macro" dialogbox.
    • + +
+ While the macro is running, if you open the "Macro" dialogbox, the macro +is paused +
    +
  • If you close the dialog box, the macro is resumed
    • +
  • If you decide to edit a macro, the macro is resumed and you can stop +the macro from the BASIC editor
    • +
  • If you switch to the BASIC editor and click on the stop button, the +macro will be stop but nothing in the UI will be updated until the "Macro" +dialogbox is closed (this seems to be a bug).
    • + +
+ +

Contents

+ +
+

Current Ms Basic script threading behaviour

+ +

Run the macro from the "Macro" dialogbox.

+ +
    +
  • All document are frozen
    • + +
+ Run the macro from the Ms Visual Basic editor. +
    +
  • All document are frozen
    • + +
+ Assign the macro to the "F10" key. Press that key. +
    +
  • All document are frozen
    • + +
+ Run a macro that will access Excel and change the cell values. +
    +
  • All word document are frozen
    • +
  • Excel is not frozen, macro is running and changing value and you can +change values.
    • + +
+ +

Contents

+ +
+

Event Handling

+ +

The OpenOffice process has multiple threads. Any thread that calls Application::Yield +or Application::Reschedule dispatches GUI events. Dispatching GUI events requires +the SolarMutex, so only one thread at a time can dispatch GUI events. In +practice the "main" OpenOffice thread is the thread that dispatches most GUI +events.

+ +

Events can be either synchronous or asynchronous.

+ +

Synchronous events are handled immediately, that means that the functionality +bound to the event is invoked immediately from the call stack of the thread +where the event occurred. The thread is therefore blocked until the event has +been handled.

+ +

Asynchronous events are placed in a message queue by the thread handling +the event, and the thread is not blocked, it continues executing. The message +queue is serviced by any thread which calls Application::Yield or Application::Reschedule. +

+ +

Contents

+ +
+

Options for script threading behaviour

+ +

There are two possible threading models that we could use:

+ +
    +
  1. One script per OpenOffice process - this is the threading model currently +used by OpenOffice.
    2. +
  2. One script per OpenOffice document - this would allow more than one +script to be run at the same time, but only one script could be run per document +at a time. The thread running the script would have to grab a document lock +before invoking the script and release it when the script has completed. +
    3. + +
+ +

The best solution is to implement option 2, and add the possibility to +configure the threading behaviour so that it acts like option 1 if the user +wishes to use this behaviour (see Configuration section below).

+ +

So, how do we implement option 2? From discussions with Mathias Bauer +and Joerg Budischweski they feel that OpenOffice should manage the spawning +of the threads which would invoke the scripts. In the case of synchronous +events the thread handling the event would spawn a thread in which it would +then invoke the script. In the case of asynchronous threads the thread which +had grabbed the event off the message queue would spawn a new thread when +it wanted to invoke a script. In other words the responsibility for managing +the per document script threads would lie with OpenOffice, not the scripting +framework.

+ +

Changes needed:

+ +
    +
  • The thread calling XFunction.invoke() (main thread for synchronous + events, message queue thread for asynchronous events) needs to spawn a +new thread and call XFunction.invoke() from there.
    • +
  • The document for which the XFunction is being invoked needs to be + locked for the duration of XFunction.invoke() (with a documentmutex of +some sort) so other XFunctions cannot be invoked for that document. The most +difficult thing is that also every view that tries to modify a document must +stick to this rule
    • + +
+ +

See also: "Threading model for an office scripting framework" discussion +on openoffice.udk.dev newsgroup

+ +

Contents

+ +
+

Issues with allowing one script per document

+ +

Because of problems with thread safety in the OpenOffice API it is currently +unsafe to allow more than one thread to make API calls at the same time. For +this reason there is a global SolarMutex which thread unsafe API implementations +automatically lock before executing any functionality, and unlock before returning. +The thread calling the OpenOffice API is not aware of this SolarMutex. While +the SolarMutex is grabbed, OpenOffice API calls from other threads will block +until the SolarMutex becomes free. The OpenOffice UI will be frozen while +the SolarMutex is locked. If a script calls a OpenOffice API, the solarmutex +will be grabbed until the API call returns which would temporarily freeze +all document windows. These freezes may be an unacceptable annoyance to users +and they may prefer that the UI be completely frozen for the duration of +script execution rather than having it freeze unexpectedly.

+ +

See also: "Office API and thread safety" discussion on openoffice.framework.dev +newsgroup

+ +

Contents

+ +
+

Configuration of threading behaviour

+ +

The threading behaviour of Office should be configurable so that the user +can switch on/off the one script per document behaviour as they wish. A radio +box should be added to the Scripting pane of the Office options dialog with +the options:

+ +

Allow only one script to be run by OpenOffice at a time.
+ Allow one script per document to be run by OpenOffice at a time

+ +

Contents

+ +
+

Identifying script threads in a debugger

+ +

The issue here is how we can identify which thread in a OpenOffice process +is running the script we are interested in debugging. This is possible in +java using the java.lang.Thread.setName() method. The pairing of script name +and document name should be sufficient to uniquely identify the appropriate +thread.

+ +

Contents

+ +
+

SolarMutex

+ +

A problem could arise if a thread that does not possess the SolarMutex + tries to execute a script synchronously, because any API call in the script +can possibly acquire the SolarMutex. This may cause a deadlock, f.e. if the +thread possessing the SolarMutex waits for a resource that is locked by the +thread that tries to execute a script synchronously. So we could add some +code here, that denies script execution, if it should be done synchronously +and the SolarMutex is locked. It's better to treat this as an error than taking +the risk of getting a deadlock.
+ ======
+ suffice to say that for synchronous executions the thread owns the SolarMutex, +it doesn't need to be the "main" thread.
+ ======
+ Every not thread safe implementation of our API will acquire the SolarMutex +in any interface call before anything will be done inside the method. So the +function object doesn't need to care for that
+ ======
+ the SolarMutex should be locked only inside the API calls (it will be anyway), +not by the function object (it mustn't, because it doesn't know if it is called +synchronously or not!), the event handler or anybody else. A big advantage +of this is, that the SolarMutex will be freed between two API calls, giving +the message queue a chance to allow for a minimum responsiveness of the office +process. The script then will work in parallel to the event queue. Only +for synchronous execution we should try to (!) acquire the SolarMutex before +executing the script as described above. If the try fails, script execution +should be denied. I consider this to be a rare case, currently I can't imagine +that any event that may cause a script execution will occur in a thread without +the SolarMutex. But it's good to handle this case in an appropriate way. +
+ ======
+

+ +

Contents

+ +

+ + + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ThreadingSoln.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/XModules.idl URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/XModules.idl?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/XModules.idl (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/XModules.idl Sun Nov 27 22:49:46 2011 @@ -0,0 +1,16 @@ +#ifndef __com_sun_star_scripting_XModules_idl__ +#define __com_sun_star_scripting_XModules_idl__ + +#include +#include + +module com { module sun { module star { module scripting { + +interface XModules: com::sun::star::uno::XInterface { + /* from original i/f spec this should return a flat list of + * the available methods, and leave any hierarchical organisation + * of same to the UI */ + sequence getAvailableMethods(); +}; +}; }; }; }; +#endif Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/XMonitorListener.idl URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/XMonitorListener.idl?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/XMonitorListener.idl (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/XMonitorListener.idl Sun Nov 27 22:49:46 2011 @@ -0,0 +1,31 @@ +#ifndef __com_sun_star_scripting_XMonitorListener__ +#define __com_sun_star_scripting_XMonitorListener__ +#ifndef __com_sun_star_uno_XInterface_idl__ +#include +#endif +#include +#include +#include + +module com { + module sun { + module star { + module scripting { + interface XMonitorListener: com::sun::star::lang::XEventListener { + + /** Will be executed when script is started + * + */ + void scriptStarted([in] ScriptStartedEvent e); + + /** Will be executed when script finishes + * + */ + void scriptCompleted([in] ScriptCompletedEvent e); + }; + }; + }; + }; +}; +#endif + Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/arch.txt URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/arch.txt?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/arch.txt (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/arch.txt Sun Nov 27 22:49:46 2011 @@ -0,0 +1,269 @@ +Language agnostic scripting framework architecture +================================================== + +Author: Laszlo Kovacs + +1. Project goals +---------------- + +1. Provide a language agnostic scripting framework specification +and implementation that allows compiled and interpreted scripting +engines to be plugged into StarOffice. This includes support for +plugging in various IDEs. + +2. Integrate in the framework described at (1) a scripting engine +for scripts developed in JAVA and a scripting engine for a JAVA +based scripting language. + +3. Select an IDE and integrate it into the framework described at +(1). Implement command line tools that duplicate the IDE +functionality (for script developers who prefer command line +environment). + +4. Refactor the current StarBasic scripting engine and +environment so that it is plugged into StarOffice through the +framework described at (1). Decision has to be made about what +kind of IDE to provide (the old one or integrate with the new +one). + +2.Language agnostic scripting framework +--------------------------------------- + +This section deals with the first item of the project goals. + +The main components of the language agnostic scripting framework +are described below. + +2.1 Runtime environment +----------------------- + +A language agnostic runtime environment has to allow script +engine developers to plug in script engines (runtime instances) +of compiled or interpreted languages. + +Runtime instances have to be managed by a runtime manager. They +need to implement interface(s) through which the associated VM, +interpreter can be started, stopped, identified, status queried, +configured. + +Runtime instances have to be easily deployable into StarOffice, +implementation as UNO components or using UNO wrappers will +achieve this. + +Because of the specifics of individual VM/interpreter +configurations the runtime implementation will probably have to +provide its own specific configuration tool. + +Runtime services that are common for every runtime and should be +part of the scripting framework implementation are: + +1. If compiled scripts are deployed by source then they will have +to be compiled before running. The location of related compilers +have to be discovered for this, probably configured through the +configuration tool. + +2. Executed scripts have to be provided with context. This can be +obtained from the storage service or can be assigned dynamically. + +3. Lifecycle services: resources acquired by the script have to +be tracked and cleaned up after execution. + +4. A sandbox could be provided for managing script resources and +access permissions to the file system and StarOffice services +granting various rights to scripts. However this might be +difficult to achieve in a language agnostic way. A simpler +approach is described in the "Binding to events" section +(signatures). + +5. Defining a state persistence service is a simple matter. In +case of languages that support persistence StarOffice specific +persistence services can be hidden from developers. + +6. Single threaded scripts have to be safely usable in the +multithreaded StarOffice environment. A simple approach of not +running two scripts at the same time in the same context (Single +Threaded Apartment model) might be enough here. + +2.2 Binding to events --------------------- + +A binding UI (part of StarOffice) has to be provided for users +who use scripts developed by script developers. This UI will +allow binding of scripts and script methods to StarOffice events. +The binding UI should navigate scripts developed in all the +supported languages. This can be achieved with a generic naming +scheme that easily maps to the supported languages naming +schemes. Deployment information is needed to describe the methods +implemented by a script (depending on languages this may be +automatically generated from the script). The binding UI also has +to facilitate parameter passing to scripts. + +It might be preferred to provide very simple editing +functionalities in the binding UI so that a script can be changed +and saved by the user before it is run. + +Security related issues in this case are: + +1. If scripts are provided by source they may be encrypted so +that only certain users can run them. The binding UI has to be +able to decrypt them based on passwords provided by the user. + +2. Scripts have to be prevented of harmful behavior. This may be +achieved by a sandbox type of approach implemented in the +runtime. This however might be difficult to achieve for every +language in a language agnostic way. + +An alternative approach is similar to the Java applet signatures. +Scripts can contain a signature from a trusted source meaning +that they can be trusted. It would be up to the user to decide +whether scripts are run or not based on their signatures. If +scripts are run they would have full access to resources and +StarOffice services. An extension to this where trusted scripts +would be granted with more resources and possibilities than not +trusted ones might be difficult to implement. + +2.3 IDE services +---------------- + +Developers need an IDE or simple command line tools for +development. The development tasks these tools have to support +are accessing/editing/storing code, compiling, debugging, code +encryption/decryption (see "Binding to events"). + +The scripting framework has to include specification and +implementation of services that will support the IDE +functionalities. These are storage, debugging and compiling +services. Encryption/decryption services are simple and will be +shared between the binding UI, the IDE, the macro recording +component and possibly the runtime environment. + +The compiling service supports easy plug in of various compilers +for compiled languages. Apart from the IDE another higher level +component that needs the compiler service is the runtime +environment, in case scripts are deployed by source and need to +be compiled before being run. + +Explicit debugging services (breakpoint setting/clearing, +variable evaluation etc.) need to be defined. Some debuggers +(JVM) allow direct connection of the IDE to them, with no need +for a special debugging service. + +Access/edit/save of scripts, their deployment information and +context has to rely on the script navigation and storage +services. No extra services have to be defined here. These +services (especially assigning context) have to be shared between +the IDE and the binding UI. + +2.4 Script navigation and storage +--------------------------------- + +Script storage is a lower level service that most of the other +services will rely on. IDEs and command line development tools +will have to load, edit, save scripts. The binding UI will have +to be able to navigate through the scripts, their deployment +information and context. Runtimes will need to locate and load +the scripts that are selected for execution. + +A storage service has to implement access, navigation and saving +of scripts, their deployment information and context for all +supported languages, interfaces will have to be defined for this. + +The approach of script storage in relation to documents and the +application has to be defined. Scripts can be part of related +documents or referenced from documents. The application wide +scripts will have to be stored in an application rather than +document specific area. + +2.5 Macro recording +------------------- + +Macro (script) recording has to be supported by the scripting +framework. The sharing of responsibilities between StarOffice, +the scripting framework and language specific macro recording +components has to be researched. + +3. IDE implementation and command line tools +-------------------------------------------- + +This section deals with the third item of the project goals. + +The main issue here is whether the preferred solution is to use +an IDE framework (such as NetBeans) to develop the IDE or an IDE +is developed from scratch (for example using JBuilder). + +IDEs will use the compiler service and the debugging service for +development. They will use the storage service to edit scripts +and to deploy scripts in various contexts (assigned to documents +or application wide). The part of the IDE that is implemented on +top of the storage service has to be more complex than an +ordinary file selection box as it has to access and store scripts +in relation to various contexts. + +Close integration between the binding UI, the IDE and the +debugging services is needed for script testing during +development. After a script has been saved (with a specific +context), developers have to be able to bind it to an event, run +it in a debugger and set breakpoint or evaluate variables through +the IDE. + +Editing command line tools will have to implement easy extraction +and saving of scripts in document and application contexts. +Command line compiling does not need extra support. Command line +debugging needs support for setting the script context before +running and cooperation with the binding UI. + +An important feature of an IDE is a GUI builder. Modern script +environments include GUI builders. In the language agnostic +context the main issues are whether a language independent GUI +building framework is feasible, and what effort will this put on +developers to learn yet another UI API. Alternatively the GUI +builder can be deferred to the individual script engine +implementations. The possibility to achieve similar look and feel +to StarOffice is important in this case. + + +4. Architecture diagram +------------------------ + +This diagram tries to capture both the language agnostic +scripting framework and the integrated IDE. It contains only the +components and their relationships (connecting lines describe +relationships), not what services the components provide. + +It does not deal with the security related issues of script +execution (the sandbox vs the signature approach). + +In case of the signature approach a signature service has to be +provided that allows scripts to be signed whenever they are +created (IDE, macro recording) and to retrieve the signature +before assigning to an event (binding UI). + +In case of the sandbox approach the common runtime services have +to be extended with the sandbox implementation and a security +configuration UI provided that configures the sandbox. This could +be built on top of the signature approach. + + + + + + + + + + + + + + + + + + + + + + + + + + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/arch.txt ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/archdiag.pdf URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/archdiag.pdf?rev=1206895&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/archdiag.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/basic-storage.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/basic-storage.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/basic-storage.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/basic-storage.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,310 @@ + + + + + + + + + + + + +
Process +of creating a macro and assigning it to an event +

+ +
Assign a +macro that was created and saved in the Standard Library of +OpenOffice called Test(). +
The +directory soffice.cfg +is created in the user/config +directory once you assign a macro to a key. +
An xml +file per context is created and contains all the bindings. +
Because +the macro is in the Standard Library of OpenOffice and that the +binding is only applied to a key in Writer: +
The file +writerkeybinding.xml +is created +

+ +
Content +of writerkeybinding.xml +

+ +
<?xml +version="1.0" encoding="UTF-8"?> +
<!DOCTYPE +accel:acceleratorlist PUBLIC "-//OpenOffice.org//DTD +OfficeDocument 1.0//EN" "accelerator.dtd"> +
<accel:acceleratorlist +xmlns:accel="http://openoffice.org/2001/accel" +xmlns:xlink="http://www.w3.org/1999/xlink"> +
+ ... +
+ <accel:item accel:code="KEY_F10" +xlink:href="macro:///Standard.Module1.Alexis()"/> +
+ ... +
</accel:acceleratorlist> +

+ +
Content +of Accelerator.dtd +

+ +
<!ENTITY +% boolean "(true|false)"> +

+ +
<!ELEMENT +accel:acceleratorlist (accel:item*)> +
<!ATTLIST +accel:acceleratorlist +
xmlns:accel +CDATA #FIXED "http://openoffice.org/2001/accel" +
xmlns:xlink +CDATA #FIXED "http://www.w3.org/1999/xlink" +
> +

+ +
<!ELEMENT +accel:item EMPTY> +
<!ATTLIST +accel:item +
accel:code +CDATA #REQUIRED +
accel:shift +%boolean; "false" +
accel:mod1 +%boolean; "false" +
accel:mod2 +%boolean; "false" +
xlink:href +CDATA #REQUIRED +
> +

+ +
The +content of user/basic +is formed by a directory per library you modified (in that case +Standard was modified) and 2 files .xlc. +
Script.xlc +is the file that will be explained: +

+ +
Content +of the file script.xlc +

+ +
<?xml +version="1.0" encoding="UTF-8"?> +
<!DOCTYPE +library:libraries PUBLIC "-//OpenOffice.org//DTD OfficeDocument +1.0//EN" "libraries.dtd"> +
+<library:libraries +xmlns:library="http://openoffice.org/2000/library" +xmlns:xlink="http://www.w3.org/1999/xlink"> +
+ <library:library library:name="Standard" +xlink:href="file:///home/al91857/StarOffice6.0/user/basic/Standard/script.xlb/" +xlink:type="simple" library:link="false"/> +
+ <library:library library:name="WebWizard" +xlink:href="file:///usr/dist/share/staroffice,v6.0/share/basic/WebWizard/script.xlb/" +xlink:type="simple" library:link="true" +library:readonly="false"/> +
+ ... +
+</library:libraries> +

+ +
Content +of Libraries.dtd +

+ +
<!ENTITY +% boolean "(true|false)"> +

+ +
<!ELEMENT +library:libraries (library:library)*> +
<!ATTLIST +library:libraries +
xmlns:library +CDATA #FIXED "http://openoffice.org/2000/library" +
xmlns:xlink +CDATA #FIXED "http://www.w3.org/1999/xlink" +
> +

+ +
<!ELEMENT +library:library EMPTY> +
<!ATTLIST +library:library +
library:name +CDATA #REQUIRED +
xlink:href +CDATA #IMPLIED +
xlink:type +CDATA #IMPLIED +
library:link +%boolean; #REQUIRED +
library:readonly +%boolean; #IMPLIED +
> +

+ +
You can +see that the xlink:href +of the library:name="Standard" +is locating as file in the home directory because I modified that +library. +

+ +
Content +of the file script.xlb +in file:///home/al91857/StarOffice6.0/user/basic/Standard +

+ +
<?xml +version="1.0" encoding="UTF-8"?> +
<!DOCTYPE +library:library PUBLIC "-//OpenOffice.org//DTD OfficeDocument +1.0//EN" "library.dtd"> +
<library:library +xmlns:library="http://openoffice.org/2000/library" +library:name="Standard" library:readonly="false" +library:passwordprotected="false"> +
+<library:element library:name="Module1"/> +
</library:library> +

+ +
Content +of Library.dtd +

+ +
<!ENTITY +% boolean "(true|false)"> +

+ +
<!ELEMENT +library:library (library:element)*> +
<!ATTLIST +library:library +
xmlns:library +CDATA #FIXED "http://openoffice.org/2000/library" +
+library:name CDATA #REQUIRED +
+library:readonly %boolean; #REQUIRED +
+library:passwordprotected %boolean; #REQUIRED +
> +

+ +
<!ELEMENT +library:element EMPTY> +
<!ATTLIST +library:element +
library:name +CDATA #REQUIRED +
> +

+ +
Content +of the file where my macro was saved: Module1.xba +

+ +
<?xml +version="1.0" encoding="UTF-8"?> +
<!DOCTYPE +script:module PUBLIC "-//OpenOffice.org//DTD OfficeDocument +1.0//EN" "module.dtd"> +
<script:module +xmlns:script="http://openoffice.org/2000/script" +script:name="Module1" script:language="StarBasic">REM + ***** BASIC ***** +

+ +
Sub +Main +

+ +
End +Sub +

+ +
Sub +Alexis +
print +&quot;alexis&quot; +
End +Sub</script:module> +

+ +
Content +of Module.dtd +

+ +
<!ELEMENT +script:module (#PCDATA)> +
<!ATTLIST +script:module +
xmlns:script +CDATA #FIXED "http://openoffice.org/2000/script" +
script:name +CDATA #REQUIRED +
script:language +CDATA #REQUIRED +
> +

+ +
When +you save the document including the macro, everything is in a Zip +file with the same hierarchy than explained above. +

+ +
The +file hierarchy is: +

+ +
Archive: + test.sxw +
+ testing: content.xml +
+ testing: Basic/Standard/Module1.xml +
+ testing: Basic/Standard/script-lb.xml +
+ testing: Basic/script-lc.xml +
+ testing: styles.xml +
+ testing: meta.xml +
+ testing: settings.xml +
+ testing: META-INF/manifest.xml +

+ +
So +the script-lb.xml file is the equivalent to the script.xlb file +explained above +
The +script-lc.xml file is the equivalent to the script.xlc file explained +Above. + + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/basic-storage.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/build-script.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/build-script.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/build-script.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/build-script.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,296 @@ + + + + + + Building Scripting + + + + + + + + + + + + + +

Building the Scripting Framework  for  OpenOffice.org

+ +

Contents:

+ +
    +
  1. Requirements
    2. +
  2. CVS
    3. +
  3. Setting up environment
    4. +
  4. Modifying modules
    5. +
  5. Building
    6. +
  6. Create package
    7. +
  7. Manual install
    +
    8. + +
+
+
+ +

Requirements:

+ + + +

Projects to get from CVS

+Backup your unoil and offapi modules and then checkout the following:
+
+ Modules to be checkout from CVS head:
+ +
    +
  • scripting
    • +
  • unoil/drafts/com/sun/star/script (drafts/com/sun/star/script, + needs to be in the unoil  module)
    • +
  • offapi/drafts/com/sun/star/script (drafts/com/sun/star/script, + needs to be in the offapi  module)
    • + +
+ If you only have solvers, you will also need to checkout the following + modules on a tag that is appropriate to the release, you are building +for:
+ +
    +
  • unoil
    • +
  • offapi
    • + +
+ +

Setting up build environment for Scripting

+ Assumption: That you have a build environment set-up to build + OpenOffice.org or components for OpenOffice.org, otherwise please read +the guide on Downloading + and Building the Source
+
+ If you have configured your environment with Java and Ant, please skip + on to ...... , otherwise you will need to re-run the configure script from + the config_office project  and include the options --with-jdk-home=<PATH + TO JAVA>  --with-ant-home=<PATH TO ANT> and source or + run the environment set-up script.
+
+ NOTE: If configure can not get Ant, after you have sourced or + run the environment set-up script,  you will need add all jarfiles + under <PATH TO ANT>/lib to your $CLASSPATH
+
+ +

Modifying offapi, unoil and scripting modules for + building

+ You will need to modify the offapi and unoil modules so that the services + and interfaces for scripting are available.
+ +

offapi  module:

+ +
    +
  1. Ensure that you have the drafts/com/sun/star/script directory +under the offapi module, if you don't, you will need to check it out from +CVS head
    2. +
  2. Modify the prj/build.lst, you will need to add the following +lines
    3. + +
      +
    • oa  offapi\drafts\com\sun\star\script\framework         + nmake   -   all oa_scriptf_drafts NULL
      • +
    • oa  offapi\drafts\com\sun\star\script\framework\provider            + nmake   - all oa_sfprovider_drafts NULL
      • +
    • oa  offapi\drafts\com\sun\star\script\framework\storage         + nmake   -   all oa_sfstorage_drafts NULL
      • +
    • and add "oa_sfprovider_drafts oa_sfstorage_drafts oa_scriptf_drafts" + to the last line before "NULL"
      • + +
    +
  3. Modify the util/makefile.mk and add the following to UNOIDLDBFILES + list 
    4. + +
      +
    1. $(UCR)$/dcssscriptframework.db \ 
      2. +
    2. $(UCR)$/dcsssfprovider.db \ 
      3. +
    3. $(UCR)$/dcsssfstorage.db
      4. + +
    + +
+ +

+ +

unoil module:

+ +
    +
  1. Ensure that you have the drafts/com/sun/star/script directory under + the unoil module, if you don't, you will need to check it out from CVS +head
    2. +
  2. Modify the makefile.mk in the top level directory of the module +-
    3. + +
      +
    1. Change the line RDB  =  $(SOLARBINDIR)/offapi.rdb + to RDB = $(PRJ)$/..$/offapi$/$(INPATH)$/ucr$/offapi.db
      2. + +
    +
  3. Modify prj/build.lst
    4. + +
      +
    1. Add the following line: ul  unoil\drafts\com\sun\star\script\framework      + nmake   -   all ul_scriptf_drafts ul_ucb ul_frame NULL             +
      +
      2. +
    2. Add ul_scriptf_drafts to the last line before NULL
      3. + +
    + +
+ +

scripting module:

+ +
    +
  1. Remove the comments from the lines in source/cppumaker.mk:
    2. + +
      +
    1. UNOUCRDEP=$(PRJ)/../offapi/$(INPATH)/ucr/offapi.db $(SOLARBINDIR)$/udkapi.rdb + $(SOLARBINDIR)$/offapi.rdb
      2. +
    2. UNOUCRRDB=$(PRJ)/../offapi/$(INPATH)/ucr/offapi.db $(SOLARBINDIR)$/udkapi.rdb + $(SOLARBINDIR)$/offapi.rdb
      +
      3. + +
    +
  2. Comment out the lines in source/cppumaker.mk
    3. + +
      +
    1. UNOUCRDEP=$(SOLARBINDIR)$/udkapi.rdb
      2. +
    2. UNOUCRRDB=$(SOLARBINDIR)$/udkapi.rdb
      3. + +
    +
  3. Remove the comment from the following line in java/build.xml:
    4. + +
      +
    1. <!-- <pathelement location="${prj}/../unoil/${inpath}/class/unoil.jar"/> + -->
      2. + +
    +
  4. Comment out the line in java/build.xml:
    5. +
      +
    1. <pathelement location="${solar.jar}/unoil.jar"/>
      +
      2. +
    + +
+ +

Building scripting

+ +
    +
  1. Execute build in the offapi module
    2. +
  2. Execute build in the unoil module
    3. +
  3. Execute build in the scripting module
    4. + +
+ +

Creating the UNO Package:

+ Please read the Developer's + Guide for more information on UNO packages
+ +
    +
  1. Create a separate directory ($pkg)
    2. +
  2. In this directory, create directories called $pkg/<PLATFORM>.plt + and $pkg/skip_registration (Where <PLATFORM> + is like linux_x86)
    3. +
  3. NOTE: A list of supported directories is available in the +source file desktop/source/pkgchk/pkgchk_packages.cxx, you may need to modify +this, if your platform is not supported
    +
    4. +
  4. Copy in the libraries from scripting/<platform>/lib to + $pkg/<PLATFORM>.plt
    5. +
  5. Copy in ScriptRuntimeForJava.jar from scripting/<platform>/class + into the top level directory, $pkg
    6. +
  6. Copy in unoil.jar from $pkg/unoil/<platform>/class +  to skip_registration directory
    +
    7. +
  7. Merge the following registries from offapi/<platform>/ucr + into one registry called ooscript.rdb under the top level +directory, $pkg
    8. + +
      +
    1. dcssscriptframework.db
      2. +
    2. dcsssfprovider.db
      3. +
    3. dcsssfstorage.db
      4. + +
    +
  8. Now, zip up all files in this directory, $pkg
    9. + +
+ +

Manual Installation of the Scripting Framework

+ +
    +
  1. Copy the zip file into your OpenOffice installation under the user/uno_packages + directory 
    2. +
  2. In the program directory, run pkgchk on the zip file
    3. +
  3. Copy from the solver ($SRC_ROOT)/solver/643/<platform>/bin/regsingleton +to your OpenOffice installation under the program directory
    +
    4. +
  4. Execute the following: 
    5. + +
      +
    1. ./regsingleton <OpenOffice Path>/user/uno_packages/cache/services.rdb + drafts.com.sun.star.script.framework.storage.theScriptStorageManager=drafts.com.sun.star.script.framework.storage.ScriptStorageManager
      2. +
    2. ./regsingleton <OpenOffice Path>/user/uno_packages/cache/services.rdb + drafts.com.sun.star.script.framework.theScriptRuntimeForJava=drafts.com.sun.star.script.framework.ScriptRuntimeForJava
      3. + +
    +
  5. Modify the the ProtocolHandler.xcu file under <OpenOffice + Path>/share/registry/data/org/openoffice/Office/, add the following + lines:
    6. + +
      +
    1. <node oor:name="com.sun.star.comp.ScriptProtocolHandler" oor:op="replace">
      +                         + <prop oor:name="Protocols">
      +                                 + <value>script:*</value>
      +                         + </prop>
      +                 + </node>
      + Under the HandlerSet Tag
      2. + +
    + +
+ Unzip HighlightTextParcel.sxp from scripting/examples/java into + <OpenOffice Path>/user, this should create a directory under + user  called Scripts/java/HighlightText
+
+ Now, run OpenOffice and under the Tools->Configure menu add +a new menu which is bound to the macro Standard.Main, then shut down + OpenOffice and modify the file <OpenOffice>/user/config/soffice.cfg/writermenubar.cfg + and change macro://Standard.main() to script://HighlightText.showForm. + Start OpenOffice again and select the menu item you have added, this +should bring up a Java dialog box call HighlightText
+
+ If you have any problems, please post your problem to dev@framework.openoffice.org
+
+
+
+
+ + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/build-script.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ide.txt URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ide.txt?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ide.txt (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ide.txt Sun Nov 27 22:49:46 2011 @@ -0,0 +1,146 @@ +IDE requirements +================ + +Author: Laszlo Kovacs + +This document contains the main issues related to IDE development +and integration into StarOffice in the context of the language +agnostic scripting framework. + +1. External IDEs +---------------- + +StarOffice currently has an internal IDE for StarBasic code ma- +nipulation. With multiple script language support introduced in- +tegration of StarOffice with a robust external IDE will be need- +ed. It is feasible to adopt an existing IDE rather than develop- +ing one from scratch. The two IDEs considered are NetBeans (Forte +for Java) and JBuilder. + +1.1. NetBeans +------------- + +NetBeans is both an IDE platform and a Java IDE developed on this +platform. Unfortunately there is an obvious naming problem here, +the NetBeans web site calls them NetBeans IDE (for the Java IDE) +and NetBeans platform (for the IDE framework that can be used to +develop IDEs for any application). While NetBeans is an open +source project, Forte for Java is the commercial implementation +of the NetBeans Java IDE. + +For Java and Java based scripting languages Forte for Java should +be used as the external IDE. The NetBeans IDE has rudimentary +support for three Java based scripting languages (environments), +they are Jython, Dynamic Java and BeanShell. These could be en- +hanced and moved into Forte for Java. + +Integration of StarBasic and other scripting languages in the +Forte environment depends on the extensibility policy of the +Forte environment. Forte 7 provides one unified IDE based on Net- +Beans for all the Forte environments (Java, C, C++, Fortran). If +Forte extensibility by Sun for Starbasic and by third parties for +other languages is not feasible because of marketing reasons then +the NetBeans JAVA IDE can be used for IDE integration. + +1.2. JBuilder +------------- + +JBuilder is a very popular Java environment, there could be mar- +keting reasons for adapting it as the external StarOffice IDE. It +is extensible through the so called OpenTools add-ins. There is +an open source project for extending JBuilder with Jython support +(needs enhancements). Support for other Java based scripting lan- +guages can be developed in a similar way. + +While JBuilder provides similar extensibility to NetBeans in cer- +tain areas, the main drawback is that it does not allow replace- +ment of Java with other languages. Various Java runtimes can be +used, but runtimes of other languages can not be plugged in. They +all have to integrate with the Java debugger that is part of +JBuilder. This might change as the Open Tools documentation +states that the debugging and building APIs will be extensively +changed in the future (I could not find out anything about the +nature of the changes). + +The only languages that could be supported in this context are +Java and Java based scripting languages. Support for non-Java +based scripting languages (including StarBasic) is not possible. + +2. Internal vs external IDE +--------------------------- + +Considering the various types of user groups and the scripts they +develop a large external IDE might not be feasible to cover the +needs and a simple internal IDE could be provided. + +The sharing of responsibilities between the external and internal +IDE has to be defined. As currently StarOffice has only an inter- +nal IDE, this provides all the needed functionality. In a multi- +ple scripting language context (where one of the languages could +be Java) adding complete IDE functionality to the internal IDE in +a language agnostic way would mean duplicating a large amount of +features of the external IDE in the internal one. Identifying the +user groups for the two IDEs and clearly separating their needs +will reduce the amount of duplication. For example assuming that +the internal IDE would be used for writing very small scripts, +complete debugging support might not be provided by the internal +IDE. + +The current Starbasic IDE should be revised along these lines. + +3. Implementation of functionality needed by the IDE(s) +------------------------------------------------------- + +In the various scenarios discussed above StarOffice might have +both an external and an internal IDE. Depending on the internal +IDE functionalities a number of underlying services will be +shared by the two IDEs. An obvious approach would be to define a +set of UNO interfaces for the functionalities (like debugging, +compiling, storage access etc). These would be implemented by un- +derlying components and used by both IDEs according to needs. + +In the context of NetBeans as an external IDE and Java and Java +based scripting language support (among other languages) several +issues have to be mentioned: + +(a) NetBeans (and Forte for Java) is already integrated with Java +so this integration would not happen through the above mentioned +UNO interfaces. If the languages supported would be Java, Java +based scripting languages and Starbasic then only the new, refac- +tored StarBasic integration would use the UNO interfaces. + +(b) The NetBeans IDE framework provides an extensive Java API for +integration of other languages environments. If an UNO layer is +attached below this, that will result in two similar APIs on top +of each other with the only benefit that the various scripting +language integrations can be developed in any language. If the +UNO layer is not added then other scripting languages (like Star- +Basic) could be integrated in Java only. + +4. Integration between the IDEs and the binding UI +-------------------------------------------------- + +The binding UI has to run a selected script's selected method. If +the script has syntax errors in it or breakpoints have been set, +execution has to stop and the (internal or external IDE) activat- +ed. For Java and Java based scripting languages this can easily +be achieved through JPDA (the Java Platform Debugger Architec- +ture, an infrastructure needed to develop end-user debugger ap- +plications). + +Integration of other scripting languages has to be done through +UNO interfaces that provide JPDA-like features. The development +environment of the language needs similar degree of cooperation +as between the JVM and the Java debugger for this. + +5. GUI building +--------------- + +An important feature of an IDE is a GUI builder. Modern script +environments include GUI builders. In the language agnostic con- +text the main issues are whether a language independent GUI +building framework is feasible (effort), and what effort will +this put on developers to learn yet another UI API. Alternatively +the GUI builder can be deferred to the individual language imple- +mentations. The possibility to achieve similar look and feel to +StarOffice is important in this case. Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ide.txt ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/index.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/index.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/index.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/index.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,120 @@ + + +Language Independent Scripting Framework + + + + +

Language Independent Scripting Framework

+ +

Nov 2002 - The Scripting Framework has now moved to the Application +Framework project. The pages you find here are kept only for historical +purposes. For up to date information on the project see + +the current Scripting Framework home page. +

+ +

This project is about enabling OpenOffice to be scripted in multiple +scripting languages.. This page is to be used as a repository of information + relating to this project.
+
A team has been put together specifically for providing a language-agnostic + scripting framework for StarOffice. 

+

The team is in the process of defining the architecture and high level +design for the scripting framework. The steps for this are:
+- provide a high level architecture (Architecture Document +)
+- brainstorm possible user stories and compile them into a product requirements document (Product Requirements +)
+- analysis of major technical scripting framework issues (Functional Areas, Interactions, Behaviour +)
+- provide high level design and interfaces for binding, invocation, naming, storage and IDE integration (in progress)
+- a number of research documents about the scripting framework issues, StarOffice areas involved and prototype are below

+ + +

Comments etc. (on the dev@udk.openoffice.org mailing list) will +be really appreciated.

+ + +

Documentation

+

Architecture, high level design, product requirements
+
+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Architecture DocumentLanguage Agnostic Scripting + Framework high level architecture. 
Design Document New!An initial design document containing class & interaction diagrams, proposals for the file structure, suggestions for the language-specific and logical names, DTD and XML for the script deployment and registry, and links to the proposed IDL files. 
Product +Requirements
+ 		Product requirements (in + spreadsheet form). It contains the first cut of use cases grouped according + to associated user roles, specific product requirements and rough priorities + for implementation.
+
Functional areas, Interactions, Behaviour +
+ 		Analysis of major technical scripting framework issues.
+
+
+
+Research, prototype
+
+ + +
Java Scripting FrameworkA document discussing +some of the issues relating to a Java implementation of the Scripting +Framework.
Framework Problems & Issues (Overview)
A collation of some +of the main problem in the areas that need to be provided by the Scripting + Framework.
Proposals for solutions
Elaborations & proposals on +some of the problem areas mentioned above.
+
+ +

Old Documentation
+

+ + + + + + + + + + + + + + + + + +
Architecture + DocumentLanguage Agnostic Scripting + Framework architecture (deprecated).
Architecture + DiagramScripting Framework architecture + diagram (PDF) (deprecated).
Services & Interfaces + A very basic first attempt + to define the necessary services & interfaces.
+ Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/index.html ------------------------------------------------------------------------------ svn:eol-style = native