Образцы Java EE 8

Данное рабочее пространство содержит образцы и модульные тесты Java EE 8. Они распределены по разным каталогам, каждый из которых соответствует определённой технологии/JSR.

Некоторые образцы/тесты имеют документацию, в остальных случаях следует читать код.

Как запустить?

Образцы тестируются на Payara, GlassFish и Tomcat с использованием Arquillian. Arquilian использует профили контейнеров для запуска и развёртывания тестов в отдельных контейнерах.

В данный момент может быть активен только один профиль контейнера, иначе возникнут конфликты зависимостей.

Доступные профили контейнеров:

• Payara и GlassFish

  • payara-ci-managed

    Этот профиль устанавливает сервер Payara и запускает его для каждого образца. Полезен для серверов непрерывной интеграции (CI). Используемую версию Payara можно задать через свойство payara.version. Это профиль по умолчанию, его не нужно указывать явно.

  • payara-micro-managed

    Этот профиль устанавливает Payara Micro и запускает jar для каждого образца. Полезен для CI-серверов. Используемую версию Payara Micro можно задать через свойство payara.micro.version.

  • payara-remote

    Для этого профиля необходимо запустить сервер Payara вне сборки. Каждый образец будет повторно использовать этот экземпляр для выполнения тестов. Полезен при разработке, чтобы избежать затрат на запуск сервера для каждого образца.

    Этот профиль поддерживает некоторые тесты, позволяя задать местоположение, где установлена Payara, через системное свойство glassfishRemote_gfHome. Например:

    -DglassfishRemote_gfHome=/opt/payara173

    Это используется для отправки команд asadmin для создания ресурсов контейнера, таких как пользователи в хранилище идентификаторов.

  • glassfish-embedded

    Данный профиль использует встроенный сервер GlassFish и работает в той же JVM, что и TestClass. Полезен при разработке, но имеет недостаток в виде запуска сервера для каждого образца.

  • glassfish-remote

    Для этого профиля необходимо запустить сервер GlassFish вне сборки. Каждый образец будет повторно использовать этот экземпляр для выполнения тестов. Полезен при разработке, чтобы избежать затрат на запуск сервера для каждого образца.

    Этот профиль поддерживает некоторые тесты, позволяя задать местоположение, где установлен GlassFish, через системное свойство glassfishRemote_gfHome. Например:

    -DglassfishRemote_gfHome=/opt/glassfish50

    Это используется для отправки команд asadmin для создания ресурсов контейнера, таких как пользователи в хранилище идентификаторов.

• Tomcat

  • tomcat-remote

    Для этого профиля необходимо запустить простой сервер Tomcat 9 вне сборки. Каждый образец будет повторно использовать этот экземпляр для выполнения тестов.

    Tomcat поддерживает образцы, использующие Servlet, JSP, язык выражений (EL), WebSocket и JASPIC.

    Для этого профиля требуется включить JMX в Tomcat. Это можно сделать, добавив следующее в [tomcat home]/bin/catalina.sh:

    JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.port=8089 -Dcom.sun.management.jmxremote=true "
    JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.ssl=false "
    JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"
    JAVA_OPTS="$JAVA_OPTS -Djava.rmi.server.hostname=localhost "

    Также для этого профиля необходимо задать имя пользователя (tomcat) и пароль (manager) для приложения управления в файле tomcat-users.xml. Полный пример см. в файле test-utils/src/main/resources/tomcat-users.xml этого репозитория.

    Обратите внимание, что это следует делать только для экземпляра Tomcat, который используется исключительно для тестирования, поскольку вышеизложенное сделает установку Tomcat полностью небезопасной!

  • tomcat-ci-managed

    Этот профиль установит сервер Tomcat и запустит его для каждого образца. Полезен для CI. Используемая версия Tomcat может быть задана через свойство tomcat.version. Переопределение используемой версии, например:

