Вы находитесь на странице: 1из 124

Edition 1.0

m2eclipse 0.10.0

Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse
Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse
Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse
Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse
Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse
Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse
Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse
Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse

Maven Integration for Eclipse

Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse
Edition 1.0 m2eclipse 0.10.0 Maven Integration for Eclipse

Developing with Eclipse and Maven

Tim O’Brien Jason van Zyl Benjamin Bentmann Igor Fedorenko Brian Fox Milos Kleint Peter Lynch Matthew Piggott Pascal Rapicault Rich Seddon Vlad Tatavu Dan Yocum

A Sonatype Open Book Mountain View, CA

Copyright © 2010 Sonatype, Inc.

This work is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States license. For more information about this license, see http://creativecommons.org/licenses/by-nc-nd/3.0/us/. You are free to share, copy, distribute, display, and perform the work under the following conditions:

• You must attribute the work to Sonatype, Inc. with a link to http://www.sonatype.com.

• You may not use this work for commercial purposes.

• You may not alter, transform, or build upon this work.

Nexus™, Nexus Professional™, and all Nexus-related logos are trademarks or registered trademarks of Sonatype, Inc., in the United States and other countries. Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. IBM® and WebSphere® are trademarks or registered trademarks of International Business Machines, Inc., in the United States and other countries. Eclipse™ is a trademark of the Eclipse Foundation, Inc., in the United States and other countries. Apache and the Apache feather logo are trademarks of The Apache Software Foundation.

Many of the designations used by manufacturers and sellers to distinguish their prod- ucts are claimed as trademarks. Where those designations appear in this book, and Sonatype, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

Published by:

Sonatype, Inc. 800 W. El Camino Real Suite 400 Mountain View, CA 94040.

For online information and ordering of this and other Sonatype books, please visit www.sonatype.com. The publisher o ers discounts on this book when ordered in quantity. For more information, please contact:

book@sonatype.com

ISBN 978-0-9842433-1-0

Editor: Tim OBrien

Copyright

vii

Foreword: 1.1

ix

1. Changes in Edition 1.1

ix

2. Changes in Edition 1.0

ix

I. Sonatype m2eclipse

1

1. Introduction to m2eclipse

3

1.1. Introduction

3

 

1.2. m2eclipse

3

2. Installing m2eclipse

5

2.1. Installing the Eclipse IDE

5

2.2. Installing m2eclipse in Eclipse 3.6 (Helios) with the Eclipse Marketplace

5

 

2.2.1. Installing Maven Integration for Eclipse (Core)

6

2.2.2. Installing Maven Integration for Eclipse (Extras) Prerequisites

8

2.2.3. Installing Maven Integration for Eclipse (Extras)

9

2.3. Installing m2eclipse in Eclipse 3.5 (Gallileo)

11

 

2.3.1. Installing m2eclipse Core Components

11

2.3.2. Installing m2eclipse Extras

12

2.3.3. Installing Optional Prerequisites

12

2.4. Uninstalling m2eclipse from Eclipse 3.6 (Helios) with the Eclipse Marketplace

13

3. Creating and Importing Projects

17

3.1. Creating a Maven Project

17

 

3.1.1. Checking Out a Maven Project from SCM

17

3.1.2. Creating a Maven Project from a Maven Archetype

18

3.1.3. Creating a Maven Module

20

3.2. Create a Maven POM File

22

3.3. Importing Maven Projects

23

 

3.3.1. Importing a Maven Project

24

3.3.2. Materializing a Maven Project

25

4. Running Maven Builds

29

4.1. Enabling the Maven Console

29

4.2. Running Maven Builds

29

5. m2eclipse Preferences

31

5.1.

Maven Preferences

31

6. Working with Maven Repositories

35

6.1. Working with Maven Repositories

35

6.2. Searching For Maven Artifacts and Java classes

35

6.3. Indexing Maven Repositories

37

6.4. Browsing and Manipulating Maven Repositories

38

 

6.4.1. Opening the Maven Repository View

39

6.4.2. Browsing Global Repositories

40

6.4.3. Browsing Your Workspace Repository

40

6.4.4. Browsing a Project Repository

41

6.4.5. Browsing Your Local Repository

43

6.4.6. Manipulating a Repository Index

43

7. Using m2eclipse

45

45

 

7.1.1. Adding and Updating Dependencies and Plugins

45

7.1.2. Downloading Source

46

7.1.3. Opening Project Pages

46

7.1.4. Resolving Dependencies

46

7.2.

Analyzing Project Dependencies in m2eclipse

47

8. Using m2eclipse

51

8.1.

Working with Maven Projects

51

8.1.1.

Downloading Source

52

8.1.2. Opening Project Pages

52

8.1.3. Resolving Dependencies

52

8.2. Using the Form-based POM Editor

52

8.3. Summary

56

II. Maven Studio for Eclipse

57

9. Introduction to Maven Studio for Eclipse

59

9.1. Introduction

59

9.2. Developer Onboarding

59

9.2.1. The Cost of New Developer Onboarding

59

9.2.2. Onboarding with Maven Studio for Eclipse: Productive on Day One

61

9.2.3. Managing Developer Workspace Complexity

61

9.3. Managing Change in Development Environments

62

9.3.1. The Common Scenario: Upgrading Development Infrastructure

63

9.3.2. Disadvantages of a High-Risk Development Environment

63

9.3.3. Advantages of a Low-risk Development Environment

64

9.4. Consolidating Project Feeds

65

9.4.1. Simple Scenario: Aggregating a Project's Feeds

66

9.4.2. Complex Scenarios: Mixed Open/Commercial Development

66

10. Maven Studio for Eclipse Quickstart

69

10.1. Introduction

69

10.1.1. What is a Codebase?

69

10.1.2. What is a Lineup?

69

10.1.3. What is a Source Tree?

70

10.1.4. What is a Source Tree Root?

70

10.1.5. Use Case for a Build Engineer

70

10.2. Getting Started with Maven Studio for Eclipse

70

10.2.1. Nexus Team Edition Prerequisites

71

10.2.2. Workstation Prerequisites

71

10.3. Installing Nexus Team Edition

71

10.3.1. Download Nexus Team Edition

71

10.3.2. Unpack Nexus Team Edition

71

10.3.3. Start Nexus Team Edition

71

10.3.4. Login as a Nexus Administrator

71

10.4. Configure Nexus Team Server

72

10.4.1. Open the Nexus Server Configuration Panel

72

10.4.2. Configure Proxy Settings

72

10.4.3. Save the Nexus Server Configuration

72

10.4.4. Add a New P2 Proxy Repository

72

10.4.5. Configure the New Proxy Repository

73

10.5. Run the Publish Lineups Scheduled Task in Nexus Team Server

73

10.5.1. Execute a Scheduled Task for P2 Lineups

73

10.5.2. Verify P2 Lineups are Published

73

10.6. Materialize a Sample Workspace

74

10.6.1. Open the Repositories Panel

74

10.6.2. Select Nexus Managed Repositories

74

10.6.3. Select Sonatype MSE Repository

74

10.6.4. Click on the MSE Installer for the Maven Lineup

74

10.6.5. Run the MSE Installer

75

10.6.6. Supply Server and Source Control Credentials

75

10.6.7. Specify Installation Directories

76

10.6.8. Verify Completed Eclipse Installation

76

10.6.9. Configure Password Recovery

77

10.7.

Creating a New MSE Lineup

78

 

10.7.1. Create a New MSE Lineup Project

78

10.7.2. Select the New P2 Lineup Wizard

79

10.7.3. Configure Nexus and Lineup Coordinates

79

10.7.4. Select Runtime Platform and Memory

80

10.7.5. Configure the Contents of the Lineup

80

10.7.6. Add a New Repository

81

10.7.7. Add the Checkstyle Plugin Installable Unit

81

10.7.8. Verify the P2 Lineup

81

 

10.8. Configuring a New Codebase

82

 

10.8.1. Maximize the Codebase Overview

82

10.8.2. Create a New Source Tree

83

10.8.3. Configure the New Source Tree

83

10.8.4. Configure the SCM Location

83

10.8.5. Add a Feed URL

84

 

10.9. Publishing a Codebase

84

 

10.9.1. Publish Your Codebase to Nexus

84

10.9.2. Supply Nexus Team URL and Credentials

85

10.9.3. Publish the Codebase

85

 

10.10. Materializing a Codebase

85

 

10.10.1. Download the Codebase Installer

85

10.10.2. Supply Apache Subversion Credentials

86

10.10.3. Supply Nexus Credentials

86

10.10.4. Configure Materialization Directories

87

10.10.5. Use Your Materialized Eclipse Installation

87

 

10.11. Troubleshooting Codebase Materialization

88

 

10.11.1.

Reset Subversion Connection

88

11. Managing MSE Codebases and P2 Lineups

89

 

11.1. Introduction

 

89

11.2. Creating a MSE Codebase

89

 

11.2.1. Creating a New P2 Lineup

89

11.2.2. Creating a New MSE Codebase

92

 

11.3. Configuring a MSE Codebase

92

11.4. Configuring Codebase Information

94

11.5. Managing Codebase Resource Locations

95

 

11.5.1. Publishing Eclipse Preferences

96

11.5.2. Publishing Maven Settings

96

 

11.6. Setting Codebase Prerequisites

97

11.7. Managing Codebase Source Trees

97

11.8. Configuring Codebase Security

98

11.9. Configuring a Source Tree

98

 

11.9.1. Adding a Maven Profile

100

11.9.2. Adding a New Feed URL

100

 

11.10.

Publishing an MSE Codebase to Nexus Team Edition

100

A. Creative Commons License

103

A.1. Creative Commons BY-NC-ND 3.0 US License

103

B. Book Revision History

 

107

B.1. Changes in Edition 0.8

107

B.2. Changes in Edition 0.7

107

B.3. Changes in Edition 0.6

107

Index

109

Copyright

Copyright © 2010 Sonatype, Inc.

Online version published by Sonatype, Inc., 800 W. El Camino Real, Suite 400, Mountain View, CA, 94040.

This work is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States license. For more information about this license, see http://creativecommons.org/licenses/by-nc-nd/3.0/us/.

Nexus™, Nexus Professional™, and all Nexus-related logos are trademarks or registered trademarks of Sonatype, Inc., in the United States and other countries.

Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries.

IBM® and WebSphere® are trademarks or registered trademarks of International Business Machines, Inc., in the United States and other countries.

Eclipse™ is a trademark of the Eclipse Foundation, Inc., in the United States and other countries.

Apache and the Apache feather logo are trademarks of The Apache Software Foundation.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and Sonatype, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

Foreword: 1.1

You are encouraged to check http://books.sonatype.com/m2eclipse-book weekly for any updates to the content. If you would like to receive updates whenever there is a change to this user's manual, please send a quick note to book@sonatype.com 1 , and we will gladly add your email to the update notification list.

We welcome your feedback, please do not hesitate to contact the Sonatype team with any questions or ideas you may have about the product.

Tim O'Brien, Sonatype

July, 2010

Edition: 1.1

1. Changes in Edition 1.1

The following changes were introduced in Edition 1.1 in July, 2010:

• Added Section 2.2, “Installing m2eclipse in Eclipse 3.6 (Helios) with the Eclipse Marketplace”

2. Changes in Edition 1.0

The following changes were introduced in Edition 1.0 in June 2010:

• Added a new part to the book on Maven Studio for Eclipse.

• Added Maven Studio for Eclipse chapters to the book.

• Chapter 9, Introduction to Maven Studio for Eclipse

• Chapter 10, Maven Studio for Eclipse Quickstart

• Chapter 11, Managing MSE Codebases and P2 Lineups

Part I. Sonatype m2eclipse

The first portion of this book deals with the Sonatype m2eclipse plugin.

Chapter 1. Introduction to m2eclipse

1.1. Introduction

