Eclipse 3.x to E4: The Migration Path

Introduction

Eclipse E4 (Eclipse 4) has been the default architecture for the Eclipse platform since the Juno release (4.2) in June 2012. Since then, all Eclipse 3.x applications continue to function, but they run in compatibility mode, which provides backwards compatibility but doesn’t let you use the new E4 features directly. This compatibility layer will be maintained, but migrating to native E4 offers numerous advantages.

Advantages of Migrating to Eclipse E4

1. Model-based UI: E4 uses a declarative application model that separates UI structure from implementation, making it more flexible and easier to modify.
2. Dependency Injection: Built-in DI reduces coupling between components and makes code more testable.
3. CSS Styling: E4 allows you to style your application using CSS, making it easier to create consistent themes and customize appearance.
4. Modular Services: The service-oriented architecture makes it easier to replace, extend or mock components.
5. Simplified Programming Model: Many common tasks require less code in E4 than in 3.x.
6. Live Model Editing: The application model can be modified at runtime, allowing for dynamic UI changes.
7. Better Resource Management: Improved resource tracking and cleanup with annotation-based lifecycle management.
8. Future-proof: As Eclipse continues to evolve, 3.x compatibility mode may eventually be deprecated.

Before You Start

Before migration, make sure you understand these important concepts:

1. Application Model: E4 uses a declarative model for UI elements
2. Dependency Injection: E4 uses this pattern extensively
3. CSS Styling: E4 allows styling UI components with CSS
4. Services: E4 uses services for many platform functions

(IMG-PLACEHOLDER: Eclipse 3.x vs E4 architecture comparison)

Migration Strategy

Step 1: Assess Your Application

First, evaluate your application to identify which parts should be migrated first:

• Components with minimal dependencies
• Non-UI plugins before UI plugins
• Extension points that have direct E4 equivalents

Step 2: Update Dependencies

Add these required dependencies to your plugin’s MANIFEST.MF file:

org.eclipse.e4.core.di
org.eclipse.e4.core.contexts
org.eclipse.e4.ui.model.workbench
org.eclipse.e4.ui.workbench

Step 3: Migrate Core Plugins First

Start with plugins that don’t depend on UI elements. This makes testing easier and reduces compatibility issues.

Migration Components Guide

Migrating Menus, Commands, and Handlers

In Eclipse 3.x, menus and commands are defined using extension points in plugin.xml:

<extension point="org.eclipse.ui.commands">
  <command id="sample.command" name="Sample Command"/>
</extension>

In E4, they are defined in the application model:

1. Create or modify the application model file (Application.e4xmi)
2. Add commands to the Commands section
3. Create handlers using the @Execute annotation:

public class SampleHandler {
  @Execute
  public void execute() {
    // Handler logic here
  }
}

(IMG-PLACEHOLDER: Application.e4xmi editor screenshot)

Migrating Lifecycle Management

Eclipse 3.x manages lifecycle with:

• IStartup extension point
• Plugin activator classes

E4 uses:

• @PostConstruct and @PreDestroy annotations
• Lifecycle hooks in the application model
• E4 service addons

Example E4 lifecycle hook:

public class MyAddon {
  @PostConstruct
  public void init(IEclipseContext context) {
    // Initialization code
  }
  
  @PreDestroy
  public void dispose() {
    // Cleanup code
  }
}

Migrating Views and Editors

1. Replace IViewPart implementations with POJO classes
2. Use @Inject to receive workbench services
3. Add view to the application model instead of using extension points

Example E4 view:

public class SampleView {
  @Inject
  public SampleView(Composite parent, MPart part) {
    // Create view contents
  }
}

Migrating Selection Service

Replace:

ISelectionService selectionService = getSite().getWorkbenchWindow().getSelectionService();

With:

@Inject
ESelectionService selectionService;

Common Issues and Solutions

1. Mixed Mode Operation: During migration, your application will have both 3.x and E4 components. Use IEclipseContext to bridge between them.
2. Extension Point Changes: Many 3.x extension points don’t exist in E4. Use the application model or services instead.
3. Context Access: In 3.x, you often use static methods for access. In E4, use dependency injection.

Testing Your Migration

1. Start with a small feature set
2. Create isolated test plugins
3. Use the compatibility layer as a fallback during migration
4. Test in both 3.x compatibility and pure E4 mode

(IMG-PLACEHOLDER: Testing workflow diagram)

Recommended Migration Order

1. Core services and non-UI plugins
2. Commands and handlers
3. Views and editors
4. Perspectives
5. Preference pages
6. Actions and menus

Key Considerations for Migration Evaluation

When to Migrate

• Large Applications: Consider a gradual migration, component by component
• New Features: If you need E4-specific features like flexible UI layouts or CSS styling
• Long-term Maintenance: Applications with long lifecycles will benefit from migrating sooner

When to Stay with 3.x Compatibility

• Stable Applications: If your application is stable and doesn’t need new E4 features
• Short Project Timeline: If you have tight deadlines, the compatibility layer may be sufficient
• Legacy Components: If you depend on 3.x-specific APIs with no E4 equivalents

Migration Effort Estimation

• Small Applications (5-10 plugins): 1-2 months for a full migration
• Medium Applications (10-50 plugins): 3-6 months
• Large Applications (50+ plugins): 6+ months, consider a phased approach

Tools to Help Migration

• Eclipse E4 Tools: Provide visual editors for application models
• Eclipse Migration Guide: Available in the Eclipse help system
• Migration analyzers: Can help identify which components need changes

References and Resources

• Eclipse E4 Wiki
• Vogella E4 Tutorials
• Eclipse E4 Tools
• Eclipse Platform Newsgroup
• Eclipse E4 Migration Guide
• Eclipse Wiki: E4 Running the compatibility Layer

Conclusion

Migrating from Eclipse 3.x to E4 requires careful planning but offers significant benefits in terms of maintainability, flexibility, and future-proofing. The most important aspects are understanding the application model, properly using dependency injection, and migrating core components first. While the process may seem complex, taking a systematic approach will lead to a cleaner, more maintainable application that can take full advantage of the modern Eclipse platform.

Remember that your migration doesn’t have to happen all at once. The compatibility layer allows you to migrate components gradually, testing each one thoroughly before moving on to the next. This incremental approach helps manage risk and allows your team to become familiar with E4 concepts over time.