Official Eclipse 3.0 Faq - Softcover

Arthorne, John; Laffra, Chris

Softcover

ISBN 10: 0321268385 ISBN 13: 9780321268389

Publisher: Addison-Wesley Professional, 2004

Synopsis

"I had a question about how to use a new Eclipse 3.0 feature, job scheduling, so I thought I would try out this book. I immediately found the answer with a concise explanation. Cool!"

--Erich Gamma

Official Eclipse 3.0 FAQs is the convenient source for answers to your most crucial questions about writing Eclipse plug-ins. Whether you're creating simple extensions for personal use or commercial Eclipse-based applications, you'll find hundreds of concise solutions here--including many that aren't answered anywhere else.

John Arthorne and Chris Laffra have worked with Eclipse technology since the very beginning; both are active members of the Eclipse development community and frequently answer questions on Eclipse newsgroups and mailing lists. Here, they cover an extraordinary range of topics, from workspace management to documentation, SWT to JFace, JDT to natural language support. Many FAQs include code samples and references to other information, making the book an invaluable desk reference for anyone working with Eclipse.

Just a few of the 350+ questions answered here...

• How do I upgrade Eclipse? Page 29
• What is new in Eclipse 3.0? Page 34
• How can I add my views and actions to an existing perspective? Page 187
• How do I set up a Java project to share in a repository? Page 58
• How do I declare my own extension point? Page 74
• How do I display a Web page in SWT? Page 141
• How do I support multiple natural languages in my plug-in messages? Page 253
• How do I save settings for a dialog or wizard? Page 166
• How do I provide syntax coloring in an editor? Page 269
• How do I hook into global actions, such as Copy and Delete? Page 225
• How do I create a Rich Client application? Page 241
• What is the purpose of activities? Page 229
• How do I create and examine an AST? Page 369

About this title

About the Author

John Arthorne has been a committer on the Eclipse project since its inception, and has worked on Eclipse's underlying technology since 1998. Before joining IBM Ottawa Lab in Ottawa, Canada, he worked for IBM subsidiary Object Technology International, developing Eclipse's precursor, VisualAge Micro Edition Java IDE.

Chris Laffra works with the J9 virtual machine team at IBM Ottawa Lab. He focuses on improving Eclipse's overall performance, and his hobby is visualization of Eclipse's execution to improve its transparency. Chris previously worked for IBM T.J. Watson Research Center and OTI in Amsterdam.

Excerpt. © Reprinted by permission. All rights reserved.

Most of the numerous Eclipse books published over the course of 2003 and 2004 cater directly to novel users and/or starting contributors to the platform. Other books have a particular focus on a specific vertical domain, such as modeling, or on a special niche, such as the underlying design principles of the platform.

This book has been carefully sculpted to fit a particular niche market of its own: Eclipse enhancers with at least some experience in writing Eclipse plug-ins. Our goal was to make this book the definitive guide to the wealth of other relevant Eclipse books, online articles, newsgroups with thousands of messages, mailing lists, and other random sources of Eclipse information, such as wikis and online FAQ lists.

A Brief Exploration of FAQs

An FAQ is a Frequently Asked Question. We pronounce the acronym FAQ as it is spelled: FAQ. 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.

The Target Audience for This Book

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).

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.

The Eclipse Versions These FAQs Cover

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 pre3.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).

How to Read This Book

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

• A question in the form an Eclipse developer would pose it
• A concise, to-the-point answer
• References to other FAQs, articles, and books

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.

Online Updates to This FAQ

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.

How This Book Was Written

"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:

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 softcopy version of the FAQ and a hardcopy 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.

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.

Spider Diagrams

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.

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.

Conventions Used in This Book

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 a "hand" 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.

The Origin of the Questions

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

• Eclipse newsgroups (http://eclipse.org/newsgroups)
• The eclipse.org articles (http://eclipse.org/articles)
• Eclipse developer mailing lists (http://eclipse.org/mail)
• Interesting discussions in the descriptions of many Eclipse bugs
• Feedback from Eclipse code camps and developer conferences such as EclipseCon Personal discussions with Eclipse committers
• Varying other sources of Eclipse information (http://eclipse.org/community/main.html)
• Our own personal experience with development of Eclipse

Structure of This Book

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 standalone 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 develo...

About this edition

• Publisher: Addison-Wesley Professional
• Publication date: 2004
• ISBN 10: 0321268385
• ISBN 13: 9780321268389
• Binding: Paperback
• Edition number: 1
• Number of pages: 386