Глава 46. Быстрый старт Java.

46.1. Плагин Java.

Как мы видели, Gradle - инструмент сборки общего назначения. Он может собрать почти все, что вы сможете реализовать в вашем сборочном скрипте. Из коробки, однаком, он не собирает ничего до тех пор, пока вы не добавите код в ваш сборочный скрипт.

Большинство Java-проектов очень похожи, так как в основе лежит: компиляция исходных кодов Java, запуск каких-либо юнит-тестов и создание jar-файла, содержащего ваши классы. Было бы замечательно, если бы вам не пришлось писать это для каждого проекта. К счастью, вы и не должны. Gradle разрешает эту проблему посредством использования плагинов. Плагин - это расширение Gradle, которое настраивает ваш проект каким-либо способов, обычно добавляя несколько предварительно настроенных задач, которые вместе делают что-то полезное. Вместе с Gradle поставляется множество плагинов и вы сами можете легко написать свой собственный и поделиться им с другими. Один из плагинов - плагин Java. Этот плагин добавляет несколько задач к вашему проекту, которые скомпилируют, выполнят юнит-тесты вашего исходного кода Java и упакуют его в jar-файл.

Плагин Java основан на соглашениях. Это означает, что плагин задает значения по умолчанию для многих аспектов проекта, таких как где расположены исходные файлы Java. Если вы следуете соглашению в вашем проекте, в большинстве случаев вам не придется много писать в вашем сборочном скрипте, чтобы получить полезную сборку. Gradle позволяет настроить ваш проект, если вы не хотите или не можете следовать соглашению в чем-либо. Фактически, так как поддержка проектво Java реализована в виде плагина, вы не обязаны использовать плагин для сборки проекта, если не хотите.

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

46.2. Базовый проект Java.

Давайте посмотрим на простой пример. Чтобы использовать плагин Java, добавьте следующее в ваш сборочный файл:

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

build.gradle

apply plugin: 'java'
	  

Примечание: код этого примера можно найти в папке samples/java/quickstart дистрибутива Gradle '-all'.

Это все что вам надо, чтобы задать проект Java. Этот код применит плагин Java к вашему проекту и добавит несколько задач к нему.

Gradle ожидает, что ваш код будет находиться в папке src/main/java и тестовый код в src/test/java. Дополнительно, все файлы из папки src/main/resources будут включены в jar-файл в качестве ресурсов и все файлы из папки src/test/resources будут включены в путь к классам, используемый для запуска тестов. Все выходные файлы создаются в папке build, а jar-файл будет находиться в папке build/libs.

Какие задачи доступны?

Вы можете использовать gradle tasks, чтобы посмотреть все задачи проекта. Эта команда позволит вам увидеть задачи, которые плагин Java добавил к вашему проекту.

46.2.1. Сборка проекта.

Плагин Java добавляет достаточно много задач к вашему проекту. Однако, существует только несколько задач, которые вам понадобятся, чтобы собрать проект. Самая часто используемая задача - build, которая выполняет полную сборку проекта. Когда вы запустите gradle build, Gradle скомпилирует, протестирует ваш код и создаст jar-файл, содержащий ваши основные классы и ресурсы:

Пример 46.2. Сборка проекта Java

Вывод команды gradle build

> gradle build
:compileJava
:processResources
:classes
:jar
:assemble
:compileTestJava
:processTestResources
:testClasses
:test
:check
:build

BUILD SUCCESSFUL

Total time: 1 secs
	  

Некоторые полезные задачи:

clean

Удаляет папку build и все собранные файлы.

assemble

Компилирует и упаковывает ваш код в jar-файл, но не запускает юнит-тесты. Другие плагины добавляют еще артефактов к этой задаче. Например, если вы используете плагин War, эта задача также соберет war-файл для вашего проекта.

check

Компилирует и тестирует ваш проект. Другие плагины добавляют дополнительные проверки в эту задачу. Например, если вы используете плагин checkstyle, эта задача также запустит Checkstyle для ваших исходных кодов.

46.2.2. Внешние зависимости.

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

Пример 46.3. Добавление хранилища Maven

build.gradle

repositories {
    mavenCentral()
}
	  

Давайте добавим несколько зависимостей. Здесь, мы объявим, что у наших классов есть зависимость времени компиляции от commons-collections и что компиляция наших тестовых классов зависит от junit:

Пример 46.4. Добавление зависимостей

build.gradle

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}
	  

Вы можете узнать больше в Главе 7 Основые управления зависимостями.

46.2.3. Настройка проекта.

Плагин Java добавляет несколько свойств к вашему проекту. У этих свойств есть значения по умолчанию, которых обычно достаточно для начала. Их легко изменить, если они не подходят. Давайте посмотрим на них в нашем примере. Здесь мы укажем номер версии для нашего проекта Java вместе в версией Java под которую написаны наши исходники. Также мы добавим несколько атрибутов в манифест jar.

Пример 46.5. Настройка MANIFEST.MF

build.gradle

sourceCompatibility = 1.7
version = '1.0'
jar {
    manifest {
        attributes 'Implementation-Title': 'Gradle Quickstart',
                   'Implementation-Version': version
    }
}
	  

Задачи, которые добавляет плагин Java - самые обычные, точно такие же, как если бы они были объявлены в сборочном файле. Это означает, что вы можете использовать любой из механизмов, показанных в предыдущих главах, для настройки этих задач. Например, вы можете установить свойства задачи, добавить к ней поведение, изменить зависимости или полностью ее заменить. В нашем примере, мы настроить задачу test, у которой тип Test, добавив системное свойство, когда задача выполняется:

