Maven Settings.xml example

In this example we are going to see the maven settings xml file and most of it’s features. Maven is a build automation tool used mainly for java projects from apache. You can access to the maven settings reference here. We are going to see some examples of the maven settings possibilities.

For this example we use the following technologies:

• MAC OSX
• Eclipse Mars.1
• Maven3
• JDK 1.8.0_65 64bits

1. Introduction

Maven has a high level of customization, you can define several things in order to define how maven works. Maven provides a configuration file called settings.xml in which you can customize the settings tag. We are going to see several things you can configure inside the settings tag in the next bullets.

The settings.xml could be in two different places:

• Maven installation: $M2_HOME/conf/settings.xml (unix notation), where M2_HOME is the maven install directory.
• User directory: ${user.home}/.m2/settings.xml (unix notation), where user.home is the user home directory.

The following image shows the maven installation directory structure:

The following image shows the user local repository structure:

You can customize both of them. If this is the case, both files will get merged, but be aware that the user-specific settings file has more priority than the other one.

The settings tag defines the following things

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

Let´s see all of them in more detail:

2. Single values

The first four elements are simple properties that accept single values. All those fields have defaults value, so you can skip the definition and the default values will be used. Let´s see it one by one:

2.1 localRepository

Indicates where is located the local maven repository. By default, this local repository is located under the user home folder in ${user.home}/.m2/repository, but with this property you can define another location. This is useful when you need to share a local repository along several users inside a project or organization.

You can see the local repository below:

The local repositories allow you to work in offline mode, and act as a cache for your artifacts, plugin and all other stuffs needed.

Use local repositories as much as you can, maven will use it by default, but you should use it anyway to improve your builds and maven operations.

2.2 interactiveMode

Indicates if maven should interact with the user for input. Is a true/false field. Defaults to true.

This option can be useful when we want to create an empty and default java project. With this option activated, maven will not ask us anything and the process will be faster. We can test it with the following instruction:

Invocation example

mvn archetype:generate -DgroupId=com.example -DartifactId=DemoJavaCodeGeeks -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Note that we have defined interactiveMode in the command line, this is only necessary if we have set interactiveMode in settings.xml to true.

The following is the console output:

2.3 usePluginRegistry

There is a file called plugin-registry.xml in ${user.home}/.m2 folder. This field indicates if maven should use that file to manage plugins versions. Defaults to false.

The Maven 2 plugin registry (~/.m2/plugin-registry.xml) is a mechanism to help the user exert some control over their build environment. Rather than simply fetching the latest version of every plugin used in a given build, this registry allows the user to peg a plugin to a particular version, and only update to newer versions under certain restricted circumstances. There are various ways to configure or bypass this feature, and the feature itself can be managed on either a per-user or global level.

• You can see more options and possibilities from the plugin registry mechanism here.

2.4 offline

Indicates if maven should work in offline mode, this is, maven can not connect to remote servers. Defaults to false.

Now, we can see an example of those four fields in the following settings.xml example with the default values:

single Values example

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <localRepository>${user.home}/.m2/repository</localRepository>
  <interactiveMode>true</interactiveMode>
  <usePluginRegistry>false</usePluginRegistry>
  <offline>false</offline>
  
  
</settings>

You have to be careful if you need to use some stuff that you had not used before in your machine, because with the offline mode activated, maven is unable to download those stuffs.

This is a common problem related to offline mode.

3. PluginGroups

The puglingGroup accepts multiples values, when a plugin is invoked, maven will search along this element in order to find the groupId for the plugin. It makes more easy the maven execution. You can define several plugins groupId, by default, it contains the following ones:

• org.apache.maven.plugins
• org.codehaus.mojo

Let´s see an example:

Group Plugin example

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <pluginGroups>
       <pluginGroup>org.mortbay.jetty</pluginGroup>
       <pluginGroup>your.own.plugin.groupId</pluginGroup>   
  </pluginGroups>
  
</settings>

Now, you can invoke the goals defined in plugins that belong to those groupId without specify it. For example:

Invocation example

mvn jetty:run

4. Servers

The servers tags allow us to define some informations that should not be distributed inside of our pom.xml files like server username, password, private keys, etc… We can define our repositories and our distributionManagement with references to the server configuration in our settings.xml or pom.xml file. Let´s see an example:

