A perspective in Eclipse is a specific configuration of a set of Windows, designed to work with each other. The standard Eclipse display has a series of perspective icons at the upper right corner of the display.

Perspectives are disconcerting at first because they reconfigure the entire window, but are useful because we can choose perspectives to match the kind of task we will be performing. Once you get used to the perspective icons, and learn that you can recover the previous window configuration just by clicking on one of the perspective icons, they make more sense.

Most of the time, we will use the Java perspective. This is the perspective that is most useful for actually writing Java code. The Java perspective typically has a Package Explorer window on the left, the Java editor in the middle of the screen, a Task list on the right, and an output window at the bottom of the screen.

Occasionally, we need to debug code, and we can use the special debug perspective. Eclipse will often automatically (or with a prompt) switch us into the debug perspective when we start debugging code (using the spider icon). The debug perspective has a stack trace in the left window in place of the package explorer, and the right window is replaced with a tabbed window to control breakpoints and value displays. When you are finished debugging, just click on the Java perspective icon to get back to coding

A third useful perspective is the Git perspective. We can use the Git perspective when cloning respositories from git, staging updates, or committing and pushing updates to the master respository. The Git perspective has a list of Git Repositories tha Eclipse knows about on the left screen, the Java Editor in the middle, and a window that has git tabs on the bottom.

Finally, there is an icon to open perspectives. If you click on that icon, it gives the list of all of the perspectives available in Eclipse.

arrow_circle_up

Using GitHub with Eclipse

It is possible to use Eclipse to drive all of the GitHub commands we need for CS-140. The following sections describe how to do specific things with GitHub using the Eclipse interface

Opening the Git Perspective

If you have never used Git in Eclipse before, the Git icon won't appear in your perspectives yet. Go to the perspectives icons (see Using Perspectives), left mouse on the "open perpectives" icon, and select "Git". Now, the GIT perspective icon should show up in your perspective icons.

In the GIT perspective, there are three basic windows.

• The left window contains a list of all the repositories Eclipse knows about.
• The center window contains the standard Eclipse editor (not used very much in the Git perspective, but there if you need to check up on some details.)
• The bottom window does most of the git management, most of the actions that can be performed on a specfic repository chosen from the list of repositories. This window contains a tabbed display that allows you to do several things:

  History tab

  Shows the list of all commits, with details about commit comments, files changed, hash codes, etc.

  Synchronize tab

  Contains the results of a syncnronize command, which we won't be using.

  Git Staging tab

  Shows what is reported as changing, and allows you to commit and push those changes to the master repository

  Git Reflog tab

  Also shows the list of commits with hashcodes, like the history tab, but more formal, less info

  Properties tab

  Shows all the properties of the selected repository

  Console tab

  The standard console output from the last command run.

arrow_circle_up

Cloning a Repository

To clone a repository, first copy the URL of the repository you want to clone into your clipboard. Then, open the Git perspective, and click on the and in the repository list window, click on the clone repository icon. This will initiate the Eclipse Clone Repository wizard.

The Eclipse Clone Wizard initial display looks like the picture to the left. Fill this in as follows:

• The URL: field contains the value in the clipboard, the URL of the repository you want to clone.
• The Host: field and the Repository path: field are filled in automatically by parsing the URL.
• The Connection Protocol: and Port: fields default correctly.
• In the Authentication section User: and Password: need to be filled in the first time, but if you check the Store in Secure Store check-button, both your userid and password will be saved for the next clone you perform.

Once these fields are correct click on the Next> button. When you do, you will get the second screen of the Clone Wizard.

The Second screen of the Clone Wizard comes up. When this is first displayed, Eclipse communicates with the GIT host. If the communication link is slow, you may see a progress bar, but that normally takes just a second or two to complete. When it is finished, you will see a display like the illustration to the right. In this display, there are just a couple of options:

• There is a list of branches of the repository. We will never be dealing with repositories that have branches, so this will always show a single entry called main, and that entry will be checked.
• There is also a Tag fetching strategy set of radio buttons.
  • When fetching a commit, also fetch its tags - this is selected, and works great for our purposes.
  • Fetch all tags and their commits
  • Don't fetch any tags

Everything on the second screen of the Clone Wizard is already correct. At this point, just hit the Next> button to get to the last screen of the Clone Wizard.

The last screen of the Clone Wizard looks something like the illustration to the left. This is the only screen where you always have to change the default values in order to get things right!. There is only one field that needs to be updated, and that is the Directory: field. You need to modify this field to point to your Eclipse Workspace and Project source directory, and you need to remove your gitHub Userid suffix from the end of the repository directory name.