The Eclipse IDE is the most widely used IDE for Java development today. Eclipse has a huge amount of plugins (see http:// www.eclipseplugincentral.com/) and an innumerable amount of organizations developing their own software on top of it. Quite simply, Eclipse is ubiquitous. The m2eclipse 1 project, provides support for Maven within the Eclipse IDE, and, in this chapter, we will explore the features it provides to help you use Maven with Eclipse.

1.2. m2eclipse

The m2eclipse plugin (http://m2eclipse.sonatype.org/) provides Maven integration for Eclipse. m2eclipse also has hooks into the features of both the Subclipse plugin (http://subclipse.tigris.org/) and the Mylyn plugin (http://www.eclipse.org/mylyn/). The Subclipse plugin provides the m2eclipse plugin with the ability to interact with Subversion repositories, and the Mylyn plugin provides the m2eclipse plugin with the ability to interact with a task-focused interface that can keep track of development context. Just a few of the features m2eclipse provides include:

• Creating and importing Maven projects

• Dependency management and integration with the Eclipse classpath

• Automatic dependency downloads and updates

• Artifact Javadoc and source resolution

• Creating projects with Maven Archetypes

• Browsing and searching remote Maven repositories

• POM management with automatic update to dependency list

• Materializing a project from a Maven POM

• Checking out a Maven project from several SCM repositories

• Adapting nested multi-module Maven projects to the Eclipse IDE

• Integration with Web Tools Project (WTP)

• Integration with Subclipse

• Integration with Mylyn

• Form-based POM Editor

• Graphical Display of Dependency Graph

• GUI Presentation of Dependency Tree and Resolved Dependencies

There are many more features in m2eclipse beyond the list above and this chapter introduces some of the more impressive features that are currently available. Let’s get started by installing the m2Eclipse plugin.

Chapter 2. Installing m2eclipse

2.1. Installing the Eclipse IDE

Sonatype recommends installing m2eclipse on Eclipse 3.5 or Eclipse 3.6, and to make use of m2eclipse you will need to install the JDK. To download an Eclipse IDE distribution:

1. Go to http://www.eclipse.org/downloads/ in a web browser.

2. Download an Eclipse distribution. Note: If you want to use the m2eclipse WTP integration, download the Eclipse IDE for JavaEE Developers distribution.

3. Install Eclipse - for more information about installing the Eclipse IDE, see the Eclipse Wiki 1 .

2.2. Installing m2eclipse in Eclipse 3.6 (Helios) with the Eclipse

Marketplace

The Eclipse Marketplace makes it easy to install m2eclipse and m2eclipse (Extras) in Eclipse 3.6 (Helios). To open the Eclipse

Marketplace, go to the Eclipse Help menu and select Eclipse Marketplace Marketplace”.

as shown in Figure 2.1, “Opening the Eclipse

as shown in Figure 2.1, “Opening the Eclipse Figure 2.1. Opening the Eclipse Marketplace The first

Figure 2.1. Opening the Eclipse Marketplace

The first time you open the Eclipse Marketplace, you will be asked to select a Marketplace. Select the Eclipse Marketplace as shown in Figure 2.2, “Selecting the Eclipse Marketplace”.

Figure 2.2. Selecting the Eclipse Marketplace 2.2.1. Installing Maven Integration for Eclipse (Core) Maven Integration

Figure 2.2. Selecting the Eclipse Marketplace

2.2.1. Installing Maven Integration for Eclipse (Core)

Maven Integration for Eclipse is separated into two components: the Core of Maven Integration for Eclipse and an optional package of extra, unsupported components. To install the core component of Maven Integration for Eclipse, open the Eclipse Marketplace, select the Search tab, and search for "Maven Integration" as shown in Figure 2.3, “Selecting Maven Integration for Eclipse from Eclipse Marketplace”. Click on the Install button to the right of the second item listed in Figure 2.3, “Selecting Maven Integration for Eclipse from Eclipse Marketplace”.

Maven Integration for Eclipse from Eclipse Marketplace”. Figure 2.3. Selecting Maven Integration for Eclipse from

Figure 2.3. Selecting Maven Integration for Eclipse from Eclipse Marketplace

Once you click on Install, Eclipse will download a list of available components from the remote update site and present you with a list of available features in the Maven Integration for Eclipse plugin as shown in Figure 2.4, “Selecting the Core m2eclipse Feature for Installation”. Select the single, required component named "Maven Integration for Eclipse (Required)", and click on the Finish button.

Figure 2.4. Selecting the Core m2eclipse Feature for Installation Eclipse will then ask you to

Figure 2.4. Selecting the Core m2eclipse Feature for Installation

Eclipse will then ask you to agree to the licenses for Maven Integration for Eclipse in the Review Licenses step shown in Figure 2.5, “Agreeing to Software License During m2eclipse Installation”. Maven Integration for Eclipse is distributed under the Eclipse Public License version 1.0. If you agree with the conditions of this license, select "I accept the terms of the license agreement" and click on the Finish button.

the license agreement" and click on the Finish button. Figure 2.5. Agreeing to Software License During

Figure 2.5. Agreeing to Software License During m2eclipse Installation

During the installation process, Eclipse may warn you that the software you are installing contains "unsigned content". If you see the dialog shown in Figure 2.6, “Ignoring Warning During m2eclipse Installation”, click on OK to continue the installation process.

click on OK to continue the installation process. Figure 2.6. Ignoring Warning During m2eclipse Installation

Figure 2.6. Ignoring Warning During m2eclipse Installation

Once m2eclipse has been installed, Eclipse will prompt you to either restart or apply changes to a running Eclipse. At this stage of the installation, you should click on Restart Now to restart your Eclipse instance. After a successful restart, Maven Integration for Eclipse will be installed.

Figure 2.7. Restarting Eclipse after m2eclipse Installation 2.2.2. Installing Maven Integration for Eclipse (Extras)

Figure 2.7. Restarting Eclipse after m2eclipse Installation

2.2.2. Installing Maven Integration for Eclipse (Extras) Prerequisites

The Maven Integration for Eclipse extra components provide support for additional tools like the Web Tools Project (WTP), Subversion integration via Subclipse, and integration with Mylyn. The following sections provide guidance for users installing some of the prerequisites for m2eclipse extra components.

2.2.2.1. Installing Subclipse in the Eclipse Marketplace

To install Subclipse in the Eclipse Marketplace, open the Marketplace, select the Search tab, and search for "Subclipse" to see the dialog shown in Figure 2.8, “Selecting Subclipse from the Eclipse Marketplace”. Click on Install next to the Subclipse search result item.

Click on Install next to the Subclipse search result item. Figure 2.8. Selecting Subclipse from the

Figure 2.8. Selecting Subclipse from the Eclipse Marketplace

Select the appropriate Subclipse components, agree to the software license for Subclipse, and restart your Eclipse installation after the installation process is completed.

2.2.2.2. Installing Mylyn in the Eclipse Marketplace

To install Mylyn in the Eclipse Marketplace, open the Marketplace, select the Search tab, and search for "Mylyn" to see the dialog shown in Figure 2.9, “Selecting Mylyn from the Eclipse Marketplace”. Click on Install next to the Mylyn search result item.

Figure 2.9. Selecting Mylyn from the Eclipse Marketplace Select the appropriate SMylyn components, agree to

Figure 2.9. Selecting Mylyn from the Eclipse Marketplace

Select the appropriate SMylyn components, agree to the software license for Mylyn, and restart you Eclipse installation after the installation process is completed.

2.2.3. Installing Maven Integration for Eclipse (Extras)

To install the extra components for Maven Integration for Eclipse, open the Eclipse Marketplace, select the Search tab, and search for Maven Integration to see the search results shown in Figure 2.10, “Selecting Maven Integration for Eclipse (Extras) from the Eclipse Marketplace”. CLick on Install next to the "Maven Integration for Eclipse (Extras)" search result item.

Integration for Eclipse (Extras)" search result item. Figure 2.10. Selecting Maven Integration for Eclipse

Figure 2.10. Selecting Maven Integration for Eclipse (Extras) from the Eclipse Marketplace

Once you have clicked on Install, Eclipse will download the list of available plugin components from the remote update site. The list of available components will then be displayed in the Confirm Select Features step as shown in Figure 2.11, “Selecting m2eclipse (Extras) Components to Install”. The components available in the Maven Integration for Eclipse (Extras) site are:

M2Eclipse Extensions Development Suppport (Optional) Install this component if you want to develop custom pages in the POM Editor, create custom actions in the Maven popup menu, provide custom templates in the POM XML editor, or make other customizations to m2eclipse.

Maven Integration for WTP (Optional) If you are developing applications using the Eclipse Web Tools Project, this component will adapt the Maven classpath container and other Maven resources to the WTP standards.

Maven issue tracking configurator for Mylyn 3.x (Optional) Maven can be configured to work with Mylyn a comprehensive issue and time tracking plugin which currently ships with the Eclipse IDE.

Maven SCM handler for Subclipse (Optional) Subclipse is a popular Subversion plugin for Eclipse hosted by the Tigris community. If you want to use Maven with Subclipse, this component will provide the necessary integration between the two plugins.

Maven SCM handler for Team/CVS (Optional) This component provides integration between the m2eclipse plugin and the CVS support built into Eclipse.

Maven SCM Integration (Optional) This component is required if you installed one of the previous plugins (Subclipse or Team/CVS)

Project configurators for commonly used maven plugins (temporary) This is a temporary project which contains project configurators for commonly used Maven Plugins.

project configurators for commonly used Maven Plugins. Figure 2.11. Selecting m2eclipse (Extras) Components to

Figure 2.11. Selecting m2eclipse (Extras) Components to Install

Once you have selected the features you wish to install, click Next. Clicking Next will bring you to the Review Licenses step as shown in Figure 2.12, “Agreeing to Software License During m2eclipse (Extras) Installation”. The m2eclipse Extras is distributed under the Eclipse Public License version 1.0. If you agree to this open source license, select "I accept the terms of the license agreement" and click on "Finish".

Figure 2.12. Agreeing to Software License During m2eclipse (Extras) Installation During the installation process for

Figure 2.12. Agreeing to Software License During m2eclipse (Extras) Installation

During the installation process for the m2eclipse Extras, you may receive some warning that "you are installing software that contains unsigned content". If you see the dialog shown in Figure 2.13, “Ignoring Warning During m2eclipse (Extras) Installation”, click OK to continue the installation process.

click OK to continue the installation process. Figure 2.13. Ignoring Warning During m2eclipse (Extras)

Figure 2.13. Ignoring Warning During m2eclipse (Extras) Installation

Once the installation process is finished, Eclipse will prompt you to apply the changes or restart your Eclipse instance with a dialog shown in Figure 2.14, “Restarting Eclipse after m2eclipse (Extras) Installation”. To complete the installation of m2eclipse (Extras), restart your Eclipse instance.

of m2eclipse (Extras), restart your Eclipse instance. Figure 2.14. Restarting Eclipse after m2eclipse (Extras)

Figure 2.14. Restarting Eclipse after m2eclipse (Extras) Installation

2.3. Installing m2eclipse in Eclipse 3.5 (Gallileo)

2.3.1. Installing m2eclipse Core Components

To install m2eclipse, use the following Eclipse update site to install the core of the m2eclipse plugin. This Core update site contains a single component: "Maven Integration for Eclipse (Required)". When you install this component you will be installing all of the core Wizards, the POM Editor, Maven Repository integration, and Maven integration:

To install this plugin in the Eclipse IDE:

1. Select Help > Install New Software. This should display the "Install" dialog.

2.

Paste the Update Site URL into the field named "Work with:" and press Enter. Pressing Enter should cause Eclipse to update list of available plugins and components.

3. Choose the component listed under m2eclipse: "Maven Integration for Eclipse (Required)".

4. Click Next. Eclipse will then check to see if there are any issues which would prevent a successful installation.

5. Click Next and agree to the terms of the Eclipse Public License v1.0.

6. Click Finish to begin the installation process.

Eclipse will then download and install the necessary components. Once the installation process is finished, Eclipse will ask you if you want to restart the IDE. Sonatype strongly recommends that you restart your IDE after installing m2eclipse.

Warning

You cannot upgrade from m2eclipse 0.9 to m2eclipse 0.10. If you are running m2eclipse 0.9.8 or 0.9.9 you must either uninstall m2eclipse from your Eclipse installation or start with a fresh installation of Eclipse.

If you've installed the plugin successfully, you should see a Maven option in the list of preference categories when you go to Window, Preferences

2.3.2. Installing m2eclipse Extras

In addition to the core m2eclipse components, the following optional components are available from a separate update site. If you plan to use m2eclipse to materialize projects from Subversion or CVS, integrate Maven with the Eclipse Web Tools Project (WTP), or use the m2eclipse Mylyn integration you will need to install the following, extra components:

• Maven SCM Integration

• Maven SCM handler for Team/CVS

• Maven SCM handler for Subclipse

• Maven issue tracking configurator for Mylyn 3.x

• Maven Integration for WTP

• M2Eclipse Extensions Development Support

To install optional m2eclipse components, use the m2eclipse Extras update site. This update site contains the following m2eclipse components:

• m2eclipse Extras Update Site: http://m2eclipse.sonatype.org/sites/m2e-extras

2.3.3. Installing Optional Prerequisites

Several of the extra components listed in the previous section require third-party plugins to be installed prior to installation. You can install these prerequisites when you install m2eclipse, just add a new remote update site to Eclipse for each of the prerequisite components.

which will load the "Software Updates and Add-ons" dialog. In

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, you should restart the IDE.

To install these prerequisites, select Help, Install New Software

this dialog, choose the Available Software panel and click on Add Site

2.3.3.1.

Installing Subclipse

When you install Subclipse, you will need to make a decision about Subversion compatibility. If you are using Subversion 1.5.x client features, you will need to install Subclipse version 1.4. If you are using Subversion 1.6.x client features, you will need to install Subclipse version 1.6.

To install Subclipse, use one of the Eclipse plugin update sites listed below.

• Subclipse 1.4 (for Subversion 1.5 compatibility): http://subclipse.tigris.org/update_1.4.x

• Subclipse 1.6 (for Subversion 1.6 compatibility): http://subclipse.tigris.org/update_1.6.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/.

2.3.3.2. Installing Mylyn

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

• Mylyn (Eclipse 3.4, 3.5, and 3.6M4): http://download.eclipse.org/tools/mylyn/update/e3.4

• Mylyn Extras (JIRA and Trac 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/.

2.3.3.3. Installing the Web Tools Platform (WTP)

To install the Web Tools Platform (WTP). Install the "Eclipse IDE for Java EE Developers" from http://www.eclipse.org/downloads/, or download a WTP release from http://download.eclipse.org/webtools/downloads/.

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

2.4. Uninstalling m2eclipse from Eclipse 3.6 (Helios) with the Eclipse Marketplace

To uninstall m2eclipse and m2eclipse (Extras) from Eclipse 3.6 (Helios), open up the Eclipse Marketplace by selecting Eclipse Marketplace from the Eclipse Help menu. Once you have the Eclipse Marketplace dialog open, select the Installed tab as shown in Figure 2.15, “Selecting Maven Integration for Eclipse Components to Uninstall”. To uninstall either "Maven Integration for Eclipse" or "Maven Integration for Eclipse (Extras)", click on the "Uninstall" button next to each item.

Figure 2.15. Selecting Maven Integration for Eclipse Components to Uninstall If you are uninstalling "Maven

Figure 2.15. Selecting Maven Integration for Eclipse Components to Uninstall

If you are uninstalling "Maven Integration for Eclipse", the Eclipse IDE will prompt you to select the feature you wish to uninstall as shown in Figure 2.16, “Selecting Components to Install for Maven Integration for Eclipse Installation”. Select the feature to uninstall, and click on Next to continue.

the feature to uninstall, and click on Next to continue. Figure 2.16. Selecting Components to Install

Figure 2.16. Selecting Components to Install for Maven Integration for Eclipse Installation

If you are uninstalling "Maven Integration for Eclipse (Extras)", the Eclipse IDE will prompt you to select the features you wish to uninstall as shown in Figure 2.17, “Selecting Maven Integration for Eclipse (Extras) Features to Uninstall”. Select the features to uninstall, and click on "Finish" or "Next".

Figure 2.17. Selecting Maven Integration for Eclipse (Extras) Features to Uninstall Once the uninstallation has

Figure 2.17. Selecting Maven Integration for Eclipse (Extras) Features to Uninstall

Once the uninstallation has successfully completed, Eclipse will prompt you to either apply changes or restart. To complete the uninstallation process, click on "Restart Now".

the uninstallation process, click on "Restart Now". Figure 2.18. Restarting Eclipse after Uinstallation 15

Figure 2.18. Restarting Eclipse after Uinstallation

Chapter 3. Creating and Importing Projects

3.1. Creating a Maven Project

When using Maven, project creation takes place through the use of a Maven archetype. In Eclipse, project creation takes place via the new project wizard. The new project wizard inside of Eclipse offers a plethora of templates for creating new projects. The m2eclipse plugin improves upon this wizard to provide the following additional capabilities:

• Checking out a Maven project from a SCM repository

• Creating a Maven project using a Maven archetype

• Creating a Maven POM file

As shown in Figure 3.1, “Creating a New Project with m2eclipse Wizards”, all three of these options are important to developers using Maven. Let’s take a look at each one.

to developers using Maven. Let’s take a look at each one. Figure 3.1. Creating a New

Figure 3.1. Creating a New Project with m2eclipse Wizards

3.1.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 3.2, “Checkout a New Project from Subversion”:

Figure 3.2. Checkout a New Project from Subversion There are additional options in this dialog

Figure 3.2. 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. The m2eclipse plugin supports the following SCM providers:

• Bazaar

• Clearcase

• CVS

• git

• hg

• Perforce

• Starteam

• Subversion

• Synergy

• Visual SourceSafe

3.1.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 3.3, “Creating a New Project with a Maven Archetype”.

Figure 3.3. Creating a New Project with a Maven Archetype The list of archetypes in

Figure 3.3. Creating a New Project with a Maven Archetype

The list of archetypes in Figure 3.3, “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 "Repository Management with Nexus", a free book available from Sonatype which can be read online here: http://www.sonatype.com/books/nexus-book/reference/ 1 . 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:

• Standard Maven Archetypes to create

• Maven Plugins

• Simple Web Applications

• Simple Projects

• New Maven Archetypes

Databinder 2 Archetypes (data-driven Wicket Applications) under net.databinder

Apache Cocoon 3 Archetypes under org.apache.cocoon

Apache Directory Server 4 Archetypes under org.apache.directory.server

Apache Geronimo 5 Archetypes under org.apache.geronimo.buildsupport

Apache MyFaces 6 Archetypes under org.apache.myfaces.buildtools

Apache Tapestry 7 Archetypes under org.apache.tapestry

Apache Wicket 8 Archetypes under org.apache.wicket

1 ???

AppFuse 9 Archetypes under org.appfuse.archetypes

Codehaus Cargo 10 Archetypes under org.codehaus.cargo

Codehaus Castor 11 Archetypes under org.codehaus.castor

Groovy-based Maven Plugin 12 Archetypes (deprecated) 19 under org.codehaus.mojo.groovy

• Jini Archetypes

Mule 13 Archetypes under org.mule.tools

Objectweb Fractal 14 Archetypes under org.objectweb.fractal

Objectweb Petals 15 Archetypes under org.objectweb.petals

• ops4j Archetypes under org.ops4j

Parancoe 16 under org.parancoe

• slf4j Archetypes under org.slf4j

Springframework 17 OSGI and Web Services Archetypes under org.springframework

Trails Framework 18 Archetypes under org.trailsframework

19 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:

Atlassian Confluence 20 Plugin Archetype under com.atlassian.maven.archetypes

Apache Struts 21 Archetypes under org.apache.struts

• Apache Shale Archetypes under org.apache.shale

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 click on Add Archetype

button next to the catalog drop down. If you have your own archetypes to add to this list, you can

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.

3.1.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.

19 Don't use the Groovy Maven Plugin in Codehaus' Mojo project. Jason Dillon has moved the Groovy Maven integration to the Groovy project in codehaus. For more information see http://groovy.codehaus.org/GMaven.

Figure 3.4. Creating a New Maven Module When creating a new Maven module you must

Figure 3.4. 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 3.5, “Selecting a Parent Project for a New Maven Module”:

“Selecting a Parent Project for a New Maven Module”: Figure 3.5. Selecting a Parent Project for

Figure 3.5. 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 3.4, “Creating a New Maven Module”. Clicking Next will then display the standard list of archetypes

from Section 3.1.2, “Creating a Maven Project from a Maven Archetype” so you can choose which one should be used to create the Maven module.

3.2. Create a Maven POM File

Another important feature m2eclipse offers is the ability to create a new Maven POM file. m2eclipse provides a wizard to easily create a new POM file inside of a project that is already in Eclipse. This POM creation wizard is shown in Figure 3.6, “Creating a New POM”:

wizard is shown in Figure 3.6, “Creating a New POM”: Figure 3.6. Creating a New POM

Figure 3.6. Creating a New POM

Creating a new Maven POM is just a matter of selecting a project, entering the Group Id, Artifact Id, Version, choosing the Packaging type, and providing a Name into the fields provided and m2eclipse. Click the Next button to start adding dependencies.

and m2eclipse. Click the Next button to start adding dependencies. Figure 3.7. Adding Dependencies to a

Figure 3.7. Adding Dependencies to a New POM

As you can see in Figure 3.7, “Adding Dependencies to a New POM” here are no dependencies in the POM yet. Just click the Add button to query the central Maven repository for dependencies as shown next in Figure 3.8, “Querying the Central Repository for Dependencies”:

3.8, “Querying the Central Repository for Dependencies”: Figure 3.8. Querying the Central Repository for Dependencies

Figure 3.8. Querying the Central Repository for Dependencies

Querying for dependencies is as easy as entering the groupId for the artifact you need. Figure 3.8, “Querying the Central Repository for Dependencies” shows a query for org.apache.commons with commons-vfs expanded to see which versions are available. Highlighting the 1.1-SNAPSHOT version of commons-vfs and clicking OK takes you back to the dependency selection where you can either query for more artifacts or just click finish to create the POM. When you search for dependencies, m2eclipse is making use of the same Nexus repository index that is used in the Nexus Repository Manager, a repository manager introduced in "Repository Management with Nexus" (http://www.sonatype.com/books/nexus-book/reference/).

Now that the you’ve seen the m2eclipse features for creating a new project, let’s look at a similar set of features for importing projects into Eclipse.

3.3. Importing Maven Projects

m2eclipse provides three options for importing a Maven project into Eclipse including:

• Import an existing Maven project

• Check out a Maven project from SCM

• Materialize a Maven project

Figure 3.9, “Importing a Maven Project” shows the wizard for importing projects with the options for Maven provided by m2eclipse:

Figure 3.9. Importing a Maven Project The dialog in Figure 3.9, “Importing a Maven Project”

Figure 3.9. Importing a Maven Project

The dialog in Figure 3.9, “Importing a Maven Project” is displayed by using the File, Import command in Eclipse and then filtering the options by entering the word maven in the filter field. As noted above, there are three options available for importing a Maven project into Eclipse including: Maven Projects, Check out Maven Project from Subversion, and Materialize Maven Projects.

Importing a Maven project from Subversion is identical to the creation of a Maven project from Subversion as discussed in the previous section so discussion of it would be redundant. Let’s move on now to review the other two options for importing a Maven project into Eclipse.

3.3.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 3.10, “Importing a Multi-module Maven Project”.

Figure 3.10. Importing a Multi-module Maven Project Figure 3.10, “Importing a Multi-module Maven Project” displays

Figure 3.10. Importing a Multi-module Maven Project

Figure 3.10, “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.

3.3.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 3.11, “Materializing a Maven Project” shows the wizard after choosing to materialize Maven projects:

Figure 3.11. Materializing a Maven Project Notice that the dialog box for Maven artifacts in

Figure 3.11. Materializing a Maven Project

Notice that the dialog box for Maven artifacts in Figure 3.11, “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 3.12, “Selecting Artifact to Materialize” shows how to add a project:

Artifact to Materialize” shows how to add a project: Figure 3.12. Selecting Artifact to Materialize Upon

Figure 3.12. 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 3.13, “Materializing Apache Camel”.

Figure 3.13. Materializing Apache Camel Upon adding a dependency, you have the option of telling

Figure 3.13. Materializing Apache Camel

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

Chapter 4. Running Maven Builds

4.1. Enabling the Maven Console

Before we begin to examine the features of m2eclipse, let’s first enable the Maven console. Open the Console View by going to Window, Show View, Console. Then click on the little arrow on the right-hand side of the Open Console icon and select Maven Console as shown below:

Open Console icon and select Maven Console as shown below: Figure 4.1. Enabling the Maven Console

Figure 4.1. Enabling the Maven Console in Eclipse

Maven Console shows the Maven output that normally appears on the console when running Maven from the command line. It is useful to be able to see what Maven is doing and to work with Maven debug output to diagnose issues.

4.2. Running Maven Builds

m2eclipse modified the Run As

an Eclipse build with Run As

common lifecycle phases like clean, install, or package. You can also load up the Run configuration dialog window and configure a Maven build with parameters and more options.

menu for an m2eclipse project. From this menu you can run one of the more

menus to allow you to run a Maven build within Eclipse. Figure 4.2, “Running

and Debug As

” shows the Run As

Figure 4.2, “Running and Debug As ” shows the Run As Figure 4.2. Running an Eclipse

Figure 4.2. Running an Eclipse build with Run As

If you need to configure a Maven build with more options, you can choose Run Configurations

Figure 4.3, “Configuring a Maven Build as a Run Configuration” shows the Run dialog for configuring a Maven build.

and create a new Maven build.

Figure 4.3. Configuring a Maven Build as a Run Configuration The Run configuration dialog allows

Figure 4.3. Configuring a Maven Build as a Run Configuration

The Run configuration dialog allows you to specify multiple goals and profiles, it exposes options like "skip tests" and "update snapshots", and allows you to customize everything from the project to the JRE to the environment variable. You can use this dialog to support any custom Maven build that you wish to launch with m2eclipse.

Chapter 5. m2eclipse Preferences

5.1. Maven Preferences

The ability to adjust the Maven preferences and some Maven options is an important aspect of developing with Maven and m2eclipse offers the ability to tweak these items via the Maven preferences page inside of Eclipse. Typically when using Maven on the command line, such preferences and options are available from files in your ~/.m2 directory and as command line options. m2eclipse provides access to some of the most important preferences and options from the Eclipse IDE. Figure 5.1, “Maven Preferences for Eclipse” shows the Maven preferences page in Eclipse:

for Eclipse” shows the Maven preferences page in Eclipse: Figure 5.1. Maven Preferences for Eclipse The

Figure 5.1. Maven Preferences for Eclipse

The check boxes in the top section provide the ability to:

• Run Maven in Offline mode, disabling any downloads from remote repositories

• Enable Debug output in the Maven Console

• Download Source jars for artifacts from remote Maven repositories

• Download JavaDoc jars for artifacts from remote Maven repositories

• Download and Update local indexes for remote repositories on startup

The next section offers a pop-up menu to select which goal you’d like to be executed when a project is imported and when the source folders for a given project are updated. The default goal is named process-resources which copies and process the resources for the project into the destination directory to make the project ready for packaging. Customizing this list of goals can come in handy if you need to run any custom goals which process resources or generate supporting configuration.

If you need help selecting a goal, click the Select

“Maven Goal Dialogs” shows the Goals dialog with a list of all the phases in the default Maven lifecycle.

button to see the "Goals" dialog. The dialog on the left-hand side ofFigure 5.2,

Figure 5.2. Maven Goal Dialogs When you see the Goals dialog for the first time,

Figure 5.2. Maven Goal Dialogs

When you see the Goals dialog for the first time, there's a chance you might be overwhelmed by the number of goals it lists. There are literally hundreds of Maven plugins for everything from generating a database, to running integration tests, to performing static analysis, to generating web services with XFire. There are over two hundred plugins with selectable goals in the Goals dialog, the dialog on the right-hand side ofFigure 5.2, “Maven Goal Dialogs” shows the "Goals" dialog with the Tomcat Maven plugin's goals highlighted. You can always narrow the list of goals shown in this dialog by typing in some text to the search dialog, as you type in text, m2eclipse is going to narrow the list of available goals to goals which contain the text in the search field.

Another Maven preference page is the Maven Installations configuration page shown in Figure 5.3, “Maven Installations Preference Page”:

page shown in Figure 5.3, “Maven Installations Preference Page”: Figure 5.3. Maven Installations Preference Page 32

Figure 5.3. Maven Installations Preference Page

This page allows you to add other Maven installations to the Eclipse environment. If you want to use a different version of Maven with the m2eclipse plugin you can configure multiple installations of Maven from this configuration page, this is very similar to the ability to add more than one Java Virtual Machine to be run inside of Eclipse. An embedded version of the Maven known as the Maven Embedder is already specified. This is what is used to execute Maven inside of Eclipse. If you have another installation of Maven which you would like to use instead of the Maven Embedder, you can add another Maven runtime by clicking on the Add button. Figure 5.3, “Maven Installations Preference Page” shows a configuration page that lists the Maven Embedder, Maven 2.0.9, and an installation of Maven 2.1-SNAPSHOT.

The Installations configuration page also allows you to specify the location of the global Maven settings file. If you do not specify the location of this file on this configuration page, Maven will use the default global settings file found in conf/settings.xml of the selected Maven installation. You can also customize the location of your user settings file from the default location of ~/.m2/settings.xml, and you can customize the location of your local Maven repository from the default location of ~/.m2/

repository.

Also available in the Eclipse preferences is the ability to enable a decorator named the Maven Version Decorator. This preference provides a given project’s current version on the Eclipse Package Explorer and is shown in Figure 5.4, “Enabling the Maven Version Decorator”.

in Figure 5.4, “Enabling the Maven Version Decorator”. Figure 5.4. Enabling the Maven Version Decorator To

Figure 5.4. Enabling the Maven Version Decorator

To enable this preference, simply check the Maven Version Decorator option that is highlighted in Figure 5.4, “Enabling the Maven Version Decorator”. If the Maven Version Decorator is not enabled, a project will only list it’s name and relative path in the Package Explorer as shown in Figure 5.5, “Package Explorer without Maven Version Decorator”:

Figure 5.5. Package Explorer without Maven Version Decorator Upon enabling the Maven Version Decorator, the

Figure 5.5. Package Explorer without Maven Version Decorator

Upon enabling the Maven Version Decorator, the project name will include the current project version as shown in Figure 5.6, “Package Explorer with Maven Version Decorator Enabled”:

“Package Explorer with Maven Version Decorator Enabled”: Figure 5.6. Package Explorer with Maven Version Decorator

Figure 5.6. Package Explorer with Maven Version Decorator Enabled

This is a helpful feature that provides the project version at a glance instead of being required to open the POM to locate the version element.

Chapter 6. Working with Maven Repositories

6.1. Working with Maven Repositories

m2eclipse also provides some tools to make working with Maven repositories a bit easier. These tools provide functionality for:

• Searching for Artifacts

• Searching for Java classes

• Indexing Maven repositories

6.2. 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 6.1, “Searching for Artifacts and Classes”:

in Figure 6.1, “Searching for Artifacts and Classes”: Figure 6.1. Searching for Artifacts and Classes Notice

Figure 6.1. Searching for Artifacts and Classes

Notice the available options in Figure 6.1, “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 6.2, “Searching for a POM”:

Figure 6.2. Searching for a POM Upon selecting an artifact and clicking OK, the POM

Figure 6.2. 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 6.3, “Searching the Repository for a Class”:

Figure 6.3. Searching the Repository for a Class This is a big time saving feature

Figure 6.3. 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.

6.3. 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 6.4, “Show Maven Indexes View”:

a view named Maven Indexes as shown in Figure 6.4, “Show Maven Indexes View”: Figure 6.4.

Figure 6.4. Show Maven Indexes View

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

View as shown in Figure 6.5, “Maven Indexes View”: Figure 6.5. Maven Indexes View Additionally, Figure

Figure 6.5. Maven Indexes View

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

Indexes View after manually navigating to locate a POM: Figure 6.6. Locating a POM from the

Figure 6.6. 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.

6.4. Browsing and Manipulating Maven Repositories

The m2eclipse plugin allows you to browse and manipulate repository indexes. Using the Maven Repository view in m2eclipse you can:

• Browse your Local Maven repository

• Browse global repositories such as the Central Maven repository

• Browse a repository which captures artifacts generated by Maven projects in your Eclipse workspace

• Rebuild a Nexus Index from scratch

• Update a Nexus Index with incremental changes

• Modify the scope of repository indexing with a "minimal" or "full" index

• Disable Indexing for a repository

• Materialize a Maven project from information stored in a POM

6.4.1. Opening the Maven Repository View

To browse Maven repositories and to manipulate repository indexes open the Maven Repositories view by selecting Windows, Show

View, Other

as shown in Figure 6.7, “Opening a View in Eclipse”.

as shown in Figure 6.7, “Opening a View in Eclipse”. Figure 6.7. Opening a View in

Figure 6.7. Opening a View in Eclipse

Once you select Other

Maven folder in the Show View dialog as shown in Figure 6.8, “Selecting the Maven Repositories View in the Show View Dialog”.

Eclipse will display a dialog containing all available views. Select the Maven Repositories view under the

views. Select the Maven Repositories view under the Figure 6.8. Selecting the Maven Repositories View in

Figure 6.8. Selecting the Maven Repositories View in the Show View Dialog

Once you have selected Maven Repositories and clicked on the OK button, Eclipse will then load the Maven Repositories view. This view contains three folders:

Local Repositories This folder contains your local Maven repository which is stored in ~/.m2/repository by default. It also contains a repository that represents the Maven projects contained in your Eclipse workspace.

Global Repositories This folder contains any global Maven repositories that are referenced by all Maven projects. This folder contains the Central Maven repository under the repository identifier of "central". It will also contain mirrors that have been configured in your

Maven Settings (~/.m2/settings.xml).

Project Repositories This folder contains repositories which are defined by your projects. These repositories are present either in your project's pom.xml file or in an active Maven Profile.

6.4.2. Browsing Global Repositories

If you have been using Maven, you are familiar with the Central Maven repository. This is default repository from which Maven will retrieve dependencies and other artifacts needed during a build. If you expand the central repository, you will be able to browse the contents of the repository and double click on specific artifacts. Double-clicking on one of the artifacts shown in Figure 6.9, “Browsing a Global Repository” will load that artifact's POM in the Form-based POM Editor.

load that artifact's POM in the Form-based POM Editor. Figure 6.9. Browsing a Global Repository In

Figure 6.9. Browsing a Global Repository

In addition to loading an artifact's POM in the Form-based POM Editor, you can also right click on a artifact and choose Materialize Project. If the POM for a particular artifact contains valid SCM information, m2eclipse can "materialize" the project from source control into your workspace.

6.4.3. Browsing Your Workspace Repository

m2eclipse maintains an index of artifacts generated by your Eclipse workspace. This "workspace" repository is shown in Figure 6.10, “Browsing the m2eclipse Workspace Repository” under the Local Repository folder. If you expand this folder, you will see artifacts that correspond to your workspace project as shown in Figure 6.10, “Browsing the m2eclipse Workspace Repository”.

Figure 6.10. Browsing the m2eclipse Workspace Repository 6.4.4. Browsing a Project Repository The Maven Repositories

Figure 6.10. Browsing the m2eclipse Workspace Repository

6.4.4. Browsing a Project Repository

The Maven Repositories view is also intelligent enough to keep track of any repositories that have been added to your project via your Maven Settings, an active Maven Profile, or that have been added directly to a project's POM. To demonstrate this feature, add a "

repository element to a pom.xml, by loading the Form-based POM Editor and clicking on the Repositories tab. Click on the "Create button and add a new repository with the following values as shown in Figure 6.11, “Adding a Repository to a Project's POM”.

• Repository Identifier: flexmojos

• Repository Name: Flexmojos Repository

• URL: http://repository.sonatype.org/content/groups/flexgroup/

Note

You will only see the Repositories tab in your Form-based POM Editor, if you have set your Maven preferences to

"Show advanced tabs in the POM Editor" under Eclipse, Preferences

,

Maven, POM Editor.

Figure 6.11. Adding a Repository to a Project's POM Save the POM and open the

Figure 6.11. Adding a Repository to a Project's POM

Save the POM and open the pom.xml tab in the POM Editor. The project's pom.xml should contain the repositories element shown in Figure 6.12, “Project POM with a Custom Repository”.

in Figure 6.12, “Project POM with a Custom Repository”. Figure 6.12. Project POM with a Custom

Figure 6.12. Project POM with a Custom Repository

Now that the pom.xml contains a custom repository, click on the refresh icon shown in the upper right-hand of Figure 6.13, “Browsing a Project Repository”. The refresh icon looks like two opposing yellow arrows, and clicking this icon will cause the Maven Repositories view to refresh the list of repositories from the selected project and your configured Maven settings.

Figure 6.13. Browsing a Project Repository Once you have added a project repository and clicked

Figure 6.13. Browsing a Project Repository

Once you have added a project repository and clicked on the refresh icon in the Maven Respositories view, you will be able to view the project-specific repository and manipulate the repository index for this project-specific repository.

6.4.5. Browsing Your Local Repository

The Maven Repostitories view allows you to browse and manipulate your local Maven repository index. m2eclipse maintains an index for the contents of your local repository, you can use this interface to browse artifacts that have been loaded into your local repository as shown in Figure 6.14, “Browsing Your Local Maven Repository”.

in Figure 6.14, “Browsing Your Local Maven Repository”. Figure 6.14. Browsing Your Local Maven Repository 6.4.6.

Figure 6.14. Browsing Your Local Maven Repository

6.4.6. Manipulating a Repository Index

Every repository that m2eclipse uses is indexed by the Nexus Indexer. If m2eclipse is using a remote repository, it will download a Nexus index from the remote repository. If m2eclipse is managing a local repository (local or workspace) it will use the open source Nexus indexer to create and maintain a local index. This index is what allows you to quickly search for and locate dependencies by artifactId, groupId, version, or classname. You can manipulate the index that is associated with a Maven repository by right-clicking on a repository in the Maven Repositories view and selecting one of the following actions:

Update Index This will update the index by running an incremental update or by downloading and index from a remote repository.

Rebiuld Index This will rebuild an index for a local repository by iterating through the contents of a repository and recreating a Nexus index from scratch. This can be a useful tool if there is another process outside of Eclipse that is going to be modifying a local Maven repository.

Disable Index Choosing this option causes m2eclipse to skip index generation for a repository. This can come in handy if you have a series of repositories which you do not want to include in artifact searches. If your organization maintains a number of specialized, segregated repositories that hold snapshots, you may not want to include these artifacts in simple searches for artifacts that contain a particular identifier or class.

for artifacts that contain a particular identifier or class. Figure 6.15. Updating a Repository Index Figure

Figure 6.15. Updating a Repository Index

Figure 6.15, “Updating a Repository Index” shows two indexing options that control the scope of a particular Nexus index:

Enable Min Index Configures the Nexus Indexer to maintain a minimal index that doesn't contain information about class names.

Enable Full Index Configures the Nexus Indexer to maintain a full Index that includes the class names contained within each artifact.

Chapter 7. Using m2eclipse

7.1.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 7.1, “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:

container was automatically updated to included it: Figure 7.1. Manually Adding a Dependency to the

Figure 7.1. 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 7.2, “Updating Maven Dependencies”:

as shown in Figure 7.2, “Updating Maven Dependencies”: Figure 7.2. Updating Maven Dependencies The second option

Figure 7.2. Updating Maven Dependencies

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

Figure 7.3. Searching for a Dependency By simply entering a groupId into the query field,

Figure 7.3. 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.

7.1.2. 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.

7.1.3. 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.

7.1.4. 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.

7.2. Analyzing Project Dependencies in m2eclipse

The latest release of m2eclipse contains a POM editor which provides some dependency analysis tools. These tools promise to change the way people maintain and monitor a project's transitive dependencies. One of the main attractions to Maven is the fact that it manages a project's dependencies. If you are writing an application which depends on the Spring Framework's Hibernate3 integration, all you need to do is depend on the spring-hibernate3 artifact from the Central Maven Repository. Maven then reads this artifact's POM and adds all of the necessary transitive dependencies. While this is a great feature that attracts people to using Maven in the first place, it can often become confusing with a project starts to depend on tens of dependencies, each with tens of transitive dependencies.

Problems start to happen when you depend on a project with a poorly crafted POM which fails to flag dependencies as optional, or when you start encountering conflicts between transitive dependencies. If one of your requirements is to exclude a dependency like commons-logging or the servlet-api, or if you need to find out why a certain dependency is showing up under a specific scope you will frequently need to invoke the dependency:tree and dependency:resolve goals from the command-line to track down the offending transitive dependencies.

This is where the POM editor in m2eclipse comes in handy. If you open a project with many dependencies, you can open the Dependency Tree tab and see a two-column display of dependencies as shown in Figure 7.4, “Dependency Tree Tab of the POM Editor”. The left-side of the panel displays a tree of dependencies. The first level of the tree consists of direct dependencies from your project, and each subsequent level lists the dependencies of each dependency. The left-hand side is a great way to figure out how a specific dependency made its way into your project's resolved dependencies. The right-hand side of this panel displays the resolved dependencies. This is the list of effective dependencies after all conflicts and scopes have been applied, and it is the effective list of dependencies that your project will use for compilation, testing, and packaging.

project will use for compilation, testing, and packaging. Figure 7.4. Dependency Tree Tab of the POM

Figure 7.4. Dependency Tree Tab of the POM Editor

The feature which makes the Dependency Tree tab so valuable is that it can be used as an investigative tool to figure out how a specific dependency made it into the list of resolved dependencies. Searching and filtering functionality available in the editor makes it really easy to search and browse trough the project dependencies. You can use “Search” entry field from the editor tool-bar and “Sort” and “Filter” actions from “Dependency Hierarchy” and “Resolved Dependencies” sections to navigate trough dependencies. Figure 7.5, “Locating Dependencies in the Dependency Tree” shows what happens when you click on commons-logging in the "Resolved Dependencies" list. When filtering is enabled in “Dependencies Hierarchy” section, clicking on a resolved dependency filters the hierarchy on the left-hand side of the panel to show all of the node which contributed to the resolved dependency. If you are trying to get rid of a resolved dependency, you can use this tool to find out what dependencies (and what transitive dependencies)

are contributing the artifact to your resolved dependencies. In other words, if you are trying to get rid of something like commons- logging from your dependency set, the Dependency Tree tab is the tool you will likely want to use.

Dependency Tree tab is the tool you will likely want to use. Figure 7.5. Locating Dependencies

Figure 7.5. Locating Dependencies in the Dependency Tree

m2eclipse also provides you with the ability to view your project's dependencies as a graph. Figure 7.6, “Viewing the Dependencies of a Project as a Graph” shows the dependencies of idiom-core. The top-most box is the idiom-core project and the other dependencies are shown below it. Direct dependencies are linked from the top box and the transitive dependencies are linked from those. You can select a specific node in the graph to highlight the linked dependencies, or you can use the Search field at the top of the page to find matching nodes.

Note that “open folder” icon on each graph node indicates that the corresponding artifact is present in the Eclipse workspace and “jar” icon indicates that the node's artifact is referenced from the Maven repository.

node's artifact is referenced from the Maven repository. Figure 7.6. Viewing the Dependencies of a Project

Figure 7.6. Viewing the Dependencies of a Project as a Graph

The graph presentation can be changed by right clicking in the editor. You can choose to show artifact ids, group ids, versions, scopes, or if you want to wrap node text or show icons. Figure 7.7, “Radial Layout of Dependency Graph” shows the same graph from Figure 7.6, “Viewing the Dependencies of a Project as a Graph” with a radial layout.

Figure 7.7. Radial Layout of Dependency Graph 49

Figure 7.7. Radial Layout of Dependency Graph

Chapter 8. Using m2eclipse

8.1. Working with Maven Projects

The m2eclipse plugin also provides a set of features for working with Maven projects once they are inside of Eclipse. There are many features that ease the ability to use Maven in Eclipse so let’s dive right into them. In the previous section, I materialized a Maven project and selected a subproject from the Apache Camel project named camel-core. We’ll use that project to demonstrate these features.

By right-clicking on the camel-core project, and selecting the Maven menu item, you can see the available Maven features. Figure 8.1, “Available Maven Features” shows a screenshot of this:

“Available Maven Features” shows a screenshot of this: Figure 8.1. Available Maven Features Notice in Figure

Figure 8.1. Available Maven Features

Notice in Figure 8.1, “Available Maven Features” the available Maven features for the camel-core project, including:

• Adding dependencies and plugins

• Updating dependencies, snapshots and source folders

• Creating a Maven module

• Downloading the source

• Opening Project URLs such as the Project Web Page, Issue Tracker, Source Control, and Continuous Integration tool.

• Enabling/Disabling workspace resolution, nested Maven modules and dependency management

These features are also big time savers so let’s review them briefly.

8.1.1.

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.

8.1.2. 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.

8.1.3. 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.

8.2. Using the Form-based POM Editor

The latest release of the m2eclipse plugin has a form-based POM editor which allows you to edit every part of a project's pom.xml

with an easy-to-use GUI interface. To open the POM Editor, click on a project's pom.xml file. If you've customized the editors for

a pom.xml file, and the POM Editor is not the default editor, you may need to right-click on the file and choose "Open With Maven POM Editor". The POM Editor will then display the Overview tab as shown in Figure 8.2, “Overview Tab of POM Editor for idiom-core”.

/

Note

The Form-based POM Editor is only available if you selected the POM Editor component when you installed the m2eclipse Eclipse plugin. For more information about installing the m2eclipse plugin, see Section 2.3.1, “Installing m2eclipse Core Components”.

One common complaint about Maven is that it forces a developer to confront large and often overwhelming XML documents in a

highly complex multi-module project build. While the authors of this book believe this is a small price to pay for the flexibility of

a tool like Maven, the graphical POM editor is a tool that makes it possible for people to use Maven without ever having to know about the XML structure behind a Maven POM.

Figure 8.2. Overview Tab of POM Editor for idiom-core The project shown in Figure 8.2,

Figure 8.2. Overview Tab of POM Editor for idiom-core

The project shown in Figure 8.2, “Overview Tab of POM Editor for idiom-core” is a project with an artifactId of of idiom- core. You'll notice that most of the fields in this idiom-core project are blank. There is no groupId or version and there is no SCM information supplied in the POM editor. This is due to the fact that idiom-core inherits most of this information from a parent project named idiom. If we open the pom.xml for the parent project in the POM Editor we would see the Overview tab shown in Figure 8.3, “Overview Tab of POM Editor for idiom Parent Project”.

That “open folder” icon on the various list entries throughout the POM editor indicate that the corresponding entry is present in the Eclipse workspace and “jar” icon indicates artifacts which are referenced from the Maven repository. You can double-click on those entries in order to open its POM in the POM editor. This works for modules, dependencies, plugins and other elements that have corresponding Maven artifacts. Underlined labels in several POM editor sections represent hyperlinks which can be used to open the POM editor for corresponding Maven artifact.

Figure 8.3. Overview Tab of POM Editor for idiom Parent Project In this parent POM,

Figure 8.3. Overview Tab of POM Editor for idiom Parent Project

In this parent POM, we see that the groupId and version are defined and that the parent POM supplies much of the information which was missing in the idiom-core project. The POM editor is going to show you the contents of the POM that you are editing,

and it will not show you any of the inherited values. If you wanted to look at the idiom-core project's effective POM in the POM editor, you can use “Show Effective POM” action from the tool-bar in the upper right-hand corner of the POM editor, which shows

a left bracket and an equals sign on a page with a blue M. It will load the effective POM for idiom-code in the POM Editor as shown in Figure 8.4, “Effective POM for idiom-core”.

as shown in Figure 8.4, “Effective POM for idiom-core”. Figure 8.4. Effective POM for idiom-core This

Figure 8.4. Effective POM for idiom-core

This effective view of the POM merges the idiom-core POM with the ancestor POMs (the parent, the grandparent, etc.), similarly to “mvn help:effective-pom” command and displays the POM editor with the effective values. Because the POM editor is display

a composite view of many different merged POMs, this effective POM Editor is read-only, and you will not be able to update any of the fields in this effective POM view.

If you were looking at the POM editor for the idiom-core project as shown in Figure 8.2, “Overview Tab of POM Editor for idiom- core”, you can also navigate to the parent POM using, ”Open Parent POM” action from the POM editor tool-bar in the upper right- hand of the POM editor.

The POM editor shows a number of showing various information from the POM. The final tab exposes the pom.xml as an XML document. There is a dependencies tab shown in Figure 8.5, “Dependencies Tab of the POM Editor” which exposes an easy-to-use interface for adding and editing dependencies to your project, as well as editing the dependencyManagement section of the POM. This dependency management screen is also integrated with the artifact searching facilities in the m2eclipse plugin. You can use actions from the editor sections, as well as Ctrl-Space typing assistance for the fields in “Dependency Details” section.

If you need to know more about one of the artifacts, you can use “Open Web Page” action from “Dependency Details” section tool- bar to check the project web page.

Details” section tool- bar to check the project web page. Figure 8.5. Dependencies Tab of the

Figure 8.5. Dependencies Tab of the POM Editor

The build tab shown in Figure 8.6, “Build Tab of the POM Editor” provides access to the contents of the build element. From this tab you can customize source directories, add extensions, change the default goal name, and add resources directories.

Figure 8.6. Build Tab of the POM Editor We only showed a small subset of

Figure 8.6. Build Tab of the POM Editor

We only showed a small subset of the POM editor. If you are interested in seeing the rest of the tabs, please download and install the m2eclipse plugin.

8.3. Summary

m2eclipse is more than just a simple plugin which adds Maven support to Eclipse, it is a comprehensive integration that will make everything from creating new projects to locating third-party dependencies orders of magnitude easier. m2eclipse is the first step toward an IDE that is aware of the rich semantic treasure that is the central Maven repository. As more people come to use m2eclipse, more projects are going to be releasing Maven Archetypes, and more projects are going to see value in publishing source artifacts to the Maven repository. If you've tried to use Eclipse and Maven together without a tool that can comprehend the hierarchical project relationships that are central to any multi-module Maven project, you will know that the ability to work with nested projects is essential to smooth integration between the Eclipse IDE and Maven.

Part II. Maven Studio for Eclipse

The second portion of this book deals with Maven Studio for Eclipse.

Chapter 9. Introduction to Maven Studio for Eclipse

9.1. Introduction

Maven Studio for Eclipse currently provides Developer Onboarding, a feature fully introduced and defined in Section 9.2, “Developer Onboarding”. For more information about Maven Studio for Eclipse, please contact info@sonatype.com 1 .

9.2. Developer Onboarding

Developer Onboarding can be defined as the process of bringing a developer "onboard" a particular development project. This process usually encompasses setting up the tools used during development - an Integrated Development Environments, compilers, and other tools used to design, write, test, debug, and deploy code. This section describes some of the challenges involved in Developer Onboarding, and provides some context for the Developer Onboarding feature now available in Maven Studio for Eclipse.

9.2.1. The Cost of New Developer Onboarding

On average, it typically takes a new developer five days before they can start contributing to a project. During this 5-day period, a developer will complete the tasks described below and illustrated in Figure 9.1, “A Representative 5-Day, Manual Onboarding”:

Day 1 Workstation Setup Setup a workstation, install baseline requirements such as a Java Development Kit and other languages or fundamental frameworks.

Day 2 Downloading Components Download all of the components required for a development environment, this often includes components like:

• Source Control tools (Subversion, Git, Clearcase, or CVS)

• Integrated Development Environments (Eclipse IDE)

• Automated Testing Tools (Selenium)

• Application Servers / Containers (Websphere, Jetty, Tomcat)

• Build Tools (Maven, Ant)

• Databases (Oracle, MySQL, SQL Server)

• Scripting Languages (Ruby, Python, Perl)

• General Utilities (cygwin, emacs, other utilities)

The best-case scenario is an organization which maintains a detailed list of software components required in a development environment. In most organizations this information isn't firmly fixed in time as different developers set up environments as they are introduced to a project. New programmers will often notice a slight variation in the versions of components used by other programmers in the same group. Example: a senior developer who has been on the team for years might still use Eclipse 3.4, while newer developers might just download the latest version of Eclipse 3.5.1.

Day 2 Self-directed Learning Developers not directly familiar with tools like Maven will need to learn how to install and configure these tools. Most new developers spend at least half a day familiarizing themselves with the installation and configuration process for new development infrastructure.

Day 3 Installing Software Once all of the required software has been downloaded, it must be installed and configured. Eclipse must be installed and configured, a local testing database must be configured, the IDE settings must be customized to account for specific standards used by the organization.

Day 3 Ad-hoc Training After setting up and environment, a developer will usually require the assistance of other members of the development team. Ad-hoc training sessions will involve other developers communicating standards and software: "Have you used JUnit before? This is how we run a unit test."

Day 4 Source Code It is just at Day 4 that a developer starts to think about accessing source code. More dicussions with members of the same group about source code are usually accompanied by an overview of the various source control systems and structure of the various groups. Checking out source code is as much about learning about the organizational structure of a code base as it is about learning how that code maps to project groups. Who is responsible for various components, how is the source checked out of source control, and how often is it updated.

Day 4 Build System Once the code is properly checked out and imported into your IDE, a developer will need to build an entire system. If the organization has already standardized on a tool like Apache Maven, this could be as simple as typing in "mvn clean install" at the command prompt. Most organizations require some level of customization for a build to work properly. Whether this means that a developer needs to fully understand a custom Ant build or just find out how to configure Maven settings to connect to a Nexus repository, there is usually some work involved in figuring out how the build works and how it should be configured properly.

Day 5 Configuring Development Environment Once a developer can build the code, the next step is to configure a local development environment. If a developer is working on an enterprise application, this may involve setting up a local instance of a database and populating that database with test data.

Day 5 Integrating 3rd Party Projects If an enterprise application depends on 3rd-party open source projects, a developer will often checkout relevant source code from open source projects and configure them alongside the development environment for internal code.

Technical Team Introduction HR Tour Workstation Setup Overview Meeting
Technical
Team
Introduction
HR
Tour
Workstation Setup
Overview
Meeting
Downloading Components Self-directed Learning
Downloading Components
Self-directed Learning

Day 1

Day 2

Day 3

Day 4

Day 5

Installing Software (Eclipse, Subversion) Ad-hoc Training
Installing Software (Eclipse, Subversion)
Ad-hoc Training
Checking Out Source Code Learning Build System / Customizing Settings
Checking Out Source Code
Learning Build System / Customizing Settings
Configuring Development Integrating 3rd Party Projects Productive Environment
Configuring Development
Integrating 3rd Party Projects
Productive
Environment

Figure 9.1. A Representative 5-Day, Manual Onboarding

9.2.2.

Onboarding with Maven Studio for Eclipse: Productive on Day One

With Maven Studio for Eclipse, a build engineer can capture all of the components required for a development environment in an MSE Codebase. This MSE Codebase is then published to Nexus Team edition and is downloaded by a developer in a process called "Materialization". When a developer materializes an MSE Codebase, a component called the MSE Installer downloads an XML descriptor which captures all of the configuration parameters for a completely customized build environment.

Figure 9.2, “Minimizing Onboarding Time with Maven Studio for Eclipse” shows the process from Figure 9.1, “A Representative 5-Day, Manual Onboarding” condensed into a single day. A developer's first day on the job is still characterized by introductions,

tours, and meetings, but instead of relegating a developer to a week of manual installation and configuration tasks, a developer simply clicks on a link to materialize an MSE Codebase. An MSE Codebase can be materialized in a few minutes, and once this process

is done, a new developer can be productive on Day One.

Technical Team MSE Introduction HR Tour Productive Overview Meeting Onboarding
Technical
Team
MSE
Introduction
HR
Tour
Productive
Overview
Meeting
Onboarding

Day 1

Figure 9.2. Minimizing Onboarding Time with Maven Studio for Eclipse

The ramifications of this easy setup process are more than just time saved and efficiencies gained. When it only takes a new developer

a few minutes to get his or her workstation setup, they can take more time in the first days to learn about projects and architecture.

They can start to engage a group socially, participating in development discussions and decisions instead of disappearing into a cave to install software.

This new ability to get prouctive quickly also changes the way in which developers are added to a project. When you know it will only take a few minutes to install a development environment, checkout all required source code, and configure a build, you won't have to build in a week of downtime into your schedule for new developers. If your project needs the help, you can hire a new developer to make focused changes without having to sacrifice five days of time to inefficient manual setup.

Maven Studio for Eclipse makes your organization more agile, more efficient. Increased efficiencies do more than save time and resources. They change the dynamics of the group and make it possible to focus more on your application's code and less on the tools required to build it.

9.2.3. Managing Developer Workspace Complexity

Developers spend most of their time connecting components within a development environment to one another. As open source software tools and components have created a wealth of choices, these tools have also increased the cognitive burden on software developers. Gone are the days when a developer could simply install Java, Eclipse, and Maven and just start to code. In today's software development environment, a developer needs to not only configure an IDE, she needs to connect that IDE to a collection of infrastructure resources like JIRA and Confluence, configure the system to interact with source control, and install any number of supporting components.

As most developers only configure a workstation once or twice a year, the true complexity is always somewhat surprising. Developers don't realize exactly how much time is wasted on workstation setup until they've wasted an entire day downloading and installing the various software components involved in an environment. This process is not unlike process most Java developer used to use to obtain dependencies for a Java project.

Before the arrival of Maven, a software developer had to manually download and configure a set of libraries, a set of dependencies. Maven Studio for Eclipse takes one of the central ideas of Maven, the idea that you can describe your project and let Maven take care of downloading components from a central repository, and it applies this concept to your development environment. Instead of asking your developers to download, configure, and connect an increasing number of components. Use Maven Studio, capture your development environment in a descriptive codebase, and let Maven Studio for Eclipse take care of the details.

= Maven + Studio Figure 9.3. Consolidating Complexity into Eclipse IDE 9.3. Managing Change in

=

= Maven + Studio Figure 9.3. Consolidating Complexity into Eclipse IDE 9.3. Managing Change in Development

Maven
+

Studio

Figure 9.3. Consolidating Complexity into Eclipse IDE

9.3. Managing Change in Development Environments

When you use Maven Studio for Eclipse Developer Onboarding, and you standard your entire development team's environment on managed Eclipse codebases, you start to decrease the amount of time, the amount of investment necessary to update and maintain your development environment. Once you've created a system that allows you to redeploy a new development environment over hundreds of workstations in a few hours, you've implemented low-risk, or "disposable" development environments. The cost to change your developer's environments is small enough that you can start making changes without having to worry about the logistics of such a change.

To illustrate the benefits of low-risk, or "disposable" development environments consider the ongoing invest of time and effort to keep a development environment up to date. The follow two examples illustrate the differences between using high-risk, high-investment development environments, and low-risk, "disposable" development environments.

9.3.1.

The Common Scenario: Upgrading Development Infrastructure

Consider a average sized workgroup of 20 developers and 5 project managers. This team of 20 developers is split up into 4 teams of five engineers, and each team works with a project manager to set direction and track progress. The product development lifecycle in this particular organization is twelve months. From initial product design to testing to implementation and lastly final delivery takes, on average about twelve months start to finish. Let's also assume that the entire team uses the same development environment, the same testing infrastructure, and a common approach to tools, releases, and source control.

At the start of a project development cycle, senior developers from each team usually meet to decide upon changes to the development tool stack. Questions like: What version of Eclipse are we standardizing on? What is the structure of our source code repository? What tools do we need to standardize on for testing? All of these questions are answered at the beginning of the project, and while developers and project managers are working on architecture issues and other plans, there is a build engineer or an architect who is tasked with documenting a standard set of tools and procedures for development.

This tools selection and standardization process usually takes two weeks to complete. While we are not dealing with new employees, very often when a new development stack is introduced, developers and managers need to recalibrate knowledge of tools, retrain themselves on the latest versions of build systems and IDEs, maybe the organization also uses this time period of refresh engineer's laptops. Getting a new laptop after two years of working can often introduce as much downtime in project schedules as hiring a new employee.

The point here is that technology management understands that there is some downtime at the start of a project to allow the senior technical talent to introduce newer approaches technologies into the mix. This is commonly accepted practice, and it makes sense to introduce risky changes at the beginning of a product lifecycle when there is enough time to mitigate any unexpected problems that might be introduced by such a change.

9.3.2. Disadvantages of a High-Risk Development Environment

Assume that it takes about two weeks to deliver change to the development environment. A new Eclipse-based plugin needs to be configured, tested, and delivered to every developer workstations, or source control locations needs to be refactored or split. This two weeks is not the time it takes for any one developer to implement a change. This two week period is the time it takes for build engineers to introduce the change, train developers, and then migrate individual developer workstations over to a new development environment. In this scenario, developers manually build workstations from a set of instructions, and each developer also has the potential to install different versions on a workstation. The two week period is the length of time it takes for most developers to convert and for every developer to work out any issues which may arise during an environment upgrade.

Figure 9.4, “High-risk Development Environments Discourage Change within Constrained Development Cycles” illustrates the end- result of having such a high-risk approach to development environments. Because the process of deploying change to a development environment take two weeks to fully implement, technical managers are going to be very careful about introducing any change into the environment in the middle of an active product development cycle. If a new version of Eclipse is introduced which improves performance, or if a new version of Maven is made available that enables greater flexibility, managers are not likely to approve any changes.

The following, fictional dialog captures the reality of a development group with a manual, high-risk strategy for testing and deploying changes to development infrastructure:

Build Engineer: "They just released a new version of Maven to address some of the issues we are having with the Surefire plugin."

Manager: "How long is it going to take to test and deploy this fix to 100 developers?"

Build Engineer: "One week of testing and about a week to deploy the changes to every team. We have to wait for people to have enough time available to follow our instructions."

Manager: "If it isn't critical, I'd rather wait until we've completed this cycle to implement this change. It doesn't seem worth it given the risk that our timelines will be affected."

Start Development Cycle (12 months) High-risk Changes to Dev Environment (2 weeks)
Start
Development Cycle
(12 months)
High-risk Changes to
Dev Environment
(2 weeks)

Figure 9.4. High-risk Development Environments Discourage Change within Constrained Development Cycles

If you work in one of these environments you'll recognize this situation. Managers are understandably risk-averse because they know that there is no automatic method for deploying changes to development environments. Developers are also risk averse because every time the build engineers come up with a new idea they lose a substantial amount of time following a loosely documented, ad-hoc process for running manual updates. In this scenario, the build engineer is often identified as the enemy of project stability and the team resists changes to the development environment.

9.3.3. Advantages of a Low-risk Development Environment

When an organization has standardized on low-risk, disposable development environments using Maven Studio for Eclipse, it takes little or no time to redeploy changes across all developer workstations. If the department needs to upgrade from Eclipse 3.5.1 to Eclipse 3.6.0 or upgrade to a newer version of the m2eclipse plugin, this change can be executed in a matter of hours. A build engineer can test a change to a development environment, publish a codebase to Nexus Team Edition and then send an email to hundreds of developers instructing them to materialize the latest codebase. In minutes, every engineer in the group can materialize the same development environment. Most importantly, if the newly published MSE Codebase has a problem or an issue, developers can rull back to a previous version of the published Codebase and continue developing.

This ability to quickly deploy a development environment doesn't just save time, it alters the dynamic between the build engineer and the project planners. If the build engineer proposes a change to the development environment which involves an upgrade to Eclipse or Maven, the build engineer can make the case that this change is low-risk. It can be implemented in a single day and deployed in minutes to every developer. If the proposed change introduces errors, developers can rollback.

Figure 9.5, “Low-risk Development Environments Enable Greater Flexibility within Constrained Development Cycles” illustrates the new dynamic introduced by low-risk changes to development environment. With Maven Studio for Eclipse, it doesn't take two weeks to convince your developers to upgrade to a new development environment, and project managers can no longer object to a simple, repeatable process with a guaranteed fallback plan.

Start (12 months) Low-risk Changes to Dev Environment (1 day)
Start
(12 months)
Low-risk Changes to
Dev Environment
(1 day)

Development Cycle

Figure 9.5. Low-risk Development Environments Enable Greater Flexibility within Constrained Development Cycles

Figure 9.5, “Low-risk Development Environments Enable Greater Flexibility within Constrained Development Cycles” shows a 12-month product development lifecycle with a series of low-risk changes to the development environment. Instead of waiting to schedule high-risk project downtime for infrastructure changes, you can upgrade your development infrastructure whenever you need to. Development doesn't have to come to a complete halt when it only takes a few minutes to materialize a codebase. If a new version of Eclipse or a critical tool from a vendor is updated, you will be able to quickly test and deploy this fix across your department wthout having to make the case to management to set aside time for the upgrade.

Maven Studio for Eclipse enables much greater flexibility within constrained development cycles because it makes development environment "disposable". You don't have to invest everyone's time in the installation and upgrade of development infrastructure; do in once, test it, publish, and everyone will have a standard environment immediately.

9.4. Consolidating Project Feeds

Developing good software is a very social activity. For people not directly involved in a development effort, this is not immediately obvious. If you don't spend your time programming, you might just think developers are doing nothing more than staring at Eclipse twelve hours a day and communicating with each other using terse, cryptic Subversion commit messages. In reality, good developers are constantly interacting on IRC, using Issue Trackers such as JIRA, having heated debates on mailing lists, and using other means of communication. If your development group involves open source, developers working on open source are communicating to large groups of volunteers over public channels such as Twitter and GitHub.

Maven Studio for Eclipse provides a mechanism for aggregating feeds for a Source Tree. You can use this mechanism as an opportunity to make sure that developers working on a particular system are following the right feeds. Think of feed support in the MSE product like having a project specific feedreader that you can configure, distribute, and update. In this industry, information is of primary importance and making sure that your developers are keeping up to date on the ever increasing number of technologies they need to know is important. With Maven Studio for Eclipse, you gain the ability to make sure that developers are paying attention to the right pieces of information.

9.4.1.

Simple Scenario: Aggregating a Project's Feeds

If your team is tracking project progress using Atlassian's JIRA issue tracker, collaborating on documentation using Atlassian's

Confluence wiki, changing source code stored in Subversion, monitoring production systems using Nagios, tracking builds using Hudson, and dscussing strategy using services like Twitter, all of these channels create a constant stream of events and which help developers track activity.

Figure 9.6, “Aggregating a Single Project's Feeds” illustrates how Maven Studio for Eclipse Source Trees can be used to aggregate

this information into a simple project activity feed presented in the Eclipse IDE. Without Maven Studio for Eclipse, this aggregated feed is something a developer has to fetch himself. When a new piece of development infrastructure such as JIRA or Subversion

is added to a project, a developer has to figure out how to integrate any available activity streams into his personal feed reader.

Usually this means that every bit of development infrastructure involved in the development effort is configured to push automated emails to developer.

While this strategy of constantly flooding each developer with activity emails accomplishes the job, it also ignores the fact that every piece of development infrastructure provides support for common feed standards such as RSS and Atom. Maven Studio for Eclipse integrates with these feed standards and it gives build engineers a standard mechanism to make sure that every developer is paying attention to the same set of valuable feeds. If you've installed a new source control system, or a new tool like Sonar which generates a useful RSS feed, just update the codebase, publish it to Nexus Team Edition, and tell your developers to materialize the latest version

of a codebase. In minutes, you can make sure that everyone is paying attention to the same activity stream within Eclipse.

Project Activity Issue Continuous Tracker Twitter: @Brian_Fox: The new Integration (JIRA) (Hudson) production
Project Activity
Issue
Continuous
Tracker
Twitter: @Brian_Fox: The new
Integration
(JIRA)
(Hudson)
production build is now available
from Central Staging
Source
Hudson Build #423 Success:
Control
Triggered by SVN Commit 423242.
(Subversion)
MSE Codebase
400 out of 400 tests passes.
Source Tree
Production
SVN: Commit 423242 by jvanzyl:
Monitoring
Updated the storage implementation
(Nagios)
to account for NoSQL
Social
Nagios: Warning on app01: Disk
Wiki
Media
utilization currently at 97%. Address
(Confluence)
(Twitter)
problem immediately.

Figure 9.6. Aggregating a Single Project's Feeds

9.4.2. Complex Scenarios: Mixed Open/Commercial Development

A increasingly common scenario in enteprise development is the hybrid open source/commercial development effort. Companies

large and small are starting to build systems to expose an open source core or API to the public which relates to a commercial

product or commercial extension. Sonatype's Nexus repository manager is just such a project. Nexus Open Source has a large, vibrant development community that includes many developers not directly employed by Sonatype. Nexus Professional has a smaller team

of programmers who are all directly employed by Sonatype.

Another common scenario is a company which develops a complex enterprise system which relies heavily on customized open source components. Companies like Google develop large, proprietary codebases for cloud computing while making massive, continued contributions to the open source projects it depends on. In these scenarios, you may configure an MSE Codebase with two source trees, one proprietary source tree pointing to your own, private source code repository, and another source tree pointing to a public, open-source repository.

In the scenario of a mixed, open/commercial development effort, you can configure the Open Source source tree to track public components: public issue trackers, twitter accounts of the main contributors, public mailling lists, and you can configure the Commercial source tree to track private activity logs from internal issue trackers and source code control systems. Developers will then see a unified view of project activity. They can keep up with the critical, open-source projects that the system depends on and they can keep track of internal activity.

Issue Continuous Tracker Integration Project Activity (JIRA) (Hudson) Twitter: @Brian_Fox: The new production
Issue
Continuous
Tracker
Integration
Project Activity
(JIRA)
(Hudson)
Twitter: @Brian_Fox: The new
production build is now available
from Central Staging
Source
Control
(Subversion)
Hudson Build #423 Success:
Open Source
Triggered by SVN Commit 423242.
400 out of 400 tests passes.
Source Tree
Production
Monitoring
SVN: Commit 423242 by jvanzyl:
(Nagios)
Updated the storage implementation
to account for NoSQL
Social
Nagios: Warning on app01: Disk
Wiki
Media
(Confluence)
utilization currently at 97%.
(Twitter)
Address problem immediately.
Twitter: @SonatypeNexus: RSO is
Issue
Continuous
running Nexus Team Edition. See
Tracker
Integration
announcement: http://bit.ly/arznMT
(JIRA)
(Hudson)
SVN: Commit 233 by juven: Fixed
bugs reported by Windows 64-bit
Source
users. Increased coverage.
Control
(Subversion)
Commercial
Nagios: Warning on app01: Disk
Source Tree
utilization currently at 97%.
Address problem immediately.
Production
Monitoring
(Nagios)
Twitter: @SonatypeNexus: RSO is
running Nexus Team Edition. See
announcement: http://bit.ly/arznMT
Social
Wiki
Media
(Confluence)
(Twitter)

Figure 9.7. Aggregating Multiple Project's Feeds

Chapter 10. Maven Studio for Eclipse Quickstart

10.1. Introduction

Maven Studio for Eclipse (MSE) gives you the ability to capture common configuration and projects for your developers with the Developer Onboarding feature. Using the Developer Onboarding feature, you can very quickly configure and deliver a common configuration across your entire enterprise.

Newly hired developers or developers just starting on a new project usually take days to setup and configure all of the moving parts that go into an efficient development environment. With Developer Onboarding, a build engineer can capture all of the requirements

in an MSE Codebase and publish this Lineup to a simple, single-click solution which will download, install, and configure an Eclipse

IDE with all of the components necessary to be productive in minutes.

10.1.1. What is a Codebase?

A Codebase describes an entire development environment including both the configuration of Eclipse and the projects that are to be

checked out from source control. The Codebase contains two parts: A Lineup and one or more Source Trees as shown in Figure 10.1, “Maven Studio for Eclipse Codebase Contents”.

MSE Codebase Eclipse Preferences Codebase Description/Icon (one or more) Source Tree SCM Information Project
MSE Codebase
Eclipse Preferences
Codebase Description/Icon
(one or more)
Source Tree
SCM Information
Project Information
Source Roots
MSE Lineup
Eclipse Distribution
Eclipse Plugins/
Components

Figure 10.1. Maven Studio for Eclipse Codebase Contents

10.1.2. What is a Lineup?

A Lineup describes an Eclipse environment: the version of Eclipse installed, the versions of individual components of the Eclipse

framework, and an inventory of all option or 3rd party plugins installed in a given environment. When you use MSE to simplify your environment, you publish a Lineup to Nexus Team Edition.

10.1.3.

What is a Source Tree?

A Codebase includes one or more Source Trees. A Source Tree is a location in a Source Control Management system like Git or

Subversion. For example, if your lineup needs to checkout projects from two internal corporate Subversion servers, your Lineup would include two Source Trees pointing to two Subversion locations. A Source Tree can contain one or more Roots.

10.1.4. What is a Source Tree Root?

A Root is a location within a SCM repository which is imported into an Eclipse installation as a Maven project. If a Source Tree

does not define a list of Roots, it has an implicit root of “/”, this is the directory in which Maven Studio for Eclipse will look for a Maven POM to import. If you want to control the directories from which a project will be imported from a Source Tree, you would define one or more Source Tree Roots.

For example, if you configured a Source Tree to point to the Subversion URL http://yourserver.com/svn/trunk, and you configured

a Root at project-a/ and a Root at project-b/, MSE will checkout the source from these two directories and import these directories

as Maven projects. Every defined Root must contain a Maven pom.xml file for a successful import.

10.1.5. Use Case for a Build Engineer

A Build Engineer uses Maven Studio for Eclipse to create a Codebase and publish this Codebase to a repository on Nexus Team

Edition. Once this Codebase has been published, the Build Engineer can then send a an e-mail to team members directing them to

a one-click installation.

Nexus Team Maven Studio MSE for Eclipse Codebase P2 Proxy
Nexus Team
Maven Studio
MSE
for Eclipse
Codebase
P2 Proxy

Figure 10.2. Maven Studio for Eclipse Interacting with Nexus Team Edition

10.2. Getting Started with Maven Studio for Eclipse

In this quickstart guide, you will:

1. Configure Nexus Team Server

2. Materialize the Sample Demo Maven Lineup

3. Create a Custom MSE Codebase

4. Configure a Custom MSE Lineup

5. Configure an MSE Source Tree

6. Publish an MSE Codebase to Nexus Team Server

7. Materialize a Custom MSE Codebase

10.2.1.

Nexus Team Edition Prerequisites

Before starting the installation, make sure that you have satisfied the following preconditions for the server running Nexus Team Edition:

• Nexus Team Edition must be installed on a server that does not have Nexus Open Source or Nexus Professional installed on it.

• You are running a Java 6 Java Development Kit downloaded from Oracle on the server that will run Nexus Team Edition.

• You will need administrative privileges on the server running Nexus Team Edition.

10.2.2. Workstation Prerequisites

Before starting the installation, make sure that you have satisfied the following preconditions for the workstations which will be running Maven Studio for Eclipse and materializing Eclipse installations from Nexus Team Edition:

• You have installed a Java Development Kit version 1.6.0_18 or higher from Oracle. Maven Studio for Eclipse requires a JDK version of 1.6.0_18.

• If you are installing Maven Studio for Eclipse into an existing Eclipse installation, you must remove any previously installed version of the m2eclipse plugin.

10.3. Installing Nexus Team Edition

The first step for setting up your environment for Maven Studio for Eclipse is to install Nexus Team Edition.

10.3.1. Download Nexus Team Edition

If you are reading this quickstart guide, you should have received an e-mail from Sonatype containing instructions for downloading Nexus Team Edition.

Download the nexus-team-webapp-1.6.1.1-bundle.tar.gz or nexus-webapp-1.6.1.1-bundle.zip archive to the server which is going to host Nexus.

10.3.2. Unpack Nexus Team Edition

After downloading the Nexus Team Edition archive, unpack the archive:

• On a Linux machine, you might install Nexus Team Edition in /usr/local/nexus-team-1.6.1.1 or /opt/nexus-team-1.6.1.1.

• On a Windows machine, you might choose to install Nexus Team Edition in c:\Program Files\Nexus Team.

10.3.3. Start Nexus Team Edition

To start Nexus Team Edition locate the appropriate platform directory under ${NEXUS_HOME}/bin/jsw

• On Windows, run nexus.bat to start Nexus.

• On OSX or Linux, run nexus start to start Nexus, and nexus stop to stop Nexus.

Note

On Windows, you may be prompted to allow the service to modify the Windows Firewall.

10.3.4. Login as a Nexus Administrator

Go to http://localhost:8081/nexus, and login with the default administrator credentials: Username: admin, Password: admin123

Figure 10.3. Login to Nexus Team Edition 10.4. Configure Nexus Team Server Once you have

Figure 10.3. Login to Nexus Team Edition

10.4. Configure Nexus Team Server

Once you have installed the Nexus Team Edition, you must configure a few Nexus Server settings which will affect the publishing of P2 Lineups.

10.4.1. Open the Nexus Server Configuration Panel

To configure your Nexus Server, open up the Server configuration panel by selecting Administration # Server from the Nexus menu.

by selecting Administration # Server from the Nexus menu. Figure 10.4. Opening the Server Configuration Panel

Figure 10.4. Opening the Server Configuration Panel

10.4.2. Configure Proxy Settings

If your Nexus Server needs to use an HTTP Proxy, you must configure the proxy settings in the Nexus Server configuration.

the proxy settings in the Nexus Server configuration. Figure 10.5. Opening the Server Configuration Panel 10.4.3.

Figure 10.5. Opening the Server Configuration Panel

10.4.3. Save the Nexus Server Configuration

Click on Server Configuration panel’s Save button to save your Nexus server configuration.

10.4.4. Add a New P2 Proxy Repository

Next, add a new P2 Proxy Repository for the Eclipse Checkstyle (eclipse-cs) plugin. Later on in this guide, you will be creating

a custom Lineup which includes the Eclipse Checkstyle plugin. Go to Views/Repositories -> Repositories, and click on the Add button. Select Proxy Repository.

Repositories, and click on the Add button. Select Proxy Repository. Figure 10.6. Adding a New P2

Figure 10.6. Adding a New P2 Proxy Repository

10.4.5.

Configure the New Proxy Repository

Once you’ve created the New Proxy repository, configure the following parameters for the new repository:

configure the following parameters for the new repository: Figure 10.7. Configuring New Proxy Repository for Checkstyle

Figure 10.7. Configuring New Proxy Repository for Checkstyle Plugin

10.5. Run the Publish Lineups Scheduled Task in Nexus Team Server

After configuring your Nexus Team server, you must create a Scheduled Task to Publish a P2 Repository Lineup.

10.5.1. Execute a Scheduled Task for P2 Lineups

To execute a scheduled task, click on Administration # Scheduled Tasks in the Nexus Menu. Locate the “Publish P2 Lineup” Job in the list of configured tasks. Right-click on this task, and select Run.

configured tasks. Right-click on this task, and select Run. Figure 10.8. Opening the Scheduled Tasks Configuration

Figure 10.8. Opening the Scheduled Tasks Configuration Panel

Click Yes in the confirmation dialog to execute the Scheduled Task.

10.5.2. Verify P2 Lineups are Published

After running the job, click on the Refresh button in the Scheduled Tasks panel as shown in the following figure.

the Scheduled Tasks panel as shown in the following figure. Figure 10.9. Running the P2 Lineup

Figure 10.9. Running the P2 Lineup Publishing Task

While the job is running, the Status is RUNNING. This job will run for approximately 1-3 minutes. While the job is running, press the Refresh button to refresh the status of the running job. Once the Job is completed, the status will change to SUBMITTED as shown in the following figure.

Figure 10.10. Verify the Completion of the P2 Lineup Publishing Task 10.6. Materialize a Sample

Figure 10.10. Verify the Completion of the P2 Lineup Publishing Task

10.6. Materialize a Sample Workspace

Once you’ve configured Nexus Team server and published the demo P2 lineups, you are ready to materialize one of the demo workspaces. In this quickstart guide, you are going to materialize the sample Maven workspace. Once this workspace is materialized, you can then use Maven Studio for Eclipse to create your own custom P2 lineups.

10.6.1. Open the Repositories Panel

To open the Repositories Panel, click on Views/Repositories -> Repositories. Once the Repositories panel is open, you should see a list of all of the User Managed Repositories.

10.6.2. Select Nexus Managed Repositories

The MSE Codebase Repository is a Nexus Managed Repository. To view all Nexus Managed Repositories, select Nexus Managed Repositories from the repository type drop down.

Managed Repositories from the repository type drop down. Figure 10.11. Viewing Nexus Managed Repositories 10.6.3.

Figure 10.11. Viewing Nexus Managed Repositories

10.6.3. Select Sonatype MSE Repository

In the list of Nexus Managed Repositories, select the MSE Codebase Repository. This repository contains the sample Apache Maven lineup.

This repository contains the sample Apache Maven lineup. Figure 10.12. Selecting the Onboarding Repositories 10.6.4.

Figure 10.12. Selecting the Onboarding Repositories

10.6.4. Click on the MSE Installer for the Maven Lineup

Maven Studio for Eclipse ships with a demonstration project: the Apache Maven project. The first thing you will want to do is materialize one of these lineups to get a fully functioning installation of Maven Studio for Eclipse.

Once you select the Onboarding Project Repository, go to the Browse Storage tab and navigate to the org/sonatype/mse/codebases/ demo-maven/0.0.1 folder. Right-click on the mse-codebase.jnlp file and choose Download.

Figure 10.13. Downloading the Demo Maven Installer 10.6.5. Run the MSE Installer When you download

Figure 10.13. Downloading the Demo Maven Installer

10.6.5. Run the MSE Installer

When you download the mse-codebase.jnlp file, Java Web Start will download, verify, and start the MSE Installer. If this is the first time you are running the MSE Installer, you will be asked to verify that the MSE Installer is trusted.

will be asked to verify that the MSE Installer is trusted. Figure 10.14. Running the MSE

Figure 10.14. Running the MSE Installer

10.6.6. Supply Server and Source Control Credentials

You will then be asked to supply credentials for any source code repository or server involved in the installation process. Check the Anonymous access checkbox to the right of the Username field and click on the Next button.

right of the Username field and click on the Next button. Figure 10.15. Supply Subversion and

Figure 10.15. Supply Subversion and Source Control Credentials

Once you click next, the M2E installer will validate that is can connect to the source code repository and Nexus. Click Next on the following dialog:

Figure 10.16. Successful Validation of MSE Installer Requirements 10.6.7. Specify Installation Directories Next, the MSE

Figure 10.16. Successful Validation of MSE Installer Requirements

10.6.7. Specify Installation Directories

Next, the MSE installer will ask you to supply two directories: The Installation Directory, where the MSE Installer installs Eclipse, and the Workspace Location, where MSE Installer puts projects and code. You can Supply custom directories or accept the default values supplied by the MSE installer.

or accept the default values supplied by the MSE installer. Figure 10.17. Supplying Installation Directories for

Figure 10.17. Supplying Installation Directories for MSE Installer

10.6.8. Verify Completed Eclipse Installation

Clicking on Finish will start the process of installing the Eclipse IDE with all of the plugins specified in the MSE Lineup. Once the installation is completed, you should see an Eclipse IDE installation.

Note

Windows may prompt you to authorize the Eclipse IDE the first time it has been launched. You may see a firewall dialog asking for permission to execute Eclipse. You should approve this request.

Once the Eclipse IDE is visible, give the tool a few minutes to update indexes and to checkout project source code from source control. Once this process is finished, you should see a list of projects in the Apache Maven project. Once the Eclipse workspace has been materialized, you can start to work with the projects it checked out.

Figure 10.18. Maven Projects Displayed in Eclipse 10.6.9. Configure Password Recovery On some platforms, Eclipse

Figure 10.18. Maven Projects Displayed in Eclipse

10.6.9. Configure Password Recovery

On some platforms, Eclipse will then prompt you to set up the Master Password and Password Recovery options in Eclipse. Click Yes in the Secure Storage dialog.

options in Eclipse. Click Yes in the Secure Storage dialog. Figure 10.19. Creating a Master Password

Figure 10.19. Creating a Master Password for Eclipse Password Recovery

In the Password Recovery dialog type in two questions that will allow you to recover the master password for this Eclipse workspace. Once you’ve typed in these questions and answer, click OK.

Figure 10.20. Configuring Password Recovery 10.7. Creating a New MSE Lineup Maven Studio for Eclipse

Figure 10.20. Configuring Password Recovery

10.7. Creating a New MSE Lineup

Maven Studio for Eclipse gives you the tools you need to define a custom Eclipse installation which can be materialized with a simple click of a button. If you’ve followed the instructions in this document, you’ve already used that capability to materialize the demonstration instance of Maven Studio for Eclipse which contains the Maven project.

Next, you are going to use the custom lineup capabilities of Maven Studio for Eclipse to define a custom lineup which will checkout source code from a Subversion repository.

10.7.1. Create a New MSE Lineup Project

To create a new MSE Lineup, click on File -> New --> Other

in Eclipse as shown in the figure below.

New --> Other in Eclipse as shown in the figure below. Figure 10.21. Creating a New

Figure 10.21. Creating a New Lineup Project (Select New -> Other)

10.7.2.

Select the New P2 Lineup Wizard

Next, select New P2 Lineup from the Maven Studio for Eclipse folder in the wizard selection dialog.

Studio for Eclipse folder in the wizard selection dialog. Figure 10.22. Creating a New Lineup Project

Figure 10.22. Creating a New Lineup Project (Select New P2 Lineup Wizard)

10.7.3. Configure Nexus and Lineup Coordinates

Clicking Next will display a dialog that contains the Nexus Server URL, the Nexus credentials used to connect to Nexus, and the Lineup Coordinates.

Enter your administrative credentials for Eclipse in this dialog and supply Lineup Coordinates for your MSE Lineup. Change the Group Id to “com.sample” or choose a group identifier that makes sense for your organization. Click on Next.

that makes sense for your organization. Click on Next. Figure 10.23. Supply Lineup Coordinates and Nexus

Figure 10.23. Supply Lineup Coordinates and Nexus Credentials

Note

Every artifact in Nexus has a coordinate which consists of a Group ID, Artifact ID, and Version. The Group ID groups projects together and is often unique to an organization or a project. The Artifact ID is a unique identifier for a project (or in this case a Lineup).

10.7.4.

Select Runtime Platform and Memory

Select the platforms that are appropriate for your platform, Specify the heap size for your Eclipse installation in megabytes, and check the “Load Installable Units from Current Eclipse Installation” checkbox.

Units from Current Eclipse Installation” checkbox. Figure 10.24. Select Runtime Platform and Memory Note If you

Figure 10.24. Select Runtime Platform and Memory

Note

If you select “Load Installable Units from Current Eclipse Installation”, Maven Studio for Eclipse will use the current Eclipse installation as a template for your new P2 Lineup.

10.7.5. Configure the Contents of the Lineup

The next step in the P2 Lineup wizard is the Lineup Editor. This interface is where you configure the contents of the P2 Lineup. You can configure which Eclipse components and plugins are installed in a materialized Eclipse installation.

are installed in a materialized Eclipse installation. Figure 10.25. Configuring Contents of a P2 Lineup The

Figure 10.25. Configuring Contents of a P2 Lineup

The first list of “Installable Units” are the plugins and components that are installed in your Eclipse installation. The default components are Maven Studio Materialization Support and Sonatype Studio Base IDE Lineup. These two components are required for all Maven Studio for Eclipse installations. Note that the version number for Maven Studio Materialization Support is 0.0.0. This special “0.0.0” version number tells Eclipse to install the latest version currently available.

If you selected “Load Installable Units from Current Eclipse Installation” in the previous step, this list should contain Eclipse plugins, components, and update sites configured in your current Eclipse installation.

10.7.6.

Add a New Repository

Click on the Add

button in the Lineup Editor.

New Repository Click on the Add button in the Lineup Editor. Figure 10.26. Adding the Checkstyle

Figure 10.26. Adding the Checkstyle Repository to the Lineup Editor

Name the new repository “Eclipse-Checkstyle Integration” and use a Location of: http://eclipse-cs.sf.net/update/

10.7.7. Add the Checkstyle Plugin Installable Unit

After adding the repository, click on OK. Then in the Lineup Editor add a new Installable Unit by clicking on Add

list of Installable Units. Enter “http://eclipse-cs.sf.net/update” into the Work with: field, press Enter, and then select the most recent version of the Checkstyle plugin.

next to the

most recent version of the Checkstyle plugin. next to the Figure 10.27. Adding the Checkstyle Installable

Figure 10.27. Adding the Checkstyle Installable Unit to the Lineup Editor

10.7.8. Verify the P2 Lineup

Once you have added the Checkstyle repository and the Checkstyle plugin as an installable unit, click on the Next button. When you click on Next, Maven Studio for Eclipse will verify that it has access to the appropriate proxy repositories on Nexus Team server.

it has access to the appropriate proxy repositories on Nexus Team server. Figure 10.28. Verifying the

Figure 10.28. Verifying the Lineup Summary

Clicking Finish will create the P2 Lineup in your workspace under the Artifact ID of your new lineup.

in your workspace under the Artifact ID of your new lineup. Figure 10.29. Viewing Your New

Figure 10.29. Viewing Your New Codebase in the Eclipse IDE

10.8. Configuring a New Codebase

Once you’ve created and configured your P2 Lineup, you will need to configure a Source Tree for your Codebase. When you configure a P2 Lineup, you are telling Maven Studio for Eclipse what Eclipse components and plugins to install when it materializes an Eclipse installation from your Nexus Team server. Once Maven Studio for Eclipse materializes an Eclipse installation it will also checkout Maven projects from source control.

In this section, you are going to configure your newly created Codebase to checkout source code from an open source Subversion repository. In a corporate environment, instead of configuring your Codebase to pull projects from an Open Source project, you would be configuring your Codebase to pull projects from your own source control system.

If the baseline Codebase Overview is not already loaded, click on mse-codebase.xml in the misc folder under the baselineup project in your Eclipse workspace.

10.8.1. Maximize the Codebase Overview

If you just completed the previous section and defined a P2 Lineup, you should see the Codebase Overview in your Eclipse environment.

Maximize the Codebase Overview by clicking on the maximize button as shown below.

Overview by clicking on the maximize button as shown below. Figure 10.30. Maximizing the Codebase Overview

Figure 10.30. Maximizing the Codebase Overview

Once you have maximized the Codebase Overview, you will see the following form.

Figure 10.31. Codebase Overview 10.8.2. Create a New Source Tree A Source Tree is a

Figure 10.31. Codebase Overview

10.8.2. Create a New Source Tree

A Source Tree is a collection of projects checked out from source control.

is a collection of projects checked out from source control. Figure 10.32. Creating a New Source

Figure 10.32. Creating a New Source Tree

Click on Create

under Source Trees and name your new Source Tree “Apache Commons”. Then click on OK.

10.8.3. Configure the New Source Tree

Once you create a new Source Tree, the Codebase Overview will switch to a form that allows you to configure a new Source Tree. This dialog will show information about the source tree, the SCM location, Roots in the Source Tree, and information about the project.

10.8.4. Configure the SCM Location

Click on the drop down next to SCM Location and select “svn” as the Source Control protocol. Then type the following URL into the SVN location: http://svn.apache.org/repos/asf/commons/proper/lang/trunk

Figure 10.33. Configuring the Commons Source Tree Click on Validate Access. Maven Studio for Eclipse

Figure 10.33. Configuring the Commons Source Tree

Click on Validate Access. Maven Studio for Eclipse will then attempt to access the source code repository to validate that you have access to this URL.

10.8.5. Add a Feed URL

Click on Create

commons-user/?format=atom

under Feeds and add in the following URL for this mailing list feed: http://mail-archive.apache.org/mod_mbox/

Click on OK.

feed: http://mail-archive.apache.org/mod_mbox/ Click on OK. Figure 10.34. Configuring the Commons Feed URL 10.9.

Figure 10.34. Configuring the Commons Feed URL

10.9. Publishing a Codebase

Once your P2 Lineup has been configured with a Source Tree, you can publish this Lineup to your Nexus Team server.

If it isn’t already open, open the P2 Lineup overview, click on mse-codebase.xml under the baseline project in your Eclipse workspace.

10.9.1. Publish Your Codebase to Nexus

In the upper right-hand corner of the P2 Lineup Overview form you should see a Publish button next to a server icon.

Overview form you should see a Publish button next to a server icon. Figure 10.35. Publish

Figure 10.35. Publish Button on Codebase Overview

Clicking on this Publish button will tell Maven Studio for Eclipse to publish the newly configured P2 Lineup to your Nexus Team server.

If your Codebase has unsaved changed, Eclipse will ask you if you want to Save your current changes. Click Yes.

10.9.2. Supply Nexus Team URL and Credentials

Clicking the Publish button will display the Publish Codebase Descriptor dialog. In this dialog you will supply the Base URL of your Nexus Team server, a Nexus username, and a Nexus password.

Nexus Team server, a Nexus username, and a Nexus password. Figure 10.36. Publish Codebase Descriptor 10.9.3.

Figure 10.36. Publish Codebase Descriptor

10.9.3. Publish the Codebase

Click OK, and Maven Studio for Eclipse will publish the Codebase to your Nexus Team Server.

Eclipse will publish the Codebase to your Nexus Team Server. Figure 10.37. Published Codebase Descriptor After

Figure 10.37. Published Codebase Descriptor

After the Codebase has been published you can close Eclipse.

10.10. Materializing a Codebase

Once you have configured your Custom Codebase and published it to your Nexus Team Server you can test your new P2 Lineup by materializing it to your workstation. To do this follow the same steps you used to materialize the demonstation Maven lineup which shipped with Maven Studio for Eclipse.

10.10.1. Download the Codebase Installer

In Nexus Team server, select the Views/Repositories -> Repository panel, and then view the Nexus Managed Repositories. Select the MSE Codebase Repository and navigate to the com/mycompany/baselineup/1.0 folder. Right-click on the mse-codebase.jnlp file and select Download.

Figure 10.38. Select Published Codebase Descriptor 10.10.2. Supply Apache Subversion Credentials Since the Codebase

Figure 10.38. Select Published Codebase Descriptor

10.10.2. Supply Apache Subversion Credentials

Since the Codebase created and published in the previous section contains a Source Tree that points to the Apache Subversion server, you should leave Anonymous access checked and click on the Next button to continue.

access checked and click on the Next button to continue. Figure 10.39. Supply Subversion Credentials to

Figure 10.39. Supply Subversion Credentials to MSE Installer

10.10.3. Supply Nexus Credentials

The MSE Installer will ask you for your Nexus credentials during the installation process. You should deselect the Anonymous access checkbox and supply your Nexus credentials. If you have not configured a new Nexus user, use the default credentials admin/

admin123.

a new Nexus user, use the default credentials admin/ admin123. Figure 10.40. Supply Nexus Credentials to

Figure 10.40. Supply Nexus Credentials to MSE Installer

10.10.4.

Configure Materialization Directories

Nexus supplies the directories for the materialization. If you want to override the default directories, specify an installation directory for the Eclipse installation and a workspace for your projects and workspace-specific configuration.

for your projects and workspace-specific configuration. Figure 10.41. Choosing Installation Directories in the MSE

Figure 10.41. Choosing Installation Directories in the MSE Installer

10.10.5. Use Your Materialized Eclipse Installation

Once the materialization process is completed, you will have a customized installation of Eclipse complete with the Eclipse- Checkstyle plugin and the source code for Apache Commons Lang. You can use this same functionality to create custom, one-click solutions for developer on-boarding.

custom, one-click solutions for developer on-boarding. Figure 10.42. A Materialized, Custom, Eclipse Workspace

Figure 10.42. A Materialized, Custom, Eclipse Workspace

Figure 10.42. A Materialized, Custom, Eclipse Workspace Figure 10.43. Checkstyle View from Materialized Workspae 87

Figure 10.43. Checkstyle View from Materialized Workspae

10.11. Troubleshooting Codebase Materialization

This section attempts to summarize some of the problems that can occur during Nexus Team Edition installation and Codebase materialization. If you encounter any problems or difficulties running through this quickstart chapter, please contact Sonatype at book@sonatype.org 1 .

10.11.1. Reset Subversion Connection

The demonstration codebase contains source trees which depend upon public Subversion servers hosted by the Apache Software Foundation. Although these servers are some of the most reliable and widely used source control systems you will find, you might experience problems during materialization if your connection is reset.

problems during materialization if your connection is reset. Figure 10.44. Subversion Connect Reset During

Figure 10.44. Subversion Connect Reset During Materialization

After the MSE Installer starts a newly installed Eclipse instance, it will attempt to checkout source code from the source trees configured in the codebase. If you see the error dialog shown in Figure 10.44, “Subversion Connect Reset During Materialization”, restart the materialization process. The connection to a Subversion server could be reset by either the server or the client, and the most likely scenario is that there was some brief downtime on the server-side. Running the materialization again should be enough to fix this problem.

If the problem continues to happen even after a retry, you might want to investigate any process or system that mght be running locally to monitor and secure a network. Checking out a large project from a public Subversion server can involve a single, long- lived connection to a remote server. Make sure that there are no security systems terminating the connection to the remote Subversion server on your end of the connection.

Chapter 11. Managing MSE Codebases and P2 Lineups

11.1. Introduction

Maven Studio for Eclipse (MSE) gives you the ability to capture common configuration and projects for your developers with the Developer Onboarding feature. Using the Developer Onboarding feature, you can very quickly configure and deliver a common configuration across your entire enterprise.

11.2. Creating a MSE Codebase

There are two ways to create an MSE Codebase:

Create a new P2 Lineup You can create a new P2 Lineup which captures an Eclipse configuration including all components and plugins installed in Eclipse. After creating and publishing a new P2 Lineup, Maven Studio for Eclipse will create a new Codebase and associate it with your new P2 Lineup.

Create a new MSE Codebase Alternatively, you can create a new MSE Codebase. This newly created MSE Codebase will have an empty P2 Lineup URL which will need to be populated using a URL of a previously published P2 Lineup.

The following sections outline the details of both of these approaches.

11.2.1. Creating a New P2 Lineup

When you create a new P2 Lineup, you are configuring the Eclipse installation which will be associated with an MSE Codebase. This includes the versions of all components and plugins which will be installed by the MSE Installer. Your configuration will be validated against a Nexus Team Edition server to ensure that users will have access to P2 Proxy repositories for all the components required by your P2 Lineup.

To create a new P2 Lineup in Eclipse, go to File -> New and select Other

Maven Studio for Eclipse folder, and select New P2 Lineup as shown in Figure 11.1, “Selecting the New P2 Lineup Wizard”.

This will display the wizard selection dialog. Expand the

This will display the wizard selection dialog. Expand the Figure 11.1. Selecting the New P2 Lineup

Figure 11.1. Selecting the New P2 Lineup Wizard

The initial screen of the new P2 Lineup Wizard shown in Figure 11.2, “Initial Screen of Lineup Wizard: Lineup Setup” captures lineup coordinates and information about the target Nexus Team Edition server. A P2 Lineup is published to Nexus and stored with a set of lineup coordinates: Group Id, Artifact Id, and Version. These coordinates uniquely identify a published P2 Lineup.

Figure 11.2. Initial Screen of Lineup Wizard: Lineup Setup Clicking Next loads the Lineup Editor

Figure 11.2. Initial Screen of Lineup Wizard: Lineup Setup

Clicking Next loads the Lineup Editor shown in Figure 11.3, “Editing a New P2 Lineup”. The Lineup Editor displays two sections:

Installable Units and Repositories. The Installable Units section configures the plugins and components which are going to be installed as a part of the MSE Codebase materialization. There are two components which will always be a part of every MSE Codebase:

Maven Studio Materialization Support This component contains the framework which supports MSE Codebase materialization. The verion number 0.0.0 tells Eclipse to use the latest available version.

Sonatype Studio Base IDE Lineup This component combines the basic features of Sonatype Studio including support for Subversion, Git, and support for the Sonatype m2eclipse component.

The Repositories section of the Lineup Edition contains all of the repositories required for a successful MSE Codebase materialization. You can add new repositories to this list to support the installation of addition installable units. For example, in Figure 11.3, “Editing a New P2 Lineup”, the Repositories section contains an extra repository http://eclipse-cs.sf.net/update. This repository corresponds to the Eclipse Checkstyle Plugin-in feature listed under Installable Units.

The Validate button in the Lineup Editor causes Maven Studio to connect to Nexus Team Edition and verify that all repositories and installable units are available. If you have added a new repository to the Lineup Editor, you will also need to add a new P2 Proxy repository to Nexus Team Edition. The Manage Nexus repositories link below the Repositories section will load the repositories list in Nexus Team Edition. If you need to add additional P2 Proxy repositories to support custom lineups, click on this Manage Nexus Repositories button and create any appropriate repositories in your Nexus Team Edition installation.

Figure 11.3. Editing a New P2 Lineup next to the list of Installable Units in

Figure 11.3. Editing a New P2 Lineup

next to the list of Installable Units in the Lineup Editor shown in will load the Add Installable Unit dialog shown in Figure 11.4, “Add

an Installable Unit to a P2 Lineup”. Select an existing repository, or paste a new Update Site URL into the Work with dropdown field, then select the appropriate Installable Units in this dialog. Clicking on OK will then return you to the P2 Lineup Editor with the Installation Units select added to the list of Installable Units configured for your new P2 Lineup.

To a new an installable unit to a P2 Lineup, click on Add Figure 11.3, “Editing a New P2 Lineup”. Clicking on Add

Figure 11.3, “Editing a New P2 Lineup”. Clicking on Add Figure 11.4. Add an Installable Unit

Figure 11.4. Add an Installable Unit to a P2 Lineup

next to the list of repositories shown in Figure 11.3, “Editing a New P2 Lineup”.

This will display the Add Repository dialog shown in Figure 11.5, “Add a Repository to a P2 Lineup”. When you add a repository to a P2 Lineup, you need to make sure that Nexus Team Edition has a matching P2 Proxy repository.

To add a repository to a P2 Lineup, click on Add

Figure 11.5. Add a Repository to a P2 Lineup Once you are finished configuring you

Figure 11.5. Add a Repository to a P2 Lineup

Once you are finished configuring you new P2 Lineup in the Lineup Editor shown in Figure 11.3, “Editing a New P2 Lineup” click Next. You will then see the New MSE Codebase Descriptor dialog shown in Figure 11.6, “Summary of New P2 Lineup Identifiers”. Clicking Finish will cause Sonatype Studio to publish the new P2 Lineup to Nexus Team Edition and open a new MSE Codebase Overview form with the P2 Lineup field populated with the results of this wizard.

P2 Lineup field populated with the results of this wizard. Figure 11.6. Summary of New P2

Figure 11.6. Summary of New P2 Lineup Identifiers

11.2.2. Creating a New MSE Codebase

If you already have a P2 Lineup configured, and you want to create a new MSE Codebase. You can create a new MSE Codebase

directly by going to File -> New, selecting Other

Project as shown in Figure 11.7, “Selecting the New Codebase Project Wizard”.

Expand the Maven Studio for Eclipse folder and then select New Codebase

Maven Studio for Eclipse folder and then select New Codebase Figure 11.7. Selecting the New Codebase

Figure 11.7. Selecting the New Codebase Project Wizard

11.3. Configuring a MSE Codebase

Once you create a codebase, you will see the Codebase Overview shown in Figure 11.8, “Codebase Overview”. The MSE Codebase settings, MSE Source Trees, resources, and security are all configured from this interface. Once a Codebase has been properly

configured, the codebase is saved as an XML file and then published to Nexus Team edition. The Codebase editor contains the following sections:

Codebase Information This section contains identifiers, URLs, a name, a description, and a logo for the MSE Codebase. This section is described in more detail in Section 11.4, “Configuring Codebase Information”.

Source Trees An MSE Codebase contains one or more Source Trees. A source tree is a location in a source control server like Git or Subversion and it corresponds to a project or set of projects in an Eclipse environment. This section is described in more detail in Section 11.7, “Managing Codebase Source Trees”.

Locations Locations holds URLs and resources which are associated with an MSE Codebase. The P2 Lineup Location points to a file hosted by Nexus Team Edition which describes the configuration of Eclipse, and the Maven Settings and Eclipse Preferences associate configuration data with an MSE Codebase. This section is described in more detail in Section 11.5, “Managing Codebase Resource Locations”.

Prerequisites This section contains configuration values which affect the operation of Eclipse. This section is described in more detail in Section 11.6, “Setting Codebase Prerequisites”.

Realms When the MSE Installer connects to remote resources to download settings, configuration, source control, or P2 Lineups, it stores credentials in Security Realms. This list of realms will be used to populate realm dropdownds throughout the Codebase and Source Tree editors. This section is described in more detail in .

Tree editors. This section is described in more detail in . Figure 11.8. Codebase Overview At

Figure 11.8. Codebase Overview

At the bottom of the Codebase Editor, you will see a series of tabs for each of the configured MSE Source Trees. Source trees are locations in a source control system which correspond to one of more projects in an Eclipse workspace. The process for creating and managing source trees is described in more detail in Section 11.7, “Managing Codebase Source Trees”.

Once a Codebase has been configured and saved, Maven Studio for Eclipse will have a project in the Project Explorer named after the Artifact ID of your Codebase which contains up to three files:

mse-codebase.xml This is the MSE Codebase descriptor, it is the XML file which is published to Nexus Team Edition, and which is used to configured the Java WebStart JNLP application which is used to start the MSE Installer.

mse-codebase-preferences.jar

If you have configured the MSE Codebase editor to generate, publish, and associate Eclipse preferences with an MSE

Codebase, this JAR file will contain an export of the selected Eclipse preferences.

mse-codebase-icon.png This is the 48x48 icon which is used to represent this MSE Codebase in an MSE Catalog.

is used to represent this MSE Codebase in an MSE Catalog. Figure 11.9. Codebase Project Files

Figure 11.9. Codebase Project Files

11.4. Configuring Codebase Information

The Codebase Information section shown in Figure 11.10, “Configuring Codebase Information” contains identifiers, URLs, a name, a description, and an application icon for the Codebase. This section contains the following fields:

Group Id The group Id is an arbitrary, organization or project-specific identifier which generally matches the reversed, period- delimited domain name of an organization plus any additional project identifiers. Examples: com.google, com.sonatype.nexus, org.apache.maven.

Artifact Id The Codebase project identifier. This artifact id is used to identify a codebase as an Eclipse project. Examples: developers working in the Ecommerce group would materialize a Codebase with an artifactId of "ecommerce".

Version

A version adheres to the following format: "<Major Version>.<Minor Version>.<Point Release>". Examples: The first version

of the "ecommerce" codebase may have a version number "1.0.0". A small update to this codebase would have the version number "1.1.0", and a major revision would have a version of "2.0.0.".

Name This field stores a descriptive name for a codebase.

Description This field contains a short, paragraph-long description of a codebase.

Image Every codebase can be associated with a 48x48 icon. Although this icon is not currently displayed by Nexus Team Edition or the MSE Installer, this icon will be visible in the upcoming Maven Studio for Eclipse Catalog feature.

Homepage This field contains a URL to the homepage associated with a codebase. This can be a page specific to the project or workgroup which is using this Codebase.

Documentation This field contains a URL to a documentation page to be associated with a Codebase.

Figure 11.10. Configuring Codebase Information 11.5. Managing Codebase Resource Locations In the MSE Codebase editor,

Figure 11.10. Configuring Codebase Information

11.5. Managing Codebase Resource Locations

In the MSE Codebase editor, the Locations section shown in Figure 11.11, “Configuring Codebase Resources” tracks important configuration resources which can be associated with a Codebase. The resources are:

Security Realm The MSE Installer will use a single security realm to access all of the resources listed in the Location section. Although there are no restrictions for the URLs used in this section, the MSE Installer was designed with the expectation that all external configuration resources would be downloaded from the same Nexus server.

P2 Lineup Location If you created your MSE Codebase using the New P2 Lineup wizard, the P2 Lineup wizard finished and then immediately loaded a new MSE Codebase with this field pre-populated. If you created a new MSE Codebase using the New MSE Codebase wizard, this field will be empty and you will need to supply a URL from Nexus Team edition.

Maven Settings This field contains a URL for your Maven Settings. Nexus Professional provides support for managing user-specific Maven Settings. To learn more about using Nexus Professional to manage and distribute Maven Settings, read "Managing Maven Settings" 1 chapter in Repository Management with Nexus 2 . If you are using the default Maven Settings location in Nexus, your URL will resemble the following URL: http://localhost:8081/nexus/service/local/templates/settings/default/content

Eclipse Preferences An MSE Codebase can distribute a set of common Eclipse preferences to cature common configuration settings that cover code standards, Aspect-oriented programming settings, and m2eclipse configuration.

programming settings, and m2eclipse configuration. Figure 11.11. Configuring Codebase Resources 1

Figure 11.11. Configuring Codebase Resources

11.5.1.

Publishing Eclipse Preferences

The MSE Codebase editor can capture your Eclipse preferences and publish them to a Nexus repository manager. Open the Eclipse

Preferences dialog shown in Figure 11.12, “Configuring Eclipse Preferences for a Codebase” by clicking on the Select Figure 11.11, “Configuring Codebase Resources”.

button in

To publish Eclipse preferences from the current Eclipse installation, select "Export workspace preferences" and select all of the preference categories you want to publish in this MSE Codebase. The available preferences categories:

PROXY Proxy configuration captures proxy configuration under General -> Network Connections from the Eclipse preferences.

JDT

Selecting this group captures all configuration under the "Java" category from the Eclipse preferences.

M2E

Selecting this group captures all configuration under the "Maven" category from the Eclipse preferences.

After configuring a codebase to publish Eclipse settings, save your Codebase and you should see a file named mse-codebase- preferences.jar associated with the MSE Codebase in the Project Explorer. When the Codebase is published to Nexus Team edition, this preferences JAR file will be published to the repository manager and associated with the published MSE Codebase.

You can associate an MSE Codebase with a set of previous published Eclipse preferences by selecting "External URL" and supplying the URL to a set of Eclipse preferences. The most common scenarios for using an existing, external URL is when an MSE Codebase is referencing Eclipse preferences from another MSE Codebase.

referencing Eclipse preferences from another MSE Codebase. Figure 11.12. Configuring Eclipse Preferences for a Codebase

Figure 11.12. Configuring Eclipse Preferences for a Codebase

11.5.2. Publishing Maven Settings

An important component of Maven configuration is a Maven Settings file usually stored in ~/.m2/settings.xml. This file contains credentials, profiles, and preferences which can use used to customize configuration variables for individual developers. Nexus Team Edition and Nexus Professional Edition provide you with the ability to store and managed Maven Settings files for developers. If you have configured Maven Settings in Nexus, you should supply the Template URL to the MSE Codebase editor. When the MSE Installer materializes a new Eclipse installation it will download a settings.xml from the Template URL and interpolate that template with two substitution variables:

${baseurl} This is the Base URL for the Nexus server responsible for delivering the Maven Settings template. If you codebase is configured to download Maven Settings from "http://central.example.org/nexus/server/local/templates/settings/default/ content", the ${baseurl} will be replaced with "http://central.example.org/nexus/".

${userId} This is the user identifier for the user making the request for Maven Settings. If your MSE Code contains a security realm for Nexus, this ${userId} value in a settings.xml template will be replaced with the username supplied to the MSE Installer for the Nexus realm.

Figure 11.10, “Configuring Codebase Information” shows the Maven Settings configuration panel from Nexus Team Edition. To

configure an MSE Codebase to download the "enterprise-webapp-team" Maven Settings template, you would supply the URL listed

in the Template URL column to the MSE Codebase editor.

in the Template URL column to the MSE Codebase editor. Figure 11.13. Configuring Codebase Information To

Figure 11.13. Configuring Codebase Information

To learn more about using Nexus Professional to manage and distribute Maven Settings, read "Managing Maven Settings" 3 chapter

11.6. Setting Codebase Prerequisites

The Codebase editor contains a section to configure prerequisites. The Required Memory field shown in Figure 11.14, “Configuring Codebase Prerequisites” allows you to configure the validation criteria which must be satisfied before the MSE Installer will materialize a codebase. The MSE Installer will test the workstation to see if it has sufficient memory to perform a materialization.

if it has sufficient memory to perform a materialization. Figure 11.14. Configuring Codebase Prerequisites 11.7.

Figure 11.14. Configuring Codebase Prerequisites

11.7. Managing Codebase Source Trees

A Source Tree is a location in source control which corresponds to one or more projects in an Eclipse environment. To add a

new Source Tree, click on the Create “Configuring Codebase Source Trees”.

button next to the Source Trees section of the Codebase editor as shown in Figure 11.15,

Figure 11.15. Configuring Codebase Source Trees To delete a Source Tree from an MSE Codebase,

Figure 11.15. Configuring Codebase Source Trees

To delete a Source Tree from an MSE Codebase, select the Codebase in the Source Trees section of the MSE Codebase editor and click on the Delete button. Eclipse will then present you with a confirmation dialog to make sure that you really want to delete the selected Source Tree.

11.8. Configuring Codebase Security

Each Codebase is associated with one or more Security Realms. The MSE Installer stores credentials in secure storage in Security Realms. Create security realms for each resource that requires a separate set of credentials. The Realms section of the Codebase Overview, as shown in Figure 11.16, “Configuring Codebase Realms”, contains the list of all realms used throughout an MSE Codebae.

the list of all realms used throughout an MSE Codebae. Figure 11.16. Configuring Codebase Realms To

Figure 11.16. Configuring Codebase Realms

To add a new Security Realm to a Codebase, click on the Create

and supply a new name for the Security Realm in the dialog shown in Figure 11.17, “Adding a New Security Realm”.

button shown in Figure 11.16, “Configuring Codebase Realms”

shown in Figure 11.16, “Configuring Codebase Realms” Figure 11.17. Adding a New Security Realm 11.9. Configuring

Figure 11.17. Adding a New Security Realm

11.9. Configuring a Source Tree

Every MSE Codebase can contain one or more Source Trees. A Source Tree is a location in source control containing one or more Maven projects. To illustrate the relationship between a Codebase and a Source Tree, consider the example illustrated in Figure 11.18, “Two Codebases with an Overlapping Source Tree”. A company has two MSE Codebases: one codebase is used by a team which develops a web application, another codebase is used by a team which develops a client-side application written in Swing. Both teams use a common library, and both teams maintain a separate Subversion repository which contains team-specific code. Each team would have a custom MSE Codebase with two Source Trees, and both of these codebases would include a Source Tree for the Common Library project.

eb W T eam Codebase Swing Web App App Common Library T eam Swing Codebase
eb
W
T eam
Codebase
Swing
Web
App
App
Common
Library
T eam
Swing
Codebase

Figure 11.18. Two Codebases with an Overlapping Source Tree

To open the Source Tree editor, go to the Codebase Overview, and click on one of the Source Tree tabs below the Codebase Overview as shown in Figure 11.8, “Codebase Overview”. If there are no Source Trees to edit, create a Source Tree by following the directions in Section 11.7, “Managing Codebase Source Trees”. The Source Tree editor is shown in Figure 11.19, “Configuring an MSE Codebase Source Tree”.

in Figure 11.19, “Configuring an MSE Codebase Source Tree”. Figure 11.19. Configuring an MSE Codebase Source

Figure 11.19. Configuring an MSE Codebase Source Tree

11.9.1.

Adding a Maven Profile

The Source Tree editor allows you to add a Maven Profile which will be made active for every project in a particular Source Tree. To add a new Maven Profile to a Source Tree, click on the Create button in th Profiles section of the Source Tree Overview shown in Figure 11.19, “Configuring an MSE Codebase Source Tree”. Once you click create, type in the name of the profile you want activated into the dialog shown in Figure 11.20, “Adding a Maven Profile”.

dialog shown in Figure 11.20, “Adding a Maven Profile”. Figure 11.20. Adding a Maven Profile 11.9.2.

Figure 11.20. Adding a Maven Profile

11.9.2. Adding a New Feed URL

The Source Tree editor allows you to add feeds which will be made available to developers working with this materialized MSE Codebase. To add a new Feed URL, click on Create in the Feed section of the Source Tree Overview shown in Figure 11.19, “Configuring an MSE Codebase Source Tree”.

Figure 11.19, “Configuring an MSE Codebase Source Tree”. Figure 11.21. Adding a New Feed URL 11.10.

Figure 11.21. Adding a New Feed URL

11.10. Publishing an MSE Codebase to Nexus Team Edition

An MSE Codebase is published to Nexus Team Edition where it is then made available to clients for materialization. To publish an MSE Codebase, open the Codebase Overview and click on the Publish button shown in Figure 11.22, “Codebase Publish Button”.

button shown in Figure 11.22, “Codebase Publish Button”. Figure 11.22. Codebase Publish Button Clicking the Publish

Figure 11.22. Codebase Publish Button

Clicking the Publish button will show the Publish Codebase Descriptor dialog shown in Figure 11.23, “Publish Codebase Dialog”. This dialog contains the URL and credentials that Maven Studio for Eclipse will use to connect to Nexus Team Edition. Clicking on the Publish button in this dialog will then cause Maven Studio for Eclipse to connect to Nexus Team Edition and transfer the codebase to Nexus Team Edition.

Figure 11.23. Publish Codebase Dialog 101

Figure 11.23. Publish Codebase Dialog

Appendix A. Creative Commons License

This work is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States license. For more information about this license, see http://creativecommons.org/licenses/by-nc-nd/3.0/us/. You are free to share, copy, distribute, display, and perform the work under the following conditions:

• You must attribute the work to Sonatype, Inc. with a link to http://www.sonatype.com.

• You may not use this work for commercial purposes.

• You may not alter, transform, or build upon this work.

If you redistribute this work on a web page, you must include the following link with the URL in the about attribute listed on a single line (remove the backslashes and join all URL parameters):

<div xmlns:cc="http://creativecommons.org/ns#"

about="http://creativecommons.org/license/results-one?q_1=2&q_1=1\

&field_commercial=n&field_derivatives=n&field_jurisdiction=us\

&field_format=StillImage&field_worktitle=Repository%3A+\Management\

&field_attribute_to_name=Sonatype%2C+Inc.\

&field_attribute_to_url=http%3A%2F%2Fwww.sonatype.com\

&field_sourceurl=http%3A%2F%2Fwww.sonatype.com%2Fbook\

&lang=en_US&language=en_US&n_questions=3">

<a rel="cc:attributionURL" property="cc:attributionName" href="http://www.sonatype.com">Sonatype, Inc.</a> / <a rel="license"

href="http://creativecommons.org/licenses/by-nc-nd/3.0/us/">

CC BY-NC-ND 3.0</a> </div>

When downloaded or distributed in a jurisdiction other than the United States of America, this work shall be covered by the appropriate ported version of Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 license for the specific jurisdiction. If the Creative Commons Attribution-Noncommercial-No Derivative Works version 3.0 license is not available for a specific jurisdiction, this work shall be covered under the Creative Commons Attribution-Noncommercial-No Derivate Works version 2.5 license for the jurisdiction in which the work was downloaded or distributed. A comprehensive list of jurisdictions for which a Creative Commons license is available can be found on the Creative Commons International web site at http://creativecommons.org/international.

If no ported version of the Creative Commons license exists for a particular jurisdiction, this work shall be covered by the generic, unported Creative Commons Attribution-Noncommercial-No Derivative Works version 3.0 license available from http://

A.1. Creative Commons BY-NC-ND 3.0 US License

THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.

BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.

1.

Definitions

a. "Collective Work" means a work, such as a periodical issue, anthology or encyclopedia, in which the Work in its entirety in unmodified form, along with one or more other contributions, constituting separate and independent works in themselves, are assembled into a collective whole. A work that constitutes a Collective Work will not be considered a Derivative Work (as defined below) for the purposes of this License.

b. "Derivative Work" means a work based upon the Work or upon the Work and other pre-existing works, such as a translation, musical arrangement, dramatization, fictionalization, motion picture version, sound recording, art reproduction, abridgment,

condensation, or any other form in which the Work may be recast, transformed, or adapted, except that a work that constitutes

a Collective Work will not be considered a Derivative Work for the purpose of this License. For the avoidance of doubt, where the Work is a musical composition or sound recording, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered a Derivative Work for the purpose of this License.

c. "Licensor" means the individual, individuals, entity or entities that offers the Work under the terms of this License.

d. "Original Author" means the individual, individuals, entity or entities who created the Work.

e. "Work" means the copyrightable work of authorship offered under the terms of this License.

f. "You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation.

2. Fair Use Rights. Nothing in this license is intended to reduce, limit, or restrict any rights arising from fair use, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws.

3. License Grant. Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non- exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below:

a. to reproduce the Work, to incorporate the Work into one or more Collective Works, and to reproduce the Work as incorporated in the Collective Works; and,

b. to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission the Work including as incorporated in Collective Works.

The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats, but otherwise you have no rights to make Derivative Works. All rights not expressly granted by Licensor are hereby reserved, including but not limited to the rights set forth in Sections 4(d) and 4(e).

4. Restrictions.The license granted in Section 3 above is expressly made subject to and limited by the following restrictions:

a. You may distribute, publicly display, publicly perform, or publicly digitally perform the Work only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy or phonorecord of the Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose

any terms on the Work that restrict the terms of this License or the ability of a recipient of the Work to exercise the rights granted to that recipient under the terms of the License. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. When You distribute, publicly display, publicly perform, or publicly digitally perform the Work, You may not impose any technological measures on the Work that restrict the ability of

a recipient of the Work from You to exercise the rights granted to that recipient under the terms of the License. This Section 4(a) applies to the Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Work itself to be made subject to the terms of this License. If You create a Collective Work, upon notice from any Licensor You must, to the extent practicable, remove from the Collective Work any credit as required by Section 4(c), as requested.

b. You may not exercise any of the rights granted to You in Section 3 above in any manner that is primarily intended for or directed toward commercial advantage or private monetary compensation. The exchange of the Work for other copyrighted

works by means of digital file-sharing or otherwise shall not be considered to be intended for or directed toward commercial advantage or private monetary compensation, provided there is no payment of any monetary compensation in connection with the exchange of copyrighted works.

c. If You distribute, publicly display, publicly perform, or publicly digitally perform the Work (as defined in Section 1 above) or Collective Works (as defined in Section 1 above), You must, unless a request has been made pursuant to Section 4(a), keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or (ii) if the Original Author and/or Licensor designate another party or parties (e.g. a sponsor institute, publishing entity, journal) for attribution ("Attribution Parties") in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; the title of the Work if supplied; to the extent reasonably practicable, the Uniform Resource Identifier, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work. The credit required by this Section 4(c) may be implemented in any reasonable manner; provided, however, that in the case of a Collective Work, at a minimum such credit will appear, if a credit for all contributing authors of the Collective Work appears, then as part of these credits and in a manner at least as prominent as the credits for the other contributing authors. For the avoidance of doubt, You may only use the credit required by this clause for the purpose of attribution in the manner set out above and, by exercising Your rights under this License, You may not implicitly or explicitly assert or imply any connection with, sponsorship or endorsement by the Original Author, Licensor and/or Attribution Parties, as appropriate, of You or Your use of the Work, without the separate, express prior written permission of the Original Author, Licensor and/or Attribution Parties.

d. For the avoidance of doubt, where the Work is a musical composition:

i. Performance Royalties Under Blanket Licenses. Licensor reserves the exclusive right to collect whether individually or, in the event that Licensor is a member of a performance rights society (e.g. ASCAP, BMI, SESAC), via that society, royalties for the public performance or public digital performance (e.g. webcast) of the Work if that performance is primarily intended for or directed toward commercial advantage or private monetary compensation.

ii. Mechanical Rights and Statutory Royalties. Licensor reserves the exclusive right to collect, whether individually or via a music rights agency or designated agent (e.g. Harry Fox Agency), royalties for any phonorecord You create from the Work ("cover version") and distribute, subject to the compulsory license created by 17 USC Section 115 of the US Copyright Act (or the equivalent in other jurisdictions), if Your distribution of such cover version is primarily intended for or directed toward commercial advantage or private monetary compensation.

e. Webcasting Rights and Statutory Royalties. For the avoidance of doubt, where the Work is a sound recording, Licensor reserves the exclusive right to collect, whether individually or via a performance-rights society (e.g. SoundExchange), royalties for the public digital performance (e.g. webcast) of the Work, subject to the compulsory license created by 17 USC Section 114 of the US Copyright Act (or the equivalent in other jurisdictions), if Your public digital performance is primarily intended for or directed toward commercial advantage or private monetary compensation.

5. Representations, Warranties and Disclaimer

UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND ONLY TO THE EXTENT OF ANY RIGHTS HELD IN THE LICENSED WORK BY THE LICENSOR. THE LICENSOR MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MARKETABILITY, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.

6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7.

Termination

a. This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Collective Works (as defined in Section 1 above) from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License.

b. Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above.

8. Miscellaneous

a. Each time You distribute or publicly digitally perform the Work (as defined in Section 1 above) or a Collective Work (as defined in Section 1 above), the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.

b. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

c. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent.

d. This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You.

Creative Commons Notice

Creative Commons is not a party to this License, and makes no warranty whatsoever in connection with the Work. Creative Commons will not be liable to You or any party on any legal theory for any damages whatsoever, including without limitation any general, special, incidental or consequential damages arising in connection to this license. Notwithstanding the foregoing two (2) sentences, if Creative Commons has expressly identified itself as the Licensor hereunder, it shall have all rights and obligations of Licensor.

Except for the limited purpose of indicating to the public that the Work is licensed under the CCPL, Creative Commons does not authorize the use by either party of the trademark "Creative Commons" or any related trademark or logo of Creative Commons without the prior written consent of Creative Commons. Any permitted use will be in compliance with Creative Commons' then- current trademark usage guidelines, as may be published on its website or otherwise made available upon request from time to time. For the avoidance of doubt, this trademark restriction does not form part of this License.

Creative Commons may be contacted at http://creativecommons.org/.

Appendix B. Book Revision History

The following sections list changes made to the book in reverse chronological order starting with 1.1.

B.1. Changes in Edition 0.8

The following changes were introduced in Edition 0.8 on February 15, 2010: