Requirement Spec: general OOoBean

Readers:	Java developers who will design, implement or use the OOoBean
Conforms to:	Rul.Req/0.1
Extends:	-
Demands:	-
Sources:	statements from current OOo users of JavaBeans (FISCUS, So4Kids, SAP)
Applies to:	OOoBean Design Specifications
Task-IDs:	i19974

Abstract

Our primary objective is to create production quality JavaBeans for the major OOo components.

A secondary objective is offering a smart API to access the main elements of office documents and to process common tasks.

i-Team Members

	Name	E-mail Address	Approval Date
UserExp	-	-	
Dev.	Michael Hönnig (MI)	Michael.Hoennig@Sun.COM	
QA	Stephan Wunderlich (SW)	Stephan.Wunderlich@Sun.COM	
Doc.			
StringRev	-	-	

Content Overview

Abstract	1

i-Team Members	1

Document Change History	2

Content Index	3

PERF: Performance Requirements	6

FUNC: Functional Requirements	8

UI: User interface	17

API: Application Programming Interface	18

DOC: Documentation	22

EXT: External Issues	23

COST	27

Glossary	27

Document Change History

Revision	Change	Initials	Date
0.11	stripped down to phase I features	MI	2004-10-28
0.10	new template for specificatiion merged	MI	2003-09-25
0.9	new template for specifications merged	MI	2003-09-19
0.8	merged annotations from email from Jürgen Kindler 09/17/03 16:04 deadline 2003-12-01 added for multiple requirements API.REU.ERRH filled with requirement from Jürgen Kindler EXT.REQ.UNOT removed	MI	2003-09-18

Content Index

Abstract	1

i-Team Members	1

Content Overview	1

Document Change History	2

PERF: Performance Requirements	6

PERF.LRN/0.7: shorten Learning Time (MUST:1-3)	6

PERF.LOC/0.6: shorten Lines of Code (MUST:1-3)	6

PERF.FIX/0.6: shorten Time to Fix at Customer (MUST:1-3)	7

FUNC: Functional Requirements	8

FUNC.BEAN/0.3: JavaBean (MUST:1-3)	8

FUNC.BEAN.LOAD/0.8: Loadable (MUST:1)	8

FUNC.BEAN.CONF/0.3: Configurable (MUST:3)	8

FUNC.BEAN.VIEW/0.8: Viewable (MUST:1)	8

FUNC.BEAN.EDIT/0.8: Editable by the User (MUST:1)	8

FUNC.BEAN.STOR/0.8: Storable (MUST:1)	9

FUNC.BEAN.PRNT/0.5: Printable (MUST,PERF:3)	9

FUNC.BEAN.PROG/0.8: Programmable (MUST,PERF:1)	9

FUNC.PAR/0.4: Parent Component (MUST,DC:2)	10

FUNC.PAR.LWP/0.4: Load without Parent Component (MUST:2)	10

FUNC.PAR.RWL/0.8: Remove while Loaded (MUST:2)	10

FUNC.PAR.LWC/0.7: Lightweight Component (MUST:-)	10

FUNC.PAR.HWC/0.7: Heavyweight Component (HINT,SCOPE)	10

FUNC.CON: Connection	11

FUNC.CON.ACCS/0.2: Connection Accessibility (MUST)	11

FUNC.CON.AUTO/0.8: Auto Connect (MUST:2)	11

FUNC.CON.MULT/0.8: Multiple Connections (MUST:2)	11

FUNC.CON.STRT/0.8: Connection Start (MUST:1)	11

FUNC.CON.STOP/0.8: Stopping the Connection (MUST:2)	12

FUNC.CON.KEEP/0.8: Keeping the Connection (MUST:2)	12

FUNC.CON.NTFY/0.4: Connection Notifications (MUST:2)	12

FUNC.CON.REST/0.2: Connection Restart (OPEN)	12

FUNC.CON.LOST/0.2: Lost Connection (MUST:1-3)	13

FUNC.CON.CMDQ/0.2: Command Queue (SHOULD)	13

FUNC.ROB/0.3: Robustness (MUST:2-3)	14

FUNC.ROB.CREC/0.8: Crash Recovery (SHOULD:3)	14

FUNC.ROB.CNOT/0.8: Crash Notification (MUST:2)	14

FUNC.ROB.DEAD/0.2: Dead Objects (HINT,SCOPE)	14

FUNC.RES/0.3: Resources (MUST,DC:1)	14

FUNC.RES.JAR/0.3: Java Archive Resources (MUST,DC:1)	15

FUNC.RES.SO/0.2: Shared Object Resources (MUST,DC:1)	15

FUNC.RES.OTH.SO/0.2: Other Resources (MUST:1)	15

FUNC.RES.JWS/0.8: Java WebStart (MUST,DC:2)	15

FUNC.OOO/0.8: OOo Version (MUST,DC:1)	15

FUNC.PER/0.2: Persistence (MUST,DC:3)	15

FUNC.PER.STAT/0.3: Persistence of Status (MUST,DC:3)	16

FUNC.PER.DOC/0.3: Persistence of Document (OPEN,DC:3)	16

UI: User interface	17

UI.NOUI/0.2: No Own User Interface (HINT,SCOPE)	17

API: Application Programming Interface	18

API.GUIB/0.3: GUI Builder (MUST:3)	18

API.GUIB.CHCC/0.3: Child Component Control (MUST:3)	18

MBar/0.2: MenuBar show/hide (MUST)	18

