System.err.println();
Comp314 Eclipse Clinic: Taylor Johnson [ttj@]
Original Clinic Material: Kyle Derr [derrley@]

Welcome!

Eclipse is a powerful tool, making it worth a student's while to learn how to use it. Because many complain of its harsh learning curve, I have been asked to give it a helpful introduction. Because I know many of you will be reading this document without having attended the clinic, I'll try to make it fairly complete, but I'm not going quite as far as making this document a step-by-step how-to for everything we're likely to cover in the clinic. That is what the clinic is for. However, this document does serve as a decent reference for the basic concepts of how to use Eclipse.

Links To Subclipse Resources

If you choose to use Eclipse, you might also find Subclipse useful. I refrain from putting my official stamp of approval on it, but I feel like most of its issues are worth dealing with in order to get a graphical interface to subversion that is incororpated into Eclipse.
  • How to install Subclipse
  • dsandler's Subclipse how-to
  • Note: All screenshots and examples in this document are taken from Eclipse 3.2 "Callisto" running on Java 5.0 on Windows XP SP-2. If you are not running this exact setup, you might find that some of the behavior is slightly different from what I describe. Most of you should be bright enough to figure it out from my examples; I have faith in you.

    Installation

    Step 1: Download Eclipse from their website.
    We'll start with installation of the Eclipse IDE. Eclipse doesn't need to be "installed," like most other programs. You simply need to find some disk space that you have permission to write to, and extract a folder from a zip file that you'll download from Eclipse's website.
    Step 2: Extract the eclipse folder from the zip file
    After you've downloaded the file, extract the eclipse folder from the zip to somewhere memorable. If you're installing to an owlnet workstation, remember to install it to somewhere local (like C:\Program Files\eclipse and not, say, on your desktop, which is actually stored on the network).
    Step 3: Create a workspace folder.
    Next, create a folder that Eclipse can use to store your projects and settings. Eclipse calls this a "workspace." You can create this anywhere you like. If you are using Eclipse on your own computer, any location will work. If you are on an Owlnet workstation, reasonable locations include the local workstation you're using (C:\) and the U:\ drive. If you would like this workspace to be accessible from all owlnet workstations, the network drive (U:) might be a reasonable place to put it. This is the method dsandler recommends, and I agree that it may be reasonable for your situation.
    Opinion:It's my opinion (based on some bad experience) that a user should not share a workspace between two workstations, even if both workstations are used by him and it seems to make sense. I have experienced annoyance when I've tried this. Because comp314 projects are all checked into subversion, I feel there is no reason for your workspace to be on a network drive. Treat two workstations that you, yourself use as if they were workstations that two different people use. Synchronizing code between two instances of yourself is the same, conceptually, as synchronizing between you and your partner--just use subversion. If you feel that you have no need to check in your code before you switch workstations, then perhaps the network drive solution is for you, but I'd ask why you wouldn't want to check in code in a circumstance like this. The only acceptable answer is, "My partner is relying on that code to be correct, and if I check in a work in progress, it won't even compile." My rebuttal to this is, "If you're working in a situation where your partner needs your code to compile for an extended period of time, perhaps the two of you should be working in separate branches in Subversion." If you're wondering what I mean by "annoyance," I experienced saving taking an annoying amount of time, due to Eclipse wanting to build my entire project off the network drive every time I saved my source. Also, several times it seemed that two different installations of Eclipse working in the same workspace yields a corrupted workspace, especially if these dueling installations were of different versions. This second reason is why I also don't recommend checking in workspace and project settings. As a secondary reason for recommending this, you and your partner might want different settings (you're debugging the program with only 32mb of heap space in order to expose and catch a memory leak, while your partner is running with 512mb so that he can continue to develop and debug other parts of the program, ignoring the leak). Run configurations are only one of the ways that conflicting project settings can be a small nightmare.

    Getting To Know Eclipse

    Now that you've "installed" Eclipse, it's time to run it. Launch its executable. When asked to specify the workspace location, give it the folder you created for this purpose. You should next be presented with the Eclipse's welcome view, shown below. Double click the tab at the top to demaximize the welcome view.
    Double click the welcome view's tab to reveal the entire Java perspective.
    Next, left-click and drag the same welcome tab around the eclipse window. You should see an outline snap to various places in the window, demonstrating that this welcome view can be moved to anywhere in the window. Double clicking it again will maximize it. Move it wherever you like a few times, then close it when you're done by clicking its tab's "X".
    Dragging a view's tab will change the view's anchor.
    Because Eclipse's terminology can be confusing, I will take an aside to disambiguate, as this is an important part of "getting to know" Eclipse. A "pane" is the abstract widget thing you just dragged around. The specific type of pane that you just dragged around the window is called a view. The arrangement of all the panes in your window is called a perspective.

    View: A specific kind of pane that offers controls and information

    Views can be called up and placed anywhere in the window at any time during the course of development. On the graphic above, you can see that several views are already open by default, namely Package Explorer, Hierarchy, Outline, Problems, Javadoc, Declaration, and Welcome. Each view can be closed with its "X" and reopened from the Show View Menu. Note that this is also a useful method for calling up a view that you've already opened, but simply misplaced. Also note that not all panes that you'll eventually create are proper views. The java editor, for instance, can exist several times in your window (once for each file that you wish to have open). It's unclear if Eclipse wants to call all panes views, but, for the purpose of this document, when I refer to a view I mean some kind of singleton pane.
    Views can be opened from the Show View menu.

    Perspective: An arrangement of panes

    Perspectives can be thought of as similar to window configurations. Dividing panes into perspectives helps an Eclipse window to minimize its clutter. Contrary to intuition, there are a finite number of singleton perspectives, each of which can be customized to your liking. There is usually one perspective for each function Eclipse serves. It's default behavior is to serve as a Java IDE, so, naturally, it's default is the Java perspective. However, Eclipse's functions are numerous, bounded only by the number of plugins you choose to install. For instance, Eclipse might also manage files on disk, serve as a useful debugger, and help you check your files into subversion. Each of these tasks has an associated perspective. Note that each perspective is entirely customizable; if it doesn't contain a view that you'd prefer it to have, simply call it up and place it where you'd like.
    Perspectives can be opened from the Open Perspective menu.
    Perspectives can be switched between from the toolbar. The left image shows only one perspective open, while the right shows two. Drag a perspective button to open it in a new Eclipse windows.

    Workspace: A collection of projects and settings

    Workspaces give the user the ability to group like projects together. If more than one user (human) uses a specific installation of Eclipse, each user should have his own (or many) workspaces. Eclipse saves all settings at the workspace level, meaning if you screw something up so bad it seems irreparable, create a new workspace and start over (assuming you can re-checkout your project). This will likely happen at least once during your work in comp314.
    You can change the workspace from the filemenu. Eclipse can interpret any folder as a workspace. Folders that don't have workspace data in them are interpreted as new workspaces.

    Project: A single compilation unit

    When getting started with Eclipse, I recommend that you understand a project to be that which one would compile with one call to javac on the command line, and the environment in which that command is executed in. A project, then, is essentially a set of source files and a build configuration. To go along with this recommendation, I also recommend that you have one workspace for comp314, and, inside it, you keep one project to correspond with each of the projects and homework assignments for the class.
    To create a new project: File->New->Project
    All of the projects that are contained by the open workspace are found in the Package Explorer View

    Let Eclipse Type For You

    One of the biggest time savers for the Eclipse user is its intelligent code completion feature. We'll explore a few common ways that eclipse can save you time by writing a fairly overcomplicated "Hello World." This excercise should help you understand a few of Eclipse's interesting features.

    Classic HelloWorld

    To begin, I'll start with the classic single (or several, in java) line HelloWorld to explain how to get a simple program to run in Eclipse.
    To make a new class, right click the project in the package explorer view. Select New->Class.
    Name it whatever you like. I'm going to choose HelloWorld, because it seems to make sense. There are some useful options in the "New Class" dialogue. An interesting one at this stage in the game is the one about "public static void main." I recommend always selecting this option if you want a main method, because Eclipse is really bad about telling you when you haven't typed it in correctly.
    This is what you should see after you create the HelloWorld class. Notice the special attention Eclipse is paying to the word "TODO" in your source. Open the "Tasks" view and you'll see a catalogue of all occurances of "TODO" and "FIXME." This is a useful tool for keeping track of bugs. Double click any of the entries in the Tasks view to jump to the associated line number.
    Replace the TODO with a HelloWorld of your choosing, then run it.
    The easiest way to run a main method in Eclipse is from the right click menu of the method's class in the Package Explorer view. This will create a default run configuration and run it.
    Not surprisingly, your Hello World should appear in the console view. You should note that stdout will show up here in black, stderr will show up in red, and stdin is captured from the keyboard while the console view is focused.
    If you wish to change the properties of any of your run configurations, you can do so in the Run window. The most important pane in that dialogue is displayed to the right. Here you can specify program arguments (that show up in argv) and VM arguments (stuff like "use a 512mb heap").
    Feel free to add some program arguments and verify that they show up in argv. This is very straightforward; I will omit it as an example.

    Insanely OO Hello World

    Eclipse's code compilation, repair, and completion features, which I feel are a serious time saver, are worth going over before going over Eclipse's OO features. At first glance (mostly because of the way they introduce themselves to the developer), the developer will probably see these features as being useful in fixing incorrectly typed (as in at the keyboard) code. Eclipse incrementally parses your code as you type, and, when you stop typing, it will attempt to compile it. If it finds errors, it will underline them in red squiqqle and provide an icon in the margin which, when clicked, will offer repair suggestions.
    Here we see what happens when I change "out" to "output," essentially creating a static field resolution error. To correct this error, left click the icon in the margin next to the error. Notice that in the tan colored box, Eclipse has shown what exactly it intends to change in the code. This is a useful box to pay attention to, as the English description of the change isn't always clear enough.
    When Eclipse is unable to compile any statement, it will make suggestions to you (the developer) as to how you should change the statement to make it valid. If there are different options, it will offer them all to you. As a (possibly unintended) consequence, these features can often be used to "correct" code that you intended to be incorrect. For instance, if you implement an interface in an anonymous inner class, yet define no methods, this code will not compile if the interface has any methods defined. Eclipse will offer to "fix" this problem for you, by providing stubs for all these methods. Suddenly, by using this feature, a 1 minute copy and paste job has now taken you less than 5 seconds.

    Create an interface much the same way you created a new class. Define one method in it for implementers (possibly different worlds to which your program would like to abstractly say hello to?).
    Back in your original main method, create a local variable that is assigned the value of a new anonymous inner class which implements your shiny new interface created in the image before. Don't define any methods inside it. Eclipse will quickly figure out that you're missing a method, and offer to add it for you. Note that each is a stub with an associated TODO tag, which is visible from the Tasks view. Imagine what a time saver this could be if an interface defined 25 or 30 methods.
    Of course, Eclipse will help you fix your type checking errors by offering casting fixes when it's appropriate. If you tire of not only trying to figure out where casts go, but also tire of typing the four parens necessary for a syntactically correct cast, simply type the statement without the cast. Eclipse will take care of suggesting where to cast appropriately.
    Here I've referenced the "Object" wh without a cast. Eclipse offers the correct cast suggestion.
    The last bit to say about our OO Hello World example is that we've not properly commented the interface that we've introduced. Attempt to add comments to both the interface you created and the single method inside it. You will notice that as soon as you press enter after typing /**, insofar as you're typing where a comment should go, eclipse will generate a comment stub for you.
    Comment stubs were created for me by Eclipse. This is particularly useful so that I include all proper parameters and the return value in my method comment.
    There are many, many other helpful code repair/completion tricks you can play with Eclipse. They are too many to enumerate in this document. My suggestion to you is, "Be lazy in the amount of typing you do on your own." Play around with it. Figure out where it can help you and where you'd rather do the typing yourself. (I no longer type import statements, for instance. Why should I type an import statement if Eclipse is just going to know what I mean and fix it for me? However, I usually type my own method calls. Eclipse will try to finish your argument list for you, guessing your intended argument list. I find that most of the time it is faster to type my arguments myself).
    Disclaimer: This does not mean that you're allowed to stop thinking about inheritance, type casting, or any other part of Java's semantics that Eclipse helps you type. Blindly accepting what Eclipse suggests will likely result in bugs, which will result in bogus runtime exceptions. Eclipse's purpose is simply to extend the life of your wrists. It has no intention of lessening the work for your brain. Developers who seek this should possibly start programming in python.

    Hotkeys To Know

    Below I've listed the hotkeys that I use most often when working in Eclipse. I've found them to be the most useful time savers of all the hotkeys, although I'm sure I could be more productive if I memorized more of them.
    CTRL+S: Save your file and build your project.
    You'll notice Eclipse will automatically build your project when you save. If you're looking to use one of those awesome Eclipse time-saver tricks I explained in the previous section, you'll probably want to save to get Eclipse to make the recommendations you're after. If it doesn't seem to happen, make sure that Eclipse is set to build your project automatically (this is on by default).
    Select this option to have Eclipse automatically (and incrementally, unfortunately) build your project.
    CTRL+SHIFT+F: Format the current source file
    This is the "pretty up my source" option. Use it often. You'll catch more bugs if you can actually read your code and comments. You can change how this option formats your code in the project or workspace settings. Look for the Java Code Style section.
    ALT+SHIFT+J: Add a javadoc-style comment to the current body.:
    This is an alternative to just simply typing the first /** and pressing enter. Sometimes the hotkey will produce correct javadoc when simply beginning the comment refuses to do so. Keep this hotkey in mind for that situation, but, obviously, typing /** is much easier.
    CTRL+SHIFT+L: List all hotkeys:
    Forgot a hotkey, or wondering if there's a hotkey for a common mouse action? Press CTRL+SHIFT+L and a small window will appear listing all of them. —dsandler
    CTRL+Space: Autocomplete:
    Eclipse will read your mind. Start typing the name of a function or class and press CTRL+Space to bring up a drop-down menu of likely completions; you can choose one with the mouse or arrow keys, type a few more characters to refine the search, or press ESC to dismiss the pop-up. —dsandler