A. Settings Details

Search in book...
Toggle Font Controls
Create new playlist

Name your new playlist

Playlist description (optional)
Sign In

Email address

Password

Forgot Password?

or

Continue with Facebook

Continue with Google
Sign Up

Full Name

Email address

Confirm Email Address

Password

or

Continue with Facebook

Continue with Google

Appendix A. Settings Details

Quick Overview

The settings element in the settings.xml file contains elements used to define values that configure Maven execution. Settings in this file are settings that apply to many projects and should not be bundled to any specific project or distributed to an audience. These include values such as the local repository location, alternate remote repository servers, and authentication information. There are two locations where a settings.xml file may live:

Maven installation directory: $M2_HOME/conf/settings.xml
User-specific settings file: ~/.m2/settings.xml

Example A-1 shows an overview of the top elements under settings.

Example A-1. Overview of top-level elements in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository/>
  <interactiveMode/>
  <usePluginRegistry/>
  <offline/>
  <pluginGroups/>
  <servers/>
  <mirrors/>
  <proxies/>
  <profiles/>
  <activeProfiles/>
</settings>

Settings Details

Simple Values

Half of the top-level settings elements are simple values, representing a range of values that configure core behavior of Maven. These are shown in Example A-2.

Example A-2. Simple top-level elements in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository>${user.dir}/.m2/repository</localRepository>
  <interactiveMode>true</interactiveMode>
  <usePluginRegistry>false</usePluginRegistry>
  <offline>false</offline>
  <pluginGroups>
    <pluginGroup>org.codehaus.mojo</pluginGroup>
  </pluginGroups>
  ...
</settings>

The simple top-level elements are:

localRepository: This value is the path of this build system’s local repository. The default value is ${user.dir}/.m2/repository.
interactiveMode: true if Maven should attempt to interact with the user for input; false if not. Defaults to true.
usePluginRegistry: true if Maven should use the ${user.dir}/.m2/plugin-registry.xml file to manage plugin versions. Defaults to false.
offline: true if this build system should operate in offline mode. Defaults to false. This element is useful for build servers that cannot connect to a remote repository, either because of network setup or for security reasons.
pluginGroups: This element contains a list of pluginGroup elements. Each contains a groupId. The list is searched when a plugin is used and the groupId is not provided in the command line. This list contains org.apache.maven.plugins by default.

Servers

The distributionManagement element of the POM defines the repositories for deployment. However, certain settings such as security credentials should not be distributed along with the pom.xml. This type of information should exist on the build server in the settings.xml. See Example A-3.

Example A-3. Server configuration in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <servers>
    <server>
      <id>server001</id>
      <username>my_login</username>
      <password>my_password</password>
      <privateKey>${usr.home}/.ssh/id_dsa</privateKey>
      <passphrase>some_passphrase</passphrase>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration></configuration>
    </server>
  </servers>
  ...
</settings>

The elements under the server are:

id: This is the id of the server (not of the user to log in as) that matches the distributionManagement repository element’s id.
username, password: These elements appear as a pair denoting the login and password required to authenticate to this server.
privateKey, passphrase: Like the previous two elements, this pair specifies a path to a private key (the default is ${user.home}/.ssh/id_dsa) and a passphrase, if required. The passphrase and password elements may be externalized in the future, but for now they must be set in plain text in the settings.xml file.
filePermissions, directoryPermissions: When a repository file or directory is created on deployment, these are the permissions to use. The legal values of each is a three-digit number corresponding to *nix file permissions, i.e., 664 or 775.

Mirrors

See Example A-4.

Example A-4. Mirror configuration in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <mirrors>
    <mirror>
      <id>planetmirror.com</id>
      <name>PlanetMirror Australia</name>
      <url>http://downloads.planetmirror.com/pub/maven2</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
  ...
</settings>

The elements are:

id, name: The unique identifier of this mirror. The id is used to differentiate between mirror elements.
url: The base URL of this mirror. The build system will use this URL to connect to a repository rather than the default server URL.
mirrorOf: The ID of the server that this is a mirror of. For example, to point to a mirror of the Maven central server (http://repo1.maven.org/maven2), set this element to central. This must not match the mirror id.

Proxies

See Example A-5.

Example A-5. Proxy configuration in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <proxies>
    <proxy>
      <id>myproxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.somewhere.com</host>
      <port>8080</port>
      <username>proxyuser</username>
      <password>somepassword</password>
      <nonProxyHosts>*.google.com|ibiblio.org</nonProxyHosts>
    </proxy>
  </proxies>
  ...
</settings>

The elements are:

id: The unique identifier for this proxy. This is used to differentiate between proxy elements.
active: true if this proxy is active. This is useful for declaring a set of proxies, but only one may be active at a time.
protocol, host, port: The protocol://host:port of the proxy, separated into discrete elements.
username, password: These elements appear as a pair denoting the login and password required to authenticate to this proxy server.
nonProxyHosts: This is a list of hosts that should not be proxied. The delimiter of the list is the expected type of the proxy server; Example A-5 is pipe-delimited, and comma-delimited is also common.

Profiles

The profile element in the settings.xml is a truncated version of the pom.xml profile element. It consists of the activation, repositories, pluginRepositories, and properties elements. The profile elements include only these four elements because they concern themselves with the build system as a whole (which is the role of the settings.xml file), not with individual Project Object Model settings.

If a profile is active from settings, its values will override any equivalent profiles with matching identifiers in a POM or profiles.xml file.

Activation

Activations are the key of a profile. Like the POM’s profiles, the power of a profile comes from its ability to modify some values only under certain circumstances; those circumstances are specified via an activation element. See Example A-6.

Example A-6. Defining activation parameters in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      <id>test</id>
      <activation>
        <activeByDefault>false</activeByDefault>
        <jdk>1.5</jdk>
        <os>
          <name>Windows XP</name>
          <family>Windows</family>
          <arch>x86</arch>
          <version>5.1.2600</version>
        </os>
        <property>
          <name>mavenVersion</name>
          <value>2.0.3</value>
        </property>
        <file>
          <exists>${basedir}/file2.properties</exists>
          <missing>${basedir}/file1.properties</missing>
        </file>
      </activation>
      ...
    </profile>
  </profiles>
  ...
</settings>

Activation occurs when all specified criteria have been met, though not all are required at once. These are the elements:

jdk: Activation has a built in, Java-centric check in the jdk element. This will activate if the test is run under a jdk version number that matches the prefix given. In Example A-6, 1.5.0_06 will match.
os: The os element can define some operating system-specific properties, shown previously.
property: The profile will activate if Maven detects a property (a value that can be dereferenced within the POM by ${name}) of the corresponding name-value pair.
file: Finally, a given filename may activate the profile by the existence of a file, or if it is missing.

The activation element is not the only way that a profile may be activated. The settings.xml file’s activeProfile element may contain the profile’s id. They may also be activated explicitly through the command line via a comma-separated list after the -P flag (e.g., -P test).

To see which profile will activate in a certain build, use the maven-help-plugin:

mvn help:active-profiles

Properties

Maven properties are value placeholders, like properties in Ant. Their values are accessible anywhere within a POM by using the notation ${X}, where X is the property. They come in five different styles, all accessible from the settings.xml file:

env.X: Prefixing a variable with env. will return the shell’s environment variable. For example, ${env.PATH} contains the $path environment variable. (%PATH% in Windows.)
project.x: A dot-notated (.) path in the POM will contain the corresponding elements value.
settings.x: A dot-notated (.) path in the settings.xml will contain the corresponding elements value.
Java system properties: All properties accessible via java.lang.System.getProperties() are available as POM properties, such as ${java.home}.
x: Set within a properties element or an external file, the value may be used as ${someVar}.

See Example A-7.

Example A-7. Setting the ${user.install} property in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      ...
      <properties>
        <user.install>${user.dir}/our-project</user.install>
      </properties>
      ...
    </profile>
  </profiles>
  ...
</settings>

The property ${user.install} is accessible from a POM if this profile is active.

Repositories

Repositories are remote collections of projects that Maven uses to populate the local repository of the build system. It is from this local repository that Maven calls its plugins and dependencies. Different remote repositories may contain different projects, and under the active profile they may be searched for a matching release or snapshot artifact. See Example A-8.

Example A-8. Repository configuration in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      ...
      <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>
        ...
      </pluginRepositories>
      ...
    </profile>
  </profiles>
  ...
</settings>

These are the elements:

releases, snapshots: These are the policies for each type of artifact, release or snapshot. With these two sets, a POM has the power to alter the policies for each type independent of the other within a single repository. For example, one may decide to enable only snapshot downloads, possibly for development purposes.
enabled: true or false for whether this repository is enabled for the respective type (releases or snapshots).
updatePolicy: This element specifies how often updates should attempt to occur. Maven will compare the local POMs timestamp to the remote. The choices are: always, daily (default), interval:X (where X is an integer in minutes), or never.
checksumPolicy: When Maven deploys files to the repository, it also deploys corresponding checksum files. Your options are to ignore, fail, or warn on missing or incorrect checksums.
layout: In the earlier description of repositories, we mentioned that they all follow a common layout. This is mostly correct. Maven 2 has a default layout for its repositories; however, Maven 1.x had a different layout. Use this element to specify whether it is default or legacy.

Plugin Repositories

Repositories are home to two major types of artifacts. The first are artifacts that are used as dependencies of other artifacts. These are the majority of plugins that reside within central. The other type of artifact is plugins. Maven plugins are themselves a special type of artifact. Because of this, plugin repositories are separated from other repositories. The structure of the pluginRepositories element block is similar to the repositories element. The pluginRepository elements each specify a remote location where Maven can find new plugins.

Active Profiles

See Example A-9.

Example A-9. Setting active profiles in settings.xml

<settings xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <activeProfiles>
    <activeProfile>env-test</activeProfile>
  </activeProfiles>
</settings>

The final piece of the settings.xml puzzle is the activeProfiles element. This contains a set of activeProfile elements, which each have a value of a profile id. Any profile id defined as an activeProfile will be active, regardless of any environment settings. If no matching profile is found, nothing will happen. For example, if env-test is an activeProfile, a profile in a pom.xml (or profile.xml with a corresponding id), it will be active. If no such profile is found, execution will continue as normal.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.

Table of Contents for A. Settings Details

Create new playlist

Sign In

Sign Up