Файл settings.xml в Maven

При использовании Maven мы сохраняем большую часть конфигурации для конкретного проекта в файле pom.xml.

Maven предоставляет файл настроек settings.xml, который позволяет указать, какие локальные и удаленные репозитории он будет использовать. Также можно использовать его для хранения настроек, которые не нужны в исходном коде (например, учетные данные).

В этом руководстве узнаем, как использовать файл settings.xml. Рассмотрим прокси, зеркалирование и профили, обсудим, как определить текущие настройки, применимые к проекту.

Конфигурации

Файл settings.xml настраивает установку Maven. Он похож на файл pom.xml, но определяется глобально или для каждого пользователя.

Рассмотрим элементы, которые можно настроить в файле settings.xml. Основной элемент настроек файла settings.xml может содержать девять возможных предопределенных дочерних элементов:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <offline/>
    <pluginGroups/>
    <servers/>
    <mirrors/>
    <proxies/>
    <profiles/>
    <activeProfiles/>
</settings>

Простые значения

Некоторые из элементов конфигурации верхнего уровня содержат простые значения:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository>${user.home}/.m2/repository</localRepository>
    <interactiveMode>true</interactiveMode>
    <offline>false</offline>
</settings>

Элемент localRepository указывает путь к локальному репозиторию системы. В локальном репозитории кэшируются все зависимости из наших проектов. По умолчанию используется домашний каталог пользователя. Однако его можно изменить, чтобы разрешить всем вошедшим в систему пользователям выполнять сборку из общего локального репозитория.

Флаг InteractiveMode определяет, разрешаем ли мы Maven взаимодействовать с пользователем, запрашивающим ввод. Этот флаг по умолчанию имеет значение true.

Флаг автономного режима определяет, может ли система сборки работать в автономном режиме. По умолчанию это значение false; однако можно переключить его на true в тех случаях, когда серверы сборки не могут подключиться к удаленному репозиторию.

Группы плагинов

Элемент pluginGroups содержит список дочерних элементов, указывающих groupId. GroupId – это уникальный идентификатор организации, создавшей определенный артефакт Maven:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <pluginGroups>
        <pluginGroup>org.apache.tomcat.maven</pluginGroup>
    </pluginGroups>
</settings>

Maven выполняет поиск в списке групп подключаемых модулей, если подключаемый модуль используется без идентификатора группы, указанного в командной строке. Список содержит группы org.apache.maven.plugins и org.codehaus.mojo по умолчанию.

Определенный выше файл settings.xml позволяет выполнять усеченные команды подключаемого модуля Tomcat:

mvn tomcat7:help
mvn tomcat7:deploy
mvn tomcat7:run

Proxies

Можно настроить прокси для некоторых или всех HTTP-запросов Maven. Элемент proxies разрешает список дочерних элементов прокси, но одновременно может быть активен только один прокси:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <proxies>
        <proxy>
            <id>baeldung-proxy</id>
            <active>true</active>
            <protocol>http</protocol>
            <host>baeldung.proxy.com</host>
            <port>8080</port>
            <username>demo-user</username>
            <password>dummy-password</password>
            <nonProxyHosts>*.baeldung.com|*.apache.org</nonProxyHosts>
        </proxy>
    </proxies>
</settings>

Определяем текущий активный прокси через флаг active. Затем с помощью элемента nonProxyHosts указываем, какие хосты не проксируются. Используемый разделитель зависит от конкретного прокси-сервера. Наиболее распространенными разделителями являются вертикальная черта и запятая.

Mirrors

Репозитории могут быть объявлены внутри проекта pom.xml. Это означает, что разработчики, совместно использующие код проекта, получают нужные настройки репозитория из коробки.

Можно использовать зеркала в тех случаях, когда хотим определить альтернативное зеркало для определенного репозитория. Это переопределяет то, что находится в pom.xml.

Например, можно заставить Maven использовать один репозиторий, зеркалируя все запросы к репозиторию:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <mirror>
            <id>internal-baeldung-repository</id>
            <name>Baeldung Internal Repo</name>
            <url>https://baeldung.com/repo/maven2/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>
</settings>

Можно определить только одно зеркало для данного репозитория, и Maven выберет первое совпадение. Обычно необходимо использовать официальный репозиторий, распространяемый по всему миру через CDN.