This is accomplished easiest by clicking on the Browse button to the right of the Directory: field, and navigating to your Eclipse Workspace directory (usually the directory above cs140), then into cs140 - the Eclipse project directory, then into "src". The display will then show ~\cs140\src\repos-gitUserID, where repos is the name of the repository, and gietUserId is your GitHub UserID. At this point, edit the destination directory by removing the "-gitUserId" suffix. Doing so will make the Eclipse package directory match the package specifications in the .java files in the repository - something which is required in Eclipse.

The rest of the fields default correctly, and the Finish button should now be enabled (the "not an empty directory" error message at the top of the screen will go away.) Click on the Finish button. At this point, the clone will actually take place and the files from the master repository will be copied onto your local hard disk.

When you are done, a confirmation screen pops up, and the repository now shows up in the Repository list on the left side of the screen.

Now, switch back to the Java perspective. If you look at the Package Explorer window, the new package that has been created by the clone that Eclipse has done for you has not yet been reflectd in the Package Explorer window. To resolve this problem, you need to navigate to the "src" item under your project in the Package Explorer window, right mouse click, and select the Refresh option. The Refresh option forces Eclipse to check to see what is on disk. Since your clone is on disk, Eclipse will update the Pacakge Explorer window to show that package, and you can continue working on your repository in Eclipse.

Committing Changes to Repository, and Pushing to the Master

When you have finished making changes to the code, and would like to commit those changes and push them to the master repository, you need to first open the Git perspective and select the repository from the list of repositories on the left.

Then, on the bottom window, navigate to the Git Staging tab. You should see a list of all of the files in the Eclipse package directory which are different from the master repository in the box labeled Unstaged Changes.

The next step is to stage the files that you want to commit. There are several ways to do this. You can use the + icon to move selected files from unstaged to staged, use - to move them back.

Once you have the correct list of files in the Staged Changes box, you can write a commit comment in the Commit Message box.

When you are comfortable with the commit message, click on the Commit and Push button. This will commit your changes to the local repository, and then copy those changes to the master repository. When it is done, you will get a pop-up confirmation screen that has the commit hash code. This is the hash code that gets cut and pasted into myCourses.

It is possible to do the commit without also doing a push by using the Commit button, but then you have to figure out how to do a push independently from the commit, and we never need to do that in this class, so just ignore the "Commit" button and always use the "Commit and Push" button.

Writing Code with Eclipse

This section contains hints on using Eclipse when you are writing code.

Creating a new Class

There are lots of ways to create a new class, but the most straightforward way is to select the package in the package explorer window, left mouse, and select New/Class from the actions pop-up. This will start the Eclipse new class wizard.

The new class wizard allows you to specify the name of the new class in the Name: box. You can specify the extends value in the Superclass: box, and specify implements values in the interfaces: box.

If you select the public static void main(String[] args) checkbox, Eclipse will add a main method to your class.

When you hit the Finish button, Eclipse will generate a new className.java file in the package sub-directory, add that class to the Package Explorer menu, and open an editor tab on that file so you can start adding to the class.

Opening the Editor for an Existing Class

In order to open a tab in the Java editor for an existing class, just double right mouse click on the class name in the package explorer.

Organizing Imports

Eclipse can usually determine exactly what import statements are required in your code, based on the classes and methods you reference in your code. Invoke Source/Organize Imports... from the menu, or use the hot-key Ctrl-Shift-O to inoke the Eclipse imports organizer. Eclipse will add or remove import statements at the top of your .java file to match what is in your code.

If there is any ambiguity, such as two different library implementations of the same class, Eclipse posts a pop-up and asks you to resolve the ambiguity before organizing imports.

Formatting your Java code

The Java editor does some automatic formatting of your code, using indentation styles, and so on, but you can get the formatter confused by things like cutting and pasting code, or inserting your own white space.

You can force Eclipse to reformat all your code to make it consistent and legible by invoking menu item Source/Format or use the hot-key Ctrl-Shift-F.

If you don't like the way Java formats your code, go to menu item Window/Preferences/Java/Code Style/Formatter. There are lots of formatting options you can tweak.

Automatic Generation of Java Code

There are several cases where Eclipse can automatically generate some of your Java code, especially when that code is predictable and regular. All these capabilities are under the menu item Source after the last separator in the resulting popup.

Here are some of these auto-generation capabilities I find particularly useful:

Generate Constructor Using Fields...

You can select which of the fields currently defined for this class you want to participate... and Eclipse will make a constructor that uses those field names as parameters, and assigns the parameters to the fields for you.