Пример 46.6. Добавление тестового системного свойства

build.gradle

test {
    systemProperties 'property': 'value'
}
	  

Какие свойства доступны?

Вы можете использовать gradle properties для вывода списка свойств проекта. Это дает вам возможность увидеть свойства, добавленные плагином Java, и их значения по умолчанию.

46.2.4. Публикация jar-файла.

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

Пример 46.7. Публикация jar-файла

build.gradle

uploadArchives {
    repositories {
       flatDir {
           dirs 'repos'
       }
    }
}
	  

Для публикации запустите gradle uploadArchives.

46.2.5. Создание проекта Eclipse.

Для создания специфичных для Eclipse файлов описаний, таких как .project, вам надо добавить еще один плагин в ваш сборочнй файл:

Пример 46.8. Плагин Eclipse

build.gradle

apply plugin: 'eclipse'
	  

Теперь выполните команду gradle eclipse для генерации файлов проекта Eclipse. Узнать больше о задаче eclipse можно узнать в Главе 66 Плагины Eclipse.

46.2.6. Резюме.

Вот пример завершенного сборочного файла нашего примера:

Пример 46.9. Пример Java - завершенный сборочный файл

build.gradle

apply plugin: 'java'
apply plugin: 'eclipse'

sourceCompatibility = 1.7
version = '1.0'
jar {
    manifest {
        attributes 'Implementation-Title': 'Gradle Quickstart',
                   'Implementation-Version': version
    }
}

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

test {
    systemProperties 'property': 'value'
}

uploadArchives {
    repositories {
       flatDir {
           dirs 'repos'
       }
    }
}
	  

46.3. Многопроектная сборка Java.

Теперь давайте взглянем на типичную многопроектную сборку. Ниже разметка проекта:

Пример 46.10. Многопроектная сборка - иерархическая разметка

Разметка сборки

multiproject/
  api/
  services/webservice/
  shared/
  services/shared/
	  

Примечание: код этого примера можно найти в папке samples/java/multiproject дистрибутива Gradle '-all'.

Здесь у нас есть четыре проекта. Проект api выдает jar-файл, которые поставляется клиенту, чтобы предоставить ему клиент Java для XML вэб-сервиса. Проект webservice - это вэб-приложение, которое возвращает XML. Проект shared содержит код, используемый api и webservice. В проекте services/shared есть код, который зависит от проекта shared.

46.3.1. Определение многопроектной сборки.

Чтобы определить многопроектную сборку, вам необходимо создать файл настроек. Файл настроек находится в корневой папке дерева исходных кодов и определяет какие проекты включать в сборку. Он должен называться settings.gradle. Для этого примера мы используем простую иерархическую разметку. Вот соответствующий файл настроек:

Пример 46.11. Многопроектная сборка - файл settings.gradle

settings.gradle

include "shared", "api", "services:webservice", "services:shared"
	  

Узнать больше о файле настроек вы можете в Главе 26 Многопроектные сборки.

46.3.2. Общая конфигурация.

В большинстве многопроектных сборок, есть какая-либо конфигурация, которая общая для всех проектов. В нашем примере, мы зададим общую конфигурацию в корневом проекте, с использованием техники под названием внедрение конфигурации. Здесь, корневой проект как контейнер и метод subprojects последовательно проходит по всем элементам этого контейнера - проектам в экземлпяре - и внедряет указанную конфигурацию. Таким способом мы легко можем задать содержимое манифеста для всех архивом и некоторые общие зависимости:

Пример 46.12. Многопроектная сборка - общая конфигурация

build.gradle

subprojects {
    apply plugin: 'java'
    apply plugin: 'eclipse-wtp'

    repositories {
       mavenCentral()
    }

    dependencies {
        testCompile 'junit:junit:4.12'
    }

    version = '1.0'

    jar {
        manifest.attributes provider: 'gradle'
    }
}
	  

Обратите внимание, что наш пример применяет плагин Java к каждому подпроекту. Это означает, что задачи и свойства конфигурации, которые мы видели в прошлой секции, доступны в каждом подпроекте. Так что вы можете компилировать, тестировать и упаковывать в jar все проекте запуском gradle build из корневой папки проекта.

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

46.3.3. Зависимости между проектами.

Вы можете добавить зависимости между проектами в той же самой сборке, так что, например, jar-файл одного проекта будет использоваться для компиляции другого. В сборочном файле проекта api мы добавим зависимость на shared. Из-за этой зависимости, Gradle гарантированного соберет проект shared до api.

Пример 46.13. Многопроектная сборка - зависимости между проектами

api/build.gradle

dependencies {
    compile project(':shared')
}
	  

Чтобы узнать как отключить эту функциональность, смотрите Секцию 26.7.1 Отключение сборки зависимых проектов.

46.3.4. Создание дистрибутива.

Здесь мы создаем дистрибутив, который поставляется клиенту:

Пример 46.14. Многопроектная сборка - файл дистрибутива

api/build.gradle

task dist(type: Zip) {
    dependsOn spiJar
    from 'src/dist'
    into('libs') {
        from spiJar.archivePath
        from configurations.runtime
    }
}

artifacts {
   archives dist
}
	  

46.4. Что дальше.

В этой главе вы увидели как сделать некоторые вещи, которые обычно необходимы для сборки проекта Java. Это глава не исчерпывающая и есть еще много вещей, которые вы можете сделать с проектами Java в Gradle. Вы можете узнать больше о плагине Java в Главе 47 Плагин Java и найти еще примеры проектов Java в папке samples/java в дистрибутиве Gradle.

С другой стороны, вы можете почитать Главу 7 Основы управления зависимостями.