Maven 2 (Part 3): Configuring eclipse for Apache Maven 2 projects

Today we're going on with the third part of our Maven 2 tutorial series. Because of the comment of Enrico I decided that this article will focus on how to configure eclipse for the usage of Maven 2 projects and how to generate the eclipse-specific files by using Maven 2. I will show these things by using the example project of part 1 and part 2 of our Maven 2 tutorial series.

As you remember I showed you some simple Maven tasks like

• mvn clean
• mvn test and
• mvn package

Today I will focus on the two other tasks

• mvn eclipse:clean and
• mvn eclipse:eclipse

Each of these two tasks are combining two informations. The first information is located before the colon-symbol: „eclipse“. This string defines that the Maven 2 eclipse plugin will be used. Maven 2 will automatically download this Plugin from the central Maven repository. The string after the colon-symbol („clean“ or „eclipse“) indicates the explicit target the Maven 2 eclipse plugin should execute.

Cleaning eclipse resources

Please navigate to the root directory of our example application and run

mvn eclipse:clean

If you now list the root directory of our project you will see that nothing has been changed. Why? This is quiet easy. If you run „mvn eclipse:clean“ Maven will use the Maven 2 eclipse plugin to remove the eclipse resources like the .settings-folder, the .project-file and the .classpath-file. In our case nothing has been deleted because our project never had eclipse-specific resources. To see how Maven 2 generates those things please go on reading this article. ;-)

Generating project-specific eclipse resources

Generating project-specific eclipse-resources is as easy as removing them. Simply navigate to your projects root directory and run
mvn eclipse:eclipse
Maven will now generate all eclipse resources needed to import the project into the eclipse IDE. Now the project is ready to become imported. But is eclipse ready to use it?

Important. Important! IMPORTANT! Please be so kind and do never commit these eclipse resources into your versioning system (e.g. subversion, cvs, git or mercurial). Do it only if you really hate your colleagues.

Importing the project

The following informations could be a little bit boring because it contains a small click-guidance on how to import the project to the eclipse IDE. Let's start by running our Maven 2 tasks again:

mvn eclipse:clean eclipse:eclipse

Now we ensured that all previous eclipse resources are removed and generated again. Open your eclipse IDE and click on „File --> Import“. Choose "Existing Projects into Workspace" and hit the "Next >"-button.

Make that the radiobutton is switched to "Select root directory" and hit the "Browse..."-button.

Navigate to your projects parent folder and select your project. Then hit the "OK"-button.

Make sure that the checkbox in front of your project is checked and press "Finish". Now eclipse starts to import the new project.

As you can see your project cannot be build. Why? Your eclipse IDE is missing the local Maven 2 repository in your build path.

Adding the local Maven 2 to eclipse build path

To let eclipse know where the local Maven 2 repository is located you should know where it is located. By default the Maven 2 repository is located at

/home/[USERNAME]/.m2/repository

on linux platforms and

C:\[PATH_TO_YOUR_HOME_FOLDER]\.m2\repository

on Windows platforms. It is important to configure this directory as a classpath variable in eclipse. To do so please click on "Window --> Preferences" in your eclipse IDE. Navigate to "Classpath variables" of the "Java"- subnode "Build Path" and press the "New..."-button. Enter "M2_REPO" as the name of the new classpath variable and the location of your Maven 2 repository as the associated path.

After that hit "OK" to create your classpath variable and again "OK" to apply your changes to the IDE preferences. Your eclipse IDE will now ask you to rebuild all projects because your classpath variables has been changes. Choose "Yes"!

As you can see your project has been successfully imported and you are able to start working on it.

For those of you who like some further informations I've added 3 hints to this article.

Hint: Relocating the local Maven 2 repository

Sometimes the default location of the Maven 2 repository isn't very nice. Therefore Maven 2 allow to change the repository location. To modify your repository location navigate to the directory

[PATH_TO_YOUR_MAVEN_INSTALLATION]/conf

Open the file "settings.xml" and uncomment the XML-node "localRepository" and switch it to whereever you want. Make sure that the XML-node "localRepository" is defined outside the comment and save it. After changing the location of your repository you should modify the classpath variable in your eclipse IDE too. Don't forget that! I've spend hours to find out why eclipse doesn't find my dependencies although they were placed in my repository before I recognized that I forget to update my classpath variable in eclipse.

Hint: Do not use network drives for the Maven 2 repository

Do not place your Maven 2 repository on network drives. If you do so your eclipse will loose performance due to the network roundtrips between eclipse and the repository.

Hint: After adding new dependencies

After you added some new dependencies please run

mvn clean eclipse:clean eclipse:eclipse

to regenerate the project-specific eclipse resources. Click on your projects root directory in the "Project Explorer" in your eclipse IDE and hit "F5" to let eclipse reload all resources. Not until that eclipse will find your new dependencies inside of your Java classes.

Previous Maven 2 articles:
Maven 2 (Part 1): Setting up a simple Apache Maven 2 Project
Maven 2 (Part 2): Dependencies, properties and scopes