Skip to main content

A Starter's Guide to the Eclipse IDE, Part 1: Installation and Projects

March 2, 2005

{cs.r.title}









Contents
Downloading and Setting up Eclipse
Setting the VM
Setting the Workspace
Working with Java Projects
Understand Perspectives
Creating your First Java Project
Creating a New Java Package
Specifying an Alternative Folder as the Java Source Folder
Using Maximize/Restore Views for Effectively Editing Java Source Files
Changing the Generated Source Template
Seeing Your Physical Files
Moving Between Navigator View and Package Explorer View
Building your Java Project
Specifying .jar Files for Your Java Project
Creating a .jar File
Generating the .jar Multiple Times
Setting Break Points
Debugging Your Java Project in Eclipse
Summary
References

The Eclipse IDE is a productive and fast development environment for Java.
Nevertheless, the learning curve is deceptively difficult, even for an
experienced Java programmer. This difficulty stems largely from the power and
flexibility of the Eclipse IDE. Over a period of time, I have deliberately
documented these oddities, road blocks, and conceptual walls.

The resulting material is is broken down into a series of three articles. This
first article talks about installing Eclipse and working with basic Java
projects. The second article talks about using Eclipse not only for managing
Java projects, but also the OS environment that usually surrounds your Java
projects, such as files and directories on your local drive. The third article
extends the ideas of part two to show you how you can manage web
applications using the same paradigm.

This article won't make you an expert in Eclipse, but will certainly make
Eclipse a great tool for your editing and Java programming activities. The
material presented here should help make you
comfortable and productive in the Eclipse IDE environment.

On the other hand, in a twisted sort of way, this article is not about
Eclipse. This article is really about the search for a productive working
environment for your Java-related activities. Imagine on a Sunday, when you should be enjoying the Florida mornings, instead you set
out to find a solution to your Java development environment woes. You are too
lazy to go to visit the local computer store and get vexed by their return
policies. Or you don't want to feel cheated by expiring licenses, like those of
the anti-virus software that came with your PC. Or you don't want to go
through 400 pages of a textbook on how to use an IDE. You have four hours to kill.
Can you find, download, install, and be happy and on your way to organizing
and working with your Java thoughts? Then this article is for you. Eclipse happens to fit the mold, although it took me multiple months to get here.
With Eclipse and the notes that are available here, my belief and wish is you
won't have to take as long as I did.

Downloading and Setting up Eclipse

Downloading Eclipse is quite easy. Head to the main Eclipse download site. If you find that the main Eclipse site is slow, you may want to consider some mirror sites. Be forewarned, though: I had hard time figuring out the directory structures and filenames at these mirror sites. After downloading, you will find it is better to set the JVM that Eclipse is going to be using to run itself. It is also better to understand the concept of an Eclipse "workspace" up front. What follows is a detailed explanation of these aspects with some recommendations.

Note: These instructions are specific to the Windows release.

Setting the VM

Now you can go to the unzipped directory, which also happens to be the install directory, to see an
executable called Eclipse.exe. If you run this, Eclipse will try to locate a
JVM on your hard drive (not necessarily from the registry). As a result, you would not be that certain what
JVM Eclipse will use.
Hence, my recommendation is to set the VM explicitly. You can do this by first creating a shortcut to Eclipse.exe and then specifying the VM and workspace arguments as follows:

i:\Eclipse.exe -VM i:\jdk142\bin\javaw.exe -data d:\my-Eclipse-workspace

The first argument is the Java executable. The second argument is the workspace. I will talk about the
workspace in the next section. Do read that section before invoking Eclipse, as you will get confused as Eclipse will prompt you to enter a workspace. You can find more about Eclipse startup options in this "Running Eclipse" document from Eclipse.org.

Here is a visual for setting up this shortcut on the Windows platform.

Figure 1

Setting the Workspace

