Глава 33. Плагин Maven.

Работа над этой главой все еще ведется.

Плагин Maven добавляет поддержку для размещения артефактов в хранилищах Maven.

33.1. Использование.

Чтобы использовать плагин Maven, включите следующую строчку в ваш сборочный скрипт:

Пример 33.1. Использование плагина Maven

build.gradle

apply plugin: 'maven'
	  

33.2. Задачи.

Плагин Maven определяет следующие задачи:

Таблица 33.1. Плагин Maven - задачи
Имя задачиЗависит отТипОписание
installВсех задач, которые собирают связанные архивыUploadУстанавливает связанные артефакты в локальный кэш Maven, включая генерацию метаданных. По умолчанию, задача install связана с конфигурацией archives. У этой конфигурации по умолчанию в качестве элемента только jar-архивы. Чтобы узнать больше об установке в локальное хранилище, смотрите Секцию 33.6.3 Установка в локальное хранилище.

33.3. Управление зависимостями.

Плагин Maven не определяет ни одной конфигурации зависимостей.

33.4. Условные свойства.

Таблица 33.2. Плагин Maven - свойства
Имя свойстваТипЗначение по умолчаниюОписание
mavenPomDirFile${project.buildDir}/pomsПапка, куда записываются сгенерированные файлы POM.
conf2ScopeMappingsConf2ScopeMappingContainerнедоступноИнструкции по отображению конфигураций Gradle в границы Maven. Смотрите секцию Отображение зависимостей.

Эти свойства предоставляются условным объектом MavenPluginConvention.

33.5. Условные методы.

Плагин Maven предоставляет фабричный метод создания POM-файлов. Это может быть полезно в том случае, если вам нужен POM-файл без контекста выгрузки в хранилище Maven.

Пример 33.2. Создание автономного POM-файла

build.gradle

task writeNewPom {
    doLast {
        pom {
            project {
                inceptionYear '2008'
                licenses {
                    license {
                        name 'The Apache Software License, Version 2.0'
                        url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
                        distribution 'repo'
                    }
                }
            }
        }.writeTo("$buildDir/newpom.xml")
    }
}
	  

Среди других вещей, Gradle поддерживает тот же синтакс построителя, что и полиглот Maven. Чтобы узнать больше об объекте Gradle Maven POM, смотрите MavenPom. Также смотрите: MavenPluginConvention.

33.6. Взаимодействие с хранилищами Maven.

33.6.1. Введение.

С Gradle вы можете размещать объекты в удаленных хранилищах Maven или устанавливать в ваше локальное хранилище Maven. Это включает в себя все манипуляции с метаданными Maven и также работает для снимков Maven. Фактически, размещение Gradle на сто процентов совместимо с Maven, так как за кулисами используются нативные задачи Maven Ant.

Размещение в хранилище Maven только часть веселья, если у вас нет файла POM. К счастью, Gradle может генерировать POM для вас, используя информацию о зависимостях, которая у него есть.

33.6.2. Размещение в хранилище Maven.

Давайте предположим, что ваш проект выдает всего лишь jar-файл по умолчанию. Теперь вы хотите разместить этот файл в удаленном хранилище Maven.

Пример 33.3. Выгрузка файла в удаленное хранилище Maven

build.gradle

apply plugin: 'maven'

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: "file://localhost/tmp/myRepo/")
        }
    }
}
	  

Вот и все. Вызов задачи uploadArchives, сгенерирует POM-файл и разместит артефакт вместе с POM-файлом в указанном хранилище.

Нужно проделать дополнительную работу, если есть необходимость поддержки протоколов, отличных от file. В этом случае, нативному коду Maven, которому мы передаем управление, требуются дополнительные библиотеки. Какие требуются библиотеки, зависит от протокола, который вы планируете использовать. Доступные протоколы и соответствующие библиотеки перечислены в Таблице 33.3 Jar-файлы протоколов для размещения в Maven (у этих библиотек есть переходные зависимости, у которые есть свои переходные зависимости). Например, для использования протокола ssh, вы можете сделать следующее:

Пример 33.4. Выгрузка файла по SSH

build.gradle

configurations {
    deployerJars
}

repositories {
    mavenCentral()
}

dependencies {
    deployerJars "org.apache.maven.wagon:wagon-ssh:2.2"
}

uploadArchives {
    repositories.mavenDeployer {
        configuration = configurations.deployerJars
        repository(url: "scp://repos.mycompany.com/releases") {
            authentication(userName: "me", password: "myPassword")
        }
    }
}
	  

Есть множество опций конфигурации для MavenDeployer. Настройка совершается посредством построителя Groovy. Все элементы этого дерева - Java beans. Чтобы настроить простые атрибуты, передайте ассоциативный массив элементам bean. В примере выше, repository и authentication - элементы bean. В Таблице 33.4 Конфигурационные элементы MavenDeployer перечислены доступные элементы bean и ссылки на Javadoc соответствующего класса. В Javadoc вы можете увидеть доступные для установки атрибуты для определенного элемента.

В Maven вы можете задать хранилища и необязательные хранилища снимков. Если хранилище снимков не определено, выпуски и снимки размещаются в элемент repository. В противном случае, снимки размещаются в элемент snapshotRepository.

Таблица 33.3 Jar-файлы протоколов для размещения в Maven
ПротоколБиблиотека
httporg.apache.maven.wagon:wagon-http:2.2
sshorg.apache.maven.wagon:wagon-ssh:2.2
ssh-externalorg.apache.maven.wagon:wagon-ssh-external:2.2
ftporg.apache.maven.wagon:wagon-ftp:2.2
webdavorg.apache.maven.wagon:wagon-webdav:1.0-beta-2
file-
Таблица 33.4 Конфигурационные элементы MavenDeployer
ЭлементJavadoc
rootMavenDeployer
repositoryorg.apache.maven.artifact.ant.RemoteRepository
authenticationorg.apache.maven.artifact.ant.Authentication
releasesorg.apache.maven.artifact.ant.RepositoryPolicy
snapshotsorg.apache.maven.artifact.ant.RepositoryPolicy
proxyorg.apache.maven.artifact.ant.Proxy
snapshotRepositoryorg.apache.maven.artifact.ant.RemoteRepository

33.6.3. Установка в локальное хранилище.

Плагин Maven добавляет задачу install к вашему проекту. Эта задача зависит от всех задач архивирования конфигурации archives. Она устанавливает эти архивы в ваше локальное хранилище Maven. Если расположение по умолчанию для локального хранилища переопределено в файле Maven settings.xml, то это учитывается задачей.

33.6.4. Генерация файла Maven POM.

При размещении артефакта в хранилище Maven, Gradle автоматически генерирует POM-файл для него. Для элементов groupId, artifactId, version и packaging, используемых для POM-файла, устанавливаются значения по умолчанию, указанные в таблице ниже. Элементы dependency создаются из объявлений зависимостей проекта.

Таблица 33.5 Значения по умолчанию для генерации файла Maven POM
Элемент MavenЗначение по умолчанию
groupIdproject.group
artifactIduploadTask.repositories.mavenDeployer.pom.artifactId (если установлено) или archiveTask.baseName.
versionproject.version
packagingarchiveTask.extension

Здесь, uploadTask и archiveTask ссылются на задачи, используемые для выгрузки и генерации архивов соответственно (например, uploadArchives и jar). Значение по умолчанию archiveTask.baseName - project.archivesBaseName, у которого, в свою очередь, значение по умолчанию project.name.

Когда вы устанавливаете свойству 'archiveTask.baseName' значение отличное от значения по умолчанию, вы также должны будете установить uploadTask.repositories.mavenDeployer.pom.artifactId то же самое значение. Иначе, на рассматриваемый проект могут ссылаться по неверному идентификатору артефакта из сгенерированных POM-файлов для других проектов в той же самой сборке.

