Adempiere: установка среды разработки

Тем, кто хочет научиться программировать на Java сразу приходят в голову вопросы - какие программы написаны на этом языке? Как посмотреть их исходный код? Что можно сделать с помощью Java? В этой статье я покажу программу, которая выполняет функцию ERP-системы, написана на Java и работает в двух режимах: как сервер и как десктопное приложение.
Для новичка установка и развертка среды для разработки Adempier представляет собой тернистый путь. Этот путь усеян множеством кочек, о которых начинающий программист Adempiere обязательно споткнется. В настоящее время я не нашел хорошего примера, который бы показал различные нюансы при установке Adempiere и этим руководством я собираюсь исправить сей факт. Объем получился довольно большим, руководство содержит много иллюстраций. Это руководство хорошо подойдет тем, кто хочет самостоятельно посмотреть, что такое мир Open Source, тем, кто еще только хочет стать программистом Java и начинающим разработчиком. Даже если вы не собираетесь заниматься разработкой для Adempiere, это руководство будет полезным, так как в нем рассматриваются многие темы, так или иначе встречающиеся в профессиональной деятельности разработчика.

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

• Windows 7
• Postgres 9.1
• Adempiere 3.7.0LTS
• JDK 1.6
• Eclipse
• TortoiseHG

Шаг 1. установка СУБД

Сердце Adempiere - это база данных. И здесь важно правильно ее установить. Неприятностей установка может принести немало, если не соблюдать некоторые правила. Так уж получилось, что Adempiere 3.7.0LTS работает без сбоев с базами данных Postgres 9 и выше. За остальные версии - не ручаюсь. Рекомендую ставить последнюю на сегодняшний день Postgres 9.1. Установка происходит очень просто: идете на сайт http://www.postgresql.org/download, скачиваете последнюю версию. Затем запускаете установщик от имени администратора (этот пункт доступен в контекстном меню). Если кто забыл, что такое контекстное меню - нажмите правую кнопку мыши :)
Что произойдет при установке - установщик не только установит СУБД на вашу машину, но и создаст пользователя postgres, для работы с базами данных. Также создаст администратора баз данных postgres и попросит ввести пароль для этого пользователя. Мой совет - делайте пароль postgres. Таким образом вам не нужно будет запоминать какие-либо пароли, это очень облегчает жизнь в разработке.
Также установщик попросит указать порт для доступа к базам данных. По умолчанию это 5432 порт, если он у вас не занят, лучше оставляйте его.

Самое главное - перед установкой назовите компьютер и пользователя администратора ЛАТИНСКИМИ буквами. Не нужно заводить пользователя с киррилическими символами, многие программы чувствительны к присутствию киррилических символов в путях.
Назовите компьютер тоже латинскими буквами. Сделать это можно в свойствах системы, вкладка “Имя компьютера” кнопка “Изменить”.

По окончании установки проверьте, создался ли пользователь postgres. Для этого в командной строке наберите net users. Выведет список всех пользователей, зарегистрированных в системе.

Добавьте переменную POSTGRES_HOME в "Переменные среды", пропишите ей путь. Также добавьте в переменную PATH путь к папке bin в каталоге Postgres. У меня это пути соответсвенно:

• C:\Program Files\PostgreSQL\9.1
• C:\Program Files\PostgreSQL\9.1\bin

На этом этапе лучше перезагрузите компьютер, изменения вступят в силу.

Зачем нужны переменные среды? Это универсальные переменные, которые используются разными программами. Достоинство их в том, что из программы или скрипта достаточно попросить ОС предоставить эту переменную и у нас уже будет ее значение. Это нужно для того чтобы обращаться к разным ресурсам уже установленных программ. Переменная PATH содержит пути к различным программам, благодаря чему в командной строке нам не надо прописывать путь к этим программам полностью, а достаточно лишь ввести их имя.

Проверьте работоспособность Postgres, откройте программу pgAdmin, которая установилась на ваш компьютер вместе с СУБД.

