How to create, debug and install plugins
Level: primary
David Gallardo (David@gallardo.org) Software Consultant March 2003
In this article, David Gallardo shows you how to create an Eclipse plugin with the Code Generation Wizard of Plug-In Development Environment. You will learn how to run and debug plugins in the runtime workshop, and install the completed plugins in Eclipse. David also studies issues related to packaging plug-ins - included maintenance version information, updating features in the form of plugins, and combined plugins to create a complete feature.
Plug-in-based architecture Eclipse platform is the development framework for IBM donated to the development source community. It is not because IBM claims to invest in total funds - $ 40 million - but because of such a huge investment. : A mature, carefully designed and scalable architecture. The value of Eclipse is that it provides an open source platform for the creation of an extensible integrated development environment. This platform allows anyone to build tools for seamless integration with environment and other tools.
The key to the seamless integration of tools and eclipse is plugin. In addition to small runtime kernels, all things in Eclipse are plugins. From this perspective, all features are created in equally. From this perspective, all features are created in equally.
However, some plugins are more important than other plugins. Workbench and Workspace are two essential plugins for the Eclipse platform - they provide extensions used by most plugins, as shown in Figure 1. The plugin requires an extended point to insert so that it can run.
Figure 1. Eclipse Workbench and Workspace: Essential Plugin Support
The Workbench component contains some extensions, for example, allowing your plugin to extend the Eclipse user interface, making these user interfaces with menu selection and toolbar buttons; request notifications for different types of events; and create a new view. The Workspace component contains an extension point that allows you to interact with resources (including projects and files).
Of course, other plugins can extend the Eclipse components that do not have Workbench and Workspace. In addition, there is a Debug component that allows your plug-in to launch programs, interacting with running programs, and handling errors - this is necessary to build a debugger. Although Debug Components is required for certain types of applications, most applications don't need it.
There is also a Team component that allows the Eclipse resource and version control system (VCS) interaction, unless you are building a VCS's Eclipse client, otherwise the Team component is like the Debug component, does not expand or enhance its functionality.
Finally, there is a HELP component that allows you to provide an online documentation and help with context. No one will deny the help documentation is a must-have part of the professional application, but it is not the necessary part of the plug-in function.
The extended points provided by each of the above components are recorded in the Eclipse Platform Help, which helps in the reference section of the Platform Plug-in Developer Guide. At first glance, especially the API refers to the entire Workbench section, it will be expected at the beginning. We don't know more about the details of many available extensions, but just a simple plug-in and their components.
Introduction to Introduction to Creating Plugins is to use Plug-in Development Environment (PDE). PDE and Java Development Tooling (JDT) IDE are standard extensions for Eclipse. PDE provides some wizard to help create a plugin, including the "Hello, World" example we will study here. From the Eclipse menu, select File => New => Other (or press Ctrl-N), then select the Plug-In Development Wizard left on the SELECT dialog. On the right side of the SELECT dialog, select Plug-in Project. Press NEXT. On the next screen, enter the project name; I used com.example.hello. Press NEXT again. On the next screen, please note that the plugin identifier is the same as the project name. Use the project name as a plug-in to minimize the chance of conflicting the plugin with the name of the other plugin. Press again again. The next screen lets you choose to manually create an initial plugin code, or run the code generation wizard. Keep the default option of the code generation wizard, select "Hello, World", then press Next, as shown in Figure 2.
Figure 2. Select "Hello, World" Code Generation Wizard
The next screen requires some additional information. Note the information on this screen: it contains the plugin name, version number, provider name, and class name. These are important information about plug-ins, we will study later. You can accept the default value provided by the wizard. Press NEXT. On the next screen, accept the default value of the package, class name, and message text. Select the "Add The Action Set To The Resource Perspective" checkbox. Press Finish.
If you receive a notification: The wizard needs to enable some other plugins to complete, then press OK.
After a while, the wizard will be completed, and there will be a new project in your work area, named Com.example.Hello, as shown in Figure 3.
Figure 3. PDE perspective: Welcome to Hello Plug-in
In Package Explorer, the left side of the workbench is an overview of some things created by the wizard. Most of them are not persistent: including many .jar files in the project class path (these Eclipse classes needed when plugins and Java runts), an icon folder (including graphics of the toolbar button), and build .properties file (contains the variables used automatically built scripts).
The most interesting thing here is the SRC folder, which contains the source code for plugins and plugin.xml files - Plug-in.xml is a plus file for plugins. We will first look at Plugin.xml.
Plug-in list file plug-in file PLUGIN.XML contains Eclipse to integrate plugins into the description information used by the frame. By default, when the plugin is created for the first time, PLUGIN.XML will be opened in the list editor area. The tab at the bottom of the editor allows you to choose the different information collections about the plugin. The Welcome tab displays the message "Welcome to Hello Plug-IN" and briefly discusses the templates used and prompts for the use of Eclipse implementation plugins. Choosing the Source tab allows you to view the full source code of the Plugin.xml file.
Let us look at the various parts of the plug-in list file. The first is the general information about the plugin, including its name, version number, the name of its class file, and .jar file name.
Listing 1. Plug-in list file - General information
ID = "com.example.hello" Name = "Hello Plug-in" Version = "1.0.0" Provider-name = "example" Class = "com.example.hello.helloplugin"> Then, the plugins needed for our plug-in: Listing 2. Plug-in list file - required plugin The first plugin listed org.eclipse.core.resources is a workspace plugin, but in fact our plugin does not need it. The second plugin org.eclipse.ui is a workbench. We need a table plug-in because we will extend its two extensions, as indicated by the following Extension tag. The first extension tag ownership attribute org.eclipse.ui.actionSets. The set of operations is a group of base values added to the table user interface - ie, menu, menu items, and toolbar. The set group is packetized, so that users can manage them more easily. For example, our Hello plug-in menu and toolbar items will appear in the Resource perspective, because when we do this when running the code generation wizard, we have made this option. If the user wants to change it, you can use the Window => Customize Perspective menu option to remove "Sample Action Set" from the item to be displayed in the Resource perspective. Figure 4. Customized Resource perspective The operation set contains two tags: MENU tag (where the menu item should appear in the table menu, and how to appear) and the action tag (describe what it should do) - especially the Action tag identifies the class of the execution operation. Note: This class is not the plugin class listed above. Listing 3. Operation collection Point = "org.eclipse.ui.actionsets"> Label = "Sample Action SET" Visible = "True" ID = "com.example.hello.action set"> Label = "Sample & Menu" ID = "SampleMenu"> Name = "SampleGroup"> Label = "& Sample Action" icon = "icons / sample.gif" Class = "com.example.hello.actions.ctions.sample" Tooltip = "Hello, Eclipse World" menubarpath = "SampleMenu / SampleGroup" Toolbarpath = "SampleGroup" ID = "com.example.hello.actions"> The purpose of many menus and operational properties is quite obvious - for example, a graphic for providing tooltip text and identification toolbar items. However, pay attention to the MenuBarPath in the Action tag: This property identifies which menu item defined in the MENU tag calls the operation defined in the Action tag. For more information on this and other workbench extension points, please refer to Platform Plug-in Developer Guide, especially the "Plugging INTO THE WORKBENCH" section (which can be obtained from the Help menu of the Eclipse). Since we have selected the plugin to the Resource perspective, the second Extension tag is generated. This tag can cause the plugin to the Resource perspective when Eclipse is first started and loaded into our plugin. Listing 4. EXTENSION tag Point = "Org.eclipse.ui.PerspectiveExtensions"> Targetid = "org.eclipse.ui.resourceperspective"> ID = "com.example.hello.action set"> If you ignore this last extension, users need to use Window => Customize Perspective to add plugins to resource (or other) perspective. The Plug Source Code Generation The wizard enables two Java source files to open the SRC folder in PDE Package Explorer. The first file helloplugin.java is a plugin class that inherits the Abstractuiplugin abstraction class. Helloplugin is responsible for managing the life cycle of the plugin. In a more expanded application, it is responsible for maintaining content such as dialog settings and user preferences. Helloplugin is going on so much: Listing 5. Helloplugin PackageCom.example.hello.actions; Import org.eclipse.ui.plugin. *; Import org.eclipse.core.runtime. *; Import org.eclipse.core.resources. *; Import java.util. *; / ** * The main plugin class to be used in the desktop. * / Public class helloplugin extends abstractuiplugin { // The shared instance. Private static helloplugin plugin // resource bundle. Private resourcebundle resourcebundle; / ** * The constructor. * / Public Helloplugin (iPlugindescriptor descriptor) { Super (Descriptor); Plugin = THIS; Try { ResourceBundle = ResourceBundle.getBundle "com.example.hello.hellopluginResources"); } catch (missingResourceException x) { ResourceBundle = NULL; } } / ** * Returns the shared instance. * / Public static helloplugin getDefault () { Return Plugin; } / ** * Returns The Workspace Instance. * / Public Static iWorkspace getWorkspace () { Return resourcesplugin.getWorkspace (); } / ** * Returns the string from the plugin's resource bundle, * or 'key' if not found. * / Public static string getresourceString (String key) { ResourceBundle bundle = helloplugin.getDefault (). GetresourceBundle (); Try { Return bundle.getstring (key); } catch (missingResourceException e) { Return Key; } } / ** * Returns The Plugin's Resource Bundle, * / Public ResourceBundle getResourceBundle () { Return resourcebundle; } } The second source file SampleAction.java contains the operations specified in the operation set of the manifest file. The sampleAction implements the iWorkbenchWindowActionDelegate interface, which allows Eclipse to use the plug-in agent, which is not in the case, Eclipse does not need to load the plugin (this optimization works to minimize the problem of memory and performance in the plugin) . IWorkBenchWindowActionDelegate interface method makes the plugin to interact with the agent: Listing 6. iWorkbenchWindowActionDelegate interface method Package com.example.hello.Anctions; Import org.eclipse.jface.action.IAction; Import org.eclipse.jface.viewers.Iction; Import org.eclipse.ui.iworkbenchwindow; Import org.eclipse.ui.iworkbenchwindowActiondeeGate; Import org.eclipse.jface.dialogs.MessageDialog; / ** * Our Sample Action Implements Workbench Action Delegate. * The action proxy will be create by the workbench and * Shown in the ui .hen the user tries to use the action, * This Delegate Will BE CREATED AND EXECUTION WILL BE * delegated to it. * @see iWorkbenchWindowActionDelegate * / Public Class SampleAction Implements iWorkbenchWindowActionDelegate { Private iWorkbenchWindow Window; / ** * The constructor. * / Public sampleAction () { } / ** * The Action Has Been ActiVated. The argument of the * Method Repestings the 'Real' Action Sitting * in The Workbench UI. * @see iWorkbenchWindowActionDelegate # run * / Public void run (IAAADITION Action) { MessageDialog.openInformation WINDOW.GETSHELL (), "Hello Plug-in", "Hello, Eclipse World"); } / ** * Selection in The Workbench Has Been Changed. WE * Can change the state of the 'real' action here * if we want, but this can only HappenAfter * The Delegate Has Been Created. * @see iWorkbenchWindowActionDelegate # SelectionChanged * / Public void SelectionChanged (IADITION Action, ISELECTION Selection) { } / ** * We can use this method to dispose of any system * Resources We prepViously allocated. * @see iWorkbenchWindowActionDelegate # Dispose * / Public void dispose () { } / ** * WE WILL Cache Window Object in Order To * Be able to provide parent shell for the message dialog. * @see iWorkbenchWindowActionDelegate # init * / Public void init (iWorkbenchWindow Window) { THIS.WINDOW = WINDOW; } } Run and Debug Plug When developing an Eclipse plugin, you must stop Eclipse and restart it with a new plugin to test and debug, which is awkward. Fortunately, Eclipse PDE provides a self-hosted development environment that allows you to run in a separate instance of the plugin to be installed on a workbench. To run the Hello plugin, select Run => Run as => Run-Time Workbench to start another Workbench instance, and the instance adds the plug-in menu option and toolbar, as shown in Figure 5. Figure 5. Hello plugin running in the runtime workbench We can activate the plugin from the "Sample Menu" menu by clicking the toolbar button. Any method generates a box, its title is "Hello Plug-in", the content is "Hello, Eclipse World", and an OK button, press this button to close this box. By selecting Run => Debug as => run-time workbench, debug the plugin in a similar method. This time, when the plug-in is running in the second workbench instance, we can perform source code in the initial workstore, and check the variables. Once the plugin is tested and ready to be released, we need to pack it properly to install it in Eclipse. Package plugins Eclipse will view their plugin directory at startup to determine which plugins to be loaded. To install a plugin, we need to create a subdirectory in the plugin directory and copy the program files and inventory files there. It is recommended that the directory name can represent the identity of the plugin, and follow the underscore and version number, but this approach is not required. Suppose Eclipse is installed in C: / Eclipse; we have to create a directory: C: /eclipse/plugins/com.example.hello_1.0.0. According to the standard of the Java program, our program file needs to archive to .jar files - our plug-in list file, you may remember that it contains this item: To create a Hello.jar file, we can export the plugin file by highlighting the project name and select File => EXPORT from the Eclipse menu to export the plugin file. Select the JAR file as the export method, press Next, then browse to our directory you created for it. Next, we also need to copy the Plugin.xml file to this directory. You can also use the file => Export menu option (but please remember to select File System as export destination). This is the full operation required to install the plugin, but you will need to stop and restart Eclipse so you can identify this new plugin. From the Help menu, select "About Eclipse Platform", you can find information about the installed plugin, including the version number. There is a button on the screen that appears is plug-in details; scroll down the list to find the Hello plugin and its version number. The purpose of the update plugin version contains version numbers in the directory name is to allow multiple versions of a plug-in on the same machine (only one version each time). We can see how this is working by creating a Hello plugin: For example, change the version number in the plugin.xml file into "1.0.1", then change the text in SampleAction.java " New and Improved Hello, Eclipse World. Select Project => Rebuild ALL from the Eclipse menu. Next, the project file is exported to a new plugin directory in JAR, for example, com.example.hello_1.0.1. Copy the revised Plugin.xml file to the same directory. When you stop and restart Eclipse, only the updated plugin is loaded. The plug-in segment and the functional component Eclipse consists of plugins, but when developing Eclipse plug-ins, additional two levels of components - plug-in and function components are considered. The plugin fragment (if the name is implicit) is an integral part of the full plugin - the target plugin. The functionality provided by the clip is merged with the function of the target plugin. The fragment can be used to localize the plug-in into a variety of languages; the functional components are added to the existing plug-in without the need to form a new release, or provide a platform-specific function. In many ways, the fragment is the same as the plugin. The main difference is that the fragment does not have a plug-in class - the life cycle of the fragment is managed by its target plugin. In addition, the list of fragments is called Fragment.xml, which lists the identity and version number of the target plugin, and the identity and version number of the clip. On the other hand, the plug-in functional components do not include encoding. In the Eclipse architecture term, the functional component is to package a set of plugins into a complete product. For example, JDT is a functional component that includes a plug-in such as a Java editor, a debugger, and a console. A manifest file named Feature.xml describes a feature archive. In this, the list file contains references to the plugins and other resources included in the feature, information, copyright information, and license information for how to update the feature. In Eclipse, the main function component sets the appearance of the Eclipse platform. The main function component is intended to determine something such as a flash screen and other features given to Eclipse. Eclipse only allows a primary function component. In this way, by creating a set of plugins, they are packaged into the functional components, and this feature is made to be a primary feature, and the Eclipse brand can be recreated and it is used to create a new and different products. If downloaded from Eclipse.org, the default main feature is Eclipse.org.platform. Subsequent steps in the plugin we just know the necessary usage of some plugins. The best knowledge of learning plug-ins is Plug-in Developer's Guide, which can be obtained from the help menu in Eclipse. This document contains a program guide, Eclipse API, and plug-in extension points, which are available on Eclipse.org, and a list of commonly available issues. Another excellent reference is the source code of Eclipse itself. Depending on your interest, you may want to find some examples to learn how different workbench features (such as view and editor) are extended, or how to use SWT (Eclipse Graphics API). In addition, the following references can help you learn more. Reference You can get Eclipse documents, articles, and download Eclipse from the Eclipse project website. Browse the full Eclipse plugin list. More plug-in information (French) can also be obtained. More Eclipse knowledge can be learned from the following developerWorks article: David Gallardo another article "Getting started with the Eclipse Platform" (developerWorks, November 2002) "Plug a Swing-based development tool into Eclipse" (developerWorks, October 2002) "Internationalizing your Eclipse plug-in" (DeveloperWorks, June 2002) "DEVELOPERWORKS, JU 201 2002)" Working XML: USE Eclipse to Build A User Interface for XM "(October 2002)" Interview MARC Erikson: Eclipse Code donation "(developerWorks, November 2001)" Working the Eclipse Platform "(developerWorks, November 2001)" Getting to know WebSphere Studio Application Developer "(developerWorks, November 2001)" Help for reusing your Assets "(DeveloperWorks, November 2001)" Create Native, Cross-Platform GUI Applications "(April 2002) For more details on plug-in development, see the articles on the Eclipse.org site. Please find the reference information you need in the open source project area and the Java technology area on developerWorks. About the author David Gallardo is an independent software consultant and writer, his expertise is software internationalization, Java web applications and database development. He became a professional software engineer for fifteen years, he has many experience in operating systems, programming languages, and network protocols. He recently engaged in advanced database and international development in a company's TradeAccess, INC. Prior to this, he was a senior engineer in the INTERNATIONAL PRODUCT DEVELOPMENT group in Lotus Development Corporation, which was responsible for developing cross-platform libraries for Lotus products (including Domino) providing Unicode and international language support. You can contact David via David@gallardo.org.
