Developer Notes

8. Resource Explorer classes and data model

The Resource Explorer is an example of what Eclipse's workbench calls a view (rather than an editor), and is expressed as an Eclipse ViewPart. Furthermore, the ResourceExplorer has to appear in the plugin's plugin.xml file so that Eclipse as a whole knows about the editor and knows how to invoke and present it.

Resource Explorer in plugin.xml

Here is the fragment of the plugin.xml file that refers to the Resource Explorer:

   <extension
         point="org.eclipse.ui.views">
      <category
            id="uk.ac.kcl.cch.jb.pliny.category"
            name="Pliny"/>
      <view
            category="uk.ac.kcl.cch.jb.pliny.category"
            class="uk.ac.kcl.cch.jb.pliny.views.ResourceExplorerView"
            icon="icons/resourceExplorer.gif"
            id="uk.ac.kcl.cch.jb.pliny.resourceExplorer"
            name="Resource Explorer"/>
[...]

Information about all views are filed in the extension element with its point attribute set to org.eclipse.ui.views. Views can be opened from the Window/Show View menu, and defining a category element, associating the Resource Explorer view with that category effectively manages the place where the command to open this view will appear in the list of views managed by Eclipse within Window/Show View.

Within the view element there are several other important attributes:

  • class: defines the Java class that should be instantiated and invoked to create the view.
  • id: provides an id string that allows this view to be referred to from elsewhere.
  • icon: provides an icon that Eclipse can display whenever it needs one to identify this view.
  • name: provides a name Eclipse can use whenever it needs to show the user a name for this view.

The ResourceExplorerView class

uk.ac.kcl.cch.jb.pliny.views.ResourceExplorerView is the main class that Eclipse will use to create Pliny's Resource Explorer view. For Eclipse to use this as a view the class must implement org.eclipse.ui.IViewPart, which it does by extending class org.eclipse.ui.part.ViewPart.

When Eclipse sets upf the Resource Explorer by instantiating ResourceExplorerView it calls method createPartControl() to ask the view to create its GUI.

ResourceExplorer View's createPartControl() method

