Chapter 29. Eclipse Ecosystem

The success of a platform can be measured by the size of its community and ultimately by the number of applications built with it. As the size of a community increases, so does the collection of components that are produced and made available—either commercially or for free. By these metrics, the Eclipse ecosystem is a huge success. The community is vibrant, the number of projects doing interesting and widely relevant work is impressive, and the majority of the world’s major software companies are members of the Eclipse Foundation. This translates into a huge number of useful, quality plug-ins that can save you time and money.

You have probably noticed that the RCP SDK includes only a few plug-ins. In Part II you learned how to add Eclipse Platform plug-ins such as Help and Update to Hyperbola. The Eclipse SDK includes more then 100 plug-ins, many of which are useful in RCP applications. Add that to the others available at eclipse.org and the hundreds available on Web sites such as sourceforge.net and marketplace.eclipse.org and it is clear that a key part of developing an RCP application is deciding which existing plug-ins to use and how they help solve the problems of your application domain.

A complete survey of the existing plug-ins is beyond the scope of this book and would likely be obsolete before it even reached your hands. Instead, this chapter contains an overview of the plug-ins in the Eclipse SDK that can be used in RCP applications.

29.1 Where to Find Plug-ins

There are two main reasons to look for additional plug-ins: Either you are looking to augment your Eclipse IDE with more tooling (e.g., Web tooling, C tools, etc.) or you need more functionality for your RCP application. You can find both in the following places.

Before going on a treasure hunt for plug-ins, read Section 23.6, “Designing a Platform,” to learn how to identify plug-ins that are meant to be reused in RCP applications. Some plug-ins are written for a particular product and are not what we call RCP-friendly.

Eclipse SDK (www.eclipse.org/downloads)—The SDK includes more than 85 plug-ins, including Java tooling (JDT), plug-in tooling (PDE), Help, Update, and various other bits and pieces. Chances are you are using the SDK to develop your plug-ins, but you might also want to include some of these in your target application.

Eclipse Tools (www.eclipse.org/tools)—The Eclipse Tools project includes many interesting and useful tooling extensions for the Eclipse IDE. These include the GEF, a visual editor (VE), Mylyn, and so on. Several of these projects (e.g., GEF) contain runtime elements that you add to your application.

Eclipse Modeling (www.eclipse.org/modeling)—The Eclipse Modeling project includes a plethora of modeling frameworks and tools that can help you build RCP applications, including the EMF and related projects.

Eclipse Technology (eclipse.org/technology)—The Eclipse Technology project includes all manner of experimental and not-so-experimental work on tooling and runtime technologies. There are subprojects for memory analysis, collaborative development, Linux tooling, and much more. Again, some of these projects include additional tooling for your development environment, some include runtime elements for your target, and some include both.

Other Eclipse projects—Eclipse.org hosts a number of other top-level projects such as Web tooling (WTP), test and performance (TPTP), and modeling and reporting (BIRT). Again, some are strictly tooling to help you build or implement your application, and some include or generate application runtime facilities.

Links to community resources—The Eclipse community is very active and includes many sites that either host or point to collections of plug-ins. The community resources page at http://eclipse.org/community/sources.html#links includes links to the major plug-in repositories and directories.

Search the Web—There are many other sources for Eclipse plug-ins. For example, http://marketplace.eclipse.org and http://sourceforge.net host hundreds of Eclipse plug-ins.

29.2 Eclipse Platform Plug-ins

The Eclipse Platform is dedicated to providing a robust, full-featured, and commercial-quality platform for the development of highly integrated tools. The Eclipse Platform is thus an excellent source of product-quality plug-ins that can be used in your applications.

In an effort to keep the RCP download small, only a small set of the platform plug-ins is included in the RCP SDK. However, as you saw in Chapter 13, “Adding Help,” and Chapter 14, “Adding Software Management,” you can add plug-ins from the Eclipse SDK to your application.

There is one caveat, however. As mentioned in Chapter 23, “RCP Everywhere,” and in particular as explained in Section 23.3, “Product Configurations,” plug-ins are designed to work either with a specific product or alternatively with any product. The Eclipse Platform contains both types. The plug-ins that depend on the existence of the IDE product, for example, having a dependency on the org.eclipse.ui.ide plug-in, are not meant to be used by RCP applications. If you aren’t sure, review the checklist in Section 23.7 for how to determine if a plug-in can be used in an RCP application.

