Comspec on Java (PDF) - JavaKomp

squawkpsychoticΛογισμικό & κατασκευή λογ/κού

2 Δεκ 2013 (πριν από 3 χρόνια και 8 μήνες)

75 εμφανίσεις








Comspec
TIDE Project No. 1169



Technical Specification Framework
Comspec on Java











Workpackage 1
Deliverable D24 part B

version 2.0


Delivery date: 29 May 1998




authors:
Alex Hekstra, Handicom, NL
Henk Klunder, Handicom, NL
Erlend Stav, SINTEF, NO


Project: Comspec, TP 1169
Comspec on Java
Page 2
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

Table of Contents
1. Introduction.....................................................................................................4
1.1 Background...............................................................................................................4
1.2 Java accessibility API................................................................................................4
1.3 Structure of this document........................................................................................4
1.4 Who this document is written for...............................................................................5
1.5 Conventions used in this document..........................................................................5
1.6 Where to find more information.................................................................................5
2. Outline of Comspec, running on Java...........................................................6
2.1 Overview....................................................................................................................6
2.2 Editing Environment..................................................................................................7
2.2.1 Introduction.......................................................................................................7
2.2.2 Data versus classes.........................................................................................7
2.2.3 Application hierarchy........................................................................................8
2.2.4 Services............................................................................................................8
2.2.5 UserLevel..........................................................................................................8
2.2.6 ClassRegistry....................................................................................................9
2.2.7 Mainwindow......................................................................................................9
2.2.8 ApplicationEditor...............................................................................................9
2.3 Run-time environment.............................................................................................10
2.4 Application...............................................................................................................10
2.4.1 Name..............................................................................................................11
2.4.2 State...............................................................................................................11
2.4.3 ObjectRegistry................................................................................................11
2.5 Application subsystems...........................................................................................11
2.6 Protocols.................................................................................................................11
3. Services.........................................................................................................12
3.1 Introduction..............................................................................................................12
3.2 ClassRegistry..........................................................................................................12
3.2.1 Introduction.....................................................................................................12
3.2.2 Design.............................................................................................................12
3.2.3 Description......................................................................................................13
3.2.4 Prototype (interface).......................................................................................15
3.3 ObjectRegistry.........................................................................................................15
3.3.1 Introduction.....................................................................................................15
3.3.2 Design.............................................................................................................15
3.3.3 Description......................................................................................................15
3.3.4 Prototype (interface).......................................................................................16
3.4 Storage and clipboard handling...............................................................................17
3.4.1 Introduction.....................................................................................................17
3.4.2 Design.............................................................................................................18
3.4.3 Description......................................................................................................18
3.4.4 Use.................................................................................................................22
3.4.5 Classes and Interfaces used for Comspec storage........................................23
3.5 Application State......................................................................................................24
3.6 User level.................................................................................................................24
3.7 Finding and Instantiating installable classes...........................................................26
4. Creating components...................................................................................27
4.1 General....................................................................................................................27
Project: Comspec, TP 1169
Comspec on Java
Page 3
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

4.2 Naming conventions................................................................................................27
4.3 ComspecContext.....................................................................................................27
4.4 Accessing services..................................................................................................28
4.5 Storage....................................................................................................................28
4.6 Application state changes.......................................................................................28
4.7 User level distinctions..............................................................................................29
4.8 Support classes.......................................................................................................29
4.9 Implementing Vocabulary Access...........................................................................29
4.10 Interaction with the Editing Environment.................................................................30
4.10.1 Editing Properties...........................................................................................30
4.10.2 Icons...............................................................................................................31
4.10.3 Interaction with the Editing system.................................................................31
4.11 Creating Layout components with special editors...................................................31
4.11.1 Introduction.....................................................................................................31
4.11.2 Available services in the layout editing system...............................................32
4.11.3 Associating an editor with a layout component...............................................32
4.12 Creating new Vocabulary Representation Types....................................................33
4.12.1 Introduction.....................................................................................................33
4.12.2 Representation Viewer...................................................................................33
4.12.3 Representation Editor.....................................................................................33
4.12.4 Representation Selector.................................................................................34
5. Overview of packages..................................................................................35
Appendix A - Glossary...........................................................................................36
Appendix B - Programmers Reference in JavaDoc............................................40

Project: Comspec, TP 1169
Comspec on Java
Page 4
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

1. Introduction
Version 1.0 of this document was released as Deliverable D20. This updated and
revised version forms a part of Deliverable D24.
1.1 Background
The first phase of this TIDE project resulted in the design of the Comspec Software
System, which was described in 1995 by the 'Architecture & Protocols' [Sva95], and
the 'Functional Specification' [Odo95] documents, published as the two parts of
Deliverable D2. OpenDoc was chosen as the platform, the 'Technical Specification'
[Tyv95] (Deliverable D3) was written, and implementation was started. In early
Spring 1997, the designers of OpenDoc ceased to support this environment and
therefore it was technically and economically unrealistic to continue the project on
this basis. The Comspec Consortium searched for an alternative platform instead of
abandoning the project. After a technical feasibility study, this resulted in the
consortiums decision, with the approval of the European Commission, that Comspec
be implemented on the Java platform.
This document replaces the original Technical Specification [Tyv95], and describes
how the basic parts of Comspec are implemented on Java and which Java features
and support systems are used. It provides a guide line for developers to produce
their own modules for the Comspec System. Many technical details about the
components can be found on our Web site (see 1.6 below) in documentation
generated from the source code by JavaDoc.
1.2 Java accessibility API
JavaSoft is developing an Accessibility API at the same time as Comspec is being
rewritten using Java. Java Access focuses on making 'standard' programs more
easily accessible for disabled users. Comspec, on the other hand, will provide
specialised building blocks and tools for the development and provision of tailored
Alternative and Augmentative Communication and Access systems for more
profoundly disabled users.
These two aspects are complimentary. Comspec systems will benefit from the Java
Accessibility features in the interaction with standard Java software. The Java
Accessibility API will make it easier to provide the 'External Application Glue'
mentioned in the Formal and Functional specifications for Comspec. It may be
possible that future versions of the Java Access API and Comspec could be more
closely interrelated, but today the systems are addressing too different needs to be
rapidly integrated.
1.3 Structure of this document
Chapter 1 this introduction
Chapter 2 overall structure of Comspec based on Java / JavaBeans
Chapter 3 services Comspec offers for its components
Chapter 4 what components should comply to in order to be used with other
components to build applications.


[Sva95] Svanæs, Dag, et al, 1995, Comspec Architecture & Protocols, Formal description,
version 1.0., (Comspec consortium)
[Odo95] Odor, Phil, 1995, Functional Specification (and User Handbooks), release 1,
(Edinburgh, Scotland)
[Tyv95] Tyvand, Steinar, et al, 1995, Technical System Specification of Comspec, release 1,
07.07.95., (Comspec consortium)
Project: Comspec, TP 1169
Comspec on Java
Page 5
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

Chapter 5 package structure of the basic Comspec software

1.4 Who this document is written for
This document addresses
· members of the Comspec Developers Group
· (third party) developers who wish to create new Comspec components
The reader is assumed to be familiar with the Comspec philosophy and the intended
purpose of these standards for the Rehabilitation Technology Industry.
The reader should have knowledge of Java and JavaBeans in order to fully
understand the technical details.
1.5 Conventions used in this document
In this document, often a reference is made to the user as a male person. This is not
because we expect every user to be a male, but writing "he / she" does not improve
readability. The user is kindly requested to replace "he" with "she" or "he / she" if the
reader feels that that is more appropriate.

When words are marked italic, they have a specific meaning and can be found in
Appendix A: Glossary.
Text in monospace indicate something literal from the Java language or
conventions: an example, a class name or a package name.
1.6 Where to find more information
· The 'Architecture & Protocols'[Sva95] is a formal specification describing the
architecture of Comspec. This document has been updated in 'Architecture
Update' [Sta97] in order to fill in some gaps and some redesigns which are
needed to comply with the Java Beans.
· The Functional Specification[Odo95] describes the Comspec philosophy from
more or less the users point of view.
· Every developed component (which will be one or more Java classes) will be
accompanied by documentation generated by JavaDoc. Detailed information on a
specific component can be found there.
· A Comspec Web site is available where the latest versions of the documents can
be found, as well as other information on the project and technical information
sheets. The address is: http://www.oslo.sintef.no/comspec
· The Java Web site is at: http://java.sun.com/



[Sta97] Stav, Erlend, 1997, Update on the Comspec Architecture, version 0.1, 30/9/97',
(Comspec consortium)
Project: Comspec, TP 1169
Comspec on Java
Page 6
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

2. Outline of Comspec, running on Java
2.1 Overview
Applications, such as a symbol based environment control or a switch operated
speaking device, can be created and tested using the Editor and can be controlled
by the End-User using the Runner. The  Runner is a separate application (the
Run-time Environment) which will load and run the Comspec Application.
Each application is built from components. Using the Editor, an integrator selects
components, links them together, and sets properties such as component names,
connections to other components, language/vocabulary content, and the appearance
of the user interface - including screen layouts, colour settings, sound etc.


