14.3.1. Installing Prerequisites

You can install these prerequisites when you install m2eclipse, just add a new remote update site to Eclipse for each of the prerequisite components. To install these prerequisites, go to Help → Software Updates → Find and Install.... Selecting this menu item will load the Install/Update dialog box. Choose the "Search for new features to install" option and click Next. You will then be presented with a list of "Update sites to visit". Click New Remote Site..., and add a new update site for each new prerequisite. Add a new remote site for each plugin and then make sure that the remote site is selected. After you click Finish, Eclipse will then ask you to select plugins components to install. Select the components you want to install and Eclipse will download, install, and configure your plugins.

Note that if you are using a recent build of Eclipse 3.4 (Ganymede) your plugin installation experience may be slightly different. In Ganymede, you will select Help → Software Updates... which will load the "Software Updates and Add-ons" dialog. In this dialog, choose the Available Software panel and click on Add Site... which will load the simple "Add Site" dialog. Enter the URL of the update site you wish to add and click OK. In the "Software Updates and Add-ons" dialog, the available plugins from an update site will appear as soon as the site is added. You can then select the modules you want to install and click the Install... button. Eclipse will then resolve all the dependencies for the selected plugins, and ask you to agree to the plugin license. After Eclipse installs new plugins, it will likely ask you for permission to restart.

14.3.1.1. Installing Subclipse

To install Subclipse, use the Eclipse plugin update site listed below.

• Subclipse 1.2: http://subclipse.tigris.org/update_1.2.x

For other versions of Subclipse, and for more information about the Subclipse plugin, please see the Subclipse project's web site at http://subclipse.tigris.org/.

14.3.1.2. Installing Mylyn

To install JIRA integration with Mylyn, add the Mylyn extras Eclipse update URL, you'll want to do this if your organization uses Atlassian's JIRA for issue tracking. To install Mylyn use the following update sites:

• Mylyn (Eclipse 3.3): http://download.eclipse.org/tools/mylyn/update/e3.3

• Mylyn (Eclipse 3.4): http://download.eclipse.org/tools/mylyn/update/e3.4

• Mylyn Extras (JIRA Support): http://download.eclipse.org/tools/mylyn/update/extras

For more information about the Mylyn project, see the Mylyn project's web site at http://www.eclipse.org/mylyn/.

14.3.1.3. Installing AspectJ Development Tools (AJDT)

If you are installing the 0.9.4 release of m2eclipse, you may also want to install both the Web Tools Platform (WTP) and the AspectJ Development Tools (AJDT). To install the AJDT use one of the following update URLs in Eclipse:

• AJDT (Eclipse 3.3): http://download.eclipse.org/tools/ajdt/33/update

• AJDT (Eclipse 3.4): http://download.eclipse.org/tools/ajdt/34/dev/update

For more information about the AJDT project, see the AJDT project's web site at http://www.eclipse.org/ajdt/.

14.3.1.4. Installing the Web Tools Platform (WTP)

To install the Web Tools Platform (WTP). Use one of the following update URLs in Eclipse, or just look for the Web Tools Project in the Discovery Site which should already be in your Eclipse remote update sites list.

• WTP: http://download.eclipse.org/webtools/updates/

For more information about the Web Tools Platform, see the Web Tools Platform project's web site at http://www.eclipse.org/webtools/.

14.3.2. Installing m2eclipse

Once you've installed the prerequisites, you can install the m2eclipse plugin from the following Eclipse update URL:

If you would like to install the latest snapshot development version of the plugin, you should use the update-dev URL instead of the previous URL:

To install m2eclipse, just add a the appropriate update site for m2eclipse. Go to Help → Software Updates → Find and Install.... Selecting this menu item will load the Install/Update dialog box. Choose the "Search for new features to install" option and click Next. You will then be presented with a list of "Update sites to visit". Click New Remote Site..., and add a new update site for m2eclipse. Add a new remote site for m2eclipse and then make sure that the remote site is selected. After you click Finish, Eclipse will then ask you to select plugins components to install. Select the components you want to install and Eclipse will download, install, and configure m2eclipse.

