"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!"
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...
Download the Sample
Chapter related to this title.
Foreword. Preface. Acknowledgments.
I. THE ECLIPSE ECOSYSTEM.
1. The Eclipse Community.
What is Eclipse?
What is the Eclipse Platform?
Where did Eclipse come from?
What is the Eclipse Foundation?
How can my users tell where Eclipse ends and a product starts?
What are Eclipse projects and technologies?
How do I propose my own project?
Who is building commercial products based on Eclipse?
What open source projects are based on Eclipse?
What academic research projects are based on Eclipse?
Who uses Eclipse in the classroom?
What is an Eclipse Innovation Grant?
What Eclipse newsgroups are available?
How do I get access to Eclipse newsgroups?
What Eclipse mailing lists are available?
What articles on Eclipse have been written?
What books have been written on Eclipse?
How do I report a bug in Eclipse?
How can I search the existing list of bugs in Eclipse?
What do I do if my feature request is ignored?
Can I get my documentation in PDF form, please?
Where do I find documentation for a given extension point?
How is Eclipse licensed?
2. Getting Started.
Where do I get and install Eclipse?
How do I run Eclipse?
How do I increase the heap size available to Eclipse?
Where can I find that elusive .log file?
Does Eclipse run on any Linux distribution?
I unzipped Eclipse, but it won't start. Why?
How do I upgrade Eclipse?
How do I install new plug-ins?
Can I install plug-ins outside the main install directory?
How do I remove a plug-in?
How do I find out what plug-ins have been installed?
Where do I get help?
How do I accommodate project layouts that don't fit the Eclipse model?
What is new in Eclipse 30?
Is Eclipse 30 going to break all of my old plug-ins?
How do I prevent my plug-in from being broken when I update Eclipse?
3. Java Development in Eclipse.
How do I show/hide files like .classpath in the Navigator?
How do I link the Navigator with the currently active editor?
How do I use the keyboard to traverse between editors?
How can I rearrange Eclipse views and editors?
Why doesn't my program start when I click the Run button?
How do I turn off autobuilding of Java code?
How do I hide referenced libraries in the Package Explorer?
Where do my .class files disappear to?
What editor keyboard shortcuts are available?
How do I stop the Java editor from showing a single method at once?
How do I open a type in a Java editor?
How do I control the Java formatter?
How do I choose my own compiler?
What Java refactoring support is available?
How can Content Assist make me the fastest coder ever?
How can templates make me the fastest coder ever?
What is a Quick Fix?
How do I profile my Java program?
How do I debug my Java program?
How do I find out the command-line arguments of a launched program?
What is hot code replace?
How do I set a conditional breakpoint?
How do I find all Java methods that return a String?
What can I view in the Hierarchy view?
How do I add an extra library to my project's classpath?
What is the advantage of sharing the .project file in a repository?
What is the function of the .cvsignore file?
How do I set up a Java project to share in a repository?
Why does the Eclipse compiler create a different serialVersionUID from javac?
4. Plug-in Development Environment.
How do I create a plug-in?
How do I use the plug-in Manifest Editor?
Why doesn't my plug-in build correctly?
How do I run my plug-in in another instance of Eclipse?
What causes my plug-in to build but not to load in a runtime workbench?
My runtime workbench runs, but my plug-in does not show. Why?
How do I add images and other resources to a runtime JAR file?
Can I add icons declared by my plug-in.xml in the runtime JAR?
When does PDE change a plug-in's Java build path?
What is a PDE JUnit test?
Where can I find the Eclipse plug-ins?
How do I find a particular class from an Eclipse plug-in?
Why do I get a "plug-in was unable to load class" error when I activate a menu or toolbar action?
What is the use of the build.xml file?
How do I prevent my build.xml file from being overwritten?
When is the build.xml script executed?
How do I declare my own extension point?74
How do I find all the plug-ins that contribute to my extension point?
Why is the interface for my new extension point not visible?
Can my extension point schema contain nested elements?
How do I create a feature?
How do I synchronize versions between a feature and its plug-in(s)?
What is the Update Manager?
How do I create an update site (site.xml)?
Why does my update site need a license?
II. THE RICH CLIENT PLATFORM.
5. All about Plug-ins.
What is a plug-in?
Do I use plug-in or plug-in?
What is the plug-in manifest file (plug-in.xml)?
How do I make my plug-in connect to other plug-ins?
What are extensions and extension points?
What is an extension point schema?
How do I find out more about a certain extension point?
When does a plug-in get started?
Where do plug-ins store their state?
How do I find out the install location of a plug-in?
What is the classpath of a plug-in?
How do I add a library to the classpath of a plug-in?
How can I share a JAR among various plug-ins?
How do I use the context class loader in Eclipse?
Why doesn't Eclipse play well with Xerces?
What is a plug-in fragment?
Can fragments be used to patch a plug-in?
What is a configuration?
How do I find out whether the Eclipse Platform is running?
Where does System.out and System.err output go?
How do I locate the owner plug-in
from a given class?
How does OSGi and the new runtime affect me?
What is a dynamic plug-in?
How do I make my plug-in dynamic enabled?
How do I make my plug-in dynamic aware?
6. Runtime Facilities.
How do I use progress monitors?
How do I use a SubProgressMonitor?
How do I use the platform logging facility?
How do I use the platform debug tracing facility?
How do I load and save plug-in preferences?
How do I use the preference service?
What is a preference scope?
How do I use IAdaptable and IAdapterFactory?
Does the platform have support for concurrency?
How do I prevent two jobs from running at the same time?
What is the purpose of job families?
How do I find out whether a particular job is running?
How can I track the lifecycle of jobs?
How do I create a repeating background task?
7. Standard Widget Toolkit (SWT).
What is SWT?
Why does Eclipse use SWT?
Is SWT platformspecific?
Is SWT better than Swing?
Can I use SWT outside Eclipse for my own project?
Are there any visual composition editors available for SWT?
Why do I have to dispose of colors, fonts, and images?
Why do I get an invalid thread access exception?
How do I get a Display instance?
How do I prompt the user to select a file or a directory?
How do I display a Web page in SWT?
How do I embed AWT and Swing inside SWT?
Where can I find more information on SWT?
What is a viewer?
What are content and label providers?
What kinds of viewers does JFace provide?
Why should I use a viewer?
How do I sort the contents of a viewer?
How do I filter the contents of a viewer?
How do I use properties to optimize a viewer?
What is a label decorator?
How do I use image and font registries?
What is a wizard?
How do I specify the order of pages in a wizard?
How can I reuse wizard pages in more than one wizard?
Can I reuse wizards from other plug-ins?160
How do I make my wizard appear in the UI?
How do I run a lengthy process in a wizard?
How do I launch the preference page that belongs to my plug-in?
How do I ask a simple yes or no question?
How do I inform the user of a problem?
How do I create a dialog with a details area?
How do I set the title of a custom dialog?165
How do I save settings for a dialog or wizard?
9. Generic Workbench.
Pages, parts, sites, windows: What is all this stuff?
How do I find out what object is selected?
How do I find out what view or editor is selected?
How do I find the active workbench page?
How do I show progress on the workbench status line?
Why should I use the new progress service?
How do I write a message to the workbench status line?
How do I create a label decorator declaratively?
How do I add label decorations to my viewer?
How do I make the workbench shutdown?
How can I use IWorkbenchAdapter to display my model elements? 176
How do I create my own preference page?
How do I use property pages?
How do I open a Property dialog?
How do I add my wizard to the New, Import, or Export menu categories?
Can I activate my plug-in when the workbench starts?
How do I create an image registry for my plug-in?
How do I use images defined by other plug-ins?
How do I show progress for things happening in the background?
How do I switch from using a Progress dialog to the Progress view?
Can I make a job run in the UI thread?
Are there any special Eclipse UI guidelines?
Why do the names of some interfaces end with the digit 2?
10. Perspectives and Views.
How do I create a new perspective?
How can I add my views and actions to an existing perspective?
How do I show a given perspective?
What is the difference between a perspective and a workbench page?
How do I create fixed views and perspectives?
What is a view?
What is the difference between a view and a viewer?
How do I create my own view?
How do I set the size or position of my view?
Why can't I control when, where, and how my view is presented?
How will my view show up in the Show View menu?
How do I make my view appear in the Show In menu?
How do I add actions to a view's menu and toolbar?
How do I make a view respond to selection changes in another view?
How does a view persist its state between sessions?
How do I open multiple instances of the same view?
11. Generic Editors.
What is the difference between a view and an editor?
How do I open an editor programmatically?
How do I open an external editor?
How do I dynamically register an editor to handle a given extension?
How do I switch to vi or emacs-style key bindings?
How do I create my own editor?
How do I enable the Save and Revert actions?
How do I enable global actions such as Cut, Paste, and Print in my editor?
How do I hook my editor to the Back and Forward buttons?
How do I create a form-based editor, such as the plug-in Manifest Editor?
How do I create a graphical editor?
How do I make an editor that contains another editor?
12. Actions, Commands, and Activities.
Actions, commands, operations, jobs: What does it all mean?
What is an action set?
How do I make my action set visible?
How do I add actions to the global toolbar?
How do I add menus to the main menu?
How do I add actions to the main menu?
Why are some actions activated without a target?
Where can I find a list of existing action group names?
What is the difference between a command and an action?
How do I associate an action with a command?
How do I create my own keybinding configuration?
How do I provide a keyboard shortcut for my action?
How can I change the name or tooltip of my action?
How do I hook into global actions, such as Copy and Delete?
How do I build menus and toolbars programmatically?
How do I make menus with dynamic contents?
What is the difference between a toolbar and a cool bar?
Can other plug-ins add actions to my part's context menu?
How do I add other plug-ins' actions to my menus?
What is the purpose of activities?
How do I add activities to my plug-in?
How do activities get enabled?
What is the difference between perspectives and activities?
13. Building Your Own Application.
What is an Eclipse application?
How do I create an application?
What is the minimal Eclipse configuration?
How do I create a Rich Client application?
How do I customize the menus in an RCP application?
How do I make key bindings work in an RCP application?
Can I create an application that doesn't have views or editors?
How do I specify where application data is stored?
Can I create an application that doesn't have a data
14. Productizing an Eclipse Offering.
What is an Eclipse product?
What is the difference between a product and an application?
How do I distribute my Eclipse offering?250
Can I use an installation program to distribute my Eclipse product?251
Can I install my product as an add-on to another product?
Where do I find suitable Eclipse logos and wordmarks?
When do I need to write a plug-in install handler?
How do I support multiple natural languages in my plug-in messages?
How do I replace the Eclipse workbench window icon with my own?254
How do I write my own eclipse.exe platform launcher?
Who shows the Eclipse splash screen?
How can I publish partial upgrades (patches) to my product?
III. THE ECLIPSE IDE PLATFORM.
15. Text Editors.
What support is there for creating custom text editors?
I'm still confused! How do all the editor pieces fit together?
How do I get started with creating a custom text editor?
How do I use the text document model?
What is a document partition?
How do I add Content Assist to my editor?
How do I provide syntax coloring in an editor?
How do I support formatting in my editor?
How do I insert text in the active text editor?
What is the difference between highlight range and selection?
How do I change the selection on a double-click in my editor?
How do I use a model reconciler?
16. Help, Search, and Compare.
How do I add help content to my plug-in?
How do I provide F1 help?
How do I contribute help contexts?
How can I generate HTML and toc.xml files?
How do I write a Search dialog?
How do I implement a search operation?281
How do I display search results?
How can I use and extend the compare infrastructure?
How do I create a Compare dialog?
How do I create a compare editor?
17. Workspace and Resources API.
How are resources created?
Can I create resources that don't reside in the file system?
What is the difference between a path and a location?
When should I use refreshLocal?
How do I create my own tasks, problems, bookmarks, and so on?
How can I be notified of changes to the workspace?
How do I prevent builds between multiple changes to the workspace?
Why should I add my own project nature?
Where can I find information about writing builders?
How do I store extra properties on a resource?
How can I be notified on property changes on a resource?
How and when do I save the workspace?300
How can I be notified when the workspace is being saved?
Where is the workspace local history stored?
How can I repair a workspace that is broken?
What support does the workspace have for team tools?
18. Workbench IDE.
How do I open an editor on a file in the workspace?
How do I open an editor on a file outside the workspace?
How do I open an editor on something that is not a file?
Why don't my markers show up in the Tasks view?
Why don't my markers appear in the editor's vertical ruler?
How do I access the active project?
What are IWorkspaceRunnable, IRunnableWithProgress, and WorkspaceModifyOperation?
How do I write to the console from a plug-in?
How do I prompt the user to select a resource?
Can I use the actions from the Navigator in my own plug-in?.
What APIs exist for integrating repository clients into Eclipse?315
How do I deploy projects to a server and keep the two synchronized?
What is the difference between a repository provider and a team
What is a launch configuration?
When do I use a launch delegate?
What is Ant?
Why can't my Ant build find javac?
How do I add my own external tools?
How do I create an external tool builder?320
19. Implementing Support for Your Own Language.
What is eScript?
Language integration phase 1: How do I compile and build programs?
How do I load source files edited outside Eclipse?
How do I run an external builder on my source files?
How do I implement a compiler that runs inside Eclipse?
How do I react to changes in source files?
How do I implement an Eclipse builder?
Where are project build specifications stored?
How do I add a builder to a given project?
How do I implement an incremental project builder?
How do I handle setup problems for a given builder?
How do I make my compiler incremental?
Language integration phase 2: How do I implement a DOM?
How do I implement a DOM for my language?
How can I ensure that my model is scalable?
Language integration phase 3: How do I edit programs?
How do I write an editor for my own language?
How do I add Content Assist to my language editor?
How do I add hover support to my text editor?
How do I create problem markers for my compiler?
How do I implement Quick Fixes for my own language?
How do I support refactoring for my own language?
How do I create an Outline view for my own language editor?
Language integration phase 4: What are the finishing touches?354
What wizards do I define for my own language?
When does my language need its own nature?
When does my language need its own perspective?
How do I add documentation and help for my own language?
How do I support source-level debugging for my own language?
20. Java Development Tool API.
How do I extend the JDT?
What is the Java model?
How do I create Java elements?
How do I create a Java project?
How do I manipulate Java code?
What is a working copy?
What is a JDOM?
What is an AST?
How do I create and examine an AST?
How do I distinguish between internal and external JARs on the build path?
How do I launch a Java program?
What is JUnit?
How do I participate in a refactoring?
What is LTK?
As Chris and John describe later in this book, the Eclipse Project began in 1999 at IBM's Object Technology International (OTI) subsidiary. At the time I was CEO and president of OTI and so was very involved in the decision to proceed with Eclipse, which was initially conceived as a successor product to the VisualAge family of software development tools. VisualAge, especially VisualAge for Java, was a commercially successful IDE. But it was also a closed environment built on proprietary APIs and did not integrate well with other vendors' tools. Only the IBM/OTI team could enhance or extend the product. Beyond these issues, though, it was becoming apparent from customer feedback that more was required than a simple rewrite of VisualAge. There was growing demand for a tool integration platform--a programming environment that would not only provide kernel IDE functionality but also allow developers, third-party vendors, and users to seamlessly add their own extensions, personalizations, and enhancements.
The vision of the Eclipse Project team was to extract the essential infrastructure underlying VisualAge--or any other IDE for that matter--and to package and deliver it as a platform. In effect, the team wanted to strip out all the IDE functionality that was specific to a particular programming language, development task, or programming model. The hope was that there would be substantial residual function left behind that could then be restructured to form a content-neutral and programming language-neutral foundation on which IDEs and similar products could be built from components. It was a bold venture, as there was no guarantee that anything practically useful would result, and there was certainly a lot of soul-searching and hand-wringing in the early days of the project.
The result was Eclipse: a tool-integration platform together with a set of components--"plug-ins" in the Eclipse vernacular--that could be seamlessly assembled into a wide variety of software development products. The Java development tools (JDT)--the Eclipse Java IDE--became our proof-point. It was built in parallel by a separate team, led by Erich Gamma of Design Patterns fame, that operated independently from the Eclipse Platform team. The JDT team had no special privileges; it had to use the same API as any other third-party product and was allowed no "backdoor" access to the Eclipse Platform. The intent was that, despite these constraints, the finished JDT should be indistinguishable from a purpose-built, vertically integrated IDE product like VisualAge. Of course, this goal was in fact realized, the Eclipse Project was a success, and the Eclipse community was born.
In the two years since the Eclipse code base was released into open source by IBM, its growth has been quite stunning, especially for those of us involved at the beginning of the venture. It has without question exceeded our wildest imaginings. Tens of thousands download the Eclipse SDK every week from more than 50 mirror sites around the globe. Thousands of Eclipse plug-ins are now available from open source and commercial suppliers. Software vendors are now shipping several hundred commercial products based on Eclipse. As of June 2004, approximately 50 companies are members of the Eclipse Foundation, which hosts Eclipse open source development. The first Eclipse Developer Conference--EclipseCON 2004--was held in Anaheim in February 2004, with more than 220 companies and organizations and nearly 25 countries represented.
Although I had a very amicable separation from OTI and IBM a couple of years ago, I continue to be actively involved with Eclipse. My main role today is leading the Eclipse Foundation Technology Project, whose mission is to engage the research and academic communities. And, of course, if you want to know more about this, Chris and John have provided a very nice section in the Official Eclipse 3.0 FAQs on this subject. It has been particularly interesting for me to see the uptake of Eclipse within the research community. In retrospect, one could perhaps have anticipated this. Software researchers necessarily build on the work of those who have gone before, and, of course, as time progresses our technology pyramids keep getting higher. Complexity is our nemesis--the low-hanging fruit was picked long ago, and most interesting problems are not simple anymore. Consequently, experimentation usually requires complex infrastructure, "plumbing" as we often call it. Most researchers spend far too much time building, rebuilding, and fixing this plumbing and far too little time developing new ideas. Given the nature of research, there are seldom any applicable standards for such infrastructure; these come only much later, when the research has matured into products. Consequently, researchers up to now have had to live and work in their own vertical towers, sharing their ideas but only infrequently sharing code. Eclipse has fundamentally changed this context, however, by providing a means to create and share that necessary common infrastructure, particularly for investigators in such areas as programming languages, tools, and environments. Researchers can focus more of their time on their real mission--innovation--and much less on the hated plumbing tasks.
So when Chris and John approached me to write this foreword to their new book, I was flattered and pleased to be asked but also, I confess, a bit perplexed. I had known and worked with both for many years at OTI and held both in high regard. I recruited Chris to help us start a new development lab in Amsterdam in the mid1990s. The venture was a great success, and Chris developed into a very fine lab director, despite the usual hurdles and bumps along the way, which probably had a lot to do with the good friendship that developed between us as we worked our way through these. John joined OTI as a coop student and rose through the ranks, as it were, invariably choosing to get down and dirty working in middle- and low-level system code--making compilers work and that sort of thing. So even without seeing their book, I was sure that it would be a worthwhile addition to the Eclipse portfolio. But not having worked closely with either for several years, I was not exactly sure what they were up to or what the book was trying to accomplish.
It was a genuinely pleasant surprise when I looked at it. In my role as the "Eclipse outreach person" for research and academia, I get "How do I do this with Eclipse" questions continually, and I am a long way from being an Eclipse expert. In fact, as Eclipse has grown and become both deeper and broader as a platform, it is probably true that no one is an "Eclipse expert" any more. Official Eclipse 3.0 FAQs immediately struck me as a great idea. For one thing, I can, and do, use it myself. But more important, I hope that it will give the thousands of users and developers who venture into Eclipse for the first time the courage to just dive in and get started, knowing that they have a life jacket to keep them afloat and a compass that will guide them through the experience. For the more experienced hands, I suspect that this book will become a (virtually) well-thumbed desktop reference, there to remind you of all those things you know you know but can't quite recall. For many, it will likely be the plug-in version that they will reference and use most often, although I suspect that a few Luddites are out there, who, like me, on occasion still enjoy the reassurance and tangibility of the printed page.
I also happen to think that the emphasis on the Rich Client Platform will prove to have been prescient. After a few years of experimentation with browser-based applications, there has lately been a resurgence of interest in old fashioned desktop apps--the "fat client" seems to be back but this time in the guise of a tonier, slicker, and more sophisticated "rich client." The rich client has learned some ease-of-use and desktop-management lessons from the Web browser and aims to offer a much better out-of-the-box experience. It remains to be seen how this is all going to play out in the marketplace, but Eclipse seems very well positioned to provide a development platform for this new generation of rich client applications. As we have seen with the research and the academic communities, nothing succeeds quite so well as being in the right place, at the right time, with the right function. So the emphasis that Chris and John have placed on this topic is timely, to say the least.Finally, I have to say that I think the decision to write the book entirely as a plug-in was very bold and very cool. It has a certain self-referential flavor to it which is very appealing to old Smalltalk programmers, such as Chris and John and yours truly. And it provides a very nicely integrated addition to the online documentation already available for Eclipse programmers and users. Whether you are an experienced developer, a newbie, an end user, or simply a curious bystander wondering what this Eclipse excitement is all about, I recommend this book to you. I guarantee that it will be both a good read and a great investment.
Eclipse Foundation Technology Project Lead
Download the Index
file related to this title.