Мы видим, что у нас доступен один сервер localhost, он слушает порт 5432, есть дефолтная база данных postgres (ее не трогаем), есть роль входа postgres. 
Для начала создадим роль adempiere, нам она понадобится в дальнейшем. Щелкаем на "Роли входа" правой кнопкой, создаем новую роль, вводим имя "adempiere", на вкладке "Определения" задаем пароль "adempiere". Готово.
Теперь можете создать базу данных с именем "adempiere" похожим способом, и назначьте владельцем пользователя adempiere.
Выделив базу данных "adempiere" появится кнопка SQL - так вы можете создавать запросы. Потренируйтесь.

Шаг 2. установка Eclipse

Здесь никаких сложностей, идем на сайт  http://www.eclipse.org/ , скачиваем последнюю версию, желательно EE. Инсталятора нет, работает сразу после распаковки. Не спешите запускать, если у вас не установлена java. Добавьте переменную ECLIPSE_HOME и пропишите путь к корневому каталогу Eclipse.

Шаг 3. установка Java

Есть одна особенность - Adempiere работает на версии Java 1.6, поэтому идите на сайт   http://www.oracle.com/technetwork/java/javase/downloads/index.html и качайте Java SE 6 JDK. Ставьте и прописывайте JAVA_HOME и добавляйте в переменную  PATH путь к папке bin.  Если вы знакомы с Java - переходите к следующему шагу.

Мои переменные среды:
JAVA_HOME  - C:\Program Files\Java\jdk1.6.0_34
PATH - ........;C:\Program Files\Java\jdk1.6.0_34\bin

Проверим настроена ли java. Для этого откроем консоль и наберем команду:

java -version
Если нам показали версию, то все в порядке. Помните - переменные среды устанавливаются при загрузке Windows.

Шаг 4. установка TortoiseHG

Скачиваем с http://tortoisehg.bitbucket.org/download/index.html нужную версию и ставим. На мой взгляд - отличная система контроля версий. Существует много различных систем контроля версий, но среди них выделяются пожалуй три: SVN, Git, Mercurial. Для командной разработки система контроля версий необходима, да и при разработке в одиночку они тоже полезны. Вы можете прочитать о них подробно в различных статьях, их нередко сравнивают. Для быстрого ознакомления с системами контроля версий очень хорошо подойдут продукты Tortoise. Они очень удобны в обращении, имеют хороший GUI и быстро настраиваются.

Вам я посоветую обратить внимание на TortoiseHg или TortoiseGit - они являются классом распределенных систем контроля версий.

Ну а для текущей задачи подойдет только Hg.

Шаг 5. установка Adempiere

Началось самое интересное. Для начала создайте папку для adempiere. Я выбрал C:\adempiere. Затем добавьте переменную ADEMPIERE_HOME и пропишите путь к этой папке. Советую перезагрузиться, больше перезагружаться не понадобиться.

Запускаем Eclipse. Нам предлагается сделать Workspace, если вы не имели дело с эклипсом, или недостаточно хорошо его знаете, то советую вам выбрать директорию, в которую можно быстро попасть. Выберите жесткий диск с достаточно большим свободным местом, нам понадобится около 2 ГБ. Я выбрал папку для workspace C:\repositories. Здесь я создам папку adempiere.

Пройдем на сайт http://sourceforge.net/scm/?type=hg&group_id=176962 , там выложен путь, откуда можно сделать клон репозитория. На данный момент это

http://adempiere.hg.sourceforge.net:8000/hgroot/adempiere/adempiere

жмем правой кнопкой на папку adempiere, ищем tortoiseHG -> clone и заполняем поля источник и назначение. Жмем "клонировать". Процесс может занять продолжительное время. В некоторых случаях процесс не завершался - это из-за качества интернета.

В результате репозиторий adempiere будет занимать около 1,5 ГБ. Откройте репозиторий в TortoiseHG Workbench. Должно появиться подобное окно:

Ищем ветку release 3.7.0 , adempierelts. - ревизия 6758 . Выделяем строчку, вызываем контекстное меню, жмем "обновить". Все, у вас есть исходники, поздравляю!

Дальше нам предстоит собрать из исходников Adempiere и запустить его. Вот что у нас получилось:

В нашей директории workspace находится репозиторий Adempiere с нужной нам текущей версией файлов. Запускайте Eclipse, выбирайте пункт меню File->Import->General->Existing project into Workspace. Заполните поле Select root directory.

У вас должен появиться пункт adempiere в поле Projects. Копировать проект в workspace не нужно, он у вас и так там находится. Жмем Finish.

