Вступ

Цей підручник створений для тих людей, яким на проекті необхідно до певної міри налаштувати 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 автоматично запускатиме юніт-тести у вашому проекті. Ви зможете побачити це з висновку в консолі:

-------------------------------------------------- -----
 TESTS
-------------------------------------------------- -----
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