Eclipse Rich Client Platform Designing, Coding, and Packaging Java¿ Applications

by Mcaffer, Jeff; Lemieux, Jean-michel

• ISBN13: 9780321334619
• ISBN10: 0321334612
• Edition: CD
• Format: Paperback
• Copyright: 2005-10-11
• Publisher: Addison-Wesley Professional

Summary

Written by the leaders of the Eclipse RCP project, this is the first and ONLY book on Eclipse Rich Client Platform!

Author Biography

Jeff McAffer leads the Eclipse RCP and Runtime teams and is one of the Eclipse Platform's original architects and committers. Prior to his work at IBM's Ottawa Software Lab, he was a developer at Object Technology International focusing on areas such as distributed/parallel OO computing, expert systems, and meta-level architectures. Jeff holds a Ph.D. from the University of Tokyo.

Jean-Michel Lemieux has been a committer on the Eclipse team and CVS component since its inception. Before joining IBM's Ottawa Software Lab to work on Eclipse, Jean-Michel built real-time SS7 monitoring systems and real-time modeling tools.

© Copyright Pearson Education. All rights reserved.

Table of Contents

Foreword	xix
John Wiegand
Foreword	xxi
Jeff Norris
Acknowledgments	xxv
Preface	xxvii
Part I Introduction	1	(26)
Eclipse as a Rich Client Platform	3	(10)
Eclipse	4	(1)
The Eclipse Rich Client Platform	5	(1)
Eclipse RCP Over the Years	6	(1)
Uses of RCP	7	(5)
IBM Workplace Client Technology™	7	(2)
NASA and Eclipse RCP	9	(3)
Summary	12	(1)
Eclipse RCP Concepts	13	(14)
A Community of Plug-ins	13	(3)
Inside Plug-ins	16	(1)
Putting a System Together	17	(1)
OSGi Framework	18	(1)
The Runtime	19	(3)
Applications	20	(1)
Products	20	(1)
Extension Registry	21	(1)
SWT	22	(1)
JFace	23	(1)
UI Workbench	23	(2)
Contribution-based Extensibility	23	(1)
Perspectives, Views, and Editors	24	(1)
Summary	25	(2)
Part II RCP by Example	27	(186)
Tutorial Introduction	29	(12)
What Is Hyperbola?	29	(2)
The Evolution of Hyperbola	31	(1)
Development Environment Installation	32	(1)
Target Setup	33	(2)
Checkpoint	35	(1)
Sample Code	36	(3)
Moving from Chapter to Chapter	36	(2)
Comparing	38	(1)
Learning by Example	39	(1)
Summary	40	(1)
The Hyperbola Application	41	(20)
Hyperbola Hello World	41	(7)
Tour of the Code	48	(4)
Application	48	(1)
Workbench Advisor	49	(1)
Perspective	50	(1)
Workbench Window Advisor	50	(1)
Action Bar Advisor	51	(1)
Summary	52	(1)
Running and Debugging	52	(7)
Debugging	53	(3)
Launch Configurations	56	(3)
Summary	59	(2)
Starting the Hyperbola Prototype	61	(20)
Continuing from the Shell	62	(1)
Saving Window Location and Size	63	(1)
Adding a Contacts View	63	(5)
Adding the Contacts View to a Perspective	65	(3)
The Chat Model	68	(2)
Filling in the Contacts View	70	(7)
The Contacts View	70	(2)
Content Providers Overview	72	(4)
The Label Provider	76	(1)
Adding Images	77	(3)
Summary	80	(1)
Pointers	80	(1)
Adding Actions	81	(20)
Adding to the Menus and Toolbar	82	(10)
Create Top-Level Menu	82	(3)
Menu Managers	85	(1)
The Add Contact Action	86	(3)
Adding the ``Add Contact'' Action	89	(2)
Customizable Toolbars	91	(1)
Adding to the Status Line	92	(2)
Status Line---A Shared Resource	93	(1)
System Tray Integration	94	(4)
Obtaining a Display	95	(1)
Creating the Tray Item	96	(2)
Summary	98	(1)
Pointers	99	(2)
Adding a Chat Editor	101	(12)
Views and Editors	102	(1)
Defining the Chat Editor	103	(8)
Editor Input	107	(2)
The Chat Action	109	(2)
Checkpoint	111	(1)
Summary	112	(1)
Pointers	112	(1)
Branding Hyperbola	113	(14)
Defining the Hyperbola Product	113	(5)
Window Images	118	(1)
Customizing the Launcher	119	(1)
Splash Screen	120	(2)
About Information	122	(3)
Product About Information	122	(3)
Plug-in About Information	125	(1)
Summary	125	(2)
Packaging Hyperbola	127	(8)
Exporting Hyperbola	127	(4)
Exporting for Other Platforms	131	(2)
Summary	133	(1)
Pointers	133	(2)
Messaging Support	135	(18)
Integrating a Third-Party Library	136	(5)
Bundling Smack	136	(3)
Testing the Bundling	139	(2)
Refactoring the Model	141	(6)
Introduction to Smack	141	(2)
Design Objectives	143	(1)
Deleting Prototype Classes	144	(1)
Adding Chats	145	(2)
Updating the UI	147	(3)
The Content Provider	148	(1)
The Label Provider	149	(1)
Chatting with Eliza	150	(1)
Summary	151	(2)
Adding a Login Dialog	153	(22)
Adding the Login Dialog	153	(7)
Branding the Dialog	157	(3)
Remembering Login Settings	160	(7)
The Basics	160	(3)
Using Preferences	163	(4)
Adding Auto-login Preferences	167	(5)
Creating a Preference Page	168	(1)
Adding the Action	169	(1)
Accessing Preferences	170	(1)
Default Preference Values	171	(1)
Preferences on the Login Dialog	172	(1)
Summary	172	(3)
Adding Key Bindings	175	(10)
Defining Commands	175	(5)
Checkpoint	180	(1)
Adding Key Bindings for Workbench Actions	180	(2)
Key Configurations	182	(1)
Keys Preference Page	183	(1)
Summary	184	(1)
Adding Help	185	(12)
Adding to the Target Platform	185	(2)
Getting Plug-ins	186	(1)
Adding Plug-ins	186	(1)
Getting the Help Plug-ins	187	(1)
Configuring the Help Plug-ins	188	(1)
Add the Help Action	188	(1)
Adding Help Content	189	(4)
Help Content Structure	193	(1)
Infopops or F1 Help	194	(2)
Exporting Plug-ins with Help	196	(1)
Summary	196	(1)
Pointers	196	(1)
Adding Update	197	(16)
Getting Update Plug-ins	197	(1)
Configuring the Update Plug-ins	198	(1)
Defining Features	199	(4)
Branding Features	203	(2)
Adding Update Actions	205	(6)
Updating Hyperbola	206	(2)
Extending Hyperbola	208	(2)
Managing Extensions	210	(1)
Automatic Updates	211	(1)
Summary	212	(1)
Part III The Workbench	213	(112)
Workbench Advisors	215	(20)
What Is an Advisor?	215	(4)
Workbench Lifecycle	217	(2)
WorkbenchAdvisor	219	(7)
Lifecycle API	220	(3)
Exceptions and Idleness API	223	(2)
Configuration API	225	(1)
Workbench Window Advisor	226	(1)
IWorkbench WindowConfigurer	227	(1)
ActionBarAdvisor	227	(1)
IActionBarConfigurer	228	(1)
Workbench Overview	228	(6)
Workbench Extension Point Reference	230	(1)
Actions	231	(1)
Scalability	232	(1)
Contributions	232	(1)
Perspectives	233	(1)
Startup	234	(1)
Summary	234	(1)
Perspectives, Views, and Editors	235	(26)
Perspectives	236	(11)
Adding Perspectives	237	(1)
Adding the Debug Perspective and Console View	238	(2)
IPageLayout Reference	240	(3)
Perspective Bar	243	(1)
Perspective Menu	244	(1)
Programmatic Perspective Control	245	(2)
Views and Editors	247	(7)
Multiple Instances of the Same View	247	(2)
Sticky Views	249	(1)
Showing Contributed Views	250	(1)
View Registry	251	(1)
Connecting Parts Together	251	(3)
Multiple Workbench Windows	254	(1)
Window Navigation Menu	255	(1)
Drag and Drop with Editors	255	(4)
Summary	259	(2)
Actions	261	(30)
Overview	261	(2)
Declarative Actions in Hyperbola	263	(9)
Declarative Actions	264	(1)
Allowing Contribution	265	(2)
Declaring Actions	267	(3)
Context Menus	270	(2)
Standard Workbench Actions	272	(2)
Retargetable Actions	274	(2)
Consolidating Declarative Actions	276	(1)
Toolbar Action Tricks	277	(3)
Showing Images and Text	277	(2)
Adding Controls to the Toolbar	279	(1)
Adding Contributions to the Status Line	280	(1)
Reporting Progress	281	(8)
Non-modal Progress	283	(2)
Progress View	285	(1)
Customizing Progress	286	(1)
Writing a ProgressProvider	287	(2)
Summary	289	(2)
Customizing Workbench Windows	291	(16)
Customization Defined	291	(1)
Customizing a Workbench Window	292	(9)
Example: Hide and Show	295	(1)
FormLayout	295	(2)
Hiding the Toolbar	297	(1)
Adding the Toggle Actions	297	(2)
Quick Search Panel	299	(1)
Checkpoint	300	(1)
Custom Window Shapes	301	(5)
Creating the Shape	302	(2)
Creating the Window	304	(1)
Defining the Window Contents	305	(1)
Summary	306	(1)
Customizing the Presentation of Views and Editors	307	(18)
Presentations	307	(1)
Sample Presentations	308	(2)
The R21 Presentation	309	(1)
Example Presentations	310	(1)
Writing a Presentation	310	(4)
Widget Hierarchy	312	(1)
StackPresentation	313	(1)
Example Presentation	314	(8)
The Presentation Factory	315	(1)
The Stack Presentation	316	(3)
Size and Position	319	(1)
Adding, Selecting, and Removing Parts	319	(3)
Menus	322	(1)
Summary	322	(3)
Part IV Development Processes	325	(120)
Integrating Code Libraries	327	(16)
Plug-ins as JARs	327	(2)
Bundling by Injection	329	(1)
Bundling by Wrapping	330	(2)
Bundling by Reference	332	(2)
Troubleshooting Classloading Problems	334	(8)
Issues with Class.forName( )	335	(4)
Issues with Context Classloaders	339	(2)
Managing JRE Classes	341	(1)
Serialization	342	(1)
Summary	342	(1)
Installing and Updating Plug-ins	343	(12)
Update's Roles	343	(1)
Features	344	(4)
Uses of Features	344	(1)
What Is a Feature?	345	(3)
Creating and Managing Update Sites	348	(3)
Example: Dynamic Content Handling	351	(3)
Summary	354	(1)
Pointers	354	(1)
Dynamic Plug-ins	355	(16)
Making Hyperbola Dynamic	355	(2)
Dynamic Challenges	357	(1)
Dynamic-awareness	357	(9)
Dynamic Extension Scenarios	357	(7)
Object Handling	364	(1)
Bundle Listeners	365	(1)
Dynamic-enablement	366	(3)
Cleaning Up After Yourself	367	(2)
Summary	369	(2)
RCP Everywhere	371	(28)
Sample Code	371	(1)
The Scenario	372	(1)
About the Scenario	372	(1)
Product Configurations	373	(5)
Restructuring Hyperbola	374	(2)
Hyperbola Projects	376	(1)
Project Naming	377	(1)
Why So Many Projects?	378	(1)
Hyperbola Product Configurations	378	(7)
The JFace Configuration	379	(2)
The PDA Configuration	381	(1)
The Extension Configuration (IDE)	381	(1)
The Workbench Configuration	382	(2)
A Hyperbola Kiosk	384	(1)
Code Structure	385	(7)
Hyperbola Layering	385	(1)
Workbench Contributions	386	(2)
Actions	388	(1)
Key Bindings	389	(1)
Views and Editors	389	(1)
Wizards, Preferences, and Property Pages	390	(1)
Optional Dependencies	390	(1)
Icons and Images	391	(1)
Designing a Platform	392	(4)
Extension Points	393	(2)
Extension Factories	395	(1)
Named and Anonymous Extensions	396	(1)
RCP-friendly Plug-ins	396	(1)
Summary	397	(2)
Building Hyperbola	399	(28)
What Is PDE Build?	400	(1)
Plug-in build.properties	401	(2)
Control Properties	401	(2)
Using Custom Build Scripts	403	(1)
Feature build.properties	403	(6)
Identifying and Placing Root Files	403	(2)
The Launcher	405	(2)
config.ini	407	(2)
Setting Up a Hyperbola Builder	409	(6)
build.properties	409	(4)
customTargets.xml	413	(2)
Running the Builder	415	(2)
Building Products	417	(2)
Cross-platform Building	419	(2)
Tweaking the Build	421	(5)
Managing the Base	421	(1)
Fetching from CVS	421	(2)
Fetching the Maps	423	(1)
Auto-substitution of Version Numbers	424	(1)
Qualifying Version Numbers	424	(1)
Controlling the Output Names	425	(1)
Summary	426	(1)
The Last Mile	427	(18)
Archives	427	(1)
Native Installers	428	(1)
Java Web Start (JNLP)	429	(6)
How Java Web Start Works	429	(1)
Hyperbola and Java Web Start	430	(2)
JAR Signing	432	(1)
Exporting for Java Web Start	433	(1)
Building JNLP Manifests	434	(1)
Java Web Start and Update	435	(1)
Update Sites	435	(1)
Initializing the Install	436	(1)
Pre-initialized Configurations	436	(1)
Multi-user Install Scenarios	437	(6)
Shared Installs	438	(1)
Shared Configurations	439	(1)
Multiple Configurations	440	(3)
Summary	443	(1)
Pointers	443	(2)
Part V Reference	445	(50)
OSGi Essentials	447	(32)
OSGi and the Eclipse Runtime	448	(2)
The Shape of Plug-ins	450	(2)
Fragments	452	(4)
Version Numbering	456	(1)
Services	457	(1)
Singletons	458	(1)
Bundle Lifecycle	459	(5)
BundleActivator (Plugin Class)	460	(1)
The Downside of Activators	461	(1)
Uses for Activators	462	(2)
Early Activation	464	(2)
Early Activation Extensions	464	(1)
osgi.bundles	465	(1)
Start Levels	465	(1)
Auto-activation	466	(2)
Classloading	468	(4)
Class Lookup Algorithm	468	(1)
Declaring Imports and Exports	469	(1)
Importing versus Requiring	470	(1)
Optionality	471	(1)
Re-exporting	471	(1)
x-internal and x-friends	471	(1)
Data Areas	472	(3)
Putting It All Together	475	(2)
Summary	477	(2)
Eclipse.org Plug-ins	479	(16)
Where to Find Plug-ins	479	(2)
Eclipse Platform Plug-ins	481	(1)
Product Introduction	481	(1)
Resources	482	(3)
Overview of Resources Key Features	483	(1)
Getting Started with Resources	484	(1)
Resources in the Workbench	485	(1)
Text Editing	485	(4)
Text Plug-ins	485	(1)
Editing versus Editor	486	(1)
Text and StyledText	487	(1)
IDocument	488	(1)
TextViewers and TextEditors	488	(1)
What Is Missing?	489	(1)
Consoles	489	(1)
Variables	490	(1)
Outline and Property Views	491	(1)
Forms	491	(1)
Browser	492	(1)
Summary	492	(3)
Index	495

