Начало работы с Alfresco Maven SDK

Jeff Potts, Январь, 2014 ч.2 =>
  • Введение
  • Основные концепции
  • Apache Maven
  • Модульные пакеты Alfresco(AMP)
  • Alfresco Maven SDK
  • Что можно сказать о старом Ant-based SDK?
  • Ваш первый проект
  • Запустим его
  • Что это было?
  • Другие команды для сборки
  • Логирование

Введение

Этот учебник создан для тех людей, которым на проекте необходимо, в некотором роде, настроить Alfresco. И вот вы сначала думаете "Что это за?!". Но в конце вы узнаете:

  • Как создать с нуля проект Альфреско используя Alfresco Maven SDK
  • Что должно произойти в зависимости от ваших настроек
  • Как создать и запустить тестирование
  • Как создать artifact подходящий для встраивания или для того чтобы поделиться им с сообществом

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

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

Основные понятия.

Вам нет необходимости знать слишком много о Maven, Alfresco, или о том зачем нужен этот SDK перед тем как начать использовать его, но отчасти это знание может помочь в чем-то, так что давайте я быстренько проведу вас через основные концепции.

Apache Maven

Apache Maven это иснструмент управления сборкой. Он имеет множество функций, но главная - это экономия времени при выяснении того, на какие зависимости (а также зависимости зависимостей) опирается ваш проект. Maven может получать и кешировать эти зависимости для вас. Если вы когда либо тратили время на установление того, какой JAR файл следует после какого JAR файла, то полезность такого инструмента очевидна.

Модульные пакеты Alfresco(AMP)

AMP это ZIP файл со структурой директорий в соответствии с определенными соглашениями. AMP файлы используются для легкого обмена и развертывания настроек на платформе Alfresco. Если вашему проекту необходимо создание пользовательских настроек на уровне repo (веб-приложение /alfresco) то вы создаете "repo" AMP. Если вашему проекту необходимо создание настроек на уровне Share (веб-приложение /share) вы создаете "share" AMP. Это весьма характерно для проекта - когда требуются изменения в обоих уровнях - вы создаете два AMP.

Alfresco Maven SDK

Сегодняшние программисты привыкли к мощным фреймворкам в которых пустая директория через минуту становится полностью забита файлами и в следующий момент ваш проект уже готов к запуску. Почему разработчики Alfresco должны довольствоваться меньшим?

Задача Maven-based SDK это создание максимально простых условий для начала разработки под Alfresco. SDK состоит из шаблона проекта ("archetype" в терминологии Maven) и некоторых встроенных фишек, которые дают Maven понять как создать AMP и развернуть их на Alfresco.

Если вы пишете свое собственное приложение отдельно от Alfresco-вских и Share-вских WAR, то у вас нет необходимости в Alfresco Maven SDK. Но если вы собираетесь писать код, который работает в любом из этих веб-приложений, Alfresco Maven SDK это то место откуда необходимо начать.

Что можно сказать о старом SDK на основе Ant?

Alfresco предоставлял этот загружаемый SDK с самого начала. SDK содержал ZIP-контейнер с необходимыми для компиляции зависимостями, исходными кодами, документацией, и примерами проектов Eclipse. Эти примеры использовали сборщик на основе Ant.

В таком подходе не было ничего плохого, но платформы разработки эволюционировали, а Ant-овские SDK не смогли эволюционировать вместе с ними. На сегодняшний день части этих примеров устарели (API нативных Web-сервисов, например, или пользовательский интерфейс Alfresco Explorer) и не хватает примеров для чрезвычайно важных частей, таких как CMIS, Web-скрипты, и расширенные рабочие процессы с использованием Activiti.

Помимо своих устаревших примеров, требуется старый Ant-овский SDK. Разработчики делают слишком много работы. С Alfresco Maven SDK, вы даже ничего не загружаете себе - вы просто создаете свой проект и начинаете кодинг.

Теперь вы получили высший уровень понимания Apache Maven, AMP, и Alfresco Maven SDK. Пришло время увидеть это все в действии