An integrator uses components and editors to create applications which can than be
transferred to the computer systems of the intended end-users. The end-user just
needs to have the Runner installed on his computer together with at least those
components referred to by his application. However, if a facilitator is to make
changes to the application on the end-users computer, then the editors also need to
be installed there.
The basic Comspec system can be downloaded from the Comspec web site. The
installation procedure will distinguish between a 'full install' (editing environment, run-
time environment, all components), or a 'run-time install' (only the elements needed
to run Comspec Applications). Third party modules can be obtained from their
developers and should have their own installation procedures. These modules will
have to be installed separately on the integrator / facilitator computer and the end-
user computer, depending on the type of module.
In future, an 'Application packer', integrated with the Editing Environment, could be
created which packages all components needed to run a Comspec Application
(software and data) into a single package. This package could then be copied to any
computer with a Java Virtual Machine installed on it, and be run. However, the
provision of an 'Application packer', is beyond the scope of this project.

The Editing Environment and the Run-time Environment both offer services to their
contents: the Applications. In turn, Applications offer services to their own contents.
Components
Editors
Editing
Environment
Applications
Runtime
Environment


Figure 1: Overview of how Components are used in the Editors to create Applications

Project: Comspec, TP 1169
Comspec on Java
Page 7
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

The access to the services is done through a structure called ComspecContext,
which is a subset of the BeanContext system proposed by JavaSoft [Cab97].
2.2 Editing Environment
This section introduces and explains many basic concepts of the Comspec system.
2.2.1 Introduction
An Application is a collection of data defining the aid for the user. To the end-user,
the Application will appear as an independent program, but technically it is a
'document' with information for the Run-time Environment. An Application consists of
a number of 'building blocks', the Application Subsystems.
An Application SubSystem represents a major aspect of the Application, such as the
visual and auditory appearance. Application SubSystems form the basis of an
Application, an Application only contains Application Subsystems: Application
Subsystems are top level components. In turn, Application Subsystems only contain
non-top level components.
We foresee the need for four Application Subsystems:
· Layout - the appearance of the application to the user on screen, auditory, etc.
· Configuration - the internal communication structure of the application (input
handling, communication to the layout, output handling)
· Vocabulary - maintaining the language material (texts, symbols, commands,
recorded speech, etc.) for the application
· Toolbar - a centralised and easy way to change properties of components, e.g.
scan speed, volume level
Each one has a specialised editor. If in the future other Application Subsystems are
constructed, these can be added to the Comspec System and embedded in
Comspec Applications.

In the Application Subsystems, the user may add various components. A Component
is a Java class, the representation of which the user can select from e.g. a tools
palette, add to the application, and then set its properties. A component may contain
other components: it can be a container. A component may use other classes, but
these helper classes are not components: the user does not manipulate them
directly. Example components are SingleSwitchInput (for a configuration),
DisplayItem and CardStack (for a layout).
Note that the Application and the Application Subsystems are also components and
containers. But the way they are created differs from other components as they are
not selected from a toolbar, they are automatically created when needed.

The Comspec Editing Environment is a program which will allow the integrator and
facilitator to create and edit the Applications. It will read information from a registry to
learn about the installed Application Subsystems, Components and their specialised
editors. It will allow the user to add or remove Application Subsystems in an
Application. To edit the Application Subsystems, the Editing Environment will activate
the specialised editors for the subsystems.

2.2.2 Data versus classes
In the introduction above, the Application was described as being data stored in a
file. There is also an Application class, a piece of object-orientated software which


[Cab97] Cable, Laurence, and Hamilton, Graham, A Draft Proposal to define an Extensible
Run-time Containment and Services Protocol for JavaBeans (Version 0.97), JavaSoft.
Project: Comspec, TP 1169
Comspec on Java
Page 8
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

can perform various actions on the data. This combination of data and class applies
to every component in the Comspec System.

2.2.3 Application hierarchy
This figure illustrates the relation of the Application and its Subsystems. Although
this figure shows four Application Subsystems, they do not need to be present for all
Applications. In the future, other Application Subsystems could be designed. These
would be at the same level as the four in the figure.


2.2.4 Services
The Editing environment offers several facilities:
· maintaining a user level (integrator, facilitator) (Note: the developer and end-user
roles or levels are not present in the Editing Environment: the developer is a
programmer, the end-user uses the Run-time Environment)
· Class Registry (for installed components)
· MainWindow + dynamic menu bar
· An ApplicationEditor to display and edit the contents of a Comspec Application
· Maintain a list of loaded applications and attach an application editor to them
· Switching between application editors during editing
· Run-time test facilities
· storage facilities (the services for editors to store and retrieve data from a
storage, and the user interface needed for the user to access these facilities)

In this document, these facilities are called 'services', because that term is used most
often in the Java world.

Some of the concepts used in these services are explained below.

2.2.5 UserLevel
Comspec users take one of the four defined User Roles.
· Developer - creates new components
· Integrator - creates and edits Comspec Applications
· Facilitator - does day-to-day adjustments to Comspec Applications
· End-user - user of Comspec Applications
The user in the developer role will never use the running Comspec software, he will
use another tool (a Java compiler) to create components. The other three user roles
(integrator, facilitator or end-user) use the Comspec software. The role of the user is
Components
Configuration
Components
Components
Vocabulary
Layout
Application
Components
Toolbar


Figure 2: Application and Application SubSystem relationship

Project: Comspec, TP 1169
Comspec on Java
Page 9
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

reflected in the User Level. This User Level is maintained by the Editing environment
and can be used, for instance, to filter properties during editing. The system
integrator has full access to all public properties, the facilitator less. See paragraph
3.6 for details.

2.2.6 ClassRegistry
Each component has to be registered before the integrator/facilitator can add these
components to the application he is building. This registering will be handled by the
ClassRegistry. The editors will need several services from the ClassRegistry.
In the future, an Component Installer will build this ClassRegistry, to assist people
during installation of new components or Application Subsystems. During the lifetime
of this project the ClassRegistry data (the file) will be updated manually, using a text
editor.
As with any Java application, the applications require that all components are
available on the system in order to run. In principle the ClassRegistry is not needed
to run applications. But as Comspec aims to be portable, modular, flexible and easy
to use, additional services are needed to help the user to verify the existence of
needed components and the required version of them whenever they install or run
new applications.

One of the required services is to generate a list of installed components based on
specified criteria.
Examples: The Application Editor will want to know about installed Application
Subsystems, so it will want to ask something like "Get me all installed components,
but only those which are Application Subsystems". The Layout Editor will only want
to know about Layout components, an Application will want to get an implementation
for the service "ObjectRegistry".

2.2.7 Mainwindow
This MainWindow will be the user interface to offer the menu for loading/saving
applications, viewers for the different editors, and so on. Subsystem Editors can add
their own menus to this menu bar. The MainWindow also contains a button bar for
quick access to most commonly used commands in the menu, and a
ComponentPalette where the available components for a subsystem are represented
by button: the user can select a component on the palette by pressing its button, and
place it in the subsystem.

2.2.8 ApplicationEditor
The application editor allows the user to:
· add/remove/edit Application Subsystems
· edit application properties
· control the application
· import/export an Application Subsystem from/to a template (templates are
explained at the end of this section)

Adding and removing Application Subsystems is done automatically: if the user
clicks on the tab for a subsystem, and that subsystem is not present in the current
application, it will be added. If a subsystem is empty when an application is saved,
the subsystem will not be saved in the application.

The Application Editor will offer several services for components. Components can
use these to create easy-to-understand user interfaces. These services are:
Project: Comspec, TP 1169
Comspec on Java
Page 10
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

· add default behaviour for newly created applications
· give access to the (Application Subsystem) editors
· add component-specific menu items to the menu-bar (based on an Application
Subsystem and/or selected object)
· load and save applications

The application editor will maintain editors for every subsystem. It finds the available
subsystems and their editors in the class registry

Templates are (parts of) Applications which can be included in other applications,
much as you can save 'template documents' in a word processor.
Examples:
· A well designed and complete Vocabulary for one user can be used in a new
application for the same user.
· A selection area in a layout, where the user can access the symbols in his
vocabulary, can be used in the layout of another application.
· A complex configuration and layout, for a complex 'communication centre' (with
support for telephone, front-door monitoring, speech, and print output) can be
developed and sold as a product.
2.3 Run-time environment
The Comspec Run-time Environment (the Runner) will allow the user to load and run
one or more applications.
When started with an application name on the command line, the runner itself will
remain hidden from the user and the application(s) will run automatically. Otherwise
a window (with an application list) will appear from which the user can select the
application to be run.
The runner will offer several services to the loaded application which are needed to
run it.
2.4 Application
The application which is being created using the Editing Environment will contain
data on its structure and properties.
It will always contain:
· an application name
· the state in which it is (loading, editing, running etc.)
· a registry of instantiated objects (ObjectRegistry)
· entries to Application Subsystems (if an Application Subsystem is empty, it is not
present by default. There will only be one entry stored for each subsystem)

There are several reasons why an Application Subsystem may be empty:
· The application may be stored as a template.
· The Comspec Application may use external application glue to control another
application (non-Comspec), e.g. a word processor, where the Comspec
Application itself does not need a layout, and the other Application has its own
user interface.
· additional (future) Application Subsystems may or may not be added.