Servers

Определение репозиториев в проекте pom.xml является хорошей практикой. Однако нельзя помещать параметры безопасности, такие как учетные данные, в наш репозиторий исходного кода с файлом pom.xml. Вместо этого определяем эту безопасную информацию в файле settings.xml:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>internal-baeldung-repository</id>
            <username>demo-user</username>
            <password>dummy-password</password>
            <privateKey>${user.home}/.ssh/bael_key</privateKey>
            <passphrase>dummy-passphrase</passphrase>
            <filePermissions>664</filePermissions>
            <directoryPermissions>775</directoryPermissions>
            <configuration></configuration>
        </server>
    </servers>
</settings>

Следует отметить, что ID сервера в settings.xml должен соответствовать элементу ID репозитория, указанному в pom.xml. XML также позволяет использовать заполнители для получения учетных данных из переменных среды.

Profiles

Элемент profiles позволяет создавать несколько дочерних элементов profile, отличающихся своим ID дочернего элемента. Элемент profile в settings.xml представляет собой усеченную версию того же элемента, доступного в pom.xml.

Он может содержать только четыре дочерних элемента: activation, repositories, pluginRepositories и properties. Эти элементы настраивают систему сборки в целом, а не какой-то конкретный проект.

Важно отметить, что значения из активного профиля в settings.xml переопределяют любые эквивалентные значения профиля в файле pom.xml или profiles.xml. Профили сопоставляются по ID.

Activation

Можно использовать профили для изменения определенных значений только при определенных обстоятельствах. Можно указать эти обстоятельства, используя элемент activation. Следовательно, активация профиля происходит при выполнении всех указанных критериев:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>baeldung-test</id>
            <activation>
                <activeByDefault>false</activeByDefault>
                <jdk>1.8</jdk>
                <os>
                    <name>Windows 10</name>
                    <family>Windows</family>
                    <arch>amd64</arch>
                    <version>10.0</version>
                </os>
                <property>
                    <name>mavenVersion</name>
                    <value>3.0.7</value>
                </property>
                <file>
                    <exists>${basedir}/activation-file.properties</exists>
                    <missing>${basedir}/deactivation-file.properties</missing>
                </file>
            </activation>
        </profile>
    </profiles>
</settings>

Есть четыре возможных активатора, и не все из них нужно указывать:

  • jdk: активируется на основе указанной версии JDK (поддерживаются диапазоны);
  • os: активируется на основе свойств операционной системы;
  • property: активирует профиль, если Maven обнаруживает определенное значение property;
  • file: активирует профиль, если данное имя файла существует или отсутствует.

Чтобы проверить, какой профиль активирует определенную сборку, можно использовать плагин help Maven:

mvn help:active-profiles

На выходе будут отображаться текущие активные профили для данного проекта:

[INFO] --- maven-help-plugin:3.2.0:active-profiles (default-cli) @ core-java-streams-3 ---
[INFO]
Active Profiles for Project 'com.baeldung.core-java-modules:core-java-streams-3:jar:0.1.0-SNAPSHOT':
The following profiles are active:
 - baeldung-test (source: com.baeldung.core-java-modules:core-java-streams-3:0.1.0-SNAPSHOT)

Properties

Properties Maven можно рассматривать как именованные заполнители для определенного значения. Значения доступны в файле pom.xml с использованием нотации ${property_name}:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>baeldung-test</id>
            <properties>
                <user.project.folder>${user.home}/baeldung-tutorials</user.project.folder>
            </properties>
        </profile>
    </profiles>
</settings>

В файлах pom.xml доступны четыре различных типа свойств:

  • properties, использующие префикс env, возвращают значение переменной среды, например, ${env.PATH};
  • properties, использующие префикс проекта, возвращают значение свойства, установленное в элементе проекта файла pom.xml, например, ${project.version};
  • properties, использующие префикс settings, возвращают значение соответствующего элемента из settings.xml, например, ${settings.localRepository};
  • можно напрямую ссылаться на все свойства, доступные через метод System.getProperties в Java, например, ${java.home};
  • можно использовать набор свойств внутри элемента properties без префикса, например, ${junit.version}.

Repositories