• -Dpayara.version=5.0.0.174

  Это изменит версию с текущей (например, 5.0.0.172) на 5.0.0.173 для целей тестирования Payara.

• -Dglassfish.version=5.0

  Это изменит версию с текущей (например, 5.1.1) на 5.0 для целей тестирования GlassFish.

Чтобы запустить их в консоли, выполните следующие действия:

1. В терминале введите mvn test -fae в корневом каталоге, чтобы запустить тесты для профиля по умолчанию.

При разработке и запуске из IDE не забудьте активировать профиль перед запуском теста.

Чтобы узнать больше об Arquillian, обратитесь к руководствам Arquillian.

Для запуска только подмножества тестов выполните в корневом каталоге следующее:

1. Установите зависимости верхнего уровня: mvn clean install -pl "test-utils" -am.
2. Перейдите в нужный модуль, например: cd cdi.
3. Запустите тесты против нужного сервера, например: mvn clean test -P glassfish-ci-managed.

Как внести свой вклад

С вашей помощью мы можем улучшить этот набор примеров, учиться друг у друга и развивать сообщество, полное увлечённых людей, которые заботятся о технологиях, инновациях и качестве кода. Каждый вклад имеет значение!

Есть несколько вещей, которые вы должны иметь в виду перед отправкой запроса на включение, чтобы мы могли легко включить новые вещи в основную ветку.

Стандартные тесты основаны на jUnit. Имена тестовых классов должны соответствовать стандартам именования surefire: **/*Test.java, **/*Test*.java или **/*TestCase.java.

Для ясности и согласованности, а также для минимизации сложности на начальном этапе мы предпочитаем стандартные тесты jUnit на Java, с дополнительными помощниками HtmlUnit, Hamcrest и, конечно же, Arquillian. Пожалуйста, не используйте альтернативы этим технологиям. Если необходимо ввести новую зависимость в этот проект, она должна предоставлять то, что не покрывается существующими зависимостями.

Некоторые принципы кодирования

• При создании нового исходного файла не добавляйте (или не копируйте) заголовок лицензии, так как мы используем лицензию верхнего уровня (MIT) для каждого файла в этом репозитории.
• Пожалуйста, следуйте профилю форматирования кода JBoss Community, определённому в репозитории jboss/ide-config. Подробности описаны там, а также конфигурации для Eclipse, IntelliJ и NetBeans.

Несколько советов по Git

• Убедитесь, что ваш форк всегда актуален. Просто запустите git pull upstream master, и вы готовы к работе.
• Когда разрабатываете новые функции, создайте ветку функций, чтобы мы плавно включили ваши изменения. Это также удобно для вас, поскольку вы можете работать над несколькими вещами параллельно ;) Чтобы создать ветку функций и переключиться на неё одним махом, вы можете использовать git checkout -b my_new_cool_feature.

Вот и всё! Добро пожаловать в сообщество!

CI Job

Задания CI выполняются Travis. Обратите внимание, что по самой природе представленных здесь примеров вполне нормально, что не все тесты проходят. Обычно это указывает на ошибку на сервере, на котором выполняются образцы. Если вы считаете, что проблема действительно в тесте, отправьте проблему или предоставьте PR с исправлением.

Запуск каждого примера в Docker

• Установите клиент Docker с http://boot2docker.io.

• Соберите образец, который вы хотите запустить.

  mvn clean package -DskipTests

  Например: (обратите внимание, что точного модуля ещё не существует, здесь wip)

  mvn -f jaxrs/jaxrs-client/pom.xml clean package -DskipTests

• Измените вторую строку в Dockerfile, чтобы указать местоположение созданного файла WAR.

• Запустите boot2docker и дайте команду

  docker build -it -p 80:8080 javaee8-sample

• В другой оболочке узнайте IP-адрес работающего контейнера:

  boot2docker ip

• Получите доступ к образцу по адресу http://IP_ADDRESS:80/jaxrs-client/webresources/persons. Точный URL будет отличаться в зависимости от образца.