Now let's make working with the exclusion file a bit friendlier by contributing a custom editor.

Example . org.eclipse.jdt.ui/plugin.xml

<extension point= "org.eclipse.ui.editors"
  id= "org.eclipse.jdt.ui.javaeditor">
  <editor
    id="org.eclipse.jdt.ui.CompilationUnitEditor"
    icon="icons/full/obj16/jcu_obj.gif"
    name="%JavaEditor.label"
    extensions="java"
    class="org.eclipse.jdt.internal.ui.javaeditor.
      CompilationUnitEditor"
    contributorClass="org.eclipse.jdt.internal.ui.javaeditor.
      CompilationUnitEditorActionContributor"
    default="true">
  </editor>
</extension>

The Java editor is contributed to files with the extension “java”.

An editor contribution requires two implementation classes. The class attribute defines the implementation of the editor part and the contributorClass specifies a separate class defining menu and toolbar contributions. This is a major difference between editors and views. A view has a single implementation class and this class handles toolbar contributions internally. Why are editor contributions factored out into a separate class? More than one editor of a particular kind can be open inside a workbench page. All open editors share the global menu and toolbar. Having a separate class for the object contributions allows the Eclipse workbench to share the editor contributions among editors of the same kind. Figure 24.2 illustrates this. It shows two open Java compilation unit editors and a text editor. The CompilationUnitEditorActionContributor is shared between the compilation unit editors.

Figure 24.2. Shared ActionContributor

The declaration of the Java editor contribution sets an attribute default to true. This is a hint that the contributed editor should be the default editor for *.java files. Consistent with the Diversity Rule, more than one editor can be contributed for a particular element. However, when opening a file, only a single editor should be opened. Eclipse handles the ambiguity by giving the user the option to open any of the registered editors in the Open With menu, but it makes it convenient to open the default editor directly, as shown in Figure 24.3.

This illustrates another rule:

So let's make our editor contribution for the test.excludes file. Since the file has a fixed name, we don't contribute the editor to the suffix only but to the entire file name. This is consistent with the Relevance Rule. We want to make our contribution as specific as possible. Instead of implementing a text editor from scratch we reuse the default text editor, but we contribute a custom contributorClass:

<extension point="org.eclipse.ui.editors">
  <editor
    id="org.eclipse.contribution.junit.TestExclusionEditor"
    icon="icons/testok.gif"
    name="Test Exclusions Editor"
    filenames="test.exclusion"
    class="org.eclipse.ui.editors.text.TextEditor"
    default="true"
    contributorClass="org.eclipse.contribution.junit.
      TestExclusionEditorActionContributor">
  </editor>
</extension>

Eclipse allows the user to modify the file-editor associations in the preferences. If we start up the run-time workbench after the above change, our editor shows up in the File Associations preference page, as shown in Figure 24.4.

Even though we don't have to implement the editor ourselves, let's look at how its implementation differs from a view. An editor is opened on a particular element that becomes its input. An editor input is a lightweight description of the element. When a text editor is opened on a file, its input is an IFileEditorInput, as illustrated in Figure 24.5.

Figure 24.5. FileEditorInput Represents an IFile

The input is passed to an editor part together with its site in the init() method.

In contrast to views, editors follow an open-modify-save cycle. The methods supporting saving are captured in the ISaveablePart interface. It defines methods like isDirty(), doSave() and doSaveAs(). When the dirty state of an editor changes we have to notify interested parties with firePropertyChange(PROP_DIRTY).

Next we'll implement the contributor class to add the actions for our editor.

Our contributor class extends the BasicTextEditorActionContributor and contributes an action, ExcludeTestAction, to append a test to be excluded.

Here is the test to verify that the action is contributed when our editor is opened. As for most of our other tests, the test is creating a TestProject in setUp() that is then disposed in tearDown().

Example . org.eclipse.contribution.junit.test/ExclusionEditorTest

public class ExclusionEditorTest extends TestCase {
  private TestProject testProject;

  protected void setUp() throws Exception {
    testProject= new TestProject();
  }

  protected void tearDown() throws Exception {
    getPage().closeAllEditors(false);
    testProject.dispose();
  }
}

The actual test creates a test.exclusion file and opens it in the editor.

Example . org.eclipse.contribution.junit.test/ExclusionEditorTest

public void testEditorContribution() throws CoreException {
  IFile file= testProject.getProject().getFile(
    new Path("test.exclusion"));
  file.create(new ByteArrayInputStream("".getBytes()), true, null);
  IEditorPart part= getPage().openEditor(file);
  assertTrue(findContributedAction(part));
}

To verify that the ExcludeTestAction is contributed to the toolbar, we have to reach into the toolbar manager and look for our contributed action:

Example . org.eclipse.contribution.junit.test/ExclusionEditorTest

private boolean findContributedAction(IEditorPart part) {
  IActionBars actionBars= part.getEditorSite().getActionBars();
  IToolBarManager manager= actionBars.getToolBarManager();
  IContributionItem[] items= manager.getItems();
  for (int i= 0; i < items.length; i++) {
    IContributionItem item= items[i];
    if (item instanceof ActionContributionItem) {
      IAction a=((ActionContributionItem)item).getAction();
      if (a.getClass().equals(ExcludeTestAction.class))
        return true;
    }
  }
  return false;
}