Ваш Первый Проект

Давайте я покажу вам как легко можно начать разработку под Alfresco используя Alfresco Maven SDK. Перед тем как начать я должен напомнить вам о необходимости иметь установленный JDK 1.7, так же как и установленные Apache Maven 3. Вам нет необходимости скачивать что-нибудь еще. Серьезно. Даже Alfresco.

  1. Создайте пустой каталог. Скоро мы создадим в нем несколько дополнительных директорий.
  2. Сейчас создадим пустой проект. Предположим вы хотите создать что-то, что вы будете развертывать в репозитории Alfresco, например Пользовательская модель содержимого (content model), несколько пользовательских правил действий (rule actions), новый набор web-скриптов, или какие-то бизнес процессы Activiti. Это действительно не важно. Для создания нового проекта, выполните команду:
    mvn archetype:generate \
    -DarchetypeCatalog=https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml \
    -Dfilter=org.alfresco.maven.archetype:
  3. Maven выполнит некоторую работу и в конечном итоге попросит вас выбрать "archetype". Ваш базовый выбор из библиотек шаблонов проекта. Здесь есть две доступных. Одна называется "alfresco-amp-archetype" и другая "alfresco-allinone-archetype". Наша цель - создать AMP, который может быть развернут в Alfresco, так что первый пункт это то что нам надо. Пишите 1 и жмите Enter.
  4. Сейчас Maven спрашивает вас специфическую версию шаблона на основе которого вы собираетесь создать проект. В настоящее время, последняя версия 1.1.1 которая является пятым вариантом в списке так что жмите 5 и Enter.
  5. Maven спрашивает о groupId. Это похоже на "Java package". Мои примеры всегда основываются на том, что я работаю в вымышленной компании SomeCo, так что я введу "com.someco" здесь. Введите что-то осмысленное для вас и жмите Enter.
  6. Следующее это artifactId. Думайте об этом, как о названии вашего проекта. Это станет также ID вашего AMP так, что выбирайте что-нибудь особенное. Вы должны также добавить строку "-repo" в ваш artifactId потому, что этот модуль будет встраиваться в репозиторий. Я назову свой "someco-mvn-tutorial-repo" и нажму Enter.

  7. В этот момент Maven покажет вам введенные значения, добавит некоторые другие определенные по-умолчанию и попросит вас подтвердить ваш выбор. Если вы захотите изменить что-нибудь, вы можете выбрать "N" и затем внести изменения или "Y" для продолжения. Вы всегда сможете изменить эти значения позже если необходимо. Жмите "Y" и затем Enter.

Сейчас Maven сделает кое-какую работу. Когда он закончит вы получите следующее:

  • Проект, структура которого организована так, как это необходимо для поддержки вашей разработки для Alfresco
  • Дефолтные конфигурационные файлы
  • Минимальный Java-код дополнительных юнит-тестов, чтобы проверить, что все работает
  • Конфигурация необходимая для запуска локального запуска экземпляра Alfresco необходимого для тестирования
  • Дефолтный POM (Project Object Model) XML файл, который сообщает Maven, какие в вашем проекте зависимости

Давайте запустим его

Вы еще не загрузили ничего. Вы еще не редактировали ничего. Все что вы сделали - это сказали Maven о создании проекта на основе шаблона, но у меня отличная новость: ваш проект готов к запуску прямо сейчас.

Попробуйте так:

cd someco-mvn-tutorial-repo
mvn integration-test -Pamp-to-war

Если вы посмотрите вывод, то увидите что Maven загружает все, что необходимо для компиляции проекта, создания AMP, развертывания AMP в Alfresco WAR, развертывания Alfresco WAR в встроенный сервер Tomcat и запуска его. В конце концов вы увидите что-то похожее на:

2014-01-15 18:01:19,339  INFO  [repo.module.ModuleServiceImpl] [localhost-startStop-1] Found 1 module(s).
2014-01-15 18:01:19,480  INFO  [repo.module.ModuleServiceImpl] [localhost-startStop-1] Installing module 'someco-mvn-tutorial-repo' version 1.0.1401151758.

