User Guide

Setting-up the ispace nature

Step 1. Follow the instruction from the download page.

Step 2. Right-click in the Package Explorer on a Java Project of your choice. Select "ispace->Add ispace nature" from the context menü. This will add the nature and create the /<project-name>/.ispace/<project-name>.ispace file.

Step 3. Rebuild the project. After Java builder finishes, the ispace builder is called. In the case that you want restart with a fresh diagram later, simply redo the clean build.

Step 4. When the complete build process finishes. right-click on the project again. And select "ispace->Open ispace view".

Note: If you want to remove the ispace nature later, open the context menu of the project and select "ispace->Remove ispace nature".

Basic Concepts and Operations

ispace uses a nested graph for visualizing hierarchical data, i.e., each node can contain sub-nodes. We refer to such nodes as composite nodes. Relations between sub-nodes of different composite nodes are automatically aggregated at the level of containing nodes.

For example the in the figure above, the three relations between classes in package pA and classes in package pB are aggregated in the relation between pA and pB.

All operations on nodes and edges are available via their context menu. In the following we describe those.

Group / Ungroup

Users can change the abstraction hierarchy by grouping and ungrouping elements. For instance, this can be used to further group methods within a class, or classes within a package. Note that you can change the name of the group by doing a single click into the group. This opens the direct edit box for the group's name.

Move

Furthermore the abstraction hierarchy can be changed by moving an element from one composite node to another composite node. The relations are automatically recalculated and reaggregated. This is an useful feature for performing a what-if analysis. For instance: "how dependencies would change, if I move this element from package A to package B?"

Expand / Collapse

The content of any composite node can be revealed by calling "expand group" in node's context menu. The reverse operation is collapse. An alternative is to use the double-click on the composite node. This features allow the user to select the portion of the data which is of interest to him, while hiding at same time all other irrelevant elements.

Drill-Down an aggregated relation

...TODO...

Hide / Unhide

Relations of irrelevant nodes can be hidden using this operation. Only the relations of the current level are hidden. E.g., hiding pA.Y will hide the incoming relations from pA.X and pA.Z, but will not affect the relation from pA to pB.

Mark elements

Elements of interest can be marked. Markers recursively propagate to their containing composite nodes. If a sub-node is marked, than its containing node inherits the marker.

For instance, in the figure above the classes X and Y in pA are marked resulting in package pA being marked too.

Moreover, for each node and each relation we can mark its corresponding targets and sources. This is done by selecting the desired relation or node and selecting from the corresponding context menu "Markers->Mark Sources" or "Markers->Mark Targets". For example, in the figure above, the classes X and Y are marked by selecting the relation pA->pB and then calling from the context menu "Markers->Mark Sources".

All markers of a selected element can be cleared by calling "Markers->Clear All Markers".

Clustering operations

Few primitive clustering operations are currently supported in ispace.

Cluster by Static/Non-Static - Separates members in a class into static and non-static members
Cluster by Type - Groups class members according to their kind. Methods are grouped together, and fields are grouped together.

Selection mechanisms

The scope of selection operations from the "Selection" context menu is always limited to elements within the same composite.

Select All - Selects all elements within the currently selected composite. (Shortcut: CTRL+A)
Invert Selection - Shanges the selection not selected elements within the same composite as the currently selected elements.
Select by Marker - Selects within a node all elements having the same marker status. In other words, if a maraked node is under current selection, and we call "Selection->Select by Marker" all other marked nodes within the same composite are selected too. On the other hand, if we have a non-marked element under the current selection, by calling "Select by Marker" will select all other non-marked nodes within the same composite.

Selected aggregated relations

If an aggregated relation is selected, then two numbers get displayed at the source and target side. This number is the number of low-level elements at each side of the aggregated relation.

Layout

Currently only the levelization layout is supported. The layout tries to sort elements in layers. The bottom most level is the level 0. There are all elements placed that have no further dependencies. Level 1 contains all the elements depending on elements from level 0. Or in general: elements from level n+1 depend on elements at level m <= n. Relations being part of a cycle are marked red.

It is possible to manually override positions of elements. The layout of a selected node can be recalculated by calling "Do Layout" from the context menu. An alternative is using the Shortcut CTRL+L.

Node and relation types

ispace nodes bound to a Java element (e.g. package, class, method, field) are annotated with the corresponding JDT icon. User defined groups have no icon.

ispace relations are categorized as: implements, inherits, uses. Visually they conform to the UML notation.

Incremental Synchronization JDT->ispace (experimental)

ispace provides support for an incremental builder responsible for synchronizing changes done in Source Code with the ispace presentation. However, note that this is an experimental feature. In the case that something goes wrong clean the project and restart with a fresh diagram.

Applying ispace

The application areas of ispace are manifold. In the following we outline some oft them.

Constructing and analyzing top-level views

When analyzing a software at top-level the user is among others concerned with the following questions.

What are the top-level elements?
What are dependencies between these elements?
Which lower level elements cause these dependencies?

ispace features are flexible enough to support answering these questions. For instance, grouping is used to hierarchically organize the information. Collapse/expand operations allow the user to select the desired amount of information within this hierarchy. Finally, mark targets/sources are useful in investigating details of dependencies between top-level elements.

Experimentally restructuring dependencies

When a top-level view is constructed, a user could identify undesired dependencies which should be eliminated. Such restructurings can be easily done in ispace, by simply applying the move operation.

Localizing features within the code

Features, as an unit of cohesive functionality that corresponds to a set of requirements in the system specification, are in general crosscutting to classes. In many cases the features are scattered across different classes and often also across different packages. ispace can be used to isolate such a feature in the source code.

Structuring god-classes and god-packages

Programming languages like Java provide organize code with classes and packages. However, in some cases some classes and packages get overloaded with responsibilities, making them difficult to understand. ispace can be used in such cases to investigate the responsibility groups in such classes and package and group contained elements.

Documenting Software Structures

Snapshots of the ispace views can be easily integrated into the project documentation.

Appendix

Known issues with the current version

Editor has to be closed before performing the clean build
Some users experienced problems on core-duo-processors. The workaround at the moment is to assign the eclipse process to single cpu only.