[未完成]关于Eclipse4RCP书中内容总结

The Eclipse platform and IDE is released every year. Before 2012 Eclipse was released in version 3.x, e.g. Eclipse 3.6, Eclipse 3.7. These releases and the corresponding API are referred to as Eclipse 3.x.

As of 2012 the main Eclipse release carried the major version number 4, e.g. Eclipse 4.2 in the year 2012 and Eclipse 4.3 in 2013. These releases and the corresponding API are referred to as Eclipse 4.

The Eclipse 4 platform is based on a flexible and extendible programming model. Eclipse 4 was an opportunity to rationalize(ˈræʃnəlaɪz 使合理化) the best parts of the Eclipse 3.x APIs and to fix pain points of Eclipse 3.x development.

1.2. Eclipse 4 vs. Eclipse 3.x

The major enhancements(增强的地方) in Eclipse 4 compared to Eclipse 3.x are the following:

the structure on an Eclipse application is described via a logical model called the application model
the application model can be modified at development and runtime
the application model can be extended
the programming model is based on dependency injection
the styling of Eclipse widgets can be configured via external (CSS like) files
the application model is decoupled(减弱) from its presentation(提交；演出；陈述，报告；颁奖仪式), this allows a flexible configuration of the user interface and to use different user interface toolkits such as SWT or JavaFX

1.3. Terminology

An Eclipse application consists(由…组成) of several Eclipse components. A software component in Eclipse is called a plug-in. A software component in OSGi is called a bundle. Both terms(条件；表达方式；措辞；说法；任期term的名词复数) can be used interchangeably(可交换地，可交替地).

This book uses the terms Eclipse based applications, Eclipse application, Eclipse 4 application and Eclipse RCP application interchangeably for referring to an application which is based on the Eclipse 4 framework.

If a certain concept refers to Eclipse 3.x, then it is explicitly( 明白地，明确地) stated.

2. The Architecture of Eclipse

2.1. Eclipse based applications

An Eclipse application consists of individual software components. The Eclipse IDE can be viewed as a special Eclipse application with the focus on supporting software development.

The core components of the Eclipse IDE are depicted( dɪˈpɪkt 描绘，描画；描述) in the following graphic.

(图中间的一个词组 Rendering Engine 翻译为渲染引擎)

Note

The intention(意图，目的) of the graphic is to demonstrate the general concept, the displayed relationships are not 100 % accurate.

The most important components of this graphic are described in the next section.

2.2. Core components of the Eclipse platform

OSGi is a specification which describes a modular(ˈmɒdjələ(r) 分单元的模块化的 ) approach for Java application. The programming model of OSGi allows you to define dynamic software components, i.e., OSGi services.

Equinox([ˈi:kwɪnɒks] 昼夜平分点，春分或秋分) is one implementation of the OSGi specification and is used by the Eclipse platform. The Equinox runtime provides the necessary framework to run a modular Eclipse application.

SWT is the standard user interface component library used by Eclipse. JFace provides some convenient APIs on top of SWT. The workbench provides the framework for the application. It is responsible for displaying all other UI components.

On top of these base components, the Eclipse IDE adds components which are important for an IDE application, for example, the Java Development Tools (JDT) or version control support (EGit).

2.3. Compatibility layer for Eclipse 3.x plug-ins

Eclipse 4 provides a compatibility layer which allows that plug-ins using the Eclipse 3.x programming model can be used unmodified in an Eclipse based application.

Most plug-ins available for the Eclipse IDE are still based on the Eclipse 3.x programming model. These plug-ins use the compatibility layer to function in the Eclipse IDE.

2.4. Eclipse RCP

Eclipse based applications which are not primarily used as software development tools are called Eclipse RCP applications. An Eclipse 4 RCP application typically uses the base components of the Eclipse platform and adds additional application specific components.

Note

This book focuses on the development of Eclipse RCP applications. The development of Eclipse plug-ins for the IDE is not covered even though some of the techniques are very similar.

