When Should the Great Migration Occur?

Before deciding when to convert a 1.0 program to 1.1, you must answer two questions:

What version of the Java runtime environment do the program's users have?
How eager are you to upgrade the program to 1.1?

Version Compatibility

As a rule, 1.0 programs run in any Java runtime environment, but programs that use 1.1 features don't run in 1.0 runtimes. Here are a couple of exceptions to the rule:

1.0 programs that depend on bugs in the 1.0 implementation might not work correctly in 1.1 runtime environments. You can find a list of incompatible bug fixes in JDK 1.1 Compatibility.
Programs that use only 1.0 features but are compiled under 1.1 often run in 1.0 runtime systems. You can take advantage of this fact to conditionally use 1.1 features, as described in [PENDING: link] Special Coding Techniques.
For example, assume you have a 1.0 program. Unless your program depends on a 1.0 bug, your program should work just fine in 1.1 runtimes. You can almost certainly use the 1.1 compiler to recompile that program, although you might see a few compiler warnings. The resulting 1.1 class files work in all 1.1-based runtime environments and probably will work in 1.0 runtimes. However, if you change the program to rely on any 1.1 API, the program won't run in 1.0 environments.
If some of your users have 1.0 environments and others have 1.1, you might choose to avoid upgrading until all the users have 1.1 runtime environments. Your program won't be able to rely on 1.1 features, but all your users should be able to run the program.
If your program is an applet that you want anyone on the Internet to be able to use, then you have to consider how many Web surfers have 1.1-compatible browsers. By the time you read this section, it's possible that very few users will still have 1.0 browsers. However, at the time of this writing, many users have browsers that support 1.0 applets but not 1.1 applets. For that reason, the online version of this book runs 1.0 versions of applets, unless the applet depends on a 1.1 feature.
If your program is an application and you distribute a runtime environment with it, then you can upgrade the program whenever you like. Similarly, if your program is an applet distributed only within your company, and everyone in your company uses a 1.1-compatible browser such as HotJava, then you can upgrade the program whenever you like.

Reasons to Convert to 1.1

Here are a few possible reasons to convert a 1.0 program to 1.1:

1.1 contains features that make the program better.
For example, if you want your program's custom components to work in GUI builders, then you should rewrite them to use the API necessary for JavaBeans components. Or you might want to use object serialization or inner classes. What's New in 1.1 lists all the new 1.1 features.

1.1 introduces new API for an old feature, and the new API will be used in all foreseen releases.
For example, the AWT event system has been rearchitected in 1.1. Although existing AWT components work with both the 1.0 and 1.1 event APIs, new components, such as the new 1.2 lightweight components, won't work with the 1.0 event API. If you upgrade your event code to 1.1, then you'll probably have less work to do when you switch to the 1.2 lightweight components.

The 1.1 implementation of some 1.0 API is incompatible with the 1.0 implementation.
This case is rare. When it happens, it's usually because the 1.0 implementation had a possible security problem, varied from platform to platform, or was simply buggy. For example, in 1.1 the System.out class variable is now final, to close a possible security hole. If a 1.0 program sets the value of System.out, then it won't work in 1.1 runtimes unless you change it to use the new System.setOut method.

You want to use the 1.1 compiler, and you want the program to compile cleanly.
You might want to upgrade a program simply to avoid compiler warnings about deprecated methods.

Migrating to 1.1