The Editor

 

The editor is one of the two tools included in CDE. The purpose of the editor is to register components, write contracts and compile them, and finally to generate the Java code that adapts components for coordination and that implements the contracts. The editor window is divided into 5 areas: the menu bar, the toolbar, and three panes. One can change the size of the panes by dragging the bars between them. We start by describing the panes, then the menu bar, and finally the toolbar.

The Project Pane

The left pane of the editor window is the project pane. It represents in a hierarchical fashion all artifacts (components, contracts, generated files) included in the project. Multiple projects may be open simultaneously during a working session with the CDE editor. However, the project pane only shows the tree of the current project. To switch to another project, use the pull-down menu at the top of the pane. To expand a node in the tree, click on the handle before the node name, or double-click on the node name. To collapse a sub-tree, click on the handle of the root node of the sub-tree. Clicking once on the node name makes it the current node. The current node always has a blue background. A node may have some operations associated to it. Right-click on the node name to make a pop-up menu appear with those operations. Most operations can also be invoked using the CDE pull-down menus. In those cases, the description of a command is given in the section about the respective menu. To indicate a command in a given menu we simply write Menu->Item. The main nodes that may appear in the tree, i.e., those for which there is a pop-up menu, are described next. 

Project node

This is the root node of the tree. The commands available in the pop-up menu are:

Project Options...
The same as Project->Project Options...
Add
The same as File->Add
Generate
The same as Project->Generate
Java Compile
This command compiles all generated files. It goes through all the children of all "Generated files" nodes in the tree and, for each one, invokes the Java Compile command.
Close Project
The same as File->Close Project
Save Project
The same as File->Save Project

Component node

There is one component node for each Java class that may be subject to coordination. Each node has at most 4 children: one node for the class attributes, one for the class methods, one for the class source file, and one for the files that CDE generated in order to make the original Java class work with coordination contracts. The pop-up menu associated to component nodes is:

