Apache Maven – Settings.xml explanation

December 25, 2014 SJ Apache Maven 0

In this article, we will explore and understand the major elements of “settings.xml” file located at {MAVEN_HOME}\conf\settings.xml and its important role

This settings.xml file is not specific to any project, so this shouldn’t be bundled with distribution like JAR or WAR. The information may include about local repository value, remote repository site location, or some application server authentication credentials

Note: It doesn’t make sense to distribute these values to audience using the applications

1. Location of settings.xml

In general, this file can be specified and referred from two locations

  • Global level
    The location of the Global level is same as we mentioned in the introductory section and all the Maven users will share the same configuration from this settings.xml file
    i.e.; {MAVEN_HOME}\conf\settings.xml
  • User level
    Whereas, in user level this file is stored at user’s home i.e.; {user.home}\.m2\settings.xml and this configuration is specific to this user only

2. Major elements of settings.xml

  • localRepository
  • interactiveMode
  • offline
  • pluginGroups
  • proxies
  • servers
  • mirrors
  • profiles
  • activeProfiles

Let’s explore each element one-by-one

2.1 <localRepository>……..</localRepository>

  • The value in this element is the path to local Maven repository, where maven stores the artifacts downloaded from central/remote repository
  • Note: For the first time, it will download all the required artifacts from central/remote repositories. And from next time onwards, whenever maven commands gets executed then it first checks the local repository
  • If present –> then adds the dependency from local repository
  • Otherwise –> downloads from central/remote repositories (depending on the configuration)
<localRepository>D:\M2_HOME\.m2\repository</localRepository>

2.2 <interactiveMode>……..</interactiveMode>

  • This will determine, whether to prompts to user for inputs
  • If it sets to,
    • true –> it will request the user to enter the value
    • false –> it will assume some sensible values for the required attributes
  • Note: default value is true, unless or until we have changed in settings.xml
<interactiveMode>true</interactiveMode>

2.3 <offline>……..</offline>

  • This element determines, whether Maven should connect to internet to download artifacts or for some other deployment when executing a build (i.e.; when resolving to dependency)
  • If it sets to,
    • true –> doesn’t connect to internet (instead resolves dependency from local repository)
    • false –> connects to internet to download artifacts and for other purposes
  • Note: default value is false, unless or until we have changed in settings.xml
<offline>false</offline>

2.4 <pluginGroups>……..</pluginGroups>

  • This element contains the list of group Ids, when resolving plugins by their prefix. This is similar to plugin lookup
  • Note: By default “org.apache.maven.plugins” and “org.codehaus.mojo” are added to the list, if these groupId doesn’t mentioned explicitly in this element
<pluginGroups>
	<pluginGroup>com.your.first.plugins</pluginGroup>
	<pluginGroup>com.your.second.plugins</pluginGroup>
	<pluginGroup>com.your.last.plugins</pluginGroup>
</pluginGroups>

2.5 <proxies>……..</proxies>

  • This element used for proxy setting, when maven user is behind the firewall and these settings can be used to connect to the internet
  • Note: If there are many proxies, then by default first active (i.e.; marked true) will be used, unless we tweak from command line while executing any maven commands
<proxies>
	<proxy>
		<id>optional</id>
		<active>true</active>
		<protocol>http</protocol>
		<username>proxyuser</username>
		<password>proxypass</password>
		<host>proxy.host.net</host>
		<port>80</port>
		<nonProxyHosts>local.net|some.host.com</nonProxyHosts>
	</proxy>
</proxies>

2.6 <servers>……..</servers>

  • This element can be used to configure authentication information, when connecting to application server. With this we can directly package & deploy the WAR file to the server for e.g.; Tomcat server. But we also need to configure equivalent plugin in our project’s pom.xml and set necessary values
  • Note: Authentication information can be stored in two ways either username/password credentials combination or privateKey/passphrase combination
<!-- Username/password -->
<server>
	<id>deploymentRepo</id>
	<username>repouser</username>
	<password>repopwd</password>
</server>

<!-- Another sample, using keys to authenticate -->
<server>
	<id>siteServer</id>
	<privateKey>/path/to/private/key</privateKey>
	<passphrase>optional; leave empty if not used</passphrase>
</server>

2.7 <mirrors>……..</mirrors>

  • For some third party dependencies, we can configure remote repositories site location in pom.xml from where these dependencies (or artifacts) can be downloaded
  • These declared repository site location sometime doesn’t responds due to various reasons; one of the reasons could be due to high traffic flowing through that site
  • In this situation, Maven allows to configure alternate mirror site of these remote repositories in settings.xml under the element <mirrors>
  • Note: When we configure remote repository site url (under the element repositories/repository), then mention value for <id> element and exactly this Id should be used in the <mirrorOf> element
  • So when maven searches for alternate repository site location, then this id helps to identify the url of the mirror site (rather it does matching with this Id for alternate mirror site location –> url)
<mirrors>
	<mirror>
		<id>mirrorId</id>
		<mirrorOf>repositoryId</mirrorOf>
		<name>Human Readable Name for this Mirror.</name>
		<url>http://my.repository.com/repo/path</url>
	</mirror>
</mirrors>

2.8 <profiles>……..</profiles>

  • Using this element, we can modify the standard build process with our preferences in settings.xml. The major child elements are activation, properties, repositories, pluginRepositories
  • Under this element, we can configure various <profile> and one of them takes effect while executing maven commands and its depends on the environment or users for which we run/execute maven commands
  • There are various to way activate these profile depending on the environment or users. Like, this can activated from command line or using <activeProfiles> element in settings.xml
  • Next we will check, how can we activate profile using <activeProfiles>

2.9 <activeProfiles>……..</activeProfiles>

  • From the list of profiles configured under <profiles> element, we can activate some of the profiles mentioning its Id under this element. Check below example
  • Note: If there are two or more profiles listed here, then it will activate in the order it is specified here. Like alwaysActiveProfile will be activated first and then second and so on
<activeProfiles>
	<activeProfile>alwaysActiveProfile</activeProfile>
	<activeProfile>anotherAlwaysActiveProfile</activeProfile>
</activeProfiles>

Useful Eclipse IDE shortcuts :

Related Articles:

References:

Happy Coding !!
Happy Learning !!

Apache Maven - Proxy setting explanation
Apache Maven - Install on Windows 7 OS

Related posts:

  1. Apache Maven – Install on Windows 7 OS
  2. Apache Maven – Changing default Maven repository location in Windows 7 OS
  3. Apache Maven – Dependency Scopes
  4. Apache Maven – Co-ordinates explained