An FAQ is a Frequently Asked Question. We pronounce the acronym FAQ as it is spelled: F-A-Q. On the Web, FAQ lists are ubiquitous. A Google search on “FAQ” results in 60 million pages, with FAQs topic ranging from early music to Esperanto to fly fishing to Perl to the X Files to XML programming. With an average FAQ size of 27K, this thriving online ecosystem of FAQs represents a whopping 1.6 petabytes of valuable, distilled domain knowledge.

In the more modest context of this book, an FAQ is a question that is frequently asked by Eclipse developers; hence the title of this book. Of course, we mean developers who extend the Eclipse Platform by writing new plug-ins. Developers who write random Java programs and happen to use Eclipse as an integrated development environment will find less guidance.

Naturally, even when considering that “wisdom lies in the question,” a long list simply of questions would be rather depressing; most readers will not instantly know the answers to the majority of the questions. Therefore, this book also includes answers and guides you to even more sources of more detailed information.

Official Eclipse 3.0 FAQs is targeted primarily at software developers interested in writing their own plug-ins to the Eclipse Platform, either for personal use or as part of a professional product. This audience consists of all the categories including and below Configurers (Figure P.1) in the Eclipse contribution pyramid described by Gamma and Beck (2004).

Figure P.1. The Eclipse contribution pyramid

Everyone below the level of Users in this pyramid is somehow involved in creating and using plug-ins to customize their Eclipse environment, or publishing plug-ins for use by the greater community. This book targets all these groups of Eclipse plug-in writers. Rather than focusing on end-user questions, we discuss how Eclipse has been implemented, what techniques are being used, what extension points are published, and what application programming interfaces (API) are available. The goal is to provide an authoritative reference for all plug-in writers: from those writing simple extensions to their environment to those writing complete Eclipse-based applications of their own.

If you are interested only in using Eclipse-based applications as an end-user, an introductory Eclipse book might be more appropriate. No effort is made here to provide an exhaustive reference for Eclipse end-users. We intentionally keep answers brief and as concise as possible. Where appropriate, the included references are intended to provide more explanation when our quick answer is too terse or cryptic. Many projects are supported by the Eclipse Foundation, but this book focuses almost exclusively on the core Eclipse Platform. If you are interested in some of the other projects under the Eclipse umbrella, we highly recommend perusing the other titles in the Addison-Wesley Eclipse Series.

If you have been using Eclipse for a while and have written your first plug-in(s), you might be ready to better integrate them into the platform and iron out the wrinkles and erase the rough edges. In that case, this book will prove an indispensable guide. The questions answered here have been harvested from people who have been asking the very same questions you are facing now. Some of the questions are tough to answer, as we have discovered over the past year of writing.

This book refers to many online Eclipse articles and books and the overwhelmingly large platform documentation. By reading this FAQ book first, we believe that you will save yourself a lot of time in finding the information you are looking for.

Eclipse is a fast-moving target. Every six weeks, a stable build is released with significant new functionality, making it extremely difficult to write a book with the potential to remain relevant for a long time. In this FAQ list, we have chosen version 3.0 of the Eclipse Platform as our primary target. However, our focus is on core concepts and principles that are relevant to most, if not all, versions of the platform. In some cases, a redesign of architecture or API warrants specific answers for different versions of the platform. Major discrepancies between 2.1 and 3.0 are pointed out, and we sometimes give different answers for 2.1 versus 3.0. We generally do not delve into topics that are relevant only to versions of the platform prior to Eclipse 2.1.

However, all the example snippets were tested primarily on the latest 3.0 builds, and you may need to reverse engineer those examples for older versions of the platform. Of course, for some functionality that is new in Eclipse 3.0, no pre-3.0 answer can be given.