Сгенерированные POM-файлы могут быть найдены в <папкаСборки>/poms. Их можно еще сильнее изменить посредством MavenPom API. Например, вы можете захотеть, чтобы артефакт размещенный в хранилище Maven имел версию или имя отличное от сгенерированного Gradle. Для этого вы можете сделать так:

Пример 33.5. Настройка POM

build.gradle

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: "file://localhost/tmp/myRepo/")
            pom.version = '1.0Maven'
            pom.artifactId = 'myMavenName'
        }
    }
}
	  

Для дополнительного содержимого в POM, можно использовать построитель pom.project. С этим построителем, можно добавить любой элемент перечисленный в справочном руководстве Maven POM.

Пример 33.6. Настройка POM с помощью построителя

build.gradle

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: "file://localhost/tmp/myRepo/")
            pom.project {
                licenses {
                    license {
                        name 'The Apache Software License, Version 2.0'
                        url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
                        distribution 'repo'
                    }
                }
            }
        }
    }
}
	  

Примечание: groupId, artifactId, version и packaging всегда должны быть установлены прямо у объекта pom.

Пример 33.7. Изменение автоматически сгенерированного содержимого

build.gradle

def installer = install.repositories.mavenInstaller
def deployer = uploadArchives.repositories.mavenDeployer

[installer, deployer]*.pom*.whenConfigured {pom ->
    pom.dependencies.find {dep -> dep.groupId == 'group3' && dep.artifactId == 'runtime' }.optional = true
}
	  

Если у больше одного артефакта для публикации, работа идет немного по-другому. Смотрите Секцию Несколько артефактов на проект.

Чтобы изменить настройки установщика Maven (смотрите Секцию 33.6.3 Установка в локальное хранилище), вы можете сделать:

Пример 33.8. Изменение установщика Maven

build.gradle

install {
    repositories.mavenInstaller {
        pom.version = '1.0Maven'
        pom.artifactId = 'myName'
    }
}
	  

Несколько артефактов на проект

Maven может работать только одним артефактом на проект. Это отражено в структуре файла Maven POM. Мы думаем, что есть много ситуаций, где есть смысл иметь более одного артефакта на проект. В таких случаях вам требуется сгенерировать несколько POM-файлов. В таких случая вы должны явно объявить каждый артефакт, который хотите опубликовать в хранилище Maven. И MavenDeployer, и MavenInstaller предоставляют API для этого:

Пример 33.9. Генерация нескольких POM-файлов

build.gradle

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: "file://localhost/tmp/myRepo/")
            addFilter('api') {artifact, file ->
                artifact.name == 'api'
            }
            addFilter('service') {artifact, file ->
                artifact.name == 'service'
            }
            pom('api').version = 'mySpecialMavenVersion'
        }
    }
}
	  

Вам нужно объявить фильтр для каждого артефакта, который хотите опубликовать. В этом фильтре задается булиновское выражение, для каких артефактов Gradle оно принимается. У каждого фильтра есть ассоциированный с ним POM-файл, который вы можете настроить. Чтобы узнать об этом больше, взгляните на PomFilterContainer и связанные с ним классы.

Отображение зависимостей

Плагин Maven настраивает отображение по умолчанию между конфигурациями Gradle, добавленными плагинами Java и War, и границами Maven. Большую часть времени вам не понадобится касаться этого и вы можете спокойно пропустить эту секцию. Отображение работает так. Вы можете отобразить конфигурацию на одну и только одну границу. Различные конфигурации могут отображаться на одну или различные границы. Также вы можете присвоить приоритет определенному отображению конфигурация-в-границу. Чтобы узнать больше, посмотрите на Conf2ScopeMappingContainer. Для обращения к конфигурации отображения, вы можете написать:

Пример 33.10. Обращение к конфигурации отображения

build.gradle

task mappings {
    doLast {
        println conf2ScopeMappings.mappings
    }
}
	  

Правила исключения Gradle преобразуются в искючения Maven, если возможно. Такое преобразование возможно, если в правиле исключения Gradle указана и группа, и имя модуля (так как Maven требуется оба, в противоположность Ivy). Исключения для конфигураций также включаются в Maven POM, если их можно преобразовать.