Generate Getters and Setters...

You can select which of the fields currently defined for this class you wnat ot participate, and specify whether you want a getter, setter, or both generated for you. Eclipse will then generate a getField and/or setField method automatically for you. (If the field is a boolean, Eclipse generates isField instead of getField.)

Generate toString...

Eclipse will generate a toString method for you based on the fields you select. Try it... it's much easier to try than to describe.

Generate Delegate Methods...

Allows you to create methods that pass there arguments onto similarly named methods on one of your fields.

Generate Constructors from SuperClass...

This looks at the class your are extending, and makes constructors for your sub-class that match every constructor for the superclass, using the superclass parameter lists.

Override/Impement Methods...

Eclipse gives you a list of all inherited methods. If you select from this list, Eclipse will generate an override method that allows you to provide your own definition of the method. The list of inherited methods includes any abstract methods that must be overriden to make a concrete class and/or implement an interface.

Running Code with Eclipse

This section contains hints on using Eclipse when you are running your code.

Eclipse "Run" Buttons

Eclipse has several Run icons (see the illustration to the right), as well as several menu sub-options under Run.

Almost all the time, we will be using the standard Run button. When you press the Run button, Eclipse almost always runs the program you want it to. If you want to know exactly how the run button works, Eclipse does the following:

1. Checks to see if the Java file you are currently editing has a main method. If so, that file becomes the Java class to run. If not, Eclipse checks to see if there is a different class in the same package as the file you are currently editing that has a main method. If there is only one such class, that class becomes the Java class to run. If there are multiple classes in the package with main methods, Eclipse checks the run history, and selects the class most recently run as the class to run. If there is no history, I'm not sure what happens.
2. Once Java has chosen the class to run in the current package, it then looks to see if there is a saved run configuration for that class. If there is a saved run configuration, Java uses that configuration, including any run time parameters specified. (See Specifying Command Line Arguments for details.) If there is no saved run configuration, Eclipse makes a new default run configuration for this class.
3. Eclipse invokes the chosen class with the chosen run configuration, and prints output to the console window at the bottom of the screen. If the program reads from standard input, you can type into the console window at the bottom of the screen.

The Run Last Tool button bypasses the complicated selection of the Java class to run and run configuration, and just re-runs whatever the last main class and run configuration you had chosen.

If you click on the Debug (spider) icon instead of the Run button, Eclipse runs your program (using the same main class and run configuration selection as the Run button) under the debugger. The debugger allows you to stop execution at breakpoints, look at the current value of fields and local variables, and single step your code.

The Run Coverage button runs your code in a special mode that collects information about all instructions that were executed, and uses that information to highlight your code in the editor to show what lines of code were run and which were not.

Often, if you hit the run coverage button by mistake, you will get code highlighting in the editor that becomes confusing and distracting. In order to turn off the code coverage highlighting, you need to delete the coverage information that was collected. However, Eclipse doesn't show that coverage information in the Default Java perspective. In order to see the coverage information, you need to select menu item Window/Show View/Other, and then in the Java folder, select Coverage. This will add a Coverage tab to the bottom output window. You can then select that tab, and select the X icon to delete the coverage. That will also remove the highlighting from your editor window.

Specifying Command Line Arguments

When you click on one of the Run buttons (see Run Buttons) in Eclipse, by default, no command line arguments are included in your invocation. You can override the default and specify command line arguments by selecting Run/Run configurations... from the menu, or by clicking on the pulldown arrow to the right of the run button and selecting Run configurations.... This will bring up the Eclipse Run COnfigurations dialog, with the Main tab selected as in the image to the right.

In the Run Configurations dialog, select the Arguments tab, as in the image to the left. You can then type any command line arguments you want in the Program Arguments section of the screen. If you then click on the Run button, the program arguments will become command line arguments on your invocation. These command line arguments get split on white space by the JVM, and put into the String[] args array that is passed into your main mentod.

Eclipse will associate this run configuration with your current package, and remember the command line arguments the next time you click on the Run button, or you select Run/Run from the menu.

Enabling Assertions

By default, when you invoke the Java Virtual Machine to run a command under Eclipse, assertion processing is turned off. That means that any assert(condition); statements in your Java code will be ignored and not checked.

If you want your assertions checked, then you need to open the Run Configurations dialog (see Specifying Command Line Arguments), click on the Arguemnts tab, and add the text -ea (short for enable assertions) to the VM arguments: area of the screen.

As in command line arguments, the resulting run configuration will be remembered and used again when you hit the Run button the next time.

Eclipse Terminology