9-Apr-12 (Created: 9-Apr-12) | More in 'Eclipse'

A starters guide to Eclipse Java IDE

Goal

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. This document is written to help a java programmer to quickly download and start using Eclipse as their primary IDE in a couple of hours. The information presented here is a summary of what I have learned about Eclipse over the last couple of months. I am hoping this document would save the reader a ton of time in getting upto speed with Eclipse.

After reading this article you will have a very good understanding of the following

  1. Downloading and setting up Eclipse
  2. Working with java projects
  3. Working with your files and directories on your filesystem
  4. Working with server side java web development using Tomcat

The primary motivation of the article is to get you, a java programmer, up and running in Eclipse in a short amount of time. To do that, I have deliberately documented the oddities, road blocks, conceptual walls over a period of time. This article won't make you an expert in Eclipse, but will certainly make Eclipse a great tool for your java programming activities.

Downloading and setting up Eclipse

Downloading Eclipse is quite easy. But you will have to know a few more things than just downloading to start using Eclipse. For example, 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" upfront. What follows is a detailed explanation of these aspects with some recommendations.

Downloading Eclipse

You can find the main Eclipse download site at Main Eclipse download site. If you find that the main Eclipse site is slow, you may want to consider some mirror sites for Eclipse. Be forewarned though, I had hard time figuring out the directory structure and filenames at these mirror sites.

When you download you will see a file that looks like Eclipse-SDK-3.0.1-win32.zip. Expand this file into a convenient root directory. The zip file already has "Eclipse" as the root directory. You have just finished installing Eclipse. Very nice so far.

Setting the VM

Now you can go to the unzipped directory, which also happens to be the install directory, to see an execuatable called Eclipse.exe. If you run this Eclipse.exe, 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 would use. Hence, my recommendation is to set the vm explicitly. You can do this by first creating a shortcut to the Eclipse.exe and specify 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 worksapce 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 from the following document

Running Eclipse document from Eclipse.org

Setting the workspace

As pointed out, the second argument to Eclipse.exe points to the workspace. For Eclipse, a workspace is a logical collection of projects. A workspace is a drectory on your hard drive where Eclipse stores the projects that you define to it. For example you can define a "project 1" and a "project 2" in workspace-a, then proceed to create a workspace called "workspace-b" for holding another set of projects "project 3" and "project 4". As an added bonus, in a workspace, individual projects can reside anywhere on your hard drive and don't have to reside as children of the workspace directory.

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 you 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, create a directory first on your hard drive, and then use that name as one of the arguments to the shortcut as explained in the previous section.

By that logic it is possible to define a workspace for each project you may develop. What I have learned very quickly is that creating separate and numerous workspaces is counter productive as you have to manage that many Eclipse shortcut icons on your desktop and also not take advantage of the visibility to 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. Othewise when you install a new Eclipse you may inadvertently delete stuff from the old install directory.

So my recommendation would be the following

  • Create a directory just for the workspace outside of 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

Do I have to do anything special to create a workspace directory?

As pointed out, a workspace directory is just like anyother directory on the hard drive. 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 with in this workspace. If you take the default, then the project directories will be created inside the workspace. Or you can change the default to create the projects outside the workspace directory in their own project specific directories.

Running Eclipse for the first time

If you run the "Eclipse-install-dir/Eclipse.exe" with out setting it up for the JVM and a personalized workspace, Eclipse will prompt you for allowing it to use the install directory as its workspace. That is OK too, but make sure you use that workspace consistently. Otherwise if you change the workspace by mistake you won't see your projects that you have created earlier in the previous workspace.

If you used my recommendation and created a shortcut with JVM and the workspace, then Eclipse will not prompt you, but will load the home view of Eclipse allowing you to get started with Eclipse.

Working with Java projects

Working with java projects involve creating classes, creating packages, editing java files, refactoring java files, compiling java files, creating libraries or jars out of java files, debugging java files, 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

If "workspace" is the concept you have to understand for running Eclipse, "perspectives" is the concept you have to understand well for using Eclipse.

What you can do with Eclipse is organized into a number of views. For example some of the views are

  • java view
  • debug view
  • resource (default) view
  • cvs (source code control) view

Each view offers a set of pre-laid out windows and menus that are possible in that view. These views are called "perspectives". So you need to know how to switch between these different perspectives to do your work. You need to look for an icon called "open perspective" that will allow you switch between these different views or perspectives. You can also do this by going to the menu structure at the top 


menu/window/open perspective

Creating your first java project

