Apache Maven: Settings.xml explanation

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

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

Major elements of settings.xml

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

Let’s explore each element one-by-one

<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)

Example:

<localRepository>D:\M2_HOME\.m2\repository</localRepository>

 

<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

Example:

<interactiveMode>true</interactiveMode>

 

<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

Example:

<offline>false</offline>

 

<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

Example:

<pluginGroups>
	<pluginGroup>com.your.first.plugins</pluginGroup>
	<pluginGroup>com.your.second.plugins</pluginGroup>
	<pluginGroup>com.your.last.plugins</pluginGroup>
</pluginGroups>

 

<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

Example:

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

 

<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

Example:

<!-- 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>

 

<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)

Example:

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

 

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

 

<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

Example:

<activeProfiles>
	<activeProfile>alwaysActiveProfile</activeProfile>
	<activeProfile>anotherAlwaysActiveProfile</activeProfile>
</activeProfiles>

References

http://maven.apache.org/settings.html
http://maven.apache.org/ref/3.2.3/maven-settings/settings.html
http://www.benchresources.net/apache-maven-local-central-and-remote-repositories
 

Read Also:

 

Happy Coding !!
Happy Learning !!

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