Section 21.2.  Features

21.2. Features Manually dealing with collections of plug-ins is quite problematic. Human error and miscommunication cause you to get a few too many plug-ins, miss a few plug-ins, or pick up the wrong versions of plug-ins. Features allow you to abstract away the packaging details and talk about arbitrarily complex collections of plug-ins that can be built and deployed. 21.2.1. Uses of Features Update uses features to manage plug-ins in the following ways: Install/Update Features are the basic element of Update management. Users and programs install and update features, and through the features, the listed plug-ins. Individual plug-ins are not updated directly. Branding Features can appear in a product's About dialog. This gives feature creators an opportunity to both make their presence known within a larger product setting and give access to any required legal information. Building Features describe complete sets of plug-ins that make up a system. These plug-ins also need to be built and managed during development. Features play a central role in PDE's automated build process. Chapter 24, "Building Hyperbola," covers this in detail. Install handlers Not everything in the world fits into a plug-in. Features also support install handlers. Install handlers are run by Update when the corresponding feature is installed or uninstalled. Install handlers are used to place additional files in the filesystem, set file permissions, or complete the configuration of a feature or product. 21.2.2. What Is a Feature? A feature is a list of related plug-ins and other features. They are defined in a feature.xml file that lives in a feature directory, as shown in Figure 21-1. Figure 21-1. Feature directory structure At its simplest, a feature is an id/version pair and a list of plug-ins. As with plug-in ids, feature ids typically follow Java package naming conventions and their version numbers take the form major.minor.micro.qualifier. The example below shows an abbreviated version of the feature.xml for the org.eclipse.rcp feature in your Eclipse 3.1 target platform. The body of the feature lists the plug-ins that comprise the RCP Base. These plug-ins are said to be included in the feature. This means that if you install the RCP Base feature, all listed plug-ins are installed. org.eclipse.rcp/feature.xml <feature id="org.eclipse.rcp" label="Eclipse RCP Base" version="3.1.0"> <plugin id="org.eclipse.core.commands" version="3.1.0"/> <plugin id="org.eclipse.core.expressions" version="3.1.0"/> <plugin id="org.eclipse.core.runtime" version="3.1.0"/> <plugin id="org.eclipse.osgi" version="3.1.0"/> <plugin id="org.eclipse.help" version="3.1.0"/> <plugin id="org.eclipse.swt" version="3.1.0"/> <plugin id="org.eclipse.jface" version="3.1.0"/> <plugin id="org.eclipse.ui" version="3.1.0"/> <plugin id="org.eclipse.ui.workbench" version="3.1.0"/> <plugin id="org.eclipse.update.configurator" version="3.1.0"/> </feature> Note It is important to note that features do not contain the plug-ins. Rather, features reference their constituent parts. This allows the same plug-in to appear in many features, but only be installed once. The previous snippet shows the XML form of the featurethis reiterates the idea that a feature is really just a list of plug-ins and other features. In practice, you never have to edit the XML directly as PDE includes a comprehensive feature editor. You can open the editor on the RCP feature using File > Open File... and navigating to the feature in your target (e.g., c:\target\eclipse\features\org.eclipse.rcp_3.1.0\feature.xml) or by double-clicking on the RCP Base feature in the Included Features list of the Hyperbola feature. Either way, open the editor and flip to the Plug-ins page, as shown in Figure 21-2. Figure 21-2. RCP feature plug-in list [View full size image] Notice that the list shown has a number of entries related to SWT. These entries are the SWT fragments that contain the code specific to a given OS, window system, and processor architecture. If you install the RCP Base feature on Windows, for example, you need a different SWT fragment than if the feature is installed on Linux using GTK. The Plug-in Details shown indicates that the selected fragment (org.eclipse.swt.gtk.linux.x86) is specific to "linux", "gtk", and "x86". As such, Update ignores this fragment on other configurations. Only the relevant attributes need to be specified. For example, if your plug-in runs on all Motif systems, simply setting the Window System to "motif" is sufficient. Of course, if the plug-in or fragment includes native code, you must specify at least the Operating System and Architecture attributes. Note Notice also that the selected fragment is marked as not needing to be unpacked during installation. Plug-ins on an update site are stored as JARs. Traditionally, Update has unpacked these JARs into plug-in directories after downloading. As of Eclipse 3.1, many plug-ins no longer need to be unpacked and therefore have this option deselected. Now that you have the RCP Base feature, you no longer have to laboriously list each of the RCP plug-ins when defining other features. Figure 21-3 shows the Included Feature page for the Hyperbola feature editor. Included are the RCP Base feature you added back in Chapter 14 and org.eclipsercp. hyperbola.feature.muc, an additional feature used to demonstrate the notion of optional features. Figure 21-3. Including features [View full size image] Here, the Included Feature Details section shows the MUC feature marked as optional. Typically, a parent feature fails to install if some of its included features and plug-ins are not present. However, marking a feature as optional allows the parent to be installed even if the optional feature is not present or cannot be installed. This is ideal for defining products that are extensible according to user needs or OS facilities. The above examples illustrate the definition of feature contentfeatures are made up of the plug-ins and features that are included in their definition. If you install a feature, all its constituents are also installed, if not already available. This is powerful, but the inclusion characteristic is limiting. Typically, when you include some plug-ins or features, you are committing to shipping them. If your product is to be installed with others, it is better to simply state a dependency on the parts that are needed. For example, the Hyperbola feature could specify a requirement that the RCP Base feature already be installed. This does not commit you to delivering the RCP Base, but it does express the dependency so that it can be checked. On the Dependencies page, you can list the features and plug-ins that must be present to successfully install your feature. Figure 21-4 shows a feature that declares the RCP Base feature and Browser and Intro plug-ins as required, but not supplied. Installing this feature makes no attempt to download or install the listed elements; rather, the information is used by the Update UI to verify the correctness of a configuration. Figure 21-4. Feature dependencies [View full size image] Tip To install features using Update, the features must have a license agreement. This agreement is shown to the user as he goes through the Update/Install wizard. To define the license, go to the License Agreement tab on the Information page of the feature editor. There you can fill in the license text and a URL to use when showing the license to the user.