The ResourceExplorer contains within it in fact two displays which are controlled by the tabs at its bottom: "By Type" and "By Date". The two displays are similar in general layout (they both, for example, use a tree paradigm, but the ordering of the things they display is different. For this reason, what happens is that SWT's tabbing mechanism is used to support the tabs themselves, and the display of each Tab is managed by Pliny's classes uk.ac.kcl.cch.jb.pliny.views.RETypeTab and uk.ac.kcl.cch.jb.pliny.views.REDateTab respectively. Among other things these classes do is to create controls to display on the screen. So, after one of each of these classes are instantiated, each of them have their createTabItem() method (this is an inherited method) invoked to populate the display area.

Much of the user interface interaction is then delegated to either RETypeTab or REDateTab which both inherit from uk.ac.kcl.cch.jb.pliny.views.REBaseTab. See the section Resource Explorer Tab Classes below for more information.

Resource Explorer Actions and Commands

Like other Eclipse Views, the Resource Explorer makes use of Eclipse's Action framework to implement actions. Many of the actions need to be undoable, and although GEF is not used in the display Resource Explorer data, we make use of GEF's Command and CommandStack classes to support undo. Thus, most actions, when run, really invoke a org.eclipse.gef.commands.Command to change the data model, and expect listeners from Resource Explorer objects to track these changes so that they are then reflected in the Explorer's display.

Action-related methods within the Explorer View class are:

Resource Explorer's two Tab classes

As mentioned above, there is a tree display behind each of the two tabs in the Explorer, and their display (and some of the interaction) come from classes uk.ac.kcl.cch.jb.pliny.views.RETypeTab and uk.ac.kcl.cch.jb.pliny.views.REDateTab which inherit from uk.ac.kcl.cch.jb.pliny.views.REBaseTab, where, in fact most of the coding lives -- given that both these classes result in very similar displays.

REBaseTab's createTabItem() method

When createTabItem() is invoked the ResourceExplorerView's createPartControl() method has set up a tab folder into which the two SWT TabItems need to be put. Thus, this method creates the new TabItem and links it to the tabFolder.

  • In both cases, the TabItem displays a tree, so creatTabItem next uses JFace's org.eclipse.jface.viewers.TreeViewer in the conventional way to manage the display of Resource information as a tree. A JFace TreeViewer makes use of the MVC model for interaction, and requires several pieces of information:
  • Information about Actions associated with this view are defined in private methods makeActions(), contributeToActionBars(), hookKeyboardActions() and hookContextMenu(). See the section Resource Explorer Actions and Commands below for some details.
  • Names of items in the tree can be direct edited. Classes uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerTextCellEditor and uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerCellModifier provide support for this.
  • Finally, drag and drop operations are signficant in the Resource Explorer. private methods setupDnDTargetProcessors() and hookDragAndDrop() set this up. See the discussion about the Resource Explorer's processing of drops as data imports in the section on Importing data below.

Other mechanisms handled by REBaseTab.

Other user facilities handled within REBaseTab include:

  • Text Cell Editing: set up in method setTextCellEditor() and using JFace's CellEditor facilities.
  • DoubleClick to open a resource: set up in method hookDoubleClickAction()
  • Assist in processing of item selection: Methods getSelectedBaseObjects(), getSelectedObjectsToOpen() and getSelectedResourceExplorerItems() provide access to selected items for other code
  • Support the Delete key function: the Delete key keypress is caught and turned into a Delete action in method hookKeyboardActions() which in turn does the real work in handleKeyReleased().
  • Manage the context menu: The methods hookContextMenu(), and fillContextMenu() (which, in turn delegates to the Resource Explorer's view's fillContextMenu() manage the display of the context menu

The Resource Explorer Data Model

The tree structure of the Resource Explorer has its own data model which is built on top of the basic Pliny data model provided for in package. uk.ac.kcl.cch.jb.pliny.model. In this way the model can both represent the data in an appropriate hierarchy to match the way the explorer displays it, but can also track changes in the basic Pliny data model in ways that reflect the way things are shown in the explorer.

The Resource Explorer operates as a tree, so the data classes that define this tree are also structured as a Tree.

Inheritance model

Classes that define the explorer data model all implement interface uk.ac.kcl.cch.jb.pliny.views.utils.IResourceExplorerItem, which defines methods to provide a textual label and an icon for the item, point to its parent, and provide for information about its children.

  • At the base of the inheritance tree for almost all resource explorer data classes is uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerItemBase which provides base implementation for many classes in the IResourceExplorerItem and begins to define methods to allow classes that inherit from it to handle dynamic changes in their data: specifically methods propertyChange() and updateMyChildren().
  • Data items that display names that come from the Pliny base model and can be changed by the user can extend uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerNamedModelItem which extends the functionality in ResourceExplorerItemBase by defining links between the name display in the explorer and the name in the Pliny base model, and adding tracking for this name so that if it is changed elsewhere it will be simultaneously updated here as well.
  • Data items that manage lists of Resources directly extend uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerSurrogateListItemBase, which in turn is an extension on ResourceExplorerItemBase.

Having now described the class inheritance basic model, it is time to look at the model classes from the perspective of the presentation hierarchy:

Level 0: Root

Depending upon whether the user is viewing the "By Type" or "By Date" display, either uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerRoot or uk.ac.kcl.cch.jb.pliny.views.utils.DatedResourceRootprovides the root of the tree which is actually displayed in the view. Since the root objects manage their children themselves, thay are able to take a type-oriented approach or a date-oriented approach with their children.

Type-display Level 1 : ObjectTypes

The root's children are created from Pliny base data model's uk.ac.kcl.cch.jb.pliny.model.ObjectType (and from the Favourites header -- see description below). Information about each of them is managed in the resource explorer's model class uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerObjectTypeItem which, because it displays the name of a Pliny resource type which is editable, extends ResourceExplorerNamedModelItem.

Type-display Level 2: Initial letter of name

Resources of each object type are grouped by the initial letter of their name -- something that is not explicitly modelled in the base Pliny data model. To manage this data model classes uk.ac.kcl.cch.jb.pliny.views.utils.ResourceNameManager and uk.ac.kcl.cch.jb.pliny.views.utils.ResourceNameInitialLetter manage and track the initial letters of names of resources, and uk.ac.kcl.cch.jb.pliny.views.utils.ResourceNameInitialLetter class implements interface IResourceExplorerItem so that it can participate in the display tree.

Level 3: Resources

Instances of uk.ac.kcl.cch.jb.pliny.model.Resource classes themselves are displayed at this level. uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerResourceItem which extends ResourceExplorerNamedModelItem because a resource's name is editable.

Level 4: "Contains" and "DisplayedIn" headers

Level four of the display always show two headers:

  • The "Contains" header: provides a list of Resources that are contained within the annotation/resource area managed by the Resource shown at level 3.
  • The "DisplayedIn" header: provides a list of Resources that contain a reference to the resource shown at level 3 in their annotation/resource area.

For both of these two items there is a list of Resources to be managed that drive level 5. Instances of uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerContainsList displays the "Contains" header, and manages the contains list, and uk.ac.kcl.cch.jb.pliny.views.utils.ResourceExplorerDisplayedInList displays the "Displayed In" header, and manager the displayedIn list of Resources. Both of these extend the base class ResourceExplorerSurrogateListItemBase.

Lower Levels

The Resources in the two lists maintained by Level 4's item reuse ResourceExplorerResourceItem for display as level 5, level 6 sees the level 4 items again, and so on recursively.

the Display Hierarchy for the Date Tab

The display hierarchy for the date display is more complex because, depending on how old the resource is it might be under the top level "today" date tag if it was just created today, top level day-of-month tag if it was created some day earlier this month, top level month tag if created some month earlier this year, or top level year tag if it was created in a previous year. Items that manage each of these date elements are:

Resource Creation within the Explorer by means of Drag and Drop

Pliny defines its own plugin.xml extension point that allows independently created plugins to announce services that they can provide to the Pliny base plugin. One of the functions involved in this is support for importing of data as a Pliny resource by dragging an instance of the outside data onto the Resource Explorer (basic Pliny demonstrates this for the Image Resource where a web page containing a resource can have its images imported into Pliny by dragging a reference to the webpage containing the interest onto the Resource Explorer's "Image" ObjectType header). Support for this comes from the Pliny-provided extension-point resourceExtensionProcessor. See the section Extension Point resourceExtensionProcessor for more information about its use here and elsewhere within Pliny.


John Bradley
Center for Computing in the Humanities
King's College London