Server example

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <servers>
    <server>
      <id>server_repo_java_code_geeks</id>
      <username>john</username>
      <password>doeIsMyPass</password>
      <privateKey>${user.home}/.ssh/dsa_key</privateKey>
      <passphrase>my_passphrase</passphrase>
      <filePermissions>774</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration></configuration>
    </server>
	<server>
      <id>server_repo_java_code_geeks_2</id>
      <username>steve</username>
      <password>steve_password</password>
      <privateKey>${user.home}/.ssh/id_dsa</privateKey>
      <passphrase>steve_passphrase</passphrase>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration></configuration>
    </server>
  </servers>
  
</settings>

As you can see we have defined two servers. The id field is the key to reference this server in our pom.xml files. We can define some fields related to the server like username and password to connect to the server, permission for files and directories, private keys, etc… Most of the elements are optional but be aware that if you use a private key, you can not use a password, otherwise, private key will be ignored.

Since maven 2.1.10, a mechanism for encrypt password has been added, see this for more information about it.

5. Mirrors

Sometimes a good approach is to create a mirror of a repository, in order to reduce the traffic over the network in a big organization, or to optimize the build operations. The mirror is like a cache of a specific repository. We can define in settings.xml those mirrors, so maven will improve its operations. Let´s see an example:

Mirror example

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <mirrors>
    <mirror>
      <id>centralmirror</id>
      <name>Apache maven central mirror Spain</name>
      <url>http://downloads.centralmirror.com/public/maven</url>
      <mirrorOf>maven_central</mirrorOf>
    </mirror>
	<mirror>
      <id>jcg_mirror</id>
      <name>Java Code Gueeks Mirror Spain</name>
      <url>http://downloads.jcgmirror.com/public/jcg</url>
      <mirrorOf>javacodegeeks_repo</mirrorOf>
    </mirror>
  </mirrors>
  
</settings>

As you can see we have defined two mirrors, one for Apache maven central repository and another one for a fictional java code geeks repository. The field mirrorOfshould point to a id of a defined repository.

The id field must not match the field mirrorOf value.

• You can see more details about the mirrors of repositories here.

6. Proxies

We can define a HTTP proxy to allow to maven be able to get access to internet, reaching the needed repositories. Let´s see an example:

Proxy example

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <proxies>
    <proxy>
      <id>jcg_proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.javacodegueeks.com</host>
      <port>9000</port>
      <username>proxy_user</username>
      <password>user_password</password>
      <nonProxyHosts>*.google.com|javacodegueeks.com</nonProxyHosts>
    </proxy>
  </proxies>
  
</settings>

As you can see we have defined a HTTP proxy server which is in a host called proxy.javacodegueeks.com, listening in port 9000, with a specific user and password and some proxy excluded URL patterns.

Want to master Maven ?

Subscribe to our newsletter and download the Apache Maven Cookbook right now!

In order to get you prepared for your Maven development needs, we have compiled numerous recipes to help you kick-start your projects. Besides reading them online you may download the eBook in PDF format!

Download NOW!

Thank you!

We will contact you soon.

7. Profiles

Profiles are a maven mechanism that adds the ability to modify some values or properties under certain circumstances. The profile defined in the settings.xml file are a reduced version of the profile that we can define inside pom.xml file. We can define activation conditions, repositories, pluginRepositories and properties elements. Beware that if the same profile id are defined in pom.xml and settings.xml, the values from settings.xml will override the values defined in pom.xml. Let´s see an example:

Profile example

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <profiles>
    <profile>
      <id>test</id>
      <activation>
        <activeByDefault>false</activeByDefault>
        <jdk>1.6</jdk>
        <os>
          <name>Windows XP</name>
          <family>Windows</family>
          <arch>x86</arch>
          <version>5.1.3200</version>
        </os>
        <property>
          <name>mavenVersion</name>
          <value>3.0.3</value>
        </property>
        <file>
          <exists>${basedir}/windows.properties</exists>
          <missing>${basedir}/windows_endpoints.properties</missing>
        </file>
      </activation>
      
	  <properties>
        <user.project>${user.home}/your-project</user.project>
		<system.jks>${user.home}/your_jks_store</system.jks>
      </properties>
	  
	  <repositories>
        <repository>
          <id>codehausSnapshots</id>
          <name>Codehaus Snapshots</name>
          <releases>
            <enabled>false</enabled>
            <updatePolicy>always</updatePolicy>
            <checksumPolicy>warn</checksumPolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
            <checksumPolicy>fail</checksumPolicy>
          </snapshots>
          <url>http://snapshots.maven.codehaus.org/maven2</url>
          <layout>default</layout>
        </repository>
      </repositories>
      
	  <pluginRepositories>
         <pluginGroup>your.own.plugin.groupId</pluginGroup>
      </pluginRepositories>
	  
    </profile>
  </profiles>
  
