Mo 4 January 22 th -26 th, 2007, Munich/Germany Eclipse Rich Client Platform Kai Tödter Karsten Becker et al. Organized by: Lindlaustr. 2c, 53842 Troisdorf, Tel.: +49 (0)2241 2341-100, Fax.: +49 (0)2241 2341-199 www.oopconference.com
Eclipse Rich Client Platform Tutorial Kai Tödter Siemens AG CT SE 2 kai.toedter@siemens.com Download tutorial material at: www.toedter.com/download/mp3m-3.2.1-20060929-src.zip Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion -1- -2-
Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion -3- Eclipse Distributions Not in scale All packages include source and doc RCP Runtime Binary => 9 MB SWT (2 MB) RCP SDK (17 MB) JDT SDK (34 MB) Eclipse Platform SDK (76 MB) Eclipse SDK (120 MB) PDE JDT IDE Workspace Misc RCP Java VM -4-
Eclipse Architecture Rich Client Application Other Tools (CDT etc.) PDE JDT Help (Optional) Update (Optional) Text (Optional) IDE Text Compare Debug IDE Search Team/ CVS Rich Client Platform Generic Workbench (UI) JFace SWT Workspace (Optional) Platform Runtime (OSGi) Java VM OSGI Formerly for: Open Services Gateway initiative Is responsible for Bundle administration Class loading Several platform services (e.g. dependency management) Since 3.2: Equinox implementation Reference implementation of OSGi R4 Extension Point Mechanism implemented as OSGi service -5- -6-
Plug-ins Plug-ins The Eclipse synonym to an OSGi bundle Declares the component model Extensions Extension Points Platform runtime Contains OSGi and the plug-in runtime Is the runtime environment for bundles/plug-ins Responsible for jobs and preferences Extension Extension Point C Debug RCA C Debug Plug-in Rich Client Platform Platform Runtime Buzzwords Plug-in A plug-in is a component. It has dependencies to other plugins Extension Points and Extensions Provided and filled in by plug-ins Feature Bundles a set of plug-ins with a specific version. Only a feature can be updated, not a single plug-in or fragment Fragment Is a addition to a plug-in which adds e.g. I18N support or adds OS specific parts Update-site A location where features can be found and installed from there -7- -8-
Platform vs. extensible application Eclipse is a platform. Thus it has a very small kernel. Platform Extensible Application Plug-in Plug-in Application Run-time Eclipse Plug-in Architecture Due to the separation of declared and implemented parts, a lazy loading is possible Declaration describes The functionality of the plug-in The UI contributions And specifies the implementation classes Implementation Is done in Java and added as JAR to the plug-in Will be loaded lazily if An extension point is used Code of this plug-in is needed by an other plug-in -9- -10-
Iceberg Tip of the iceberg Startup time: O(#used plug-ins), not O(# installed plug-ins) Namespaces Plug-in namespaces Each plug-in has its own classloader Requests are delegated to the responsible classloader requires Y requires X A requires Z requires -11- -12-
SWT & JFace SWT Native GUI-Widgets Not OO (e.g. API-compliance between different OS only due to conventions) JFace Abstraction over SWT Viewer Forms-API Wizards / Dialogs / Actions MVC / Command Pattern Workbench Workbench Contributes the empty main window Adds support for Menu bars Tool bars Perspectives Views / Editors Preferences And many more extension points -13- -14-
Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion The simplest RCP application Create a new, empty plug-in called com.siemens.ct.mp3m Do NOT check the box to create an Activator class Do NOT check the box at Would you like to create a rich client application? on the second page. We do that manually. -15- -16-
New Plug-in Project Wizard Empty Plug-in Project -17- -18-
Adding the Application Extension Double click on MANIFEST.MF Choose the tab Dependencies Add org.eclipse.core.runtime and SAVE! Choose the tab Extensions Add org.eclipse.core.runtime.applications Type application in the ID field Right click the extension and select new/application Right click application and select new/run Type com.siemens.ct.mp3m.application in the class attribute Click on class to create the class Select the applications Extension -19- -20-
Add the Application Class Implement the run Method -21- -22-
Launching Launching creates a lot of confusion because nothing seems to work Often there is no problem with your code, just the Launch Configuration is not set up well Open the MANIFEST.MF again and select the Overview tab Click on Launch an Eclipse application This creates a default launch configuration and runs it Your Launching Helpers Open the launch configuration, take a look at The name field to give your launch configuration a meaningful name, e.g. MP3M The Arguments tab Add consolelog command line parameter This will output all logging also to the console The Plug-ins tab The Add Required Plug-ins button The Validate Plug-in Set button The Configuration tab Here you can check to clear the configuration data -23- -24-
The Launch Configuration Dialog (1) The Launch Configuration Dialog (1) -25- -26-
Successful Run Exercise Create a minimal console RCP application that just outputs Hello, world! to the console -27- -28-
Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion Screenshot of Minimal RCP Application -29- -30-
The Basic Classes Application ApplicationWorkbenchAdvisor ApplicationWorkbenchWindowAdvisor ApplicationActionBarAdvisor Perspective Application Declaration in plugin.xml <extension id="application" point="org.eclipse.core.runtime.applications"> <application> <run class="com.siemens.ct.mp3m.application"> </run> </application> </extension> -31- -32-
Application Class public class Application implements IPlatformRunnable { public Object run(object args) throws Exception { Display display = PlatformUI.createDisplay(); try { PlatformUI.createAndRunWorkbench(display, new ApplicationWorkbenchAdvisor() ); return IPlatformRunnable.EXIT_OK; finally { display.dispose(); ApplicationWorkbenchAdvisor public class ApplicationWorkbenchAdvisor extends WorkbenchAdvisor { public WorkbenchWindowAdvisor createworkbenchwindowadvisor( IWorkbenchWindowConfigurer configurer) { return new ApplicationWorkbenchWindowAdvisor(configurer); public String getinitialwindowperspectiveid() { return Perspective.PERSPECTIVE_ID; public void initialize(iworkbenchconfigurer configurer) { // saves the window position and size configurer.setsaveandrestore(true); -33- -34-
ApplicationWorkbenchWindowAdvisor public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor { public ApplicationWorkbenchWindowAdvisor( IWorkbenchWindowConfigurer configurer) { super(configurer); public ActionBarAdvisor createactionbaradvisor(iactionbarconfigurer configurer) { return new ApplicationActionBarAdvisor(configurer); public void prewindowopen() { IWorkbenchWindowConfigurer configurer = getwindowconfigurer(); configurer.setinitialsize(new Point(400, 300)); configurer.setshowcoolbar(false); configurer.setshowstatusline(false); ApplicationActionBarAdvisor public class ApplicationActionBarAdvisor extends ActionBarAdvisor { private IWorkbenchAction exitaction; public ApplicationActionBarAdvisor(IActionBarConfigurer configurer) { super(configurer); protected void makeactions(final IWorkbenchWindow window) { exitaction = ActionFactory.QUIT.create(window); register(exitaction); protected void fillmenubar(imenumanager menubar) { MenuManager filemenu = new MenuManager("File", IWorkbenchActionConstants.M_FILE); menubar.add(filemenu); filemenu.add(exitaction); -35- -36-
Perspective Declaration in plugin.xml <extension point="org.eclipse.ui.perspectives"> <perspective name="mp3m Perspective" class="com.siemens.ct.mp3m.perspective" id="com.siemens.ct.mp3m.perspective"> </perspective> </extension> Perspective Class public class Perspective implements IPerspectiveFactory { public static final String PERSPECTIVE_ID = "com.siemens.ct.mp3m.perspective"; public void createinitiallayout(ipagelayout layout) { // Create a layout template for views and editors -37- -38-
Exercise Create a minimal Workbench RCP application that has a File and a Help menu as well as an Exit menu item in the File menu Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion -39- -40-
Deployment & Update We need the update functionality For reuse, we create a separate plug-in We need a feature, only features can be updated We need an update site, where we can download the updates This can also be in the local file system Adding Update Functionality Depending on the type of RCP application, there's many different approaches: Reuse the Eclipse IDE Update functionality Create separate actions for different needs Provide a fully customized update action, that fits best for your application -41- -42-
Find the Eclipse IDE Update Functionality Import the Eclipse plug-ins into your workspace so you can search in them The Update Manger is invoked by selecting Help/Software Updates/Find and Install Search for the text Find and Install in all plugin.properties files Open the corresponding plugin.xml You find it in project org.eclipse.ui.ide Copy the definitions to your plug-in Copy the required classes to your plug-in Modify these classes for your needs Fix the dependencies and start your application The launch configuration now includes some new plug-ins that need to be bundled in a feature Eclipse IDE Update Benefits Easy to use for experienced Eclipse users But consider: The IDE update manager was designed for experienced IDE users, probably to sophisticated for your RCP app You probably don t want to add new update sites You might want to separate the update of your existing application from the installation of new features for your app. -43- -44-
Creating an Update Plug-in Create a new plug-in com.siemens.ct.mp3m.update No activator, but UI contributions Add the following dependencies and SAVE! org.eclipse.core.runtime org.eclipse.ui org.eclipse.ui.workbench org.eclipse.update.core org.eclipse.update.ui Open the plugin.xml in the manifest editor and add the extension org.eclipse.ui.actionsets Create an action set with id = com.siemens.ct.mp3m.update label = Update Actions Creating an Update Plug-in (2) Add a new menu with id = com.siemens.ct.mp3m.update.updatemenu label = Software Updates path = help/group.updates Add a new separator to this menu name = group0-45- -46-
Creating the Action Delegate Class Add a new action with id = com.siemens.ct.mp3m.update.installed label = Update installed features menubarpath = help/com.siemens.ct.mp3m. update.updatemenu/group0 class = com.siemens.ct.mp3m.update.updateaction Click on class Generate the class Implement the run method (see next slide) The Update Action s implementation public class UpdateAction implements IWorkbenchWindowActionDelegate { private IWorkbenchWindow window; public void init(iworkbenchwindow window) { this.window = window; public void run(iaction action) { BusyIndicator.showWhile(window.getShell().getDisplay(), new Runnable() { public void run() { UpdateJob job = new UpdateJob("Search for updates", false, false); job.setuser(true); job.setpriority(job.interactive); UpdateManagerUI.openInstaller(window.getShell(), job); ); // more methods like dispose and init -47- -48-
Creating a Feature Create a new feature-project and set the name to com.siemens.ct.mp3m.feature Open the feature.xml Set the update URL to file:/c:/temp/com.siemens.ct.mp3m.site open the plug-ins page Add com.siemens.ct.mp3m Add com.siemens.ct.mp3m.update Add all required plug-ins (see the run-configuration) Creating a product configuration Select File/New/Product Configuration -49- -50-
Configure Product Product Configuration Click here for exporting the product -51- -52-
Creating an Update Site Create a new Update Site Project set the name to com.siemens.ct.mp3m.site uncheck Use default and set it to c:/temp/com.siemens.ct.mp3m.site add a new category MP3M add the previously created feature build it Exercise Create a new plug-in with update functionality Create a feature including the 2 plug-ins Create a product configuration Export the product Create an update site that contains the feature -53- -54-
Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion Including help (1) We create a separate plug-in for the help system Benefits Clean software architecture Can be updated separately -55- -56-
Including help (2) Create a new plug-in project named com.siemens.ct.mp3m.help Go extension tab in the plugin.xml editor Add the help-template using the extension wizard Add the following plug-ins as dependencies org.eclipse.help org.eclipse.help.appserver, org.eclipse.help.base org.eclipse.help.webapp, org.eclipse.help.ui org.apache.lucene, org.eclipse.core.runtime org.eclipse.core.expressions org.eclipse.jface org.eclipse.ui.workbench org.eclipse.update.configurator Add the HelpContens action form the ActionFactory to the ActionbarAdvisor Typical Help Plug-in Structure -57- -58-
TOC XML File <?xml version="1.0" encoding="utf-8"?> <?NLS TYPE="org.eclipse.help.toc"?> <toc label="mp3 Manager Table of Contents"> <topic label="general" href="html/general.html" /> <topic label="user Documentation" href="html/userdoc.html" /> <topic label="license" href="html/license.html" /> </toc> Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion -59- -60-
Extensions and Extension Points Extension C Debug RCA Extension Point C Debug Plug-in Rich Client Platform Platform Runtime Benefits of Extension Points Separation of declarative XML for UI contributions Icons Menu Items Buttons Etc. Much better scalability Supports lazy loading of Java classes Better uncoupling of plug-ins -61- -62-
Extension Point Example (1) Open the plugin.xml editor of com.siemens.ct.mp3m.model Select the tab Extension Points Add a new extension point Set the name and ID to mp3info and press finish Add a new Element named provider Add a new Attribute named class Set kind property to java Set required property to true Set based on property to com.siemens.ct.mp3m.model.imp3infoprovider Extension Point Example (2) Open com.siemens.ct.mp3m.model.mp3infoproviderfactory Replace the implementation of the default constructor with private MP3InfoProviderFactory() { IConfigurationElement[] providers = Platform.getExtensionRegistry().getConfigurationElementsFor("com.siemens.ct.mp3m.model", "mp3info"); for (IConfigurationElement provider : providers) { try { currentprovider = (IMP3InfoProvider) provider. createexecutableextension("class"); catch (CoreException e) { LogUtil.logError("com.siemens.ct.mp3m.model",e); -63- -64-
Exercise Create an interface that returns an info string Create an extension point that instantiates classes implementing that interface Create a new plug-in using this extension point In the application, collect all extensions of this extension point and output all info strings to the console Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion -65- -66-
What is Product Branding? Product branding gives your application a specific high-level visual appearance Can be used for Vendor-specific appearance Product families Various different editions of the same software basis What can be branded in RCP apps? Launcher s icon Splash screen with progress bar and progress text Title bar text The image the window system associates with the product About dialog image About dialog text Also: New UI Presentation Style -67- -68-
Example RCP Demo Blue Branding Example RCP Demo Orange Branding -69- -70-
How to create a Branding? (1) Create a new product configuration How to create a Branding? (2) In the Launcher tab, fill out all the fields -71- -72-
How to create a Branding? (3) In the branding tab, fill out all the fields Separate Branding Plug-ins You can create separate branding plug-ins Including product configuration Including all branding resources and information Blue Branding Orange Branding -73- -74-
Branding & Features (1) For every separate branding, you need a separate feature Feature with Blue Branding Feature with Orange Branding Blue Branding Plug-in Orange Branding Plug-in Branding & Features (1) Approach 1: 1. Create a feature for each product branding 2. Include all plug-ins, that define your product in that feature 3. Place the product configuration in that feature 4. In the product configuration include only the branding feature! -75- -76-
Branding & Features (2) Approach 2: 1. Create a feature with your application plug-ins 2. Create a separate feature that contains only the specific branding plug-in 3. Include the application feature in your branding feature Use the Included Features tab in the feature.xml editor 4. In the product configuration include only the branding feature! Branding Feature Tips Create a directory structure: rootfiles/configuration Put your own plugin_customization.ini file into the configuration directory Content: org.eclipse.ui/show_progress_on_startup=true Insert root=rootfiles at the top of your build.properties file Put -plugincustomization configuration/plugin_customization.ini in the Program Arguments of your Launcher Product Configuration -77- -78-
Internationalized Product Brandings Useful for internationalize product versions Images and about text Can easily be implemented using plug-in fragments Internationalized Product Brandings Every product configuration can refer to a branding plug-in For internationalized product brandings create plug-in fragments of that branding plug-in Provide plugin_<locale>.properties for each locale, e.g. plugin_de.properties -79- -80-
Internationalized Branding Fragment plugin_de.properties: abouttext=deutscher Orange MP3 productname=deutscher Orange MP3 Manager aboutimage=product_lg_de.gif windowimages=icon16x16_de.gif,icon32x32_de.gif Product Configuration File In the product configuration editor refer to the following keys: 16x16 Image: %windowimages 32x32 Image: Leave this blank! abouttext: %abouttext Text: %text It is important to use the key windowimages for the 16x16 Image The value of windowimages is then automatically copied in the plugin.xml of your localized fragment -81- -82-
Branding Demo Exercise Create a branding feature Create a branding plug-in Create a product configuration in the feature Provide splash screen, icons, etc. in the branding plug-in Launch your demo application with product branding -83- -84-
Outline Architectural Overview Building an RCP Application Textual Hello-World Minimal Workbench Application Deployment & Update Including Help Creating an Extension Point Branding Discussion Resources Book: Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications by Jeff McAffer and Jean-Michel Lemieux -85- -86-
Discussion -87-