FBar/0.2: FunctionBar show/hide (MUST)	18

OBar/0.2: ObjectBar show/hide (MUST)	18

TBar/0.2: ToolBar show/hide (MUST)	18

SBar/0.2:StatusBar show/hide (MUST)	18

HSCB/0.2: Horizontal ScrollBar show/hide (SHOULD)	18

VCSB/0.2: Vertical ScrollBar show/hide (SHOULD)	18

HRul/0.2: Horizontal Ruler show/hide (SHOULD)	18

VRul/0.2: Vertical Ruler show/hide (SHOULD)	18

API.GUIB.VWOC/0.2: View Option Control (SHOULD:3)	19

Scale/0.2 (SHOULD):	19

ObjectBorders/0.2 (SHOULD):	19

API.GUIB.EVTS/0.4: Events (MUST:3)	19

ungrouped requirements	19

API.NODC/0.8: API Behavior without Document (MUST:1)	19

API.FULL/0.6: Fully Programmable (MUST:1)	19

API.SIM:	20

API.SIM.SEAP/0.2: Short Element Access Paths (SHOULD,PERF:3)	20

API.SIM.SEAP.DOC/0.3: OfficeDocument (SHOULD)	20

API.SIM.SEAP.FRM/0.3: Frame (SHOULD)	20

API.SIM.SEAP.CTL/0.3: Controller (SHOULD)	20

API.SIM.JAVA/0.3: Java Classes (SHOULD,DC:3)	20

API.SIM.PRT/0.2: Printing (MUST)	21

API.REU/0.2: Reusability (MUST)	21

API.REU.GEN/0.8: Genericness (MUST:1)	21

API.REU.IMPI/0.3: Implementation Independence (SHOULD,DC:1)	21

API.REU.INTI/0.3: Interface Independence (MUST,DC:1)	21

API.REU.ERRH/0.8: API Error Handling (MUST:2)	22

NOO: the error of no OOo found is reported	22

NOC: the error of not being able to establish the connection is reported	22

NOR: the error of not having found necessary resources (SO, JAR etc.) is reported	22

API.CON/0.2: Connection API (MUST)	22

DOC: Documentation	22

DOC.API.REF/0.3: Reference Manual (MUST:1)	22

DOC.API.DEV/0.3: Developers Guide (MUST:3)	22

DOC.API.UML/0.3: UML Diagram (MUST:2)	22

EXT: External Issues	23

EXT.PREC/0.3: External Preconditions	23

EXT.PREC.UNOC/0.3: UNO Connection (MUST:1)	23

EXT.PRE.REMD/0.7: Remote Display (NICE:-)	23

EXT.INF: External Influences	24

EXT.INF.TBX/0.5: Toolboxes (HINT:3)	24

EXT.INF.CR/0.5: Crash Recovery (HINT:2)	24

EXT.REQ: External Requirements	25

EXT.REQ.UNOT/0.8: UNO Timeouts (MUST,SCOPE:2)	25

EXT.REQ.UNOL/0.4: UNO Logging (NICE,SCOPE:3)	25

EXT.REQ.TSOO/0.3: Thread Safe OOo (MUST,SCOPE:3)	25

EXT.REQ.CLS/0.7: Cancel Load/Save (SHOULD,SCOPE:3)	25

EXT.REQ.CCP/0.4: Cut, Copy and Paste (MUST,SCOPE:3)	25

EXT.REQ.STST/0.4: Stop/Start Timing in OOo (MUST,SCOPE:2)	26

COST	27

COST.TOT: Total Cost/0.5 (SHOULD:*)	27

Glossary	27

PERF: Performance Requirements

PERF.LRN/0.7: shorten Learning Time	(MUST:1-3)

Scale: Time needed by typical Java programmers who do not know the OOoBean to create their first Java application which includes an OOoBean, load a document, set a simple content and save the document.

Meter: Given: Fully installed OOo, OOo SDK and Java SDK. The Java developer pointed to the OOoBean chapter in the developers guide and the respective chapter of the Reference Manual. Then measuring the time until the functionality mentioned in Scale works.

Past: 8h (TBD: this is just a wild guess)

Goal: 2h

Must: 4h

Stakeholder: TBD

Rationale: In he past the example code had to be studied, understood and adapted. This meant about 500 LOC had to be read and understood by the application developer.

PERF.LOC/0.6: shorten Lines of Code	(MUST:1-3)

Scale: Lines of code needed to embed an OOoBean into an arbitrary Java application , load a document, set a simple content and save the document.

Meter: Count lines of code needed if only libraries which are part of the OOo deliverables is made use of. If example code is copied, it fully counts. Only one statement per line, the condition of if/case/while/for statements counts as a separate statement. Commentary lines do not count, neither do import statements, empty lines or lines with just „{„ or „}“.

Past: 350

Goal: 10

Must: 20

Stakeholder: TBD

Rationale: In he past the example code was copied into the client application and frequently modified and, due to lack of functionality, extended. This meant that the LOC of the example added to the LOC of the client application. The client application developer became responsible for maintaining this code too.

PERF.FIX/0.6: shorten Time to Fix at Customer	(MUST:1-3)

Scale: Time needed by the original developers of a OOoBean application to integrate a patch for a defect in into their application.

Meter: Provide the developer with an environment mentioned in PERF.LRN.Meter, the original OOoBean application and the OOo SDK which includes the patch. Testing time not counted.

Past[AWT-component handling ]: >1h

Goal[AWT-component handling]: 0