В моей ОС стояла JRE7 - Eclipse подхватил путь к этой машине и теперь в моем проекте после операции Building Workspace, я наблюдаю 100 Java Problems. Это не страшно, там только одна ошибка, которая мешает скомпилировать файл Viewer.java. Вызвана она как раз различиями версий Java.

Добавим в Eclipse JDK6.

Жмем Windows->Preferences. Ищем Java->Installed JREs. Добавляем путь к папке с JDK.

И отмечаем ее в чекбоксе.

Далее настроим Workspace.

Жмем пункт меню Projects->Properties

Выбираем Java Compiler. В правом верхнем углу ссылка Configure Workspace Settings. Давим ее и выбираем JDK Compliance level 1.6.

После применения всех изменений потребуется перекомпиляция файлов проекта. Не беспокойтесь, Eclipse все сделает сам. По окончании нас ждет скомпилированный без ошибок проект. Теперь необходимо его собрать. В папке util_dev есть файл сборщика ant build.xml. Запускаем его как Ant Build.

util_dev -> build.xml -> Run As -> Ant Build

Процесс занимает довольно длительное время - встаньте, приготовьте кофе :)

install:
[echo] =========== Install Adempiere
[copy] Copying 4 files to C:\repositories\adempiere\adempiere\install
[copy] Copying C:\repositories\adempiere\install\build\Adempiere_370LTS.tar.gz to C:\repositories\adempiere\adempiere\install\Adempiere_370LTS.tar.gz
[copy] Copying C:\repositories\adempiere\install\build\Adempiere_370LTS.tar.gz.MD5 to C:\repositories\adempiere\adempiere\install\Adempiere_370LTS.tar.gz.MD5
[copy] Copying C:\repositories\adempiere\install\build\Adempiere_370LTS.zip to C:\repositories\adempiere\adempiere\install\Adempiere_370LTS.zip
[copy] Copying C:\repositories\adempiere\install\build\Adempiere_370LTS.zip.MD5 to C:\repositories\adempiere\adempiere\install\Adempiere_370LTS.zip.MD5
[unzip] Expanding: C:\repositories\adempiere\install\build\Adempiere_370LTS.zip into C:\repositories\adempiere\adempiere
complete:
BUILD SUCCESSFUL
Total time: 7 minutes 57 seconds


То, что вывел нам сборщик перед вами. Нас интересуют сейчас строки раздела install - там находится собранный Adempier.

Идем в папку adempiere/install там есть архив Adempiere_370LTS. Берем его содержимое и помещаем в ADEMPIERE_HOME.

Теперь нам нужно залить дамп базы Adempiere. Он находится в ADEMPIERE_HOME/data/adempiere_pg.dmp

открываем консоль и пишем:

psql -U adempiere -d adempiere -f C:\adempiere\data\Adempiere_pg.dmp >> dump_errors.log


Вас попросят ввести пароль для пользователя adempiere. У меня вывод был в кракозябрах, но все корректно залилось в базу. Теперь в базе adempiere есть схема adempiere. И в ней таблицы, некоторые даже со значениями - это потому, что там находится не только данные о деятельности предприятия, но и необходимые настройки Adempiere, а также есть учебный клиент.

Шаг 6. Запуск Adempiere

Вот мы наконец и добрались до первого запуска. Для начало нужно настроить Adempiere. Запускайте файл RUN_setup.bat из ADEMPIERE_HOME.

Есть кнопка "Проверка" - убедитесь с помощью нее, что вы указали валидные параметры. Обязательно настройте правильно сервер БД. В поле "Пароль System" укажите пароль пользователя postgres. По умолчанию Веб порт стоит 80, у меня он был занят, поэтому поставил 8080. SSL тоже пришлось поменять. Сервер электронной почты не важен.

Жмем "Сохранить" - ждем окончания установки, процесс длительный.

Запустите RUN_Adempiere.bat. Вас могут попросить согласиться с лицензией, отметить какие-то данные, пока не покажут вот такое окно:

Пользователь и пароль одинаковые - вообще все пользователи и их пароли хранятся в базе данных в таблице ad_user. Вам нужно нажать значок базы там, где красная строчка. Появится следующее окно - заполните данные и нажмите "Тестовая база данных". Если появилась зеленая галка - все хорошо, жмите OK во всех окнах.