A final caveat: This book went into production just after the 3.0M9 milestone build. This build represents a nearly feature-complete preview of what the final Eclipse 3.0 will be. We have covered only material that we are confident will remain correct when the final release goes out the door. With that said, there could be minor discrepancies between the information in this book and the final 3.0 release. We will try to maintain corrections and clarifications on the book’s Web site (http://eclipsefaq.org).

This book consists of 20 chapters in three parts. Each chapter contains a number of FAQs, consisting of

One way to read this FAQ book is to glance over the table of contents, look at a few random FAQs, and use the book primarily as a desk reference. In that case, the included index at the end of the book or an online search engine will be invaluable.

Another way is to read this book from front to back. The chapters have been carefully written so that the next question is closely related to the current one or directly elaborates on a common theme. If you take this route, keep in mind that we have made the somewhat arbitrary distinction between “user questions” (Part I) and “developer questions” (Parts II and III). Of course, every developer is also a user, so we often had difficultly deciding exactly where a question should lie. Does it make sense to explain how a user builds a plug-in before describing exactly what a plug-in is? Novice users may find it necessary to flip back and forth between Part I and the remainder of this book as they grow into the simultaneous roles of “user” and “developer” of the platform.

This FAQ list is found online at this book’s Web site (http://eclipsefaq.org). At that site, you can search and browse FAQs and propose new categories and questions for which the editors of the FAQ list may post answers.

Furthermore, from that Web site, FAQs can be downloaded as an Eclipse plug-in, in the form of Hypertext Markup Language (HTML) files. The plug-in allows for searching with the common Eclipse Help search (through Help > Help Contents...) to efficiently find your way through this FAQ list. Any reference made in an FAQ to other FAQs, documentation, or articles is done through HTML hyperlinks.

“Eat your own dog food” is one of the most important guiding principles the Eclipse development team follows. As soon as possible, Eclipse was used to develop Eclipse itself. It is the most secure way to iron out bugs in the system. If you force yourself to use your own product, you are bound to make sure that it works well. Naturally, we adopted the same style while writing this book.

To write this book in the true Eclipse spirit, we developed a plug-in that extends the following extension point:

<extension point="org.eclipse.help.toc">
   <toc file="toc.xml" primary="true"/>
</extension>

The toc.xml file provides a topical ordering over the large collection of FAQ files. We realized early that we would go through quite a few editing steps before finalizing our ordering. We envisioned changing question titles, ordering in a given section, creating new FAQs, and discarding some others. Moreover, we also wanted to have a lot of FAQ cross-references. Finally, we wanted to offer readers both a soft-copy version of the FAQ and a hard-copy printed version. Being good computer scientists, we decided that we had to build some of our own tooling to ease our work. Of course, we downloaded available open source technology when and where appropriate.

In writing the documentation for Eclipse 2.1, the Eclipse team devoted a lot of energy to managing the integrity of the documentation. Changing a section topic could result in changing a name in various unrelated locations. We decided to write an explorer for the toc.xml file to automate file editing, ordering, renaming, and cross-linking. Figure P.2 shows a screen dump of our Toc.xml Explorer with HTML preview window in action.

Figure P.2. Toc.xml Explorer with HTML preview window

A second problem we faced was our wish for one master source for both the plug-in and book incarnations of the FAQ list. We decided to edit and maintain only the plug-in version and to generate the book from the plug-in with an automated script. For this conversion, we used HTMLDOC, a great tool for generating a Portable Document Format (PDF) version of a book from a set of input HTML files. This results in the best control over the printed end result. We also developed some rudimentary Eclipse support for HTMLDOC to allow automatic generation of camera-ready manuscripts from any plug-in containing a toc.xml file.

While we were at it, we also wrote an Eclipse HTML editor with basic code assist and syntax highlighting. Finally, we wrote a number of sample Eclipse plug-ins that are available from the book’s Web site and on the book’s CD-ROM.

To generate diagrams of relevant Eclipse object structures, we used enhanced Spider diagrams. Spider diagrams were introduced by Erich Gamma and Kent Beck to illustrate complex object relationships. The Spider plug-in is a graphical object explorer. It shows objects as nodes in a graph. References between objects appear as arcs. The Spider plug-in is licensed under the Common Public License (CPL) and can be downloaded from the Spider Web site (http://www.javaspider.org).

For this book, we downloaded Spider and enhanced it only slightly to improve its visual appearance for printed matter and added support for exporting a graph to a bitmap image on the file system.

Figure P.3 shows a sample Spider graph containing an instance of class WelcomeEditor. When the method called getTitle() is invoked on it, the string “Welcome” is returned. The getItems() method returns an array with six WelcomeItems. Of the six, items 0, 2, and 5 are shown in Figure P.3. When getEditorSite is called on the WelcomeEditor object, an instance of EditorSite is returned. One of its methods, getActionBars(), returns an instance of EditorActionBars. Two of its fields—active and enabledAllowed—have a value equal to true and the refCount field has a value of 3.

Figure P.3. A Spider graph

Unlike Unified Modeling Language (UML) diagrams, Spider diagrams show a reference graph of live objects and their values. Spider diagrams are derived from the actual object model of a live, running Eclipse instance. Java reflection is used to inspect objects and obtain symbolic information.

Throughout this book, we use italics for emphasis, FAQ titles, special terms, and book titles. We use code font for code fragments, file names, class names, method and field names, strings, and objects. We use bold font for menu paths, key names, and perspective and view names.

Optionally, an FAQ is followed by a list of related FAQs, book references, or URLs for related Web sites. Such a section is highlighted by having the following image in the text margin:

The table of contents mentions both FAQ numbers and the page on which the FAQ can be found. For brevity, the index at the end of the book only refers to the FAQ number.

We collected good questions from various sources and then wrote our own answers:

Part I (Chapter 1-4) discusses the organizational structure of the Eclipse Project and lays the fundaments for plug-in development. It explains where to download Eclipse, how to extend the platform by writing a plug-in, and how to use the Eclipse development environment to edit Java code. After reading Part I, you should become comfortably familiar with the strengths and abilities of the Eclipse Platform.

Part II (Chapters 5-14) describes Eclipse as a generic application platform, the so-called Rich Client Platform (RCP), with which stand-alone applications other than development tools can be built. The Eclipse plug-in architecture allows software developers to grow an application by picking and choosing the plug-ins they need to meet their goals. This has proven a godsend for the development tooling domain, which was previously dominated by monolithic products that were nearly impossible to customize and that rarely interoperated with each other.

Along the way, the Eclipse community took an unexpected left turn. While the Eclipse Foundation is still dedicated primarily to tool development, many members of the open source community around Eclipse started to see things differently and began to use the Eclipse Platform to build things other than development tools. They built games, chat clients, and news readers, and consulting companies started building all sorts of custom applications on top of the Eclipse Platform. They realized that a component-based platform with a vast store of open source components already available was ideal for rapidly creating all kinds of applications. Part II will still be interesting for development tool writers, since a great deal of the Eclipse Platform’s functionality has been pushed down into this generic layer.

Part III (Chapter 15-20) discusses the Eclipse IDE Platform and will be of interest to those who want to enhance the Eclipse IDE with new behavior. These chapters cover FAQs relating to the broad assortment of plug-ins that round out the Eclipse SDK and include a chapter on extending the Java development tool (JDT) plug-ins, as well as a large chapter that guides you along the various steps of writing an IDE for your own programming language. Many of the plug-ins that make up the Eclipse IDE Platform, such as those providing text-editing functionality, search and compare support, and even repository support, may be interesting for RCP applications.

Note

Erich Gamma and Kent Beck, Contributing to Eclipse (Addison-Wesley, 2004)

The Eclipse FAQ Web site (http://eclipsefaq.org)

HTMLDOC (http://www.easysw.com/htmldoc)

The Spider Web site (http://www.javaspider.org)