In this chapter we review the Eclipse SDK plug-ins that can be used by RCP applications. We do not have enough pages to provide an exhaustive reference to each, but we provide enough detail for you to understand how they work and where to find more information.

29.3 Product Introduction

When users start an application for the first time, they often do not know how or where to begin. This leads them to either dismiss the application because they don’t understand its features or waste precious time trying to figure out how to get started.

Intro support solves these problems by giving users an introduction to the features of the product the first time it is started. This is your opportunity to direct users to important starting points, highlight interesting capabilities, and ultimately help users understand what your product is and how to use it.

The Workbench provides an extension point named org.eclipse.ui.intro and an interface to describe Intro pages named IIntroPart. The Workbench does not, however, provide any reusable pieces that make it easy to create an Intro page. Applications can either provide their own IIntroPart implementation or use the org.eclipse.ui.intro plug-in and its helpers to build a nicer Intro page.

By default, the Intro page is shown the first time a product is started. The showing of the Intro pages is controlled by the preference IWorkbenchPreferences.SHOW_INTRO. The actual creation and triggering are done in WorkbenchWindowAdvisor.openIntro(). The default implementation opens the contributed Intro content, but you can override this to do whatever you like.

The lifecycle of the Intro part is as follows:

• The Intro part is created on Workbench startup. As with editor and view areas, this area is managed by an Intro site (implementing org.eclipse.ui.intro.IIntroSite).

• The ID of the current product (Platform.getProduct()) is used to choose the Intro part to show.

• The Intro part class (implementing org.eclipse.ui.intro.IIntroPart) is created and initialized with the Intro site.

• While the Intro part is being shown to the user, it can transition back and forth between full and standby modes (either programmatically or explicitly by the user).

• Eventually the Intro part is closed (either programmatically or explicitly by the user) and the current perspective takes over the entire Workbench window area.

A good way to understand how to build Intro pages is to look at the Intro template. Create a new RCP plug-in project, and from the list of templates select RCP application with intro. The sample code for Chapter 25 includes Intro support for Hyperbola, and the Workbench itself includes a standard action to open the Intro page called org.eclipse.ui.actions.ActionFactory.INTRO.

29.4 Resources

The Resources plug-in offers a layer above java.io.File that adds support for markers, builders, change notifications, local history, and persistent and session properties. It introduces a workspace in which projects, files, and folders are created and manipulated. Projects are root folders in the workspace and contain files and folders. This plug-in is the basis for all IDE tooling in Eclipse.

It is a common misconception that the Resources plug-in is only for tools. In fact, Resources is all about file manipulation. If your application does a lot of sophisticated file manipulation, either explicitly or under the covers, you might be interested in Resources. Of course, you can always use java.io.File and related classes to manage files directly.

29.4.1 Overview of Resources Key Features

From the very beginning of Eclipse, it was clear that there was a need for a plug-in that provides base-level resource support on which to build programming language tooling such as compilers, debuggers, versioning, and search. When you look at the services provided by the Resources plug-in, it is obvious that they were added specifically to satisfy these requirements. Following is a small overview of the features provided by this plug-in:

Change notifications—When resources are changed, there is always someone that cares (e.g., UI viewers, builders). The plug-in provides efficient deltas that describe the changes made to a set of resources. This is useful since file notifications are not part of the standard Java class libraries.

Incremental builders—Incremental project builders transform or manipulate resources to produce additional resources. For example, the Java development tools define an incremental project builder that compiles a Java source file into a class file any time a file is added or modified in a Java project. It also keeps track of dependent files and recompiles them when necessary.

Markers—During the course of editing or building a resource, a plug-in may need to tag resources to communicate problems or other information to the user. The resource marker mechanism is used to manage this kind of information. A marker is like a yellow sticky note stuck to a resource. On the marker you can record information about a problem (e.g., location, severity) or a task to be done. Markers can also be used to simply record a location as a bookmark.

Properties—Resources have properties that can be used to store meta-information about a resource. Your plug-in can use these properties to hold application-specific information about a resource. Resource properties are declared, accessed, and maintained by various plug-ins and are not interpreted by the Platform. When a resource is deleted from the workspace, its properties are also deleted.