Must[AWT-component handling]: 0.5h

Stakeholder: TBD

Rationale: In he past the example code was copied into the client application and frequently modified as well. Sometimes the code was even restructured due to lack of functionality in the examples. Whenever a defect was fixed in this code, which frequently was the case, the fix had to be integrated into the client application code as well.

FUNC: Functional Requirements

FUNC.BEAN/0.3: JavaBean	(MUST:1-3)

Description:The main requirement for the OOoBean JavaBean is to make OOo documents available as JavaBeans which behave as close as possible like 100% pure JavaBeans. Making the documents available as JavaBeans means that they can be: {FUNC.BEAN.LOAD, FUNC.BEAN.VIEW, FUNC.BEAN.EDIT, FUNC.BEAN.STOR, FUNC.BEAN.PRNT, FUNC.BEAN.PROG}.

Stakeholder: Kay Ramme (StarOffice)

Scale: Rating of behavior as a JavaBean between 0 and 9

Meter: Survey of typical users (client application developers)

FUNC.BEAN.LOAD/0.8: Loadable	(MUST:1)

Description: The OOoBean has a direct method to load it in all ways com::sun::star::frame::XComponentLoader allows to load a document, with the exception that the target frame is always the frame of the OooBean.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: Loading documents into OOOBeans is a very common task, occurring in almost all client application environments. Thus, this topic should be addressed directly.

FUNC.BEAN.CONF/0.3: Configurable	(MUST:3)

=API.GUIB

FUNC.BEAN.VIEW/0.8: Viewable	(MUST:1)

Description: The OOo document within the OOoBean must be viewable by the user.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: Viewing contents, is a general feature of user interface JavaBeans.

FUNC.BEAN.EDIT/0.8: Editable by the User	(MUST:1)

Description: The OOo document within the OOoBean must be editable by the user.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: Editing contents, is a general feature of user interface JavaBeans.

FUNC.BEAN.STOR/0.8: Storable	(MUST:1)

Description: The OOoBean has a direct method to store its content in all ways com::sun::star::frame::XStorable allows to store a document.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: Storing documents into OOOBeans is a very common task, occurring in almost all client application environments. Thus, this topic should be addressed directly.

FUNC.BEAN.PRNT/0.5: Printable	(MUST,PERF:3)

Description: The OOoBean has an easy method to print its content in all ways com::sun::star::view::XPrintable allows to print a document.

Scale: Statement complexity (->Glossary: Statement Complexity) in Java to print the content document without any explicit settings or options and without exception handling.

Goal: <=7

Plan: <=6

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: Printing documents into OOOBeans is a very common task, occurring in many client application environments.

FUNC.BEAN.PROG/0.8: Programmable	(MUST,PERF:1)

Description: The OOoBean offers access to the full OOo API with limited or no overhead. This can mean, just to give access to all necessary interfaces.

Scale: Statement Complexity (->Glossary: Statement Complexity) in Java having a OOoBean in a variable compared to having the OOo document in a variable. Exception handling is not counted.

Deadline: 2003-12-15

Goal: <=2 (read: not more then 2 degrees more complexity)

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: In almost all context, functionality specific to the concrete JavaBean is used by the client application environment. Thus, this functionality has to be easily accessible.

FUNC.PAR/0.4: Parent Component	(MUST,DC:2)

Description: The OOoBean relates to its parent like any normal AWT window. This includes {FUNC.PAR.LWP, FUNC.PAR.RWL, FUNC.PAR.LWC}.

Stakeholder: Matthias.Schmidt@Sun.COM (SO/SAP integration), Jürgen Kindler (FISCUS)

Rationale: The JavaBean examples which are part of the OOo SDK and the JavaBean framework of OOo had several restrictions regarding this issue which were root cause for many bugs.

FUNC.PAR.LWP/0.4: Load without Parent Component	(MUST:2)

Description: It can be created and loaded without being added to a java.awt.Container.

Stakeholder: Matthias.Schmidt@Sun.COM (SO/SAP integration), Jürgen Kindler (FISCUS)

Rationale: Some frameworks, like the SAP PatinGUI framewor, require the document to be loaded into the bean before the bean has a parent or before the parent has a system window.

FUNC.PAR.RWL/0.8: Remove while Loaded	(MUST:2)

Description: It can be removed from its java.awt.Container while loaded.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: The OOoBean might be moved from one window to another window in client frameworks or GUI builders. This also covers the timing problems (order of destruction) when the parent hierarchy is unbuild and the OOoBean destroyed. Especially if the current OOoBean is still loading a document and the Java AWT/Swing parent window gets destroyed, it is an guaranteed crash.

FUNC.PAR.LWC/0.7: Lightweight Component	(MUST:-)

Description: The OOoBean behaves as a normal lightweight component. This includes sibling components of the parent which may overlap the OOoBean.

Source: E-Mail from Matthias Schmidt on 2003-09-15.

Stakeholder: Matthias Schmidt (Sun)

Removal Rationale: See EXT.PRE.REMD.RemovalRationale. Additional, for popups there is a workaround in Java, by allowing Swing to create system windows for them.

FUNC.PAR.HWC/0.7: Heavyweight Component	(HINT,SCOPE)

Assumption: The OOoBean behaves as a normal heavyweight component. All issues related to this subject are not bugs in the OOoBean but rather in the client application.

Source: Mixing heavy and light components, Amy Fowler
(http://java.sun.com/products/jfc/tsc/articles/mixing/)

Stakeholder: Michael Hönnig (StarOffice)

Rationale: This demarcation statement determines the scope of the OOoBean components responsibility and the scope of the client environment in respect to UI component behavior.

FUNC.CON: Connection

The connection refers to the connection itself as well as the OOo instance on the other side.

FUNC.CON.ACCS/0.2: Connection Accessibility	(MUST)

Description: The underlying connection of the OOoBean is accessible on the API level.

Removal Rationale: No requirement based rationale for this requirement could be found. Maybe it turns out to be a solution for other requirements, but it does not seem to be an requirement itself.

FUNC.CON.AUTO/0.8: Auto Connect	(MUST:2)

Qualifier: No connection established and connection needed.

Description: The OOoBeans must implicitly create their own connection.

Deadline: 2003-12-15

Source: JavaBeans specification,
and email from Jürgen Kindler (FISCUS) on dev@api.ooo at 2003-08-04 9:43h

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: JavaBeans are instantiated in GUI builders without any properties set yet.

FUNC.CON.MULT/0.11: Multiple Connections	(SHOULD:3)

Description: Multiple connections to a single or even multiple instances of OOo have to be supported. (yet to be decided)

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Source: email 2003-09-17 16:04

Rationale: If the API is designed in a way which does not consider this feature, it might have to be changed in the future if we ever want this feature. Especially with a remote display mechanism, it's very likely that this requirement comes up.

FUNC.CON.STRT/0.11: Connection Start	(SHOULD:3)

Description: It must be possible to explicitly start to the OOo with a specific Connection-URL (->Glossary: Connection URL) or with a default Connection-URL.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: On the one hand, the ConnectionURL has to explicitly stated anyway to allow multiple connections and connections to a distinct OOo instance. On the other hand I can imagine several client environments where it makes the API much more reusable if the connection is started explicitly:

Pre-Establishing the connection to move the time OOo needs to start to an earlier point before it actually is needed and expected to appear within a second.

Trying multiple connection URLs which might or might not be available, e.g. depending on the client resisting standalone or in different network environments.

Making sure that a connection can be established before any UI is available.

FUNC.CON.STOP/0.8: Stopping the Connection	(MUST:2)

Description: It must be possible to explicitly stop the connection to OOo.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: The same OOo instance can be used with a normal UI and as a OOoBean server. In this case client application has to be able to state when it will not use the connection anymore. Additionally, there is one important situation when stopping is required: If multiple JVMs use StarOffice, the first one using it might have started the service. But this JVM is not necessarily the one that can shutdown StarOffice. So if an application cannot stop StarOffice during the JVM shutdown, it should at least drop the connection to free the resources within StarOffice and make sure that the last application using StarOffice can shut it down later.

FUNC.CON.KEEP/0.8: Keeping the Connection	(MUST:2)

Qualifier: Explicit termination of OOo by the user

Description: The OOoBean must intervene with the termination of OOo and keep OOo alive until it is not needed anymore.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: If a user who uses the same OOo instance which is used as a OOoBean server with the normal UI and explicitly terminates this OOo instance, all active OOoBean instances lost connection.

FUNC.CON.NTFY/0.4: Connection Notifications	(MUST:2)

Qualifier: Connection starts/stops

Description: An event is called which notifies the listeners about the start or stop of the connection.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: This feature is needed to make it easier for client programs to clean up their references when the connection to OOo is terminated. If possible race conditions cannot avoided with other mechanisms this might also be helpful.

FUNC.CON.REST/0.2: Connection Restart	(OPEN)

Description: After loading and closing a number of documents into the OOoBean, OOo should be regularly terminated, if it does not terminate within a certain time, killed and in either case restarted. The number of times reusing OOo within one runtime should be configurable, default 25.

Rationale: OOo usually hangs after using it much more then 25 times.

Stakeholder: Jürgen Kindler (FISCUS)

Source: email from Jürgen Kindler (FISCUS) on de@api.ooo at 2003-08-04 9:43h

Owner: Kay Ramme (StarOffice)

Removal Rationale: OOo is supposed not to hang. See EXTR.REQ.TSOO and EXTR.REQ.UNOT too. We want to minimize effort in workarounds and rather fix the bug in OOo.

FUNC.CON.LOST/0.2: Lost Connection	(MUST:1-3)

Description: For each method of the OOoBean itself it has to be clearly specified how it behaves when the connection to OOo is lost.

Assumption: For methods which are directly called via UNO, standard UNO behavior applies.

Stakeholder: Jürgen Kindler (FISCUS)

Source: email from Jürgen Kindler (FISCUS) on dev@api.ooo at 2003-08-04 9:43h

Rationale: A clear definition what the methods do and how the OOoBean behaves when the connection to OOo is lost will ease the pain of having to deal with this issue as an client application developer.

FUNC.CON.CMDQ/0.2: Command Queue	(SHOULD)

Description: Method calls to the OOo UNO API should be queued. In case of a transaction log, the queue should be continued to execute at the point where the connection was lost, after OOo was restarted and the connection re-established.

Stakeholder: Jürgen Kindler (FISCUS)

Source: email from Jürgen Kindler (FISCUS) on de@api.ooo at 2003-08-04 9:43h

Rationale: This feature would take a lot of effort out of client applications to deal with dying OOo connections.

Owner: Kay Ramme (StarOffice)

Removal Rationale: We do not want to put too much efforts in this kind of workarounds, rather we have the OOo bugs fixed which lead to lost connections (mostly deadlocks). See EXTR.REQ.TSOO and EXTR.REQ.UNOT too. Additionally, this only works for methods called directly at the OOoBean anyway, but more complex client applications use sub objects via UNO as well, and these would be dead. Creating a transaction aware wrapper for all UNO components is definitely out of scope for this the OOoBean. Who wants, can build that on top of this OOoBean.

FUNC.ROB/0.3: Robustness	(MUST:2-3)

Gist: The OOoBean must not die when the connected OOo instance crashes. Details of this requirement are described in {FUNC.ROB.CREC, FUNC.ROB.CNOT, FUNC.ROB.DEAD}.

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: Some instance of the application has to deal with this issue anyway, otherwise the user will be confronted with a dead UI component. It makes most sense to deal with this issue within the OOoBean and not in the client because it is the same for all clients: Get rid of the dead UI component and, after re-establishing the connection, create a new UI component.

FUNC.ROB.CREC/0.8: Crash Recovery	(SHOULD:3)

Description: If the connected OOo crashes, the OOoBean must re-start OOo, re-connect and load the document stored by the crash guard.

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: see above

Note: It might be a MUST requirement, due to Jürgen Kindler. I am checking this currently.

FUNC.ROB.CNOT/0.8: Crash Notification	(MUST:2)

=FUNC.CON.NTFY

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: If OOo or the connection to OOo crashes, all UNO objects which the client application got from the OOoBean are invalid (dead). With such a crash notification, the client application can clean up its references to such object and is even able to create new references. Based on this, a transaction mechanism could be implemented, which was actually the original requirement from the stakeholder. See next statement too.

FUNC.ROB.DEAD/0.2: Dead Objects	(HINT,SCOPE)

Qualifier: connection terminated unexpectedly

Description: Is not in the scope of the product to deal explicitly with dead object references other than the OOoBean class itself and maybe some of the wrapper classes after a crash of OOo.

Assumption: These other objects are UNO objects, they behave as specified in UNO.

Stakeholder: Kay Ramme (StarOffice)

Rationale: Features like command queuing or transactions are considered too complex and valid only in limited context anyway. We do not want to spend time on this issue in the basic OOoBean. It brings unnecessary complexity too.

FUNC.RES/0.3: Resources	(MUST,DC:1)

Description: Resources needed by the OOoBean, like jar files, shared libraries or OOo itself, have to be searched according to the rules {FUNC.RES.*}.

Stakeholder: Matthias.Schmidt@Sun.COM (SO/SAP integration)

Rationale: The existing JavaBean framework classes had no defined method of how to search needed resources. This was the root cause for several bugs.

FUNC.RES.JAR/0.3: Java Archive Resources	(MUST,DC:1)

Description: JAR files are loaded through the default ClassLoader active for the Java environment of the OooBean.

FUNC.RES.SO/0.2: Shared Object Resources	(MUST,DC:1)

Description: Shared Libraries (e.g. lib*.so or *.dll) are first tried to load from the ClassLoader active for the Java environment of the OOoBean by ClassLoader.getResource(), then, if it is an UrlClassLoader, the paths and parent paths are searched, at last the ClassPath (from System.getProperty()) is searched.

Stakeholder: Michael Hönnig (StarOffice)

Rationale: There are some very restricted environments in which the OOoBean is used. I identified the lack of a definition how resources are found as the key. In some environments we actually cannot find our resources. This definition enables the environment to find the resources. That some environments do not allow to exchange the Java ClassLoader nor have a normal directory structure, cannot be resolved by the OOoBea, just by the environment itself.

FUNC.RES.OTH.SO/0.2: Other Resources	(MUST:1)

Description: For other resources, needed by the chosen design, an appropriate search method has to be defined in the Design Specification.

FUNC.RES.JWS/0.11: Java WebStart	(MUST,DC:3)

Description: It must be possible to use the OOoBean via Java WebStart were OOo is locally installed.

Stakeholder: Jürgen Kindler (FISCUS)

Source: TBD – link to Java WebStart documentation

Rationale: The existing JavaBean framework classes had no defined method of how to search needed resources. This was the root cause for several bugs.

FUNC.OOO/0.8: OOo Version	(MUST,DC:1)

Description: The OOoBean works with a product StarOffice7 / OOo 1.1.

Deadline[Step 1-2 Requirements]: 2003-12-01

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: The schedule of the FISCUS project needs a production quality OOoBean before the end of 2003. By this time, no further version other then StarOffice 7 / OOo 1.1 will be available and StarOffice7 will be in use by FISCUS.

Removal Rationale: Due to heavy changes in the UI comfig of OOo this is not possiblex.

FUNC.OOO/0.11: OOo Version	(MUST,DC:1)

Description: The OOoBean works with a product StarOffice8 / OOo 2.0

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: The schedule of the FISCUS project needs a production quality OOoBean before the end of 2003. By this time, no further version other then StarOffice 7 / OOo 1.1 will be available and StarOffice7 will be in use by FISCUS.

FUNC.PER/0.2: Persistence	(MUST,DC:3)

Description: JavaBean persistence must be used.

Source: JavaBean specification

Stakeholder: Michael Hönnig (StarOffice)

FUNC.PER.STAT/0.3: Persistence of Status	(MUST,DC:3)

Description: Status settings which are configurable in GUI builders are stored with the JavaBean persistence mechanism. This comprises all properties exposed due to API.GUIB.

Source: JavaBean specification

Stakeholder: Michael Hönnig (StarOffice)

Rationale: Persistence of JavaBeans is used to store the settings which are done in the GUI builder. It is not actually used to store the document itself.

FUNC.PER.DOC/0.3: Persistence of Document	(OPEN,DC:3)

Description: It is still undecided whether the whole document is used in the JavaBean persistance mechanism for the OooBean.

Source: JavaBean specification

Stakeholder: Michael Hönnig (StarOffice)

Rationale: Persistence of JavaBeans is used to store the settings which are done in the GUI builder. It is not actually used to store the document itself. It's just still questionable whether the user of a GUI builder might want to enter document content in the GUI builder too, for example to create a template or a form within the OOoBean.

UI: User interface

UI.NOUI/0.2: No Own User Interface	(HINT,SCOPE)

Description: The OOoBean does not have an own user interface. The user interface of the OOo component which is contained in the OOoBean will be used.

Stakeholder: Michael Hönnig (StarOffice)

Rationale: This states clearly that extra user interface is not within the scope of the OOoBean.

API: Application Programming Interface

Gist: The OOoBean has an appropriate API specified by the following requirements.

API.GUIB/0.3: GUI Builder	(MUST:3)

Description: The OOoBean API is to be designed by the rules of JavaBeans. Therefore, the most important configuration properties {API.GUIB.CHCC, API.GUIB.VWOC} and events {API.GUIB.EVTS} should be explicitly available as JavaBean properties and JavaBean events.

Rationale: This requirement is necessary to make the OOoBean useable in JavaBean GUI builders.

Stakeholder: Kay Ramme (StarOffice)

API.GUIB.CHCC/0.3: Child Component Control	(MUST:3)

Description: Internal child components like tool and menu bars, rulers etc. can be shown/hidden via properties from UI-oriented JavaBean design tools.

MBar/0.2: MenuBar show/hide (MUST)

FBar/0.2: FunctionBar show/hide (MUST)

OBar/0.2: ObjectBar show/hide (MUST)

TBar/0.2: ToolBar show/hide (MUST)

SBar/0.2:StatusBar show/hide (MUST)

HSCB/0.2: Horizontal ScrollBar show/hide (SHOULD)

VCSB/0.2: Vertical ScrollBar show/hide (SHOULD)

HRul/0.2: Horizontal Ruler show/hide (SHOULD)

Description: This rule does not apply, if no such ruler exists in the specific OOo application document.

VRul/0.2: Vertical Ruler show/hide (SHOULD)

Description: This rule does not apply, if no such ruler exists in the specific OOo application document.

Further, OOo application specific, child components are specified for certain subclasses of the OooBean.

Source: JavaBean guidelines

Stakeholder: Jürgen Kindler (FISCUS)

API.GUIB.VWOC/0.2: View Option Control	(SHOULD:3)

Description: Major view options should be controllable as properties from UI-oriented JavaBean design tools.

Scale/0.2 (SHOULD):

Description: There should be a JavaBean property for setting and getting the scale (zoom) of the document within the OOoBean.

ObjectBorders/0.2 (SHOULD):

Description: There should be a JavaBean property for showing/hiding borders of objects within the document in the OOoBean. Which these are has to be specified with the concrete OOoBean subclass for each OOo application.

Source: JavaBean guidelines

Stakeholder: Michael Hönnig (StarOffice)

API.GUIB.EVTS/0.4: Events	(MUST:3)

TBD

ungrouped requirements

API.NODC/0.8: API Behavior without Document	(MUST:1)

Qualifier: no document is loaded into the OOoBean and a method is called which operates on a loaded document only

Description: An exception has to be thrown which states that no document is loaded.

Deadline: 2003-12-15

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: This behavior has to be clearly specified because the unspecified behavior of the old OOo JavaBeans in case of no document loaded was frequently an issue of discussion and bugs in client applications.

API.FULL/0.6: Fully Programmable	(MUST:1)

=FUNC.BEAN.PROG

API.SIM:

Gist: A minor requirement is making the use of the API somewhat easier. But API functionality should not simply be copied from multiple interfaces to a single Java class or a few Java classes.

API.SIM.SEAP/0.2: Short Element Access Paths	(SHOULD,PERF:3)

Description: Access to frequently sub elements as stated below {API.SIM.SEAP.DOC,API.SIM.SEAM.FRM,API.SIM.SEAP.CTL}should only need few terms.

Scale: Number of terms (->Glossary: Term) needed to access certain objects within the application domains.

Meter: A collection of commonly used use cases regarding accessing sub objects of the applications (Writer, Calc, Draw etc.). These are specified in the application specific OOoBeans.

Past[1st paragraph of main text in Writer]: TBD

Must[1st paragraph of main text in Writer]: TBD

Past[arbitrary cell in Calc]: TBD

Must[arbitrary cell in Calc]: TBD

Past[named object in Draw]: TBD

Must[named object in Draw]: TBD

We want easy access for members of the following UNO components:

API.SIM.SEAP.DOC/0.3: OfficeDocument	(SHOULD)

Description: There should be a Java wrapper class for the OfficeDocument.

API.SIM.SEAP.FRM/0.3: Frame	(SHOULD)

Description: There should be a Java wrapper class for the Frame into which the OOo document is loaded.

API.SIM.SEAP.CTL/0.3: Controller	(SHOULD)

Description: There should be a Java wrapper class for the Controller associated with the OOo document.22

A feature which fulfills this requirement might be implemented by the upcoming UNO version 3.5 anyway: automatically generated wrapper classes for UNO objects which implement all supported interfaces of the service.

Stakeholder: Michael Hönnig (StarOffice)

Rationale: Just to access the needed sub objects within OOos object structure, usually needs many terms which makes the API unhandy in such cases.

API.SIM.JAVA/0.3: Java Classes	(SHOULD,DC:3)

Where Java classes can be used without loss in features, these should be preferred over OOo API classes. A list of classes cannot be offered because this list depends on the classes actually needed in the implementation.

There might be support for this in the upcoming UNO version 3.5 anyway.

Rationale: Java programmers are used to classes from standard Java libraries. Using these classes flattens the learning curve and makes these programs more likely accept the OOoBean.

API.SIM.PRT/0.2: Printing	(MUST)

A smart printing API is supported which is as similar as possible to the OOo API but supports synchronous printing.

Removal Rationale: This feature is already present indirectly by using the OOo API. Synchronous printing can be specified in the PrintOptions.

API.REU/0.2: Reusability	(MUST)

API.REU.GEN/0.8: Genericness	(MUST:1)

Description: The general OOoBean API must be independent of specific OOo apps.

Deadline: 2003-12-01

Rationale: A common but independent root class for all OOoBeans makes it possible to write client application code which is independent from the actual document type. Additionally this way it is easier to create specific OOoBeans for future applications. There will be extra OOoBean subclasses for each OOo application.

Stakeholder: Jürgen Kindler (FISCUS)

Source: email from Jürgen Kindler on 2003-09-15 09:37

API.REU.IMPI/0.3: Implementation Independence	(SHOULD,DC:1)

Description: The OOoBean implementation should work with the system window office and an RVP (VCL remote visualization protocol) office.

Rationale: RVP is currently the only solution which could make it possible to behave like a lightweight Java Swing component. This requirement once in a while comes up from customers. We would like to use the same OOoBean implementation and just exchange the OOoBean framework implementation.

Stakeholder: Users of the existing OOo JavaBean framework

API.REU.INTI/0.3: Interface Independence	(MUST,DC:1)

Description: The OOoBean API must work with the system window office and an RVP (VCL remote visualization protocol) office.

Rationale: RVP is currently the only solution which could make it possible to behave like a lightweight Java Swing component. This requirement once in a while comes up from customers. If we cannot use the same OOoBean implementation, at least we want to use the same OOoBean API, thus client applications do not need to be changed.

Stakeholder: Users of the existing OOo JavaBean framework

API.REU.ERRH/0.11: API Error Handling	(MUST:2)

Description: In FUNC.CON.AUTO/.03 and FUNC.CON.START/0.4 errors might occur if OOo cannot be found or is running without being configured to respond to connections. It is also possible that classes used to connect to OOo are not compatible to the OOo instance which is running or will be created (e.g. OOoBean tries to connect to StarOffice 6.0 ). Such configuration problems should be result in defined exceptions.

NOO: the error of no OOo found is reported

NOC: the error of not being able to establish the connection is reported

NOR: the error of not having found necessary resources (SO, JAR etc.) is reported

Stakeholder: C.P. Hennessy (OOo), Jürgen Kindler (FISCUS)

Source: email from Jürgen Kindler 2003-09-17 16:04

Annotation: Fiscus has implemented a version check based on the version name. Note that we change the version number of the StarOffice installation that is reserved for embedded use in our application to avoid possible conflicts with installations (for non embedded use) that already exist or may be done after “our” installation is done. It might be necessary to make the version check configurable. (←Jürgen Kindler)

Removal Rationale: This feature is incomaptaible with the perspective of loading OOo as a service (Kay Ramme, Sun).

API.CON/0.2: Connection API (MUST)

=CON.ACC

DOC: Documentation

DOC.API.REF/0.3: Reference Manual	(MUST:1)

Description: The API of the OOoBean is fully documented using JavaDoc.

Stakeholder: Jürgen Kindler (FISCUS)

DOC.API.DEV/0.3: Developers Guide	(MUST:3)

Description: The chapter about the OOoBean in the Developers Guide has to be updated.

Stakeholder: Jürgen Schmidt (StarOffice)

DOC.API.UML/0.3: UML Diagram	(MUST:2)

Description: The internal and external structure of the OOoBean have to be documented with UML diagrams.

Stakeholder: Jürgen Schmidt (StarOffice)

EXT: External Issues

This chapter lists requirements to products other than the OOoBean but related to the OOoBean. These issues also have to be seen as risks for the OOoBean product itself.

EXT.PREC/0.3: External Preconditions

Here external preconditions are listed which are already known by the time of specifying the requirements of the product itself.

EXT.PREC.UNOC/0.3: UNO Connection	(MUST:1)

Qualifier: Connection created implicitly by UrlResolver

Description: The UNO connection must be available for the OOoBean.

Rationale: The UrlResolver is the state of the art method to establish a connection. Using the UrlResolver makes applications less complex. Unfortunately, there is currently no access to the connection itself if the UrlResolver ist used to get the remote service manager.

EXT.PRE.REMD/0.7: Remote Display	(NICE:-)

Description: It would be nice if VCL could render on a remote (in sense of another process) device where the remote communication uses a specified protocol.

Source: E-Mail from Matthias Schmidt on 2003-09-15.

Stakeholder: Matthias Schmidt (Sun)

Ratioinale: To be able to create a lightweight component, display needs to be implmented in Java. This means VCL needed a remote display. (←FUNC.PAR.LWC)

Removal Rationale: This requirement is way out of the resource scope for the next release.

EXT.INF: External Influences

This chapter lists relationships to planned changes in external components, mostly in SO/OOo.

EXT.INF.TBX/0.5: Toolboxes	(HINT:3)

Description: The toolboxes will get a new layout in SO/OOo Q. There will be no context dependent overlapping toolboxes anymore which can be switched, but smaller context dependent toolboxes which will all show if applicable at a certain time.
(←SO/OOo Q PCD)

Contact: Carsten Driesner (StarOffice)

EXT.INF.CR/0.5: Crash Recovery	(HINT:2)

Description: Crash recovery will be re-implemented in SO/OOo Q.
(←SO/OOo Q PCD).

Contact: Lars Oppermann (StarOffice)?

EXT.REQ: External Requirements

This sub chapter lists requirements which typical users of the OOoBean have but which are not in the scope of the OOoBean itself but rather in external products.

EXT.REQ.UNOT/0.8: UNO Timeouts	(MUST,SCOPE:2)

Qualifier: OOo does not answer on UNO calls anymore
(which most likely means that it hangs)

Description: When UNO should throw a timeout exception.

Stakeholder: Jürgen Kindler (FISCUS)

RemovalStakeholder: Kai Sommerfeld (StarOffice)

RemovalRationale: We cannot come up with a sensible rationale for this requirement. If the user gets impatient, a timeout does not really help because there is nothing which can be done other then cancelling the connection. And this can be done directly as soon as EXT.PREC.UNOC is solved. The application just should not block its own UI thread to allow the user to cancel the task.

EXT.REQ.UNOL/0.4: UNO Logging	(NICE,SCOPE:3)

Description: It would be nice to have a mechanism in UNO which logs all requested and performed calls.

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: This helps debugging especially in case of a crash of OOo.

EXT.REQ.TSOO/0.3: Thread Safe OOo	(MUST,SCOPE:3)

Description: The OOo API must be thread safe.

Risk: A hanging or crashing OOo might make the JavaBean unusable for the client software because it relies on unwrapped components directly from the OOo API:

Stakeholder: Jürgen Kindler (FISCUS)

EXT.REQ.CLS/0.7: Cancel Load/Save	(SHOULD,SCOPE:3)

Description: Loading and saving the document should be cancelable.

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: If a document needs very long time to load, users sometimes get impatient and want to stop the action.

EXT.REQ.CCP/0.4: Cut, Copy and Paste	(MUST,SCOPE:3)

Description: Functions similar to Cut, Copy and Paste must be available at an API level, based on selections at least for OOo/Writer. The content of the real clipboard must not be touched by these functions.

Deadline: 2003-12-01 (too big of a feature for a product patch (← Michael Hönnig))

Stakeholder: Jürgen Kindler (FISCUS)

Rationale: The stakeholder needs to copy text contents containing format information from one document to another.

EXT.REQ.STST/0.4: Stop/Start Timing in OOo	(MUST,SCOPE:2)

Qualifier: OOo is terminated and re-started right away

Description: A new connection has to be established about as fast as for the case when OOo is started without having a previous, terminating instance.

Plan: <= normal OOo start + 1s

Deadline: 2003-12-01

Stakeholder: Jürgen Kindler (FISCUS)

Source: email from Jürgen Kindler (FISCUS) on de@api.ooo at 2003-08-04 13:36h

Glossary

Operator, purely syntactical: A purely syntactical operator is an operator which does not result in runtime processing in a compiler language. Examples for such operators are the the Qualifier '.' and the statement separator ';'.

Term: A term is defined as any variable or type reference, any non-purely syntactical operator (Glossary: Operator, purely syntactical), any value and any members, including method names. E.g. the statemtent aBean.setSomething(null); contains 4 terms: 'aBean', 'setSomething', '()' and 'null'. The '.' and ';' are purely syntactical and therefore not counted.

Statement Complexity: Statement complexity is defined by the number of terms (->Glossary: Term) multiplied by the number of program flow parts (->Glossary: Program Flow Part). Example: The statement n > m ? i=1 : i=m; has a statement complexity of 33.

Program Flow Part: A program flow part is a number of statements or expressions, limited by the beginning or end of the whole statement sequence of any branch expression (->Glossary: Branch Expression). Shortcutting possibilities of boolean expressions are ignored for this matter.

Branch Expression: A branch expression is an expression which directly can cause the program flow to branch. Examples: if, else, while, switch, case, try, catch. A method or operator call which might result in an exception, is no branch expression.

Connection-URL: The connection-URL is a URL describing the host, port and method to access another process via UNO.

Fiscus has implemented a version check based on the version name. Note that we change the version number of the StarOffice installation that is reserved for embedded use in our application to avoid possible conflicts with installations (for non embedded use) that already exist or may be done after “our” installation is done. It might be necessary to make the version check configurable.

The source of software product implementation and change is the I-Team (Implementation Team). I-Teams are typically comprised of people who have skills in the areas of Product Marketing, Development Engineering, Technical Publications, and Test Engineering. I-Teams define the features or set of changes (based on input from SCs, customers, Engineering, or Marketing), plan the implementation project, perform the implementation and testing...

Document - ID	Spec Owner	Last Change	Status
SDK.Req.OOoBean/0.11	Michael Hoennig	2004-11-02	FINAL

SDK.Req.OOoBean/0.11: Glossary	Page 27/27

SDK.Req.OOoBean/0.11

Requirement Spec: general OOoBean

Michael Hönnig

2003-08-08T15:19:48