Что означает что модули вашего проекта были сгенерированы и распознаны сервером Alfresco.

После того как увидите:

Jan 16, 2014 8:38:20 AM org.apache.coyote.AbstractProtocol start INFO: Starting ProtocolHandler ["http-bio-8080"]

Вы должны быть в состоянии открыть:

http://localhost:8080/alfresco

И залогиниться используя "admin" и "admin".

Когда закончите любоваться, вернитесь обратно к окну в котором запустили вашу команду для Maven и нажмите ctrl-c для выключения сервера.

Если вы получите ошибку out-of-memory при запуске интеграционного теста, вы возможно должны ввести некоторые параметры JVM для параметров памяти в Maven. Одно из возможных решений это установить переменную окружения MAVEN_OPTS . Для примера, Я установил себе значения в:

-Xmx1024M -XX:MaxPermSize=512m

С помощю MAVEN_OPTS установите столько, чтобы не видеть ошибки переполнения памяти.

Что это было?

Вы запросили Maven о запуске "integration-test" с целью использования профиля "amp-to-war". Это привело к сборке проекта, развертывании его как AMP на свежий Alfresco WAR, и запуска встроенного сервера Tomcat. После этого вы смогли залогиниться в старый клиент Alfresco Explorer поработать с репозиторием тестируя свой модуль.

Если вы посмотрите в конечной (target) директории, то увидите AMP который был создан и впоследствии развернут в Alfresco WAR. В моем случае он называется "someco-mvn-tutorial-repo.amp". Этот файл - то что вы должны дать вашей IT-команде если вы готовы применить ваши изменения уровня репозитория на реальном сервере Alfresco.

Другие команды для Сборки

Вам может быть не всегда необходимо стартовать сервер Alfresco и оставлять его запущенным. Если вы просто хотите собрать проект, запустить юнит-тест и упаковать AMP, вы можете выполнить:

mvn package

Если вы хотите установить AMP внутрь вашего локального репозитория Maven, выполните:

mvn install

Вы возможно заметили, что проект по-умолчанию включает в себя простой юнит-тест. По-умолчанию, Maven будет автоматически запускать юнит-тесты в вашем проекте. Вы сможете увидеть это по выводу в консоли:

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running org.alfresco.demoamp.test.DemoComponentTest

Это хорошая практика, чтобы убедиться, что ваш проект всегда включает в себя юнит-тесты и запускает их каждый раз при сборке. Многие организации используют CI (Continuous Integration, непрерывная интеграция) инструменты, которые зависят от от этих тестов. Если вы по каким либо причинам не хотите запускать тестирование, можете пропустить его, примерно так:

mvn install -DskipTests=true

Если вы захотите удалить все скомпилированные штуки которые Maven создает и начать сначала вы можете выполнить:

mvn clean

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

mvn clean -Ppurge

Теперь вы знаете как создать новый проект Alfresco по шаблону и получили основы сборки с тестами или без. Следующий шаг - научится работать с вашим проектом в IDE.

Логирование

Файл log4j.properties находится в каталоге модулей, файл log4j.properties включает в себя

log4j.logger.org.alfresco.demoamp.DemoComponent=${module.log.level}

Вы наверно захотите заменить это собственными настройками, которые соответствуют структуре вашего пакета.

Для настройки module.log.level вы можете сделать это при запуске Maven, например так:

mvn install -Dmodule.log.level=DEBUG

Или можно отредактировать pom.xml и добавить это в свойства, как-то так:

<module.log.level>DEBUG</module.log.level>

Если вы измените pom.xml, тогда AMP при создании получит эти настройки, и впоследствии, WAR в который развертывается AMP будет писать логи. Это может быть (а может и нет) то, что вы хотите. Если вы не уверены, то возможно лучше установить нужные значения используя командную строку так как это не позволит случайно испортить значения в вашем AMP.

ECM Architect


This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License. ч.2 =>