Derived resources—Many resources get created in the course of translating, compiling, copying, or otherwise processing files that the user creates and edits. Derived resources are resources that are not original data and can be re-created from their source files. It is common for derived files to be excluded from certain kinds of processing. For example, derived resources are typically not kept in a team repository since they clutter the repository, change regularly, and can be re-created from their source files.

The eclipse.org Web site has many examples and articles that explain how to use these features. If you do not need any of these features, just go ahead and use java.io.File instead. Otherwise, the next sections provide a basic introduction to the plug-in.

29.4.2 Getting Started with Resources

The Resources plug-in provides access to resources via a workspace. Imagine the workspace as the container for all resources through which you must pass to access any resource. The snippet below shows how to access the workspace and create a project and file. Projects are the top-level elements in the workspace.

IResources (e.g., IFile, IFolder) objects are handles to state maintained by the workspace. This allows you to access a resource before it exists and at the same time hold on to a resource that has been deleted.

29.4.3 Resources in the Workbench

Prior to Eclipse 3.0, resources were at the heart of the Workbench, and building an application that did not include resources was not possible. When the RCP was created, these dependencies were moved to org.eclipse.ui.ide or the IDE product. The IDE uses the workspace resource model as its underlying data model. The IDE plug-in, and the extensions defined within it, are not designed to be reused in other RCP applications; that is, although it is technically possible to either subclass or reference IDE classes, it is not particularly supported by the generic UI Workbench. So, if you are developing an IDE-style product, you should consider extending the existing IDE application rather than developing your own RCP application.

29.5 Text Editing

If you need to show or edit text in your application, you need the text editing framework. Programming languages have evolved, but the fact remains that developers spend most of their time writing code in a text editor of some sort. Given Eclipse’s origin as an IDE, the text infrastructure included in the platform is very advanced and includes state-of-the-art text editing features.

The breadth of support provided by the text editing framework comes at a price—it’s complex. Basic text editing capabilities are fairly easy to implement, but as soon as you start adding advanced features such as syntax highlighting, content assist, and annotations, you have to invest some time to understand the framework. This section shows you how to add basic text editing to an RCP application.

29.5.1 Text Plug-ins

The text framework is split across several plug-ins to modularize and encapsulate functionality. For example, this allows reuse of the text model without implying a dependency on text presentation. Figure 29-1 shows how these plug-ins are layered and what functionality is included in each plug-in.

Figure 29-1 Overview of text-related plug-ins

Support for IResource text editing is provided by the org.eclipse.ui.editors plug-in and is tightly coupled to the Eclipse IDE product. As such, it is not part of the RCP. There are, however, many pieces of the text infrastructure that are available for use in RCP applications. The remainder of this section demonstrates how to integrate text editing support into an RCP application.

29.5.2 Editing versus Editor

The text framework can be used to implement a full-featured programming language editor and can also be used to allow editing of text in a dialog or show output for a console.

Given its architecture, you can use org.eclipse.text to manipulate text without a presentation. The org.eclipse.jface.text plug-in provides the link between the model (IDocument) and the view (StyledText) via the TextViewer. The coupling to the Workbench, in particular to editors, is provided by the org.eclipse.ui.workbench.texteditor plug-in with the addition of an AbstractTextEditor.

As a developer of an RCP application, you can pick and choose the text features you need from the framework.

29.5.3 Text and StyledText

The simplest way to either show or allow editing of text is to use the SWT Text control. This is a native control that is good enough for many simple editing requirements. The SWT custom control called StyledText is a step up from the Text control. It is a subclass of Canvas and allows editing of text, changing the font and colors of text regions, and changing the cursor. Because it is a Canvas, clients can draw directly on the widget and extend the presentation of the text. For example, a common pattern is to add a line styler to StyledText to show syntax highlighting.

If all you require is a rich edit control, using StyledText is good enough. You can embed the control in dialogs or views—and bingo! You have rich edit capabilities. If you want more bells and whistles such as content assist, hyperlinks, overview, and outline rulers, the Text plug-ins are what you need.

29.5.4 IDocument