An Application is both a ComspecContext for its subsystems and the components
therein, and a ComspecContextChild using the services of its context, the Editing
Environment or the Run-time Environment.

Project: Comspec, TP 1169
Comspec on Java
Page 11
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

2.4.1 Name
The name will follow general naming conventions, but does not have to be unique.

2.4.2 State
The state of the application will be maintained and can be: loading / starting / running
/ stopping / editing. This state can be offered to any component in the application if it
needs to know the state of the application at that specific moment.

2.4.3 ObjectRegistry
The ObjectRegistry maintains a 'name space'. All items in this name space must
have an unique name. When an objecty registers with the ObjectRegistry, this
registry will check the name of the object, and make sure the name is unique, e.g. by
adding a number to a default name.
At Edit-time, these names may be presented to the user to select a component. At
Run-time, a script engine may use these names to access the components.
2.5 Application subsystems
Currently the Comspec system has four subsystems:
· Configuration
· Layout
· Vocabulary
· Toolbar

Each of these subsystems should:
· be a ComspecComponent (this means also that it must be a JavaBean and
implement the java.io.Serializable interface, with the additional Comspec
storage requirements)
· be representable in the Application Editor window. This can be done through
standard BeanInfo support for an icon, and something like a name property.
· be registered in the ApplicationSubsystem Registry (part of the ClassRegistry)
· have an Editor (this Editor will only be used at edit time)
· be storable as a separate file
· support create/new/clear/load/store of subsystem
· should implement an editing protocol with its editor

Note that the Toolbar is a very desirable subsystem to have in Comspec, but the
functionality will be limited in the first releases. Only a few controls will be available,
e.g. a number input for numerical properties and a checkbox for boolean properties,
making some properties unavailable for modification via the Toolbar.
2.6 Protocols
In Java the Comspec protocols are implemented as interfaces. The main run-time
interactions between the components is done using these protocols. The protocols
can be found in the comspec.protocol package, and a description is found in the
JavaDoc generated documentation found on the Comspec web site.

Further information on the protocols can be found in the Formal Description
document, and its addendum.

Project: Comspec, TP 1169
Comspec on Java
Page 12
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

3. Services
3.1 Introduction
In Comspec there are various situations where a component in the system needs to
know something of its environment. The environment must then do something for the
component. This is what the services are about.

The services designed are:
· ClassRegistry - a list of installed components. Editors access this list to allow the
user to select an installed component and use it in a Comspec Application.
· ObjectRegistry - a list of used components in the Applications. Editors access this
list to allow the user to select other components in the Application to create links
between components. The software can query this list based on a name, or on a
superclass, e.g. all components which implement a certain protocol.
· Storage facilities - Used by the Editors, Editing Environment, and Run-time
Environment to store and retrieve Applications, Application Subsystems and parts
of applications, where objects and their properties and the links between objects
are stored in a reliable way.
· Application State - to control the starting, running and stopping of an application.
Components can check the application state to see if e.g. timers must be started.
· User Level - to hide the more complex issues for facilitators and end-users.
3.2 ClassRegistry
3.2.1 Introduction
The ClassRegistry is used to find the classes (software) available for creating
Comspec Applications. Besides the editors, other parts of the Comspec system may
also need support from the ClassRegistry, for example: the Application Runner, to
verify if the required components are available on the system and are of the required
version.

3.2.2 Design
The ClassRegistry:
· holds available components for an installation of Comspec
· distinguishes between subsystem components (e.g. layout components,
configuration components)
· lists available Application Subsystems
· lists installed services
· offers editors easy access
· lets developers install new components easily
· contains or provides access to the following data:
· name
· class
· type (layout component, configuration component, toolbar component,
vocabulary component, application subsystem)
· lets developers register one component in more then one sub-registry
· lets developers register non-Comspec components too
· allows developers to remove components removed from the registry

Project: Comspec, TP 1169
Comspec on Java
Page 13
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

3.2.3 Description
Class registry file format

The format is a simple text file with certain special characters. Changes to the Class
Registry are done by editing this file. Developers should create installation routines
which change this file for the integrators

The first character defines the purpose of the line. The structure of this file is like
this:

[registry group1]
*full.class.Path1
-param1=data
-param2=data
*full.class.Path2
-param1=data
-param2=data
[registry group2]
*full.class.AnotherPath
-param1=data

Each line of the file is checked for the first character on the line. If it is one of the set
of special characters, this line is processed. If the first character is another character,
the entire line is skipped.

Special first characters:
Char meaning
[ group name for a ClassRegistry group. Line must end with ].
* component in this ClassRegistry group
- line is a property or parameter for the above component
; line is a comment

Empty lines are ignored, comment lines are skipped

The parameters are used, for instance, to define the editor for the class.

Pre-defined parameters

In the [Application] group, the following parameters are defined:
· Editor - to specify an alternative editor. If this parameter is not specified, an
Application Subsystem editor is expected to be in a special class. If the
Application Subsystem is in a class
<path>.subsystem.SubSystem,
the editor is expected to be in the class
<path>.subsystem.editor.SubSystemEditor.
The example below defines the editor exactly as the default.
· Extension - the default extension for files containing saved subsystems.
· MaximumUserLevel - the highest user level where this subsystem should be
visible in the Editing Environment, 1 = visible only for integrators, 2 = visible for
integrators and facilitators

Example:
Project: Comspec, TP 1169
Comspec on Java
Page 14
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

[Application]
*comspec.layout.Layout
-Editor=comspec.layout.editor.LayoutEditor
-Extension=layout
-MaximumUserLevel=2

In the Application Subsystem groups (Layout, Configuration etc.) the installed
components are listed. Parameters:
· Group - to group components on a component palette (not yet implemented)
· Label - the name of the component as it should appear in the 'ToolTip' over the
button in the component palette.

Examples:
[Layout]
*comspec.components.simpleelement.SimpleElement
-Label=Display item
-Group=Display elements

[Configuration]
*comspec.component.switchinput.SingleSwitchInput
-Label=One Key
-Group=Input

The ClassRegistry also contains references to installed services. In the section
[Services] the links are made between the service protocol (the definition of the
service) and the service implementation. For each service in Comspec, a default
implementation is available, but in future these could be replaced by better
implementations.
[Services]
*comspec.system.ServiceInterface
-Implementation=company.name.comspec.AlternativeImplementation

If an entry is not found, or the -Implementation parameter is missing, the
implementation is assumed to be in the class with the same name as the interface,
with "Support" added.

The ClassRegistry also contains a list of data types to be used as representation
data for Vocabulary Items. Based on the MIME-type specifications used in internet
communication, entries in the [RepresentationTypes] section contains the name of
the data type, and information for the system how to handle data of this type. The
parameters defined are:
· Viewer - a RepresentationViewer (defined in the VocabularyRetrieval protocol)
capable of viewing data of this type.
· Editor - an (optional) class which can be used to edit data of this type
· Selector - an (optional) class which can be used to select data of this type from a
special database. If not specified, the FileSelector class will be used to select data
(files) from the "HardDisk" database.
· Extensions - file extensions for selecting data stored in separate files
· DefaultID - an ID to use for representations with this type of data


ClassRegistry access

To access the registry, an Editor needs to access the ClassRegistry service first.
This is done through the ComspecContext:

Project: Comspec, TP 1169
Comspec on Java
Page 15
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

ClassRegistry srv =
(ClassRegistry) ctxt.getService(ClassRegistry.class, this);

When a handle to the ClassRegistry is retrieved, it can be accessed. The
ClassRegistry contains a number of groups, each group contains a number of
ClassRegistryEntry objects.

3.2.4 Prototype (interface)
public interface ClassRegistry {
public Vector getGroupNames();
public Vector getClassNames(String groupName);
public Enumeration getClasses(String groupName);
public ClassRegistryEntry getClass(String groupName,
String className);
}

public interface ClassRegistryEntry {
public String getClassName();
public Vector getPropertyNames();
public String getProperty(String propertyName);
}

Class names are case sensitive and are full paths to the Java classes (excluding the
file extension). Group names and property names are case insensitive.

The interfaces can be found in comspec.system.ClassRegistry and
comspec.system.ClassRegistryEntry. Default implementations of the
ClassRegistry and the ClassRegistryEntry can be found in
comspec.environment.ClassRegistrySupport and
comspec.environment.ClasRegistryEntrySupport.
3.3 ObjectRegistry
3.3.1 Introduction
The ObjectRegistry is a service for components to find other components by name
or by type. Editors can use this service. For example, when setting a link, the Editor
can present the user with a list of components to which links can be made. A script
interpreter can use this service to execute the script.

3.3.2 Design
The ObjectRegistry will:
· define the 'name space' in which objects can be found by a unique ID
· be able to add/remove registered objects

3.3.3 Description
This section describes how Comspec Components should interact with the
ObjectRegistry: the ObjectRegistry protocol.

· The Comspec Components will always have an ID (String). The default ID is the
name of the component with "1" added. The user can change the ID in the
appropriate editor. If the ID has changed, this editor will call the setID() method of
the component. The setID method should check if this ID is already in use in its
ComspecContext (using the ObjectRegistry method findComponent(newID) ). If
not in use, the component should un-register itself, accept the new ID, and
Project: Comspec, TP 1169
Comspec on Java
Page 16
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