Excerpts

Preface Preface In many ways, this book is one of the design documents for the Eclipse Rich Client Platform (RCP). It was written during the Eclipse 3.1 development cycle by members of the development team. Its chapters were sometimes written before the related function was even implemented. The exercise of explaining how things work forced upon us the realities of using the mechanisms and concepts that make up the Eclipse RCP. This was not always pleasant. It did, however, give us a unique opportunity to correct the course of the Eclipse RCP. Whenever we came across something that was hard to explain or compli-cated to use, we were able to step back and consider changing Eclipse to make things easier. Often we could, and often we (or, more accurately, the Eclipse Platform team as a whole) did. It is somewhat hard to convey the joyful feeling of deleting a complicated, detailed 10-page set of instructions or explanation and replacing it with just a paragraph detailing a new wizard or facility. On other occasions, we gained key insights that helped us produce a clearer, simpler description of a function. Fixing bugs discovered during this process provided welcome distractions as we were writing, coding, learning, and trying to have real lives all at the same time. We learned an incredible amount about Eclipse as an RCP and trust that you will too. About this Book This book guides you, the would-be RCP developer, through all stages of developing and delivering an example RCP application called Hyperbola, an instant messaging chat client. We develop Hyperbola from a blank workspace into a full-featured, branded RCP application. The choice of the instant messaging domain allowed us to plausibly touch a wide range of RCP issues from building pluggable and dynamically extensible systems to using third-party code libraries to packaging applications for a variety of environments. We cover scenarios ranging from PDAs to kiosks, to standalone desktops, to full integration with the Eclipse IDE. This book enables you to do the same with your applications. Roughly speaking, the book is split in two. The first half, Parts I and II, sets the scene for RCP and presents a tutorial-style guide to building an RCP application. The tutorial incrementally builds Hyperbola into a functioning, branded chat client complete with Help, Update, and other advanced capabilities. The tutorial is written somewhat informally to evoke the feeling that we are there with you, working through the examples and problems. We share some of the pitfalls and mishaps that we experienced while developing the application and writing the tutorial. The second half of the book looks at what it takes to "make it real." It's one thing to write a prototype and quite another to ship a product. Rather than leaving you hanging at the prototype stage, Parts III and IV are composed of chapters that dive into the details required to finish the job--namely, the refining and refactoring of the first prototype, customizing the user interface, and building and delivering products to your customers. This part is written as more of a reference, but it still includes a liberal sprinkling of step-by-step examples and code samples. The goal is to cover most of the major stumbling blocks reported in the community and seen in our own development of professional products. A final part, Part V, is pure reference. It covers the essential aspects of OSGi, the base execution framework for Eclipse, and touches on various functions available in the Eclipse Platform but not covered earlier in the book. Since one book could not possibly cover everything about Eclipse, and there are many existing books that cover Eclipse and plug-in development, we focus on the areas directly related to RCP function, API, and development. Audience This book is targeted at several groups of Java developers. Some Java programming experience is assumed and no attempt is made to introduce Java concepts or syntax. For developers new to the Eclipse RCP, there is information about the origins of the platform, how to get started with the Eclipse IDE, and how to write your first RCP application. Prior experience with Eclipse is helpful, but not necessary. For developers experienced with creating Eclipse plug-ins, the book covers aspects of plug-in development that are unique to RCP development. For example, not only are there special hooks for RCP applications, but RCP applications have additional characteristics such as branding, plug-in building as part of a release engineering process, deployment, and installation to name a few. For experienced Eclipse RCP developers, this book covers new RCP features and functions in Eclipse 3.1 as well as the new tooling that makes designing, coding, and packaging RCP applications easier than ever before. Sample Code Reading this book can be a very hands-on experience. There are ample opportunities for following along and doing the steps yourself as well as writing your own code. The CD that accompanies the book includes code samples for each chapter. Instructions for managing these samples are given in Chapter 3, "Tutorial Introduction," and as needed in the text. In general, all required materials are available on the CD. Note that these materials are also available on the Web from eitherhttp://eclipse.orgorhttp://eclipsercp.org. The CD includes development tooling, targets, and sample code appropriate for several operating systems (OSs), including Windows,®Linux, and Mac OS X. In particular, the following resources are included: a readme.html file with installation and usage instructions. Eclipse 3.1 SDK Eclipse 3.1 RCP SDK Eclipse 3.1 RCP Delta pack code samples for each chapter as needed Java Development Kit (JDK) 1.4.2 for Windows and Linux Conventions The following formatting conventions are used throughout the book: Bold--Used for UI elements such as menu paths (e.g., File > New > Project)and wizard and editor elements. Italics--Used for emphasis and to highlight terminology. Lucida Sans Typewriter--Used for Java code, property names, filepaths, plug-in ids, and the like that are embedded in the text of a paragraph. Lucida Console--Used for Java code samples and XML snippets. Lucida Console Bold- Used to highlight important lines in code samples. Notes and sidebars are used often to highlight information that readers may find interesting or helpful in using or understanding the function being described in the main text. We tried to achieve an effect similar to that of an informal pair-programming experience where you sit down with somebody and get impromptu tips and tricks here and there. Feedback The official Web site for this book ishttp://eclipsercp.org/book. Additional information and errata are available athttp://www.awprofessional.com/ title/0321334612. You can report problems or errors found in the book or CD to the authors at [e-mail]. Suggestions for improvements and feedback are also very welcome. Copyright Pearson Education. All rights reserved.