Manipulating text is error-prone and difficult; you have to manage lines, indexes, wrapping, and many other details to keep the text correct. IDocument is a text model designed to help with manipulating text and, in some cases, with storing text so it can be presented. For example, documents can be partitioned into disjointed parts by using token- and rule-based filters. Partitions are useful for syntax highlighting and are stored with a document to avoid having to maintain additional data structures. Think of an IDocument as a java.util.StringBuffer on steroids.

29.5.5 TextViewers and TextEditors

The next step up from using SWT controls to display text is using the TextViewer classes in org.eclipse.jface.text. A TextViewer connects a StyledText control with an IDocument model, and a TextEditor provides support for displaying a TextViewer in an editor. This sounds simple, but many details are being taken care of for you by the viewer and editor.

Below is a quick example of how to provide a simple text editor. Here we create a concrete implementation of AbstractTextEditor and a concrete IDocumentProvider. The document provider connects the document to the editor and allows sharing of documents between editors. Figure 29-2 shows how this works in more general terms.

Figure 29-2 Relationships among key text classes

AbstractTextEditor provides most of the features you need from a basic editor. As a result, our simple text editor implementation only needs to hook the document provider to the editor.

The SimpleDocumentProvider handles reading and saving the file. When the editor is opened, it is provided with an IEditorInput that describes the file to be opened. The editor delegates the task of manipulating the bytes in the file to the document provider. Your main coding job is to provide implementations of the following methods for the document provider:

createDocument()— loads the file from disk and creates the IDocument with the contents of the file

doSaveDocument()— saves the file to disk

isModifiable()— decides if the user can edit the file

isReadOnly()— decides if the document is going to be able to be saved

29.5.6 What Is Missing?

Because org.eclipse.ui.editors is not part of RCP, there are some features that are not available to RCP applications. For example, the most feature-filled editor is AbstractDecoratedTextEditor. It supports line numbers, change ruler, overview ruler, print margins, and current line highlighting.

In addition, the UI Editors plug-in contains IResource editing support. As a result, there is no easy way of editing an IFile without creating your own specific document provider. Have a look at FileDocumentProvider for hints if you need to implement IResource-aware editors.

The sample code for this chapter includes an example text editor. You can see it in action by opening an XML file or text file using Hyperbola > Open File....

29.6 Consoles

Consoles are traditionally used to display raw output from a running program and also accept keyboard commands. They are also very common in IDEs. Instead of having each plug-in define its own Console views, the Console plug-in provides a single view into which other plug-ins can contribute their consoles. This makes it much easier for users to find consoles—all they have to do is open one view, and from there they can easily toggle between the available consoles.

The Console plug-in also provides many helpful classes for creating consoles. For example, in Chapter 16, “Perspectives, Views, and Editors,” we showed how simple it is to add an XMPP messaging console to Hyperbola. The plug-in also provides many features useful in writing text consoles, for example, hyperlinking and text coloring. To find out more about the console, see the example in Chapter 16 and look at org.eclipse.ui.console.TextConsole and the extension points provided by the Console plug-in.

29.7 Variables

This plug-in provides classes and interfaces to support the definition and contribution of variables for the purpose of string substitution. It supports the recursive replacement of variables referenced by name in arbitrary strings with the value of the variable. Two types of variables are provided: value variables (IValueVariable) and dynamic variables (IDynamicVariable).

A value variable has a simple setter and getter for its value. A dynamic variable has an associated resolver that provides a variable’s value each time it is referenced (replaced) in a string substitution. A dynamic variable may also provide an argument in its reference, which can be used by its resolver to determine its substitution value.

A variable manager (IStringVariableManager) is provided to manage the set of defined variables. Value variables may be created via API on the variable manager or contributed via the valueVariables extension point. Dynamic variables must be contributed via the dynamicVariables extension point.

The variable manager provides change notification for value variables and an API for performing string substitution. Substitution simply takes a string containing variable patterns and returns that string with all the variables replaced by their associated variable values.

Variables are referenced in strings by enclosing them in braces, preceded by a dollar sign. For example, abc${foo}ghi is composed of the strings abc and ghi sandwiching the variable foo. If the value of foo is def, string substitution gives abcdefghi.

In the case of dynamic variables, an optional argument is supplied by appending a colon and argument value after the variable name, for example, ${foo:bar}. In this case the resolver associated with foo is given the referenced argument, bar, when asked to resolve a value for the variable foo.

29.8 Outline and Property Views