register itself again. If the new ID is in use, the setID() method should throw an
IDAlreadyUsedException: the ID is already used by another component.
· If the ComspecContext for the component is set, the component should register
itself with the ObjectRegistry for this ComspecContext. If the new
ComspecContext differs from the old ComspecContext, the component should
unregister itself from the old ComspecContext. Even if the ComspecContext set is
the same as the original ComspecContext, the component should register itself.
There are basically two cases when a ComspecContext will be set:
1. The component is created. The ID will be the default ID, but maybe this ID
is already used
2. The component is read from a stream (file loading, clipboard pasting) and
inserted into some container. The ID may be changed by the user, but this
ID may is already be used. (This will usually be the case with clipboard
copy and paste)
· When an object registers itself, the ObjectRegistry will modify the ID if the ID is
not unique. If the ID is already in use, the ObjectRegistry uses a numbering
scheme which appends a number to a string to create an unique ID. The return
value of the registerObject() method indicates if the ID was changed. The
component will always be registered, regardless of the return value.

Note: the ID is the 'name' of a component as the user will see it.

3.3.4 Prototype (interface)
The definition of the ObjectRegistry is:

public interface ObjectRegistry {
public boolean registerObject(ComspecComponent c, String
defaultID);
public void unregisterObject(ComspecComponent c);
public ComspecComponent findObject(String ID);
public Vector IDs();
public Vector IDs(Class protocol);
public Vector IDs(Class[] protocols);
public Vector objects();
public Vector objects(Class protocol);
public Vector objects(Class[] protocols);
}

public interface ComspecComponent
extends ComspecContextChild {
public String getDefaultID();
public void setID(String newID) throws IDAlreadyUsedException;
public String getID();
}

Note: The ComspecComponent interface presented only shows the part needed for
the ObjectRegistry.

The interface for the ObjectRegistry can be found in
comspec.system.ObjectRegistry. A default implementation of the
ObjectRegistry can be found in
comspec.application.ObjectRegistrySupport.
The interface for the ComspecComponent can be found in
comspec.system.ComspecComponent. A default implementation for Comspec
Components can be found in
Project: Comspec, TP 1169
Comspec on Java
Page 17
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

comspec.component.ComspecComponentSupport. Developers can do one of
three things:
· fully implement the CompspecComponent interface in their own components
· subclass the ComspecComponentSupport class
· delegate the implementation of the ComspecComponent interface to the
ComspecComponentSupport class
The second or third option are recommended.
3.4 Storage and clipboard handling
3.4.1 Introduction
A Storage mechanism is needed to store Applications, Application Subsystems, and
components to files, and to store one or more components on the clipboard for cut-
and-paste or drag-and-drop operations.
This mechanism should, of course, also handle the retrieval of the information
stored.

Java has support for storage in the Serialization and Externalization
mechanisms. These mechanisms are relatively simple: pass an object to the storage
writer, and the component and all related (linked) objects will be stored.
For Comspec, however, we need a system with a finer detail:
· if a group of components in the layout is selected and copied to the clipboard,
only the links within the selection must be stored; links to components outside the
selection must not be stored, nor the components linked to
· when components are read back from the storage, links must be re-created to the
corresponding new objects, not to the original objects (if they still exist)

The problem with Java's serialization is that it is difficult to maintain compatibility
between versions of software. If, for instance, class ancestry is changed, or a few
properties are dropped in favour of some new, more advanced properties, the
system cannot read files created with older versions. Since various components are
based on Java's own classes, or third party classes, it is not possible to guarantee
compatibility of stored subsystems between different versions of the software.

In the Comspec system, two storage mechanisms are available:
· Extension on the Java Serialization mechanism
· A Comspec Storage system

Each of these storage systems handle the details listed above, e.g. restoring links
between components. The Serialization based storage system is best used for short-
term storage (e.g. clipboard operations), while the Comspec Storage system is to be
used for long-term storage (e.g. storage to file)

Note: the serialization mechanism stores and restores property data without
changing it. The exception is the link to other components. The containing
environment (e.g. an Editor or the Run-time Environment) must make sure extra
requirements on properties are met. An example of such a requirement is the
component IDs: they must be unique in their name space. A protocol is created in
solving this issue: see section 3.3 for the protocol assuring the component IDs
remain unique. Other similar issues will have to be handled outside the storage
mechanism.

Project: Comspec, TP 1169
Comspec on Java
Page 18
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

3.4.2 Design
File operations:
· The storage should be easy to implement for each component
· The user should get a reasonable message if something goes wrong
· If one or more of the components used to create an application are not available
when the application is loaded on a system, the user should get a message
explaining which components are missing (including their version numbers)

Behaviour of clipboard transfers:
· Selections of objects may be transferred to and from the clipboard within the
same application and between open applications
· When a set of components is transferred from the clipboard, all connections to
components within the set will be maintained; all other connections will be broken

3.4.3 Description
There are two storage mechanism. One is based on the Java Serialization
mechanism, the other is a separate implementation which allows versioning of data.

Serialization based mechanism

With the Serialization based mechanism, most of the aspects of storage are handled
automatically. However, this standard system does not provide the fine detail we
need in Comspec, and the default error handling is not enough to fulfil our
requirements as the error messages are often too cryptic for the user. The two core
classes of Serialization mechanism, the ObjectOutputStream and
ObjectInputStream, will be extended versions to have more meaningful error
messages, and to add the necessary extra functionality.

This extended storage system has been defined as a set of interfaces. A software
developer could create a more enhanced system based on these interfaces, but a
default implementation is provided with the basic Comspec System. The interfaces
defined below should be implemented by the ObjectOutputStream and
ObjectInputStream subclasses used for storage in Comspec.

The Comspec additions to the storage system consists of three interfaces. All
connections to other components (except for the references containers hold to
contained components) should be kept in objects supporting the
ComspecComponentLink interface. During storage to streams that support the
ComspecOutputStream interface, these link objects are responsible for requesting
a storage reference from the stream, that should be saved instead of a direct
pointer. When reading from a stream that supports the ComspecInputStream
interface the link objects are responsible for registering themselves with the stream,
and on request, resolving the storage ID by calling the getComponentForID method
of the stream.

public interface ComspecComponentLink {
public ComspecComponent getComponent();
public void resolveRef(ComspecInputStream in);
}

public interface ComspecInputStream {
public void addRefToBeResolved(ComspecComponentLink link);
public ComspecComponent getComponentForID(int fID);
}

Project: Comspec, TP 1169
Comspec on Java
Page 19
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

public interface ComspecOutputStream {
public int generateID(ComspecComponent component);
public Vector getUsedClassDescriptions();
}

In addition to these interfaces, the Comspec system contains classes with
standard implementations of these interfaces, named after the interfaces
with ...Support" added at the end.

Comspec Storage System

The Comspec Storage System is based on the ideas in the Bento storage
mechanism in OpenDoc. The Comspec Storage System allows one root component
to store its data.
· The 'Storage' is a collection of storage units.
· Each object stores its data in one storage unit. This strict separation of data for
each object provides a high level of robustness in the storage system.
· References to other objects are either stored as a strong or as a weak reference.
The Storage System will assure that the object referenced by strong references
are stored too. When reading back, a reference resolver will restore the links if
the objects originally referred to were also stored in the same storage.
· It is possible to write the data of an object in several formats. If, for instance, a
class is updated, it can write both the data in the format used by the old version,
and data in the new version. When reading data, the class can check for data
available in in its current format version, or in older format versions. It is possible
to maintain compatibility with older versions, and current versions, and newer
versions. Large data blocks which format is identical across multiple versions can
be written to a separate data block (e.g. storing images), thus reducing stored file
size.
· Each object actively participating in the Storage must implement the
comspec.storage.StorableComponent interface, and write its own property
data to the storage.
· The term 'property' in the Comspec Storage System refers to all the data (all the
property) of an object, not to a single property of a component.

The Comspec Storage System is defined in several interfaces in the
comspec.storage package:

Project: Comspec, TP 1169
Comspec on Java
Page 20
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

public interface StorableComponent {
public void writeToStorage(StorageWriter writer);
public void readFromStorage(StorageReader reader);
public void postReadFromStorage(StorageRefResolver resolver);
}

public interface StorageWriter {
public void addProperty(StoredProperty property);
public void addPropertyVersion(String propertyName,
String versionName, byte[] data);
public int createWeakRef(StorableComponent component);
public int createStrongRef(StorableComponent component);
}

public interface StorageReader {
public StoredProperty[] properties();
public StoredProperty getProperty(String propertyName);
public byte[] getPropertyVersion(String property,
String version);
}

public interface StorageRefResolver {
public StorableComponent resolveWeakRef(int componentRef);
public StorableComponent resolveStrongRef(int componentRef);
}

The comspec.component.StorageSupport class is created to store commonly
used objects used in Java, e.g. to store Strings, Components, Containers, Fonts,
Colors etc.

The StorableComponent interface should be implemented by all Comspec
Components. The internal data format is entirely the responsiblility of a component
developer. Usually, the class will create a java.io.ByteArrayOutputStream, and a
java.io.DataOutputStream on top of that. All persistent property is written to the data
stream. References to other components should be written as a reference. A sample
implementation is given below. A few rules of thumb:

· the StorableComponents must have a parameter-less constructor
· if the super class is a StorableComponent, storage of inherited property data can
be done by calling the super's methods
· data should be stored with a name unique for the component. If all classes in the
inheritance tree store the data as "Property", a subclass will overwrite the data of
the superclass. Store the property data with the same name as the class.

Example:

public class FabulousComponent extends ComspecComponentSupport {


// must support parameter-less constructor
public FabulousComponent() {
super();
....
}

....
Project: Comspec, TP 1169
Comspec on Java
Page 21
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

private static final String storageName = "FabulousComponent";
private static final String storageVersion = "v1.0";
private transient int linkRef = -1;

public void writeToStorage(StorageWriter writer) {
try {
super.writeToStorage(writer);

ByteArrayOutputStream bst = new ByteArrayOutputStream();
DataOutputStream dst = new DataOutputStream(bst);

// write properties
...
dst.writeInt(dst, writer.createWeakRef(link)));
...

dst.flush();
dst.close();

writer.addPropertyVersion(storageName, storageVersion,
bst.toByteArray());
}
catch (Exception e) {}
}

public void readFromStorage(StorageReader reader) {
super.readFromStorage(reader);
byte[] propData = reader.getPropertyVersion(storageName,
storageVersion);
if (propData == null)
return ; // error
try {
ByteArrayInputStream bst =
new ByteArrayInputStream(propData);
DataInputStream dst = new DataInputStream(bst);

// read properties, read links as references (int values)
...
linkRef = dst.readInt();
...

dst.close();
}
catch (Exception ex) {
}
}

public void postReadFromStorage(StorageRefResolver resolver) {
super.postReadFromStorage(resolver);
// resolve reference links
if (linkRef != -1) {
link = resolver.resolveWeakRef(linkRef);
linkRef = -1;
}
}

The default implementation of the Comspec Storage System is in the
comspec.storage.ComponentStorage and the
comspec.storage.StorageUnit classes

Project: Comspec, TP 1169
Comspec on Java
Page 22
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98


3.4.4 Use

Storing and restoring a Comspec Application or Subsystem

A stored Comspec application or subsystem consists of a single file. This file
contains all the information needed to restore an application or subsystem, and
some extra information that will be used for meaningful error messages in the event
of a missing component when the application or subsystem is read.
The structure of the file can be browsed by a special program In the future it can also
be utilised by installers that want to package required component classes with the
application.

When an application or subsystem is saved to a file, the following steps are
performed:
· Get the installed StorageWriter implementation class by querying the
ClassRegistry
· Create an instance of the class found
· Write the root object to this StorageWriter
· Create a FileOutputStream, and create a DataOutputStream on top of that.
· Write the contents of the Storage to this stream
· Flush and close the stream

When an application or subsystem is restored, the following steps are performed:
· Get the installed StorageReader subclass by querying the ClassRegistry
· Create an instance of the class found above
· Create a FileInputStream and a DataInputStream on top of that.
· Let the Storage read the content form the file
· Read the root component from the storage
· Close the stream instance


Storing and restoring a set of components or objects

For short-term storage, the Serialization based system is used for storage. When a
(set of) objects is stored, the following steps are performed:
· Get the installed ComspecOutputStream subclass by querying the ClassRegistry
· Create an instance of the class found above, on top of a FileOutputStream or
ByteArrayOutputStream
· Write all the objects to this instance
· Close the streams

When an application is restored, the following steps are performed:
· Get the installed ComspecInputStream by querying the ClassRegistry
· Create an instance of the class found above, on top of a FileInputStream or
ByteArrayInputStream
· Read all objects from this instance
· Close the streams

Requirements set for components to behave correctly in the Storage mechanism can
be found in Chapter 4.

Project: Comspec, TP 1169
Comspec on Java
Page 23
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

3.4.5 Classes and Interfaces used for Comspec storage
ComspecOutputStream

This interface will be used for storage of Comspec Applications and for writing to the
clipboard. During the transfer, this object will build a list of all the transferred classes.
The list can be retrieved from this object and written in a separate file. It will also be
able to generate storage ID's for a ComspecComponent held by
ComspecComponentLink instances. The list of IDs and their corresponding
components will be stored in the stream.

ComspecInputStream

This interface will be used for retrieving Comspec Applications and for reading from
the clipboard. During retrieval, objects implementing the ComspecComponentLink
interface will register themselves with this object. When closing the stream, all the
registered ComspecComponentLink instances will be told it is time to resolve their
reference, and will get a ComspecComponent pointer back given the storage ID.

ComspecComponent

Through the ComspecComponent interface the storage mechanism can find a
description of the class and its version that is suitable to display to users if the
component is missing or is a wrong version. This information is stored in the
separate text file that lists all components used to create an application.

ComspecComponentLink

Instances of this interface will be used to hold all persistent references between
Comspec components except the references containers hold to contained
components. When writing to storage, these objects will store references to other
components by requesting storage IDs from the output stream, and writing these IDs
instead of the direct pointer. When reading from storage these objects will read the
IDs and register themselves to get an update when all stored objects have been
read. At that time they will request the input stream to get the pointer corresponding
to the ID.

ComspecVersion

Keeps track of the major and minor version number, and can display the version
number in a way suitable for displaying to the user.
Note: Although the class name is ComspecVersion, it does not return the version of
Comspec!

The interfaces defining the storage are in ComspecOutputStream,
ComspecInputStream and ComspecComponentLink. Default implementations
of these are in ComspecOutputStreamSupport,
ComspecInputStreamSupport and ComspecComponentLinkSupport, all in the
comspec.system package.
Project: Comspec, TP 1169
Comspec on Java
Page 24
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

3.5 Application State
The Application State determines the
state a Comspec Application is in. Its
main intended use is to determine if the
Application is in "Editing" or "Running"
state, but a few extra states are defined
to handle transitions between editing and
running (the "Starting" and "Stopping"
states), and to determine Application
boot state ("Loading") and Application
exit ("Stopped").

Note that state changes can only occur
as the arrows indicate.

Keeping track of the ApplicationState is
defined as a service, which can be
accessed via the ComspecContext. The
comspec.system.ApplicationStat
e defines the interface for the
ApplicationState service.
The default implementation of this
service is in comspec.system.ApplicationStateSupport class.
3.6 User level
In Comspec four user roles are defined (three of these correspond to three different
User Levels in the Comspec architecture):
· Developer - a programmer who creates and modifies components
· Integrator - a technically trained person who creates Applications from
components and sets their overall properties
· Facilitator - a teacher, parent or helper of the End-user doing day-to-day
maintenance
· End-user - the user of a Comspec Application

These user roles are important for the system as they are reflected in three different
User Levels: End-User, Facilitator and Integrator. The purpose is for the software to
hide complexity as much as possible. The facilitator should, for instance, not be able
to modify the Configuration of an application. For more details, see the Comspec
Functional Specification [Odo95].

A component should 'display' only the properties accessible to the user with a given
user level. This should be done through a special ComspecBeanInfo class: see
Chapter 4.

In the next table you will find a list of actions available for each user level.

Activity Integrator

Facilitator End-User
Change user level + + -
Create or Edit configuration + - -
Modify parameters (scan speed, volume
level, etc.)
+ + *1 - *2
Modify layout (screen and appearance,
sound etc.)
+ + *3 -
Loadi ng
Starti ng
Running
Stoppi ng
Stopped
Editing

Figure 3: ApplicationState allowed states and
state changes
Project: Comspec, TP 1169
Comspec on Java
Page 25
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

Create layout + - -
Edit scanning relations in layout + - -
Edit vocabulary item in layout components

+ + -
Create Vocabulary + - -
Create Vocabulary groups + - -
Create Vocabulary representation types + - -
Add / remove / edit Groups, Items and
Representations in the Vocabulary
+ + -
Add / remove / edit representation types in
a Vocabulary
+ - -
Create / Edit Toolbar + - -

Notes:
1. The Facilitator access to parameters is through a specially designed toolbar. This
toolbar is created by the integrator and provides a centralised and easy way to
change selected parameters of the application. Some other parameters may be
accessible directly in the application, not through a Toolbar.
2. The End-user is not expected to change many parameters in an Application. The
End-user can only have access to parameters through a Toolbar, or by selecting
elements in the Layout which can e.g. toggle values, or increment values with a
fixed step.
3. The Facilitator access layout options can be done through the same mechanism
as the integrator accesses them (directly in the Layout, or through a property
sheet), but the preferred way is access via the Toolbar.
4. This table is not complete: it is intended to clarify the various user levels.
5. Developers create components. If they want to test their components, they will
take the role of one of the other user levels. They have full control over all
properties, even those properties not relevant for the users of the Comspec
system.
6. Integrators can do everything in the application: edit Applications, Application
Subsystems, layouts, configurations and vocabularies, and create toolbars for
facilitators or end-users. These toolbars provide easy and safe access for
untrained people. Integrators have full access to all properties relevant for
Comspec (note: Java Beans can have other properties not relevant to the users of
Comspec)
7. Facilitators only have limited access to the editing capabilities, to protect them
from inadvertently making an application unusable for the end-user.
8. End-users cannot change anything in the application, they are only using the
application. The only exceptions are when the layout contains special adjuster
controls, and if a toolbar is defined for them, in which case they can change
certain pre-defined properties, e.g. scan speed, volume level. To access the
toolbar, they currently must be able to use a mouse or other pointing device, as
the toolbar is not accessible for e.g. switch intput.

