Eclipse Tip: Use the Execution Environment to Create Portable Java Projects
In Eclipse, creating Java projects is easy—you invoke the New Java Project wizard, enter the new project's name, click Finish, and you're done. If you need to modify the default project configuration, you can do so right there in the wizard, or accept the defaults and make changes later.
When setting up a larger project, such as one that you plan to share with others, you should try to keep its configuration as portable as possible. For example, you should avoid using absolute paths when linking to resources, minimize the use of user-defined path variables, and so forth. This will simplify development environment setup for other developers who want to participate.
Specifying the JRE System Library
One particularly important project configuration property is the JRE System Library. It is the fundamental dependency that dictates which Java Runtime Environment your code is compiled against. You must have at least one JRE installed on your system to be able to run Eclipse. By default, this is the JRE used for all new projects.
Figure 1: Workbench Preferences page listing Execution Environments and their corresponding compatible JREs.
As you know, today's world of Java is not constrained to one version. Even though the latest stable release is version 5, many companies still use 1.4 and even 1.3. The brave developers may be experimenting with the latest beta release of Mustang (Java SE 6). Eclipse 3.2, at a minimum, requires Java 1.4 to run; however, you can use Eclipse to develop software for other versions of Java, regardless of the JRE used to run your IDE: In your Workbench Preferences, go to Java -> Installed JREs and add as many JREs as you like (of course, you have to obtain and install them first). When creating a new Java project, the wizard will let you select a JRE other than the default one.
This feature is very useful particularly when you want your code to work with older versions while running your Eclipse IDE in a newer JRE (otherwise, you'd have to exercise a great deal of caution to avoid inadvertently introducing dependencies on new APIs). However, it doesn't necessarily keep your projects portable; every JRE you add to your preferences is uniquely named. The name is defaulted to the JRE's installation directory. If you set up a project to use a JRE other that the default one, its name will be recorded in the project's JDT configuration (in other words, the .classpath file). But, what if other developers have a slightly different version of the required JRE (for example, j2re1.4.2_03 vs. j2sdk1.4.2_11), or simply name theirs differently? They'd get a nasty "Unbound classpath container: 'JRE System Library [j2sdk1.4.2_11]'" error after importing your project into their workspace. Sure, you can use an agreed-upon JRE name, but there is a better way....
Specifying the Java Execution Environment
Figure 2: Plug-in Manifest Editor lets you specify one (or more) Execution Environments for the plug-in.
Since version 3.2, Eclipse supports the notion of Execution Environment. It is essentially an alias for JREs matching a certain version of Java; for example, J2SE-1.4 covers all JREs compatible with Java 2 Standard Edition 1.4 (this, by the way, includes later versions, such as 5 and 6). To see the available execution environment definitions, open your Workbench Preferences and go to Java -> Installed JREs -> Execution Environments. Clicking an execution environment will display all compatible JREs that you configured. The ones that are a "perfect match" are highlighted. If you have multiple matching JREs, you may check the one you prefer to use.
As you can see, execution environments are much more portable than specific JREs. But, how do you set up your project to use one? The New Java Project wizard won't let you do it on the first page; however, you can click Next and select the Libraries tab on the next page. In it, select JRE System Library and click Edit. You will see a dialog that lets you choose an Execution Environment as an alternative to a specific JRE.
Alternatively, you can reconfigure your project after it is created. In the Package Explorer, right-click your project's JRE System Library node and choose Configure... from the context menu.
What About the Plug-ins?
Even though Eclipse Plug-in projects are essentially set up as specialized Java projects, it is not recommended to modify their Java Build Path settings directly. This is because the Plug-in project configuration is managed by the PDE. Luckily, the Plug-in Manifest Editor provides support for specifying the required Execution Environment for plug-ins. In fact, you can choose more than one. In the Overview page, there is an Execution Environments section that lets you do just that. After you add the desired execution environments to the list, click the Update the classpath and the compiler compliance settings link below it. This will not only update your project's Java Build Path, but also its compiler settings to match the language level corresponding to the selected environment (for example, Java Generics are only supported in J2SE-1.5 and later, the "assert" keyword in 1.4, and so on.)
The chosen execution environments also are recorded in the plug-in's manifest. At runtime, Eclipse will refuse to run a plug-in unless the runtime JRE is compatible with the plug-in's execution environment specification. (In other words, a plug-in may specify its minimum required execution environment.)
For more information about this feature, see the latest Eclipse Help:
About the Author
Peter Nehrer is a software consultant specializing in Eclipse-based enterprise solutions and J2EE applications. He is the founder of Ecliptical Software Inc. and a contributor to several Eclipse-related Open Source projects. He holds an M.S. in Computer Science from the University of Massachusetts at Amherst, MA. Peter can be reached at pnehrer AT eclipticalsoftware DOT com.