The Group items by category mechanism allows a small subset of features to be shown in the list, grouped by category. Eclipse is a highly modular application, and a regular install is likely to include over 400 features and over 600 plug-ins. A one-dimensional list of all of the features will take up a significant amount of UI space and would not provide the best user experience; and in any case, many of the features are subsets of the core functionality (Mylyn alone will install over 150 features depending on what combinations are selected in the install).
This categorization works by providing a category.xml file (also known as site.xml) which defines a category and a collection of features (from Eclipse 4.3 onwards, plug-ins as well as features). When the Group items by category checkbox is selected, only the groups and features defined in the category.xml file are shown, and the rest of the features and plug-ins are hidden. These are usually done via a separate Update Site Project.
- Create a new project called
com.packtpub.e4.updateas an Update Site Project. This will create a new project with asite.xmlfile. (If it is renamed fromsite.xmltocategory.xmlit will fail; so don't do that.) - Double-click on the
site.xmlfile and it will open an editor. - Click on the New Category button and enter the following:
- ID:
com.packtpub.e4.category - Name:
PacktPub Example E4 Category - Description:
Contains features for the PacktPub E4 book by Alex Blewitt
- ID:
- Ensure that the
com.packtpub.e4.categoryis selected, and click on the Add Feature button. - Select the
com.packtpub.e4.featurefrom the pop-up menu, and this will add it to the highlighted category:
- Click on the Build All button, and an update site will be materialized into the project folder:
- Finally, check that the categories are set up correctly by going into Help | Install New Software and placing the path to the workspace in use.
- Ensure the Group items by category checkbox is selected, and the category containing the feature should be seen:
The site.xml file is not required by modern Eclipse runtimes, but the artifacts.jar and content.jar contain XML files required by P2 to perform installation. These contain a list of all of the features and plug-ins, and what constraints are required for their installation (such as the packages a bundle exports or imports).
P2 generates a categorization from either a site.xml or category.xml file. These are essentially the same, but the update site has a nicer UI for editing and generating the content required.
<site>
<feature id="com.packtpub.e4.feature" version="1.0.0.qualifier"
url="features/com.packtpub.e4.feature_1.0.0.qualifier.jar">
<category name="com.packtpub.e4.category"/>
</feature>
<category-def name="com.packtpub.e4.category"
label="PacktPub E4 Example Category">
<description>
Contains features for the PacktPub E4 book by Alex Blewitt
</description>
</category-def>
</site>This file contains a list of features (which themselves contain plug-ins) and can be used to generate an update site, which is a features and plugins directory along with the top-level content. If the artifacts.jar or content.jar is missing (and there is no site.xml file), Eclipse will be unable to install content from the repository.
When the update site is built, it will replace the .qualifier with a build identifier, which is derived and then composed of the year/month/day/time. It is possible to override this with a different value if desired.
The artifacts.jar and content.jar files are ZIP files which contain a single xml file. This xml file is put in a JAR solely for compression; it can be served (though less efficiently) as artifacts.xml or content.xml as well.
This update site can be transferred to host onto a remote server to allow installation into other Eclipse instances. Eclipse supports HTTP as well as FTP by default, although it can be extended to allow other protocols.
Generally, only top-level features should be exposed in the update site. These may include other features or plug-ins, but only the top-level features are shown in the update site and in the installed list in Eclipse via Help | About | Installation Details.