Cascade Tutorial
Cascade is a Type Qualifier Inference (TQI) tool. It proposes a set of changes, each of which annotates part of the code.
A video version of this tutorial is available available at http://youtu.be/FOyGZNp5bAI.
To run Cascade, right-click on the Eclipse project that you want to annotate and select Type Qualifier Inference > Infer Nullness Qualifiers. The following screenshot shows how to run Cascade.
When you run Cascade, it initiates several jobs to compute the changes that would annotate the code. You can see the progress of these jobs in the Progress view (See the screenshot below).
The jobs shown in the Progress view update the Cascade view (See the screenshot below). We recommend that you wait until all the jobs in the Progress view are finished and then start using the Cascade view.
Cascade recursively initiates a job that runs the Nullness Checker on a copy of the source code, proposes a change to resolve each error message, applies the change on the copy of the source code. Cascade continues this recursive computation until there are no more error messages to resolve or changes to apply. Cascade builds a tree that reflects the results of this recursive computation on a copy of the source code so that it does not affect the original source code.
More concretely, Cascade first initiates a job that runs the Nullness Checker on a copy of the source code. As a result, the Nullness Checker may report several error messages. These error messages become the root nodes of the Cascade tree. For each error message, Cascade computes a change that would fix that error message and proposes the change by making it a child of the error message in the tree. Next, for each pair of error message and proposed change, Cascade applies the change on the copy of the source code that produced the error message and then recursively computes the rest of the tree starting from the resulting source code.
The Cascade view consists of a tree (See the screenshot below). The root of the tree is the set of error messages that the Nullness Checker reports for the Eclipse project that you ran Cascade on.
The Cascade tree has two types of nodes: change nodes and error message nodes. A change node is a child of an error message node and a non-root error message node is a child of a change node. The screenshot below shows the root of a Cascade tree with six error messages.
Cascade alternates the background colors of the tree nodes between white and grey to make it easy to visually distinguish the adjacent tree nodes. The different background colors of the tree nodes don't have any semantic connotation.
To expand a tree node, click on the triangle icon besides it. When you click on the triangle icon the tree will expand to show the children of the tree node that you expanded. If you click the triangle icon again, the tree will collapse the children of that tree node.
The tree in the Cascade view is similar to other trees in Eclipse, e.g., the Package Explorer view. However, unlike standard Eclipse views that use trees to show hierarchies of program elements, Cascade uses a tree to show future states of the source code.
- Expanding an error message shows a change (if any) that Cascade proposes to resolve that error message.
- Expanding a change shows the new error messages that will appear if the change is applied.
Expanding the Cascade tree doesn't change the source code. Rather, it allows you to explore the future states of the source code. That is, you can use Cascade to see how a sequence of the proposed changes will affect the source code.
Expanding an error message shows a change (if any) that Cascade proposes to resolve that error message. For example, if you expand the first error message shown in the screenshot below, the tree will expand to propose a change described as Change field left to @Nullable TreeNode (2). The tree shows the change below the error message and indents the change to indicate that the change is a child of the error message. The screenshot below shows the shape of the tree after expanding the tree node of the first error message.
Expanding a change node shows the new error messages that will appear if the change is applied. If the change won't introduce any new errors, the change node won't expand. The screenshot below highlights the following error message:
incompatible types in argument.
this(1, null, null)
found : null
required: @Initialized @NonNull TreeNode
To resolve the above error message, Cascade proposes the change Change parameter l to @Nullable TreeNode. Moreover, the screenshot shows the following error message as a child of this change, which means that performing the change will introduce the following error message:
incompatible types in argument.
left = l;
found : @Initialized @Nullable TreeNode
required: @Initialized @NonNull TreeNode
In addition, further expansion of the above error message shows that Cascade proposes the change Change field left to @Nullable TreeNode (1) to fix this error message.
Recall that expanding the Cascade tree doesn't change the code. Rather, it proposes changes to resolve error messages and shows the new error messages that applying a change will introduce.
If you double-click on an error message, Cascade will open and highlight the piece of code related to the error message (See the screenshot below for an example).
Cascade proposes changes to resolve some of the error messages. Children of an error message node in the tree are the changes that Cascade proposes to resolve the error message.
Description. The description of the change tree node explains how the change is going to annotate the program. The change description includes a number in parentheses at the end. This number indicates the number of error messages that this change will resolve. For example, the change description shown in the tree above indicates that it will resolve two error messages.
Ordering. The number of error messages that each change resolves affects the ordering of the error messages. Error messages whose proposed changes resolve a larger number of error messages will appear above the other error messages.
Viewing. If you single-click on a change tree node, Cascade will open and highlight the piece of the code that the change will annotate. In addition, will mark the error messages that the change will resolve by green check mark icons (See the screenshot below for an example).
If you double-click on a change tree node, Cascade will apply the change on the code and open the affected code in the editor (See the screenshot below). In addition, Cascade will disable the applied change and the error messages that it resolves. That is, Cascade changes the text colors of the change tree node and the error message tree nodes that the change resolves to grey to indicate that you applied the change and the error messages are resolved.
You should feel free to apply the proposed changes in any order and intersperse them with manual edits. However, these actions may make the tree inconsistent with the source code, in which case you can press the refresh icon to recompute the tree.
To undo a proposed change that you just applied through Cascade, give focus to the Eclipse code editor and then Press Ctrl+z. Undoing a change will cause Cascade to enable the change and the error messages that it resolves in the tree.
As you modify the source code manually, the Cascade tree may become inconsistent with the source code. You can refresh the Cascade tree to make the tree consistent with the source code.
If you press the yellow refresh icon at the top of the Cascade view, Cascade will run the jobs to compute the tree and show the updated tree.
- What will Cascade do if you double-click an error shown on the tree?
- What will Cascade do if you double-click a change shown on the tree?
- What will Cascade do if you expand an error shown on the tree?
- What will Cascade do if you expand a change shown on the tree?
- How can you undo a change that you applied from the tree?
- What will Cascade do if you click on the Refresh icon?