If you've installed the plugin successfully, you should see a Maven option in the list of preferences options when you go to Window → Preferences....

14.5.1. Checking Out a Maven Project from SCM

m2eclipse provides the ability to check out a project directly from a SCM repository. Simply enter the SCM information for a project and it will check it out for you to a location of your choice as shown in Figure 14.3, “Checkout a New Project from Subversion”:

Figure 14.3. Checkout a New Project from Subversion

There are additional options in this dialog for specifying a particular revision by browsing the revisions in a Subversion repository or by simply entering the revision number manually. These features reuse of some of the features in the Subclipse plugin to interact with the Subversion repository. In addition to Subversion, the m2eclipse plugin also supports the following SCM providers:

14.5.2. Creating a Maven Project from a Maven Archetype

m2eclipse offers the ability to create a Maven project using a Maven Archetype. There are many Maven Archetypes provided in the list that comes with m2eclipse as shown in Figure 14.4, “Creating a New Project with a Maven Archetype”.

Figure 14.4. Creating a New Project with a Maven Archetype

The list of archetypes in Figure 14.4, “Creating a New Project with a Maven Archetype” is a list generated by something called the Nexus Indexer. Nexus is a repository manager which is introduced in Chapter 16, Repository Manager. The Nexus indexer is a file which contains an index of the entire Maven repository, and m2eclipse uses it to list all of the available archetypes in the entire Maven repository. When this chapter was last updated, m2eclipse had approximately ninety archetypes in this Archetype dialog. Highlights of this list include:

^[4]And these were just the archetypes that were listed under the Nexus Indexer Catalog, if you switch Catalogs you'll see other archetypes. While your results may vary, the following additional archetypes were available in the Internal Catalog:

A catalog is simply a reference to a repository index. You can manage the set of catalogs that the m2eclipse plugin knows about by clicking on the Configure... button next to the catalog drop down. If you have your own archetypes to add to this list, you can click on Add Archetype....

Once you choose an archetype, Maven will retrieve the appropriate artifact from the Maven repository and create a new Eclipse project with the selected archetype.

14.5.3. Creating a Maven Module

m2eclipse provides the ability to create a Maven module. Creating a Maven module is almost identical to creating a Maven project as it also creates a new Maven project using a Maven archetype. However, a Maven module is a subproject of another Maven project typically known as a parent project.

Figure 14.5. Creating a New Maven Module

When creating a new Maven module you must select a parent project that already exists inside of Eclipse. Clicking the browse button displays a list of projects that already exist as shown in Figure 14.6, “Selecting a Parent Project for a New Maven Module”:

Figure 14.6. Selecting a Parent Project for a New Maven Module

After selecting a parent project from the list, you are returned to the New Maven Module window and the Parent Project field is populated as shown in Figure 14.5, “Creating a New Maven Module”. Clicking Next will then display the standard list of archetypes from Section 14.5.2, “Creating a Maven Project from a Maven Archetype” so you can choose which one should be used to create the Maven module.

14.7.1. Importing a Maven Project

m2eclipse can import a Maven project with an existing pom.xml. By pointing at the directory where a Maven project is located, m2eclipse detects all the Maven POMs in the project and provides a hierarchical list of them as shown in Figure 14.11, “Importing a Multi-module Maven Project”.

Figure 14.11. Importing a Multi-module Maven Project

Figure 14.11, “Importing a Multi-module Maven Project” displays the view of the project being imported. Notice that all the POMs from the project are listed in a hierarchy. This allows you to easily select which POMs (and therefore which projects) that you want to be imported into Eclipse. Once you select the project you would like to import, m2eclipse will import and build the project(s) using Maven.

14.7.2. Materializing a Maven Project

