Group Notebook - page 11 of 42

Mon May 5 17:26:47 1997 (GMT)

Editor API Document




Specification of the DOE2000 Notebook Basic Editor API


Prepared By: Jim Myers, Newton Brown


Date: 4-29-97


Purpose: Notebook editors are classes that allow input of new media/data types into the notebook. The purpose of separating the editors from the notebook client is to allow domain experts to be able to build new editors without requiring access to or knowledge of the notebook client or engine.


General Requirements:



For the user, all editors should be equal, e.g. external tools should not be invoked differently than those developed by the project. The user needs to:

1) Select the media/data type to input,

2) Launch a tool to create/import/edit it, and

3) Submit the new data to the notebook system


It would be helpful for the user if new editors could be added to the system dynamically and even semi-automatically (new editors are discovered by the notebook and the user is queried). A common look-and-feel for editors would help the user, but certain data types may require very odd looking editors. There are many other things that might be nice Ė if editors could be brought up in user defined positions, could come up embedded in the client window or as separate windows, etc.




At the most basic level, there are a relatively few steps required to enter information into the notebook. Whatever the media/data type, once it is packaged as a notebook Object (NOb), the processing is identical. The developer should not have to deal with any processing after packaging the data and should not care if that processing changes after the editor is built and installed. The developer should be able to receive credit/acknowledgement for his/her contribution and should provide help (possibly evolving) for their editor.




Since the notebook clients will use Java, a Java interface to editors makes sense. (A CORBA interface may also be desirable at some point. At first, access to CORBA, editors written in other languages, and "legacy editors", could be handled through wrapping them in a Java interface. )


Editor selection: A fairly general mechanism for allowing selection of an editor is to display a text string and/or picture to the user. This could be through a menu, button bar, or other means. If the editor provides the text and picture, the notebook client can display all editors the same way, and different notebook clients could use different means to display editors.


Editor launch: Similarly, the editor will have to be invoked, either with no starting data, or to edit existing data. The mechanism for this could be drag and drop, menu selection, button click, etc. Since we again want this to be uniform for all editors, the mechanism should be in the notebook client.


Editor submit: The editor may take an arbitrary amount of time to gather the user input, after which it can create a NOb, and pass it to the notebook client for processing. Having all editors create NObs greatly simplifies the client, which only deals with one input type. There are three ways the client could become aware of when the editor has produced a NOb:

  1. Make the launch call synchronous and donít return from the method call until a NOb is available. Since the client could spawn a thread for each editor launch, this method could work. It does mean that only one Nob could be returned per editor launch.
  2. Have the client poll the editor. This is ugly.
  3. Have the editor call a callback on the client. This is the most flexible, but has some consequences:


The one-to-one correspondence of editor launch and object return is broken. If the user selects "text, image, sketch" from the client, they may still enter "image, text, sketch, text" into the notebook, e.g. the order of editor selection doesnít matter.


The editor object has to know the name of a method in the client to call it. The other choices (and I think all the other features listed) only require the client to know editor methods, not vice versa.

Overall, # 3 seems to be the best choice.


Editor acknowledgement: There should be a mechanism for the user to learn about the developer of the editor. While the editor could implement its own "about" button, it might be useful to let the client have access to the information as well. The information available could be text, a dialog box, or a URL. What should we support?


Editor help: There should be a mechanism for the user to learn about the usage of the editor. While the editor could implement its own "help" button, it might be useful to let the client have access to the information as well. The information available could be text, a dialog box, or a URL. What should we support?


JavaBeans??? JavaBeans have some similarity to what we want to do with editors. However, they are much more targeted to GUI builder clients (ala Visual Basic with Visual Basic controls) and have many features that arenít needed here. We might want to take advantage of their definition of a get icon function and the four types of icons they pick as standards (16x16 and 32x32 in color and B/W). They also define a help function that returns HTML. Perhaps we should adopt this as well. (the spec allows you, e.g. the notebook client, to display the HTML, pass it off to a browser, whatever.)



So, a proposal for version 1.0 of the editor API:


Public interface NBClient {

Save (NOb[]); //Should this be AddNob(NOb[]);?



public interface NBEditor {


String getLabel();

Image getIcon(int iconKind);

Launch(NOb, NBClient);

String About();

String Help();



Editor interface needs to have the following methods:

Return Type







Returns the name of the Editor

Length (suggest <=40 characters)



getIcon(int iconKind)

Returns an image (icon) that represents the Editor. Null is valid if icon of specified type does not exist.

16x16,32x32 pixels with 8 bit color in GIF format, or B/W

IconKind specifies which of the four icon types is requested


Launch(NOb, NBClient )

Launches the Editor which will enable the modification or creation of an object of type Notebook Object - NOb

NBClient is a reference to the Nbclient invoking the editor

NOb, NBClient



Returns HTML for the about information for the Editor.




Returns a HTML for the help information for the Editor




NBClient interface


Return Type







Returns a Notebook Object - NOb



A master Java application will coordinate the input of a wide array of data types. Within the master application a toolbar containing icons representing all the different data inputting applications called "Editors". These Editors will be created and maintained by a wide array of Scientists and organizations. All the Editors will have a few common functions that will enable them to be launched and used in a similar manner. The editor will launch, save one or more NObs (in one call or sequentially), and eventually quit. The proposed functions are listed in the table above. The master and toolbar applications can also vary by organization.


Outstanding Issues:

    1. Java version restrictions? Is 1.1 necessary?
    2. Local Vs network location of Editor classes. Can we dynamically download new editors from the notebook server site?
    3. Launch() parameters.
    1. Base NBClient definition. Are there other functions we want to add to the required list for use by editors? (Obviously the notebook clients have more functions, but editors may not care. For DOE2000, we may want to define more common functions on the client, specifically for how it interacts with the engine, but that is outside this scope. By putting the Save function in a separate interface, we can define it now and figure out the rest later.

Jim Myers