Java Developer Tools

Legacy API Decommissioning

This document describes our rationale and plan for decommissioning the old (or version 1.0) WindowTester Pro runtime API.

  1. Background
  2. Motivation
  3. Moving Forward
  4. Phase 1: Ruthless Documentation
    1. Deprecated Services
    2. Internalized Packages
  5. Phase 2: Migrate Implementation
    1. Strategy: Implementation Shunts
  6. Phase 3: API Baseline
  7. Phase 4: Legacy Compatibility Bundles
  8. Phase 5: Migration
  9. Making the Move Easier
    1. Option 1: Refactor to Use Preferred Classes
    2. Option 2: Add Legacy Bundle Dependencies
  10. Timeline

Background

In March of 2007, we introduced a new and improved runtime API. To make the transition painless we shipped the old and new APIs side-by-side in the same bundles. For customers who have tests that mixed APIs this was key to an easy adoption. Over time, as the new API has proven itself, the older version has become truly legacy code. Indeed, for new users of the tool, there is no reason to use it. Unfortunately, our decision to continue to ship the legacy version means that like it or not, new users are exposed to the API creating unnecessary confusion.

Motivation

It’s easy to feel the pain of the hybrid API. For example, suppose you are writing a test case and you want to insert a condition. Reasonable, right? The trouble comes when you go to import the ICondition interface:


How do you know which to import? Removing the deprecated API from the product will save the user from needing to know.

Moving Forward

To improve usability, we will begin teasing apart the old and new API pieces. New users will be met with a leaner API, rid of deprecated classes and interfaces. Users who still require access to the legacy API will be able to do this through an optional legacy API compatibility layer (a set of bundles). This document describes how we mean to do this.

(NOTE: legacy bundles are no longer shipped with the product as of version 5.0. The migration tooling described here should remove the need for them. If you believe you still need these bundles, please contact support and we will work with you to find a solution that best fits your needs.)

Phase 1: Ruthless Documentation

Deprecated Services

In the first phase, we will ensure that ALL deprecated API is properly tagged with the @deprecated javadoc and all deprecated packages are marked as deprecated in their package summaries.

A summary of deprecated API can be found in the javadocs.

Internalized Packages

Additionally, all internal packages will be appropriately marked as such using the "x-internal:=true" attribute in their declaring bundle manifests.

Phase 2: Migrate Implementation

The next step is to move existing implementations into internal packages. To aid in migration, shunt classes will be left behind that maintain binary compatibility and provide documentation for making the move to the new API.

Strategy: Implementation Shunts

The basic pattern is best illustrated with an example. For example, the move of UITestCaseSWT from it’s legacy home in the junit.extensions package to its new home is accomplished with this implementation of junit.extensions.UITestCaseSWT:

/**
 * ...
 * @deprecated prefer {@link com.windowtester.runtime.swt.UITestCaseSWT}
 */
public class UITestCaseSWT extends com.windowtester.runtime.swt.UITestCaseSWT {         
        public UITestCaseSWT() { super(); }
        public UITestCaseSWT(String testName){ super(testName); }
        ...
}

Phase 3: API Baseline

To aid (internally) in ensuring there are no API breakages in the migration, an API baseline will be setup using the PDE API tooling.

Phase 4: Legacy Compatibility Bundles

The following new bundles are defined to house migrated features.

  • com.windowtester.runtime.legacy for com.windowtester.runtime features
  • com.windowtester.swt.runtime.legacy for com.windowtester.swt.runtime features

These bundles will ship with initially ship with the product. Eventually, they will be provisioned as a separate (optional) feature.

Phase 5: Migration

A summary of migrated resources is contained in a separation legacy bundles document.

Making the Move Easier

In many cases, this transition will not affect the user and will be completely transparent. Otherwise there are a few scenarios.

Option 1: Refactor to Use Preferred Classes

In case you are using a deprecated class that has a preferred (API) version, update the reference to import the preferred version. For example, if you are extending junit.extensions.UITestCaseSWT, change your class to extend com.windowtester.runtime.swt.UITestCaseSWT instead (as recommended in the javadocs).

Note: if a class you depend on has been deprecated and no preferred class is specified, please contact us so that we can provide API to suit your needs.

Option 2: Add Legacy Bundle Dependencies

If refactoring is infeasible, you can add a dependency on the com.windowtester.runtime.legacy and/or com.windowtester.swt.runtime.legacy bundles as needed.

Timeline

5.0.0 (March 2010)
Legacy API removal and migration with supporting tooling
3.7.0 (January 2009)
Complete legacy API Deprecation
Migration of legacy API SWT Conditions
Migration of (internal) legacy SWT Selectors and Matchers

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.