The comspec.system.UserLevel interface defines the UserLevel service which
can be accessed in the ComspecContext. It also defines the constants which can be
used to determine the user level. A default implementation for this service can be
found in comspec.system.UserLevelSupport.
Notes:
1. If the UserLevel service is not available, the software must assume it is at End-
User Level.
2. The UserLevel is intended to be used by the different Editors. Developers usually
need to implement UserLevel awareness only in their BeanInfo classes or the
component's Customizer.
Project: Comspec, TP 1169
Comspec on Java
Page 26
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98


3.7 Finding and Instantiating installable classes
Most components in the Comspec System will need some kind of service from its
environment. The ComspecContext system provides access to these services, by
returning a reference to an already loaded instance of a class. Things get a bit more
complex if a component needs to instantiate an installable class  that is what this
section is about.

The implementation of most of these services can be replaced by implementations
from third-party developers: the ClassRegistry offers support for this. An extra
service is added to the Editing Environment and the Run-time Environment to allow
components to find the class implementing a certain service, or even instantiate that
class.

This service will browse the ClassRegistry for the installed services, and return either
the string containing the class path, the class itself, or an instance of the class.

public interface ClassFinder {
public String implementationName(Class interface)
throws ClassNotFoundException;
public Class implementationClass(Class interface)
throws ClassNotFoundException;
public Object implementationObject(Class interface)
throws ClassNotFoundException;
}

For instance, components can use this service to create the proper
ComspecComponentLink objects:

ComspecComponentLink outputLink;
...
ClassFinder finder;
finder = (ClassFinder) ctxt.getService(ClassFinder.class, this);
...
outputLink = (ComspecComponentLink)
finder.implementationObject(ComspecComponentLink.class);


The interface for the ClassFinder can be found in comspec.system.ClassFinder
interface, the default implementation is in
comspec.environment.ClassFinderSupport.

Project: Comspec, TP 1169
Comspec on Java
Page 27
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

4. Creating components
This chapter is meant for component developers to learn what requirements are set
on their components to integrate in the Comspec System. Access to services are
explained, and a few lines of example code are present to clarify some
implementation issues.
4.1 General
Components in Comspec have the following requirements:
· be a JavaBean
· be a ComspecContextChild, and behave properly (see Object Registry)
· be registered in the Class Registry
· have a BeanInfo class based on the ComspecBeanInfo
In addition to these requirements the component should implement the protocols
associated with its role in the system. If a Comspec Component fulfils these
requirements, the editors will be able to use it and other components will be able to
link to it.
4.2 Naming conventions
Each Comspec Component should have a unique name which is its ID. This ID
should start with an alphabetical character, and contain only A..Z, a..z, 0..9, and _
(underscore). Names are not case-sensitive in the ObjectRegistry. In Java, there is
no restriction in length for the names. However, it is good practice to use short but
descriptive names, and to use capitals only to mark the beginning of words in a
name. The property editor for the ID property should notify the user about illegally
formed IDs.
Comspec Components are responsible for registering their ID's with the
ObjectRegistry, which they may access through their ComspecContext. To ensure
the uniqueness of its ID, the component must negotiate an ID with the
ObjectRegistry each time the ID is changed or the ComspecContext is set. See
paragraphs 3.3.3 and 3.3.4 for more information on the co-operation between a
Comspec Component and the ObjectRegistry.

The links between components are to be stored as ComspecComponentLink
objects, not as IDs. The Storage mechanism ensures correct re-creation of these
links when the classes are read from file or clipboard.
4.3 ComspecContext
The ComspecContext allows components to access external services: see the next
section. The ComspecContextChild interface is a simple interface to implement.
There are two things to pay attention to when implementing this interface:
· the reference to the ComspecContext should be defined as transient (the
ComspecContext must not be stored to the file) and initialised to null.
· When the ComspecContext of a component is set, the component must check
whether its ID is unique within this ComspecContext, even if the ComspecContext
did not change. To do this, the component must re-register in the ClassRegistry
service from the ComspecContext. See the description of the ClassRegistry
service.
Project: Comspec, TP 1169
Comspec on Java
Page 28
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

4.4 Accessing services
The Comspec components can access services by calling the getService function of
their ComspecContext. E.g. to find the vocabulary, the following code can be used:

VocabularyRetrieval vocab;
vocab = (VocabularyRetrieval)
ctxt.getService(VocabularyRetrieval.class, this);

In this example, the VocabularyRetrieval parameter in the getService() method is the
Comspec protocol which the Vocabulary has to implement, and can be used to find
the correct service through it's ComspecContext ctxt.
4.5 Storage
During serialization storage, the components can be completely passive. During
storage in the Comspec Storage system, the methods in the
comspec.storage.StorableComponent interface are called. These must
usually be implemented for every Component.

For Comspec components, only a few rules are required for correct storage:
· All components to be stored should implement the
comspec.system.ComspecComponent interface (and thereby the
java.io.Serializable interface and the
comspec.storage.StorableComponent interface)
· A component containing other components should store its contained
components during storage (do not mark data fields for the contents as
transient)
· All other cross-component references should be kept in a
ComspecComponentLink, instead of direct links. The storage mechanism will
store the links during serialization and restore them during de-serialization. The
ComspecComponentLink is a wrapper around a reference to a
ComspecComponent, and participates in the Storage process.
· For Comspec Storage: three methods need to be implemented, except when the
class is derived from a StorableComponent AND the class does not define any
property data itself (only the properties defined in the class itself need to be
written to and read from the stream). References to other StorableComponents
should be written as references. The ComspecComponentLinkSupport class does
this, and all that needs to be done is calling single methods in this class to ensure
proper writing and reading of links.
The comspec.storage.StorageSupport class supports reading and writing of
various object types, e.g. java.awt.Container, java.awt.Color etc.
4.6 Application state changes
If a component needs to know about the current Application State, it can access the
ApplicationState service:

ApplicationState appState = (ApplicationState)
ctxt.getService(ApplicationState.class, this);

The component can check the ApplicationState property, or register itself as a
ApplicationState change listener. See section 3.5 for more information about the
ApplicationState service and the allowed states and state changes.
Project: Comspec, TP 1169
Comspec on Java
Page 29
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

4.7 User level distinctions
When designing and implementing new Comspec components the different user
levels of Comspec should be considered, as described in section 3.6. To filter
properties according to the user level, a ComspecBeanInfo class should be made for
it. This class is a normal BeanInfo class, but reports only the properties visible for the
user level. The Editors will request the BeanInfo for each component, and report the
user level for the BeanInfo.
See the comspec.system.ComspecBeanInfo interface for information on how to
create a ComspecBeanInfo.

The current userlevel can be found by requesting it as a service from the context of
the component. E.g.:

int level = UserLevel.END_USER; // default value
UserLevel usrLevel = (UserLevel)
ctxt.getService(UserLevel.class, this);
if (usrLevel != null)
level = usrLevel.getUserLevel();

Note: if the UserLevel service is not available, the software must assume it is at End-
User Level.
4.8 Support classes
When implementing new Comspec components, developers can base much of the
implementation on pre-made support classes. These support classes can be found
in the comspec.component and comspec.support package. Classes available
here include ConfigComponentSupport and LayoutComponentSupport which
implement default behaviour including most of the required protocols for
configuration and layout components.
The comspec.system.ComspecComponentLinkSupport class implements the
necessary behaviour for keeping track of cross-component connections, as
described in section on the ComspecComponentLink interface.

Further information can be found in the JavaDoc generated documentation for the
comspec.component package.

4.9 Implementing Vocabulary Access
Besides the pure protocol based access to the Vocabulary, acutally using data from
the Vocabulary usually involves the implementation of other interfaces.
RepresentationData returned from the Vocabulary needs to be represented in one
way or another. Components can query the Vocabulary for viewers to represent the
data for the components. These viewers take the raw representation data from the
Vocabulary, process this data, and represent it on screen (in case of a Drawable
reprensentation) or play the data (in case of a Playable representation). Components
can become a 'representation site' to allow the viewers to represent the data in a
consistent way.
A component can implement the DrawableRepresentationSite and / or the
PlayableRepresentationSite in the comspec.vocabulary.viewer package
Project: Comspec, TP 1169
Comspec on Java
Page 30
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

4.10 Interaction with the Editing Environment
4.10.1 Editing Properties
If a component is selected inside one of the subsystem editors, the Editor will pass
the component object to the PropertySheet (Note: the Vocabulary Editor handles
property editing of its own components in another way) The PropertySheet will try to
get the components' BeanInfo. If the component declares to have a Customizer, this
Customizer will be displayed in the PropertySheet, otherwise the PropertySheet will
show a list of editable properties of the component.
The default style for customizers is a tabbed pane (TabsetCustomizer) with one
panel for each tab (see the comspec.support.panel package)

Implementing a Customizer based on these classes involves the creation of the
following classes:
· xxxBeanInfo - to tell the system which customizer to use
· xxxCustomizer - a subclass of TabsetCustomizer, creating a few standard pages
(tabs) using standard panels from the comspec.support.panel package, and
a few component-specific pages.
· Panels (subclasses of e.g. java.awt.Container) for each specific page in the
Tabset.