The Outline and Property views are not included in the RCP, but you can easily include them in your application by adding the org.eclipse.ui.views plug-in to your target.

To use the Property or Outline view, add the views to a perspective using the usual IPageLayout.addView() or IPageLayout.addStandaloneView() methods, or open them programmatically using IWorkbenchPage.showView(). The view IDs for both are found on IPageLayout, even though the views are not part of the Workbench. This is historical. Before RCP, they were part of the IDE Workbench. For backward-compatibility reasons, they were left there.

Both views are interesting because they work by supporting the active editor and switch their content as the editor is changed. They do this by listening to part changes, and they query the active part to see if they have anything to contribute to the outline or property views.

29.9 Forms

If you’ve opened a plugin.xml file using the plug-in manifest editor, you’ve seen the Forms plug-in in action. The Forms plug-in provides Web-like UIs by modestly extending SWT to manipulate style bits, colors, fonts, and other properties to get the desired look and feel. It’s actually become a standard to use forms in editors that display and allow editing of structured data.

The Eclipse Forms classes handle many of the SWT details needed to write nice-looking and well-behaved editors. For example, the FormToolKit widget factory is responsible for creating form-friendly SWT controls for use in custom form layouts that handle wrapping and scrolling for you.

29.10 Browser

The Browser plug-in and the Workbench’s browser APIs and extension point provide all you need to open a URL in either an internal or an external Web browser. Although the Workbench provides the generic APIs, such as IWorkbenchBrowser.createBrowser(String), the Browser plug-in provides the implementation for this by extending the org.eclipse.ui.browserSupport extension point.

To use the Browser plug-in, simply add it to your target and then access the Workbench’s browser support via IWorkbench.getBrowserSupport(). From the returned IWorkbenchBrowser you can call createBrowser(String) to get the default browser IWebBrowser reference. You can then call IWebBrowser.openURL(URL) to open a Web page. The Browser plug-in contributes a preference page that allows the user to configure the browser to use to show Web pages.

29.11 The Common Navigator Framework

A typical JFace viewer like the Hyperbola group viewer provides the user with a view of objects using a single content provider, label provider, sorter, and filter. The Common Navigator Framework (CNF) extends this idea by allowing a single view to dynamically use multiple and unrelated sets of content providers, label providers, sorters, and filters. These can be activated in the view depending on declarative expressions or using API calls.

The CNF uses the idea of Navigator Content Extensions (NCE) which can refer to a content provider, label provider, sorter, or drag adapter (note that filters are configured separately). An NCE has associated expressions that tell it when it is active. NCEs are also presented to users in the view context menu so that they can turn them on or off in order to show the view in different ways. Examples of NCEs are a resource content extension that controls how resources are presented and a Java content extension that shows Java projects. In the IDE’s Project Explorer, you can turn off the Java content extension to get a pure resource view of the workspace.

Check out the Platform Plug-in Developer’s Guide > Programmer’s Guide > Common Navigator Framework for more detailed information on how to use the CNF in your application.

29.12 Declarative Services

In Chapter 14 we needed to access some OSGi services like the IProfileRegistry in order to work with the p2 API and add software management support to Hyperbola. To access these services, we used the BundleContext API and some relatively boilerplate code. The org.eclipse.equinox.ds plug-in contains an implementation of the Declarative Services (DS) specification that’s part of the standard OSGi compendium services.

DS allows you to declaratively wire OSGi services together across plug-ins. Using DS, you can specify what services your plug-in provides and what services are required. This is all specified using XML, and the org.eclipse.equinox.ds plug-in is responsible for wiring everything together. We highly recommend using DS if interacting with OSGi services.

29.13 Summary

Here we have seen just a taste of the wide range of plug-ins available from eclipse.org for use in writing RCP applications. There are plug-ins for text manipulation, user assistance, resource management, and so on. Beyond the Eclipse Platform and eclipse.org, the list becomes almost boundless.

The net result is that before writing your function, you should look around for existing plug-ins that you can reuse. When browsing plug-ins, always ensure that the plug-in was designed to be used in other applications. To do this, refer to the rules and guidelines from Section 23.7 for how to determine if a plug-in is RCP-friendly. The corollary to this is that you may also want to contribute some of your plug-ins back to the community for others to use.