Создание архетипа Maven из существующего проекта
Создайте архетип из существующего проекта и сгенерируйте новые клоны с минимальными усилиями. Прекратите копи-паст проектов и создайте архетип!
Если вы создаете облако микросервисов или находитесь в среде, где вам нужно сгенерировать несколько проектов или модулей maven, очень полезно создавать архетипы для разработки этих новых модулей/проектов.
Что такое архетип?
Как использовать общий архетип?
Использовать архетип довольно просто. Если вы хотите сгенерировать архетип на основе списка по умолчанию, просто запустите:
Затем выберите один из вариантов, укажите детали и подтвердите. Новый проект уже будет создан.
Как использовать стандартный архетип?
В этом случае нам нужно указать groupId и artifactId архетипа, чтобы иметь возможность использовать настраиваемый. В качестве примера давайте посмотрим на архетип, предоставленный Adobe для AEM:
Как работает архетип?
Внутри архетипа есть все файлы (pom-файл, классы, readme и т. д.) С переменными, которые будут заменены во время генерации проекта. В качестве примера вы можете увидеть эти переменные в нескольких частях файла pom ниже.
В Maven есть хорошая документация, как организовать и создать свой архетип с нуля.
Создание архетипа из проекта
В большинстве случаев поддерживать архетип сложно, потому что:
Это не сам проект, поэтому вам нужно использовать свой архетип, чтобы увидеть, работает ли сгенерированный проект.
Мы ленивы, и если это трудно понять, то будет сложно поддерживать. Люди вернутся к проектам копирования и вставки и заменят текст.
Создайте свой пример проекта для архетипа
Некоторые желательные характеристики в проекте примера для архетипа:
Он должен быть простым, но полным. Не забудьте включить все зависимости и по одному примеру каждого элемента вашего проекта. Например, если проект представляет собой микросервис, имеет смысл включить контроллер, службу и репозиторий.
Включите dot-файлы как часть этого проекта и хороший файл readme.
archetype:create-from-project
В рамках конфигурации вы можете передать файл archetype.properties в качестве параметра. Этот файл свойств должен выглядеть так:
Как вы видите выше, я включил только изменяющуюся часть файлов или переменных, и maven позаботится о их замене за меня.
Шаг-за-шагом
Давайте пройдем все шаги от нашего примера проекта архетипа до нашего архетипа.
1. Переименуйте все dot-файлы.
Известно, что dot-файлы не включаются в архетип. Поэтому нам нужно переименовать их, чтобы они также были включены в сгенерированный архетип (и последующий проект).
2. Вызовите цель maven с желаемыми параметрами.
В документации вы можете увидеть больше параметров и узнать, почему и когда они используются, но вкратце:
-Dinteractive=false : интерактивный режим отключен.
-DkeepParent=true : оставить родителя.
-DpropertyFile=archetype.properties : используйте наш файл archetype.properties для проверки переменных.
-DpackageName=com.almeida.tomas : имя пакета для источников java, который должен быть включен в архетип.
-Darchetype.filteredExtensions=java,xml,md : файлы с выбранными расширениями будут проверены, а содержимое и имя файлов будут изменены переменными.
3. Очистите сгенерированные метаданные архетипа.
В некоторых случаях генерация включает значение свойства по умолчанию, и мы хотим быть уверены, что все значения будут заполнены пользователем.
4. Установите или разверните архетип.
Если вы запускаете эти команды локально, архетип в вашем локальном репо:
Я рекомендую настроить задание Jenkins, чтобы каждый раз, когда в проект вносится изменение, Jenkins запускает команды и отправляет новую версию в ваш репозиторий.
Используйте созданный вами архетип
Теперь нас попросят указать значение для переменных по умолчанию и персонализированных переменных:
Подтвердите, что значения, которые вы ввели, верны:
Необходимо переименовать dot-файлы:
Итак, теперь вы можете создать несколько клонов вашего примера проекта архетипа за считанные минуты!
Apache Maven — основы
После публикации топика о Maven в комментариях возникли вопросы о том, как начать с ним работать, с чего начать, как составлять файлы pom.xml, откуда брать плагины и т.п. Данный топик будет своего рода getting started или f.a.q.
Терминология
Как в любой системе, в Maven, есть свой набор терминов и понятий.
Вся структура проекта описывается в файле pom.xml (POM – Project Object Model), который должен находиться в корневой папке проекта. Ключевым понятием Maven является артефакт — это, по сути, любая библиотека, хранящаяся в репозитории. Это может быть какая-то зависимость или плагин.
Зависимости — это те библиотеки, которые непосредственно используются в вашем проекте для компиляции кода или его тестирования.
Плагины же используются самим Maven’ом при сборке проекта или для каких-то других целей (деплоймент, создание файлов проекта для Eclipse и др.).
В самом начале работы с Maven, пользователь непременно столкнется с таким понятием как архетип. Архетип — это некая стандартная компоновка файлов и каталогов в проектах различного рода (веб, swing-проекты и прочие). Другими словами, Maven знает, как обычно строятся проекты и в соответствии с архетипом создает структуру каталогов.
Как правило, название артефакта состоит из названия группы, собственного названия и версии. К примеру Spring будет иметь вот такое название в среде Maven: org.springframework.spring:2.5.5. Последний домен означает всегда artifactId, все, что перед ним – groupId – хорошо это запомните!
На жизненном цикле останавливаться не буду, так как он хорошо описан в вышеобозначенной статье. А теперь перейдем к практике.
Установка Maven
Последнюю версию всегда можно скачать на странице загрузки на официальном сайте. Просто распаковываем архив в любую директорию. Далее необходимо создать переменную в Path, в которой необходимо указать путь к Maven. Заходим в Win + Pause – Дополнительно – Переменные среды – в верхнем окошке нажимаем Создать, вводим имя M2_HOME и значение допустим “C:\apache-maven-2.2.1”. Далее там же создаем еще одну переменную M2 со значением %M2_HOME%\bin. Так же убеждаемся, что есть переменная JAVA_HOME с путем к JDK. Ее значение должно быть примерно таким «c:\Program Files\Java\jdk1.6.0_10\». И наконец в том же окошке создаем/модифицируем переменную Path, в нее необходимо просто написать %M2%, чтобы наша папочка с исполняемым файлом Maven была видна из командной строки. Теперь необходимо проверить работоспособность нашей установки. Для этого заходим в командную строку и вводим команду
Должна появиться информация о версиях Maven, jre и операционной системе, что-то вроде:
Maven создаст вам локальный репозиторий в вашей личной папке, например в каталоге C:\Documents and Settings\username\.m2\repository
Все, Maven готов к работе, можно приступать к созданию приложения.
Создание приложения из архетипа
На сайте Maven перечислены наиболее популярные архетипы для приложений, но вы можете легко создать свой или найти более специфичный например здесь.
Итак, допустим нас интересует веб-приложение – находим подходящий архетип, называется он maven-archetype-webapp. В командной строке, в необходимом каталоге выполняем команду Maven:
Теперь мы можем лицезреть довольно наглядную структуру каталогов с говорящими названиями java – здесь будут ваши классы, webapp – здесь размещаются странички веб-приложения, resources – различного рода ресурсы в classpath (файлы конфигурации, например), test – юнит-тесты, соответственно и т.п.
Сборка проекта
Здесь все просто – выполняем команду
в корневом каталоге приложения, там, где находится файл pom.xml. Первая команда скомпилирует ваш проект и поместит его в папку target, а вторая еще и положит его к вам в локальный репозиторий.
Есть полезная функция, наподобие конвеера, то есть можно написать
и Maven сначала очистит папку target проекта, потом соберет его и положит в репозиторий.
Минимальный набор действий для работы Maven мы изучили, теперь переходим к кастомизации и добавлению зависимостей проекта.
Зависимости и репозитории
Как правило, большинство популярных библиотек находятся в центральном репозитории, поэтому их можно прописывать сразу в раздел dependencies вашего pom-файла. Например чтобы подключить Spring Framework необходимо определить следующую зависимость:
Версию хотя и можно не указывать и тогда Maven возьмет последний вариант, но я вам лично советую это делать, потому как у нас неоднократно бывали случаи, что проект просто в один момент переставал собираться или начинал падать в совершенно неожиданных и хорошо оттестированных местах, хотя вроде бы никто ничего не менял.
Специфические вещи обычно не находятся в центральном репозитории и тогда вам придется указать репозиторий производителя вручную. Для примера добавим зависимость JSF-фреймворка ajax-компонентов JBoss RichFaces.
С зависимостями все просто:
А вот репозиторий JBoss теперь необходимо прописать ручками либо в файле settings.xml, который лежит в корне вашего локального репозитория, либо в самом файле pom.xml, в зависимости от того, нужен ли данный репозиторий во всех проектах, либо в каком-то одном конкретном, соответственно:
Как правило на сайтах крупных проектов пишут всю информацию, необходимую для встраивания их библиотеки в проект на основе Maven, но бывают случаи, когда артефакт приходится искать очень и очень долго. Здесь нам очень сильно может помочь MVNrepository.com — он вам всегда подскажет где может находиться искомая библиотечка. Но если уж и там не нашлось, то из собственного опыта могу посоветовать гуглить « pom.xml». Бывает так, что проекты уже давно закрыты и в репозитории не положены потому что разработчики уже не заботятся об их распространении. Тогда остается один единственный способ – добавить файл в репозиторий вручную командой:
Последний параметр чаще всего имеет значение jar.
Плагины
Так как плагины являются такими же артефактами, как и зависимости, то они описываются практически так же. Вместо раздела dependencies – plugins, dependency – plugin, repositories – pluginRepositories, repository – pluginRepository.
Плагинами Maven делает все, даже непосредственно то, для чего он затевался – сборку проекта, только этот плагин необязательно указывать в свойствах проекта, если вы не хотите добавить какие-то фичи.
Посмотрим как настроить плагин для создания проекта для Eclipse с использованием WTP ver. 2.0. В раздел plugins нашего pom.xml прописываем следующий плагин:
Теперь идем опять таки в командную строку и выполняем команду
Ждем пока Maven найдет все библиотеки в репозитории или скачает их и вуаля – теперь наш Maven-проект можно открыть как проект eclipse. При этом библиотеки никуда не копируются как при классическом подходе, а остаются в репозитории и Eclipse делает на них ссылку через свои переменные.
Единого списка всех плагинов естественно не существует, на официальном сайте только есть поддерживаемые плагины непосредственно разработчиками Maven. Однако хотелось бы отметить, что названия плагинов довольно прямолинейны и сделав поиск по ключевым словам «maven tomcat plugin» вы скорее всего обнаружите первой ссылкой плагин для деплоймента проекта в Tomcat.
Собственный репозиторий
К сожалению сам не имею большого опыта настройки репозитория, но могу посоветовать как наиболее простой и распространенный Nexus. За дополнительной информацией следует обратиться на сайт данного проекта.
Однако нельзя оставить без внимания и достойных конкурентов в лице Artifactory и Archiva.
Руководство по Maven Archetype
Путеводитель по Maven Archetype
1. обзор
Основным преимуществом использования архетипов является стандартизация разработки проектов и предоставление разработчикам возможности легко следовать передовым методам и быстрее загружать свои проекты.
В этом руководстве мы рассмотрим, как создать собственный архетип, а затем как использовать его для создания проекта Maven с помощьюmaven-archetype-plugin.
2. Дескриптор архетипа Maven
The Maven archetype descriptor is the heart of the archetype project. Это XML-файл с именемarchetype-metadata.xml, расположенный в каталогеMETA-INF/maven jar-файла.
Он используется для описания метаданных архетипов:
ТегrequiredProperties используется для предоставления свойств во время создания проекта. Таким образом, нам будет предложено ввести для них значения с выбором принять значение по умолчанию.
fileSets,, с другой стороны, используются для настройки того, какие ресурсы будут скопированы в конкретный сгенерированный проект. Фильтрованный файл означает, что заполнители будут заменены предоставленными значениями в процессе генерации.
Если мы хотим сгенерировать многомодульный проект, то тегmodules может помочь настроить все модули сгенерированного проекта.
Обратите внимание, что этот файл о Archetype 2 и выше. В версии 1.0.x файл назывался простоarchetype.xml и имел другую структуру.
Для получения дополнительной информации обязательно посмотритеofficial Apache docs.
3. Как создать архетип
An archetype is a normal Maven project with the following extra content:
src/main/resources/META-INF/maven/archetype-metadata.xml: дескриптор, используемый для описания метаданных архетипов
Чтобы создать архетип вручную, мы можем начать с недавно созданного проекта Maven, а затем добавить ресурсы, упомянутые выше.
Или мы можем сгенерировать его, используяarchetype-maven-plugin, and, а затем настроить содержимое каталогаarchetype-resources и файлаarchetype-metadata.xml.
Для генерации архетипа мы можем использовать:
Мы также можем создать архетип из существующего проекта Maven:
Он создается вtarget/generated-sources/archetype, и готов к использованию.
Независимо от того, как мы создавали архетип, в итоге мы получим следующую структуру:
Теперь мы можем начать построение нашего архетипа, поместив ресурсы в каталогarchetype-resources и настроив их в файлеarchetype-metadata.xml.
4. Создание архетипа
Теперь мы готовы настроить наш архетип. В качестве изюминки этого процесса мы собираемся продемонстрировать создание простого архетипа Maven для создания приложения RESTful на основе JAX-RS 2.1.
Назовем это простоmaven-archetype.
4.1. Упаковка архетипа
Начнем с измененияpom.xml of проекта архетипа, расположенного вthe maven-archetype directory:
Этот тип упаковки доступен благодаря расширениюarchetype-packaging:
4.2. Добавлениеpom.xml
Теперь давайте создадим файлpom.xml, расположенный в каталогеarchetype-resources:
Как видим,groupId, artifactId иversion параметризованы. Они будут заменены при создании нового проекта из этого архетипа.
Мы можем поместить все необходимое для сгенерированного проекта, например, зависимости и плагины, вpom.xml. Здесь мы добавили зависимость JAX RS, поскольку архетип будет использоваться для создания приложения на основе RESTful.
4.3. Добавление необходимых ресурсов
Затем мы можем добавить код Java для нашего приложения вarchetype-resources/src/main/java.
Класс для настройки приложения JAX-RS:
И класс для ресурса ping:
Наконец, поместите файл конфигурации сервераserver.xml вarchetype-resources/src/main/config/liberty.
4.4. Настройка метаданных
После добавления всех необходимых ресурсов мы можем теперь настроить, какие из них будут копироваться во время генерации через файлarchetype-metadata.xml.
Мы можем сказать нашему архетипу, что мы хотим, чтобы все исходные файлы Java были скопированы:
Здесь мы хотим, чтобы все файлы Java из каталогаsrc/main/java и файлserver.xml изsrc/main/config/liberty, были скопированы.
4.5. Установка архетипа
Теперь, когда мы закончили собирать все вместе, мы можем установить архетип, вызвав эту команду:
На этом этапе архетип зарегистрирован в файлеarchetype-catalog.xml,, расположенном в локальном репозитории Maven и, следовательно, готов к использованию.
5. Использование установленного архетипа
The maven-archetype-plugin allows the user to create a Maven project through the generate goal and existing archetype. Для получения дополнительной информации об этом плагине вы можете посетитьhomepage.
Эта команда использует этот плагин для генерации проекта Maven из нашего архетипа:
Затем мы должны передать GAV нашего архетипа в качестве аргументов целиmaven-archetype-plugin:generate. Мы также можем передать GAV конкретного проекта, который мы хотим сгенерировать, в противном случае мы можем предоставить их в интерактивном режиме.
Таким образом, созданный конкретный проектcool-jaxrs-sample готов к запуску без каких-либо изменений. Итак, мы можем запустить его, просто вызвав эту команду:
Затем мы можем получить доступ к этому URL:
Создание своих архетипов и каталогов в Maven
Уже довольно продолжительное время (около года набежит) активно пользуюсь системой сборки Apache Maven и вполне ею доволен. Несмотря на свои очевидные и не очень недостатки, неоспоримым преимуществом является автоматическое управление зависимостями, хорошая структурированность проектов и отсутствие скриптов сборки как таковых, а следовательно проблем с ними.
Многим может не нравится, что мавен в самом деле отбирает у разработчика свободу выбора структуры проекта и прямо таки диктует ее, но в самом ли деле эта свобода настолько важна, чтобы делать изза нее жирный аргумент против? Не думаю. Есть другие, более серьезные, на мой взгляд, недостатки, в первую очередь — трудность диагностики проблем при сборке и недостаточная документированность мавена и плагинов.
Был случай на проекте, когда новый член команды не смог собрать билд, получив маловразумительный вывод, что и только после двух часов копания выяснилось, что в поме была прибита пятая версия явы как основная, а она не была установлена.
Поиск плагинов и их настройка — это тоже мучительные круги ада, но по сравнению с xml-программированием на ant’e это еще ничего.
Однако при правильном подходе и набитом скилле, мавен практически не ощущается в работе, что мне очень нравится.
Собственно, в этой статье речь пойдет не о муках, а о архетипах, их каталогах и создании собственных архетипов и каталогов.
С помощью этих нехитрых концепций можно ощутимо упростить себе жизнь при создании нового проекта.
Создаем локальный каталог
Архетип в мавене — это шаблон нового проекта, со структурой и заготовками исходных и конфигурационных файлов.
Любой, кто хотя бы раз создавал проект на мавене, сталкивался с архетипами. Например, типичный метод создания проекта, который витает в интернете:
Вопрос, откуда взять нужные параметры, всегда меня волновал, обычно я вежливо спрашиваю у Гугла и он мне обычно отвечает 🙂
Если мы например, захотим создать простоe приложение, то мы используем архетип под названием maven-archetype-quickstart, например вот так:
Есть более удобный способ создания проекта, с помощью цели archetype:generate. При вызове, в интерактивном режиме будет предложено ввести параметры нового проекта.
Но тут возникает проблема. Мавен предлагает выбрать тип нового проекта из списка готовых шаблонов, а список состоит ни много ни мало из более чем 300 вариантов. Найти там нужный шаблон — задача довольно нетривиальная, обычно я сбрасываю вывод в файл и потом грепом ищу то что нужно.
Погуглив немного, я нашел для себя решение этой проблемы, не совсем как по мне окончательное, но вполне себе с намеком на элегантность. Архетипы можно обьединять в каталоги! Но как это может помочь?
Каталог определяется URL’ом, где он расположен, кроме того в мавене есть три предопределенных каталога, или если хотите, алиаса: internal, remote и local.
| internal | содержит архетипы, встроенные в maven, их немного и они уже де-факто идут с самим дистрибутивом |
| remote | центральный каталог maven, находится по адресу http://repo1.maven.org/maven2/archetype-catalog.xml, его местоположение зависит от текущих настроек мавена, например возможно переопределить этот урл на одно из зеркал репозитория |
| local | каталог из локального репозитория, обычно находится в /.m2/archetype-catalog.xml |
У цели archetype:generate есть параметр archetypeCatalog, с помощью которого можно указать список каталогов, где нужно искать возможные архетипы. По умолчанию, значение параметра ‘remote,local’. Но если убрать оттуда remote, то получим почти то, что нужно.
Подсмотреть структуру файла можно из каталога remote. Например, чтобы получить список выше, файл должен иметь вид
Немного поколдовав с конфигурацией мавена, можно сделать такую ситуацию постоянной, нужно создать профиль, в котором выставить значение переменной archetypeCatalog. Для этого в ваш файл settings.xml нужно добавить
Усе! Теперь, при вызове, цель archetype:generate вместо тонн мусора, будет выводить вам то, что скажете.
К слову у плагина archetype есть любопытная цель crawl, которая сканирует ваш локальный репозиторий на предмет наличия архетипов и генерирует из всех найденных каталог. К сожалению, документация немного врет и по умолчанию файл генерируется совсем не там где ожидает увидеть его мавен. Готовить нужно так:
Вопреки официальной документации параметр называется не catalogFile, а catalog.
Создаем свой архетип
Вторая проблема, которую мы рассмотрим — это создание собственного архетипа. Зачем это нужно? Нужно это по той простой причине, что при всем кажущемся обилии архетипов, среди них не оказалось подходящего для простой веб-разработки. Есть несколько близких по духу, например тот же maven-archetype-webapp, но дескрипторы в нем устаревшие, нету log4j и нормального темплейта jsp. В итогое после создания пустого проекта, нужно перейти в режим работы напильником, и с помощью гугла переделывать все как надо. В конце концов на десятый раз мне это надоело, и я решил создать свой собственный архетип, самый лучший и самый правильный. Более конкретно, создадим заготовку для простенького приложения на spring-mvc c использованием Servlet 2.5/JSP 2.1/JSTL 1.2 c готовым к работе логированием.
Внимание, в следующем абзаце возможно зависание от количества упоминаний слова архетип.
Для начала нужно создать проект для нашего архетипа, используя архетип maven-archetype-archetype, например с помощью того же archetype: сreate.
Чтобы не мучится в консоли, пересядем в эклипс, хотя конечно же все, что написано ниже, можно сделать и с помощью vim’а или еще чегото такого.
После чего делаем импорт и смотрим на структуру более детально.
Проект состоит из одной папки resources, в которой содержися две подпапки: archetype-resources и META-INF. В первой храниться костяк будущих выдающихся проектов, которые еще будут созданы поколениями програмистов после нашей смерти, во второй хранится файлик META-INF/maven/archetype.xml. Это дескриптор архетипа. В нем будет хранится описание того, что входит в архетип.
Дополним костяк, всем чем нужно: добавим туда простенькую jsp страничку, более-менее сносный web.xml, простенький контроллер и конфиг log4j.properties. Все это вы найдете в архиве, который можно скачать. Из интересных моментов, на которые стоит обратить внимание, это замены, которые делает мавен при создании проекта. В архетипе реализован механизм темплейтов на основе Velocity, который практически не документирован, если ктото уверен в обратном, поделитесь, буду благодарен.
В частности в контроллере через темплейты реализована подстановка имени пакета.
Тот же самый ход использован в конфигурации Spring MVC и при генерации целевого pom.xml. Пока что список известных мне переменных довольно скуден: $groupId, $artifactId, $version и $package. Думаю, всем понятно, что каждый значит, все это указывается при создании проекта из архетипа.
Вообще тема темплейтов интересная и нераскрытая, думаю немного погодя раскопаю ее поглубже, а пока то что есть, вполне достаточно для наших скромных нужд.
Когда процесс подготовки шаблонов завершен, нужно подготовить файл-дескриптор архетипа, тот самый archetype.xml.
| src/main/java |
| src/main/resources |
| src/test/java |
| src/test/resources |
| src/site |
После того как все готово, можно установить наш архетип в репозиторий с помощью
и теперь он готов к использованию.
Наш маленький проект готов к запуску
После чего по ссылке http://localhost:8080/baremvcapp можно узреть сие творение.
Теперь архетип, можно сказать приготовлен, добавим его в локальный каталог руками или с помощью цели archetype:crawl.
Теперь при вызове archetype:generate в списке должна появиться строчка
с чем я нас и поздравляю.
В заключение осталось добавить, что описанный выше способ устарел (увы), и помечен как deprecated, но все еще работает, а про right way документации как то кот наплакал. Все что мне пока известно, это что дескриптор изменили, теперь он называется archetype-metadata.xml и имеет более мощный синтаксис. Надеюсь хватит еще на десяток лет вперед статьи писать.
Использованные ресурсы
UPD: Есть еще цель archetype:create-from-project, которая сгенерирует шаблон из вашего проекта. Шаблон сгенерируется в папку target/generated-sources/archetype. То есть фактически из любого вашего проекта можно сгенерировать архетип и потом использовать его в качестве отправной точки. Спасибо 1nd1go