As pointed out above, the second argument to Eclipse points to the workspace. For Eclipse, a workspace is a logical collection of projects. A workspace is a directory on your hard drive where Eclipse stores the projects that you define to it. When you specify this directory name to Eclipse, Eclipse will create some files within this directory to manage the projects. The projects controlled by this workspace may or may not reside in this directory; this depends on what you chose while creating new projects via Eclipse in this workspace. If you take the default, then the project directories will be created inside of the workspace. Or, you can change the default to create the projects outside of the workspace directory in their own project-specific directories.

if you don't specify the workspace on the command line, then Eclipse will ask you at startup where the workspace is, while giving you an option to use the install directory as the default workspace. On this startup screen, Eclipse also offers to take that default directory and not ask you again. Alternatively, you may want to specify your own workspace and not use the default. To specify your own workspace directory, first create a directory on your hard drive, and then use that name as one of the arguments to the shortcut, as explained in the previous section.

Figure 2

Although it is possible to define a workspace for each project you may develop, creating separate and numerous workspaces is counterproductive, as you have to manage that many Eclipse shortcut icons on your desktop and also cannot take advantage of the visibility of multiple projects at one time. My current thinking is to put most of the projects in just one workspace. If you are going to use one workspace, one thinking is, "Why not use the default workspace and not worry about creating a new one?" This will work if you keep your projects outside of this directory.
Otherwise, when you install a new Eclipse, you may inadvertently delete stuff from the old install directory.

My recommendation is the following:

  • Create a directory just for the workspace outside of the Eclipse install directory.
  • Use that directory as your one and only workspace to manage most of your projects.
  • Specify that directory on the shortcut.
  • Call that shortcut "my-only-Eclipse" or something of that nature.

Make sure you use that workspace consistently. Otherwise if you change the workspace by mistake, you won't see the projects that you have created earlier in the previous workspace.

Working with Java Projects

Working with Java projects involves creating classes, creating packages, editing
Java files, refactoring Java files, compiling Java files, creating libraries or .jars out of
Java files, debugging Java files, and running Java files. For a Java programmer, these are some of the very common tasks. What follows is an explanation of how Eclipse does each of these tasks.

Understand Perspectives

A perspective is a view of your current project using a set of pre-laid-out windows and menus that are possible in that view. The current perspective guides you to what you can do with Eclipse. Some of the views are the Java view, the debug view, the resource (default) view, and the CVS (source code control) view. To switch between these different perspectives, click on the icon called "open perspective." You can also do this by going to the menu structure at the top of the screen.

menu/window/open perspective
.

The following illustration is an annotated picture of the Eclipse environment in its "Java" perspective. Some of the aspects that are talked about in this article are highlighted in the document.

Figure 3

Creating Your First Java Project

To create a Java project, navigate to the Java perspective. Go to the menu -> File -> New - > Project and choose
"Java project." Here, you can choose a project name and its location. Recall from above that the location of the project can be inside or outside of the workspace. By default, Eclipse chooses a location inside. If you want otherwise, un-click the default and specify your own directory outside of the workspace. All that is required to create a Java project is a name and a location, so choose to finish the wizard to see your Java project created.

Subsequently, the perspective in Eclipse will be changed to the Java perspective, allowing you to see your
Java project in the Java package explorer. The package explorer window allows you to see your
Java packages and Java source files inside of your Java project. At this time, as you haven't yet created any packages or
Java files, your view will not show any Java packages. You will only see a project with no files or packages in it.

Creating a New Java Package

Right-click on the package explorer of your Java project and create a package called

com.testcom.testapp.testmod
.
You can type that whole package string once, or you can create those directories individually. Using the project root as the root, Eclipse will create the directory structure mapping to the package names.

Specifying an Alternative Folder as the Java Source Folder

The previous exercise assumed that your Java files and Java packages will use the project root directory as the root directory. Sometimes, for the sake of separating Java source files clearly from the rest of the project, you may want to use a subdirectory such as src as the root for Java packages and source files.