Вы должны войти в систему:

Отлично, мы убедились, что десктопная версия приложения работает. Теперь проверим, как работает сервер. Для этого запустите из папки utils RUN_Server2.bat. Все необходимые настройки уже сделаны. После появления надписи в консоли

Started in "time"

открывайте браузер и вводите адрес сервера приложения, который писали вначале этого пункта. У меня это anteastra-book:8080

Жмем "Adempiere ZK webUI" и попадаем на форму аутентификации. Дальше интересней - будем узнавать как отлаживать наш Adempiere.

Для запуска в консоли linux я использую команду:

screen -dmS AD ./RUN_Server2.sh


Шаг 7. отладка Desktop приложения

Приведу пример, как можно запустить десктопное приложение для отладки. Во первых нам нужно создать файл "adempiere.proporties". Вот как он выглядит:

#Adempiere #Sun Sep 02 09:26:18 NOVT 2012 SingleInstancePerWindow=xyzN WarningD=Einstellungen_nicht_aendern,_da_diese_undokumentierte_Nebenwirkungen_haben. LoadTabMetaDataBackground=xyzN OpenWindowMaximized=xyzN UILookFeel=xyzAdempiere StorePassword=xyzY DataSource=xyzjava\:adempiereDB CacheWindow=xyzY TempDir=xyzC\:\\Users\\ANTEAS~1\\AppData\\Local\\Temp\\ Warning=Do_not_change_any_of_the_data_as_they_will_have_undocumented_side_effects. ApplicationPassword=xyzGardenAdmin ShowAdvanced=xyzY TraceLevel=xyzWARNING LogMigrationScript=xyzN AdempiereSys=xyzN CDate=xyz2012-09-02 09\:25\:45.254 ShowTrl=xyzN TraceFile=xyzN AutoLogin=xyzN PrintPreview=xyzN ApplicationUserID=xyzGardenAdmin Language=xyz\u0420\u0443\u0441\u0441\u043A\u0438\u0439 (Russian) Charset=xyzUTF-8 ValidateConnectionOnStartup=xyzN AutoNew=xyzN Connection=xyzCConnection[name\=anteastra-book{localhost-adempiere-adempiere},AppsHost\=anteastra-book,AppsPort\=1099,type\=PostgreSQL,DBhost\=localhost,DBport\=5432,DBname\=adempiere,BQ\=false,FW\=false,FWhost\=,FWport\=0,UID\=adempiere,PWD\=adempiere] UITheme=xyzAdempiere Theme AutoCommit=xyzY ShowAcct=xyzY

Его не нужно создавать самому, он генерируется автоматически при сохранении настроек Adempiere. Откройте проект в эклипсе. Жмите Ctrl+Shift+T - теперь вводите в поле поиска "setup". Выбирайте класс из пакета org.compiere.install

Запустите его на исполнение. Перед вами появиться знакомое окно Setup. Сделайте настройки аналогичными из предыдущего шага. Сохраните. Вы получите сообщение о невозможности сделать сборку, не обращайте на него внимания. Вам нужен был файл adempiere.proporties и он создался в папке проекта.

Найдите аналогичным образом класс Adempiere из пакета org.compiere. Выберите опцию Debug configuration.

Вам необходимо передать параметры виртуальной машине.

-DPropertyFile="C:\repositories\adempiere\Adempiere.properties"
-DADEMPIERE_HOME="C:\repositories\adempiere\"

Запускайте debug.

Шаг 8. отладка WEB приложения

Для того, чтобы отлаживать WEB - приложение мы применим другой механизм. JPDA - Java Platform Debugger Architecture (Архитектура отладчика на платформе Java) позволяет запускать отладчик, присоединяясь к уже работающему приложению. Это приложение должно запустится в java-машине с определенными параметрами, чтобы мы могли иметь доступ к отладке. Подробнее информацию можно найти в интернете по ключевым словам "JPDA введение".

Применительно к адемпьеру мы поступим следующим образом: найдите файл %ADEMPIERE_HOME%/AdempiereEnv.proporties, найдите в нем строчку

ADEMPIERE_JAVA_OPTIONS=-Xms64M -Xmx512M

и замените ее на строку

ADEMPIERE_JAVA_OPTIONS=-Xms64M -Xmx512M -server -Xdebug -Xrunjdwp\:transport\=dt_socket,server\=y,suspend\=n,address\=1024

