Eclipse

Goals

• Install Eclipse.
• Import existing Git+Maven projects into Eclipse.
• Build and run projects from within Eclipse.

Concepts

• editor
• formatter
• Content Assist
• Eclipse Installer
• Integrated Development Environment (IDE)
• null analysis
• perspective
• project
• run configuration
• Source Control Management (SCM)
• view
• workspace

Preparation

• Download and install the latest Eclipse release.
  • Use the Eclipse Installer (recommended).
  • Choose the Eclipse IDE for Java EE Developers package (recommended).

Lesson

An Integrated Development Environment (IDE) is a set of development-related tools integrated into a cohesive interface to assist in the development process. A Java IDE will usually integrate a syntax-highlighting source code editor, a compiler, a debugger, along with support for Maven and Git. Of the free IDEs the most popular are Eclipse and NetBeans. Also very popular is IntelliJ IDEA, a commercial paid product of JetBrains.

Eclipse

In this course we will use Eclipse as our IDE. In its long history Eclipse has burgeoned from more than a glorified editor into a complete platform covering various languages and subject areas. Many related products release Eclipse plugins that integrate with the Eclipse platform.

Workspace

A workspace is where Eclipse stores projects and other metadata. By default Eclipse chooses to store your workspace under your user home directory in a subdirectory named workspace, and will create that directory if needed. Inside the workspace directory, Eclipse will maintain a .metadata directory that maintains the current settings for that workspace.

Project

The workspace keeps track of which projects are open and closed. Each project usually lives in a separate directory. The project directory does not necessarily have to be to the workspace directory. It is reasonable to use your existing project directories; you don't need to move them. Inside each project directory, Eclipse uses several of its own files to keep track of the project settings.

…
#Maven
/target/
…
#Eclipse
/.settings/
.classpath
.project
…

.settings/

A directory containing settings for various Eclipse plugins.

.classpath

A description of the project build configuration and dependencies.

.project

The main Eclipse project definition file.

Installing Eclipse

There are two ways to download and install Eclipse:

Manual Installation

The traditional approach, in which you download an archive containing all files.

Eclipse Installer

A newer approach, which purports to ease the installation and upgrade process.

With either installation approach, Eclipse comes with various “package solutions” to choose from. Because the Eclipse IDE has morphed into a platform with many plugin options and supported languages, these packages represent preconfigured bundles that are useful to various types of users based upon the way they intend to use Eclipse.

After installing Eclipse, make sure you have all the required plugins installed, listed under Plugins below.

Eclipse Installer

The new Eclipse Installer purports to be “The way to install and update your Eclipse Development Environment”. Here is an overview of the process; Eclipse has complete instructions with pictures on its site.

1. Download the Eclipse Installer using the download button on the Eclipse Downloads page.
2. Select a mirror for download.
3. Run the Eclipse Installer executable.
4. Select which Eclipse package you prefer.
5. Select the installation folder on your computer.
6. Press INSTALL.

Manual Installation

1. Choose the package you want from the Eclipse Downloads Packages page.
2. Select a mirror for download.
3. Uncompress the archive into a separate directory.

Running Eclipse

If you used the Eclipse Installer, you had the option of adding a shortcut link. Otherwise, you can run Eclipse by finding and activating the executable file (e.g. eclipse.exe on Windows) in the installation directory. When Eclipse starts for the first time, it will ask you to Select a workspace. See Workspace above.

Plugins

Depending on the Eclipse package you choose, many plugins may be already installed with the distribution. Most plugins may be installed via the Eclipse Marketplace (recommended) via Help → Eclipse Marketplace.... You may also use Help → Install New Software... and select the update site for your version of Eclipse. The recommended plugins should already be installed with the Eclipse package you selected when installing.

1. Marketplace: If the Eclipse Marketplace Client (Help → Eclipse Marketplace...) is not installed, it is recommended you install it by searching under Help → Install New Software.... This will make it easier to add popular plugins.
2. EGit: If the Git Team Provider (EGit) is not installed, search for “EGit” in the Eclipse Marketplace (Help → Eclipse Marketplace...).
3. Maven: The m2e plugin should come installed with the standard packages. Otherwise, you can install it by searching for “m2e” or “Maven integration” in the Eclipse Marketplace (Help → Eclipse Marketplace...).
4. Mylyn: (optional) This plugin helps you keep track of separate tasks and the files associated with those tasks. It is available in the Eclipse Marketplace (Help → Eclipse Marketplace...), but it should come installed with standard packages.
5. Atlassian Connector: (optional) The Atlassian Connector allows Eclipse to download tasks directly from JIRA and integrates with Mylyn. Although this connector will no longer be supported, it may still work with Eclipse for some time, although it may not be available in the Eclipse Marketplace. Atlassian has instructions for installing the Eclipse connector.
6. Eclipse XML Editors and Tools: (optional) These editors are extremely useful for working with XML. They come installed with the standard packages.
7. Miscellaneous Internet Tools: (optional) For working with Internet-related formats and for controlling servers from directly within the IDE, you may want to install one or more of the following plugins: Eclipse Java EE Developer Tools, Eclipse Web Developer Tools, JavaScript Development Tools, JST Server Adapters, and JST Server Adapters Extensions. Many of these come already installed with the Eclipse IDE for Java EE Developers package.

Updating Eclipse

You can update Eclipse by selecting Help → Check for Updates. To upgrade your installation to another full release (such as from Neon/4.6 to Oxygen/4.7), you will need to add the repository of the new release in the Available Software Sites before following the update procedure, as explained in the FAQ for upgrading Eclipse.

Settings

JRE

Verify that you have the latest JRE installed and selected as default. Go to Window → Preferences → Java → Installed JREs; you should see the JDK for Java 8 installed and selected. Ensure that the full JDK is selected. If a Java JRE rather than the full JDK is selected, you won't be able to browse the Java library source code for example. You may need to select Add..., select Standard VM, and then browse to the location where you installed the JDK.

Encoding

Just as we indicated an encoding of UTF-8 in Maven, it is a good idea to configure Eclipse to use the UTF-8 encoding for all text files to allow them to work across different platforms. Select Window → Preferences → General → Workspace and set Text file encoding to Other: UTF-8.

Formatting

It is important that all developers on a project choose a common approach to how code will be formatted. Eclipse makes this easier by including a formatter that can format a single file or entire project according to a set of formatting rules. You can choose a set of formatting rules under Window → Preferences → Java → Code Style → Formatter. After choosing an auto-format configuration, you can auto-format a single file by using Ctrl+Shift+F.

In these lessons we will use the Google Java Style, for which there is an Eclipse configuration and which you can import into Eclipse:

1. Download the Java Google Style Eclipse formatter configuration. To download the file, in the GitHub UI Right-Click on Raw and use your browser's Save Link As... facility.
2. Go to Window → Preferences → Java → Code Style → Formatter → Import... and import that configuration into Eclipse.
3. Format your source code as needed using Ctrl+Shift+F.
4. (optional) Configure Eclipse to format some or all of your code automatically each time you save a file.
   1. Go to Window → Preferences → Java → Editor → Save Actions.
   2. Select Perform the selected actions on save.
   3. Select Format source code (Format all lines or Format edited lines).
   4. Deselect Organize imports.

Dictionary

Eclipse has the ability to automatically check spelling in real time in source code comments. There are invariably technical words that Eclipse does not recognize by default, so a dictionary can be maintained in a simple text file of words separated one on each line. If you have such a dictionary, or want to start one, you can go to Window → Preferences → General → Editors → Text Editors → Spelling and make sure Enabled spell checking is selected. Then in the same panel, select the appropriate text file as the User defined dictionary.

Null Analysis and JSR-305

You can configure Eclipse to recognize your @Nonnull and @Nullable annotations for null analysis—attempting to determine, even at compile time, whether your code is handling null correctly based upon the annotations you've used. (See JDT Core/Null Analysis for more information.)

You'll need to indicate that you are using the JSR-305 annotations for null analysis. First enable null analysis using Window → Preferences → Java → Compiler → Errors/Warnings → Null analysis → Enable annotation-based null analysis. (Eclipse may ask you to clarify whether certain violations should be considered warnings or errors. Then by Use default annotations for null specifications select Configure... and enter:

'Nullable' annotation

javax.annotation.Nullable

'NonNull' annotation

javax.annotation.Nonnull

Creating a Project

Importing from a Local Repository

If you've already been working with a project that is using Maven for building and Git for version control, you can import the existing project directly into Eclipse.

1. Go to File → Import... → Maven → Existing Maven Projects and press Next.
2. Beside Root Directory press Browse... and select the root directory of your project.
3. The POM of your project (with a label indicating its coordinates) should be selected. Press Finish.

Cloning from a Remote Repository

If you haven't yet cloned your project from a remote Git repository, you can clone it manually using Git commands and then following the instructions above for Importing from a Local Repository. But Eclipse also allows you a way to clone your project from a remote repository and import it into Eclipse in one fell swoop.

1. Go to File → Import... → Maven → Check out Maven Projects from SCM and press Next.
2. Beside SCMURL make sure Git is selected, and enter the the Git clone URL from your remote repository (e.g. https://jdoe@bitbucket.org/jdoe/example.git).
3. Press Finish.

Eclipse will then clone your project into a new directory in the workspace and then import the project into Eclipse.

Creating a New Project

You can also create a blank Eclipse project from scratch.

1. Go to File → New → Java Project and press Next.
2. Enter a project name.
3. Press Finish.

A preferred approach would be to create a Maven project from scratch in Eclipse.

1. Go to File → New → Other..., choose Maven → Maven Project and press Next.
2. Select Create a simple project and press Next.
3. Fill out the minimal details for the Maven POM and press Finish.

Put a Project under Version Control

If you created a project and haven't yet put it under version control, you can always do that manually from the command line. You can also do it from inside Eclipse:

1. Right-click on the project and select Team → Share Project....
2. Select Git and press Next.
3. Select Use or create repository in parent folder of project.
4. Select the project you are putting under version control.
5. Press Create Repository and then press Finish.

Eclipse Views

The main Eclipse window is divided into dockable views on the left, right, and bottom as context calls for. Files are opened in the center editor.

Project Explorer

The Project Explorer on the left is the main Eclipse navigator for your project(s).

Editor

Double-clicking on a file opens it for editing inside Eclipse. You can also quickly open source code files by using Ctrl+Click on a class, interface, link, or one of many other types of definitions.

Eclipse Perspectives

Eclipse has several perspectives that help you work with a certain task. Each perspective has a different mix of views and those views are usually arranged in a way most helpful for that task. Here are several useful perspectives:

• Java EE perspective (default in the Eclipse IDE for Java EE Developers package)
• Java perspective (default in the Eclipse IDE for Java Developers package)
• Debug perspective
• Git perspective

Perspectives are normally represented by buttons at the top, right-hand corner of the Eclipse main window.

Building a Project

Running a Project

Eclipse maintains a run configuration for each program it executes. There can be several run configurations covering a single project (using different classes with main(…) methods, for example) or even a single class (to run the same programs with different parameters, for example). Eclipse also provides several shortcuts to run or rerun several types of programs.

Review

Gotchas

• When trying to show the currently loaded file in one of the explorers by pressing Alt+Shift+W, If you accidentally press Ctrl+Shift+W Eclipse will close all the files open in the editor.

In the Real World

• When you search across files, Eclipse will show a list of results in the search view. By default when you try to open several files from the results, Eclipse will only open one file at a time, replacing the last file result opened in the same tab. If you prefer the ability to open several of the result files at the same time in multiple tabs, disable the setting Window → Preferences → General → Search → Reuse editors to show matches.
• If you run out of memory when using Eclipse, you can increase the amount of Eclipse allocates by editing the eclipse.ini file, as explained in FAQ How do I increase the heap size available to Eclipse?.

Task

1. Install Eclipse.
2. Configure the Eclipse formatter to use the Google Java Style.
3. Verify that you have added appropriate .gitignore files covering Eclipse and Maven.
4. Import your Booker application (booker) and data structures library (datastruct) into the Eclipse workspace as Eclipse projects.
5. Create and switch to a new branch for the lesson from within Eclipse.
6. Reformat all your source code to match the Google Java Style.
7. From within Eclipse change the POM versions of both projects to match that of the current lesson.
8. Commit the modifications and push your changes to the remote repository, all from within Eclipse.

See Also

• Introduction to Eclipse: Driving Java Productivity (YouTube - NewCircle Training)
• Creating and Importing Projects (Developing with Eclipse and Maven)
• Create a New Maven Project in Eclipse (Tech-Recipes)
• Leveraging JSR-305 null annotations to prevent NullPointerExceptions (Apache Sling)

References

• Integrated development environment (Wikipedia)
• Eclipse Documentation
• Eclipse Wiki
• 5 Steps to Install Eclipse
• FAQ for upgrading Eclipse
• Developing with Eclipse and Maven (Sonatype)
• Google Java Style
• JDT Core/Null Analysis (Eclipse Wiki)

Resources

• Eclipse
  • Eclipse Downloads
  • Eclipse Downloads Packages
  • Eclipse Packaging Project (EPP) Releases Includes the latest development milestone versions and release candidates.
  • Java Google Style Eclipse formatter configuration
• NetBeans
• IntelliJ IDEA (JetBrains)