2.5. Provisional(prəˈvɪʒənl 暂时的，临时的；暂定的) API

Currently the Application Programming Interface (API) for Eclipse 4.3 is partially(ˈpɑ:ʃəli 部分地) released.

Some API is still marked as provisional. This means that the API might be changed in the future. If you use such API, you must be prepared that you might have to make some adjustments to your application in a future Eclipse release.

Note

If you use unreleased API, you see a Discouraged access warning in the Java editor.

The discussion which API will be released for Eclipse 4.4 takes place in Bug report for Eclipse 4.4 API.

2.6. Important configuration files

An Eclipse plug-in has the following main configuration files. These files are defining the API, and the dependencies of the plug-in.

MANIFEST.MF - contains the OSGi configuration information.
plugin.xml - contains information about Eclipse specific extension mechanisms('mekənɪzəmz 机制；机械作用 ).

An Eclipse plug-in defines its API and its dependencies via the MANIFEST.MF file, e.g., the Java packages which can be used by other plug-ins and the packages or plug-ins which are required by the plug-in.

The plugin.xml file provides the possibility to create and contribute to Eclipse specific API. You can add extension points and extensions in this file. Extension-points define interfaces for other plug-ins to contribute functionality. Extensions contribute functionality to these interfaces. Functionality can be code and non-code based.

Note

In Eclipse 4 the usage of extension points and extensions is less important than in Eclipse 3.x. Several extension points have been replaced with the usage of the application model.

3. Tutorial(tju:ˈtɔ:riəl 辅导材料使用说明书): Install Eclipse IDE for RCP development

3.1. Prerequisites(pri:'rekwɪzɪts 先决条件，前提 )

The following description assumes that you have Java installed in at least version 1.7.

3.2. Download and install the Eclipse SDK

The description in this book is based on the Eclipse 4.3.x release. Download the latest version of the Eclipse SDK build (4.3.1 or 4.3.1) from the following URL:

http://download.eclipse.org/eclipse/downloads/

This website should look similar to the following screenshot. Click on the release version to get to the download section.

The download is a zip file, which is a compressed archive of multiple files. Most operating systems can extract zip files in their file browser. For example, if you are using Windows 7 as operating system, right-click on the file in the Explorer and select the Extract all... menu entry. If in doubt about how to unzip, search via Google for How to unzip a file on ... , replacing "..." with your operating system.

Warning

Do not extract Eclipse to a directory with a path which contains spaces as this might lead to problems in the usage of Eclipse. Also avoid path names longer than 255 characters as this seems to create problems under Microsoft Windows.

After you extracted the zip file, double-click the eclipse.exe (Windows) or the eclipse file (Linux) (or the launcher icon specific to your platform) to start Eclipse.

To avoid any collision(kəˈlɪʒn 碰撞；冲突；（意见，看法）的抵触) with existing work select an empty directory as the workspace for this book.

3.3. Install the e4 tools

The Eclipse SDK download does not include the e4 tools, which make creating Eclipse 4 applications easier. These tools provide wizards to create Eclipse 4 artifacts(人工制品 ) and the specialized model editor for the application model.

The author of this book provides a working and recent version of the e4 tools for the Eclipse 4.3 release under the following URL:

http://download.vogella.com/kepler/e4tools

You can install the e4 tools via Help → Install new software by entering the URL.

Note

From this update site, install only the E4 CSS Spy and the Eclipse e4 Tools. The other entries are not used in this book and may cause different behavior.

Note

The e4 tools installation from the "download.vogella.com" site is not signed. For a signed e4 tools installation use Section 3.4, “Eclipse e4 tools update site”.

Restart your Eclipse IDE after the installation.

Tip

If you want to use Eclipse 4.4 (which is as of the time of this writing under development), you can use the following update site: http://download.vogella.com/luna/e4tools

3.4. Eclipse e4 tools update site

The above update site was created to provide a stable(稳定的,持久的) link for the reader of the book. The same code base is used by Eclipse.org to create an official update site for the Eclipse e4 tooling.

Unfortunately the link for this update site changes from time to time(不时地,常常) but it can be found on the following website: Eclipse.org e4tools site.

If you click on a Build Name link, you also find the URL for the update site. The following screenshots demonstrate this for a particular build of the e4 tools.

Note

This website might change over time.

4. Exercise: Wizard to create an RCP application

4.1. Create project

Select File → New → Other... → Eclipse 4 → Eclipse 4 Application Project from the menu of your Eclipse SDK.

Create a project called com.example.e4.rcp.wizard. Leave the default settings on the first two wizard pages. These settings are similar to the following screenshots.

On the third wizard page, enable the Enable development mode for application model and Create sample content (parts, menu etc.) flags.

Note

The Enable development mode for application model flag adds the clearPersistedState flag to the product configuration file. This ensures that changes during development in your application model are always visible. SeeSection 17, “Configure the deletion of persisted model data” for more information. Via the Create sample content (parts, menu etc.) flag you configure that the generated application should contain example content, e.g., a view and some menu and toolbar entries.

This wizard creates all the necessary files to start your application. The central file for starting your application is the .product file, created in your project folder.

4.2. Launch

Open the editor for your com.example.e4.rcp.wizard.product product configuration file by double-clicking on the file in the Package Explorer view.

Switch to the Overview tab in the editor and launch your Eclipse application by pressing the Launch an Eclipse applicationhyperlink. This selection is highlighted in the following screenshot.

This starts your Eclipse application which should look similar to the following screenshot. Note that the example application generated by the e4 tools project might change over time.

Note

You learn all the details of what happened here in later chapters.

5. The usage of run configurations

5.1. What are run configurations?

A run configuration defines the environment which will be used to execute a generic launch. For example, it defines arguments to the Java virtual machine (VM), plug-in (classpath) dependencies etc. Sometimes a run configuration is also called launch configuration.

If you start your Eclipse application, using the link in the .product file, the corresponding run configuration is automatically created or updated.

To review and edit your run configurations select Run → Run Configurations... from the Eclipse menu.

On the Main tab in the field Location you specify where the Eclipse IDE will create the files necessary to start your Eclipse based application.

5.2. Launch configuration and Eclipse products

The launch configuration stores the settings from the product configuration file. The launch configuration is created or updated every time you start your application via the product.

You can use the created run configuration directly for starting the application again. In this case changes in the product configuration file are not considered.

Warning

Using an existing run configuration is a common source of frustration and time consuming error analysis. To ensure that you use the latest configuration from your product, start via the .product file.

5.3. Launch arguments

The run configuration allows you to add additional start arguments for your application on the Arguments tab. By default Eclipse includes already some arguments, e.g. parameters for -os, -ws and -arch to specify the architecture on which the application is running.

The following table lists useful launch arguments.

Table 1. Launch parameters

Parameter	Description
`consoleLog`	Error messages of the running Eclipse application are written to standard-out (`System.out`) which can be viewed in the Eclipse IDE Console view that started the RCP application.
`nl`	Specifies the runtime language for your application. For example `-nl en` starts your application using the English language. This is useful for testing translations.
`console`	Provides access to an OSGi console where you can check the status of your application.
`noExit`	Keeps the OSGi console open even if the application crashes. This allows to analyze the application dependencies even if the application crashes during startup.
`clearPersistedState`	Deletes cached runtime changes of the Eclipse 4 application model.

6. Common launch problems

6.1. Launch problem number #1: missing plug-ins

The most common problem is that some required plug-ins are missing in your product. If you are using a feature based product configuration, you need to ensure that all plug-ins which are referred to in the MANIFEST.MF file are also included in your features.

Eclipse can check for missing dependencies automatically before you run the Launch configuration. On the Plug-ins Tab select theValidate plug-ins automatically prior to launching option. This will check if you have all the required plug-ins in your run configuration.

If this check reports that some plug-ins are missing, try clicking the Add Required Plug-ins button.

After identifying the missing plug-ins ensure that you add them to your product (if the product is plug-in based) or to your features (if the product is feature based).

Warning

Never fix problems with plug-ins only in the run configuration because the run configuration is created and updated based on the product configuration file. So always ensure that the product file is correctly configured instead of changing the derived information.

6.2. Checklist for other common problems

The following table lists potential problems and solutions.

Table 2. Run configuration problems

Problem	Investigate
During start you get error messages such as "One or more bundles are not resolved because the following root constraints are not resolved" or "java.lang.RuntimeException: No application id has been found."	Check that all required plug-ins are included in your run configuration. Make sure that your product defines dependencies to all required plug-ins or features. Bundles may also require a certain version of the Java virtual machine, e.g. a bundle may require Java 1.6 and will therefore not load in a Java 1.5 VM. Check the `MANIFEST.MF` file on the Overview tab in the Execution Environments section which Java version is required.
Strange behavior but no error message.	Check if your run configuration includes the `-consoleLog` parameter. This option allows you to see errors from Eclipse based application in theConsole view of the Eclipse IDE.
Runtime configuration is frequently missing required plug-ins	Make sure that your product or your feature(s) includes all required dependencies.
A change in the product Dependencies tab is not reflected in the run configuration (e.g. a new plug-in is added but is not included in the run configuration)	A product updates an existing run configuration if you start the product directly from the product definition file. If you select the run configuration directly, it will not be updated.
Application model changes are not reflected in the Eclipse 4 application.	Eclipse 4 persists user changes in the application in a delta file which is restored at startup. During development this might lead to situations where model changes are not correctly applied to the runtime model, e.g., you define a new menu entry and this entry is not displayed in your application. Either set the Clear flag on the Main tab in your run configuration or add the `clearPersistedState` parameter for your product configuration file or run configuration.
Services, e.g. key bindings or the selection service, are not working in an Eclipse 4 application.	Used to be problem in Eclipse 4.2 as in this release every part needed to implement a `@Focus` method which places the focus on an SWT control. Should work correctly in Eclipse 4.3, even without the `@Focus` method.
Menu entries are disabled in an Eclipse 4.3 build.	Eclipse 4.3 introduces a new model add-on which you need to register with your application model. The new application wizards adds that by default. When migrating from Eclipse 4.2, ensure that your application model has an entry pointing to the `HandlerProcessingAddon` class in the package `org.eclipse.e4.ui.internal.workbench.addons`. The bundle symbolic name is `org.eclipse.e4.ui.workbench`.
Application "org.eclipse.ant.core.antRunner" could not be found in the registry or Application could not be found in the registry.	Ensure that you have pressed the New... button in the product configuration file and selected the `E4Application` as application to start. You can check the current setting in your `plugin.xml` file on the Extensionstab and in the details of the org.eclipse.core.runtime.products extension.

7. Eclipse 4 application model

7.1. What is the application model?

Eclipse 4 uses an abstract description, called the application model, to describe the structure of an application. This application model contains the visual elements as well as some non-visual elements of the Eclipse 4 application.

The visual parts are, for example, windows, parts (views and editors), menus, toolbars, etc. Examples for non-visual components are handlers, commands and key bindings.

The following screenshot shows an example application model opened in the e4 tools editor.

Each model element has attributes which describe its current state, e.g. the size and the position of a window. Most of the model elements are in a hierarchical order, for example, parts might be grouped below a perspective.

7.2. Scope of the application model

The application model defines the structure of the application but it does not describe the content of the individual user interface components.

For example, the application model describes which parts are available. It also describes the properties of the parts, e.g., if a part is closable, its label, ID, etc. But it does not describe the content of the part, e.g., the labels, text fields and buttons it consists of. The content of the part is still defined by your source code.

If the application model was a house, it would describe the available rooms (parts) and their arrangement (perspectives , PartStacks , PartSashContainer) but not the furniture of the rooms. This is illustrated by the following image.

7.3. How do you define the application model?

The base of the application model is typically defined as a static file. The default name for this file is Application.e4xmi and the default location is the main directory of your application plug-in.

This XMI file is read at application startup and will be used to construct the initial application model.

The application model is extensible, e.g., other plug-ins can contribute to it via model processors and model fragments.

8. User interface model elements

The following model elements represents the basic elements which you use to create the user interface of your application.

8.1. Window

Eclipse applications consist of one or more windows. Typically an application has only one window, but you are not limited to that, e.g., if you want to support multiple connected monitors.

8.2. Views and editors - parts

Parts are user interface components which allow you to navigate and modify data. A part can have a dropdown menu, context menus and a toolbar.

Parts can be freely positioned in the user interface.

Parts are typically classified into views and editors. The distinction into views and editors is not based on technical differences, but on a different concept of using and arranging these parts.

A view is typically used to work on a set of data, which might be a hierarchical structure. If data is changed via the view, this change is typically directly applied to the underlying data structure. A view sometimes allows us to open an editor for a selected set of data.

An example for a view is the Package Explorer, which allows you to browse the files of Eclipse projects. If you change data in thePackage Explorer, e.g., renaming a file, the file name is directly changed on the file system.

Editors are typically used to modify a single data element, e.g., the content of a file or a data object. To apply the changes made in an editor to the data structure, the user has to explicitly save the editor content.

For example, the Java editor is used to modify Java source files. Changes to the source file are applied once the user selects theSave command. A dirty editor tab is marked with an asterisk to the left of the modified name of the file.

8.3. Perspective

A perspective is a visual container for a set of parts. Perspectives can be used to store different arrangements of parts. For example, the Eclipse IDE uses them to layout the views appropriate to the task (development, debugging, review, ...) the developer wants to perform.

You can place perspectives in a perspective stack in the application model. Switching perspectives can be done via the part service provided by the Eclipse platform.

8.4. PartStack and PartSashContainer

Parts can be directly assigned to a window or a perspective, but typically you want to group and arrange them.

For this you can use the PartStack and PartSashContainer model elements.

A PartStack contains a stack of parts showing the content of one part while showing the headers of all parts. One part is active and the user can switch to another part by selecting the corresponding tab.

A PartSashContainer displays all its children at the same time either horizontally or vertically aligned.

The following shows a simple Eclipse application layout using two PartSashContainer and a few PartStacks.

On the top of this layout there is a horizontal PartSashContainer which contains another PartSashContainer and some PartStacks. The hierarchy is depicted in the following graphic.

8.5. Using layout weight data for children elements

You can use the Container Data attribute on a child of a PartSashContainer to assign a layout weight.

This layout weight is interpreted as the relative space the corresponding child element should get assigned in the PartSashContainer.

The setting is depicted in the following screenshot.

Warning

If you set the Container Data for one element, you must define it for all elements, too. Otherwise the missing values are interpreted as very high and these elements take up all available space.

Tip

The initial total of all the container data values is maintained when elements in the sash are moved. In order to allow fine grained/smooth dragging this total must be similar to the screen resolution. A too low value (i.e. 50 / 50) causes the part to be moved multiple pixels per sash unit, which the user will realize as a jerky movement. Therefore, use a sufficient high value, e.g., 10000.

9. Connecting model elements to classes and resources

9.1. Connect model elements to classes

Certain model elements in the application model can contain references to Java classes via an Uniform Resource Identifier (URI).

The URI describes the location of the Java class. The first part of this URI is the plug-in, the second one the package and the last one the class.

Some application model elements have a Class URI attribute which points to a Java class for this element. This class provides the behavior of the part. Using the house/rooms metaphor from earlier, the class is responsible for defining the furnishings, the layout of the room and how the interactive objects behave.