· If no customizer is to be created, it is strongly recommended to create a BeanInfo
for each component. If based on the
comspec.component.ComspecBeanInfoSupport class, implementing this is
very easy. All you have to do is define the properties visible for the integrator or
facilitator using the one of the various property() methods. There are versions
of this method to define properties with custom editors, visibility for certain user
levels etc.

package ....

import java.beans.*;

public class FabulousComponentBeanInfo
extends comspec.component.ComspecBeanInfoSupport {

public PropertyDescriptor[] getPropertyDescriptors() {
try {
return new PropertyDescriptor[] {
// ID property, only visible for integrators
property(
"ID",
"Component ID",
FabulousComponent.class,
comspec.system.UserLevel.INTEGRATOR),
// my fabulous property, visible for everyone
property(
"fabulousProp",
"Some Fabulous Property",
FabulousComponent.class,
FabulousPropertyEditor.class)
};
} catch (IntrospectionException e) {
return super.getPropertyDescriptors();
}
}
}

Project: Comspec, TP 1169
Comspec on Java
Page 31
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

4.10.2 Icons
Each component should have one or more icons. If you write your own BeanInfo, you
should find, load and create a java.awt.Image in the getIcon() method. If you base
your BeanInfo on comspec.component.ComspecBeanInfoSupport, all you have to do
is to create the icon images in GIF format, and to name them according the following
convention:

name :== <ComponentName> + "_" + [size][color spec] + ".gif"
size :== "16x16" | "32x32"
color spec :== "c" | ""

So, if your component is called Fabulous, the ComspecBeanInfoSupport class will
look for the following files if getIcon() is called:
FileName icon type
Fabulous_16x16.gif 16 by 16 pixels, monchrome
Fabulous_16x16c.gif 16 by 16 pixels, color
Fabulous_32x32.gif 32 by 32 pixels, monchrome
Fabulous_32x32c.gif 32 by 32 pixels, color

Color icons should mark their background as transparent, monochrome icons should
be black + transparent.

Place these image files in the \images directory in your jar, or in the same directory
as your component class.

4.10.3 Interaction with the Editing system
The most important issue for components to be checked is that the component acts
like and looks like a JavaBean. Although many advanced features of the JavaBean
architecture are not used, the most important issues that are used (and should be
implemented) are:
· definitions of properties (getter and setter method signatures)
· proper generation PropertyChange events
· definition of a BeanInfo (not required but strongly recommended)

4.11 Creating Layout components with special editor s
4.11.1 Introduction
For most layout components the developer do not need to do anything special to
enable the components to be editable in the layout editors. This section describes
more advanced features that probably only will be used by components that will be
containers of other layout components.

Each layout component will during editing have an editor associated with it. This
editor will e.g. react to mouse move and button activity within the component. Most
layout components do not require any special handling of these events, and thus
their editor pass the events on to the currently active editor, or to the their container's
editor if the active editor do not consume the event. This handling is implemented by
a default editor that will be associated with the component if no component specific
editor is specified.

Project: Comspec, TP 1169
Comspec on Java
Page 32
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

The comspec.layout.support package contains the basic interfaces and
classes of the layout editing system. The most basic interface is the
LayoutComponentEditor interface that must be implemented of all editors for
layout components. The class LayoutComponentEditorSupport implements the
default behaviour, and this is used directly by the system as the default editor. It can
also be extended to create specialised editors.

Some layout components may during edit time want to e.g. maintain a selection or
provide special tools for editing. The layout system uses an activation manager to
ensure that there is exactly on component editor that is "active" at any time. The
editor for the Card Stack will e.g. enable selection of components within it when it is
active, and adjust the available menu actions according to the current selection. The
ActivateableEditor interface is an extension of the LayoutComponentEditor
interface that should be implemented if the editor will be activateable. Container
components should implement the ContainerEditor interface that is an extension
of the ActivateableEditor interface.

4.11.2 Available services in the layout editing system
The layout editing system provides access to some services that is useful and/or
necessary for editors that can be activated, and especially for container editors.
These services are accessed using the normal getService() function of the
ComspecContext.

Available services:
· ActivationManager. This object manages the activation of editors in the
layout, and should e.g. be requested to activate an editor from the editors
activate method.
· EditorManager. This object is responsible for finding and creating appropriate
editors for components. Should be used by container components when they
insert new components to find/create an editor for the new component.
· ConnectionDrawer. This object is responsible for drawing the scan
connections between components. This object can be used by container editors
to display the scan connections.
· CommandManager. This object is used to manage commands in the system,
including undo and redo. Should be used by editors that perform commands.
· LayoutMenuManager. This object manages the menus specific for the layout.
Activateable editors should use this object to enable/disable menu items as
appropriate.
· Grid. This object contains the current grid settings used in the layout, and can
adjust positions and sizes to the current grid. Used e.g. in container editors that
support a grid.
· Clipboard. This object is the shared clipboard of the layout editing system.
Should be used by layout component editors that can transfer content from or to
the clipboard.

4.11.3 Associating an editor with a layout component
There is basically two ways to specify the editor for a layout component.

Class registry. The editor can be explicitly specified in the Comspec class registry,
by specifying the full class name in a property called "Editor".

Project: Comspec, TP 1169
Comspec on Java
Page 33
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

Naming convention. If no explicit entry is found in the class registry, the system will
use naming conventions to try to locate the editor class. First it will try to locate a
class by adding "Editor" to the name of the layout component class. If this is not
found, it will add ".editor" to the package name, and add "Editor" to the class
name. If this also fails, the default editor class will be used.

4.12 Creating new Vocabulary Representation Types
4.12.1 Introduction
The Vocabulary system allows new data types to be used in a Vocabulary. Up to
three different handler classes can be created for each data type. To install a new
data type, an entry should be made in the ClassRegistry database, defining
· the data type (like image/x-my-own-fabulous-graphical-language-image)
· the viewer class (like com.company.fabulous.Viewer)
· the editor class (optional)
· the selector class (optional, needed if data is not stored in separate files)

Note, all interfaces and classes in this paragraph are located in the
comspec.vocabulary.viewer package, unless otherwise specified.

4.12.2 Representation Viewer
This must be a class capable of "viewing" the data for other components. Viewers
can be Drawable, Playable, or both. The Viewer Class must at least implement the
DrawableRepresentationViewer or the PlayableRepresentationViewer
interface. When needed, the Vocabulary system will instantiate the class and set the
data to it. This data can be of the following class types:
· byte[] a 1-to-1 image of the data as stored in the file
· a java.io.File a reference to a file where the data is stored
· a java.io.URL a reference to a file where the data is stored
· a java.io.InputStream an opened stream where the data can be read from
· other - some type specific data object
The Viewer class should try to extract the data from any of these.