Now let's implement the contributor class. It manages the action we want to contribute:

public class TestExclusionEditorActionContributor
    extends BasicTextEditorActionContributor {
  private ExcludeTestAction excludeAction;

  public TestExclusionEditorActionContributor() {
    excludeAction= new ExcludeTestAction();
  }
...

We contribute the excludeAction to the Edit menu and append it to the local toolbar by extending the corresponding contribution methods:

public void contributeToToolBar(IToolBarManager manager) {
  super.contributeToToolBar(manager);
  manager.add(new Separator());
  manager.add(excludeAction);
}

public void contributeToMenu(IMenuManager menu) {
  super.contributeToMenu(menu);
  IMenuManager editMenu= menu.findMenuUsingPath(
    IWorkbenchActionConstants.M_EDIT);
  if (editMenu != null) {
    editMenu.add(new Separator());
    editMenu.add(excludeAction);
  }
}

Notice that we contribute the same action object to both the menu and the toolbar. When changing an attribute of an action (for example, its enabled state), both the menu and toolbar are automatically updated.

Since the contributor is shared among editors of the same kind we have to implement setActiveEditor(). This method is called whenever the contributor's editor has changed. We check that the new editor is a TextEditor and inform our action that it should now target a different editor:

public void setActiveEditor(IEditorPart target) {
  super.setActiveEditor(target);
  ITextEditor editor= null;
  if (target instanceof ITextEditor)
    editor= (ITextEditor)target;
  excludeAction.setActiveEditor(editor);
}

Finally, to enable early garbage collection of editors when the contributor is disposed, we make sure that the action clears the reference to the active editor:

public void dispose() {
  super.dispose();
  excludeAction.setActiveEditor(null);
}

Next, let's implement the ExcludeTestAction. It is an ordinary JFace action and it keeps a reference to its target editor:

public class ExcludeTestAction extends Action {
  private ITextEditor editor;
  public ExcludeTestAction() {
    setText("Exclude Test");
    setToolTipText("Exclude a Test Case");
    setImageDescriptor(createImage("icons/test.gif"));
  }

  public void setActiveEditor(ITextEditor target) {
    editor= target;
  }
  //...
}

We create the images in the helper method createImage() which retrieves the images relative to the installed plug-in location:

private ImageDescriptor createImage(String path) {
  URL url= JUnitPlugin.getPlugin().getDescriptor().getInstallURL();
  ImageDescriptor descriptor= null;
  try {
    descriptor= ImageDescriptor.createFromURL(new URL(url, path));
  } catch (MalformedURLException e) {
    descriptor= ImageDescriptor.getMissingImageDescriptor();
  }
  return descriptor;
}

When the action is run, it allows the user to select a test. Once the user makes a choice, it appends the selected test name to the active editor:

public void run() {
  IType type= selectTest();
  if (type != null)
    appendTest(type.getFullyQualifiedName());
}

The method selectTest() uses the TestSearcher to find all the tests inside the project and presents the list in a dialog. As we have seen above, the input to a text editor is a IFileEditorInput from which we can navigate to the containing Java project:

private IType selectTest() {
  IEditorInput input= editor.getEditorInput();
  if (input instanceof IFileEditorInput) {
    IFile file= ((IFileEditorInput)input).getFile();
    IJavaProject jproject= JavaCore.create(file.getProject());
    try {
      IType[] types= new TestSearcher().findAll(jproject,
        new NullProgressMonitor());
      return showDialog(types);
    } catch (JavaModelException e) {
    }
  }
  return null;
}

To show the list of tests, we use an ElementListSelectionDialog with a JFace label provider to define the appearance of the elements in the dialog. The Java development tools provide a standard JavaElementLabelProvider that we use to render the types.

private IType showDialog(IType[] types) {
  ElementListSelectionDialog dialog=
    new ElementListSelectionDialog(
      editor.getSite().getShell(),
      new JavaElementLabelProvider());
  dialog.setTitle("Exclude Test");
  dialog.setMessage("Select Test to exclude:");
  dialog.setElements(types);
  if (dialog.open() == Window.OK)
    return (IType)dialog.getFirstResult();
  return null;
}

Finally, we are ready to insert the fully qualified type name into the editor. Eclipse editors use IDocuments to store their contents. A text editor has a document provider. It knows which document is associated with a particular editor input. Once we have the document we can insert the text:

private void appendTest(String testName) {
  IDocumentProvider provider= editor.getDocumentProvider();
  IEditorInput input= editor.getEditorInput();
  IDocument document= provider.getDocument(input);
  if (document == null)
    return;
  try {
    document.replace(document.getLength(), 0, testName+"
");
  } catch (BadLocationException e) {
  }
}

This concludes the implementation of our simple editor. Let's review this chapter:

In the next chapter we will revisit the ResultView.