Удаленные репозитории содержат коллекции артефактов, которые Maven использует для заполнения локального репозитория. Для определенных артефактов могут потребоваться разные удаленные репозитории. Maven ищет репозитории, включенные в активном профиле:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>adobe-public</id>
            <repositories>
	        <repository>
	            <id>adobe-public-releases</id>
	            <name>Adobe Public Repository</name>
	            <url>https://repo.adobe.com/nexus/content/groups/public</url>
	            <releases>
	                <enabled>true</enabled>
	                <updatePolicy>never</updatePolicy>
	            </releases>
	            <snapshots>
	                <enabled>false</enabled>
	            </snapshots>
	        </repository>
	    </repositories>
        </profile>
    </profiles>
</settings>

Можно использовать элемент repository, чтобы включить только release или snapshots артефактов из определенного репозитория.

Репозитории плагинов

Существует два стандартных типа артефактов Maven: зависимости и плагины. Поскольку плагины Maven являются особым типом артефактов, можно отделить репозитории плагинов от других:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>adobe-public</id>
            <pluginRepositories>
               <pluginRepository>
                  <id>adobe-public-releases</id>
                  <name>Adobe Public Repository</name>
                  <url>https://repo.adobe.com/nexus/content/groups/public</url>
                  <releases>
                      <enabled>true</enabled>
                      <updatePolicy>never</updatePolicy>
                  </releases>
                  <snapshots>
                      <enabled>false</enabled>
                  </snapshots>
	        </pluginRepository>
	    </pluginRepositories>
        </profile>
    </profiles>
</settings>

Примечательно, что структура элемента pluginRepositories очень похожа на элемент repositories.

Активные профили

Элемент activeProfiles содержит дочерние элементы, которые относятся к определенному ID профиля. Maven автоматически активирует любой профиль, указанный здесь:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <activeProfiles>
        <activeProfile>baeldung-test</activeProfile>
        <activeProfile>adobe-public</activeProfile>
    </activeProfiles>
</settings>

В этом примере каждый вызов mvn выполняется так, как если бы мы добавили -P baeldung-test,adobe-public в командную строку.

Уровень настроек

Файл settings.xml обычно находится в нескольких местах:

  • глобальные настройки в домашнем каталоге Mavens: ${maven.home}/conf/settings.xml;
  • настройки пользователя в домашнем каталоге пользователя: ${user.home}/.m2/settings.xml.

Если оба файла существуют, их содержимое объединяется. Конфигурации из пользовательских настроек имеют приоритет.

Определение местоположения файла

Чтобы определить расположение глобальных и пользовательских настроек, можно запустить Maven, используя флаг отладки, и искать “settings” в выводе:

$ mvn -X clean | grep "settings"

[DEBUG] Reading global settings from C:\Program Files (x86)\Apache\apache-maven-3.6.3\bin\..\conf\settings.xml
[DEBUG] Reading user settings from C:\Users\Baeldung\.m2\settings.xml

Определение эффективных настроек

Можно использовать плагин help Maven, чтобы узнать содержимое объединенных глобальных и пользовательских настроек:

mvn help:effective-settings

Здесь описывается настройка в формате XML:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository>C:\Users\Baeldung\.m2\repository</localRepository>
    <pluginGroups>
        <pluginGroup>org.apache.tomcat.maven</pluginGroup>
        <pluginGroup>org.apache.maven.plugins</pluginGroup>
        <pluginGroup>org.codehaus.mojo</pluginGroup>
    </pluginGroups>
</settings>

Переопределение местоположения по умолчанию

Maven позволяет переопределить расположение глобальных и пользовательских настроек через командную строку:

$ mvn clean --settings c:\user\user-settings.xml --global-settings c:\user\global-settings.xml

Можно использовать более короткую версию той же команды –s:

$ mvn clean --s c:\user\user-settings.xml --gs c:\user\global-settings.xml

Заключение

В этой статье рассмотрели конфигурации, доступные в файле Maven settings.xml.

Мы научились настраивать прокси, репозитории и профили. Далее рассмотрели разницу между файлами глобальных и пользовательских настроек и то, как определить, какие из них используются.

Наконец, рассмотрели определение используемых эффективных настроек и переопределение расположения файлов по умолчанию.

Оригинал

➜