Viewers can have a certain context to represent the data in: a RepresentationSite
(see RepresentationSite, DrawableRepresentationSite,
PlayableRepresentationSite comspec. This site specifies the appearance of
the representation, a DrawableRepresentationSite can for instance specify the font
and the colors to use.
The viewer should query and use information provided by this site.

4.12.3 Representation Editor
Representation Editors enable the users to actually edit the data. The editor is
embedded inside a dialog, and should have a user interface based on
java.awt.Component. Editors could, for instance, allow the user to edit a graphics,
texts etc.

A Representation Editor must implement the
comspec.vocabulary.editor.RepresentationEditor interface. This
interface defines how the representation data is set to / got from the editor, and
indicates the editor when to start and stop editing.
Project: Comspec, TP 1169
Comspec on Java
Page 34
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98


If a certain representation type has no editor defined in the ClassRegistry, the
selector will be used in stead. Currently, only a PlainTextEditor for the text/plain data
type is implemented.

4.12.4 Representation Selector
Being technically the same as Representation Editors, Representation selectors are
intended to allow users to select data for a certain representation from a database.

This type of class is intended to be implemented to for third party vocabulary
databases. The user selects e.g. symbolic information from an image collection
where the images are stored in some propriety or compressed database.

One selector is currently implemented, which selects data from the "harddisk"
database: the FileSelector. It allows the user to select data from the harddisk.

If a certain representation type has no selector defined in the ClassRegistry, the
default selector (the FileSelector) will be used in stead.
Project: Comspec, TP 1169
Comspec on Java
Page 35
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

5. Overview of packages
This chapter provides a quick reference to elements in the Comspec System. The
following table describes the most important packages:

Package Contents
comspec.protocol Comspec Protocol definition interfaces and support classes
comspec.system system related services, helper classes and definition
interfaces
comspec.support general helper classes like a sorter class, panels for
customizers, edit commands etc.
comspec.storage the Comspec Storage system
comspec.application Application class and helper classes
comspec.application.editor ApplicationEditor class and helper classes
comspec.environment the Comspec Editing and Runtime Environment and helper
classes (ComponentPalette, ButtonBar etc.)
comspec.environment
.propertysheet
The PropertySheet system
comspec.component interfaces and support classes for any
Comspec component
comspec.component.<name> classes needed for each component <name>.
comspec.configuration Configuration application subsystem class and helper
classes
comspec.configuration.editor Configuration Editor class and helper classes
comspec.layout Layout application subsystem class and helper classes
comspec.layout.editor Layout Editor class and helper classes
comspec.vocabulary Vocabulary application subsystem class and helper classes
comspec.vocabulary.editor Vocabulary Editor class and helper classes
comspec.vocabulary.viewer Vocabulary representation viewers
comspec.toolbar Toolbar application subsystem class and helper classes
comspec.toolbar.editor Toolbar Editor class and helper classes
Notes:
1. A package is the Java way of organizing software classes. There is no direct
relationship between packages and the files in which a number of classes can be
grouped for easy transport.
2. The Java package system allows different classes to share the same name. For
example, a helper class 'Timer' might provide timing tasks for one component. If
another component also needs timing tasks, then another class also called Timer
can be created. By placing related classes in one package, class naming conflicts
are reduced. It is still possible to use classes from another package, but then the
programmer has to include the package name.
For each component, there will be a package. Most components will consist of
multiple classes (at least the component class and the BeanInfo class). If, for
instance, all components and their helper classes were placed into one package, this
package could easily contain hundreds of classes. For this reason it will become
unwieldy to have many components in a single package. A practical limit would be
around 50 classes in one package, with an optimum of maybe 20 classes per
package. For the development of Comspec, we have decided to create a separate
package for each component, with the result that the number of classes (estimated
at 2 to 5 per component) will usually be much lower than the practical optimum of
around 20.
Project: Comspec, TP 1169
Comspec on Java
Page 36
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

Appendix A - Glossary
Application
This term is used for two items:
1. The data to interlink and present a group of components which will appear to
the user (by using the Runner) as an independent program
2. The class (software) handling this data
The application as data is what the users of Comspec will see: it is a file. This file
contains, besides the data for the Application class, all the data for the Application
Subsystems, and also the property data for all the layout, vocabulary,
configuration, and toolbar components.
The application as an instantiated class is what the software components in the
Comspec System may deal with. This class will delegate the handling of most of
the data in the Application file to the Application Subsystems, thus de-serializing
the hierarchical structure of the data. See: Serialized format.
ApplicationState
The mode of the application (loading, running, editing, starting, stopping,
stopped).
Application Subsystem
The classes (e.g. Configuration, Layout) which form the basis of an Application.
Each has its own editor. An Application Subsystem is a top level component in an
Application; in Comspec, the Application only contains Application Subsystems.
Application Subsystems only contain non-top level components.
Class
Definition of an object (data and software code). A class needs to be instantiated
to become active. Instances of a class are called objects. There can be many
instances of the same class (e.g. a dialogue box may have several buttons, each
one an instance of the same Button class).
ClassRegistry
The registry listing the installed components for Comspec. Elements in this
registry can be activated and added to a Comspec Application.
Component
The Java-class created by a developer which will be a building block for future
Applications.
Component Installer, Installer
The Comspec Component Installer. The software utility which will assist installing
new components and applications. (Beyond the scope of this project.)
ComspecContext
An 'environment' for components in which components can learn about their
environment and access the services in the environment.
The ComspecContext is a sub-set of the BeanContext API, as proposed by SUN.
Because the BeanContext API was not stable at the time this document was
written, we created a sub-set of the BeanContext API. The ComspecContext is
the service provider, the ComspecContextChild is the client for services. See
[Cab97].
Project: Comspec, TP 1169
Comspec on Java
Page 37
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

ComspecContextChild
A leaf in the ComspecContext hierarchy. Equivalent to the BeanContextChild. See
ComspecContext.
Developer
A software developer who creates components (Java Classes).
Editing Environment
The software platform from which the User can create/modify/test applications.
Both the Editing Environment and the Run-time Environment will be part of the
basic Comspec System, obtainable from the Comspec Web site.
Software which enables the user to change the contents or properties of an item.
These items might be text (the editor is then a word processor), a drawing (the
editor is a drawing program), or a Comspec Application (the editor is the
Application Editor).
In Comspec, the term Editor is sometimes used to define the Comspec Editing
Environment, which most users will see as the 'editor' as opposed to the 'runner'
See also: Editing Environment, Run-time Environment
End-User
The (possibly disabled) individual for which the application is intended.
A (non-technical) person who modifies existing applications based on the needs
of an individual end-user
HTML
A page description language used on the World Wide Web of the Internet. This
has become a standard file format for text with rich content. Viewers for HTML are
available from different vendors for different platforms.
Installed
Components which are available on disk and registered in relevant registries.
Integrator
A technically trained person who creates an application from components, or who
makes major changes to an existing application.
Interface
An interface is a collection of method names, without definitions, that can be
implemented by classes. Independent of the ancestry of classes, if different
classes implement the same interface, they can be accessed in the same way as
if they had a common super class.
Java
Java is three things in one: An object-orientated programming language
(resembling C++), a programming library, and a definition of a computer system.
Because Java also defines the computer system (the Java Virtual Machine), Java
programs will run on any computer supporting the Java Virtual Machine. Java is
developed by Sun Microsystems (see their Web site at http://www.sun.com/).
More information about Java can be found at http://www.javasoft.com/
JavaDoc
A documentation generator tool supplied with the Java development kit from Sun
(JDK). By inserting a certain style of comments in the source code, programmers
Project: Comspec, TP 1169
Comspec on Java
Page 38
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

can now use this tool to create documentation from their software. The
documentation generated is in HTML format and can be read by any popular Web
browser.
Name space
A 'space' or environment in which each name must be unique. The Comspec
Application will have one name space for every component in it (application
subsystems, components in the sub systems). One exception to this rule is the
Vocabulary which will have its own name space for the Vocabulary Items and
Representations.
Object
Instantiated class. See Class
ObjectRegistry
Registry listing the active (instantiated) objects in a 'name space'
Package
A package is the Java way of organizing software classes. This mechanism
allows for a structured way of organizing classes and interfaces, much like a
directory structure for organising files on a disk. There is no direct relationship
between packages and the files in which a number of classes can be grouped for
easy transport.
Run-time Environment
The software platform from which the End-User can run its Applications
Runner
This is another word for the Run-timeEnvironment. The user (integrator or
facilitator) of Comspec will see two Java Applications: the 'Editor' to edit Comspec
Applications, the 'Runner' to run them. Both the Editing Environment and the Run-
time Environment will be part of the basic Comspec System, obtainable from the
Comspec web site.
See also: Run-time Environment, Editing Environment.
Selected
User focused on specific object
Serialized format
The data in an application is often not organized sequentially, but rather in a
hierarchical way. To store this data in a file, send it through a network connection,
or even use the simple copy / paste via the clipboard, this hierarchical data needs
to be 'serialized', that is, all the information must be presented as a sequence of
bytes. The Java Serialization support does just this: it reads all the information
stored in any structure of classes and writes it into a stream of bytes. When
reading the stream back, the original structure is restored. This process is called
de-serialization.
Storage unit
A 'closed' box inside the Comspec Storage system in which a component writes
all its property data.
Project: Comspec, TP 1169
Comspec on Java
Page 39
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

Template
An Application or a part of an Application which can be used to create a new
Application. An Application can be a template, much like a standard letter in a
word processor can be a template: small modifications are needed to create a
new letter. Application Subsystems can be saved as separate files, they can then
be embedded in another application.
User
A Developer, Integrator, Facilitator or End-User
UserLevel
The user of the Comspec system, (Integrator, Facilitator or End-User). There is
another User Role, the Developer, but he will not use the Comspec software as a
developer. See User Role.
User Role
The role a user can assume. This is similiar to the UserLevel, but of the four User
Roles, only three correspond with a UserLevel. The Developer will never use the
Comspec software as a user, he will create Comspec Components with another
development tool. The Developer will test his own Comspec Components at the
other three user levels, but then he assumes another User Role.
See: User, UserLevel



Project: Comspec, TP 1169
Comspec on Java
Page 40
/ 40

Version 2.0 © Comspec 1998 Issued 29/05/98

Appendix B - Programmers Reference in JavaDoc

At the same time this document (Comspec on Java) was released, a full
Programmers Reference was created using JavaDoc.

JavaDoc is a tool to generate HTML files from Java source-code files. These files
contain detailed information about components, their methods and properties.
The files can be browsed by any popular web browser. Apart form the plain
information, every word or sentence that is underlined is a "hypertext" link, giving
direct access to other related information.

To locate the position of certain information in these files, one of the entries at the
top of these pages can be used, i.e.:
· Alphabetical index
· Class hierarchy
· Package index

The examples provided, are:
1. Index to all keywords. This index provides a quick access to the documentation of
any element in Comspec.
2. Overview of class hierarchy. This documentation shows the relation between
super and sub classes.
3. Package index shows all the class packages in Comspec. This index allows
browsing through the documentation much like browsing a directory tree.
4. For each class or interface, detailed information is provided on every method and
field. Note that from this lowest, most detailed level, the reader can return to each
of the four 'indexes' (All Packages, Class hierarchy, This Package, Index), or
continue browsing to the next and previous class in the same package.

The interested reader is kindly referred to the current and most complete
documentation on the Comspec web site:

http://www.oslo.sintef.no/comspec/java/packages.html

( above link N/A 2006  see
http://www.handicom.nl/english/Comspec/
)