Because we are trying to create a java project let us navigate to the java perspective. Go to "menu/file/new/project" and choose Java project. Here you can choose a project name and its location. The location of the project can be inside the workspace or outside the workspace. By default, Eclipse chooses a location inside. If you want otherwise, unclick the default and specify your own directory outside of the workspace. As a "name" and a "location" are sufficient to create a java project, you can choose to "finsih" 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. Package explorer window allows you to see your java packages and java source files inside 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. So 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. You don't have to 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 like "src" as the root for java packages and source files. You can accomplish this by carrying out the following steps.

  1. Create a sub folder called "src" under your project root
  2. Go to java build properties of the project
  3. Define the "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 that package. Say you give your java class a name "HelloWorld". In response Eclipse will create a "HelloWorld.java" source file inside 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 on. Well this is where Eclipse just shines. Eclipse allows you to maximize that view so that your edit window takes all the 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 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 only see pacakges and java related files. You will not know where the physical directories are created etc. To see this you can go to 


menu/window/show views/navigator

Navigator view will show you the exact file structure on the hard drive for your projects.

Thus far you know how to create java projects, packages, and files. Now it is to time turn the attention to building a java project, specifying depenedent jar files, and creating jar files of your own for reusable code.

Building your java project

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" menu item and turn off this option. I have grown to like this option for building projects or source files automatically. Very efficient overall. There may be times where you want to turn this feature off. Your choice there.

To see the "Build Automatically" in action, add a main method to the "HelloWorld" java class. In Eclipse it would have been nice to see an option to add a main method to a java class automatically at this stage, once the class is already created. Perhaps there is. But I don't know this yet. If you were a bit psychic though, you would have known of this need and would have chosen to generate the main method while you had created this class. Nothing lost, here is a sample main method 


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 save operation would have already had your project built. To debug the project, Look for a "bug" icon on the tool bar and look for its drop down. 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 the document.

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 these jar files that your project depends on 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 them, you can debug into the jar file as well. You can drill down into this jar file and pick the class file you want to debug, and double click on 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 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 round about. 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 "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