For example, in addition to the Java source files, your project may contain documents, properties files, XML files, XSLT files, dependent .jar files, and generated .jar files. Also, while you are in the package explorer view, Eclipse has a habit of listing all of your Java packages and the dependent .jar files one time in one view along with the other subdirectories. This view can be quite crowded, and fails to give you the structure of your source files.

When you start developing web applications, you may want to separate the HTML content and JSP files from the Java files that would form a .jar file to go along with the web content.

You can accomplish this by carrying out the following steps.

  1. Create a subfolder called src under your project root.
  2. Go to the Java build properties of the project.
  3. Define src as the source folder for Java.
Using Maximize/Restore Views for Effectively Editing Java Source Files

With a Java package in place, you are ready to create a Java source file in Eclipse. In the package explorer window, right-click on your package to create a class inside of that package. Say you give your
Java class the name HelloWorld. In response, Eclipse will create a HelloWorld.java source file inside of that package.

The created Java source file is automatically opened for editing in the center window of the screen, with a bunch of windows all around. You will start feeling cheated with so little space for your expressive hand to work in. This is where Eclipse just shines. Eclipse allows you to maximize that view so that your edit window takes up all possible space. This functionality, of maximizing an edit window and restoring that edit window back to its original position, is tied to the title bar of that edit window. Double-clicking the title bar of the edit window will maximize the view (or vice versa, if it was already maximized).

Changing the Generated Source Template

When Eclipse generated your Java class, it used a template to spit out code for your Java class. You can change the template for this generation by following the comments in this generated file.

Seeing Your Physical files: Moving Between Navigator View and Package Explorer View

So far, if you are in the package explorer view, you see Java packages and Java-related files. There are certain directories and files that are not exposed in this view. For example, the .classpath and .project files are visible only in the navigator view. Also, if you specify an output directory for your Java class files, this directory and the class files are visible only in the navigator view.

A navigator view will faithfully reflect what is on the file system. To access the navigator view, you can do the following.

menu/window/show views/navigator

There is another time when a navigator view could be useful. If you have an extended hierarchy of packages, the package explorer only shows a flat view of these packages. It is possible, through navigator view, to look at files in a deeply nested hierarchy with out getting crowded by other files. In the navigator view, the .jar files are nicely tucked away in a jar subdirectory and won't crowd the main window. The source files are also tucked away in their own subdirectory, improving the visibility and comprehension of your structure.

Nevertheless, the majority of the time, all of the functionality that is available in the navigator view is also exposed in
the package explorer view as well, especially for directories that do not contain Java source files.

Building Your Java Project

Thus far you know how to create Java projects, packages, and files. Now it is time to turn your attention to building a
Java project, specifying dependent .jar files, and creating .jar files of your own for reusable code. In Eclipse 3, the default setting is to build a Java project automatically. If you don't want this, you can go to Menu -> Project -> Build Automatically and turn off this option. I have grown to like this option for building projects or source files automatically.

To see Build Automatically in action, add a main() method to the HelloWorld
Java class. If you were a bit psychic, though, you would have chosen to generate the main method while you had created this class.

public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("Hello world");
  }
}

Now add this code to your Java class and save your file. This saves the operation builds of your project. To debug the project, Look for a "bug" icon on the tool bar and look for its drop-down menu. While focused on the HelloWorld Java file, you can choose "debug as a
Java application" to run your Java class in debug mode.
You will see the console output in one of the bottom tabs.

The above action basically created a debug configuration for your file, identifying your class as the runnable class, etc. If you do this for another
Java file in your project, that would create another debug configuration with that name. Or you can manually create a debug configuration identifying the classname that contains the main method, etc. There is more to debugging in Eclipse, which is covered later in this article.

Specifying .jar Files for Your Java Project

Once you build a bare-bones Java project, your most likely next need will be to start using other
Java libraries. You can specify the .jar files that your project depends upon as follows:

your-java-project/right-click/properties/java build path/libraries/add external jars

When you add a .jar file as a dependency it will show up in the package explorer at the same level as your project. If the .jar file has
Java source files as well as Java class files in it, you can debug into the .jar file as well. You can drill down into this .jar file, pick the class file you want to debug, and double-click it. Eclipse will open up that class file with a suggestion to add the source code. At that time, you can specify the same .jar file again as the source for the
Java class files for which the .jar file has the source. It is also possible to provide source via a source directory, as well, for that binary-only .jar file.

Creating a .jar File

If you are developing reusable components, it is quite likely that you may want to package your libraries as .jar files. Creating a .jar file in Eclipse is a bit of a roundabout process. The .jar creation process is almost considered external (or orthogonal) to the development cycle. Let me start with the basics. One would think that you can specify the .jar options as part of the project's build options. But that is not so. To create a .jar of your project, your access path is:

your-java-project/right-click/export/jar file

Creating a jar file is placed under "export." Moving on, the .jar export page offers you lot of options, such as what files need to be kept in the .jar and what files need not be kept in the .jar file. Typically, I choose the following files to be in my .jar:

  1. All Java source files starting at the source directory.
  2. All Java binary class files starting at the source directory.
  3. Any additional needed directories with properties files or XML files.

I also verify the following during .jar generation:

  1. Check options for Java source files and class files.
  2. Uncheck the Eclipse project-related files on the right-hand side of the window.
  3. Expand the project and uncheck the unwanted subdirectories (this is quite important).

Once you are done with options, you can choose a .jar file target for this export. This target .jar path may be outside or inside of the project hierarchy. If it is inside, make sure you exclude that directory during the .jar generation process as part of the .jar file. Then click Finish to produce the .jar file.

If you keep the .jar file inside of the hierarchy, you can right-click it and open it using a system-registered editor. In Windows, if the .jar file is associated with
WinZip, then this will show you what the final .jar looks like. It is always a good idea to check the final .jar to make sure the .jar has everything you need--neither more nor less.

Generating the .jar Multiple Times

The .jar generation process described above can be quite repetitive if you are generating the .jar many times. The second page of the .jar creation wizard has an option to save the .jar file creation parameters as a .jar description file. You can use this description (file) next time around to generate the .jar file without going through the lengthy, (worse yet) error-prone, selection process all over again. To accomplish this, on the second page of the wizard, choose a file name for this description file. This will create an XML file in your project that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<jardesc>
    <jar path="W:/satya/i/Eclipse/workspace/test/jars/test.jar"/>
    <options overwrite="false"
    compress="true"
    exportErrors="true"
    exportWarnings="true"
    saveDescription="true"
    descriptionLocation="/test/jars/test.jardesc"
    useSourceFolders="false"
    buildIfNeeded="true"/>
    <manifest manifestVersion="1.0"
    usesManifest="true"
    reuseManifest="false"
    saveManifest="false"
    generateManifest="true" manifestLocation="">
        <sealing sealJar="false">
            <packagesToSeal/>
            <packagesToUnSeal/>
        </sealing>
    </manifest>
    <selectedElements exportClassFiles="true"
    exportOutputFolder="false"
    exportJavaFiles="true">
        <javaElement handleIdentifier="=test/<com.testcom.testapp.testmod"/>
        <javaElement handleIdentifier="=test/<properties"/>
    </selectedElements>
</jardesc>

The next time you want to generate that .jar file, just right-click on this .jar description file
and chose "createJar."
If you want to modify this description file, either you can do it manually
or invoke the GUI again by right-clicking on this file and choosing "Open Jar packager."

It is also possible to maintain a multiple set of these definitions for various purposes. For example, a deployment .jar might not include source files or even the binaries used in unit testing.