Edit Textual
This opens a new tabbed edit window with the component source code in the edition pane (if it doesn't exist), and makes it the current window.
Reload
This command reloads the component source code into the project. CDE generates the files from the information stored in the project; hence, this commands allows to update the project repository with respect to any changes done to the source file. A message appears in the message pane stating the exact path of the source file that was reloaded. The tree is updated correspondingly. Notice that the generated files node disappears, because the files have to be regenerated for the updated component.
Generate
The same command as in the Project menu.
Java Compile
Compiles all files generated for this component, i.e., under the "Generated Files" node.
Update Source...
This command allows to copy the file stored in the components directory to the original place. A confirmation dialog appears before this operation is carried out.
Coordinated Operations...
This command opens a dialog with the list of all the component's public methods, with a check box for each one. The buttons at the bottom of the dialog allow to quickly set or unset all marks. After choosing which methods may in the future be subject to coordination, the dialog can be closed by pressing the "OK" button. 
Query Operations...
This command opens the same dialog the previous one. However, its purpose is to select all those methods which do not change the state of the component.
Delete
Removes the component from the project and closes all related edit windows.

The component node children are described next.

 Attributes

This node has no pop-up menu. There is one child for each public attribute. 

Operations

This node has no pop-up menu and has one child for each public method (except constructors) of the component. In turn, each method has one child node for each parameter. The parameter nodes have no pop-up menu associated to them, but the method nodes have the following one:

Coordinated
This checkbox should be set if the method may in the future be coordinated, i.e., may appear in the trigger of some contract rule. By default, i.e., when a component is added or reloaded to the project, all methods may be coordinated.
Query
This checkbox should be set if the method does not change the state of the object. This information is used by CDE when generating code for contract rules triggered by state changes. By default, all methods starting with "get" or called "toString" are set as query methods.

Selecting a method node creates an edit window for the component (if it does not exist), makes it the current window, and jumps to the first line of the method.

File

This node corresponds to the source file of the component, which is stored in the components directory under the project directory. To edit the file, double-click on the node. The same effect can be obtained by selecting the Edit Textual from the node's pop-up menu, which has no further operations. 

Generated Files

This node has no pop-up menu. There is one child for each file generated by CDE from the component source. In this version of CDE, three files are generated, called X.java, XInterface.java and IXPartner.java, where X is the name of the component. One should not change any of these files. Double-clicking on a file node opens the file in the edition pane. Each file node has the following pop-up menu:

Edit Textual
This command opens the file.
Java Compile
Invokes the Java compiler on this file. The result will be put in the classes subdirectory of the project directory.

Contract node

A contract node may have the following children nodes: one for each participant, one for the source file, one for each rule, one for the attributes, and one for the generated files.  Again, we describe first the contract node's pop-up menu and then the children nodes.

Edit Textual
This opens the contract source file in a new tabbed edit window in the edition pane (if it doesn't exist), and makes it the current window.
Generate
The same command as in the Project menu.
Java Compile
Invokes the Java compiler on all files generated for this contract, which are in the "Generated Files" node.
Delete
Removes the contract from the project and closes all related edit windows.

The source file node behaves in the same way as the source file node of a component node, i.e., it reacts to double-clicks and has the same pop-up menu. A contract rule node has one child for each part of the rule: trigger, guard, body, and failure condition. Selecting the rule node will jump to that rule in the edit window for the contract source file. Of course, if necessary the file will first be opened. The attributes node has one child for each contract attribute. Selecting an attribute node will open an edit window for that contract (if necessary) and then jump to the line of that attribute. The generated files node is as for components, the difference being the actual files that are generated: there is one file X.java, where X is the contract name,  and one file Xp_PConnector.java for each participant p:P declared in the contract. Each generated file node has the same pop-up menu as for components.

The Edit Pane

The edit pane contains one tabbed edit window for each currently opened file. The file may be the source of a component or contract, it may be a Java file generated by CDE, or any other text file, e.g., a Java file that is part of the application being built but which is not under coordination. Although it is possible to edit any text file with CDE, the built-in editor is only aware of the syntax of Java and contracts: it uses different fonts and colors to highlight reserved words, comments, strings, etc. It also shows matching parentheses and braces.

The left bottom area of the pane shows the current cursor position, in the form line number:column number. The right bottom area shows the full path name of the current file.

The actual editing area has a gray thick line on its left, which separates it from a column containing the line numbers. By default, the column is not visible. The line can be dragged left and right to change the width of the column. Double-clicking on the line will  make the column disappear (resp. appear), if it is visible (resp. not visible). 

Right-clicking on the edit window pops up a menu with the copy, cut, and paste operations of the Edit menu, the save and close operations of the File menu, and a Compile command which is only enabled for Java files. It invokes the Java compiler on that file. 

The Message Pane

The messages in the lower part of the CDE window are generated by CDE or by the Java compiler. If the compilation of a contract generated some errors, it is possible to click on the error message to jump directly to the offending line in the edit pane. 

The File Menu

This menu contains commands that operate on files and projects. Obviously, certain commands (like Save and Save Project) will only be active if there is an open file or project.

New

This item opens a submenu with two items:

File...
Opens a file dialog to create a new text file. An empty edit window is created.
Contract...
Opens a file dialog to choose a directory and a name for a new contract source file. There is no special extension for contracts, but we at ATX use ctr. A new contract node is created with a source file child, and an edit window with a contract template appears. 

New Project...

This command opens a file dialog to choose a directory and to input the name of a new project file. There is no special extension for project files; at ATX we use cdp. The project pane is updated: a new view is created just with the project root node. If the directory where the new project file is to be created already has a components subdirectory, the user has to confirm whether s/he wants to proceed, because its existence indicates there is already another project in that directory. There is no problem for two projects to share common subdirectories as long as the actual component and contracts are distinct. If two projects share some components or contracts, then the user must be aware that any change to a file in a project might be jeopardizing the other project.  

Add

This item is only active if at least one project is open. It has a submenu with two items to add components and contracts to the current project:

Add Component...
This command opens a file dialog to choose a Java source file. Once the file is chosen, CDE attempts to load the Java class into the project. If there is any syntax error in the file, the load operation fails and a message appears indicating the syntax error. If loading succeeds, a new component node is added to the project tree
Add Contract...
This command is similar to the previous one. The contract will only be added to the project if it compiles, i.e., if it contains no errors.

Open File...

This command allows the user to open any text file. This is useful if there is some mistake in a component or contract and therefore it cannot be loaded into the project. With this command it is possible to open the component or contract as a simple text file, without trying to add it to the project. Using the CDE text editor one can correct the file and then try to load it.

Open Project...

This command opens a previously saved project, making it the current project. The project pane is updated correspondingly.

Reopen

This submenu contains a list of recently opened files, divided into two groups: text files and projects. This allows to quickly open files on which the user is working. 

Close

This command closes the current edit window. If the file has been changed, a dialog asks the user whether s/he wants to save the file.

Close Project

This command closes the current project. If the project has been changed, a dialog appears asking the user whether changes are to be saved. All windows in the edit pane related to the current project are closed. 

Save

This command saves the file in the current edit window.

Save Project

This command saves the current project.

Save As...

This command opens a file dialog to save the file in the current edit window under a different name or in a different location. However, the current edit window continues to be opened on the original file.

Exit

This command exits CDE.

The Edit Menu

This menu contains the usual cut, copy, and paste operations. The cut and copy operations are only active if some text is selected in the current edit window.  The menu also has a command to select all the text in the current edit window.

The View Menu

The operations in this menu change the appearance of the CDE editor window.

View Output

This toggle command makes the message pane (dis)appear. 

View Explorer

This toggle command makes the project pane (dis)appear.

Detach Window

This command detaches the current edit window from the edit pane, i.e., the edit window becomes a freely floating window. 

The Project Menu

This menu gathers operations on projects, like generating the Java files that adapt components and implement contracts. 

Compile

This submenu has two items:

Contract Compiler
This command saves the file in the current edit window and tries to load it as a contract. Any error messages appear in the message pane. If there is no edit window open, the command is inactive.
Java Compiler
This command invokes the Java compiler on the file in the current edit window. Any messages from the Java compiler appear in the message pane. If there is no edit window, or if the file in the current edit window has not a .java extension, then this command is disabled.

Add Component...

This command is the same as selecting File->Add->Add Component...

Add Contract...

This command is the same as File->Add->Add Contract...

Generate

This command is only active if the current node in the project pane is a component node or a contract node. In each case this command generates the necessary files to adapt the component or implement the contract. These files will be in a Generated Files node under the current component or contract node. 

If the component or contract source file has been changed meanwhile, a dialog appears to confirm whether the user wants to proceed. Clicking OK will automatically reload the component or contract and then generate the files.

Project Options...

This command opens a dialog with three tabs:

Files/Directories
There are three text boxes to introduce the paths of files necessary for CDE to properly generate and compile files. The first path is of the Java compiler. If its location is already in the PATH environment variable, there is no need to write anything in this box, unless the user wishes to use an alternate Java compiler. The second path is the location of the CDE runtime classes, namely file cderuntime.jar in the directory where CDE was installed. The third box contains the paths of all directories containing packages with classes referred by the components or contracts, but which are not under coordination and therefore haven't been added to the project. For example, if a contract has as an attribute an object of a certain class X (belonging to a package P) which is not part of the project --- because no method of X will ever be coordinated ---, then the directory containing P must be given in the third box.
Generation
This tab has only a single check-box option: Generate Animation Events. This option should be selected if the CDE animator will be used to test the contracts. If, on the other hand, the contracts and components will be embedded in a stand-alone application, then the option should be left unchecked. 
General
This tab includes a single option to state whether the project should be saved in XML format.

The Tools Menu

Animator...

This command launches the CDE animator. It is only enabled if a project is open.

The Help Menu

About...

This command shows the CDE splash screen with the ballerinas together with the version number.

The Toolbar

The buttons in the toolbar are merely shortcuts to frequently used commands. The following table shows the button icon and the corresponding menu command. The button is inactive (i.e., the icon is grayed out) whenever the corresponding command is. When the mouse cursor is left for a while over a button, a tool tip appears: a small text box describing the action associated to the button.

Button Command Button Command
File->New Edit->Cut
File->New Project Edit->Copy
File->Open Edit->Paste
File->Open Project    
File->Close Project->Compile->Java Compiler
File->Save Project->Generate

The Key Shortcuts

The following table lists the available key shortcuts. Of course, they will only perform any action if the corresponding menu command is enabled.

Key Command Key Command
Ctrl-N File->New Ctrl-X Edit->Cut
Ctrl-O File->Open Ctrl-C Edit->Copy
Ctrl-W File->Close Ctrl-V Edit->Paste
Ctrl-S File->Save Ctrl-A Edit->Select All
       
    Ctrl-F9 Project->Generate