m2eclipse also offers the ability to "materialize" a Maven project. Materialization is similar to the process of checking out a Maven project from Subversion, but instead of manually entering the URL to the project’s Subversion repository, the Subversion URL is discovered from the project’s root POM file. You can use this feature to "materialize" projects from nothing more than a POM file if the POM file has the appropriate elements to specify the location of a source repository. Using this feature, you can browse the central Maven repository for projects, and materialize them into Eclipse projects. This comes in handy if your project depends on a third-party open source library, and you need to get your hands on the source code. Instead of tracking down the project web site and figuring out how to check it out of Subversion, just use the m2eclipse project to magically "materialize" the Eclipse project.

Figure 14.12, “Materializing a Maven Project” shows the wizard after choosing to materialize Maven projects:

Figure 14.12. Materializing a Maven Project

Notice that the dialog box for Maven artifacts in Figure 14.12, “Materializing a Maven Project” is empty. This is because no projects have been added yet. In order to add a project, you must click the Add button on the right side and select a dependency to add from the central Maven repository. Figure 14.13, “Selecting Artifact to Materialize” shows how to add a project:

Figure 14.13. Selecting Artifact to Materialize

Upon entering a query, candidate dependencies will be located in the local Maven repository. After a few seconds of indexing the local Maven repository, the list of candidate dependencies appears. Select the dependency to add and click OK so that they are added to the list as shown in Figure 14.14, “Materializing Apache Camel”.

Figure 14.14. Materializing Apache Camel

Upon adding a dependency, you have the option of telling the m2eclipse plugin to check out all projects for the artifact.

14.9.1. Adding and Updating Dependencies and Plugins

Let’s say we’d like to add a dependency or a plugin to the camel-core POM. For the sake of demonstration, we're going to add commons-lang as a dependency. (Please note that the functionality for adding a dependency or a plugin is exactly the same so we’ll demonstrate it by adding a dependency.)

m2eclipse offers two options for adding dependencies to a project. The first option is by manually editing the POM file to type in the XML to add the dependency. The downside to manually editing the POM file to add a dependency is that you must already know the information about the artifact, or use the features discussed in the next section to manually locate the artifact information in the repository indexes. The upside is that after manually adding the dependency and saving the POM, the project’s Maven Dependencies container will be automatically updated to include the new dependency. Figure 14.18, “Manually Adding a Dependency to the Project's POM” shows how I added a dependency for commons-lang to the camel-console POM and the Maven Dependencies container was automatically updated to included it:

Figure 14.18. Manually Adding a Dependency to the Project's POM

Manually adding a dependency works well but requires more work than the second approach. Upon manually adding the dependency element to the POM, the Eclipse progress in the lower right-hand corner of the Eclipse workbench reflects the action as shown in Figure 14.19, “Updating Maven Dependencies”:

Figure 14.19. Updating Maven Dependencies

The second option for adding a dependency is much easier because you don’t have to know any information about about the artifact other than its groupId. Figure 14.20, “Searching for a Dependency” shows this functionality:

Figure 14.20. Searching for a Dependency

By simply entering a groupId into the query field, m2eclipse queries the repository indexes and even shows a version of the artifact that is currently in my local Maven repository. This option is preferred because it is such a tremendous time saver. With m2eclipse, you no longer need to hunt through the central Maven repository for an artifact version.

14.9.2. Creating a Maven Module

m2eclipse makes it very easy to create a series of nested projects in a multi-module Maven project. If you have a parent project, and you want to add a module to the project, just right click on the project, go the Maven menu, and choose "New Maven Module Project". m2eclipse will walk you through the project creation process to create a new project, then it will update the parent project's POM to include the module reference. Before m2eclipse came along it was very difficult to use a hierarchy of Maven projects within Eclipse. With m2eclipse, the details of the underlying relationships between parent and child projects are integrated into the development environment.

14.9.3. Downloading Source