On the question including source files, for IT corporations, I strongly recommend to include the source files.
I have been burned too many times by not having a matching source for the .jar that is in production.
Although I was able to reverse engineer using jad (a wonderful tool), I wished they had included
the source code along with the .jar file.

For Aspire/J2EE, the open source product I work on, I have gotten into the habit of .jarring the source along
with the binaries. Without binaries it would have been 600K and with binaries it is about 1.4M. I think that
extra space is well worth it when it comes to debugging or discovering the source file when one needs it.

Setting Break Points

While viewing a Java file in the editor, just double-click in the left margin against a source line to put a break point. You can put break points in the dependent .jar files, as well, as long as you have access to the source files of those .jar files. Eclipse allows you to drill down into and expand a .jar file to see the constituent directories and files. You can drill down into these dependent .jar files, pick the class file you want to debug, and double-click it. It will open up that class file with a suggestion to add the source code. Here you can specify the same .jar file again as the source if the .jar file has the source as well, or use an alternative source. This is especially
helpful for remote debugging, which is covered later in this article as part of working with WAR development.

Debugging Your Java Project in Eclipse

In older IDEs, debugging used to be "just click a button," but is a bit more involved in modern IDEs, especially in
Java. Older IDEs, especially under Windows, worked with one project that usually resulted in a single executable file. So a "debug" in the IDE implied only one thing: build and run the only executable that is in the project. But the modern IDEs like Eclipse and Visual Studio can build multiple projects in a single environment. This means a single "debug" button is ambiguous. This is further complicated for
Java, because a workspace can not only include multiple projects, but each project may have more than one executable
Java file with a main method in it. This is an additional ambiguity that one has to deal with while debugging or running a program in
Java.

Once you understand these issues, you can anticipate (perhaps with a bit of intuition) how each IDE would have solved the debug ambiguity problem and how they implement single-button-click debugging. In Eclipse, this is handled through debug configurations. These are named configurations where you specify all of the
relevant material for the IDE so that the IDE can unambiguously resolve the Java class that has a main method to start running.

Let me consider first debugging a Java class that already has a main method in it.

  1. Select a Java class with a main method in the package explorer.
  2. Locate the debug drop-down menu in the top button menu.
  3. Choose debug as Java application.
  4. Alternatively, you can also right-click on the Java source file and choose "debug/java application."

Either choice will start the debugging process with stdout going to the console. In addition, Eclipse will create debug/run configuration for this
Java class with its unqualified name in the work space. You can view/change this configuration later by going to the debug menu and choosing the "debug ..." menu item.

Alternatively, you can highlight a package and choose to "debug as java application." Eclipse will then does a type search for a class with a main method inside of that package. Then it will allow you to pick a class from the list of classes. This
selection will not only start the debug process, but also creates a debug configuration as mentioned above. This method is equivalent to the method above, except that this time Eclipse allowed you to choose that debug class a bit differently.

You can take this process one step up the chain; choose the project and ask Eclipse to do "debug as a
Java application." This time, Eclipse will try to locate a class with a main method in all of the packages and also in the dependent .jar files.

Alternatively, if you chose the debug menu item "debug ..." then Eclipse will show all of the currently available debug configurations. You can edit a debug configuration to match your new specs or create a new debug configuration by choosing the class name and the rest of the debug dependencies.

Summary

This article presented a sequence of tips for getting up and running with your most common development tasks in the Eclipse IDE. In the next part of the series, you will see how to work with files and directories on your file system in addition to your Java programming needs. The third part of the series will conclude with a look at server-side Java web development using Tomcat.

References


1. Author's web log


2. Frequently attempted tasks in Eclipse, in a tabular format


3. A small FAQ I manage for Eclipse, written as I run into issues with Eclipse


4. Some notes on Eclipse and CVS for collaborative development

width="1" height="1" border="0" alt=" " />
Satya Komatineni is the author of AspireJ2EE (http://www.activeintellect.com), an open source web development RAD tool for J2EE/XML.