</settings>

If you see the activation tag, we have defined some elements in order to activate this profile, this profile is not activated by default as we have indicated in activeByDefault field. If some of those criterias that we have defined are matched, maven will activate this profile.

We have defined some properties inside properties tag. When this profile is active, we can access to those properties anywhere inside pom.xml file with ${prop} notation where prop is the name that we have gave to the property.

We have defined some repositories and plugingRepositories too. This elements can be used when this profile is activated.

8. Active profiles

We can place inside of the activeProfiles some defined profiles and all of them will be activated regardless of its activation conditions or configuration elements. Let´s see an example:

Activate profile example

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <activeProfiles>
    <activeProfile>test</activeProfile>
  </activeProfiles>
  
</settings>

9. Conclusions

As we have seen in this example, maven settings file allow us to customize maven execution in several different ways and we can accomplish a lot of things with settings.xml file.

We can see the entire settings xml file below:

Activate profile example

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <localRepository>${user.home}/.m2/repository</localRepository>
  <interactiveMode>true</interactiveMode>
  <usePluginRegistry>false</usePluginRegistry>
  <offline>false</offline>

  <pluginGroups>
       <pluginGroup>org.mortbay.jetty</pluginGroup>
	   <pluginGroup>your.own.plugin.groupId</pluginGroup>	   
  </pluginGroups>

  <servers>
    <server>
      <id>server_repo_java_code_gueeks</id>
      <username>john</username>
      <password>doeIsMyPass</password>
      <privateKey>${user.home}/.ssh/dsa_key</privateKey>
      <passphrase>my_passphrase</passphrase>
      <filePermissions>774</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration></configuration>
    </server>
	<server>
      <id>server_repo_java_code_gueeks_2</id>
      <username>steve</username>
      <password>steve_password</password>
      <privateKey>${user.home}/.ssh/id_dsa</privateKey>
      <passphrase>steve_passphrase</passphrase>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration></configuration>
    </server>
  </servers>

  <mirrors>
    <mirror>
      <id>centralmirror</id>
      <name>Apache maven central mirror Spain</name>
      <url>http://downloads.centralmirror.com/public/maven</url>
      <mirrorOf>maven_central</mirrorOf>
    </mirror>
	<mirror>
      <id>jcg_mirror</id>
      <name>Java Code Gueeks Mirror Spain</name>
      <url>http://downloads.jcgmirror.com/public/jcg</url>
      <mirrorOf>javacodegueeks_repo</mirrorOf>
    </mirror>
  </mirrors>

  <proxies>
    <proxy>
      <id>jcg_proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.javacodegueeks.com</host>
      <port>9000</port>
      <username>proxy_user</username>
      <password>user_password</password>
      <nonProxyHosts>*.google.com|javacodegueeks.com</nonProxyHosts>
    </proxy>
  </proxies>

  <profiles>
    <profile>
      <id>test</id>
      <activation>
        <activeByDefault>false</activeByDefault>
        <jdk>1.6</jdk>
        <os>
          <name>Windows XP</name>
          <family>Windows</family>
          <arch>x86</arch>
          <version>5.1.3200</version>
        </os>
        <property>
          <name>mavenVersion</name>
          <value>3.0.3</value>
        </property>
        <file>
          <exists>${basedir}/windows.properties</exists>
          <missing>${basedir}/windows_endpoints.properties</missing>
        </file>
      </activation>
      
	  <properties>
        <user.project>${user.home}/your-project</user.project>
		<system.jks>${user.home}/your_jks_store</system.jks>
      </properties>
	  
	  <repositories>
        <repository>
          <id>codehausSnapshots</id>
          <name>Codehaus Snapshots</name>
          <releases>
            <enabled>false</enabled>
            <updatePolicy>always</updatePolicy>
            <checksumPolicy>warn</checksumPolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
            <checksumPolicy>fail</checksumPolicy>
          </snapshots>
          <url>http://snapshots.maven.codehaus.org/maven2</url>
          <layout>default</layout>
        </repository>
      </repositories>
      
	  <pluginRepositories>
         <pluginGroup>your.own.plugin.groupId</pluginGroup>
      </pluginRepositories>
	  
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>test</activeProfile>
  </activeProfiles>

</settings>

10. Download the source code

This was an example about Maven Settings.xml.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

I agree to the Terms and Privacy Policy

Sign up

Thank you!

We will contact you soon.