If the central Maven repository contains a source artifact for a particular project, you can download the source from the repository and expose it to the Eclipse environment. When you are trying to debug a complex issue in Eclipse, nothing can be easier than being able to right click on a third-party dependency and drill into the code in the Eclipse debugger. Select this option, and m2eclipse will attempt to download the source artifact from the Maven repository. If it is unable to retrieve this source artifact, you should ask the maintainers of the project in question to upload the appropriate Maven source bundle to the central Maven repository.

14.9.4. Opening Project Pages

A Maven POM contains some valuable URLs which a developer may need to consult. These are the project's web page, the URL for the source code repository, a URL for a continuous integration system like Hudson, and a URL for an issue tracker. If these URLs are present in a project's POM, m2eclipse will open these project pages in a browser.

14.9.5. Resolving Dependencies

You can configure a project to resolve dependencies from a workspace. This has the effect of altering the way that Maven locates dependency artifacts. If a project is configured to resolve dependencies from the workspace, these artifacts do not need to be present in your local repository. Assume that project-a and project-b are both in the same Eclipse workspace, and that project-a depends on project-b. If workspace resolution is disabled, the m2eclipse Maven build for project-a will only succeed if project-b's artifact is present in the local repository. If workspace resolution is enabled, m2eclipse will resolve the dependency via the eclipse workspace. In other words, when workspace resolution is enabled, project's don't have to be installed in the local repository to relate to one another.

You can also disable dependency management. This has the effect of telling m2eclipse to stop trying to manage your project's classpath, and it will remove the Maven Dependencies classpath container from your project. If you do this, you are essentially on your own when it comes to managing your project's classpath.

14.10.1. Searching For Maven Artifacts and Java classes

m2eclipse adds a couple of items to the Eclipse Navigation menu that make searching for Maven Artifacts and Java classes easy work. Each option is available by clicking on the Navigate menu as shown in Figure 14.21, “Searching for Artifacts and Classes”:

Figure 14.21. Searching for Artifacts and Classes

Notice the available options in Figure 14.21, “Searching for Artifacts and Classes” under the Eclipse Navigate menu named Open Maven POM and Open Type from Maven. The Open Maven POM option allows you to search the Maven repository for a given POM as shown in Figure 14.22, “Searching for a POM”:

Figure 14.22. Searching for a POM

Upon selecting an artifact and clicking OK, the POM for that artifact is opened in Eclipse for browsing or editing. This is handy when you need to take a quick look at the POM for a given artifact.

The second m2eclipse option in the Navigate menu is named Open Type from Maven. This feature allows you to search for a Java class by name in a remote repository. Upon opening this dialog, simply type ‘factorybean’ and you’ll see many classes with the name FactoryBean in them as shown in Figure 14.23, “Searching the Repository for a Class”:

Figure 14.23. Searching the Repository for a Class

This is a big time saving feature because it means that manually searching through artifacts in a Maven repository for a particular class is a thing of the past. If you need to use a specific class, just fire up Eclipse, go to the Navigate menu and search for the class. m2eclipse will show you the list of artifacts in which it appears.

14.10.2. Indexing Maven Repositories

The Maven Indexes View allows you to manually navigate to POMs in a remote repository and open them in Eclipse. To see this View, go to View → Show View → Other, type the word "maven" into the search box and you should see a view named Maven Indexes as shown in Figure 14.24, “Show Maven Indexes View”:

Figure 14.24. Show Maven Indexes View

Select this View and click OK. This will show the Maven Indexes View as shown in Figure 14.25, “Maven Indexes View”:

Figure 14.25. Maven Indexes View

Additionally, Figure 14.26, “Locating a POM from the Indexes View” shows the Maven Indexes View after manually navigating to locate a POM:

Figure 14.26. Locating a POM from the Indexes View

After finding the apache-camel artifact, double-clicking on it will open it up in Eclipse for browsing or editing.

These features make working with remote repositories from inside of Eclipse so much easier and faster. After all the hours you may have spent doing these types of tasks by manually over the last few years - visiting repositories through a web browser, downloading artifacts and grepping through them for classes and POMs - you'll find that m2eclipse is a welcome change for the better.