После этого запустите %ADEMPIERE_HOME%/RUN_silentsetup.bat и дождитесь окончания работы скрипта.

Запустите скрипт %ADEMPIERE_HOME%/utils/RUN_Server2.bat должно появиться такое окно:

Обратите внимание, должна появиться надпись:

Listening for transport dt_socket at address: 1024

Это означает, что вы можете подключиться к отладке на порт 1024. Для этого откройте знакомое окно Debug configurations. Создайте новую конфигурацию типа Remote Java Application.

Тип подключения: standart (socket attach)
Хост: anteastra-book (хост на котором доступно ваше приложение)
Port: 1024

Жмите Debug. В окне debug будет отражен стек вызова. Для проверки того, что вы можете прерваться на определенном месте, с помощью комбинации клавиши CTRL+SHIFT+T найдите класс Panel - это базовый класс для отрисовки окон в веб интерфейсе Adempiere. Поставьте брейкпоинт в конструкторе и попробуйти авторизоваться в Adempiere.

Шаг 9. Настройка среды для кастомизации Adempiere

Мы выбрали опен сорсную программу для того, чтобы мы могли изменять код, добавлять программно новые возможности. Конкретно для Adempiere уже предложен механизм добавления нового кода. К адемпьеру при сборке добавляются библиотеки в формате jar. В них содержатся скомпилированные классы Java, посмотреть их можно, открыв библиотеку любым просмотрщиком zip-архивов. Библиотеки, в которые можно добавлять кастомный код так и называются customization.jar и zkcustomization.jar. Для примера мы создадим свою библиотеку zkcustomization.jar.

Для начала создадим новый проект в нашем workspace.

Не забудьте добавить проект adempiere в список required projects:

Теперь постановка задачи: в окне product info изменить заголовок.

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

Выберите любого партнера в поле Buisness partner.

Вот то окно Product Info.

Это же окно доступно из главной панели при клике на пункте View -> Product &Info.

Изменим отрисовку окна Product info.

Для начала найдите класс ProductInfoPanel и скопируйте его в наш проект zkcustom.

Этот класс сразу же скомпилируется, несмотря на множество подключаемых библиотек, которые не содержатся в стандартных библиотеках Java. Это потому что мы добавили проект adempiere в ресурсы проекта zkcustom.

Теперь сделаем сборку библиотеки zkcustomization.jar. Для этого нам понадобится создать файл сборщика ant. Это файл формата xml, поэтому вы можете создать его прямо контекстного меню проекта.

Теперь нам нужно наполнить его инструкциями для сборки. В сети есть много упоминаний о том как составлять инструкции для ant. Вот, например, хороший ресурс: http://www.ibm.com/developerworks/ru/edu/j-apant/index.html

согласно ему я сделал вот такой файл buil.xml:

<?xml version="1.0" encoding="UTF-8"?> <project default="wholeBuild" name="zk customization">      <description>Build zkcustomization.jar for adempiere</description>     <property name="srcDir" location="bin"/> <property name="baseDir" location="./"/>     <target name="init">        <mkdir dir="${baseDir}/tmp/WEB-INF/classes"/>     </target>     <target name="compile" depends="init">         <copy todir="${baseDir}/tmp/WEB-INF/classes">     <fileset dir="${srcDir}">         <include name="**/*"/>        </fileset>     </copy>     </target>     <target name="createJar" depends="compile">         <jar destfile="${baseDir}/zkcustomization.jar" basedir="${baseDir}/tmp"></jar>     </target> <target name="wholeBuild" depends="createJar">     <delete dir="tmp"/> </target> </project>
Если запустить его как сборщик ant, то получим в корне файл zkcustomization.jar - теперь, если мы его скопируем в папку ADEMPIERE_HOME/lib и запустим RUN_silentsetup.bat то получим адемпьер с включенным нашим классом вместо стандартного.

Изменим заголовок окна с помощью метода setTitle()

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

Один интересный момент - если мы подключимся сейчас в режиме debug и начнем менять код во время выполнения программы, то он автоматически подставится в виртуальную машину Java (при условии, что он скомпилировался). Такое поведение называется Hot deployment.

На этом руководство заканчивается. Приятной разработки!