So 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 additionally 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 sub directories (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 the project hierarchy or inside 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 on "Finish" to produce the jar file.

If you were to keep the jar file inside the hierarchy you can right click on 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 every thing you need - neither more nor less.

Generating the jar multiple times

The jar generation process described above can be quite repetetive if you are generating the jar a lot of 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 with out 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 


<?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>

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 chosing "Open Jar packager".

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 and expand into a jar file to see the constituent directories and files. You can drill down into these dependent jar files and pick the class file you want to debug and double click on 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 heplful for remote debugging, which is covered later in the document as part of working with WAR development.

More on deugging 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 more complicated for Java because, a workspace could 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 debug. In Eclipse this is handled through debug configurations. These are named configurations where you specify all the relevent 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 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 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 selction 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 up the chain and 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 the currently available debug configurations. You can edit a debug configuration to match your new specs or create a new degug configuration by choosing class name and the rest of the debug dependencies.

So far I have summarized the activities related to the creation and build of java projects. Let me now show you some hints or tips that would make you more productive as you start working with multiple files in your projects.

Working with files in your java projects

The goal of an IDE is to provide the developer enough visibility for all the needed assets and being able to manipulate them. The effectiveness of an IDE lies here. Eclipse has more than adequate facilities in this area. This section of the article intends to lay these out for you in the form of hints and tips.

Working with file associations

Sometimes your project contains files that don't have any built in editors. In that case Eclipse will kick off an underlying operating system edit. In windows this might open a notepad or any other registered program in the OS. This file will be opened outside of Eclipse. Sometimes the editors inside of Eclipse are perfectly capable of handling these (particularly text based, but with varieties of extensions) files. To tell Eclipse to open these files in the text editor (or in one of the supported editors) you can use Eclipse's file associations configuration. You can get to this configuration by going to 


window/preferences/workbench/file associations

Here you can add new file types and also editors that can handle these associations. Once these are defined, you will be able to double click on the files in your project and have them take advantage of Eclipse's nice windowing capabilities. Particularly the ability to work in regular/maximized views seemlessly.

Alternatively if you don't want to define a file association, you can drag the file into the editing window to force the editor to try to open that file. This is especially useful for batch files. Because double clicking on a batch file could result in two connotations. It might mean to run the batch file or to open it. If you leave the double click to "run" the file, you might want to drag the batchfile on to an editor to edit that batchfile.

Editing files

The ability of Eclipse to go from a complex view with many windows to a simple view with only one window and go back where you started is very very nice. Eclipse does this very quickly as well. This is not limited to just two levels, as I have seen it done with three levels as well, all tied to the window/section title bar mouse clicks. The nice thing is you can do this not only to the editor windows but also to such utility windows as debug windows, console windows etc.

Another thing I use while editing files is ctrl-shift-f4. This will close all current windows that you are working on, particularly the editor windows. Sometimes you have oppened so many files, it just doesn't make sense to squinch your eyes to find out which file you want.

Also, while you are busy working with files in the edit space, you may have navigated to a variety of places in your package explorer, making it hard to locate those files in the package explorer or navigator. You can sync these views by right clicking on the file in the editor and choosing "show in package explorer". Sometimes this option is not available from the right click on the editor window of your file. In that case, go to "Navigate/show-in-package-explorer". This particular menu is a smart menu. Depending on where you are this can show one of the following 


navigate/show in/navigator
navigate/show in/package explorer

Which of the above you see depend on the context (perspective).

Searching for files

The usual file search facilities are available in Eclipse through search menus. For example you can search for files that contain some text you are looking for. What is pleasantly unusual after that is, when you choose the file to view from the search box at the bottom, notice the narrow right margin next to the editor window. You will see tiny rectangles or markers indicating the position or line of the occuring or found text. Simply click on that marker and you will be taken to that line of that file.

what more, if you were to change the source file to fix some of the searched patterns, that file reference will disappear from your search collection at the bottom. This allows for a very quick search and replace operation across a large number of files.

These markers are also quite helpful in the auto compilation mode where you can just follow the errors/issues and fix them. In the auto build mode these markers also get aggregated to the package level and also to the project level. That means if you see something wrong with a file because it did not compile, or if there is a warning, you will see a marker on that file and on that package and also on that project. This allows for a quick location of the errors. Just follow the markers starting at the project and down to the file.

Searching for java source files

Another unusual but nice facility Eclipse provide is searching or opening a java type. Go to "menu/navigate/Open type". This will open a dialog box where you can enter a partial class name and Eclipse will narrow the search with every letter you type. This is quite useful in locating java classes quickly irrespective of what packages they are in. If you are in a java perspective you can get to the same menu by typing the key combination ctrl-shift-t.

The getters and setters simplified

When a java class is being defined, it is quite tedious to write getters and setters for the private or protected variables. Eclipse offers to write these methods for you via the menu item "file/right-click/source/Generate Getters and Setters". The ensuing dialog will guide you for choosing getters and setters to your liking. The base menu "file/right-click/source/" offers the following additional goodies as well

  1. Override/implement methods: for implementing virtual functions from base class
  2. Add constructors from superclass: if you were to call the baseclass constructors
  3. Generate constructors using fields: If you were to create a constructor using some or all of the fields
  4. Generate delegate methods: If you were to expose some functions of member variables as functions of the parent class

The magic of "open declaration"

While walking through java code you may want to see where a given class or a method is originally defined. By placing the cursor on one of these words, right click and choose "open declaration" to have Eclipse open the source file where the object, whether it is a class or a method, is originally defined.

Creating an import statement for a class

Another wonderful thing Eclipse does is fill in a package import name for you when you try to create a type in the source code and that type is not already imported. Just hightlight the type string and do "right click/source/import type". This will import that type for you. Or you can use the key combination ctrl-shift-m while high-lighting the type name.

Optimizing imports

I don't use this often, but if you have imported types with a *, then you can use organize imports to import only those types that are used. This is automatic. Just choose the option and the file will change to include the specific types. Note that you will not be prompted for any confirmation.

Working with deprecations and errors

As mentioned earlier attention markers are quite helpful in the auto compilation mode where you can easily follow them and fix them. In the auto build mode these markers also get aggregated to the package level and also to the project level. That means if you see something wrong with a file because it did not compile or there is a warning then you will see a marker on that file, and on that package, and also on that project. This allows for a quick location of the errors. Just follow the markers starting at the project and down to the file.

Also compilation errors, warnings and other messages show up in the "task window" at the bootom of your screen. You can configure how much information you want to see here. On the top right hand corner of the "task window" you will see an icon for "filters". This dialog allows you to configure the task view.

I normally chose the following

  1. Show only errors
  2. Show errors only for the selected resource and its children

With that setting, if I select a project in the IDE, then all the problems related to that project will be shown. If I expand the project and choose a package with in that project, I will only see problems related to that package, so on and so forth.

Working with code blocks

The recent release of Eclipse helps out with code blocks in multiple ways. when a cursor is positioned somewhere in the editor the enclosing programming unit (function, class, etc) block is indicated with a thin (green) vertical bar in the left margin. As you type "if", "while" etc, Eclipse helps out with anonther color coded vertical bar indicating the span of the block. This seems to have a mind of its own in 3.0 release. Hopefully will get better in the next release. Also if you position the cursor next to an ending brace, the matching brace is enclosed in a color coded lightly visible rectangle.

When the code blocks are small one can grasp them in their entirity. However if you have an extended "if", it helps to realize the start and end of that code block. Even when you are careful not to extend your "if" blocks, you have the "try/catch" blocks to contend with, and even function boundaries. When this facility is not there you may not have missed much, but once you have used it, you may find yourself looking for it.

Working with the right margin

The right margin of your editing area is used quite effectively in Eclipse. The lines or areas requiring attention are subtly high-lighted using small colored rectangles. Using these markers you can quickly tell if there are deprecations in that file or errors in that file or search strings in that file. Moreover by clicking on these markers you can go to that area quickly to resolve the issue.

Working with simple projects

You may think of IDE as a place to compile, but it is also a good editing environment that brings together disjointed directories in to a single visual environment. For example, while working with a project, you may want to monitor log files, or look into external batch files or write notes in another part of a directory tree. For things like this you can use the Eclipse IDE to create a simple project and hook up your directory root in to the workspace as a simple project. This allows you to view/manipulate files in that directory without leaving the editor. For example I use a project called "work" pointing to "c:\work". This allows me to work with text files in this directory within the ide environment.

Working with war projects

There are probably a number of ways to work with war projects. One can use a tool like Websphere Studio or MyEclipse studio. But these solutions require a substantial investment in cost and learning (atleast the websphere). The first goal for me is to document how one can use Eclipse with out any additional plugins to develop simple websites using Tomcat. This mode of working is especially useful for simple tools like Aspire/J2EE that require just an editing environment to be productive. I call this mode "Basic War development" in Eclipse.

What is possible with Basic WAR Development in Eclipse

  1. Visibility to all your files with in the war directory
  2. Ability to text edit all files including html, jsp, web.xml, and properties in one place using one editor
  3. No other tools but the basic Eclipse is required
  4. You can have java files compiled and be part of the war
  5. Debugging can be done via the remote debugging facilities of Eclipse

What is not possible with Basic WAR Development in Eclipse

  1. It is harder to find specialized editors for each file type in the war
  2. Debugging is a bit round about
  3. Difficult to debug into the JSP files

One will have to use a commercial solution to take advantage of these additional benefits.

How to create your war project

A war project has a specific structure as stipulated by the servlet (J2EE) standards. My assumption is that you are already aware of this directory structure and know how to create this directory structure and have it served up by tomcat. Briefly this directory structure on your hard drive looks something like: 


\my-webapp
   \java-src
      \com\my-com\my-project\my-mod\my-file.java
   \web-inf
      \lib\my-jar.jar
	  \web.xml
   \module1
   \configuration
      \a.xml
	  \b.properties
   \log
   \index.html

Once you have this directory structure in place, simply create a java project and specify the target directory as the webapp directory. Eclipse somehow seem to identify the inner jar files as dependent jar files. Eclipse will also automatically create a .classpath file and a .project file in that directory.

The .classpath file contains the jar files that are going to be used to build any java files if they were to be present. This is an xml file that can be tuned manually if needed. The .project file contains the project specific information in an xml format. Both these files are usually managed by the IDE and visible only in the navigator window. But when you migrate between different Eclipses or different boxes it might help to manually change these files to the new environments with out recreating the projects from scratch.

Settingup file associations for the war project

Once the project is in place the next thing to do is to set up the file associations to the following most common file types in your war project. These file types are

  1. .log
  2. .properties
  3. .html
  4. .jsp

You can do this by going to "window/preferences/workbench/file association". I usually set them to a plain text editor. But if you happen to find a good editor for each one of those separately, do use those specialized editors. I haven't had much luck. Perhaps I will post a note when I do find one.

Locating files in the war project

The next thing you do often is to locate a file in your war structure and try to edit it. For this you chose "search/search" available as "ctrl-h". Just type in the filename or a partial filename and you will be taken there. When the files are too many in the pane you can use "ctrl-shift-f4" to get rid of them all. Once in a while you want to go back to the previously opened files. You can do this by going to the "file" menu. By default it seem to show 4 files. I suppose one can increase this number. It will be nice to see this list as part of the editor pane.

If you are looking at a log file, Eclipse usually prompts you if the file has changed since you visited it last. Sometimes it seem to miss this. In that case you may have to close the file and reopen it. Or you can try the following

  1. Locate that file using alt-shift-w in the package explorer
  2. right click on the file
  3. Refresh

In summary the many ways of locating files in Eclipse are

  1. Search by name
  2. Search by text inside the file
  3. Use package explorer
  4. Use navigator
  5. Use previously viewed files
  6. If java file use opentype ctrl-shift-t
  7. Use Alt-shift-w when you are viewing a file

Property files and character sets

I have noticed a couple of times that after editing a property file in the Eclipse text editor it will introduce some strange characters in the file, making the java property file reader to throw an exception. What makes hard is that these characters are invisible in regular editors. Only option is to carefully retype the lines using trial and error elimination.

Use Alt-shift-w for synching your views

When you are looking at a file in the text editor window you click "alt-shift-w" to show you that file in the navigator or the package explorer. This is useful in the following cases especially

  1. You are looking at a readonly file and you want to change its attribute
  2. You want to refresh a file
  3. You want to find a sibling file in the same directory

A note on regular expression search in Eclipse

When you are searching for a file with some text occurance inside, you can use a regular expression to specify wild cards. For example with the following expression 


*GetEmployees*

you would hope to identify files that have this text in those files anywhere on the line. But this will fail with a 


Dangling meta character

message. To correct it, do the following 


^*GetEmployees*

The leading ^ carat symbol indicates the begining of a line.

Using Remote debugging for WAR projects

So far I have discussed a WAR project with no java source files in it. This section will talk about how you can use Java as part of your WAR development effort and also being able to debug into java source files. Note that this does not cover the JSP debugging. This mode is especially usful for development systems like Aspire where the JSP pages are used only for painting, and all the business logic is acomplished by server side parts.

Step1 - Create a source directory for your java source files

Start out by creating a sub directory called "src" under your web app root. Then proceed to define the "src" folder as your source folder for the java files. You can do this by "your-project/right-click/properties/java build path/source/Add Folder". Also on the same dialog box, change the output folder to "webapp-root/web-inf/classes". This will allow for the generated classes to be available for tomcat to load them from the war path.

Step2 - Create a batch file for starting your tomcat

Use the following code to create a batch file for starting your tomcat in debug mode 


@rem mystartup-debug.bat
@set CATALINA_HOME=w:\satya\i\tomcat5028
@set JAVA_HOME=c:\java142
set JPDA_TRANSPORT=dt_socket
set JPDA_ADDRESS=8587
@set exe=%CATALINA_HOME%\bin\catalina.bat
@call %exe% jpda run %1 %2 %3 %4

Notice how jpda settings are set to socket and a socket address. Also see how the first argument to tomcat is mentioned as "jpda". This batch file is based on tomcat 5.0.28. For your specific version of tomcat you may have to tune it accordingly. When this file is run Tomcat's jvm will start in debug mode. In this mode the jvm will be listening on the above specified port "8587".

Sometimes if the JVM is not able to acquire the port it may start in regular mode abandoning listening on that port. One way to know whether if it is waiting on that port or not is to use the "netstat" tool.

On a windows command prompt do 


netstat -a

This will print out all the server ports that are being listened on. Befor running your batch file, you should not see this port in the print out. After running your batch file you should see this port in the printout. Sometimes you will not see this port after running your batch file. This means most likely, for an unknown reason, JVM has failed to acquire this port. In my case I have tried a different port number and that seem to succeed.

Step3 - Hooking up Eclipse so that you can debug your webapp

Once your tomcat is running in debug mode, go on to Eclipse and locate the debug/run configurations. You can do this by going to the debug icon drop down in the menu. Choose the "debug ..." option. This opens up a dialog box with available debug configurations. Choose Remote Java Application and click "New". You will have to chose the following on the ensuing dialog box

  1. project: your web app project
  2. connection type: socket attach
  3. host: local host
  4. port: 8587

You will have to chose the same port number that you have used in your debug batch file. The "source" tab is an important tab in the remote debug configuration dialog. It tells Eclipse where to look for the source files in addition to the project you have chosen. For example if you are using external jar files as part of your setup, you can set them up in a separate project and include that project as part of the source tab.

Once you create this configuration, you can save it and use that configuration for debugging. You will be able to put break points in the "src" folder that you have created earlier under your web application project. You can also put breakpoints in the external jar files project that you may have created.

Summary

That concludes this article with out getting into the advanced options of Eclipse. With the information presented here you will be able to effectively download and start using Eclipse for the following purposes

  1. Develop and debug regular java applications
  2. Develop and debug web applications that can run under tomcat
  3. Effectively navigate your filesystem for editing purposes

References

1. Authors Blog

2. Frequently attempted tasks in Eclipse in a tabular format

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