From 465e5a2e7900cdb744740745f3d65a110d6e9962 Mon Sep 17 00:00:00 2001 From: Tomaz Cerar Date: Thu, 14 Dec 2017 01:05:08 +0100 Subject: [PATCH] Add generated docs --- .gitignore | 5 - README.html | 230 +++++++++ README.md | 130 ++++- RELEASE_PROCEDURE.html | 89 ++++ RELEASE_PROCEDURE.md | 2 +- app-client/README.html | 170 +++++++ app-client/README.md | 62 +-- app-client/client-simple/pom.xml | 2 +- app-client/ear/pom.xml | 2 +- app-client/ejb/pom.xml | 2 +- app-client/pom.xml | 2 +- batch-processing/README.html | 135 ++++++ batch-processing/README.md | 32 +- batch-processing/pom.xml | 2 +- bean-validation-custom-constraint/README.html | 75 +++ bean-validation-custom-constraint/README.md | 30 +- bean-validation-custom-constraint/pom.xml | 2 +- bean-validation/README.html | 72 +++ bean-validation/README.md | 32 +- bean-validation/pom.xml | 2 +- bmt/README.html | 78 +++ bmt/README.md | 36 +- bmt/pom.xml | 2 +- cdi-alternative/README.html | 76 +++ cdi-alternative/README.md | 30 +- cdi-alternative/pom.xml | 2 +- cdi-decorator/README.html | 75 +++ cdi-decorator/README.md | 30 +- cdi-decorator/pom.xml | 2 +- cdi-injection/README.html | 61 +++ cdi-injection/README.md | 32 +- cdi-injection/pom.xml | 2 +- cdi-interceptors/README.html | 86 ++++ cdi-interceptors/README.md | 38 +- cdi-interceptors/pom.xml | 2 +- cdi-portable-extension/README.html | 93 ++++ cdi-portable-extension/README.md | 26 +- cdi-portable-extension/pom.xml | 2 +- cdi-stereotype/README.html | 82 ++++ cdi-stereotype/README.md | 36 +- cdi-stereotype/pom.xml | 2 +- cdi-veto/README.html | 80 ++++ cdi-veto/README.md | 30 +- cdi-veto/pom.xml | 2 +- cmt/README.html | 96 ++++ cmt/README.md | 32 +- cmt/pom.xml | 2 +- contacts-jquerymobile/README.html | 165 +++++++ contacts-jquerymobile/README.md | 36 +- contacts-jquerymobile/SERVICES.html | 71 +++ .../functional-tests/pom.xml | 2 +- contacts-jquerymobile/pom.xml | 2 +- dist/pom.xml | 2 +- ejb-asynchronous/README.html | 110 +++++ ejb-asynchronous/README.md | 36 +- ejb-asynchronous/client/pom.xml | 2 +- ejb-asynchronous/ejb/pom.xml | 2 +- ejb-asynchronous/pom.xml | 2 +- ejb-in-ear/README.html | 89 ++++ ejb-in-ear/README.md | 34 +- ejb-in-ear/ear/pom.xml | 2 +- ejb-in-ear/ejb/pom.xml | 2 +- ejb-in-ear/pom.xml | 2 +- ejb-in-ear/web/pom.xml | 2 +- ejb-in-war/README.html | 92 ++++ ejb-in-war/README.md | 36 +- ejb-in-war/pom.xml | 2 +- ejb-multi-server/README.html | 273 +++++++++++ ejb-multi-server/README.md | 72 +-- ejb-multi-server/app-main/ear/pom.xml | 2 +- ejb-multi-server/app-main/ejb/pom.xml | 2 +- ejb-multi-server/app-main/pom.xml | 2 +- ejb-multi-server/app-main/web/pom.xml | 2 +- ejb-multi-server/app-one/ear/pom.xml | 2 +- ejb-multi-server/app-one/ejb/pom.xml | 2 +- ejb-multi-server/app-one/pom.xml | 2 +- ejb-multi-server/app-two/ear/pom.xml | 2 +- ejb-multi-server/app-two/ejb/pom.xml | 2 +- ejb-multi-server/app-two/pom.xml | 2 +- ejb-multi-server/app-web/pom.xml | 2 +- ejb-multi-server/client/pom.xml | 2 +- ejb-multi-server/pom.xml | 2 +- ejb-remote/README.html | 175 +++++++ ejb-remote/README.md | 40 +- ejb-remote/client/pom.xml | 2 +- ejb-remote/pom.xml | 2 +- ejb-remote/server-side/pom.xml | 2 +- ejb-security-context-propagation/README.html | 315 ++++++++++++ ejb-security-context-propagation/README.md | 100 ++-- ejb-security-context-propagation/pom.xml | 2 +- ejb-security-interceptors/README.html | 453 ++++++++++++++++++ ejb-security-interceptors/README.md | 102 ++-- ejb-security-interceptors/pom.xml | 2 +- ejb-security-jaas/README.html | 301 ++++++++++++ ejb-security-jaas/README.md | 88 ++-- ejb-security-jaas/pom.xml | 2 +- ejb-security-programmatic-auth/README.html | 209 ++++++++ ejb-security-programmatic-auth/README.md | 80 ++-- ejb-security-programmatic-auth/pom.xml | 2 +- ejb-security/README.html | 208 ++++++++ ejb-security/README.md | 84 ++-- ejb-security/pom.xml | 2 +- ejb-throws-exception/README.html | 94 ++++ ejb-throws-exception/README.md | 36 +- ejb-throws-exception/ear/pom.xml | 2 +- ejb-throws-exception/ejb-api/pom.xml | 2 +- ejb-throws-exception/ejb/pom.xml | 2 +- ejb-throws-exception/pom.xml | 2 +- ejb-throws-exception/web/pom.xml | 2 +- ejb-timer/README.html | 81 ++++ ejb-timer/README.md | 30 +- ejb-timer/pom.xml | 2 +- forge-from-scratch/README.html | 109 +++++ forge-from-scratch/README.md | 18 +- forge-from-scratch/pom.xml | 2 +- greeter/README.html | 77 +++ greeter/README.md | 36 +- greeter/pom.xml | 2 +- h2-console/README.html | 53 ++ h2-console/README.md | 32 +- h2-console/pom.xml | 2 +- ha-singleton-deployment/README.html | 166 +++++++ ha-singleton-deployment/README.md | 36 +- ha-singleton-deployment/pom.xml | 2 +- ha-singleton-service/README.html | 384 +++++++++++++++ ha-singleton-service/README.md | 76 +-- ha-singleton-service/pom.xml | 2 +- ha-singleton-service/primary-only/pom.xml | 2 +- ha-singleton-service/with-backups/pom.xml | 2 +- helloworld-html5/README.html | 129 +++++ helloworld-html5/README.md | 38 +- helloworld-html5/functional-tests/pom.xml | 2 +- helloworld-html5/pom.xml | 2 +- helloworld-jms/README.html | 209 ++++++++ helloworld-jms/README.md | 74 +-- helloworld-jms/pom.xml | 2 +- helloworld-mbean/README.html | 124 +++++ helloworld-mbean/README.md | 54 +-- .../helloworld-mbean-service/pom.xml | 2 +- .../helloworld-mbean-webapp/pom.xml | 2 +- helloworld-mbean/pom.xml | 2 +- .../README.html | 157 ++++++ helloworld-mdb-propertysubstitution/README.md | 74 +-- helloworld-mdb-propertysubstitution/pom.xml | 2 +- helloworld-mdb/README.html | 86 ++++ helloworld-mdb/README.md | 36 +- helloworld-mdb/pom.xml | 2 +- helloworld-mutual-ssl-secured/README.html | 383 +++++++++++++++ helloworld-mutual-ssl-secured/README.md | 82 ++-- helloworld-mutual-ssl-secured/pom.xml | 2 +- helloworld-mutual-ssl/README.html | 329 +++++++++++++ helloworld-mutual-ssl/README.md | 76 +-- helloworld-mutual-ssl/pom.xml | 2 +- helloworld-rs/README.html | 63 +++ helloworld-rs/README.md | 34 +- helloworld-rs/pom.xml | 2 +- helloworld-singleton/README.html | 63 +++ helloworld-singleton/README.md | 30 +- helloworld-singleton/pom.xml | 2 +- helloworld-ssl/README.html | 202 ++++++++ helloworld-ssl/README.md | 74 +-- helloworld-ssl/pom.xml | 2 +- helloworld-ws/README.html | 98 ++++ helloworld-ws/README.md | 38 +- helloworld-ws/pom.xml | 2 +- helloworld/README.html | 60 +++ helloworld/README.md | 28 +- helloworld/pom.xml | 2 +- hibernate/README.html | 90 ++++ hibernate/README.md | 38 +- hibernate/pom.xml | 2 +- inter-app/README.html | 91 ++++ inter-app/README.md | 52 +- inter-app/appA/pom.xml | 2 +- inter-app/appB/pom.xml | 2 +- inter-app/pom.xml | 2 +- inter-app/shared/pom.xml | 2 +- jaxrs-client/README.html | 134 ++++++ jaxrs-client/README.md | 28 +- jaxrs-client/pom.xml | 2 +- jaxws-addressing/README.html | 105 ++++ jaxws-addressing/README.md | 38 +- jaxws-addressing/client/pom.xml | 2 +- jaxws-addressing/pom.xml | 2 +- jaxws-addressing/service/pom.xml | 2 +- jaxws-ejb/README.html | 110 +++++ jaxws-ejb/README.md | 38 +- jaxws-ejb/client/pom.xml | 2 +- jaxws-ejb/pom.xml | 2 +- jaxws-ejb/service/pom.xml | 2 +- jaxws-pojo/README.html | 102 ++++ jaxws-pojo/README.md | 38 +- jaxws-pojo/client/pom.xml | 2 +- jaxws-pojo/pom.xml | 2 +- jaxws-pojo/service/pom.xml | 2 +- jaxws-retail/README.html | 134 ++++++ jaxws-retail/README.md | 46 +- jaxws-retail/client/pom.xml | 2 +- jaxws-retail/pom.xml | 2 +- jaxws-retail/service/pom.xml | 2 +- jsonp/README.html | 62 +++ jsonp/README.md | 24 +- jsonp/pom.xml | 2 +- jta-crash-rec/README.html | 183 +++++++ jta-crash-rec/README.md | 60 +-- jta-crash-rec/pom.xml | 2 +- jts-distributed-crash-rec/README.html | 235 +++++++++ jts-distributed-crash-rec/README.md | 68 +-- jts-distributed-crash-rec/pom.xml | 2 +- jts/README.html | 269 +++++++++++ jts/README.md | 104 ++-- jts/application-component-1/pom.xml | 2 +- jts/application-component-2/pom.xml | 2 +- jts/pom.xml | 2 +- kitchensink-angularjs/README.html | 105 ++++ kitchensink-angularjs/README.md | 30 +- .../functional-tests/pom.xml | 2 +- kitchensink-angularjs/pom.xml | 2 +- kitchensink-ear/README.html | 112 +++++ kitchensink-ear/README.md | 40 +- kitchensink-ear/ear/pom.xml | 2 +- kitchensink-ear/ejb/pom.xml | 2 +- kitchensink-ear/pom.xml | 2 +- kitchensink-ear/web/pom.xml | 2 +- kitchensink-html5-mobile/README.html | 97 ++++ kitchensink-html5-mobile/README.md | 32 +- kitchensink-html5-mobile/SERVICES.html | 47 ++ kitchensink-html5-mobile/pom.xml | 2 +- kitchensink-jsp/README.html | 85 ++++ kitchensink-jsp/README.md | 40 +- kitchensink-jsp/pom.xml | 2 +- kitchensink-ml-ear/README.html | 200 ++++++++ kitchensink-ml-ear/README.md | 60 +-- kitchensink-ml-ear/ear/pom.xml | 2 +- kitchensink-ml-ear/ejb/pom.xml | 2 +- kitchensink-ml-ear/pom.xml | 2 +- kitchensink-ml-ear/web/pom.xml | 2 +- kitchensink-ml/README.html | 169 +++++++ kitchensink-ml/README.md | 38 +- kitchensink-ml/pom.xml | 2 +- kitchensink/README.html | 80 ++++ kitchensink/README.md | 38 +- kitchensink/pom.xml | 2 +- log4j/README.html | 62 +++ log4j/README.md | 32 +- log4j/pom.xml | 2 +- logging-tools/README.html | 129 +++++ logging-tools/README.md | 54 +-- logging-tools/pom.xml | 2 +- logging/README.html | 268 +++++++++++ logging/README.md | 76 +-- logging/pom.xml | 2 +- mail/README.html | 158 ++++++ mail/README.md | 80 ++-- mail/pom.xml | 2 +- managed-executor-service/README.html | 114 +++++ managed-executor-service/README.md | 26 +- managed-executor-service/pom.xml | 2 +- messaging-clustering-singleton/README.html | 367 ++++++++++++++ messaging-clustering-singleton/README.md | 172 +++---- messaging-clustering-singleton/pom.xml | 2 +- messaging-clustering/README.html | 242 ++++++++++ messaging-clustering/README.md | 114 ++--- messaging-clustering/pom.xml | 2 +- numberguess/README.html | 60 +++ numberguess/README.md | 32 +- numberguess/pom.xml | 2 +- payment-cdi-event/README.html | 94 ++++ payment-cdi-event/README.md | 36 +- payment-cdi-event/pom.xml | 2 +- picketlink-sts/README.html | 204 ++++++++ picketlink-sts/README.md | 72 +-- picketlink-sts/pom.xml | 2 +- pom.xml | 6 +- resteasy-jaxrs-client/README.html | 78 +++ resteasy-jaxrs-client/README.md | 16 +- resteasy-jaxrs-client/pom.xml | 2 +- servlet-async/README.html | 62 +++ servlet-async/README.md | 30 +- servlet-async/pom.xml | 2 +- servlet-filterlistener/README.html | 99 ++++ servlet-filterlistener/README.md | 30 +- servlet-filterlistener/pom.xml | 2 +- servlet-security/README.html | 230 +++++++++ servlet-security/README.md | 72 +-- servlet-security/pom.xml | 2 +- shopping-cart/README.html | 185 +++++++ shopping-cart/README.md | 90 ++-- shopping-cart/client/pom.xml | 2 +- shopping-cart/pom.xml | 2 +- shopping-cart/server/pom.xml | 2 +- shrinkwrap-resolver/README.html | 86 ++++ shrinkwrap-resolver/README.md | 24 +- shrinkwrap-resolver/pom.xml | 2 +- spring-greeter/README.html | 99 ++++ spring-greeter/README.md | 28 +- spring-greeter/functional-tests/pom.xml | 2 +- spring-greeter/pom.xml | 2 +- .../README.html | 98 ++++ .../README.md | 30 +- .../pom.xml | 2 +- spring-kitchensink-basic/README.html | 95 ++++ spring-kitchensink-basic/README.md | 30 +- .../functional-tests/pom.xml | 2 +- spring-kitchensink-basic/pom.xml | 2 +- .../README.html | 99 ++++ spring-kitchensink-controlleradvice/README.md | 30 +- .../functional-tests/pom.xml | 2 +- spring-kitchensink-controlleradvice/pom.xml | 2 +- .../README.html | 105 ++++ spring-kitchensink-matrixvariables/README.md | 30 +- .../functional-tests/pom.xml | 2 +- spring-kitchensink-matrixvariables/pom.xml | 2 +- spring-kitchensink-springmvctest/README.html | 101 ++++ spring-kitchensink-springmvctest/README.md | 30 +- .../functional-tests/pom.xml | 2 +- spring-kitchensink-springmvctest/pom.xml | 2 +- spring-petclinic/CHANGES.html | 21 + spring-petclinic/CHANGES.md | 2 +- spring-petclinic/README.html | 125 +++++ spring-petclinic/README.md | 36 +- spring-petclinic/functional-tests/pom.xml | 2 +- spring-petclinic/pom.xml | 2 +- spring-resteasy/README.html | 90 ++++ spring-resteasy/README.md | 48 +- spring-resteasy/pom.xml | 2 +- tasks-jsf/README.html | 87 ++++ tasks-jsf/README.md | 40 +- tasks-jsf/pom.xml | 2 +- tasks-rs/README.html | 242 ++++++++++ tasks-rs/README.md | 64 +-- tasks-rs/pom.xml | 2 +- tasks/README.html | 89 ++++ tasks/README.md | 32 +- tasks/pom.xml | 2 +- temperature-converter/README.html | 74 +++ temperature-converter/README.md | 30 +- temperature-converter/pom.xml | 2 +- thread-racing/README.html | 78 +++ thread-racing/README.md | 32 +- thread-racing/pom.xml | 2 +- websocket-client/README.html | 76 +++ websocket-client/README.md | 32 +- websocket-client/pom.xml | 2 +- websocket-endpoint/README.html | 65 +++ websocket-endpoint/README.md | 32 +- websocket-endpoint/pom.xml | 2 +- websocket-hello/README.html | 76 +++ websocket-hello/README.md | 34 +- websocket-hello/pom.xml | 2 +- wsat-simple/README.html | 141 ++++++ wsat-simple/README.md | 34 +- wsat-simple/pom.xml | 2 +- .../README.html | 146 ++++++ wsba-coordinator-completion-simple/README.md | 32 +- wsba-coordinator-completion-simple/pom.xml | 2 +- .../README.html | 137 ++++++ wsba-participant-completion-simple/README.md | 32 +- wsba-participant-completion-simple/pom.xml | 2 +- xml-dom4j/README.html | 61 +++ xml-dom4j/README.md | 32 +- xml-dom4j/pom.xml | 2 +- xml-jaxp/README.html | 85 ++++ xml-jaxp/README.md | 34 +- xml-jaxp/pom.xml | 2 +- 365 files changed, 16414 insertions(+), 2459 deletions(-) create mode 100644 README.html create mode 100644 RELEASE_PROCEDURE.html create mode 100644 app-client/README.html create mode 100644 batch-processing/README.html create mode 100644 bean-validation-custom-constraint/README.html create mode 100644 bean-validation/README.html create mode 100644 bmt/README.html create mode 100644 cdi-alternative/README.html create mode 100644 cdi-decorator/README.html create mode 100644 cdi-injection/README.html create mode 100644 cdi-interceptors/README.html create mode 100644 cdi-portable-extension/README.html create mode 100644 cdi-stereotype/README.html create mode 100644 cdi-veto/README.html create mode 100644 cmt/README.html create mode 100644 contacts-jquerymobile/README.html create mode 100644 contacts-jquerymobile/SERVICES.html create mode 100644 ejb-asynchronous/README.html create mode 100644 ejb-in-ear/README.html create mode 100644 ejb-in-war/README.html create mode 100644 ejb-multi-server/README.html create mode 100644 ejb-remote/README.html create mode 100644 ejb-security-context-propagation/README.html create mode 100644 ejb-security-interceptors/README.html create mode 100644 ejb-security-jaas/README.html create mode 100644 ejb-security-programmatic-auth/README.html create mode 100644 ejb-security/README.html create mode 100644 ejb-throws-exception/README.html create mode 100644 ejb-timer/README.html create mode 100644 forge-from-scratch/README.html create mode 100644 greeter/README.html create mode 100644 h2-console/README.html create mode 100644 ha-singleton-deployment/README.html create mode 100644 ha-singleton-service/README.html create mode 100644 helloworld-html5/README.html create mode 100644 helloworld-jms/README.html create mode 100644 helloworld-mbean/README.html create mode 100644 helloworld-mdb-propertysubstitution/README.html create mode 100644 helloworld-mdb/README.html create mode 100644 helloworld-mutual-ssl-secured/README.html create mode 100644 helloworld-mutual-ssl/README.html create mode 100644 helloworld-rs/README.html create mode 100644 helloworld-singleton/README.html create mode 100644 helloworld-ssl/README.html create mode 100644 helloworld-ws/README.html create mode 100644 helloworld/README.html create mode 100644 hibernate/README.html create mode 100644 inter-app/README.html create mode 100644 jaxrs-client/README.html create mode 100644 jaxws-addressing/README.html create mode 100644 jaxws-ejb/README.html create mode 100644 jaxws-pojo/README.html create mode 100644 jaxws-retail/README.html create mode 100644 jsonp/README.html create mode 100644 jta-crash-rec/README.html create mode 100644 jts-distributed-crash-rec/README.html create mode 100644 jts/README.html create mode 100644 kitchensink-angularjs/README.html create mode 100644 kitchensink-ear/README.html create mode 100644 kitchensink-html5-mobile/README.html create mode 100644 kitchensink-html5-mobile/SERVICES.html create mode 100644 kitchensink-jsp/README.html create mode 100644 kitchensink-ml-ear/README.html create mode 100644 kitchensink-ml/README.html create mode 100644 kitchensink/README.html create mode 100644 log4j/README.html create mode 100644 logging-tools/README.html create mode 100644 logging/README.html create mode 100644 mail/README.html create mode 100644 managed-executor-service/README.html create mode 100644 messaging-clustering-singleton/README.html create mode 100644 messaging-clustering/README.html create mode 100644 numberguess/README.html create mode 100644 payment-cdi-event/README.html create mode 100644 picketlink-sts/README.html create mode 100644 resteasy-jaxrs-client/README.html create mode 100644 servlet-async/README.html create mode 100644 servlet-filterlistener/README.html create mode 100644 servlet-security/README.html create mode 100644 shopping-cart/README.html create mode 100644 shrinkwrap-resolver/README.html create mode 100644 spring-greeter/README.html create mode 100644 spring-kitchensink-asyncrequestmapping/README.html create mode 100644 spring-kitchensink-basic/README.html create mode 100644 spring-kitchensink-controlleradvice/README.html create mode 100644 spring-kitchensink-matrixvariables/README.html create mode 100644 spring-kitchensink-springmvctest/README.html create mode 100644 spring-petclinic/CHANGES.html create mode 100644 spring-petclinic/README.html create mode 100644 spring-resteasy/README.html create mode 100644 tasks-jsf/README.html create mode 100644 tasks-rs/README.html create mode 100644 tasks/README.html create mode 100644 temperature-converter/README.html create mode 100644 thread-racing/README.html create mode 100644 websocket-client/README.html create mode 100644 websocket-endpoint/README.html create mode 100644 websocket-hello/README.html create mode 100644 wsat-simple/README.html create mode 100644 wsba-coordinator-completion-simple/README.html create mode 100644 wsba-participant-completion-simple/README.html create mode 100644 xml-dom4j/README.html create mode 100644 xml-jaxp/README.html diff --git a/.gitignore b/.gitignore index 0c226bf576..e66f56ee1c 100644 --- a/.gitignore +++ b/.gitignore @@ -6,11 +6,6 @@ bin */.gitignore .gitkeep /helloworld-jsp -README.html -SERVICES.html -CHANGES.html -CONTRIBUTING.html -RELEASE_PROCEDURE.html out nb-configuration.xml nbactions.xml diff --git a/README.html b/README.html new file mode 100644 index 0000000000..e826c2bd32 --- /dev/null +++ b/README.html @@ -0,0 +1,230 @@ + + + Red Hat JBoss Enterprise Application Platform (JBoss EAP) Quickstarts + + + +

Red Hat JBoss Enterprise Application Platform (JBoss EAP) Quickstarts

+

Summary: The quickstarts demonstrate Java EE 7 and a few additional technologies from the JBoss stack. They provide small, specific, working examples that can be used as a reference for your own project.

+

Introduction

+

These quickstarts run on Red Hat JBoss Enterprise Application Platform 7.1 or later. We recommend using the JBoss EAP ZIP file. This version uses the correct dependencies and ensures you test and compile against your runtime environment.

+

Be sure to read this entire document before you attempt to work with the quickstarts. It contains the following information:

+ +

Use of EAP7_HOME and JBOSS_HOME Variables

+

The quickstart README files use the replaceable value EAP7_HOME to denote the path to the JBoss EAP installation. When you encounter this value in a README file, be sure to replace it with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Available Quickstarts

+

All available quickstarts can be found here: http://www.jboss.org/developer-materials/#!formats=jbossdeveloper_quickstart. You can filter by the quickstart name, the product, and the technologies demonstrated by the quickstart. You can also limit the results based on skill level and date published. The resulting page provides a brief description of each matching quickstart, the skill level, and the technologies used. Click on the quickstart to see more detailed information about how to run it. Some quickstarts require deployment of other quickstarts. This information is noted in the Prerequisites section of the quickstart README file.

+

Note: Some of these quickstarts use the H2 database included with JBoss EAP. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Quickstart Name Demonstrated Technologies Description Experience Level Required Prerequisites
app-client EJB, EAR, AppClient The app-client quickstart demonstrates how to code and package a client app and use the JBoss EAP client container to start the client Main program. Intermediate
batch-processing CDI, Batch 1.0, JSF The batch-processing quickstart shows how to use chunk oriented batch jobs to import a file to a database. Intermediate
bean-validation CDI, JPA, BV The bean-validation quickstart provides Arquillian tests to demonstrate how to use CDI, JPA, and Bean Validation. Beginner
bean-validation-custom-constraint CDI, JPA, BV The bean-validation-custom-constraint quickstart demonstrates how to use the Bean Validation API to define custom constraints and validators. Beginner
bmt EJB, BMT The bmt quickstart demonstrates Bean-Managed Transactions (BMT), showing how to manually manage transaction demarcation while accessing JPA entities. Intermediate
cdi-alternative CDI, Servlet, JSP The cdi-alternative quickstart demonstrates how to create a bean that can be implemented for different purposes without changing the source code. Intermediate
cdi-decorator CDI, JSF The cdi-decorator quickstart demonstrates the use of a CDI Decorator to intercept bean methods and modify the business logic. Intermediate
cdi-injection CDI, JSF The cdi-injection quickstart demonstrates the use of CDI Injection and Qualifiers in JBoss EAP with a JSF front-end client. Beginner
cdi-interceptors JPA, JSF, EJB The cdi-interceptors quickstart demonstrates how to use CDI interceptors for cross-cutting concerns such as logging and simple auditing. Intermediate
cdi-portable-extension CDI The cdi-portable-extension quickstart demonstrates a simple CDI Portable Extension that uses SPI classes to inject beans with data from an XML file. Intermediate
cdi-stereotype JPA, JSF, EJB The cdi-stereotype quickstart demonstrates how to apply CDI stereotypes to beans to encapsulate CDI interceptor bindings and CDI alternatives. Intermediate
cdi-veto CDI The cdi-veto quickstart is a simple CDI Portable Extension that uses SPI classes to show how to remove beans and inject JPA entities into an application. Intermediate
cmt EJB, CMT, JMS The cmt quickstart demonstrates Container-Managed Transactions (CMT), showing how to use transactions managed by the container. Intermediate
contacts-jquerymobile jQuery Mobile, jQuery, JavaScript, HTML5, REST The contacts-jquerymobile quickstart demonstrates a Java EE 7 mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST. Beginner
ejb-asynchronous Asynchronous EJB The ejb-asynchronous quickstart demonstrates the behavior of asynchronous EJB invocations by a deployed EJB and a remote client and how to handle errors. Advanced
ejb-in-ear EJB, EAR The ejb-in-ear quickstart demonstrates how to deploy an EAR archive that contains a JSF WAR and an EJB JAR. Intermediate
ejb-in-war EJB, JSF, WAR The ejb-in-war quickstart demonstrates how to package an EJB bean in a WAR archive and deploy it to JBoss EAP. Arquillian tests are also provided. Intermediate
ejb-multi-server EJB, EAR The ejb-multi-server quickstart shows how to communicate between multiple applications deployed to different servers using an EJB to log the invocation. Advanced
ejb-remote EJB, JNDI The ejb-remote quickstart uses EJB and JNDI to demonstrate how to access an EJB, deployed to JBoss EAP, from a remote Java client application. Intermediate
ejb-security EJB, Security The ejb-security quickstart demonstrates the use of Java EE declarative security to control access to EJBs in JBoss EAP. Intermediate
ejb-security-context-propagation EJB, Security The ejb-security-context-propagation quickstart demonstrates how the security context can be propagated to a remote EJB using a remote outbound connection configuration Advanced
ejb-security-interceptors EJB, Security The ejb-security-interceptors quickstart demonstrates how to use client and server side interceptors to switch the identity for an EJB call. Advanced
ejb-security-jaas EJB, Security The ejb-security-jaas quickstart demonstrates how legacy JAAS security domains can be used in conjunction with Elytron Intermediate
ejb-security-programmatic-auth EJB, Security The ejb-security-programmatic-auth quickstart demonstrates how to programmatically setup different identities when invoking a remote secured EJB. Intermediate
ejb-throws-exception EJB, EAR The ejb-throws-exception quickstart demonstrates how to throw and handle Exceptions across JARs in an EAR. Intermediate
ejb-timer EJB Timer The ejb-timer quickstart demonstrates how to use the EJB timer service @Schedule and @Timeout annotations with JBoss EAP. Beginner
forge-from-scratch Forge The forge-from-scratch quickstart demonstrates how JBoss Forge can generate a Java EE (JPA, EJB, JAX-RS, JSF) web-enabled database application. Intermediate
greeter CDI, JSF, JPA, EJB, JTA The greeter quickstart demonstrates the use of CDI, JPA, JTA, EJB and JSF in JBoss EAP. Beginner
h2-console H2 The h2-console quickstart demonstrates how to use the H2 Console that is bundled with and built specifically for JBoss EAP. Beginner
ha-singleton-deployment EJB, Singleton Deployments, Clustering The ha-singleton-deployment quickstart demonstrates the recommended way to deploy any service packaged in an application archive as a cluster-wide singleton. Advanced
ha-singleton-service MSC, Singleton Service, Clustering The ha-singleton-service quickstart demonstrates how to deploy a cluster-wide singleton MSC service. Advanced
helloworld CDI, Servlet The helloworld quickstart demonstrates the use of CDI and Servlet 3 and is a good starting point to verify JBoss EAP is configured correctly. Beginner
helloworld-html5 CDI, JAX-RS, HTML5 The helloworld-html5 quickstart demonstrates the use of CDI 1.2 and JAX-RS 2.0 using the HTML5 architecture and RESTful services on the backend. Beginner
helloworld-jms JMS The helloworld-jms quickstart demonstrates the use of external JMS clients with JBoss EAP. Intermediate
helloworld-mbean CDI, JMX, MBean The helloworld-mbean quickstart demonstrates the use of CDI and MBean in JBoss EAP and includes JConsole instructions and Arquillian tests. Intermediate
helloworld-mdb JMS, EJB, MDB The helloworld-mdb quickstart uses JMS and EJB Message-Driven Bean (MDB) to create and deploy JMS topic and queue resources in JBoss EAP. Intermediate
helloworld-mdb-propertysubstitution JMS, EJB, MDB The helloworld-mdb-propertysubstitution quickstart demonstrates the use of JMS and EJB MDB, enabling property substitution with annotations. Intermediate
helloworld-mutual-ssl Mutual SSL, Undertow The helloworld-mutual-ssl quickstart is a basic example that demonstrates mutual SSL configuration in JBoss EAP Intermediate
helloworld-mutual-ssl-secured Mutual SSL, Security, Undertow The helloworld-mutual-ssl-secured quickstart demonstrates securing a Web application using client mutual SSL authentication and role-based access control Intermediate
helloworld-rs CDI, JAX-RS The helloworld-rs quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses JAX-RS to say Hello. Intermediate
helloworld-singleton EJB, Singleton The helloworld-singleton quickstart demonstrates an EJB Singleton Bean that is instantiated once and maintains state for the life of the session. Beginner
helloworld-ssl SSL, Undertow The helloworld-ssl quickstart is a basic example that demonstrates server side SSL configuration in JBoss EAP. Beginner
helloworld-ws JAX-WS The helloworld-ws quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses JAX-WS to say Hello. Beginner
hibernate Hibernate The hibernate quickstart demonstrates how to use Hibernate ORM 5 API over JPA, using Hibernate-Core and Hibernate Bean Validation, and EJB. Intermediate
inter-app EJB, CDI, JSF The inter-app quickstart shows you how to use a shared API JAR and an EJB to provide inter-application communication between two WAR deployments. Advanced
jaxrs-client JAX-RS The jaxrs-client quickstart demonstrates JAX-RS Client API, which interacts with a JAX-RS Web service that runs on JBoss EAP. Beginner
jaxws-addressing JAX-WS The jaxws-addressing quickstart is a working example of the web service using WS-Addressing. Beginner
jaxws-ejb JAX-WS The jaxws-ejb quickstart is a working example of the web service endpoint created from an EJB. Beginner
jaxws-pojo JAX-WS The jaxws-pojo quickstart is a working example of the web service endpoint created from a POJO. Beginner
jaxws-retail JAX-WS The jaxws-retail quickstart is a working example of a simple web service endpoint. Beginner
jsonp CDI, JSF, JSON-P The jsonp quickstart demonstrates how to use the JSON-P API to produce object-based structures and then parse and consume them as stream-based JSON strings. Beginner
jta-crash-rec JTA, Crash Recovery The jta-crash-rec quickstart uses JTA and Byteman to show how to code distributed (XA) transactions in order to preserve ACID properties on server crash. Advanced
jts JTS, EJB, JMS The jts quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction. Intermediate cmt
jts-distributed-crash-rec JTS, Crash Recovery The jts-distributed-crash-rec quickstart uses JTS and Byteman to demonstrate distributed crash recovery across multiple application servers. Advanced jts
kitchensink CDI, JSF, JPA, EJB, JAX-RS, BV The kitchensink quickstart demonstrates a Java EE 7 web-enabled database application using JSF, CDI, EJB, JPA, and Bean Validation. Intermediate
kitchensink-angularjs AngularJS, CDI, JPA, EJB, JPA, JAX-RS, BV The kitchensink-angularjs quickstart demonstrates a Java EE 7 application using AngularJS with JAX-RS, CDI, EJB, JPA, and Bean Validation. Intermediate
kitchensink-ear CDI, JSF, JPA, EJB, JAX-RS, BV, EAR The kitchensink-ear quickstart demonstrates web-enabled database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR. Intermediate
kitchensink-html5-mobile CDI, HTML5, REST The kitchensink-html5-mobile quickstart is based on kitchensink, but uses HTML5 and jQuery Mobile, making it suitable for mobile and tablet computers. Beginner
kitchensink-jsp JSP, JSTL, CDI, JPA, EJB, JAX-RS, BV The kitchensink-jsp quickstart demonstrates how to use JSP, JSTL, CDI, EJB, JPA, and Bean Validation in JBoss EAP. Intermediate
kitchensink-ml CDI, JSF, JPA, EJB, JAX-RS, BV, i18n, l10n The kitchensink-ml quickstart demonstrates a localized Java EE 7 compliant application using JSF, CDI, EJB, JPA, and Bean Validation. Intermediate
kitchensink-ml-ear CDI, JSF, JPA, EJB, JAX-RS, BV, EAR, i18n, l10n The kitchensink-ml-ear quickstart demonstrates a localized database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR. Intermediate
log4j JBoss Modules The log4j quickstart demonstrates how to use container defined modules to add dependencies on 3rd party libraries and limit the application package size. Beginner
logging Logging The logging quickstart demonstrates how to configure different logging levels in JBoss EAP. It also includes an asynchronous logging example. Intermediate None
logging-tools JBoss Logging Tools The logging-tools quickstart shows how to use JBoss Logging Tools to create internationalized loggers, exceptions, and messages and localize them. Beginner
mail JavaMail, CDI, JSF The mail quickstart demonstrates how to send email using CDI and JSF and the default Mail provider that ships with JBoss EAP. Beginner
managed-executor-service EE Concurrency Utilities, JAX-RS, JAX-RS Client API The managed-executor-service quickstart demonstrates how Java EE applications can submit tasks for asynchronous execution. Beginner
messaging-clustering JMS, MDB The messaging-clustering quickstart does not contain any code and instead uses the helloworld-mdb quickstart to demonstrate clustering using ActiveMQ Messaging. Intermediate helloworld-mdb
messaging-clustering-singleton JMS, MDB, Clustering The messaging-clustering-singleton quickstart uses a JMS topic and a queue to demonstrate clustering using JBoss EAP messaging with MDB singleton configuration where only one node in the cluster will be active. Advanced
numberguess CDI, JSF The numberguess quickstart demonstrates the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in JBoss EAP. Beginner
payment-cdi-event CDI, JSF The payment-cdi-event quickstart demonstrates how to create credit and debit CDI Events in JBoss EAP, using a JSF front-end client. Beginner
picketlink-sts WS-Trust, SAML The picketlink-sts quickstart demonstrates how to deploy a fully compliant WS-Trust Security Token Service (STS). Advanced
resteasy-jaxrs-client JAX-RS, CDI The resteasy-jaxrs-client quickstart demonstrates an external JAX-RS RestEasy client, which interacts with a JAX-RS Web service that uses CDI and JAX-RS. Intermediate helloworld-rs
servlet-async Asynchronous Servlet, CDI, EJB The servlet-async quickstart demonstrates how to use asynchronous servlets to detach long-running tasks and free up the request processing thread. Intermediate
servlet-filterlistener Servlet Filter, Servlet Listener The servlet-filterlistener quickstart demonstrates how to use Servlet filters and listeners in an application. Intermediate
servlet-security Servlet, Security The servlet-security quickstart demonstrates the use of Java EE declarative security to control access to Servlets and Security in JBoss EAP. Intermediate
shopping-cart SFSB EJB The shopping-cart quickstart demonstrates how to deploy and run a simple Java EE 7 shopping cart application that uses a stateful session bean (SFSB). Intermediate
shrinkwrap-resolver CDI, Arquillian, Shrinkwrap The shrinkwrap-resolver quickstart demonstrates three common use cases for ShrinkWrap Resolver in Red Hat JBoss Enterprise Application Platform. Intermediate
spring-greeter Spring MVC, JSP, JPA The spring-greeter quickstart is based on the greeter quickstart, but differs in that it uses Spring MVC for Mapping GET and POST requests. Beginner
spring-kitchensink-asyncrequestmapping JSP, JPA, JSON, Spring, JUnit The spring-kitchensink-asyncrequestmapping quickstart showcases the use of asynchronous requests is an example using JSP, JPA and Spring 4.x. Intermediate
spring-kitchensink-basic JSP, JPA, JSON, Spring, JUnit The spring-kitchensink-basic quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x. Intermediate
spring-kitchensink-controlleradvice JSP, JPA, JSON, Spring, JUnit The spring-kitchensink-controlleradvice quickstart showcases Spring 4.x's @ControllerAdvice, which was introduced in Spring 3.2. Intermediate
spring-kitchensink-matrixvariables JSP, JPA, JSON, Spring, JUnit The spring-kitchensink-matrixvariables quickstart showcases Spring 4.x's support for Matrix Variables in URLs that was introduced in Spring 3.2. Intermediate
spring-kitchensink-springmvctest JSP, JPA, JSON, Spring, JUnit The spring-kitchensink-springmvctest quickstart demonstrates how to create an MVC application using JSP, JPA and Spring 4.x. Intermediate
spring-petclinic JPA, Junit, JMX, Spring MVC Annotations, AOP, Spring Data, JSP, webjars, Dandellion The spring-petclinic quickstart shows how to run the Spring PetClinic Application in JBoss EAP using the JBoss EAP BOMs. Advanced
spring-resteasy Resteasy, Spring The spring-resteasy quickstart demonstrates how to package and deploy a web application that includes resteasy-spring integration. Beginner
tasks JPA, Arquillian The tasks quickstart includes a persistence unit and sample persistence code to demonstrate how to use JPA for database access in JBoss EAP. Intermediate
tasks-jsf JSF, JPA The tasks-jsf quickstart demonstrates how to use JPA persistence with JSF as the view layer. Intermediate tasks
tasks-rs JPA, JAX-RS The tasks-rs quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence. Intermediate tasks
temperature-converter CDI, JSF, SLSB EJB The temperature-converter quickstart does temperature conversion using an EJB Stateless Session Bean (SLSB), CDI, and a JSF front-end client. Beginner
thread-racing Batch, CDI, EE Concurrency, JAX-RS, JMS, JPA, JSON, Web Sockets A thread racing web application that demonstrates technologies introduced or updated in the latest Java EE specification. Beginner
websocket-client Web Socket, CDI Events, JSON, SSL Demonstrates use of a Javascript WebSocket client, WebSocket configuration, programmatic binding, and secure WebSocket. Intermediate
websocket-endpoint CDI, WebSocket, JSON-P Shows how to use WebSockets with JSON to broadcast information to all open WebSocket sessions in JBoss EAP. Beginner
websocket-hello WebSocket, CDI, JSF The websocket-hello quickstart demonstrates how to create a simple WebSocket application. Beginner
wsat-simple WS-AT, JAX-WS The wsat-simple quickstart demonstrates a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service, bundled as a WAR, and deployed to JBoss EAP. Intermediate
wsba-coordinator-completion-simple WS-BA, JAX-WS The wsba-coordinator-completion-simple quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (CoordinatorCompletion protocol). Intermediate
wsba-participant-completion-simple WS-BA, JAX-WS The wsba-participant-completion-simple quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (ParticipantCompletion Protocol). Intermediate
xml-dom4j DOM4J, Servlet, JSF The xml-dom4j quickstart demonstrates how to use Servlet and JSF to upload an XML file to JBoss EAP and parse it using a 3rd party XML parsing library. Intermediate
xml-jaxp JAXP, SAX, DOM, Servlet The xml-jaxp quickstart demonstrates how to use Servlet and JSF to upload an XML file to JBoss EAP and validate and parse it using DOM or SAX. Intermediate
+

Suggested Approach to the Quickstarts

+

We suggest you approach the quickstarts as follows:

+ +

System Requirements

+

The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the Red Hat JBoss Enterprise Application Platform Documentation Getting Started Guide located on the Customer Portal.

+

You can also use JBoss Developer Studio or Eclipse to run the quickstarts.

+

Run the Quickstarts

+

The root folder of each individual quickstart contains a README file with specific details on how to build and run the example. In most cases you do the following:

+ +

Build and Deploy the Quickstarts

+

See the README file in each individual quickstart folder for specific details and information on how to run and access the example.

+

Build the Quickstart Archive

+

In most cases, you can use the following steps to build the application to test for compile errors or to view the contents of the archive. See the specific quickstart README file for complete details.

+
    +
  1. Open a command prompt and navigate to the root directory of the quickstart you want to build.
    2. +
  2. Use this command if you only want to build the archive, but not deploy it: +
        mvn clean install
+
    +
    3. +
+

Build and Deploy the Quickstart Archive

+

In most cases, you can use the following steps to build and deploy the application. See the specific quickstart README file for complete details.

+
    +
  1. Make sure you start the JBoss EAP server as described in the quickstart README file.
    2. +
  2. Open a command prompt and navigate to the root directory of the quickstart you want to run.
    3. +
  3. Use this command to build and deploy the archive: +
        mvn clean install wildfly:deploy
+
    +
    4. +
+

Undeploy an Archive

+

The command to undeploy the quickstart is simply:

+
    mvn wildfly:undeploy
+
+

Verify the Quickstarts Build with One Command

+

You can verify the quickstarts build using one command. However, quickstarts that have complex dependencies must be skipped. For example, the resteasy-jaxrs-client quickstart is a RESTEasy client that depends on the deployment of the helloworld-rs quickstart. As noted above, the root pom.xml file defines a complex-dependencies profile to exclude these quickstarts from the root build process.

+

To build the quickstarts:

+
    +
  1. Do not start the JBoss EAP server.
    2. +
  2. Open a command prompt and navigate to the root directory of the quickstarts.
    3. +
  3. Use this command to build the quickstarts that do not have complex dependencies: +
        mvn clean install '-Pdefault,!complex-dependencies'
+
    +
    4. +
+

Undeploy the Deployed Quickstarts with One Command

+

To undeploy the quickstarts from the root of the quickstart folder, you must pass the argument -fae (fail at end) on the command line. This allows the command to continue past quickstarts that fail due to complex dependencies and quickstarts that only have Arquillian tests and do not deploy archives to the server.

+

You can undeploy quickstarts using the following procedure:

+
    +
  1. Start the JBoss EAP server.
    2. +
  2. Open a command prompt and navigate to the root directory of the quickstarts.
    3. +
  3. Use this command to undeploy any deployed quickstarts: +
        mvn wildfly:undeploy -fae
+
    +
    4. +
+

To undeploy any quickstarts that fail due to complex dependencies, follow the undeploy procedure described in the quickstart's README file.

+

Run the Quickstarts in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Optional Components

+

The following components are needed for only a small subset of the quickstarts. Do not install or configure them unless the quickstart requires it.

+ + + \ No newline at end of file diff --git a/README.md b/README.md index 5e680ed6c7..05abab0c64 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -# ${product.name.full} (${product.name}) Quickstarts +# Red Hat JBoss Enterprise Application Platform (JBoss EAP) Quickstarts Summary: The quickstarts demonstrate Java EE 7 and a few additional technologies from the JBoss stack. They provide small, specific, working examples that can be used as a reference for your own project. ## Introduction -These quickstarts run on ${product.name.full} ${product.version} or later. We recommend using the ${product.name} ZIP file. This version uses the correct dependencies and ensures you test and compile against your runtime environment. +These quickstarts run on Red Hat JBoss Enterprise Application Platform 7.1 or later. We recommend using the JBoss EAP ZIP file. This version uses the correct dependencies and ensures you test and compile against your runtime environment. Be sure to read this entire document before you attempt to work with the quickstarts. It contains the following information: @@ -25,20 +25,120 @@ Be sure to read this entire document before you attempt to work with the quickst * [Contributing Guide](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONTRIBUTING.md#jboss-developer-contributing-guide): This document contains information targeted for developers who want to contribute to JBoss developer projects. -## Use of ${jboss.home.name} and JBOSS_HOME Variables +## Use of EAP7_HOME and JBOSS_HOME Variables -The quickstart README files use the *replaceable* value `${jboss.home.name}` to denote the path to the ${product.name} installation. When you encounter this value in a README file, be sure to replace it with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +The quickstart README files use the *replaceable* value `EAP7_HOME` to denote the path to the JBoss EAP installation. When you encounter this value in a README file, be sure to replace it with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Available Quickstarts All available quickstarts can be found here: . You can filter by the quickstart name, the product, and the technologies demonstrated by the quickstart. You can also limit the results based on skill level and date published. The resulting page provides a brief description of each matching quickstart, the skill level, and the technologies used. Click on the quickstart to see more detailed information about how to run it. Some quickstarts require deployment of other quickstarts. This information is noted in the `Prerequisites` section of the quickstart README file. -_Note_: Some of these quickstarts use the H2 database included with ${product.name}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment! +_Note_: Some of these quickstarts use the H2 database included with JBoss EAP. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment! + + +| *Quickstart Name* | *Demonstrated Technologies* | *Description* | *Experience Level Required* | *Prerequisites* | +| --- | --- | --- | --- | --- | +| [app-client](app-client/README.md) |EJB, EAR, AppClient | The `app-client` quickstart demonstrates how to code and package a client app and use the JBoss EAP client container to start the client Main program. | Intermediate | | +| [batch-processing](batch-processing/README.md) |CDI, Batch 1.0, JSF | The `batch-processing` quickstart shows how to use chunk oriented batch jobs to import a file to a database. | Intermediate | | +| [bean-validation](bean-validation/README.md) |CDI, JPA, BV | The `bean-validation` quickstart provides Arquillian tests to demonstrate how to use CDI, JPA, and Bean Validation. | Beginner | | +| [bean-validation-custom-constraint](bean-validation-custom-constraint/README.md) |CDI, JPA, BV | The `bean-validation-custom-constraint` quickstart demonstrates how to use the Bean Validation API to define custom constraints and validators. | Beginner | | +| [bmt](bmt/README.md) |EJB, BMT | The `bmt` quickstart demonstrates Bean-Managed Transactions (BMT), showing how to manually manage transaction demarcation while accessing JPA entities. | Intermediate | | +| [cdi-alternative](cdi-alternative/README.md) |CDI, Servlet, JSP | The `cdi-alternative` quickstart demonstrates how to create a bean that can be implemented for different purposes without changing the source code. | Intermediate | | +| [cdi-decorator](cdi-decorator/README.md) |CDI, JSF | The `cdi-decorator` quickstart demonstrates the use of a CDI Decorator to intercept bean methods and modify the business logic. | Intermediate | | +| [cdi-injection](cdi-injection/README.md) |CDI, JSF | The `cdi-injection` quickstart demonstrates the use of *CDI Injection and Qualifiers* in JBoss EAP with a JSF front-end client. | Beginner | | +| [cdi-interceptors](cdi-interceptors/README.md) |JPA, JSF, EJB | The `cdi-interceptors` quickstart demonstrates how to use CDI interceptors for cross-cutting concerns such as logging and simple auditing. | Intermediate | | +| [cdi-portable-extension](cdi-portable-extension/README.md) |CDI | The `cdi-portable-extension` quickstart demonstrates a simple CDI Portable Extension that uses SPI classes to inject beans with data from an XML file. | Intermediate | | +| [cdi-stereotype](cdi-stereotype/README.md) |JPA, JSF, EJB | The `cdi-stereotype` quickstart demonstrates how to apply CDI stereotypes to beans to encapsulate CDI interceptor bindings and CDI alternatives. | Intermediate | | +| [cdi-veto](cdi-veto/README.md) |CDI | The `cdi-veto` quickstart is a simple CDI Portable Extension that uses SPI classes to show how to remove beans and inject JPA entities into an application. | Intermediate | | +| [cmt](cmt/README.md) |EJB, CMT, JMS | The `cmt` quickstart demonstrates Container-Managed Transactions (CMT), showing how to use transactions managed by the container. | Intermediate | | +| [contacts-jquerymobile](contacts-jquerymobile/README.md) |jQuery Mobile, jQuery, JavaScript, HTML5, REST | The `contacts-jquerymobile` quickstart demonstrates a Java EE 7 mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST. | Beginner | | +| [ejb-asynchronous](ejb-asynchronous/README.md) |Asynchronous EJB | The `ejb-asynchronous` quickstart demonstrates the behavior of asynchronous EJB invocations by a deployed EJB and a remote client and how to handle errors. | Advanced | | +| [ejb-in-ear](ejb-in-ear/README.md) |EJB, EAR | The `ejb-in-ear` quickstart demonstrates how to deploy an EAR archive that contains a *JSF* WAR and an *EJB* JAR. | Intermediate | | +| [ejb-in-war](ejb-in-war/README.md) |EJB, JSF, WAR | The `ejb-in-war` quickstart demonstrates how to package an *EJB* bean in a WAR archive and deploy it to JBoss EAP. Arquillian tests are also provided. | Intermediate | | +| [ejb-multi-server](ejb-multi-server/README.md) |EJB, EAR | The `ejb-multi-server` quickstart shows how to communicate between multiple applications deployed to different servers using an EJB to log the invocation. | Advanced | | +| [ejb-remote](ejb-remote/README.md) |EJB, JNDI | The `ejb-remote` quickstart uses *EJB* and *JNDI* to demonstrate how to access an EJB, deployed to JBoss EAP, from a remote Java client application. | Intermediate | | +| [ejb-security](ejb-security/README.md) |EJB, Security | The `ejb-security` quickstart demonstrates the use of Java EE declarative security to control access to EJBs in JBoss EAP. | Intermediate | | +| [ejb-security-context-propagation](ejb-security-context-propagation/README.md) |EJB, Security | The `ejb-security-context-propagation` quickstart demonstrates how the security context can be propagated to a remote EJB using a remote outbound connection configuration | Advanced | | +| [ejb-security-interceptors](ejb-security-interceptors/README.md) |EJB, Security | The `ejb-security-interceptors` quickstart demonstrates how to use client and server side interceptors to switch the identity for an EJB call. | Advanced | | +| [ejb-security-jaas](ejb-security-jaas/README.md) |EJB, Security | The `ejb-security-jaas` quickstart demonstrates how legacy `JAAS` security domains can be used in conjunction with `Elytron` | Intermediate | | +| [ejb-security-programmatic-auth](ejb-security-programmatic-auth/README.md) |EJB, Security | The `ejb-security-programmatic-auth` quickstart demonstrates how to programmatically setup different identities when invoking a remote secured EJB. | Intermediate | | +| [ejb-throws-exception](ejb-throws-exception/README.md) |EJB, EAR | The `ejb-throws-exception` quickstart demonstrates how to throw and handle Exceptions across JARs in an EAR. | Intermediate | | +| [ejb-timer](ejb-timer/README.md) |EJB Timer | The `ejb-timer` quickstart demonstrates how to use the EJB timer service `@Schedule` and `@Timeout` annotations with JBoss EAP. | Beginner | | +| [forge-from-scratch](forge-from-scratch/README.md) |Forge | The `forge-from-scratch` quickstart demonstrates how *JBoss Forge* can generate a Java EE (JPA, EJB, JAX-RS, JSF) web-enabled database application. | Intermediate | | +| [greeter](greeter/README.md) |CDI, JSF, JPA, EJB, JTA | The `greeter` quickstart demonstrates the use of *CDI*, *JPA*, *JTA*, *EJB* and *JSF* in JBoss EAP. | Beginner | | +| [h2-console](h2-console/README.md) |H2 | The `h2-console` quickstart demonstrates how to use the H2 Console that is bundled with and built specifically for JBoss EAP. | Beginner | | +| [ha-singleton-deployment](ha-singleton-deployment/README.md) |EJB, Singleton Deployments, Clustering | The `ha-singleton-deployment` quickstart demonstrates the recommended way to deploy any service packaged in an application archive as a cluster-wide singleton. | Advanced | | +| [ha-singleton-service](ha-singleton-service/README.md) |MSC, Singleton Service, Clustering | The `ha-singleton-service` quickstart demonstrates how to deploy a cluster-wide singleton MSC service. | Advanced | | +| [helloworld](helloworld/README.md) |CDI, Servlet | The `helloworld` quickstart demonstrates the use of *CDI* and *Servlet 3* and is a good starting point to verify JBoss EAP is configured correctly. | Beginner | | +| [helloworld-html5](helloworld-html5/README.md) |CDI, JAX-RS, HTML5 | The `helloworld-html5` quickstart demonstrates the use of *CDI 1.2* and *JAX-RS 2.0* using the HTML5 architecture and RESTful services on the backend. | Beginner | | +| [helloworld-jms](helloworld-jms/README.md) |JMS | The `helloworld-jms` quickstart demonstrates the use of external JMS clients with JBoss EAP. | Intermediate | | +| [helloworld-mbean](helloworld-mbean/README.md) |CDI, JMX, MBean | The `helloworld-mbean` quickstart demonstrates the use of *CDI* and *MBean* in JBoss EAP and includes JConsole instructions and Arquillian tests. | Intermediate | | +| [helloworld-mdb](helloworld-mdb/README.md) |JMS, EJB, MDB | The `helloworld-mdb` quickstart uses *JMS* and *EJB Message-Driven Bean* (MDB) to create and deploy JMS topic and queue resources in JBoss EAP. | Intermediate | | +| [helloworld-mdb-propertysubstitution](helloworld-mdb-propertysubstitution/README.md) |JMS, EJB, MDB | The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of *JMS* and *EJB MDB*, enabling property substitution with annotations. | Intermediate | | +| [helloworld-mutual-ssl](helloworld-mutual-ssl/README.md) |Mutual SSL, Undertow | The `helloworld-mutual-ssl` quickstart is a basic example that demonstrates mutual SSL configuration in JBoss EAP | Intermediate | | +| [helloworld-mutual-ssl-secured](helloworld-mutual-ssl-secured/README.md) |Mutual SSL, Security, Undertow | The `helloworld-mutual-ssl-secured` quickstart demonstrates securing a Web application using client mutual SSL authentication and role-based access control | Intermediate | | +| [helloworld-rs](helloworld-rs/README.md) |CDI, JAX-RS | The `helloworld-rs` quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses *JAX-RS* to say Hello. | Intermediate | | +| [helloworld-singleton](helloworld-singleton/README.md) |EJB, Singleton | The `helloworld-singleton` quickstart demonstrates an *EJB Singleton Bean* that is instantiated once and maintains state for the life of the session. | Beginner | | +| [helloworld-ssl](helloworld-ssl/README.md) |SSL, Undertow | The `helloworld-ssl` quickstart is a basic example that demonstrates server side SSL configuration in JBoss EAP. | Beginner | | +| [helloworld-ws](helloworld-ws/README.md) |JAX-WS | The `helloworld-ws` quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses *JAX-WS* to say Hello. | Beginner | | +| [hibernate](hibernate/README.md) |Hibernate | The `hibernate` quickstart demonstrates how to use Hibernate ORM 5 API over JPA, using Hibernate-Core and Hibernate Bean Validation, and EJB. | Intermediate | | +| [inter-app](inter-app/README.md) |EJB, CDI, JSF | The `inter-app` quickstart shows you how to use a shared API JAR and an EJB to provide inter-application communication between two WAR deployments. | Advanced | | +| [jaxrs-client](jaxrs-client/README.md) |JAX-RS | The `jaxrs-client` quickstart demonstrates JAX-RS Client API, which interacts with a JAX-RS Web service that runs on JBoss EAP. | Beginner | | +| [jaxws-addressing](jaxws-addressing/README.md) |JAX-WS | The `jaxws-addressing` quickstart is a working example of the web service using WS-Addressing. | Beginner | | +| [jaxws-ejb](jaxws-ejb/README.md) |JAX-WS | The `jaxws-ejb` quickstart is a working example of the web service endpoint created from an EJB. | Beginner | | +| [jaxws-pojo](jaxws-pojo/README.md) |JAX-WS | The `jaxws-pojo` quickstart is a working example of the web service endpoint created from a POJO. | Beginner | | +| [jaxws-retail](jaxws-retail/README.md) |JAX-WS | The `jaxws-retail` quickstart is a working example of a simple web service endpoint. | Beginner | | +| [jsonp](jsonp/README.md) |CDI, JSF, JSON-P | The `jsonp` quickstart demonstrates how to use the JSON-P API to produce object-based structures and then parse and consume them as stream-based JSON strings. | Beginner | | +| [jta-crash-rec](jta-crash-rec/README.md) |JTA, Crash Recovery | The `jta-crash-rec` quickstart uses JTA and Byteman to show how to code distributed (XA) transactions in order to preserve ACID properties on server crash. | Advanced | | +| [jts](jts/README.md) |JTS, EJB, JMS | The `jts` quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction. | Intermediate | cmt | +| [jts-distributed-crash-rec](jts-distributed-crash-rec/README.md) |JTS, Crash Recovery | The `jts-distributed-crash-rec` quickstart uses JTS and Byteman to demonstrate distributed crash recovery across multiple application servers. | Advanced | jts | +| [kitchensink](kitchensink/README.md) |CDI, JSF, JPA, EJB, JAX-RS, BV | The `kitchensink` quickstart demonstrates a Java EE 7 web-enabled database application using JSF, CDI, EJB, JPA, and Bean Validation. | Intermediate | | +| [kitchensink-angularjs](kitchensink-angularjs/README.md) |AngularJS, CDI, JPA, EJB, JPA, JAX-RS, BV | The `kitchensink-angularjs` quickstart demonstrates a Java EE 7 application using AngularJS with JAX-RS, CDI, EJB, JPA, and Bean Validation. | Intermediate | | +| [kitchensink-ear](kitchensink-ear/README.md) |CDI, JSF, JPA, EJB, JAX-RS, BV, EAR | The `kitchensink-ear` quickstart demonstrates web-enabled database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR. | Intermediate | | +| [kitchensink-html5-mobile](kitchensink-html5-mobile/README.md) |CDI, HTML5, REST | The `kitchensink-html5-mobile` quickstart is based on `kitchensink`, but uses HTML5 and jQuery Mobile, making it suitable for mobile and tablet computers. | Beginner | | +| [kitchensink-jsp](kitchensink-jsp/README.md) |JSP, JSTL, CDI, JPA, EJB, JAX-RS, BV | The `kitchensink-jsp` quickstart demonstrates how to use JSP, JSTL, CDI, EJB, JPA, and Bean Validation in JBoss EAP. | Intermediate | | +| [kitchensink-ml](kitchensink-ml/README.md) |CDI, JSF, JPA, EJB, JAX-RS, BV, i18n, l10n | The `kitchensink-ml` quickstart demonstrates a localized Java EE 7 compliant application using JSF, CDI, EJB, JPA, and Bean Validation. | Intermediate | | +| [kitchensink-ml-ear](kitchensink-ml-ear/README.md) |CDI, JSF, JPA, EJB, JAX-RS, BV, EAR, i18n, l10n | The `kitchensink-ml-ear` quickstart demonstrates a localized database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR. | Intermediate | | +| [log4j](log4j/README.md) |JBoss Modules | The `log4j` quickstart demonstrates how to use container defined modules to add dependencies on 3rd party libraries and limit the application package size. | Beginner | | +| [logging](logging/README.md) |Logging | The `logging` quickstart demonstrates how to configure different logging levels in JBoss EAP. It also includes an asynchronous logging example. | Intermediate | None | +| [logging-tools](logging-tools/README.md) |JBoss Logging Tools | The `logging-tools` quickstart shows how to use JBoss Logging Tools to create internationalized loggers, exceptions, and messages and localize them. | Beginner | | +| [mail](mail/README.md) |JavaMail, CDI, JSF | The `mail` quickstart demonstrates how to send email using CDI and JSF and the default Mail provider that ships with JBoss EAP. | Beginner | | +| [managed-executor-service](managed-executor-service/README.md) |EE Concurrency Utilities, JAX-RS, JAX-RS Client API | The `managed-executor-service` quickstart demonstrates how Java EE applications can submit tasks for asynchronous execution. | Beginner | | +| [messaging-clustering](messaging-clustering/README.md) |JMS, MDB | The `messaging-clustering` quickstart does not contain any code and instead uses the `helloworld-mdb` quickstart to demonstrate clustering using ActiveMQ Messaging. | Intermediate | helloworld-mdb | +| [messaging-clustering-singleton](messaging-clustering-singleton/README.md) |JMS, MDB, Clustering | The `messaging-clustering-singleton` quickstart uses a JMS topic and a queue to demonstrate clustering using JBoss EAP messaging with MDB singleton configuration where only one node in the cluster will be active. | Advanced | | +| [numberguess](numberguess/README.md) |CDI, JSF | The `numberguess` quickstart demonstrates the use of *CDI* (Contexts and Dependency Injection) and *JSF* (JavaServer Faces) in JBoss EAP. | Beginner | | +| [payment-cdi-event](payment-cdi-event/README.md) |CDI, JSF | The `payment-cdi-event` quickstart demonstrates how to create credit and debit *CDI Events* in JBoss EAP, using a JSF front-end client. | Beginner | | +| [picketlink-sts](picketlink-sts/README.md) |WS-Trust, SAML | The `picketlink-sts` quickstart demonstrates how to deploy a fully compliant WS-Trust Security Token Service (STS). | Advanced | | +| [resteasy-jaxrs-client](resteasy-jaxrs-client/README.md) |JAX-RS, CDI | The `resteasy-jaxrs-client` quickstart demonstrates an external JAX-RS RestEasy client, which interacts with a JAX-RS Web service that uses *CDI* and *JAX-RS*. | Intermediate | helloworld-rs | +| [servlet-async](servlet-async/README.md) |Asynchronous Servlet, CDI, EJB | The `servlet-async` quickstart demonstrates how to use asynchronous servlets to detach long-running tasks and free up the request processing thread. | Intermediate | | +| [servlet-filterlistener](servlet-filterlistener/README.md) |Servlet Filter, Servlet Listener | The `servlet-filterlistener` quickstart demonstrates how to use Servlet filters and listeners in an application. | Intermediate | | +| [servlet-security](servlet-security/README.md) |Servlet, Security | The `servlet-security` quickstart demonstrates the use of Java EE declarative security to control access to Servlets and Security in JBoss EAP. | Intermediate | | +| [shopping-cart](shopping-cart/README.md) |SFSB EJB | The `shopping-cart` quickstart demonstrates how to deploy and run a simple Java EE 7 shopping cart application that uses a stateful session bean (SFSB). | Intermediate | | +| [shrinkwrap-resolver](shrinkwrap-resolver/README.md) |CDI, Arquillian, Shrinkwrap | The `shrinkwrap-resolver` quickstart demonstrates three common use cases for ShrinkWrap Resolver in Red Hat JBoss Enterprise Application Platform. | Intermediate | | +| [spring-greeter](spring-greeter/README.md) |Spring MVC, JSP, JPA | The `spring-greeter` quickstart is based on the `greeter` quickstart, but differs in that it uses Spring MVC for Mapping GET and POST requests. | Beginner | | +| [spring-kitchensink-asyncrequestmapping](spring-kitchensink-asyncrequestmapping/README.md) |JSP, JPA, JSON, Spring, JUnit | The `spring-kitchensink-asyncrequestmapping` quickstart showcases the use of asynchronous requests is an example using JSP, JPA and Spring 4.x. | Intermediate | | +| [spring-kitchensink-basic](spring-kitchensink-basic/README.md) |JSP, JPA, JSON, Spring, JUnit | The `spring-kitchensink-basic` quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x. | Intermediate | | +| [spring-kitchensink-controlleradvice](spring-kitchensink-controlleradvice/README.md) |JSP, JPA, JSON, Spring, JUnit | The `spring-kitchensink-controlleradvice` quickstart showcases Spring 4.x's `@ControllerAdvice`, which was introduced in Spring 3.2. | Intermediate | | +| [spring-kitchensink-matrixvariables](spring-kitchensink-matrixvariables/README.md) |JSP, JPA, JSON, Spring, JUnit | The `spring-kitchensink-matrixvariables` quickstart showcases Spring 4.x's support for **Matrix Variables** in URLs that was introduced in Spring 3.2. | Intermediate | | +| [spring-kitchensink-springmvctest](spring-kitchensink-springmvctest/README.md) |JSP, JPA, JSON, Spring, JUnit | The `spring-kitchensink-springmvctest` quickstart demonstrates how to create an MVC application using JSP, JPA and Spring 4.x. | Intermediate | | +| [spring-petclinic](spring-petclinic/README.md) |JPA, Junit, JMX, Spring MVC Annotations, AOP, Spring Data, JSP, webjars, Dandellion | The `spring-petclinic` quickstart shows how to run the Spring PetClinic Application in JBoss EAP using the JBoss EAP BOMs. | Advanced | | +| [spring-resteasy](spring-resteasy/README.md) |Resteasy, Spring | The `spring-resteasy` quickstart demonstrates how to package and deploy a web application that includes resteasy-spring integration. | Beginner | | +| [tasks](tasks/README.md) |JPA, Arquillian | The `tasks` quickstart includes a persistence unit and sample persistence code to demonstrate how to use JPA for database access in JBoss EAP. | Intermediate | | +| [tasks-jsf](tasks-jsf/README.md) |JSF, JPA | The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as the view layer. | Intermediate | tasks | +| [tasks-rs](tasks-rs/README.md) |JPA, JAX-RS | The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence. | Intermediate | tasks | +| [temperature-converter](temperature-converter/README.md) |CDI, JSF, SLSB EJB | The `temperature-converter` quickstart does temperature conversion using an *EJB Stateless Session Bean* (SLSB), *CDI*, and a *JSF* front-end client. | Beginner | | +| [thread-racing](thread-racing/README.md) |Batch, CDI, EE Concurrency, JAX-RS, JMS, JPA, JSON, Web Sockets | A thread racing web application that demonstrates technologies introduced or updated in the latest Java EE specification. | Beginner | | +| [websocket-client](websocket-client/README.md) |Web Socket, CDI Events, JSON, SSL | Demonstrates use of a Javascript WebSocket client, WebSocket configuration, programmatic binding, and secure WebSocket. | Intermediate | | +| [websocket-endpoint](websocket-endpoint/README.md) |CDI, WebSocket, JSON-P | Shows how to use WebSockets with JSON to broadcast information to all open WebSocket sessions in JBoss EAP. | Beginner | | +| [websocket-hello](websocket-hello/README.md) |WebSocket, CDI, JSF | The `websocket-hello` quickstart demonstrates how to create a simple WebSocket application. | Beginner | | +| [wsat-simple](wsat-simple/README.md) |WS-AT, JAX-WS | The `wsat-simple` quickstart demonstrates a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service, bundled as a WAR, and deployed to JBoss EAP. | Intermediate | | +| [wsba-coordinator-completion-simple](wsba-coordinator-completion-simple/README.md) |WS-BA, JAX-WS | The `wsba-coordinator-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (CoordinatorCompletion protocol). | Intermediate | | +| [wsba-participant-completion-simple](wsba-participant-completion-simple/README.md) |WS-BA, JAX-WS | The `wsba-participant-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (ParticipantCompletion Protocol). | Intermediate | | +| [xml-dom4j](xml-dom4j/README.md) |DOM4J, Servlet, JSF | The `xml-dom4j` quickstart demonstrates how to use Servlet and JSF to upload an XML file to JBoss EAP and parse it using a 3rd party XML parsing library. | Intermediate | | +| [xml-jaxp](xml-jaxp/README.md) |JAXP, SAX, DOM, Servlet | The `xml-jaxp` quickstart demonstrates how to use Servlet and JSF to upload an XML file to JBoss EAP and validate and parse it using DOM or SAX. | Intermediate | | -[TOC-quickstart] - ## Suggested Approach to the Quickstarts @@ -51,11 +151,11 @@ We suggest you approach the quickstarts as follows: ## System Requirements -The applications these projects produce are designed to be run on ${product.name.full} ${product.version} or later. +The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build these projects is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on how to install and run JBoss, see the [${product.name.full} Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. +To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the [Red Hat JBoss Enterprise Application Platform Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) to run the quickstarts. @@ -64,7 +164,7 @@ You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio The root folder of each individual quickstart contains a README file with specific details on how to build and run the example. In most cases you do the following: -* [Start the ${product.name} Server](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/START_JBOSS_EAP.md#start-the-jboss-eap-server) +* [Start the JBoss EAP Server](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/START_JBOSS_EAP.md#start-the-jboss-eap-server) * [Build and deploy the quickstarts](#build-and-deploy-the-quickstarts) @@ -86,7 +186,7 @@ In most cases, you can use the following steps to build the application to test In most cases, you can use the following steps to build and deploy the application. See the specific quickstart README file for complete details. -1. Make sure you start the ${product.name} server as described in the quickstart README file. +1. Make sure you start the JBoss EAP server as described in the quickstart README file. 2. Open a command prompt and navigate to the root directory of the quickstart you want to run. 3. Use this command to build and deploy the archive: @@ -105,7 +205,7 @@ You can verify the quickstarts build using one command. However, quickstarts tha To build the quickstarts: -1. Do not start the ${product.name} server. +1. Do not start the JBoss EAP server. 2. Open a command prompt and navigate to the root directory of the quickstarts. 3. Use this command to build the quickstarts that do not have complex dependencies: @@ -118,7 +218,7 @@ To undeploy the quickstarts from the root of the quickstart folder, you must pas You can undeploy quickstarts using the following procedure: -1. Start the ${product.name} server. +1. Start the JBoss EAP server. 2. Open a command prompt and navigate to the root directory of the quickstarts. 3. Use this command to undeploy any deployed quickstarts: @@ -129,7 +229,7 @@ To undeploy any quickstarts that fail due to complex dependencies, follow the un ## Run the Quickstarts in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Optional Components diff --git a/RELEASE_PROCEDURE.html b/RELEASE_PROCEDURE.html new file mode 100644 index 0000000000..b3cadfa6cc --- /dev/null +++ b/RELEASE_PROCEDURE.html @@ -0,0 +1,89 @@ + + +Testing the quickstarts + + + +

Quickstarts Release Procedure

+

Testing the quickstarts

+

Most of the quickstarts require starting Red Hat JBoss Enterprise Application Platform in standalone mode. Some require the "standalone-full" profile, some require XTS, some require Postgres and some require other quickstarts to be deployed. Profiles are used in the root POM to separate out these groups, allowing you to test the quickstarts easily. For example, to run those that require only standalone mode:

+
  mvn clean verify wildfly:deploy wildfly:undeploy -Parq-remote -P-requires-postgres,-requires-full,-complex-dependencies,-requires-xts
+
+

Or, to run those only those quickstarts that require the full profile

+
  mvn clean verify wildfly:deploy wildfly:undeploy -Parq-remote -P-requires-postgres,-default,-complex-dependencies,-requires-xts
+
+

And so on.

+

Quickstarts in other repositories

+

If the quickstarts are stored in another repository, you may wish to merge them in from there, do this:

+
    +
  1. +

    Add the other repo as a remote

    +
     git remote add -f <other repo> <other repo url>
+
    +
    2. +
  2. +

    Merge from the tag in the other repo that you wish to use. It is important to use a tag, to make tracking of history easier. We use a recursive merge strategy, always preferring changes from the other repo, in effect overwriting what we have locally.

    +
     git merge <tag> -s recursive -Xtheirs -m "Merge <Other repository name> '<Tag>'"
+
    +
    3. +
  3. +

    Review and push to upstream

    +
     git push upstream HEAD:master
+
    +
    4. +
+

Rendering Markdown

+

The quickstarts use flexmark maven plugin to process the markdown. This builds on the basic markdown syntax, adding support for tables, code highlighting, relaxed code blocks etc). We add a couple of custom piece of markup - [TOC] which allows a table of contents, based on headings, to be added to any file, and [Quickstart-TOC], which adds in a table listing the quickstarts.

+

Just run

+
    mvn generate-resources -Pdocs
+
+

To render all markdown files to HTML.

+

To do proper release with zip file & all markdown files with resolved variables and rendered html files, run

+
    mvn clean install -Drelease
+
+

Which will also result in zip with all quickstarts in dist/target

+

Publishing builds to Maven

+
    +
  1. You must have gpg set up and your key registered, as described at hhttp://blog.sonatype.com/people/2010/01/how-to-generate-pgp-signatures-with-maven/
    2. +
  2. You must provide a property gpg.passphrase in your settings.xml in the release profile e.g. +
      <profile>
+        <id>release</id>
+        <properties>
+            <gpg.passphrase>myPassPhrase</gpg.passphrase>
+        </properties>
+  </profile>
+
    +
    3. +
  3. You must have a JBoss Nexus account, configured with the server id in settings.xml with the id jboss-releases-repository e.g. +
      <server>
+      <id>jboss-releases-repository</id>
+      <username>myUserName</username>
+      <password>myPassword</password>
+  </server>
+
    +
    4. +
  4. +

    Add org.sonatype.plugins plug-in group to your settings.xml so the Nexus plug-in can be available for publishing scripts.

    +
      <pluginGroups>
+      <pluginGroup>org.sonatype.plugins</pluginGroup>
+  </pluginGroups>
+
    +
    5. +
+

Release Procedure

+
    +
  1. Make sure you have access to rsync files to filemgmt.jboss.org/download_htdocs/jbossas
    2. +
  2. Release the archetypes
    3. +
  3. Regenerate the quickstart based on archetypes +
     dist/release-utils.sh -r
+
    +
    4. +
  4. +

    Release

    +
     dist/release.sh -s <old snapshot version> -r <release version>
+
    +

    This will update the version number, commit and tag, build the distro zip and upload it to <download.jboss.org>. Then it will reset the version number back to the snapshot version number.

    +
    5. +
+ + \ No newline at end of file diff --git a/RELEASE_PROCEDURE.md b/RELEASE_PROCEDURE.md index ac58a79714..9d10c95c9a 100644 --- a/RELEASE_PROCEDURE.md +++ b/RELEASE_PROCEDURE.md @@ -4,7 +4,7 @@ Quickstarts Release Procedure Testing the quickstarts ----------------------- - Most of the quickstarts require starting ${product.name.full} in standalone mode. Some require the "standalone-full" profile, some require XTS, some require Postgres and some require other quickstarts to be deployed. Profiles are used in the root POM to separate out these groups, allowing you to test the quickstarts easily. For example, to run those that require only standalone mode: + Most of the quickstarts require starting Red Hat JBoss Enterprise Application Platform in standalone mode. Some require the "standalone-full" profile, some require XTS, some require Postgres and some require other quickstarts to be deployed. Profiles are used in the root POM to separate out these groups, allowing you to test the quickstarts easily. For example, to run those that require only standalone mode: mvn clean verify wildfly:deploy wildfly:undeploy -Parq-remote -P-requires-postgres,-requires-full,-complex-dependencies,-requires-xts diff --git a/app-client/README.html b/app-client/README.html new file mode 100644 index 0000000000..2dae5b69cf --- /dev/null +++ b/app-client/README.html @@ -0,0 +1,170 @@ + + + app-client: Use the JBoss EAP Application Client Container + + + +

app-client: Use the JBoss EAP Application Client Container

+

Author: Wolf-Dieter Fink
+Level: Intermediate
+Technologies: EJB, EAR, AppClient
+Summary: The app-client quickstart demonstrates how to code and package a client app and use the JBoss EAP client container to start the client Main program.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The app-client quickstart demonstrates how to use the JBoss EAP client container to start the client Main program and provide Dependency Injections (DI) for client applications in Red Hat JBoss Enterprise Application Platform. It also shows you how to use Maven to package the application according to the JavaEE specification.

+

This example consists of the following Maven projects, each with a shared parent:

+ + + + + + + + + +
Sub-project Description
ejb An application that can be called by the client.
ear The EAR packaging contains the server and client side.
client-simple A simple client application for running in the application-client container to show the injection
+

The root pom.xml file builds each of the subprojects in the appropriate order.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add the Application Users

+

If the client and server are run on different hosts, you must add the following users to the JBoss EAP server side application. Be sure to use the names and passwords specified in the table as they are required to run this example.

+ + + + + + + + +
UserName Realm Password Roles
admin ManagementRealm admin-123 leave blank for none
quickuser ApplicationRealm quick-123 leave blank for none
+

To add the users, open a command prompt and type the following commands:

+
    For Linux:
+        EAP7_HOME/bin/add-user.sh -u admin -p admin-123
+        EAP7_HOME/bin/add-user.sh -a -u quickuser -p quick-123
+
+    For Windows:
+        EAP7_HOME\bin\add-user.bat -u admin -p admin-123
+        EAP7_HOME\bin\add-user.bat -a -u quickuser -p quick-123
+
+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build the artifacts: +
    mvn clean install wildfly:deploy
+
    +
    4. +
+

Access the Remote Client Application from the Same Machine

+

This example shows how to invoke an EJB from a remote standalone application on the same machine. Both the client and server are on the same machine, so the defaults are sufficient and no authentication is necessary.

+
    +
  1. Be sure the quickstart deployed successfully as described above.
    2. +
  2. Navigate to the root directory of this quickstart and type the following command to run the application. Be sure to replace EAP7_HOME with the path to your JBoss EAP installation. +
    For Linux:   EAP7_HOME/bin/appclient.sh ear/target/app-client.ear#simpleClient.jar Hello from command line
+For Windows: EAP7_HOME\bin\appclient.bat ear\target\app-client.ear#simpleClient.jar Hello from command line
+
    +
    3. +
  3. +

    Review the result. The client outputs the following information provided by the server application:

    +
    [org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-51) Main started with arguments
+[org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-51)             [Hello, from, command, line]
+[org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-##) Hello from StatelessSessionBean@myhost
+
    +

    This output shows that the ServerApplication is called at the jboss.node myhost. The application client connected automatically a server on the same machine.

    +
    4. +
  4. +

    Review the server log files to see the bean invocations on the server.

    +
     ClientContext is here = {Client =dev84, jboss.source-address=localhost/127.0.0.1:45315}
+
    +
    5. +
+

Access the Remote Client Application from a Different Machine

+

This example shows how to invoke an EJB from a remote standalone Java EE application on a different machine. In this case, the client needs to define a properties file to define properties to connect and authenticate to the server. The properties file is passed on the command line using the --ejb-client-properties argument.

+

Configure Machine_1 (Remote Server Machine)

+
    +
  1. Install JBoss EAP on this machine.
    2. +
  2. Add the application users to the JBoss EAP server on this machine as described above.
    3. +
  3. Start the JBoss EAP server with the following command. Be sure to replace MACHINE_1_IP_ADDRESS with the IP address of this machine. These arguments make the server accessible to the network. +
    For Linux:   EAP7_HOME/bin/standalone.sh -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS
+For Windows: EAP7_HOME\bin\standalone.bat -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS
+
    +
    4. +
+

Configure Machine_2 (Local Client Machine)

+
    +
  1. Install JBoss EAP on this server. There is no need to add the application users to this server.
    2. +
  2. Download the app-client quickstart to this machine.
    3. +
  3. Create a jboss-ejb-client.properties file. This file can be located anywhere in the file system, but for ease of demonstration, we create it in the root directory of this quickstart. Add the following content, replacing MACHINE_1_IP_ADDRESS with the IP address of Machine_1. +
    remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
+remote.connections=default
+remote.connection.default.host=MACHINE_1_IP_ADDRESS
+remote.connection.default.port=8080
+remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false
+remote.connection.default.username=quickuser
+remote.connection.default.password=quick-123
+
    +
    4. +
  4. +

    Open a command prompt and navigate to the root directory of the quickstart.

    +
    5. +
  5. Deploy the app-client quickstart to the remote machine using the following command: +
    mvn clean install wildfly:deploy -Dwildfly.hostname=MACHINE_1_IP_ADDRESS [-Dwildfly.port=9099] -Dwildfly.username=admin -Dwildfly.password=admin-123
+
    +
    6. +
  6. Be sure that the quickstart deployed successfully and the server is running on Machine_1 as described above.
    7. +
  7. Type this command to run the app-client application: +
    For Linux:   EAP7_HOME/bin/appclient.sh --ejb-client-properties=ejb-client.properties ear/target/app-client.ear#simpleClient.jar Hello from command line
+For Windows: EAP7_HOME\bin\appclient.bat --ejb-client-properties=ejb-client.properties ear\target\app-client.ear#simpleClient.jar Hello from command line
+
    +
    8. +
  8. +

    Review the result. The client outputs the following information, which was provided by the application:

    +
    [org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-51) Main started with arguments
+[org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-51)             [Hello, from, command, line]
+[org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-##) Hello from StatelessSessionBean@theOtherHOST
+
    +

    This output shows that the ServerApplication is called at the jboss.node theOtherHOST.

    +
    9. +
  9. +

    Review the server log files on the remote machine to see the bean invocations on the server.

    +
     ClientContext is here = {Client =dev84, jboss.source-address=localhost/127.0.0.1:45315}
+
    +

    As shown above, the connected server(s) can be configured using the properties file. It is also possible to connect multiple servers or a cluster using the same jboss-ejb-client.properties file.

    +
    10. +
+

Undeploy the Archive from the Local Machine

+

Follow these instructions if you are testing the quickstart on the same machine.

+
    +
  1. Make sure you have started the JBoss EAP server on the machine where the quickstart is deployed as described above.
    2. +
  2. Open a command prompt on that server and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive from the local machine. +
    mvn wildfly:undeploy
+
    +
    4. +
+

Undeploy the Archive from the Remote Machine

+

Follow these instructions if you are testing the quickstart on a different machine.

+
    +
  1. Make sure you have started the JBoss EAP server on the remote server machine, Machine_1, where the quickstart is deployed as described above.
    2. +
  2. Open a command prompt on the local client machine, Machine_2, and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive from the remote server machine, Machine_1. +
    mvn wildfly:undeploy -Dwildfly.hostname=MACHINE_1_IP_ADDRESS [-Dwildfly.port=9099] -Dwildfly.username=admin -Dwildfly.password=admin-123
+
    +
    4. +
+ + \ No newline at end of file diff --git a/app-client/README.md b/app-client/README.md index 2923dfae8f..dfc61ab0f2 100644 --- a/app-client/README.md +++ b/app-client/README.md @@ -1,16 +1,16 @@ -# app-client: Use the ${product.name} Application Client Container +# app-client: Use the JBoss EAP Application Client Container Author: Wolf-Dieter Fink Level: Intermediate Technologies: EJB, EAR, AppClient -Summary: The `app-client` quickstart demonstrates how to code and package a client app and use the ${product.name} client container to start the client Main program. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `app-client` quickstart demonstrates how to code and package a client app and use the JBoss EAP client container to start the client Main program. +Target Product: JBoss EAP +Source: ## What is it? -The `app-client` quickstart demonstrates how to use the ${product.name} client container to start the client `Main` program and provide Dependency Injections (DI) for client applications in ${product.name.full}. It also shows you how to use Maven to package the application according to the JavaEE specification. +The `app-client` quickstart demonstrates how to use the JBoss EAP client container to start the client `Main` program and provide Dependency Injections (DI) for client applications in Red Hat JBoss Enterprise Application Platform. It also shows you how to use Maven to package the application according to the JavaEE specification. This example consists of the following Maven projects, each with a shared parent: @@ -27,19 +27,19 @@ The root `pom.xml` file builds each of the subprojects in the appropriate order. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add the Application Users -If the client and server are run on different hosts, you must add the following users to the ${product.name} server side application. Be sure to use the names and passwords specified in the table as they are required to run this example. +If the client and server are run on different hosts, you must add the following users to the JBoss EAP server side application. Be sure to use the names and passwords specified in the table as they are required to run this example. | **UserName** | **Realm** | **Password** | **Roles** | |:-----------|:-----------|:-----------|:-----------| @@ -49,28 +49,28 @@ If the client and server are run on different hosts, you must add the following To add the users, open a command prompt and type the following commands: For Linux: - ${jboss.home.name}/bin/add-user.sh -u admin -p admin-123 - ${jboss.home.name}/bin/add-user.sh -a -u quickuser -p quick-123 + EAP7_HOME/bin/add-user.sh -u admin -p admin-123 + EAP7_HOME/bin/add-user.sh -a -u quickuser -p quick-123 For Windows: - ${jboss.home.name}\bin\add-user.bat -u admin -p admin-123 - ${jboss.home.name}\bin\add-user.bat -a -u quickuser -p quick-123 + EAP7_HOME\bin\add-user.bat -u admin -p admin-123 + EAP7_HOME\bin\add-user.bat -a -u quickuser -p quick-123 If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: [Add an Application User](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build the artifacts: @@ -83,10 +83,10 @@ If you prefer, you can use the add-user utility interactively. For an example of This example shows how to invoke an EJB from a remote standalone application on the same machine. Both the client and server are on the same machine, so the defaults are sufficient and no authentication is necessary. 1. Be sure the quickstart deployed successfully as described above. -2. Navigate to the root directory of this quickstart and type the following command to run the application. Be sure to replace `${jboss.home.name}` with the path to your ${product.name} installation. +2. Navigate to the root directory of this quickstart and type the following command to run the application. Be sure to replace `EAP7_HOME` with the path to your JBoss EAP installation. - For Linux: ${jboss.home.name}/bin/appclient.sh ear/target/app-client.ear#simpleClient.jar Hello from command line - For Windows: ${jboss.home.name}\bin\appclient.bat ear\target\app-client.ear#simpleClient.jar Hello from command line + For Linux: EAP7_HOME/bin/appclient.sh ear/target/app-client.ear#simpleClient.jar Hello from command line + For Windows: EAP7_HOME\bin\appclient.bat ear\target\app-client.ear#simpleClient.jar Hello from command line 3. Review the result. The client outputs the following information provided by the server application: @@ -108,17 +108,17 @@ This example shows how to invoke an EJB from a remote standalone Java EE applica ### Configure Machine_1 (Remote Server Machine) -1. Install ${product.name} on this machine. -2. Add the application users to the ${product.name} server on this machine as described above. -3. Start the ${product.name} server with the following command. Be sure to replace `MACHINE_1_IP_ADDRESS` with the IP address of this machine. These arguments make the server accessible to the network. +1. Install JBoss EAP on this machine. +2. Add the application users to the JBoss EAP server on this machine as described above. +3. Start the JBoss EAP server with the following command. Be sure to replace `MACHINE_1_IP_ADDRESS` with the IP address of this machine. These arguments make the server accessible to the network. - For Linux: ${jboss.home.name}/bin/standalone.sh -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS - For Windows: ${jboss.home.name}\bin\standalone.bat -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS + For Linux: EAP7_HOME/bin/standalone.sh -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS + For Windows: EAP7_HOME\bin\standalone.bat -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS ### Configure Machine_2 (Local Client Machine) -1. Install ${product.name} on this server. There is no need to add the application users to this server. +1. Install JBoss EAP on this server. There is no need to add the application users to this server. 2. Download the `app-client` quickstart to this machine. 3. Create a `jboss-ejb-client.properties` file. This file can be located anywhere in the file system, but for ease of demonstration, we create it in the root directory of this quickstart. Add the following content, replacing `MACHINE_1_IP_ADDRESS` with the IP address of `Machine_1`. @@ -137,8 +137,8 @@ This example shows how to invoke an EJB from a remote standalone Java EE applica 6. Be sure that the quickstart deployed successfully and the server is running on `Machine_1` as described above. 7. Type this command to run the `app-client` application: - For Linux: ${jboss.home.name}/bin/appclient.sh --ejb-client-properties=ejb-client.properties ear/target/app-client.ear#simpleClient.jar Hello from command line - For Windows: ${jboss.home.name}\bin\appclient.bat --ejb-client-properties=ejb-client.properties ear\target\app-client.ear#simpleClient.jar Hello from command line + For Linux: EAP7_HOME/bin/appclient.sh --ejb-client-properties=ejb-client.properties ear/target/app-client.ear#simpleClient.jar Hello from command line + For Windows: EAP7_HOME\bin\appclient.bat --ejb-client-properties=ejb-client.properties ear\target\app-client.ear#simpleClient.jar Hello from command line 8. Review the result. The client outputs the following information, which was provided by the application: @@ -162,7 +162,7 @@ This example shows how to invoke an EJB from a remote standalone Java EE applica Follow these instructions if you are testing the quickstart on the same machine. -1. Make sure you have started the ${product.name} server on the machine where the quickstart is deployed as described above. +1. Make sure you have started the JBoss EAP server on the machine where the quickstart is deployed as described above. 2. Open a command prompt on that server and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive from the local machine. @@ -173,7 +173,7 @@ Follow these instructions if you are testing the quickstart on the same machine. Follow these instructions if you are testing the quickstart on a different machine. -1. Make sure you have started the ${product.name} server on the remote server machine, `Machine_1`, where the quickstart is deployed as described above. +1. Make sure you have started the JBoss EAP server on the remote server machine, `Machine_1`, where the quickstart is deployed as described above. 2. Open a command prompt on the local client machine, `Machine_2`, and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive from the remote server machine, `Machine_1`. diff --git a/app-client/client-simple/pom.xml b/app-client/client-simple/pom.xml index 5cd8f7b34a..401717971b 100644 --- a/app-client/client-simple/pom.xml +++ b/app-client/client-simple/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts app-client - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA app-client-client-simple jar diff --git a/app-client/ear/pom.xml b/app-client/ear/pom.xml index 23ab56046d..703908cc78 100644 --- a/app-client/ear/pom.xml +++ b/app-client/ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts app-client - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA app-client-ear ear diff --git a/app-client/ejb/pom.xml b/app-client/ejb/pom.xml index 54e86d89d6..a74273d506 100644 --- a/app-client/ejb/pom.xml +++ b/app-client/ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts app-client - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA app-client-ejb ejb diff --git a/app-client/pom.xml b/app-client/pom.xml index bcc9c83974..a75ce7483d 100644 --- a/app-client/pom.xml +++ b/app-client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/batch-processing/README.html b/batch-processing/README.html new file mode 100644 index 0000000000..1ea3424605 --- /dev/null +++ b/batch-processing/README.html @@ -0,0 +1,135 @@ + + + batch-processing: Chunk oriented Batch 1.0 processing + + + +

batch-processing: Chunk oriented Batch 1.0 processing

+

Author: Rafael Benevides
+Level: Intermediate
+Technologies: CDI, Batch 1.0, JSF
+Summary: The batch-processing quickstart shows how to use chunk oriented batch jobs to import a file to a database.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

This quickstart simulates a file importation using batch jobs. To make it easy, this quickstart offers the user a way to generate files. The generate file can have its name and the number of records customized. The user may also specify if the file contains an error or not.

+

The Job contains two steps (tasks):

+
    +
  1. Import the file (Chunk oriented) - The chunk size was set to 3. The RecordsReader is responsible for parsing the file and create an instance of Contact. The ContactsFormatter applies the proper case to the Contact name and it also applies a mask to the phone number. Finally, ContactsPersister will send the Contact instance to the Database.
    2. +
  2. Log the number of records imported
    3. +
+

The database schema defines that the column for name is unique. For that reason, any atempt to persist a duplicate value will throw an exception. On the second attempt to run the job, the ChunkCheckpoint will provide information to skip the Contacts that were already persisted.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. This will deploy target/batch-processing.war to the running instance of the server.
    5. +
+

Access the Application

+

Access the running application in a browser at the following URL: http://localhost:8080/batch-processing/

+

You are presented with a simple form that allows you to generate sample files to be imported.

+

Usage 1: Import the file without any errors

+

Click on Generate a new file and start import job button. This will generate a new file with 10 unique records to be imported. After the file is generated, the import job will start.

+

You will see a table containing information about the task that was just started. You can click on Update jobs list button and verify that the job was completed.

+

Investigate the Console Output

+

At the logs you will see that the files with 10 records were processed using 3 records at a time.

+
INFO  [org.jboss.as.quickstarts.batch.controller.BatchController] (default task-3) Starting to generate 10 in file /var/folders/j8/63sgdmbn5tqdkyw0tz6df53r0000gn/T/temp-file.txt
+INFO  [org.jboss.as.quickstarts.batch.controller.BatchController] (default task-3) File generated at /var/folders/j8/63sgdmbn5tqdkyw0tz6df53r0000gn/T/temp-file.txt
+INFO  [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - 1) Job import-file - Execution #1 starting.
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsPersister] (Batch Thread - 1) No checkpoint detected. Cleaning the Database
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #1 - Changing name ZIqYKITxiM -> Ziqykitxim | phone  978913851 -> (978)-913-851
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #2 - Changing name JbHjnaThps -> Jbhjnathps | phone  095108018 -> (095)-108-018
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #3 - Changing name FJTlXRtCdR -> Fjtlxrtcdr | phone  286847939 -> (286)-847-939
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Preparing to persist 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Persisting 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #4 - Changing name mlmBABWzfL -> Mlmbabwzfl | phone  744478648 -> (744)-478-648
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #5 - Changing name jVlTYiBRMP -> Jvltyibrmp | phone  135063841 -> (135)-063-841
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #6 - Changing name DwEFbSjfQE -> Dwefbsjfqe | phone  404572175 -> (404)-572-175
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Preparing to persist 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Persisting 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #7 - Changing name niDXWwGJuQ -> Nidxwwgjuq | phone  949448390 -> (949)-448-390
+15:57:40,850 INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #8 - Changing name VZBArfowSe -> Vzbarfowse | phone  902370961 -> (902)-370-961
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #9 - Changing name aSpyWCWwje -> Aspywcwwje | phone  246977695 -> (246)-977-695
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Preparing to persist 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Persisting 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #10 - Changing name TofTfbRBzI -> Toftfbrbzi | phone  868339088 -> (868)-339-088
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Preparing to persist 1 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Persisting 1 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.ReportBatchelet] (Batch Thread - 1) Imported 10 to Database
+INFO  [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - 1) Job import-file - Execution #1 finished. Status: COMPLETED
+
+

Usage 2: Import an error file and fix it

+

Now we will simulate a file with duplicate records. This will raise an exception and stop the processing. After that, we will fix the file and continue the importing where it stopped.

+

Mark the Generate a duplicate record checkbox and click on Generate a new file and start import job button. If you click on Update jobs list button, you will see that the job failed with the following Exit Status: Error : org.hibernate.exception.ConstraintViolationException: could not execute statement. This was caused because the job tried to insert a duplicate record at the Database. You will also see org.h2.jdbc.JdbcSQLException: Unique index or primary key violation exception stacktraces in the server log.

+

Now we will fix the file and restart that job execution. Uncheck the Generate a duplicate record checkbox and click on Generate a new file button. This will generate file without errors.

+

Click on Restart button in the last column for that job instance in the List of Jobs table. If you click on Update jobs list button, you will see that the job was completed.

+

Analyze the logs and check that the job started from the last checkpoint.

+
16:08:56,323 INFO  [org.jboss.as.quickstarts.batch.job.RecordsReader] (Batch Thread - 3) Skipping to line 3 as marked by previous checkpoint
+
+

Investigate the Console Output

+
INFO  [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - 3) Job import-file - Execution #3 starting.
+INFO  [org.jboss.as.quickstarts.batch.job.RecordsReader] (Batch Thread - 3) Skipping to line 3 as marked by previous checkpoint
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #4 - Changing name HdeqwzEjbA -> Hdeqwzejba | phone  686417040 -> (686)-417-040
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #5 - Changing name veEEbtpYTJ -> Veeebtpytj | phone  367981821 -> (367)-981-821
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #6 - Changing name bQIKTUyqMW -> Bqiktuyqmw | phone  103363182 -> (103)-363-182
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Preparing to persist 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Persisting 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #7 - Changing name KVLIGXhCry -> Kvligxhcry | phone  117327691 -> (117)-327-691
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #8 - Changing name PBAZgernHy -> Pbazgernhy | phone  066203468 -> (066)-203-468
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #9 - Changing name DGtNZdteGB -> Dgtnzdtegb | phone  908779587 -> (908)-779-587
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Preparing to persist 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Persisting 3 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #10 - Changing name mhmIHhZMhv -> Mhmihhzmhv | phone  094518410 -> (094)-518-410
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Preparing to persist 1 contacts
+INFO  [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Persisting 1 contacts
+WARN  [org.jberet] (Batch Thread - 3) JBERET000018: Could not find the original step execution to restart.  Current step execution id: 0, step name: reportBatchelet
+INFO  [org.jboss.as.quickstarts.batch.job.ReportBatchelet] (Batch Thread - 3) Imported 10 to Database
+INFO  [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - 3) Job import-file - Execution #3 finished. Status: COMPLETED
+
+

Usage 3: Import an error file and do not fix the errors

+

Check the Generate a duplicate record checkbox and click on Generate a new file ans start import job button. If you click on Update jobs list button, you will see that the job failed with the following Exit Status: Error : org.hibernate.exception.ConstraintViolationException: could not execute statement. This was caused because we tried to insert a duplicate record at the Database.

+

This time we will not fix the file. Just click on Restart button again. If you click on Update jobs list button, you will see that the job was marked as ABANDONED this time because it was restarted once. Notice that there is a new parameter: restartedOnce=true. This behavior was implemented at JobListener for demonstration purpose to avoid that a FAILED job that was already restarted once, to be restarted twice.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + + \ No newline at end of file diff --git a/batch-processing/README.md b/batch-processing/README.md index 67935965c7..cf55536353 100644 --- a/batch-processing/README.md +++ b/batch-processing/README.md @@ -4,8 +4,8 @@ Author: Rafael Benevides Level: Intermediate Technologies: CDI, Batch 1.0, JSF Summary: The `batch-processing` quickstart shows how to use chunk oriented batch jobs to import a file to a database. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? @@ -19,46 +19,46 @@ The Job contains two steps (tasks): The database schema defines that the column for name is unique. For that reason, any atempt to persist a duplicate value will throw an exception. On the second attempt to run the job, the `ChunkCheckpoint` will provide information to skip the Contacts that were already persisted. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/batch-processing.war` to the running instance of the server. ## Access the Application -Access the running application in a browser at the following URL: +Access the running application in a browser at the following URL: You are presented with a simple form that allows you to generate sample files to be imported. @@ -148,7 +148,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -157,7 +157,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/batch-processing/pom.xml b/batch-processing/pom.xml index 983455796a..92074137df 100644 --- a/batch-processing/pom.xml +++ b/batch-processing/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/bean-validation-custom-constraint/README.html b/bean-validation-custom-constraint/README.html new file mode 100644 index 0000000000..7ff55abd25 --- /dev/null +++ b/bean-validation-custom-constraint/README.html @@ -0,0 +1,75 @@ + + + bean-validation-custom-constraint: Bean Validation Using Custom Constraints + + + +

bean-validation-custom-constraint: Bean Validation Using Custom Constraints

+

Author: Giriraj Sharma
+Level: Beginner
+Technologies: CDI, JPA, BV
+Summary: The bean-validation-custom-constraint quickstart demonstrates how to use the Bean Validation API to define custom constraints and validators.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it

+

The bean-validation-custom-constraint quickstart demonstrates how to use CDI, JPA, and Bean Validation in Red Hat JBoss Enterprise Application Platform. Bean Validation API allows the developers to define their own constraints by creating a new annotation and writing the validator which is used to validate the value. This quickstart will show you how to create custom constraints and then use it to validate your data. It includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java.

+

This quickstart does not contain a user interface layer. The purpose of this project is to show you how to test bean validation using custom constraints with Arquillian. In this quickstart, the personAddress field of entity Person is validated using a set of custom constraints defined in the class AddressValidator. If you want to see an example of how to test bean validation with a user interface, look at the kitchensink example.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

When you run the tests, JUnit will present you test report summary:

+
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+

If you are interested in more details, look in the target/surefire-reports directory.

+

You can also check the server console output to verify that the Arquillian tests deployed to and ran in the application server. Search for lines similar to the following ones in the server output log:

+
INFO [org.jboss.as.server.deployment] (MSC service thread 1-5) WFLYSRV0027: Starting deployment of "test.war" (runtime-name: "test.war")
+...
+INFO [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "test.war" (runtime-name : "test.war")
+...
+INFO [org.jboss.as.server.deployment] (MSC service thread 1-3) WFLYSRV0028: Stopped deployment test.war (runtime-name: test.war) in 32ms
+...
+INFO [[org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0009: Undeployed "test.war" (runtime-name: "test.war")
+
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Test the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+

You may see the following message when you run the command. It indicates the source is not provided in the third-party antlr JAR.

+
    [INFO] The following files have NOT been resolved:
+    [INFO]    antlr:antlr:jar:sources:2.7.7:provided
+
+ + \ No newline at end of file diff --git a/bean-validation-custom-constraint/README.md b/bean-validation-custom-constraint/README.md index 8fe897d9af..91ec2c0e98 100644 --- a/bean-validation-custom-constraint/README.md +++ b/bean-validation-custom-constraint/README.md @@ -4,52 +4,52 @@ Author: Giriraj Sharma Level: Beginner Technologies: CDI, JPA, BV Summary: The `bean-validation-custom-constraint` quickstart demonstrates how to use the Bean Validation API to define custom constraints and validators. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it -The `bean-validation-custom-constraint` quickstart demonstrates how to use CDI, JPA, and Bean Validation in ${product.name.full}. Bean Validation API allows the developers to define their own constraints by creating a new annotation and writing the validator which is used to validate the value. This quickstart will show you how to create custom constraints and then use it to validate your data. It includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java. +The `bean-validation-custom-constraint` quickstart demonstrates how to use CDI, JPA, and Bean Validation in Red Hat JBoss Enterprise Application Platform. Bean Validation API allows the developers to define their own constraints by creating a new annotation and writing the validator which is used to validate the value. This quickstart will show you how to create custom constraints and then use it to validate your data. It includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java. This quickstart does not contain a user interface layer. The purpose of this project is to show you how to test bean validation using custom constraints with Arquillian. In this quickstart, the personAddress field of entity Person is validated using a set of custom constraints defined in the class AddressValidator. If you want to see an example of how to test bean validation with a user interface, look at the [kitchensink](../kitchensink/README.md) example. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -81,7 +81,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Test the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/bean-validation-custom-constraint/pom.xml b/bean-validation-custom-constraint/pom.xml index 2fc2dcf96b..b58861c2c3 100644 --- a/bean-validation-custom-constraint/pom.xml +++ b/bean-validation-custom-constraint/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/bean-validation/README.html b/bean-validation/README.html new file mode 100644 index 0000000000..0b4245c41c --- /dev/null +++ b/bean-validation/README.html @@ -0,0 +1,72 @@ + + + bean-validation: Bean Validation Tested Using Arquillian + + + +

bean-validation: Bean Validation Tested Using Arquillian

+

Author: Karel Piwko
+Level: Beginner
+Technologies: CDI, JPA, BV
+Summary: The bean-validation quickstart provides Arquillian tests to demonstrate how to use CDI, JPA, and Bean Validation.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The bean-validation quickstart demonstrates how to use CDI, JPA, and Bean Validation in Red Hat JBoss Enterprise Application Platform. It includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java.

+

This quickstart does not contain a user interface layer. The purpose of this project is to show you how to test bean validation with Arquillian. If you want to see an example of how to test bean validation with a user interface, look at the kitchensink example.

+

This quickstart is a basic example of bean validation and is not localized. Because it is not localized, English messages are hard-coded in the constraint annotations in the Member class to ensure the test violation messages are matched when running the JBoss EAP server using another language. For examples of localized quickstarts, see the kitchensink-ml, kitchensink-ml-ear, and logging-tools quickstarts.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

When you run the tests, JUnit will present you test report summary:

+
Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
+
+

If you are interested in more details, look in the target/surefire-reports directory.

+

You can also check the server console output to verify that the Arquillian tests deployed to and ran in the application server. Search for lines similar to the following ones in the server output log:

+
INFO [org.jboss.as.server.deployment] (MSC service thread 1-5) WFLYSRV0027: Starting deployment of "test.war" (runtime-name: "test.war")
+...
+INFO [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "test.war" (runtime-name : "test.war")
+...
+INFO [org.jboss.as.server.deployment] (MSC service thread 1-3) WFLYSRV0028: Stopped deployment test.war (runtime-name: test.war) in 32ms
+...
+INFO [[org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0009: Undeployed "test.war" (runtime-name: "test.war")
+
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/bean-validation/README.md b/bean-validation/README.md index abc6d8bd48..a256f7ef64 100644 --- a/bean-validation/README.md +++ b/bean-validation/README.md @@ -4,53 +4,53 @@ Author: Karel Piwko Level: Beginner Technologies: CDI, JPA, BV Summary: The `bean-validation` quickstart provides Arquillian tests to demonstrate how to use CDI, JPA, and Bean Validation. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `bean-validation` quickstart demonstrates how to use CDI, JPA, and Bean Validation in ${product.name.full}. It includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java. +The `bean-validation` quickstart demonstrates how to use CDI, JPA, and Bean Validation in Red Hat JBoss Enterprise Application Platform. It includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java. This quickstart does not contain a user interface layer. The purpose of this project is to show you how to test bean validation with Arquillian. If you want to see an example of how to test bean validation with a user interface, look at the [kitchensink](../kitchensink/README.md) example. -This quickstart is a basic example of bean validation and is not localized. Because it is not localized, English messages are hard-coded in the constraint annotations in the `Member` class to ensure the test violation messages are matched when running the ${product.name} server using another language. For examples of localized quickstarts, see the `kitchensink-ml`, `kitchensink-ml-ear`, and `logging-tools` quickstarts. +This quickstart is a basic example of bean validation and is not localized. Because it is not localized, English messages are hard-coded in the constraint annotations in the `Member` class to ensure the test violation messages are matched when running the JBoss EAP server using another language. For examples of localized quickstarts, see the `kitchensink-ml`, `kitchensink-ml-ear`, and `logging-tools` quickstarts. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -83,7 +83,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/bean-validation/pom.xml b/bean-validation/pom.xml index 390e4a2106..cc19cdd64b 100644 --- a/bean-validation/pom.xml +++ b/bean-validation/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/bmt/README.html b/bmt/README.html new file mode 100644 index 0000000000..c7fe831f9e --- /dev/null +++ b/bmt/README.html @@ -0,0 +1,78 @@ + + + bmt: Bean Managed Transactions with JPA and JTA + + + +

bmt: Bean Managed Transactions with JPA and JTA

+

Author: Mike Musgrove
+Level: Intermediate
+Technologies: EJB, BMT
+Summary: The bmt quickstart demonstrates Bean-Managed Transactions (BMT), showing how to manually manage transaction demarcation while accessing JPA entities.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The bmt quickstart demonstrates how to manually manage transaction demarcation while accessing JPA entities in Red Hat JBoss Enterprise Application Platform.

+

On occasion, the application developer requires finer grained control over the lifecycle of JTA transactions and JPA Entity Managers than the defaults provided by the Java EE container. This example shows how the developer can override these defaults and take control of aspects of the lifecycle of JPA and transactions.

+

When you run this example, you will be provided with a Use bean managed Entity Managers checkbox. * If you check the checkbox, it shows the developer responsibilities when injecting an Entity Manager into a managed (stateless) bean. * If you uncheck the checkbox, shows the developer responsibilities when using JPA and transactions with an unmanaged component.

+

JBoss EAP ships with H2, an in-memory database written in Java. This example shows how to transactionally insert key value pairs into the H2 database and demonstrates the requirements on the developer with respect to the JPA Entity Manager.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

NOTE: A Java EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/bmt.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/bmt/.

+

You will be presented with a simple form for adding key/value pairs and a checkbox to indicate whether the updates should be executed using an unmanaged component. Effectively this will run the transaction and JPA updates in the servlet, not session beans. If the box is checked then the updates will be executed within a session bean method.

+
    +
  1. To list all pairs leave the key input box empty.
    2. +
  2. To add or update the value of a key fill in the key and value input boxes.
    3. +
  3. Press the submit button to see the results.
    4. +
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/bmt/README.md b/bmt/README.md index d26f9d4142..74144c7294 100644 --- a/bmt/README.md +++ b/bmt/README.md @@ -4,12 +4,12 @@ Author: Mike Musgrove Level: Intermediate Technologies: EJB, BMT Summary: The `bmt` quickstart demonstrates Bean-Managed Transactions (BMT), showing how to manually manage transaction demarcation while accessing JPA entities. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `bmt` quickstart demonstrates how to manually manage transaction demarcation while accessing JPA entities in ${product.name.full}. +The `bmt` quickstart demonstrates how to manually manage transaction demarcation while accessing JPA entities in Red Hat JBoss Enterprise Application Platform. On occasion, the application developer requires finer grained control over the lifecycle of JTA transactions and JPA Entity Managers than the defaults provided by the Java EE container. This example shows how the developer can override these defaults and take control of aspects of the lifecycle of JPA and transactions. @@ -17,50 +17,50 @@ When you run this example, you will be provided with a `Use bean managed Entity * If you check the checkbox, it shows the developer responsibilities when injecting an Entity Manager into a managed (stateless) bean. * If you uncheck the checkbox, shows the developer responsibilities when using JPA and transactions with an unmanaged component. -${product.name} ships with H2, an in-memory database written in Java. This example shows how to transactionally insert key value pairs into the H2 database and demonstrates the requirements on the developer with respect to the JPA Entity Manager. +JBoss EAP ships with H2, an in-memory database written in Java. This example shows how to transactionally insert key value pairs into the H2 database and demonstrates the requirements on the developer with respect to the JPA Entity Manager. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ _NOTE: A Java EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/bmt.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . You will be presented with a simple form for adding key/value pairs and a checkbox to indicate whether the updates should be executed using an unmanaged component. Effectively this will run the transaction and JPA updates in the servlet, not session beans. If the box is checked then the updates will be executed within a session bean method. @@ -79,7 +79,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -88,7 +88,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/bmt/pom.xml b/bmt/pom.xml index 41ba0a67b9..7414cd94b0 100644 --- a/bmt/pom.xml +++ b/bmt/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/cdi-alternative/README.html b/cdi-alternative/README.html new file mode 100644 index 0000000000..102ca92950 --- /dev/null +++ b/cdi-alternative/README.html @@ -0,0 +1,76 @@ + + + cdi-alternative: Demonstrates CDI Alternatives + + + +

cdi-alternative: Demonstrates CDI Alternatives

+

Author: Nevin Zhu
+Level: Intermediate
+Technologies: CDI, Servlet, JSP
+Summary: The cdi-alternative quickstart demonstrates how to create a bean that can be implemented for different purposes without changing the source code.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The cdi-alternative quickstart demonstrates how to create beans that can be implemented for different purposes in Red Hat JBoss Enterprise Application Platform without changing the Java source code. Instead, you define the default and alternative (@Alternative) bean implementations during the development phase. Then at deployment time, rather than modifying the source code, you can choose to deploy the default or alternative beans by modifying the <alternatives> element in the WEB-INF/beans.xml file.

+

Alternatives can be used to customize deployments for specific situations, to handle client-side business logic that is determined at runtime, and to create dummy beans to be used for test purposes.

+

This quickstart demonstrates how to deploy an example with alternative sales tax rates. It defines the following classes, interfaces, and WEB-INF/beans.xml files:

+
    +
  • Demo: This class extends HttpServlet and handles the incoming servlet request. It gets the tax rate and returns it to the page.
    • +
  • Tax: This interface defines the getRate() method to get the tax rate.
    • +
  • TaxImpl_1: This is the default class that returns the Tax_1 rate.
    • +
  • TaxImpl_2: This is an alternative class that returns the Tax_2 rate. Note the @Alternative annotation in the class.
    • +
  • WEB-INF/beans.xml: This file specifies the TaxImpl_2 alternative should be used by the quickstart. To use the default TaxImpl_1 class, delete or comment out the <alternatives> element and redeploy the quickstart.
    • +
  • result.jsp: The JSP page that displays the tax rate.
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This deploys target/cdi-alternative.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/cdi-alternative/.

+

You can specify alternative versions of the bean in the WEB-INF/beans.xml file by doing one of the following:

+
    +
  1. You can remove the <alternatives> tag so that it defaults to use TaxImpl_1.
    2. +
  2. You can create another alternative bean class and use that class name as an alternative.
    3. +
+

In this quickstart, in order to switch back to the default implementation, comment the <alternatives> block in the WEB-INF/beans.xml file and redeploy the quickstart.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/cdi-alternative/README.md b/cdi-alternative/README.md index fe22e240ab..2e775a7cdb 100644 --- a/cdi-alternative/README.md +++ b/cdi-alternative/README.md @@ -4,12 +4,12 @@ Author: Nevin Zhu Level: Intermediate Technologies: CDI, Servlet, JSP Summary: The `cdi-alternative` quickstart demonstrates how to create a bean that can be implemented for different purposes without changing the source code. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `cdi-alternative` quickstart demonstrates how to create beans that can be implemented for different purposes in ${product.name.full} without changing the Java source code. Instead, you define the default and alternative (`@Alternative`) bean implementations during the development phase. Then at deployment time, rather than modifying the source code, you can choose to deploy the default or alternative beans by modifying the `` element in the `WEB-INF/beans.xml` file. +The `cdi-alternative` quickstart demonstrates how to create beans that can be implemented for different purposes in Red Hat JBoss Enterprise Application Platform without changing the Java source code. Instead, you define the default and alternative (`@Alternative`) bean implementations during the development phase. Then at deployment time, rather than modifying the source code, you can choose to deploy the default or alternative beans by modifying the `` element in the `WEB-INF/beans.xml` file. Alternatives can be used to customize deployments for specific situations, to handle client-side business logic that is determined at runtime, and to create dummy beans to be used for test purposes. @@ -25,39 +25,39 @@ This quickstart demonstrates how to deploy an example with alternative sales tax ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This deploys `target/${project.artifactId}.war` to the running instance of the server. +4. This deploys `target/cdi-alternative.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . You can specify alternative versions of the bean in the `WEB-INF/beans.xml` file by doing one of the following: @@ -69,7 +69,7 @@ comment the `` block in the `WEB-INF/beans.xml` file and redeploy ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -78,7 +78,7 @@ comment the `` block in the `WEB-INF/beans.xml` file and redeploy ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/cdi-alternative/pom.xml b/cdi-alternative/pom.xml index dd3be82f1e..1d464d686e 100644 --- a/cdi-alternative/pom.xml +++ b/cdi-alternative/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml cdi-alternative diff --git a/cdi-decorator/README.html b/cdi-decorator/README.html new file mode 100644 index 0000000000..b948ae7cbe --- /dev/null +++ b/cdi-decorator/README.html @@ -0,0 +1,75 @@ + + + cdi-decorator: Demonstrates CDI Decorator + + + +

cdi-decorator: Demonstrates CDI Decorator

+

Author: Ievgen Shulga
+Level: Intermediate
+Technologies: CDI, JSF
+Summary: The cdi-decorator quickstart demonstrates the use of a CDI Decorator to intercept bean methods and modify the business logic.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The cdi-decorator quickstart demonstrates the use of CDI decorators in Red Hat JBoss Enterprise Application Platform. A decorator implements one or more bean types and intercepts business method invocations of beans which implement those bean types. These bean types are called decorated types.

+

Decorators are similar to interceptors, but because they directly implement operations with business semantics, they are able to implement business logic and, conversely, unable to implement the cross-cutting concerns for which interceptors are optimized.

+

Decorators may be associated with any managed bean that is not itself an interceptor or decorator or with any EJB session bean. A decorator instance is a dependent object of the object it decorates.

+

This example represents a common decorator design pattern. We take a class and we wrap decorator class around it. When we call the class, we always pass through the surrounding decorator class before we reach the inner class. In this example, the decorator class simply changes the staff bonus from 100 to 200 and the staff position from Java Developer to Team Lead. It then logs a message to the server console.

+

By default, all decorators are disabled, so the application will run without using decorator. We need to enable our decorator in the WEB-INF/beans.xml descriptor to make it work.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/cdi-decorator.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/cdi-decorator.

+

You can specify decorator of the bean in the WEB-INF/beans.xml file by doing one of the following:

+
    +
  1. You can add a decorators tag and specify a decorator class.
    2. +
  2. You can specify a different decorator class name in the decorators tag.
    3. +
+

For this example, uncomment the <decorators> tag in the WEB-INF/beans.xml file and redeploy the application. When you access the application, you will see changed information from web-browser and following in the server log:

+
CDI decorator method was called!
+CDI decorator method was called!
+
+

The message appears twice because the decorator is called twice, once to get the staff position and then again to get the staff bonus.

+

In order to switch back to the default implementation, comment the decorators block in the WEB-INF/beans.xml file and redeploy the quickstart.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/cdi-decorator/README.md b/cdi-decorator/README.md index e435e05267..3173fc7713 100644 --- a/cdi-decorator/README.md +++ b/cdi-decorator/README.md @@ -4,12 +4,12 @@ Author: Ievgen Shulga Level: Intermediate Technologies: CDI, JSF Summary: The `cdi-decorator` quickstart demonstrates the use of a CDI Decorator to intercept bean methods and modify the business logic. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `cdi-decorator` quickstart demonstrates the use of CDI decorators in ${product.name.full}. +The `cdi-decorator` quickstart demonstrates the use of CDI decorators in Red Hat JBoss Enterprise Application Platform. A decorator implements one or more bean types and intercepts business method invocations of beans which implement those bean types. These bean types are called decorated types. @@ -28,39 +28,39 @@ By default, all decorators are disabled, so the application will run without usi ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/cdi-decorator.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . You can specify decorator of the bean in the `WEB-INF/beans.xml` file by doing one of the following: @@ -78,7 +78,7 @@ In order to switch back to the default implementation, comment the `decorators` ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -87,7 +87,7 @@ In order to switch back to the default implementation, comment the `decorators` ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/cdi-decorator/pom.xml b/cdi-decorator/pom.xml index 17d120f743..36c6a71a0b 100644 --- a/cdi-decorator/pom.xml +++ b/cdi-decorator/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml cdi-decorator diff --git a/cdi-injection/README.html b/cdi-injection/README.html new file mode 100644 index 0000000000..a7ee44f9f1 --- /dev/null +++ b/cdi-injection/README.html @@ -0,0 +1,61 @@ + + + cdi-injection: Example Using CDI (Contexts and Dependency Injection) + + + +

cdi-injection: Example Using CDI (Contexts and Dependency Injection)

+

Author: Jason Porter
+Level: Beginner
+Technologies: CDI, JSF
+Summary: The cdi-injection quickstart demonstrates the use of CDI Injection and Qualifiers in JBoss EAP with a JSF front-end client.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The cdi-injection quickstart demonstrates the use of CDI Injection and Qualifiers in Red Hat JBoss Enterprise Application Platform, with JSF as the front-end client.

+

Any Java class which has a no-argument constructor and is in an archive with a WEB-INF/beans.xml is available for lookup and injection. For EL resolution, it must be annotated @Named.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/cdi-injection.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/cdi-injection/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/cdi-injection/README.md b/cdi-injection/README.md index e06d77c343..10fa80a22d 100644 --- a/cdi-injection/README.md +++ b/cdi-injection/README.md @@ -3,55 +3,55 @@ Author: Jason Porter Level: Beginner Technologies: CDI, JSF -Summary: The `cdi-injection` quickstart demonstrates the use of *CDI Injection and Qualifiers* in ${product.name} with a JSF front-end client. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `cdi-injection` quickstart demonstrates the use of *CDI Injection and Qualifiers* in JBoss EAP with a JSF front-end client. +Target Product: JBoss EAP +Source: ## What is it? -The `cdi-injection` quickstart demonstrates the use of *CDI Injection and Qualifiers* in ${product.name.full}, with JSF as the front-end client. +The `cdi-injection` quickstart demonstrates the use of *CDI Injection and Qualifiers* in Red Hat JBoss Enterprise Application Platform, with JSF as the front-end client. Any Java class which has a no-argument constructor and is in an archive with a `WEB-INF/beans.xml` is available for lookup and injection. For EL resolution, it must be annotated `@Named`. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/cdi-injection.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -60,7 +60,7 @@ The application will be running at the following URL org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml cdi-injection diff --git a/cdi-interceptors/README.html b/cdi-interceptors/README.html new file mode 100644 index 0000000000..a433be9c11 --- /dev/null +++ b/cdi-interceptors/README.html @@ -0,0 +1,86 @@ + + + cdi-interceptors: Example Using CDI Interceptors + + + +

cdi-interceptors: Example Using CDI Interceptors

+

Author: Ievgen Shulga
+Level: Intermediate
+Technologies: JPA, JSF, EJB
+Summary: The cdi-interceptors quickstart demonstrates how to use CDI interceptors for cross-cutting concerns such as logging and simple auditing.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The cdi-interceptors quickstart demonstrates how to use CDI interceptors for cross-cutting concerns such as logging and simple auditing in applications deployed to Red Hat JBoss Enterprise Application Platform. Interceptors can be applied to any business methods or beans, simply by adding appropriate interceptor binding type annotation. The project contains EJB service that can create and retrieve object from database. This example demonstrates 2 interceptors: AuditInterceptor and LoggingInterceptor

+

The quickstart defines the @Audit and @Logging interceptor binding types. The AuditInterceptor and LoggingInterceptor classes are annotated with the binding type annotation and contain a method annotated @AroundInvoke. If the interceptor is enabled, this method will be called when the intercepted methods are invoked. In the ItemServiceBean bean, notice the create()and getList() methods are annotated with the @Audit and @Logging binding types. This means the aroundInvoke() method in the AuditInterceptor and LoggingInterceptor classes will be called when the ItemServiceBean bean's create() and getList() methods are called, but only if that interceptor is enabled. To enable an interceptor, you must add the interceptor class to the WEB-INF/beans.xml descriptor file.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/cdi-interceptors.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/cdi-interceptors.

+

You can now comment out classes in the WEB-INF/beans.xml file to disable one or both of the interceptors and view the results.

+
    +
  • Comment the <class>org.jboss.as.quickstarts.cdi.interceptor.AuditInterceptor</class> and you will no longer see the audit history on the browser page.
    • +
  • Comment the <class>org.jboss.as.quickstarts.cdi.interceptor.LoggingInterceptor</class> and you will no longer see the log messages in the server log.
    • +
+

In this quickstart, in order to switch back to the default implementation, comment the interceptors block in the WEB-INF/beans.xml file and redeploy the quickstart.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/cdi-interceptors/README.md b/cdi-interceptors/README.md index a9734d52b3..3ddb050ea3 100644 --- a/cdi-interceptors/README.md +++ b/cdi-interceptors/README.md @@ -4,57 +4,57 @@ Author: Ievgen Shulga Level: Intermediate Technologies: JPA, JSF, EJB Summary: The `cdi-interceptors` quickstart demonstrates how to use CDI interceptors for cross-cutting concerns such as logging and simple auditing. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `cdi-interceptors` quickstart demonstrates how to use CDI interceptors for cross-cutting concerns such as logging and simple auditing in applications deployed to ${product.name.full}. +The `cdi-interceptors` quickstart demonstrates how to use CDI interceptors for cross-cutting concerns such as logging and simple auditing in applications deployed to Red Hat JBoss Enterprise Application Platform. Interceptors can be applied to any business methods or beans, simply by adding appropriate interceptor binding type annotation. The project contains EJB service that can create and retrieve object from database. This example demonstrates 2 interceptors: `AuditInterceptor` and `LoggingInterceptor` The quickstart defines the `@Audit` and `@Logging` interceptor binding types. The `AuditInterceptor` and `LoggingInterceptor` classes are annotated with the binding type annotation and contain a method annotated `@AroundInvoke`. If the interceptor is enabled, this method will be called when the intercepted methods are invoked. In the `ItemServiceBean` bean, notice the `create()`and `getList()` methods are annotated with the `@Audit` and `@Logging` binding types. This means the `aroundInvoke()` method in the `AuditInterceptor` and `LoggingInterceptor` classes will be called when the `ItemServiceBean` bean's `create()` and `getList()` methods are called, but only if that interceptor is enabled. To enable an interceptor, you must add the interceptor class to the `WEB-INF/beans.xml` descriptor file. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/cdi-interceptors.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . You can now comment out classes in the `WEB-INF/beans.xml` file to disable one or both of the interceptors and view the results. @@ -75,7 +75,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -86,18 +86,18 @@ _Note:_ You will see the following warnings in the server log. You can ignore th This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/cdi-interceptors/pom.xml b/cdi-interceptors/pom.xml index 7e4df4d77f..cec625784f 100644 --- a/cdi-interceptors/pom.xml +++ b/cdi-interceptors/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml cdi-interceptors diff --git a/cdi-portable-extension/README.html b/cdi-portable-extension/README.html new file mode 100644 index 0000000000..59edf42791 --- /dev/null +++ b/cdi-portable-extension/README.html @@ -0,0 +1,93 @@ + + + cdi-portable-extension: CDI Portable Extension + + + +

cdi-portable-extension: CDI Portable Extension

+

Author: Jason Porter
+Level: Intermediate
+Technologies: CDI
+Summary: The cdi-portable-extension quickstart demonstrates a simple CDI Portable Extension that uses SPI classes to inject beans with data from an XML file.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The cdi-portable-extension quickstart demonstrates how to use some of the SPI classes to create a simple CDI portable extension in an application deployed to Red Hat JBoss Enterprise Application Platform.

+

CDI exposes a set of SPIs to allow development of portable extensions to CDI. A portable extension is an extension to Java EE 6 and above that is tailored to a specific use case and runs on any Java EE 6 or later implementation. Portable extensions can implement features not yet supported by the specifications, such as type-safe messages or external configuration of beans.

+

This particular extension explores the ProcessInjectionTarget and InjectionTarget SPI classes of CDI to demonstrate one possible way to seed data into beans. It uses the ProcessInjectionTarget to create and add state to beans using XML. It is similar to the Seam XML configuration idea from Seam 3, but is much more simplistic.

+

The project contains very simple domain model classes, an extension class, the service registration file for that extension and an Arquillian test to verify the extension is working correctly.

+
    +
  • CreatureExtension: Class that implements Extension. This is the first step in creating a portable extension. It is not a bean since it is instantiated by the container during the initialization process, before any beans or contexts exist. However, it can be injected into other beans once the initialization process is complete.
    • +
  • XmlBackedWrappedInjectionTarget: Wrapper class for the standard @link InjectionTarget to add the field values from the XML file.
    • +
  • CreatureType: An enum in the model package. It defines the two types of creatures, MONSTER and NPC.
    • +
  • Creature: The interface in the model package. Defines the name and type of creature.
    • +
  • Monster: Class in the model package that implments creature with a type MONSTER.
    • +
  • NonPlayerCharacter: Class in the model package that implements creature with a type NPC.
    • +
  • META-INF/creatures.xml: The XML in this file seeds the bean with data.
    • +
  • META-INF/creatures.xsd: The schema for the XML that seeds the bean with data.
    • +
+

On application start, there will be one instance of Monster with a name of Cat, hitpoints of 10 and an initiative of 25. There will also be one instance of NonPlayerCharacter with name of Drunkard and location of Drunken Duck Tavern. There is no instantiation code for the object outside of the CDI extension.

+

Note: This quickstart does not contain any user interface. Instead, you run tests and check server log messages to verify everything is working correctly.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

Maven prints a summary of the two performed tests to the console.

+
-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.jboss.as.quickstart.cdi.extension.test.CreatureExtensionTest
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.87 sec
+
+Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+

Server log

+

The following messages are written to the server log when the tests are run:

+
INFO  [org.jboss.as.server.deployment] (MSC service thread 1-6) WFLYSRV0027: Starting deployment of "test.war" (runtime-name: "test.war")
+...
+INFO  [org.jboss.as.quickstart.cdi.extension.CreatureExtension] (MSC service thread 1-3) Setting up injection target for class org.jboss.as.quickstart.cdi.extension.model.Monster
+[timestamp] INFO  [org.jboss.as.quickstart.cdi.extension.CreatureExtension] (MSC service thread 1-3) Setting up injection target for class org.jboss.as.quickstart.cdi.extension.model.NonPlayerCharacter
+...
+INFO  [org.jboss.as.server] (management-handler-thread - 6) WFLYSRV0010: Deployed "test.war" (runtime-name : "test.war")
+...
+[timestamp] INFO  [org.jboss.as.server.deployment] (MSC service thread 1-4) WFLYSRV0028: Stopped deployment test.war (runtime-name: test.war) in 27ms
+...
+INFO  [org.jboss.as.server] (management-handler-thread - 6) WFLYSRV0009: Undeployed "test.war" (runtime-name: "test.war")
+
+

The two statements to look for are these:

+
INFO  [org.jboss.as.quickstart.cdi.extension.CreatureExtension] (MSC service thread 1-3) Setting up injection target for class org.jboss.as.quickstart.cdi.extension.model.Monster
+
+INFO  [org.jboss.as.quickstart.cdi.extension.CreatureExtension] (MSC service thread 1-3) Setting up injection target for class org.jboss.as.quickstart.cdi.extension.model.NonPlayerCharacter
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/cdi-portable-extension/README.md b/cdi-portable-extension/README.md index 691156e06c..a22b683fe2 100644 --- a/cdi-portable-extension/README.md +++ b/cdi-portable-extension/README.md @@ -4,12 +4,12 @@ Author: Jason Porter Level: Intermediate Technologies: CDI Summary: The `cdi-portable-extension` quickstart demonstrates a simple CDI Portable Extension that uses SPI classes to inject beans with data from an XML file. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `cdi-portable-extension` quickstart demonstrates how to use some of the SPI classes to create a simple CDI portable extension in an application deployed to ${product.name.full}. +The `cdi-portable-extension` quickstart demonstrates how to use some of the SPI classes to create a simple CDI portable extension in an application deployed to Red Hat JBoss Enterprise Application Platform. CDI exposes a set of SPIs to allow development of portable extensions to CDI. A portable extension is an extension to Java EE 6 and above that is tailored to a specific use case and runs on any Java EE 6 or later implementation. Portable extensions can implement features not yet supported by the specifications, such as type-safe messages or external configuration of beans. @@ -34,36 +34,36 @@ _Note:_ This quickstart does not contain any user interface. Instead, you run te ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -104,7 +104,7 @@ The two statements to look for are these: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/cdi-portable-extension/pom.xml b/cdi-portable-extension/pom.xml index 679f131cf5..17d31d62f4 100644 --- a/cdi-portable-extension/pom.xml +++ b/cdi-portable-extension/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml cdi-portable-extension diff --git a/cdi-stereotype/README.html b/cdi-stereotype/README.html new file mode 100644 index 0000000000..1f19b208e9 --- /dev/null +++ b/cdi-stereotype/README.html @@ -0,0 +1,82 @@ + + + cdi-stereotype: Example Using CDI Stereotype. + + + +

cdi-stereotype: Example Using CDI Stereotype.

+

Author: Ievgen Shulga
+Level: Intermediate
+Technologies: JPA, JSF, EJB
+Summary: The cdi-stereotype quickstart demonstrates how to apply CDI stereotypes to beans to encapsulate CDI interceptor bindings and CDI alternatives.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The cdi-stereotype quickstart is an extension of the cdi-interceptors quickstart and demonstrates how to use a CDI stereotype in Red Hat JBoss Enterprise Application Platform.

+

A stereotype is an annotation, annotated @Stereotype, that packages several other annotations. Stereotypes allow a developer to declare common metadata for beans in a central place.

+

In this example, the stereotype encapsulates the following :

+
    +
  • All beans with this stereotype inherit the following interceptor bindings: @Logging and @Audit
    • +
  • All beans with this stereotype are alternatives
    • +
+

This quickstart defines stereotype with 2 interceptors bindings (@Logging and @Audit) to be inherited by all beans with that stereotype. It also indicates that all beans to which it is applied are @Alternatives. An alternative stereotype lets us classify beans by deployment scenario. Arquillian tests added in cdi-interceptors quickstart.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the JBoss EAP Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/cdi-stereotype.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/cdi-stereotype/

+

You can now comment out classes in the WEB-INF/beans.xml file to disable one or both of the interceptors or alternative stereotype and view the results.

+
    +
  • Comment the <class>org.jboss.as.quickstarts.cdi.interceptor.AuditInterceptor</class> and you will no longer see the audit history on the browser page.
    • +
  • Comment the <class>org.jboss.as.quickstarts.cdi.interceptor.LoggingInterceptor</class> and you will no longer see the log messages in the server log.
    • +
  • Comment the <stereotype>org.jboss.as.quickstarts.cdi.interceptor.ServiceStereotype</stereotype> and you no longer see ItemAlternativeServiceBean implementation invoked.
    • +
+

In this quickstart, in order to switch back to the default implementation, uncomment the <interceptors> and <stereotype> block in the WEB-INF/beans.xml file and redeploy the quickstart.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/cdi-stereotype/README.md b/cdi-stereotype/README.md index 642c2645cf..48193e7995 100644 --- a/cdi-stereotype/README.md +++ b/cdi-stereotype/README.md @@ -4,12 +4,12 @@ Author: Ievgen Shulga Level: Intermediate Technologies: JPA, JSF, EJB Summary: The `cdi-stereotype` quickstart demonstrates how to apply CDI stereotypes to beans to encapsulate CDI interceptor bindings and CDI alternatives. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `cdi-stereotype` quickstart is an extension of the [cdi-interceptors](../cdi-interceptors/README.md) quickstart and demonstrates how to use a CDI stereotype in ${product.name.full}. +The `cdi-stereotype` quickstart is an extension of the [cdi-interceptors](../cdi-interceptors/README.md) quickstart and demonstrates how to use a CDI stereotype in Red Hat JBoss Enterprise Application Platform. A stereotype is an annotation, annotated `@Stereotype`, that packages several other annotations. Stereotypes allow a developer to declare common metadata for beans in a central place. @@ -21,46 +21,46 @@ In this example, the stereotype encapsulates the following : This quickstart defines stereotype with 2 interceptors bindings (`@Logging` and `@Audit`) to be inherited by all beans with that stereotype. It also indicates that all beans to which it is applied are `@Alternatives`. An alternative stereotype lets us classify beans by deployment scenario. Arquillian tests added in [cdi-interceptors](../cdi-interceptors/README.md) quickstart. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). -## Start the ${product.name} Server +## Start the JBoss EAP Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/cdi-stereotype.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL +The application will be running at the following URL You can now comment out classes in the `WEB-INF/beans.xml` file to disable one or both of the interceptors or alternative stereotype and view the results. @@ -82,7 +82,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -91,7 +91,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/cdi-stereotype/pom.xml b/cdi-stereotype/pom.xml index 26e49da756..ae1f309e63 100644 --- a/cdi-stereotype/pom.xml +++ b/cdi-stereotype/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml cdi-stereotype diff --git a/cdi-veto/README.html b/cdi-veto/README.html new file mode 100644 index 0000000000..1116fe5a60 --- /dev/null +++ b/cdi-veto/README.html @@ -0,0 +1,80 @@ + + + cdi-veto: A Simple CDI Portable Extension Example + + + +

cdi-veto: A Simple CDI Portable Extension Example

+

Author: Jason Porter
+Level: Intermediate
+Technologies: CDI
+Summary: The cdi-veto quickstart is a simple CDI Portable Extension that uses SPI classes to show how to remove beans and inject JPA entities into an application.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The cdi-veto quickstart demonstrates a simple CDI portable extension and some of the SPI classes used to complete that task in an application deployed to Red Hat JBoss Enterprise Application Platform. This particular extension explores the ProcessInjectionTarget and InjectionTarget SPI classes of CDI to demonstrate removing a bean from CDI's knowledge and correctly injecting JPA entities in your application.

+

A portable extension is an extension to Java EE 6 and above, which is tailored to a specific use case and will run on any Java EE 6 or later implementation. Portable extensions can implement features not yet supported by the specifications, such as type-safe messages or external configuration of beans.

+

The project contains very simple domain model classes, an extension class, the service provider configuration file, and an Arquillian test to verify the extension is working correctly.

+

This quickstart does not contain any user interface. The tests must be run to verify everything is working correctly.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

Maven prints summary of the 4 performed tests to the console.

+
-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.jboss.as.quickstart.cdi.veto.test.InjectionWithoutVetoExtensionWithManagerTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.492 sec
+Running org.jboss.as.quickstart.cdi.veto.test.InjectionWithVetoExtensionAndManagerTest
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 7.988 sec
+Running org.jboss.as.quickstart.cdi.veto.test.InjectionWithVetoExtensionWithoutManagerTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.093 sec
+
+Results :
+
+Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
+
+

In the server log you see a few lines similar to

+
         INFO  [VetoExtension] (MSC service thread 1-8) Vetoed class class org.jboss.as.quickstart.cdi.veto.model.Car
+         INFO  [CarManager] (http--127.0.0.1-8080-2) Returning new instance of Car
+
+

That will let you know the extension is working. To really see what is going on and understand this example, please read the source and the tests.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/cdi-veto/README.md b/cdi-veto/README.md index a22cdfcf87..90b2e838c0 100644 --- a/cdi-veto/README.md +++ b/cdi-veto/README.md @@ -4,12 +4,12 @@ Author: Jason Porter Level: Intermediate Technologies: CDI Summary: The `cdi-veto` quickstart is a simple CDI Portable Extension that uses SPI classes to show how to remove beans and inject JPA entities into an application. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `cdi-veto` quickstart demonstrates a simple CDI portable extension and some of the SPI classes used to complete that task in an application deployed to ${product.name.full}. This particular extension explores the `ProcessInjectionTarget` and `InjectionTarget` SPI classes of CDI to demonstrate removing a bean from CDI's knowledge and correctly injecting JPA entities in your application. +The `cdi-veto` quickstart demonstrates a simple CDI portable extension and some of the SPI classes used to complete that task in an application deployed to Red Hat JBoss Enterprise Application Platform. This particular extension explores the `ProcessInjectionTarget` and `InjectionTarget` SPI classes of CDI to demonstrate removing a bean from CDI's knowledge and correctly injecting JPA entities in your application. A portable extension is an extension to Java EE 6 and above, which is tailored to a specific use case and will run on any Java EE 6 or later implementation. Portable extensions can implement features not yet supported by the specifications, such as type-safe messages or external configuration of beans. @@ -17,42 +17,42 @@ The project contains very simple domain model classes, an extension class, the s This quickstart does not contain any user interface. The tests must be run to verify everything is working correctly. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -92,7 +92,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/cdi-veto/pom.xml b/cdi-veto/pom.xml index 6987247da0..6110ecbd03 100644 --- a/cdi-veto/pom.xml +++ b/cdi-veto/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml cdi-veto diff --git a/cmt/README.html b/cmt/README.html new file mode 100644 index 0000000000..e8d750a03f --- /dev/null +++ b/cmt/README.html @@ -0,0 +1,96 @@ + + + cmt: Container Managed Transactions (CMT) + + + +

cmt: Container Managed Transactions (CMT)

+

Author: Tom Jenkinson
+Level: Intermediate
+Technologies: EJB, CMT, JMS
+Summary: The cmt quickstart demonstrates Container-Managed Transactions (CMT), showing how to use transactions managed by the container.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The cmt quickstart demonstrates using transactions managed by the container in Red Hat JBoss Enterprise Application Platform. It is a fairly typical scenario of updating a database and sending a JMS message in the same transaction. A simple MDB is provided that prints out the message sent but this is not a transactional MDB and is purely provided for debugging purposes.

+

Aspects touched upon in the code:

+
    +
  1. XA transaction control using the container managed transaction annotations
    2. +
  2. XA access to the standard default datasource using the JPA API
    3. +
  3. XA access to a JMS queue
    4. +
+

After users complete this quickstart, they are invited to run through the following quickstarts:

+
    +
  1. jts - The JTS quickstart builds upon this quickstart by distributing the CustomerManager and InvoiceManager
    2. +
  2. jts-distributed-crash-rec - The crash recovery quickstart builds upon the jts quickstart by demonstrating the fault tolerance of JBoss EAP.
    3. +
+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

What are Container Managed Transactions?

+

Prior to EJB, getting the right incantation to ensure sound transactional operation of the business logic was a highly specialised skill. Although this still holds true to a great extent, EJB has provided a series of improvements to allow simplified transaction demarcation notation that is therefore easier to read and test.

+

With CMT, the EJB container sets the boundaries of a transaction. This differs from BMT (bean managed transactions) where the developer is responsible for initiating and completing a transaction via the methods begin, commit, rollback on a javax.transaction.UserTransaction.

+

What Makes This an Example of Container Managed Transactions?

+

Take a look at org.jboss.as.quickstarts.cmt.ejb.CustomerManagerEJB. You can see that this stateless session bean has been marked up with the @javax.ejb.TransactionAttribute annotation.

+

The available options for this annotation are as follows:

+
    +
  • Required - As demonstrated in the quickstart. If a transaction does not already exist, this will initiate a transaction and complete it for you, otherwise the business logic will be integrated into the existing transaction
    • +
  • RequiresNew - If there is already a transaction running, it will be suspended, the work performed within a new transaction which is completed at exit of the method and then the original transaction resumed.
    • +
  • Mandatory - If there is no transaction running, calling a business method with this annotation will result in an error
    • +
  • NotSupported - If there is a transaction running, it will be suspended and no transaction will be initiated for this business method
    • +
  • Supports - This will run the method within a transaction if a transaction exists, alternatively, if there is no transaction running, the method will not be executed within the scope of a transaction
    • +
  • Never - If the client has a transaction running and does not suspend it but calls a method annotated with Never then an EJB exception will be raised.
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server with the Full Profile

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the full profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Open a command prompt and navigate to the root directory of this quickstart.
    2. +
  2. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    3. +
  3. +

    This will deploy target/cmt.war to the running instance of the server.

    +
    4. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/cmt/.

+

You will be presented with a simple form for adding customers to a database.

+

After a user is successfully added to the database, a message is produced containing the details of the user. An example MDB will dequeue this message and print the following contents:

+
Received Message: Created invoice for customer named:  Jack
+
+

When the same customer name is given, a duplicate warning is given and no JMS-message is send to cause the above message.

+

The customer name should match: letter & '-', otherwise an error is given. This is to show that a 'LogMessage' entity is still stored in the database thanks to the @TransactionAttribute(TransactionAttributeType.REQUIRES_NEW) that the method logCreateCustomer in the EJB LogMessageManagerEJB is decorated with.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

NOTE: Within JBoss Developer Studio, be sure to define a server runtime environment that uses the standalone-full.xml configuration file.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/cmt/README.md b/cmt/README.md index 8be54206a9..6f1737e519 100644 --- a/cmt/README.md +++ b/cmt/README.md @@ -4,12 +4,12 @@ Author: Tom Jenkinson Level: Intermediate Technologies: EJB, CMT, JMS Summary: The `cmt` quickstart demonstrates Container-Managed Transactions (CMT), showing how to use transactions managed by the container. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `cmt` quickstart demonstrates using transactions managed by the container in ${product.name.full}. It is a fairly typical scenario of updating a database and sending a JMS message in the same transaction. A simple MDB is provided that prints out the message sent but this is not a transactional MDB and is purely provided for debugging purposes. +The `cmt` quickstart demonstrates using transactions managed by the container in Red Hat JBoss Enterprise Application Platform. It is a fairly typical scenario of updating a database and sending a JMS message in the same transaction. A simple MDB is provided that prints out the message sent but this is not a transactional MDB and is purely provided for debugging purposes. Aspects touched upon in the code: @@ -20,9 +20,9 @@ Aspects touched upon in the code: After users complete this quickstart, they are invited to run through the following quickstarts: 1. [jts](../jts/README.md) - The JTS quickstart builds upon this quickstart by distributing the CustomerManager and InvoiceManager -2. [jts-distributed-crash-rec](../jts-distributed-crash-rec/README.md) - The crash recovery quickstart builds upon the [jts](../jts/README.md) quickstart by demonstrating the fault tolerance of ${product.name}. +2. [jts-distributed-crash-rec](../jts-distributed-crash-rec/README.md) - The crash recovery quickstart builds upon the [jts](../jts/README.md) quickstart by demonstrating the fault tolerance of JBoss EAP. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ ### What are Container Managed Transactions? @@ -47,23 +47,23 @@ The available options for this annotation are as follows: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server with the Full Profile -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the full profile: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml ## Build and Deploy the Quickstart @@ -73,11 +73,11 @@ In the following instructions, replace `${jboss.home.name}` with the actual path mvn clean install wildfly:deploy -3. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +3. This will deploy `target/cmt.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . You will be presented with a simple form for adding customers to a database. @@ -99,7 +99,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -108,7 +108,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). _NOTE:_ Within JBoss Developer Studio, be sure to define a server runtime environment that uses the `standalone-full.xml` configuration file. diff --git a/cmt/pom.xml b/cmt/pom.xml index 3dd5c42ce4..fd5bf51663 100644 --- a/cmt/pom.xml +++ b/cmt/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml cmt diff --git a/contacts-jquerymobile/README.html b/contacts-jquerymobile/README.html new file mode 100644 index 0000000000..ab4769c510 --- /dev/null +++ b/contacts-jquerymobile/README.html @@ -0,0 +1,165 @@ + + + contacts-jquerymobile: CRUD Example Using HTML5, jQuery Mobile and JAX-RS + + + +

contacts-jquerymobile: CRUD Example Using HTML5, jQuery Mobile and JAX-RS

+

Author: Joshua Wilson
+Level: Beginner
+Technologies: jQuery Mobile, jQuery, JavaScript, HTML5, REST
+Summary: The contacts-jquerymobile quickstart demonstrates a Java EE 7 mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The contact-jquerymobile quickstart is a deployable Maven 3 project designed to help you get your foot in the door developing HTML5 based mobile web applications with Java EE 7 in Red Hat JBoss Enterprise Application Platform. This project is setup to allow you to create a basic Java EE 7 application using HTML5, jQuery Mobile, JAX-RS, CDI, EJB, JPA, and Bean Validation. It includes a persistence unit and some sample persistence and transaction code to help you get your feet wet with database access in enterprise Java.

+

This application is built using a HTML5 + REST approach. This uses a pure HTML client that interacts with with the application server via restful end-points (JAX-RS). This application also uses some of the latest HTML5 features and advanced JAX-RS. And since testing is just as important with client side as it is server side, this application uses QUnit to show you how to unit test your JavaScript.

+

This application focuses on CRUD in a strictly mobile app using only jQuery Mobile(no other frameworks). The user will have the ability to:

+
    +
  • +

    Create a new contact.

    +
    • +
  • +

    Read a list of contacts.

    +
    • +
  • +

    Update an existing contact.

    +
    • +
  • +

    Delete a contact.

    +
    • +
+

Validation is an important part of an application. Typically in an HTML5 app you can let the built-in HTML5 form validation do the work for you. However, mobile browsers do not support this feature at this time. In order to validate the forms, the jquery.validate plugin was added, which provides both client-side and server-side validation. Over AJAX, if there is an error, the error is returned and displayed in the form. You can see an example of this in the Edit form if you enter an email that is already in use. The application will attempt to insert the error message into a field if that field exists. If the field does not exist then it display it at the top. In addition, there are qunit tests for every form of validation.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ is required. Note that some behaviors, such as validation, will vary slightly based on browser support, especially IE 9.

+

Mobile web support is limited to Android and iOS devices. It should run on HP, and Black Berry devices as well. Windows Phone, and others will be supported as jQuery Mobile announces support.

+

With the prerequisites out of the way, you are ready to build and deploy.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Note: Adding -b 0.0.0.0 to the above commands will allow external clients, such as phones, tablets, and desktops, connect through your local network.

+

For example

+
    For Linux:   EAP7_HOME/bin/standalone.sh -b 0.0.0.0
+    For Windows: EAP7_HOME\bin\standalone.bat -b 0.0.0.0
+
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This deploys target/contacts-jquerymobile.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

Access the running client application in a browser at the following URL: http://localhost:8080/contacts-jquerymobile/.

+

The app is made up of the following pages:

+

Main page

+
    +
  • Displays a list of contacts
    • +
  • Search bar for the list
    • +
  • Details button changes to the Detailed list
    • +
  • Clicking on a contact brings up an Edit form
    • +
  • Menu button (in upper left) opens menu
    • +
+

Menu pullout

+
    +
  • Add a new Contact
    • +
  • List/Detail view switcher, depending on what is currently displayed
    • +
  • About information
    • +
  • Theming - apply various themes (only on the List view)
    • +
+

Details page

+
    +
  • Same as Main page except all information is displayed with each contact
    • +
+

Add form

+
    +
  • First name, Last name, Phone, Email, and BirthDate fields
    • +
  • Save = submit the form
    • +
  • Clear = reset the form but stay on the form
    • +
  • Cancel = reset the form and go the Main page
    • +
+

Edit form

+
    +
  • Same as Add form
    • +
  • Delete button will delete the contact currently viewed and return you to the Main page
    • +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Minification

+

By default, the project uses the wro4j plugin, which provides the ability to concatenate, validate and minify JavaScript and CSS files. These minified files, as well as their unmodified versions are deployed with the project.

+

With just a few quick changes to the project, you can link to the minified versions of your JavaScript and CSS files.

+

First, in the <project-root>/src/main/webapp/index.html file, search for references to minification and comment or uncomment the appropriate lines.

+

Finally, wro4j runs in the compile phase so any standard build command like package, install, etc. will trigger it. The plug-in is in a profile with an id of minify so you will want to specify that profile in your maven build.

+

NOTE: By default there are turn off tests so you must use the arquillian test profile to run tests when minifying. For example:

+
#No Tests
+mvn clean package wildfly:deploy -Pminify
+
+

OR

+
#With Tests
+mvn clean verify wildfly:deploy -Pminify,arq-remote
+
+

Run the Arquillian Tests

+

By default, tests are configured to be skipped. The reason is that the sample test is an Arquillian test, which requires the use of a container. You can activate this test by selecting one of the container configuration provided for JBoss.

+

To run the test in JBoss, first start the container instance. Then, run the test goal with the following profile activated:

+
mvn clean verify -Parq-remote
+
+

Run the QUnit tests

+

QUnit is a JavaScript unit testing framework used and built by jQuery. Because JavaScript code is the core of this HTML5 application, this quickstart provides a set of QUnit tests that automate testing of this code in various browsers. Executing QUnit test cases are quite easy.

+

Simply load the following HTML in the browser you wish to test.

+
    QUICKSTART_HOME/contacts-jquerymobile/src/test/qunit/index.html
+
+

Note: If you use Chrome, some date tests fail. These are false failures and are known issues with Chrome. FireFox, Safari, and IE run the tests correctly. You can also display the tests using the Eclipse built-in browser.

+

For more information on QUnit tests see http://qunitjs.com/.

+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests. They are located under the directory functional-tests. Functional tests verify that your application behaves correctly from the user's point of view - simulating clicking around the page as a normal user would do.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    6. +
+

NOTE: For this to work, Arquillian needs to know the location of the JBoss EAP server. This can be declared through the JBOSS_HOME environment variable or the jbossHome property in arquillian.xml. See Run the Arquillian Tests for complete instructions and additional options.

+
    mvn clean verify -Parq-managed
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+ +

Debug the Application

+

If you want to be able to debug into the source code or look at the Javadocs of any library in the project, you can run either of the following two commands to pull them into your local repository. The IDE should then detect them.

+
mvn dependency:sources
+mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/contacts-jquerymobile/README.md b/contacts-jquerymobile/README.md index 026e810de5..5d249f64fa 100644 --- a/contacts-jquerymobile/README.md +++ b/contacts-jquerymobile/README.md @@ -4,12 +4,12 @@ Author: Joshua Wilson Level: Beginner Technologies: jQuery Mobile, jQuery, JavaScript, HTML5, REST Summary: The `contacts-jquerymobile` quickstart demonstrates a Java EE 7 mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `contact-jquerymobile` quickstart is a deployable Maven 3 project designed to help you get your foot in the door developing HTML5 based mobile web applications with Java EE 7 in ${product.name.full}. This project is setup to allow you to create a basic Java EE 7 application using HTML5, jQuery Mobile, JAX-RS, CDI, EJB, JPA, and Bean Validation. It includes a persistence unit and some sample persistence and transaction code to help you get your feet wet with database access in enterprise Java. +The `contact-jquerymobile` quickstart is a deployable Maven 3 project designed to help you get your foot in the door developing HTML5 based mobile web applications with Java EE 7 in Red Hat JBoss Enterprise Application Platform. This project is setup to allow you to create a basic Java EE 7 application using HTML5, jQuery Mobile, JAX-RS, CDI, EJB, JPA, and Bean Validation. It includes a persistence unit and some sample persistence and transaction code to help you get your feet wet with database access in enterprise Java. This application is built using a HTML5 + REST approach. This uses a pure HTML client that interacts with with the application server via restful end-points (JAX-RS). This application also uses some of the latest HTML5 features and advanced JAX-RS. And since testing is just as important with client side as it is server side, this application uses QUnit to show you how to unit test your JavaScript. @@ -27,9 +27,9 @@ This application focuses on **CRUD** in a strictly mobile app using only **jQuer ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ is required. Note that some behaviors, such as validation, will vary slightly based on browser support, especially IE 9. @@ -39,32 +39,32 @@ With the prerequisites out of the way, you are ready to build and deploy. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat Note: Adding `-b 0.0.0.0` to the above commands will allow external clients, such as phones, tablets, and desktops, connect through your local network. For example - For Linux: ${jboss.home.name}/bin/standalone.sh -b 0.0.0.0 - For Windows: ${jboss.home.name}\bin\standalone.bat -b 0.0.0.0 + For Linux: EAP7_HOME/bin/standalone.sh -b 0.0.0.0 + For Windows: EAP7_HOME\bin\standalone.bat -b 0.0.0.0 ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This deploys `target/${project.artifactId}.war` to the running instance of the server. +4. This deploys `target/contacts-jquerymobile.war` to the running instance of the server. ## Access the Application -Access the running client application in a browser at the following URL: . +Access the running client application in a browser at the following URL: . The app is made up of the following pages: @@ -101,7 +101,7 @@ The app is made up of the following pages: ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -159,19 +159,19 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the server for you, type the following command: +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: -_NOTE: For this to work, Arquillian needs to know the location of the ${product.name} server. This can be declared through the `JBOSS_HOME` environment variable or the `jbossHome` property in `arquillian.xml`. See [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests) for complete instructions and additional options._ +_NOTE: For this to work, Arquillian needs to know the location of the JBoss EAP server. This can be declared through the `JBOSS_HOME` environment variable or the `jbossHome` property in `arquillian.xml`. See [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests) for complete instructions and additional options._ mvn clean verify -Parq-managed ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). diff --git a/contacts-jquerymobile/SERVICES.html b/contacts-jquerymobile/SERVICES.html new file mode 100644 index 0000000000..44be51003d --- /dev/null +++ b/contacts-jquerymobile/SERVICES.html @@ -0,0 +1,71 @@ + + +CREATE + + + +

contacts-jquerymobile: JAX-RS Services Documentation

+

Author: Joshua Wilson

+

This example supports various RESTFul end points which also includes JSONP support for cross domain requests.

+

By default the base URL for services is /jboss-contacts-jquerymobile/rest.

+

ContactService End Points

+

##CREATE

+

Create a new contact

+

/rest/contacts

+
    +
  • Request type: POST
    • +
  • Request type: JSON
    • +
  • Return type: JSON
    • +
  • Request example:
    • +
+
{email: "jane.doe@company.com", id: 14, firstName: "Jane", lastName: 'Doe', phoneNumber: "223-223-1231", birthDate:'1966-01-03'}
+
+
    +
  • Response example:
    • +
  • Success: 200 OK
    • +
  • Validation error: Collection of <field name>:<error msg> for each error
    • +
+
{"email":"That email is already used, please use a unique email"}
+
+

##READ

+

List all contacts

+

/rest/contacts

+
    +
  • Request type: GET
    • +
  • Return type: JSON
    • +
  • Response example:
    • +
+
[{email: "jane.doe@company.com", id: 14, firstName: "Jane", lastName: 'Doe', phoneNumber: "223-223-1231", birthDate:'1966-01-03'},
+ {email: "john.doe@company.com", id: 15, firstName: "John", lastName: 'Doe', phoneNumber: "212-555-1212", birthDate:'1978-02-23'}]
+
+

Find a contact by it's ID.

+

/rest/contacts/<id>

+
    +
  • Request type: GET
    • +
  • Return type: JSON
    • +
  • Response example:
    • +
+
{email: "jane.doe@company.com", id: 14, firstName: "Jane", lastName: 'Doe', phoneNumber: "223-223-1231", birthDate:'1966-01-03'}
+
+

##UPDATE

+

Edit one contact

+

/rest/contacts

+
    +
  • Request type: PUT
    • +
  • Return type: JSON
    • +
  • Response example:
    • +
+
{email: "jane.doe@company.com", id: 14, firstName: "Jane", lastName: 'Doe', phoneNumber: "223-223-1231", birthDate:'1966-01-03'}
+
+

##DELETE

+

Delete one contact

+

/rest/contacts

+
    +
  • Request type: DELETE
    • +
  • Return type: JSON
    • +
  • Response example:
    • +
+
{email: "jane.doe@company.com", id: 14, firstName: "Jane", lastName: 'Doe', phoneNumber: "223-223-1231", birthDate:'1966-01-03'}
+
+ + \ No newline at end of file diff --git a/contacts-jquerymobile/functional-tests/pom.xml b/contacts-jquerymobile/functional-tests/pom.xml index d58d928a4c..5b033f523a 100644 --- a/contacts-jquerymobile/functional-tests/pom.xml +++ b/contacts-jquerymobile/functional-tests/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml diff --git a/contacts-jquerymobile/pom.xml b/contacts-jquerymobile/pom.xml index 28fa9fcb74..7edbf5e3c9 100644 --- a/contacts-jquerymobile/pom.xml +++ b/contacts-jquerymobile/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml contacts-jquerymobile diff --git a/dist/pom.xml b/dist/pom.xml index 8dca3cacf8..50d0dafbaa 100644 --- a/dist/pom.xml +++ b/dist/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml quickstarts-dist diff --git a/ejb-asynchronous/README.html b/ejb-asynchronous/README.html new file mode 100644 index 0000000000..28872016b3 --- /dev/null +++ b/ejb-asynchronous/README.html @@ -0,0 +1,110 @@ + + + ejb-asynchronous: EJB with asynchronous methods + + + +

ejb-asynchronous: EJB with asynchronous methods

+

Author: Wolf-Dieter Fink
+Level: Advanced
+Technologies: Asynchronous EJB
+Summary: The ejb-asynchronous quickstart demonstrates the behavior of asynchronous EJB invocations by a deployed EJB and a remote client and how to handle errors.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-asynchronous quickstart demonstrates the behavior of asynchronous EJB invocations in Red Hat JBoss Enterprise Application Platform. The methods are invoked by both an EJB in the deployment and by a remote client. The quickstart also shows error handling if the asynchronous method invocation fails.

+

The example is composed of 2 Maven modules, each with a shared parent. The modules are as follows:

+
    +
  • ejb: This module contains the EJB's and will be deployed to the server
    • +
  • client : This module contains a remote EJB client
    • +
+

The root pom.xml builds each of the submodules in the above order and deploys the archive to the server.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. This will deploy ejb/target/ejb-asynchronous-ejb.jar to the running instance of the server.
    5. +
+

Check whether the application is deployed successfully.

+

Access the Application

+
    +
  1. Open a command prompt and navigate to the root directory of this quickstart.
    2. +
  2. Type this command to start the client +
    cd client
+mvn exec:exec
+
    +

    Note: This quickstart requires quickstart-parent artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command:

    +
    mvn clean install
+
    +
    3. +
  3. +

    Check the client output

    +
    INFO: The server log should contain a message at (about) <date>, indicating that the call to the asynchronous bean completed.
+INFO: Got the async result as expected => returning at <date>, duration was 200ms
+INFO: Got the async result as expected after wait => returning at <date>, duration was 1500ms
+INFO: Catch the expected Exception of the asynchronous execution!
+INFO: Results of the parallel (server) processing : [returning at <date> duration was 5000ms, returning at <date>, duration was 3000ms]
+
    +
    4. +
  4. +

    Check the server log.

    +

    There should be two INFO log messages for the fireAndForget invocation:

    +
    'fireAndForget' Will wait for 15000ms
+
    +

    and 15sec later (the client should be finished at this time)

    +
    action 'fireAndForget' finished
+
    +
    5. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+
    +
  1. Install the required Maven artifacts and deploy the asynchronous EJB quickstart project. +
      +
    • Right-click on the ejb-asynchronous-ejb project and choose Run As --> Maven Install.
      • +
    • Right-click on the ejb-asynchronous-ejb project and choose Run As --> Run on Server.
      • +
    +
    2. +
  2. Build and run the client side of the quickstart project. +
      +
    • Right-click on the ejb-asynchronous-client project and choose Run As --> Java Application.
      • +
    • In the Select Java Application window, choose AsynchronousClient - org.jboss.as.quickstarts.ejb.asynchronous.client and click OK.
      • +
    • The client output displays in the Console window.
      • +
    +
    3. +
  3. To undeploy the project, right-click on the ejb-asynchronous-ejb project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    4. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-asynchronous/README.md b/ejb-asynchronous/README.md index 3e1d204993..5fd1f5d7b8 100644 --- a/ejb-asynchronous/README.md +++ b/ejb-asynchronous/README.md @@ -4,12 +4,12 @@ Author: Wolf-Dieter Fink Level: Advanced Technologies: Asynchronous EJB Summary: The `ejb-asynchronous` quickstart demonstrates the behavior of asynchronous EJB invocations by a deployed EJB and a remote client and how to handle errors. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-asynchronous` quickstart demonstrates the behavior of asynchronous EJB invocations in ${product.name.full}. The methods are invoked by both an EJB in the deployment and by a remote client. The quickstart also shows error handling if the asynchronous method invocation fails. +The `ejb-asynchronous` quickstart demonstrates the behavior of asynchronous EJB invocations in Red Hat JBoss Enterprise Application Platform. The methods are invoked by both an EJB in the deployment and by a remote client. The quickstart also shows error handling if the asynchronous method invocation fails. The example is composed of 2 Maven modules, each with a shared parent. The modules are as follows: @@ -21,33 +21,33 @@ The root `pom.xml` builds each of the submodules in the above order and deploys ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `ejb/target/${project.artifactId}-ejb.jar` to the running instance of the server. +4. This will deploy `ejb/target/ejb-asynchronous-ejb.jar` to the running instance of the server. Check whether the application is deployed successfully. @@ -86,7 +86,7 @@ Check whether the application is deployed successfully. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -95,18 +95,18 @@ Check whether the application is deployed successfully. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. 1. Install the required Maven artifacts and deploy the asynchronous EJB quickstart project. - * Right-click on the `${project.artifactId}-ejb` project and choose `Run As` --> `Maven Install`. - * Right-click on the `${project.artifactId}-ejb` project and choose `Run As` --> `Run on Server`. + * Right-click on the `ejb-asynchronous-ejb` project and choose `Run As` --> `Maven Install`. + * Right-click on the `ejb-asynchronous-ejb` project and choose `Run As` --> `Run on Server`. 2. Build and run the client side of the quickstart project. - * Right-click on the `${project.artifactId}-client` project and choose `Run As` --> `Java Application`. + * Right-click on the `ejb-asynchronous-client` project and choose `Run As` --> `Java Application`. * In the `Select Java Application` window, choose `AsynchronousClient - org.jboss.as.quickstarts.ejb.asynchronous.client` and click `OK`. * The client output displays in the `Console` window. -3. To undeploy the project, right-click on the `${project.artifactId}-ejb` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +3. To undeploy the project, right-click on the `ejb-asynchronous-ejb` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/ejb-asynchronous/client/pom.xml b/ejb-asynchronous/client/pom.xml index c3ab1df2b6..33af67db27 100644 --- a/ejb-asynchronous/client/pom.xml +++ b/ejb-asynchronous/client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-asynchronous - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-asynchronous-client jar diff --git a/ejb-asynchronous/ejb/pom.xml b/ejb-asynchronous/ejb/pom.xml index 102fbf8a2b..208710476e 100644 --- a/ejb-asynchronous/ejb/pom.xml +++ b/ejb-asynchronous/ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-asynchronous - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-asynchronous-ejb ejb diff --git a/ejb-asynchronous/pom.xml b/ejb-asynchronous/pom.xml index ddded93613..572c9eabe1 100644 --- a/ejb-asynchronous/pom.xml +++ b/ejb-asynchronous/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-asynchronous diff --git a/ejb-in-ear/README.html b/ejb-in-ear/README.html new file mode 100644 index 0000000000..bce7a3971b --- /dev/null +++ b/ejb-in-ear/README.html @@ -0,0 +1,89 @@ + + + ejb-in-ear: Deployment of an EAR Containing a JSF WAR and EJB JAR + + + +

ejb-in-ear: Deployment of an EAR Containing a JSF WAR and EJB JAR

+

Author: Paul Robinson
+Level: Intermediate
+Technologies: EJB, EAR
+Summary: The ejb-in-ear quickstart demonstrates how to deploy an EAR archive that contains a JSF WAR and an EJB JAR.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-in-ear quickstart demonstrates the deployment of an EAR artifact to Red Hat JBoss Enterprise Application Platform. The EAR contains: JSF WAR and an EJB JAR.

+

The example is composed of three Maven projects, each with a shared parent. The projects are as follows:

+
    +
  1. +

    ejb: This project contains the EJB code and can be built independently to produce the JAR archive.

    +
    2. +
  2. +

    web: This project contains the JSF pages and the managed bean.

    +
    3. +
  3. +

    ear: This project builds the EAR artifact and pulls in the EJB and Web artifacts.

    +
    4. +
+

The root pom.xml builds each of the subprojects in the above order and deploys the EAR archive to the server.

+

The example follows the common "Hello World" pattern. These are the steps that occur:

+
    +
  1. A JSF page asks the user for their name.
    2. +
  2. On clicking Greet, the name is sent to a managed bean named Greeter.
    3. +
  3. On setting the name, the Greeter invokes the GreeterEJB, which was injected to the managed bean. Notice the field annotated with @EJB.
    4. +
  4. The response from invoking the GreeterEJB is stored in a field (message) of the managed bean.
    5. +
  5. The managed bean is annotated as @SessionScoped, so the same managed bean instance is used for the entire session. This ensures that the message is available when the page reloads and is displayed to the user.
    6. +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy ear/target/ejb-in-ear.ear to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/ejb-in-ear/.

+

Enter a name in the input field and click the Greet button to see the response.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

For this quickstart, follow the special instructions to build Quickstarts Containing an EAR.

+
    +
  1. Right-click on the ejb-in-ear-ear subproject, and choose Run As --> Run on Server.
    2. +
  2. Choose the server and click Finish.
    3. +
  3. This starts the server, deploys the application, and opens a browser window that accesses the running application.
    4. +
  4. To undeploy the project, right-click on the ejb-in-ear-ear project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-in-ear/README.md b/ejb-in-ear/README.md index 66bed7ac39..cfcfe2afcd 100644 --- a/ejb-in-ear/README.md +++ b/ejb-in-ear/README.md @@ -4,12 +4,12 @@ Author: Paul Robinson Level: Intermediate Technologies: EJB, EAR Summary: The `ejb-in-ear` quickstart demonstrates how to deploy an EAR archive that contains a *JSF* WAR and an *EJB* JAR. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-in-ear` quickstart demonstrates the deployment of an EAR artifact to ${product.name.full}. The EAR contains: *JSF* WAR and an *EJB* JAR. +The `ejb-in-ear` quickstart demonstrates the deployment of an EAR artifact to Red Hat JBoss Enterprise Application Platform. The EAR contains: *JSF* WAR and an *EJB* JAR. The example is composed of three Maven projects, each with a shared parent. The projects are as follows: @@ -31,46 +31,46 @@ The example follows the common "Hello World" pattern. These are the steps that o ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `ear/target/${project.artifactId}.ear` to the running instance of the server. +4. This will deploy `ear/target/ejb-in-ear.ear` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . Enter a name in the input field and click the _Greet_ button to see the response. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -79,14 +79,14 @@ Enter a name in the input field and click the _Greet_ button to see the response ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). For this quickstart, follow the special instructions to build [Quickstarts Containing an EAR](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-ear-project). -1. Right-click on the `${project.artifactId}-ear` subproject, and choose `Run As` --> `Run on Server`. +1. Right-click on the `ejb-in-ear-ear` subproject, and choose `Run As` --> `Run on Server`. 2. Choose the server and click `Finish`. 3. This starts the server, deploys the application, and opens a browser window that accesses the running application. -4. To undeploy the project, right-click on the `${project.artifactId}-ear` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +4. To undeploy the project, right-click on the `ejb-in-ear-ear` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/ejb-in-ear/ear/pom.xml b/ejb-in-ear/ear/pom.xml index 26bddbd318..afb7ace597 100644 --- a/ejb-in-ear/ear/pom.xml +++ b/ejb-in-ear/ear/pom.xml @@ -26,7 +26,7 @@ org.jboss.eap.quickstarts ejb-in-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-in-ear-ear ear diff --git a/ejb-in-ear/ejb/pom.xml b/ejb-in-ear/ejb/pom.xml index 97844cc849..f5690f90db 100644 --- a/ejb-in-ear/ejb/pom.xml +++ b/ejb-in-ear/ejb/pom.xml @@ -26,7 +26,7 @@ org.jboss.eap.quickstarts ejb-in-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-in-ear-ejb ${qs.name.prefix} ejb-in-ear - ejb diff --git a/ejb-in-ear/pom.xml b/ejb-in-ear/pom.xml index e6c4cd98f0..cda3bb38f5 100644 --- a/ejb-in-ear/pom.xml +++ b/ejb-in-ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-in-ear diff --git a/ejb-in-ear/web/pom.xml b/ejb-in-ear/web/pom.xml index 7ed7e0a526..8ac2b71ecf 100644 --- a/ejb-in-ear/web/pom.xml +++ b/ejb-in-ear/web/pom.xml @@ -26,7 +26,7 @@ org.jboss.eap.quickstarts ejb-in-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-in-ear-web war diff --git a/ejb-in-war/README.html b/ejb-in-war/README.html new file mode 100644 index 0000000000..181b5bede6 --- /dev/null +++ b/ejb-in-war/README.html @@ -0,0 +1,92 @@ + + + ejb-in-war: Deployment of a WAR Containing an EJB + + + +

ejb-in-war: Deployment of a WAR Containing an EJB

+

Author: Paul Robinson
+Level: Intermediate
+Technologies: EJB, JSF, WAR
+Summary: The ejb-in-war quickstart demonstrates how to package an EJB bean in a WAR archive and deploy it to JBoss EAP. Arquillian tests are also provided.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-in-war quickstart demonstrates the deployment of an EJB bean bundled in a WAR archive for deployment to Red Hat JBoss Enterprise Application Platform. The project also includes a set of Arquillian tests for the managed bean and EJB.

+

The example follows the common "Hello World" pattern. These are the steps that occur:

+
    +
  1. A JSF page asks the user for their name.
    2. +
  2. On clicking submit, the name is sent to a managed bean named Greeter.
    3. +
  3. On setting the name, the Greeter invokes the GreeterEJB, which was injected into the managed bean. Notice the field annotated with @EJB.
    4. +
  4. The response from invoking the GreeterEJB is stored in a field message of the managed bean.
    5. +
  5. The managed bean is annotated as @SessionScoped, so the same managed bean instance is used for the entire session. This ensures that the message is available when the page reloads and is displayed to the user.
    6. +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/ejb-in-war.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/ejb-in-war/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

JUnit will present you test report summary:

+
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+

If you are interested in more details, check target/surefire-reports directory. You can check console output to verify that Arquillian has really used the real application server. Search for lines similar to the following ones in the server output log:

+
INFO  [org.jboss.as.server.deployment] (MSC service thread 1-3) WFLYSRV0027: Starting deployment of "test.war" (runtime-name: "test.war")
+...
+INFO  [org.jboss.as.server] (management-handler-thread - 29) WFLYSRV0010: Deployed "test.war" (runtime-name : "test.war")
+...
+ INFO  [org.jboss.as.server.deployment] (MSC service thread 1-3) WFLYSRV0028: Stopped deployment test.war (runtime-name: test.war) in 12ms
+...
+INFO  [org.jboss.as.server] (management-handler-thread - 30) WFLYSRV0009: Undeployed "test.war" (runtime-name: "test.war")
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-in-war/README.md b/ejb-in-war/README.md index b85da887ea..932c796713 100644 --- a/ejb-in-war/README.md +++ b/ejb-in-war/README.md @@ -3,13 +3,13 @@ Author: Paul Robinson Level: Intermediate Technologies: EJB, JSF, WAR -Summary: The `ejb-in-war` quickstart demonstrates how to package an *EJB* bean in a WAR archive and deploy it to ${product.name}. Arquillian tests are also provided. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `ejb-in-war` quickstart demonstrates how to package an *EJB* bean in a WAR archive and deploy it to JBoss EAP. Arquillian tests are also provided. +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-in-war` quickstart demonstrates the deployment of an *EJB* bean bundled in a WAR archive for deployment to ${product.name.full}. The project also includes a set of Arquillian tests for the managed bean and EJB. +The `ejb-in-war` quickstart demonstrates the deployment of an *EJB* bean bundled in a WAR archive for deployment to Red Hat JBoss Enterprise Application Platform. The project also includes a set of Arquillian tests for the managed bean and EJB. The example follows the common "Hello World" pattern. These are the steps that occur: @@ -21,44 +21,44 @@ The example follows the common "Hello World" pattern. These are the steps that o ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/ejb-in-war.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -69,13 +69,13 @@ The application will be running at the following URL org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-in-war diff --git a/ejb-multi-server/README.html b/ejb-multi-server/README.html new file mode 100644 index 0000000000..0fbce48a62 --- /dev/null +++ b/ejb-multi-server/README.html @@ -0,0 +1,273 @@ + + + ejb-multi-server: EJB Communication Across Servers + + + +

ejb-multi-server: EJB Communication Across Servers

+

Author: Wolf-Dieter Fink
+Level: Advanced
+Technologies: EJB, EAR
+Summary: The ejb-multi-server quickstart shows how to communicate between multiple applications deployed to different servers using an EJB to log the invocation.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-multi-server quickstart demonstrates communication between applications deployed to different Red Hat JBoss Enterprise Application Platform servers. Each application is deployed as an EAR and contains a simple EJB bean. The only function of each bean is to log the invocation.

+

This example consists of the following Maven projects, each with a shared parent:

+ + + + + + + + + + +
Sub-project Description
app-main An application that can be called by the client. It can also call the different sub-applications.
app-one and app-two These are simple applications that contain an EJB sub-project to build the ejb.jar file and an EAR sub-project to build the app.ear file. Each application contains only one EJB that logs a statement on a method call and returns the jboss.node.name and credentials.
app-web A simple WAR application. It consists of one Servlet that demonstrates how to invoke EJBs on a different server.
client This project builds the standalone client and executes it.
+

The root pom.xml builds each of the subprojects in an appropriate order.

+

The server configuration is done using CLI batch scripts located in the root of the quickstart folder.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start with a Clean Server Install

+

It is important to start with a clean version of JBoss EAP before testing this quickstart. Be sure to unzip or install a fresh JBoss EAP instance.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add the Application Users

+

The following users must be added to the ApplicationRealm to run this quickstart. Be sure to use the names and passwords specified in the table as they are required to run this example.

+ + + + + + + + + +
UserName Realm Password Roles
quickuser ApplicationRealm quick-123 leave blank for none
quickuser1 ApplicationRealm quick123+ leave blank for none
quickuser2 ApplicationRealm quick+123 leave blank for none
+

To add the users, open a command prompt and type the following commands:

+
    For Linux:
+        EAP7_HOME/bin/add-user.sh -a -u quickuser -p quick-123
+        EAP7_HOME/bin/add-user.sh -a -u quickuser1 -p quick123+
+        EAP7_HOME/bin/add-user.sh -a -u quickuser2 -p quick+123
+
+    For Windows:
+        EAP7_HOME\bin\add-user.bat -a -u quickuser -p quick-123
+        EAP7_HOME\bin\add-user.bat -a -u quickuser1 -p quick123+
+        EAP7_HOME\bin\add-user.bat -a -u quickuser2 -p quick+123
+
+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Back Up the Server Configuration Files

+

JBoss EAP server configuration for this quickstart is very complicated and not easily restored by running a JBoss CLI script, so it is important to back up your server configuration files before you begin.

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Back up the following files, replacing EAP7_HOME with the path to your JBoss EAP installation: +
    EAP7_HOME/domain/configuration/domain.xml
+EAP7_HOME/domain/configuration/host.xml        
+
    +
    3. +
  3. After you have completed testing and undeployed this quickstart, you can replace these files to restore the server to its original configuration.
    4. +
+

Configure the Server

+

You configure the domain server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a install-domain.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Start with a fresh instance of the JBoss EAP as noted above under Start with a Clean JBoss EAP Install.

    +
    2. +
  2. +

    Be sure you add the required users as specified above under Add the Application Users.

    +
    3. +
  3. +

    Before you begin, make sure you followed the instructions above under Back Up the JBoss EAP Server Configuration Files.

    +
    4. +
  4. Start the JBoss EAP server +
      +
    • Open a command prompt and navigate to the root of the EAP directory.
      • +
    • Start the server using the following command: +
      bin/domain.sh    
+
      +
      • +
    +
    5. +
  5. Review the install-domain.cli file in the root of this quickstart directory. This script configures and starts multiple servers needed to run this quickstart.
    6. +
  6. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh -c --file=install-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat -c --file=install-domain.cli
+
    +

    You should see the following result when you run the script:

    +
    {
+    "outcome" => "success",
+    "result" => "STOPPED"
+}
+{
+    "outcome" => "success",
+    "result" => "STOPPED"
+}
+{
+    "outcome" => "success",
+    "result" => undefined,
+    "server-groups" => undefined
+}
+{
+    "outcome" => "success",
+    "result" => undefined,
+    "server-groups" => undefined
+}
+{
+    "outcome" => "success",
+    "result" => undefined,
+    "server-groups" => undefined
+}
+{
+    "outcome" => "success",
+    "result" => undefined,
+    "server-groups" => undefined
+}
+{
+    "outcome" => "success",
+    "result" => undefined,
+    "server-groups" => undefined
+}
+The batch executed successfully
+process-state: reload-required
+{
+    "outcome" => "success",
+    "result" => undefined,
+    "server-groups" => undefined,
+    "response-headers" => {"process-state" => "reload-required"}
+}
+{
+    "outcome" => "success",
+    "result" => "STARTING",
+    "response-headers" => {"process-state" => "reload-required"}
+}
+{
+    "outcome" => "success",
+    "result" => "STARTING",
+    "response-headers" => {"process-state" => "reload-required"}
+}
+{
+    "outcome" => "success",
+    "result" => "STARTING",
+    "response-headers" => {"process-state" => "reload-required"}
+}
+{
+    "outcome" => "success",
+    "result" => "STARTING",
+    "response-headers" => {"process-state" => "reload-required"}
+}
+{
+    "outcome" => "success",
+    "result" => "STARTING",
+    "response-headers" => {"process-state" => "reload-required"}
+}
+{
+    "outcome" => "success",
+    "result" => "Starting",
+    "response-headers" => {"process-state" => "reload-required"}
+
    +
    7. +
+

NOTE: Depending on your machine configuration, you may see "Exception in thread "main" java.lang.OutOfMemoryError: unable to create new native thread" exceptions in the server log when you run this script. If you do, you must increase the ulimit open files and max user processes settings. Instructions to do this are located here: http://ithubinfo.blogspot.com/2013/07/how-to-increase-ulimit-open-file-and.html. After you update the ulimit settings, be sure to reboot and start with a fresh instance of the server.

+

Review the Modified Server Configuration

+

There are too many additions to the configuration files to list here. Feel free to compare the domain.xml and host.xml to the backup copies to see the changes made to configure the server to run this quickstart.

+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started and configured the JBoss EAP server successfully as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build the artifacts: +
    mvn clean install
+
    +
    4. +
+

You should see BUILD SUCCESS at the end of the build SUCCESS messages for each component.

+
    +
  1. In the same command prompt, deploy the applications using the provided CLI batch script by typing the following command: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh -c --file=deploy-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat -c --file=deploy-domain.cli
+
    +

    This will deploy the app-*.ear files to different server-groups of the running domain. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +

    You may see the following warnings in the server log. You can ignore these warnings.

    +
    [Server:app-oneB] 13:00:13,346 WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 13) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
+[Server:app-oneB] 13:00:13,346 WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 13) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+[Server:app-oneB] 13:00:13,347 WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 13) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
+[Server:app-oneB] 13:00:13,347 WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 13) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+[Server:app-oneA] 13:00:13,407 WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 11) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
+[Server:app-oneA] 13:00:13,408 WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 11) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+[Server:app-oneA] 13:00:13,408 WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 11) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
+[Server:app-oneA] 13:00:13,408 WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 11) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+
    +
    2. +
+

NOTE: If ERRORs appear in the server.log when installing or deploying the quickstart, stop the domain and restart it. This should ensure further steps run correctly.

+

Access the Remote Client Application

+

This example shows how to invoke an EJB from a remote standalone application.

+
    +
  1. Make sure that the deployments are successful as described above.
    2. +
  2. Navigate to the quickstart client/ subdirectory.
    3. +
  3. Type this command to run the application: +
    mvn exec:java
+
    +

    The client will output the following information provided by the applications:

    +
    InvokeAll succeed: MainApp[anonymous]@master:app-main  >  [ app1[quickuser1]@master:app-oneB > app2[quickuser2]@master:app-twoA ; app2[quickuser2]@master:app-twoA ]
+
    +

    This output shows that the MainApp is called with the user anonymous at node master:app-main and the sub-call is proceeded by the master:app-oneA node and master:app-twoA node as quickuser2.

    +

    Review the server log files to see the bean invocations on the servers.

    +

    Note: This quickstart requires quickstart-parent artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command:

    +
    mvn clean install
+
    +
    4. +
  4. +

    If it is necessary to invoke the client with a different JBoss EAP version the main class can be invoked by using the following command from the root directory of this quickstart. Replace EAP7_HOME with your current installation path. The output should be similar to the previous mvn executions.

    +
    java -cp EAP7_HOME/bin/client/jboss-client.jar:app-main/ejb/target/ejb-multi-server-app-main-ejb-client.jar:app-two/ejb/target/ejb-multi-server-app-two-ejb-client.jar:client/target/ejb-multi-server-client.jar org.jboss.as.quickstarts.ejb.multi.server.Client
+
    +
    5. +
+

NOTE:

+
    +
  • If exec is called multiple times, the invocation for app1 might use app-oneA and app-oneB node due to cluster loadbalancing.
    • +
  • A JBoss EAP will deny the invocation of unsecured methods of appOne/appTwo since security is enabled but the method does not include @Roles. You need to set default-missing-method-permissions-deny-access = false for the ejb3 subsystem within the domain profile ha and default to allow the method invocation. See the install-domain.cli script.
    • +
+

Access the JSF application Inside the Main Application

+

The JSF example shows different annotations to inject the EJB. Also how to handle the annotation if different beans implement the same interface and therefore the container is not able to decide which bean needs to be injected without additional informations.

+
    +
  1. Make sure that the deployments are successful as described above.
    2. +
  2. Use a browser to access the JSF application at the following URL: http://localhost:8080/ejb-multi-server-app-main-web/
    3. +
  3. Insert a message in the Text input and invoke the different methods. The result is shown in the browser.
    4. +
  4. See server logfiles and find your given message logged as INFO.
    5. +
+

Access the Servlet Application Deployed as a WAR Inside a Minimal Server

+

An example how to access EJBs from a separate instance which only contains a web application.

+
    +
  1. Make sure that the deployments are successful as described above.
    2. +
  2. Use a browser to access the Servlet at the following URL: http://localhost:8380/ejb-multi-server-app-web/
    3. +
  3. The Servlet will invoke the remote EJBs directly and show the results, compare that the invocation is successful
    4. +
+

Undeploy the Archives

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=undeploy-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=undeploy-domain.cli
+
    +
    4. +
+

Remove the Server Domain Configuration

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Restore the EAP7_HOME/domain/configuration/domain.xml and EAP7_HOME/domain/configuration/host.xml files with the back-up copies of the files. Be sure to replace EAP7_HOME with the path to your server.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

EJB Client (ejb-client) currently has limited support in the Eclipse Web Tools Platform (WTP). For that reason, this quickstart is not supported in Red Hat JBoss Developer Studio.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-multi-server/README.md b/ejb-multi-server/README.md index 3d53174bd2..fbbee6fdef 100644 --- a/ejb-multi-server/README.md +++ b/ejb-multi-server/README.md @@ -4,13 +4,13 @@ Author: Wolf-Dieter Fink Level: Advanced Technologies: EJB, EAR Summary: The `ejb-multi-server` quickstart shows how to communicate between multiple applications deployed to different servers using an EJB to log the invocation. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-multi-server` quickstart demonstrates communication between applications deployed to different ${product.name.full} servers. Each application is deployed as an EAR and contains a simple EJB bean. The only function of each bean is to log the invocation. +The `ejb-multi-server` quickstart demonstrates communication between applications deployed to different Red Hat JBoss Enterprise Application Platform servers. Each application is deployed as an EAR and contains a simple EJB bean. The only function of each bean is to log the invocation. This example consists of the following Maven projects, each with a shared parent: @@ -28,19 +28,19 @@ The server configuration is done using CLI batch scripts located in the root of ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start with a Clean Server Install -It is important to start with a clean version of ${product.name} before testing this quickstart. Be sure to unzip or install a fresh ${product.name} instance. +It is important to start with a clean version of JBoss EAP before testing this quickstart. Be sure to unzip or install a fresh JBoss EAP instance. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add the Application Users @@ -56,26 +56,26 @@ The following users must be added to the `ApplicationRealm` to run this quicksta To add the users, open a command prompt and type the following commands: For Linux: - ${jboss.home.name}/bin/add-user.sh -a -u quickuser -p quick-123 - ${jboss.home.name}/bin/add-user.sh -a -u quickuser1 -p quick123+ - ${jboss.home.name}/bin/add-user.sh -a -u quickuser2 -p quick+123 + EAP7_HOME/bin/add-user.sh -a -u quickuser -p quick-123 + EAP7_HOME/bin/add-user.sh -a -u quickuser1 -p quick123+ + EAP7_HOME/bin/add-user.sh -a -u quickuser2 -p quick+123 For Windows: - ${jboss.home.name}\bin\add-user.bat -a -u quickuser -p quick-123 - ${jboss.home.name}\bin\add-user.bat -a -u quickuser1 -p quick123+ - ${jboss.home.name}\bin\add-user.bat -a -u quickuser2 -p quick+123 + EAP7_HOME\bin\add-user.bat -a -u quickuser -p quick-123 + EAP7_HOME\bin\add-user.bat -a -u quickuser1 -p quick123+ + EAP7_HOME\bin\add-user.bat -a -u quickuser2 -p quick+123 If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: [Add an Application User](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user). ## Back Up the Server Configuration Files -${product.name} server configuration for this quickstart is very complicated and not easily restored by running a JBoss CLI script, so it is important to back up your server configuration files before you begin. +JBoss EAP server configuration for this quickstart is very complicated and not easily restored by running a JBoss CLI script, so it is important to back up your server configuration files before you begin. -1. If it is running, stop the ${product.name} server. -2. Back up the following files, replacing ${jboss.home.name} with the path to your ${product.name} installation: +1. If it is running, stop the JBoss EAP server. +2. Back up the following files, replacing EAP7_HOME with the path to your JBoss EAP installation: - ${jboss.home.name}/domain/configuration/domain.xml - ${jboss.home.name}/domain/configuration/host.xml + EAP7_HOME/domain/configuration/domain.xml + EAP7_HOME/domain/configuration/host.xml 3. After you have completed testing and undeployed this quickstart, you can replace these files to restore the server to its original configuration. @@ -83,22 +83,22 @@ ${product.name} server configuration for this quickstart is very complicated and You configure the domain server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `install-domain.cli` script provided in the root directory of this quickstart. -1. Start with a fresh instance of the ${product.name} as noted above under [Start with a Clean ${product.name} Install](#start-with-a-clean-server-install). +1. Start with a fresh instance of the JBoss EAP as noted above under [Start with a Clean JBoss EAP Install](#start-with-a-clean-server-install). 2. Be sure you add the required users as specified above under [Add the Application Users](#add-the-application-users). -3. Before you begin, make sure you followed the instructions above under [Back Up the ${product.name} Server Configuration Files](#back-up-the-server-configuration-files). -4. Start the ${product.name} server +3. Before you begin, make sure you followed the instructions above under [Back Up the JBoss EAP Server Configuration Files](#back-up-the-server-configuration-files). +4. Start the JBoss EAP server * Open a command prompt and navigate to the root of the EAP directory. * Start the server using the following command: bin/domain.sh 5. Review the `install-domain.cli` file in the root of this quickstart directory. This script configures and starts multiple servers needed to run this quickstart. -6. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +6. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh -c --file=install-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat -c --file=install-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh -c --file=install-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat -c --file=install-domain.cli You should see the following result when you run the script: { @@ -182,7 +182,7 @@ There are too many additions to the configuration files to list here. Feel free ## Build and Deploy the Quickstart -1. Make sure you have started and configured the ${product.name} server successfully as described above. +1. Make sure you have started and configured the JBoss EAP server successfully as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build the artifacts: @@ -192,8 +192,8 @@ There are too many additions to the configuration files to list here. Feel free 4. In the same command prompt, deploy the applications using the provided CLI batch script by typing the following command: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh -c --file=deploy-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat -c --file=deploy-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh -c --file=deploy-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat -c --file=deploy-domain.cli This will deploy the `app-*.ear` files to different server-groups of the running domain. You should see the following result when you run the script: @@ -237,15 +237,15 @@ This example shows how to invoke an EJB from a remote standalone application. mvn clean install -4. If it is necessary to invoke the client with a different ${product.name} version the main class can be invoked by using the following command from the root directory of this quickstart. Replace ${jboss.home.name} with your current installation path. The output should be similar to the previous mvn executions. +4. If it is necessary to invoke the client with a different JBoss EAP version the main class can be invoked by using the following command from the root directory of this quickstart. Replace EAP7_HOME with your current installation path. The output should be similar to the previous mvn executions. - java -cp ${jboss.home.name}/bin/client/jboss-client.jar:app-main/ejb/target/ejb-multi-server-app-main-ejb-client.jar:app-two/ejb/target/ejb-multi-server-app-two-ejb-client.jar:client/target/ejb-multi-server-client.jar org.jboss.as.quickstarts.ejb.multi.server.Client + java -cp EAP7_HOME/bin/client/jboss-client.jar:app-main/ejb/target/ejb-multi-server-app-main-ejb-client.jar:app-two/ejb/target/ejb-multi-server-app-two-ejb-client.jar:client/target/ejb-multi-server-client.jar org.jboss.as.quickstarts.ejb.multi.server.Client _NOTE:_ * _If exec is called multiple times, the invocation for `app1` might use `app-oneA` and `app-oneB` node due to cluster loadbalancing._ -* _A ${product.name} will deny the invocation of unsecured methods of `appOne`/`appTwo` since security is enabled but the method does not include @Roles. You need to set `default-missing-method-permissions-deny-access = false` for the `ejb3` subsystem within the domain profile `ha` and `default` to allow the method invocation. See the `install-domain.cli` script._ +* _A JBoss EAP will deny the invocation of unsecured methods of `appOne`/`appTwo` since security is enabled but the method does not include @Roles. You need to set `default-missing-method-permissions-deny-access = false` for the `ejb3` subsystem within the domain profile `ha` and `default` to allow the method invocation. See the `install-domain.cli` script._ ## Access the JSF application Inside the Main Application @@ -268,18 +268,18 @@ An example how to access EJBs from a separate instance which only contains a web ## Undeploy the Archives -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=undeploy-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=undeploy-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=undeploy-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=undeploy-domain.cli ## Remove the Server Domain Configuration -1. If it is running, stop the ${product.name} server. -2. Restore the `${jboss.home.name}/domain/configuration/domain.xml` and `${jboss.home.name}/domain/configuration/host.xml` files with the back-up copies of the files. Be sure to replace ${jboss.home.name} with the path to your server. +1. If it is running, stop the JBoss EAP server. +2. Restore the `EAP7_HOME/domain/configuration/domain.xml` and `EAP7_HOME/domain/configuration/host.xml` files with the back-up copies of the files. Be sure to replace EAP7_HOME with the path to your server. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse diff --git a/ejb-multi-server/app-main/ear/pom.xml b/ejb-multi-server/app-main/ear/pom.xml index 4ec94fe320..eab6ef63f1 100644 --- a/ejb-multi-server/app-main/ear/pom.xml +++ b/ejb-multi-server/app-main/ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server-app-main - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-main-ear ear diff --git a/ejb-multi-server/app-main/ejb/pom.xml b/ejb-multi-server/app-main/ejb/pom.xml index d8b307587c..406316bf36 100644 --- a/ejb-multi-server/app-main/ejb/pom.xml +++ b/ejb-multi-server/app-main/ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server-app-main - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-main-ejb ejb diff --git a/ejb-multi-server/app-main/pom.xml b/ejb-multi-server/app-main/pom.xml index 75875f65ca..81b2872538 100644 --- a/ejb-multi-server/app-main/pom.xml +++ b/ejb-multi-server/app-main/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-multi-server-app-main diff --git a/ejb-multi-server/app-main/web/pom.xml b/ejb-multi-server/app-main/web/pom.xml index 87c6e842fc..91c8f56940 100644 --- a/ejb-multi-server/app-main/web/pom.xml +++ b/ejb-multi-server/app-main/web/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server-app-main - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-main-web war diff --git a/ejb-multi-server/app-one/ear/pom.xml b/ejb-multi-server/app-one/ear/pom.xml index 27e9e04dd4..b5a57bc7c8 100644 --- a/ejb-multi-server/app-one/ear/pom.xml +++ b/ejb-multi-server/app-one/ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server-app-one - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-one-ear ear diff --git a/ejb-multi-server/app-one/ejb/pom.xml b/ejb-multi-server/app-one/ejb/pom.xml index d14e765dc6..ed12a01568 100644 --- a/ejb-multi-server/app-one/ejb/pom.xml +++ b/ejb-multi-server/app-one/ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server-app-one - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-one-ejb ejb diff --git a/ejb-multi-server/app-one/pom.xml b/ejb-multi-server/app-one/pom.xml index 740e96abb1..d0065fd67c 100644 --- a/ejb-multi-server/app-one/pom.xml +++ b/ejb-multi-server/app-one/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-one pom diff --git a/ejb-multi-server/app-two/ear/pom.xml b/ejb-multi-server/app-two/ear/pom.xml index 3543a5094e..4a3f06525d 100644 --- a/ejb-multi-server/app-two/ear/pom.xml +++ b/ejb-multi-server/app-two/ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server-app-two - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-two-ear ear diff --git a/ejb-multi-server/app-two/ejb/pom.xml b/ejb-multi-server/app-two/ejb/pom.xml index c5c3463a7d..5be63fff56 100644 --- a/ejb-multi-server/app-two/ejb/pom.xml +++ b/ejb-multi-server/app-two/ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server-app-two - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-two-ejb ejb diff --git a/ejb-multi-server/app-two/pom.xml b/ejb-multi-server/app-two/pom.xml index fae31e3125..5c1534b14d 100644 --- a/ejb-multi-server/app-two/pom.xml +++ b/ejb-multi-server/app-two/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-two pom diff --git a/ejb-multi-server/app-web/pom.xml b/ejb-multi-server/app-web/pom.xml index 9ce32e80a0..ad225b41b7 100644 --- a/ejb-multi-server/app-web/pom.xml +++ b/ejb-multi-server/app-web/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-app-web war diff --git a/ejb-multi-server/client/pom.xml b/ejb-multi-server/client/pom.xml index 125aba7b3f..446aa71cdd 100644 --- a/ejb-multi-server/client/pom.xml +++ b/ejb-multi-server/client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-multi-server - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-multi-server-client jar diff --git a/ejb-multi-server/pom.xml b/ejb-multi-server/pom.xml index 6a39fc37c2..20ee86fd88 100644 --- a/ejb-multi-server/pom.xml +++ b/ejb-multi-server/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-multi-server diff --git a/ejb-remote/README.html b/ejb-remote/README.html new file mode 100644 index 0000000000..8020cf6713 --- /dev/null +++ b/ejb-remote/README.html @@ -0,0 +1,175 @@ + + + ejb-remote: Remote EJB Client Example + + + +

ejb-remote: Remote EJB Client Example

+

Author: Jaikiran Pai, Mike Musgrove
+Level: Intermediate
+Technologies: EJB, JNDI
+Summary: The ejb-remote quickstart uses EJB and JNDI to demonstrate how to access an EJB, deployed to JBoss EAP, from a remote Java client application.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-remote quickstart shows how to access an EJB from a remote Java client application. It demonstrates the use of EJB and JNDI in Red Hat JBoss Enterprise Application Platform.

+

There are two components to this example:

+
    +
  1. A server side component: +

    The server component is comprised of a stateful EJB and a stateless EJB. It provides both an EJB JAR that is deployed to the server and a JAR file containing the remote business interfaces required by the remote client application.

    +
    2. +
  2. A remote client application that accesses the server component. +

    The remote client application depends on the remote business interfaces from the server component. This application looks up the stateless and stateful beans via JNDI and invokes a number of methods on them.

    +
    3. +
+

Each component is defined in its own standalone Maven module. The quickstart provides a top level Maven module to simplify the packaging of the artifacts.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+

Since this quickstart builds two separate components, you can not use the standard Build and Deploy commands used by most of the other quickstarts. You must follow these steps to build, deploy, and run this quickstart.

+
    +
  1. Make sure you have started the JBoss EAP server. See the instructions in the previous section.
    2. +
  2. Open a command prompt and navigate to the ejb-remote quickstart directory
    3. +
  3. Build and install the server side component: +
      +
    • Build the EJB and client interfaces JARs and install them in your local Maven repository. +
      mvn clean install         
+
      +
      • +
    • Deploy the EJB JAR to your server. This Maven goal will deploy server-side/target/ejb-remote-server-side.jar. You can check the JBoss EAP server console to see information messages regarding the deployment. +
      mvn wildfly:deploy
+
      +
      • +
    +
    4. +
  4. Build and run the client application +
      +
    • Navigate to the client subdirectory: +
      cd ../client
+
      +
      • +
    • Compile the client code +
      mvn clean compile
+
      +
      • +
    • Execute the client application within Maven +
      mvn exec:exec        
+
      +
      • +
    +

    Note: This quickstart requires quickstart-parent artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command:

    +
    mvn clean install
+
    +
    5. +
+

Investigate the Console Output

+

When the client application runs, it performs the following steps:

+
    +
  1. Obtains a stateless session bean instance.
    2. +
  2. Sends method invocations to the stateless bean to add two numbers, and then displays the result.
    3. +
  3. Sends a second invocation to the stateless bean subtract two numbers, and then displays the result.
    4. +
  4. Obtains a stateful session bean instance.
    5. +
  5. Sends several method invocations to the stateful bean to increment a field in the bean, displaying the result each time.
    6. +
  6. Sends several method invocations to the stateful bean to decrement a field in the bean, displaying the result each time.
    7. +
+

The output in the terminal window will look like the following:

+
  Obtained a remote stateless calculator for invocation
+  Adding 204 and 340 via the remote stateless calculator deployed on the server
+  Remote calculator returned sum = 544
+  Subtracting 2332 from 3434 via the remote stateless calculator deployed on the server
+  Remote calculator returned difference = 1102
+  Obtained a remote stateful counter for invocation
+  Counter will now be incremented 5 times
+  Incrementing counter
+  Count after increment is 1
+  Incrementing counter
+  Count after increment is 2
+  Incrementing counter
+  Count after increment is 3
+  Incrementing counter
+  Count after increment is 4
+  Incrementing counter
+  Count after increment is 5
+  Counter will now be decremented 5 times
+  Decrementing counter
+  Count after decrement is 4
+  Decrementing counter
+  Count after decrement is 3
+  Decrementing counter
+  Count after decrement is 2
+  Decrementing counter
+  Count after decrement is 1
+  Decrementing counter
+  Count after decrement is 0
+
+

Logging statements have been removed from this output here to make it clearer.

+

Build and Run The Quickstart as an Executable JAR

+

The remote client application can also be built as a standalone executable JAR with all of its dependencies.

+
    +
  1. Open a command prompt and navigate to the ejb-remote/client quickstart directory +
    cd client
+
    +
    2. +
  2. Type the following in the command line: +
    mvn clean package assembly:single
+
    +
    3. +
  3. +

    You can then run the executable JAR using the java -jar command. You will see the same console output as above.

    +
    java -jar target/ejb-remote-client-jar-with-dependencies.jar
+
    +
    4. +
+

Undeploy the Archive

+

To undeploy the server-side component from the JBoss EAP server:

+
    +
  1. Navigate to the server-side subdirectory: +
    cd ../server-side
+
    +
    2. +
  2. Type the following command: +
    mvn wildfly:undeploy
+
    +
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+
    +
  1. +

    Install the required Maven artifacts and deploy the server side of the quickstart project.

    +
      +
    • Right-click on the ejb-remote-server-side project and choose Run As --> Maven Install.
      • +
    • Right-click on the ejb-remote-server-side project and choose Run As --> Run on Server.
      • +
    +
    2. +
  2. +

    Build and run the client side of the quickstart project.

    +
      +
    • Right-click on the ejb-remote-client project and choose Run As --> Java Application.
      • +
    • In the Select Java Application window, choose RemoteEJBClient - org.jboss.as.quickstarts.ejb.remote.client and click OK.
      • +
    • The client output displays in the Console window.
      • +
    +
    3. +
  3. +

    To undeploy the project, right-click on the ejb-remote-server-side project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.

    +
    4. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-remote/README.md b/ejb-remote/README.md index 690a520419..c384010084 100644 --- a/ejb-remote/README.md +++ b/ejb-remote/README.md @@ -3,13 +3,13 @@ Author: Jaikiran Pai, Mike Musgrove Level: Intermediate Technologies: EJB, JNDI -Summary: The `ejb-remote` quickstart uses *EJB* and *JNDI* to demonstrate how to access an EJB, deployed to ${product.name}, from a remote Java client application. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `ejb-remote` quickstart uses *EJB* and *JNDI* to demonstrate how to access an EJB, deployed to JBoss EAP, from a remote Java client application. +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-remote` quickstart shows how to access an EJB from a remote Java client application. It demonstrates the use of *EJB* and *JNDI* in ${product.name.full}. +The `ejb-remote` quickstart shows how to access an EJB from a remote Java client application. It demonstrates the use of *EJB* and *JNDI* in Red Hat JBoss Enterprise Application Platform. There are two components to this example: @@ -25,36 +25,36 @@ Each component is defined in its own standalone Maven module. The quickstart pro ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart Since this quickstart builds two separate components, you can not use the standard *Build and Deploy* commands used by most of the other quickstarts. You must follow these steps to build, deploy, and run this quickstart. -1. Make sure you have started the ${product.name} server. See the instructions in the previous section. +1. Make sure you have started the JBoss EAP server. See the instructions in the previous section. 2. Open a command prompt and navigate to the ejb-remote quickstart directory 3. Build and install the server side component: * Build the EJB and client interfaces JARs and install them in your local Maven repository. mvn clean install - * Deploy the EJB JAR to your server. This Maven goal will deploy `server-side/target/${project.artifactId}-server-side.jar`. You can check the ${product.name} server console to see information messages regarding the deployment. + * Deploy the EJB JAR to your server. This Maven goal will deploy `server-side/target/ejb-remote-server-side.jar`. You can check the JBoss EAP server console to see information messages regarding the deployment. mvn wildfly:deploy 4. Build and run the client application @@ -132,12 +132,12 @@ The remote client application can also be built as a standalone executable JAR w 4. You can then run the executable JAR using the `java -jar` command. You will see the same console output as above. - java -jar target/${project.artifactId}-client-jar-with-dependencies.jar + java -jar target/ejb-remote-client-jar-with-dependencies.jar ## Undeploy the Archive -To undeploy the server-side component from the ${product.name} server: +To undeploy the server-side component from the JBoss EAP server: 1. Navigate to the server-side subdirectory: @@ -150,21 +150,21 @@ To undeploy the server-side component from the ${product.name} server: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. 1. Install the required Maven artifacts and deploy the server side of the quickstart project. - * Right-click on the `${project.artifactId}-server-side` project and choose `Run As` --> `Maven Install`. - * Right-click on the `${project.artifactId}-server-side` project and choose `Run As` --> `Run on Server`. + * Right-click on the `ejb-remote-server-side` project and choose `Run As` --> `Maven Install`. + * Right-click on the `ejb-remote-server-side` project and choose `Run As` --> `Run on Server`. 2. Build and run the client side of the quickstart project. - * Right-click on the `${project.artifactId}-client` project and choose `Run As` --> `Java Application`. + * Right-click on the `ejb-remote-client` project and choose `Run As` --> `Java Application`. * In the `Select Java Application` window, choose `RemoteEJBClient - org.jboss.as.quickstarts.ejb.remote.client` and click `OK`. * The client output displays in the `Console` window. -3. To undeploy the project, right-click on the `${project.artifactId}-server-side` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +3. To undeploy the project, right-click on the `ejb-remote-server-side` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/ejb-remote/client/pom.xml b/ejb-remote/client/pom.xml index c18e022a2a..93e90fda04 100644 --- a/ejb-remote/client/pom.xml +++ b/ejb-remote/client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-remote - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-remote-client diff --git a/ejb-remote/pom.xml b/ejb-remote/pom.xml index 383a205e54..dec42b1881 100644 --- a/ejb-remote/pom.xml +++ b/ejb-remote/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-remote diff --git a/ejb-remote/server-side/pom.xml b/ejb-remote/server-side/pom.xml index e08944cafe..d6daf5cd2e 100644 --- a/ejb-remote/server-side/pom.xml +++ b/ejb-remote/server-side/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts ejb-remote - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-remote-server-side diff --git a/ejb-security-context-propagation/README.html b/ejb-security-context-propagation/README.html new file mode 100644 index 0000000000..f422090e62 --- /dev/null +++ b/ejb-security-context-propagation/README.html @@ -0,0 +1,315 @@ + + + ejb-security-context-propagation: Demonstrate security context propagation in EJB to remote EJB calls + + + +

ejb-security-context-propagation: Demonstrate security context propagation in EJB to remote EJB calls

+

Author: Stefan Guilhen
+Level: Advanced
+Technologies: EJB, Security
+Summary: The ejb-security-context-propagation quickstart demonstrates how the security context can be propagated to a remote EJB using a remote outbound connection configuration
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-security-context-propagation quickstart demonstrates how the security context of an EJB can be propagated to a remote EJB in Red Hat JBoss Enterprise Application Platform.

+

The quickstart makes use of two EJBs, SecuredEJB and IntermediateEJB, to verify that the security context propagation is correct, and a RemoteClient standalone client.

+

SecuredEJB

+

The SecuredEJB has four methods:

+
String getSecurityInformation();
+String guestMethod();
+String userMethod();
+String adminMethod();
+
+

The first method can be called by all users that are created in this quickstart. The purpose of this method is to return a String containing the name of the Principal that called the EJB along with the user's authorized role information, for example:

+
[Principal=[quickstartUser], In role [guest]=true, In role [user]=true, In role [admin]=false]
+
+

The next three methods are annotated to require that the calling user is authorized for roles guest, user and admin respectively.

+

IntermediateEJB

+

The IntermediateEJB contains a single method. Its purpose is to make use of a remote connection and invoke each of the methods on the SecuredEJB. A summary is then returned with the outcome of the calls.

+

RemoteClient

+

Finally there is the RemoteClient stand-alone client. The client makes calls using the identity of the established connection.

+

In the real world, remote calls between servers in the servers-to-server scenario would truly be remote and separate. For the purpose of this quickstart, we make use of a loopback connection to the same server so we do not need two servers just to run the test.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the Red Hat JBoss Enterprise Application Platform Documentation Getting Started Guide located on the Customer Portal.

+

You can also use JBoss Developer Studio or Eclipse to run the quickstarts.

+

Prerequisites

+

This quickstart uses the default standalone configuration plus the modifications described here.

+

It is recommended that you test this approach in a separate and clean environment before you attempt to port the changes in your own environment.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add the Application Users

+

This quickstart uses secured management interfaces and is built around the default ApplicationRealm as configured in the JBoss EAP distribution. You must create the following application user to access the running application:

+ + + + + + + + +
UserName Realm Password Roles
quickstartUser ApplicationRealm quickstartPwd1! guest,user
superUser ApplicationRealm superPwd1! guest,user,admin
+

To add the user, open a command prompt and type the following commands:

+
For Linux:
+  EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user'
+  EAP7_HOME/bin/add-user.sh -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin'
+
+For Windows:
+  EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user'
+  EAP7_HOME\bin\add-user.bat -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin'
+
+

The quickstart user establishes the actual connection to the server.

+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Configure the Server

+

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

+

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-elytron.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-elytron.cli file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart deployment. Comments in the script describe the purpose of each block of commands.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-elytron.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-elytron.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    5. +
  5. +

    Because this example quickstart demonstrates security, exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-system-exception.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-system-exception.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+
    +
    6. +
  6. Stop the JBoss EAP server.
    7. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. The following application-security-domain was added to the ejb3 subsystem: +
    <application-security-domains>
+    <application-security-domain name="quickstart-domain" security-domain="ApplicationDomain"/>
+</application-security-domains>
+
    +

    The application-security-domain essentially enables Elytron security for the quickstart EJBs. It maps the quickstart-domain that was set in the EJBs via annotation to the Elytron ApplicationDomain that will be responsible for authenticating and authorizing access to the EJBs.

    +
    2. +
  2. The following ejb-outbound-configuration authentication configuration and ejb-outbound-context authentication context were added to the elytron subsystem: +
    <authentication-configuration name="ejb-outbound-configuration" security-domain="ApplicationDomain" sasl-mechanism-selector="PLAIN"/>
+<authentication-context name="ejb-outbound-context">
+    <match-rule authentication-configuration="ejb-outbound-configuration"/>
+</authentication-context>
+
    +

    The ejb-outbound-configuration contains the authentication configuration that will be used when invoking a method on a remote EJB, for example when IntermediateEJB calls the methods on the SecuredEJB. The above configuration specifies that the identity that is currently authenticated to the ApplicationDomain will be used to establish the connection to the remote EJB. The sasl-mechanism-selector defines the SASL mechanisms that should be tried. In this quickstart the PLAIN mechanism has been chosen because other challenge-response mechanisms such as DIGEST-MD5 can't provide the original credential to establish the connection to the remote EJB.

    +

    The ejb-outbound-context is the authentication context that is used by the remote outbound connection and it automatically selects the ejb-outbound-configuration.

    +
    3. +
  3. +

    The following ejb-outbound outbound-socket-binding connection was created within the standard-sockets socket-binding-group:

    +
    <outbound-socket-binding name="ejb-outbound">
+    <remote-destination host="localhost" port="8080"/>
+</outbound-socket-binding>
+
    +

    For the purpose of the quickstart we just need an outbound connection that loops back to the same server. This will be sufficient to demonstrate the server-to-server capabilities.

    +
    4. +
  4. The following ejb-outbound-connection remote-outbound-connection was added to the outbound-connections within the remoting subsytem: +
    <outbound-connections>
+    <remote-outbound-connection name="ejb-outbound-connection" outbound-socket-binding-ref="ejb-outbound" authentication-context="ejb-outbound-context"/>
+</outbound-connections>
+
    +
    5. +
  5. The http-connector in the remoting subsystem was updated to use the application-sasl-authentication authentication factory. It allows for the identity that was established in the connection authentication to be propagated to the components. +
    <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm" sasl-authentication-factory="application-sasl-authentication"/>
+
    +
    6. +
  6. +

    Finally, the application-sasl-authentication factory was updated in the elytron subsystem to include the PLAIN mechanism:

    +
    <sasl-authentication-factory name="application-sasl-authentication" sasl-server-factory="configured" security-domain="ApplicationDomain">
+    <mechanism-configuration>
+        <mechanism mechanism-name="PLAIN"/>
+        <mechanism mechanism-name="JBOSS-LOCAL-USER" realm-mapper="local"/>
+        <mechanism mechanism-name="DIGEST-MD5">
+            <mechanism-realm realm-name="ApplicationRealm"/>
+        </mechanism>
+    </mechanism-configuration>
+</sasl-authentication-factory>
+
    +
    7. +
  7. +

    If you chose to run the script to suppress system exceptions, you should see the following configuration in the ejb3 subsystem.

    +
    <log-system-exceptions value="false"/>
+
    +
    8. +
+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/ejb-security-context-propagation.jar to the running instance of the server.

    +
    5. +
+

Run the Client

+

Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your command prompt is still in the same folder.

+

Type this command to execute the client:

+
mvn exec:exec
+
+

Investigate the Console Output

+

When you run the mvn exec:exec command, you see the following output. Note there may be other log messages interspersed between these.

+
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+
+    * * IntermediateEJB - Begin Testing with principal quickstartUser * *
+
+    Remote Security Information: [Principal=[quickstartUser], In role [guest]=true, In role [user]=true, In role [admin]=false]
+    Can invoke guestMethod? true
+    Can invoke userMethod? true
+    Can invoke adminMethod? false
+
+    * * IntermediateEJB - End Testing * *
+
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+
+    * * IntermediateEJB - Begin Testing with principal superUser * *
+
+    Remote Security Information: [Principal=[superUser], In role [guest]=true, In role [user]=true, In role [admin]=true]
+    Can invoke guestMethod? true
+    Can invoke userMethod? true
+    Can invoke adminMethod? true
+
+    * * IntermediateEJB - End Testing * *
+
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+

As can be seen from the output the identities authenticated to the intermediate EJB were propagated all the way to the remote secured EJB and their roles have been correctly evaluated.

+

Investigate the Server Console Output

+

If you chose not to run the script to suppress system exceptions, you should see the following exceptions in the JBoss EAP server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not authorized.

+
    12:26:06,556 ERROR [org.jboss.as.ejb3.invocation] (default task-57) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_context_propagation.SecuredEJBRemote.adminMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_context_propagation.SecuredEJBRemote.adminMethod() of bean: SecuredEJB is not allowed
+        at org.jboss.as.ejb3.security.RolesAllowedInterceptor.processInvocation(RolesAllowedInterceptor.java:67)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.as.ejb3.security.SecurityDomainInterceptor.processInvocation(SecurityDomainInterceptor.java:44)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.as.ejb3.deployment.processors.StartupAwaitInterceptor.processInvocation(StartupAwaitInterceptor.java:22)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.as.ejb3.component.interceptors.ShutDownInterceptorFactory$1.processInvocation(ShutDownInterceptorFactory.java:64)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.as.ejb3.deployment.processors.EjbSuspendInterceptor.processInvocation(EjbSuspendInterceptor.java:57)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.as.ejb3.component.interceptors.LoggingInterceptor.processInvocation(LoggingInterceptor.java:67)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.as.ee.component.NamespaceContextInterceptor.processInvocation(NamespaceContextInterceptor.java:50)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.as.ejb3.component.interceptors.AdditionalSetupInterceptor.processInvocation(AdditionalSetupInterceptor.java:54)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.invocation.ContextClassLoaderInterceptor.processInvocation(ContextClassLoaderInterceptor.java:60)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.invocation.InterceptorContext.run(InterceptorContext.java:438)
+        at org.wildfly.security.manager.WildFlySecurityManager.doChecked(WildFlySecurityManager.java:609)
+        at org.jboss.invocation.AccessCheckingInterceptor.processInvocation(AccessCheckingInterceptor.java:57)
+        at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
+        at org.jboss.invocation.ChainedInterceptor.processInvocation(ChainedInterceptor.java:53)
+        at org.jboss.as.ee.component.ViewService$View.invoke(ViewService.java:198)
+        at org.wildfly.security.auth.server.SecurityIdentity.runAsFunctionEx(SecurityIdentity.java:380)
+        at org.jboss.as.ejb3.remote.AssociationImpl.invokeWithIdentity(AssociationImpl.java:492)
+        at org.jboss.as.ejb3.remote.AssociationImpl.invokeMethod(AssociationImpl.java:487)
+        at org.jboss.as.ejb3.remote.AssociationImpl.lambda$receiveInvocationRequest$0(AssociationImpl.java:188)
+        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
+        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
+        at java.lang.Thread.run(Thread.java:745)
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can restore the original server configuration by running the restore-configuration.cli script provided in the root directory of this quickstart or by manually restoring the backup copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli
+
    +

    This script reverts the changes made to the ejb3, elytron and remoting subsystems. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    3. +
  3. If you choose to run the script to suppress system exceptions, run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-system-exception.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-system-exception.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+
    +
    4. +
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the backup copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart requires additional configuration and deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+
    +
  1. Be sure to Add the Application Users as described above.
    2. +
  2. Follow the steps above to Configure the Server. Stop the server at the end of that step.
    3. +
  3. To deploy the application to the JBoss EAP server, right-click on the ejb-security-context-propagation project and choose Run As --> Run on Server.
    4. +
  4. To access the application, right-click on the ejb-security-context-propagation project and choose Run As --> Java Application.
    5. +
  5. Choose RemoteClient - org.jboss.as.quickstarts.ejb_security_context_propagation and click OK.
    6. +
  6. Review the output in the console window.
    7. +
  7. To undeploy the project, right-click on the ejb-security-context-propagation project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    8. +
  8. Be sure to Restore the Server Configuration when you have completed testing this quickstart.
    9. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-security-context-propagation/README.md b/ejb-security-context-propagation/README.md index 44d202ac93..b4a340964c 100644 --- a/ejb-security-context-propagation/README.md +++ b/ejb-security-context-propagation/README.md @@ -4,13 +4,13 @@ Author: Stefan Guilhen Level: Advanced Technologies: EJB, Security Summary: The `ejb-security-context-propagation` quickstart demonstrates how the security context can be propagated to a remote EJB using a remote outbound connection configuration -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? The `ejb-security-context-propagation` quickstart demonstrates how the security context of an EJB can be propagated to a -remote EJB in ${product.name.full}. +remote EJB in Red Hat JBoss Enterprise Application Platform. The quickstart makes use of two EJBs, `SecuredEJB` and `IntermediateEJB`, to verify that the security context propagation is correct, and a `RemoteClient` standalone client. @@ -46,12 +46,12 @@ to run the test. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version}. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on -how to install and run JBoss, see the [${product.name.full} Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. +To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on +how to install and run JBoss, see the [Red Hat JBoss Enterprise Application Platform Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) to run the quickstarts. @@ -61,14 +61,14 @@ This quickstart uses the default standalone configuration plus the modifications It is recommended that you test this approach in a separate and clean environment before you attempt to port the changes in your own environment. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The -installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The +installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add the Application Users -This quickstart uses secured management interfaces and is built around the default `ApplicationRealm` as configured in the ${product.name} distribution. You must create the following application user to access the running application: +This quickstart uses secured management interfaces and is built around the default `ApplicationRealm` as configured in the JBoss EAP distribution. You must create the following application user to access the running application: | **UserName** | **Realm** | **Password** | **Roles** | |:-----------|:-----------|:-----------|:-----------| @@ -78,12 +78,12 @@ This quickstart uses secured management interfaces and is built around the defau To add the user, open a command prompt and type the following commands: For Linux: - ${jboss.home.name}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user' - ${jboss.home.name}/bin/add-user.sh -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin' + EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user' + EAP7_HOME/bin/add-user.sh -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin' For Windows: - ${jboss.home.name}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user' - ${jboss.home.name}\bin\add-user.bat -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin' + EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user' + EAP7_HOME\bin\add-user.bat -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin' The `quickstart` user establishes the actual connection to the server. @@ -97,37 +97,37 @@ These steps assume you are running the server in standalone mode and using the d You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart deployment. Comments in the script describe the purpose of each block of commands. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-elytron.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-elytron.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-elytron.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-elytron.cli You should see the following result when you run the script: The batch executed successfully process-state: reload-required -5. Because this example quickstart demonstrates security, exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing ${jboss.home.name} with the path to your server: +5. Because this example quickstart demonstrates security, exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-system-exception.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-system-exception.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-system-exception.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-system-exception.cli You should see the following result when you run the script: The batch executed successfully -6. Stop the ${product.name} server. +6. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following `application-security-domain` was added to the `ejb3` subsystem: @@ -186,21 +186,21 @@ After stopping the server, open the `${jboss.home.name}/standalone/configuration ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.jar` to the running instance of the server. +4. This will deploy `target/ejb-security-context-propagation.jar` to the running instance of the server. ## Run the Client @@ -251,7 +251,7 @@ secured EJB and their roles have been correctly evaluated. ## Investigate the Server Console Output -If you chose not to run the script to suppress system exceptions, you should see the following exceptions in the ${product.name} +If you chose not to run the script to suppress system exceptions, you should see the following exceptions in the JBoss EAP server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not authorized. @@ -290,7 +290,7 @@ authorized. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -302,22 +302,22 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-configuration.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-configuration.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli This script reverts the changes made to the `ejb3`, `elytron` and `remoting` subsystems. You should see the following result when you run the script: The batch executed successfully process-state: reload-required -3. If you choose to run the script to suppress system exceptions, run the following command, replacing ${jboss.home.name} with the path to your server: +3. If you choose to run the script to suppress system exceptions, run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-system-exception.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-system-exception.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-system-exception.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-system-exception.cli You should see the following result when you run the script: @@ -325,23 +325,23 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the backup copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the backup copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). This quickstart requires additional configuration and deploys and runs differently in JBoss Developer Studio than the other quickstarts. 1. Be sure to [Add the Application Users](#add-the-application-users) as described above. 2. Follow the steps above to [Configure the Server](#configure-the-server). Stop the server at the end of that step. -3. To deploy the application to the ${product.name} server, right-click on the `${project.artifactId}` project and choose `Run As` --> `Run on Server`. -4. To access the application, right-click on the `${project.artifactId}` project and choose `Run As` --> `Java Application`. +3. To deploy the application to the JBoss EAP server, right-click on the `ejb-security-context-propagation` project and choose `Run As` --> `Run on Server`. +4. To access the application, right-click on the `ejb-security-context-propagation` project and choose `Run As` --> `Java Application`. 5. Choose `RemoteClient - org.jboss.as.quickstarts.ejb_security_context_propagation` and click `OK`. 6. Review the output in the console window. -7. To undeploy the project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +7. To undeploy the project, right-click on the `ejb-security-context-propagation` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. 8. Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/ejb-security-context-propagation/pom.xml b/ejb-security-context-propagation/pom.xml index ff0a59b86a..cd6feb65e2 100644 --- a/ejb-security-context-propagation/pom.xml +++ b/ejb-security-context-propagation/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-security-context-propagation diff --git a/ejb-security-interceptors/README.html b/ejb-security-interceptors/README.html new file mode 100644 index 0000000000..fefb298510 --- /dev/null +++ b/ejb-security-interceptors/README.html @@ -0,0 +1,453 @@ + + + ejb-security-interceptors: Use Interceptors to Switch Identities for an EJB Call + + + +

ejb-security-interceptors: Use Interceptors to Switch Identities for an EJB Call

+

Author: Darran Lofthouse, Stefan Guilhen
+Level: Advanced
+Technologies: EJB, Security
+Summary: The ejb-security-interceptors quickstart demonstrates how to use client and server side interceptors to switch the identity for an EJB call.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/ Deprecated: This quickstart is deprecated in favour of ejb-security-context-propagation and ejb-security-programatic-auth

+

What is it?

+

The ejb-security-interceptors quickstart demonstrates how to use client and server side interceptors to switch the identity for an EJB call in Red Hat JBoss Enterprise Application Platform.

+

By default, when you make a remote call to an EJB deployed to the application server, the connection to the server is authenticated and any request received over this connection is executed as the identity that authenticated the connection. This is true for both client-to-server and server-to-server calls. If you need to use different identities from the same client, you normally need to open multiple connections to the server so that each one is authenticated as a different identity.

+

Rather than open multiple client connections, this quickstart offers an alternative solution. The identity used to authenticate the connection is given permission to execute a request as a different user. This is achieved with the addition of the following three components:

+
    +
  1. A client side interceptor to pass the requested identity to the remote server.
    2. +
  2. A server side interceptor to receive the identity and request that the call switches to that identity.
    3. +
  3. A JAAS LoginModule to decide if the user of the connection is allowed to execute requests as the specified identity.
    4. +
+

The quickstart then makes use of two EJBs, SecuredEJB and IntermediateEJB, to verify that the propagation and identity switching is correct and a RemoteClient standalone client.

+

SecuredEJB

+

The SecuredEJB has three methods:

+
String getSecurityInformation();
+boolean roleOneMethod();
+boolean roleTwoMethod();
+
+

The first method can be called by all users that are created in this quickstart. The purpose of this method is to return a String containing the name of the Principal that called the EJB along with the user's authorized role information, for example:

+
    [Principal={ConnectionUser}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=false]
+
+

The next two methods are annotated to require that the calling user is authorized for roles RoleOne and RoleTwo respectively.

+

IntermediateEJB

+

The IntermediateEJB contains a single method. Its purpose is to make use of a remote connection and invoke each of the methods on the SecuredEJB. A summary is then returned with the outcome of the calls.

+

RemoteClient

+

Finally there is the RemoteClient stand-alone client. The client makes calls using the identity of the established connection and also makes calls switching the identity to the different users.

+

In the real world, remote calls between servers in the servers-to-server scenario would truly be remote and separate. For the purpose of this quickstart, we make use of a loopback connection to the same server so we do not need two servers just to run the test.

+

Note on EJB client interceptors

+

JBoss EAP allows client side interceptors for EJB invocations. Such interceptors are expected to implement the org.jboss.ejb.client.EJBClientInterceptor interface. User applications can then plug in such interceptors in the 'EJBClientContext' either programatically or through the ServiceLoader mechanism.

+
    +
  • The programmatic way involves calling the org.jboss.ejb.client.EJBClientContext.registerInterceptor(int order, EJBClientInterceptor interceptor) API and passing the 'order' and the 'interceptor' instance. The 'order' is used to decide where exactly in the client interceptor chain, this 'interceptor' is going to be placed.
    • +
  • The ServiceLoader mechanism is an alternate approach which involves creating a META-INF/services/org.jboss.ejb.client.EJBClientInterceptor file and placing/packaging it in the classpath of the client application. The rules for such a file are dictated by the Java ServiceLoader Mechanism. This file is expected to contain in each separate line the fully qualified class name of the EJB client interceptor implementation, which is expected to be available in the classpath. EJB client interceptors added via the ServiceLoader mechanism are added to the end of the client interceptor chain, in the order they were found in the classpath.
    • +
+

This quickstart uses the ServiceLoader mechanism for registering the EJB client interceptor and places the META-INF/services/org.jboss.ejb.client.EJBClientInterceptor in the classpath, with the following content:

+
    # EJB client interceptor(s) that will be added to the end of the interceptor chain during an invocation
+    # on EJB. If these interceptors are to be added at a specific position, other than last, then use the
+    # programmatic API in the application to register it explicitly to the EJBClientContext
+
+    org.jboss.as.quickstarts.ejb_security_interceptors.ClientSecurityInterceptor
+
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Prerequisites

+

This quickstart uses the default standalone configuration plus the modifications described here.

+

It is recommended that you test this approach in a separate and clean environment before you attempt to port the changes in your own environment.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add the Application Users

+

This quickstart uses secured management interfaces and is built around the default ApplicationRealm as configured in the JBoss EAP distribution. You must create the following application users to access the running application:

+ + + + + + + + + + +
UserName Realm Password Roles
ConnectionUser ApplicationRealm ConnectionPassword1! User
AppUserOne ApplicationRealm AppPasswordOne1! User, RoleOne
AppUserTwo ApplicationRealm AppPasswordTwo1! User, RoleTwo
AppUserThree ApplicationRealm AppPasswordThree1! User, RoleOne, RoleTwo
+

To add the users, open a command prompt and type the following commands:

+
    For Linux:
+      EAP7_HOME/bin/add-user.sh -a -u 'ConnectionUser' -p 'ConnectionPassword1!' -g 'User'
+      EAP7_HOME/bin/add-user.sh -a -u 'AppUserOne' -p 'AppPasswordOne1!' -g 'User,RoleOne'
+      EAP7_HOME/bin/add-user.sh -a -u 'AppUserTwo' -p 'AppPasswordTwo1!' -g 'User,RoleTwo'
+      EAP7_HOME/bin/add-user.sh -a -u 'AppUserThree' -p 'AppPasswordThree1!' -g 'User,RoleOne,RoleTwo'
+
+    For Windows:
+      EAP7_HOME\bin\add-user.bat -a -u 'ConnectionUser' -p 'ConnectionPassword1!' -g 'User'
+      EAP7_HOME\bin\add-user.bat -a -u 'AppUserOne' -p 'AppPasswordOne1!' -g 'User,RoleOne'
+      EAP7_HOME\bin\add-user.bat -a -u 'AppUserTwo' -p 'AppPasswordTwo1!' -g 'User,RoleTwo'
+      EAP7_HOME\bin\add-user.bat -a -u 'AppUserThree' -p 'AppPasswordThree1!' -g 'User,RoleOne,RoleTwo'
+
+

The first user establishes the actual connection to the server. The subsequent two users demonstrate how to switch identities on demand. The final user can access everything but can not participate in identity switching.

+

Note that within the quickstart, we do not make use of the passwords for any of the App users. The passwords specified for those users are only suggested values that meet password minimum requirements.

+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Configure the Server

+

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

+

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-security-domain.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-security-domain.cli file in the root of this quickstart directory. This script adds the quickstart-domain security domain to the security subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-security-domain.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+
    +
    5. +
  5. Because this example quickstart demonstrates security, exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-system-exception.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-system-exception.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+
    +
    6. +
  6. Stop the JBoss EAP server.
    7. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. The following quickstart-domain security-domain was added to the security subsystem. +
    <security-domain name="quickstart-domain" cache-type="default">
+    <authentication>
+        <login-module name="DelegationLoginModule" code="org.jboss.as.quickstarts.ejb_security_interceptors.DelegationLoginModule" flag="optional">
+            <module-option name="password-stacking" value="useFirstPass"/>
+        </login-module>
+        <login-module code="Remoting" flag="optional">
+            <module-option name="password-stacking" value="useFirstPass"/>
+        </login-module>
+        <login-module code="RealmDirect" flag="required">
+            <module-option name="password-stacking" value="useFirstPass"/>
+        </login-module>
+    </authentication>
+</security-domain>
+
    +

    The EJB side of this quickstart makes use of a new security domain called quickstart-domain, which delegates to the ApplicationRealm. The DelegationLoginModule is used to support identity switching in this quickstart.

    +

    The login module can either be added before or after the existing Remoting login module in the domain, but it MUST be somewhere before the existing RealmDirect login module. If the majority of requests will involve an identity switch, then it is recommended to have this module as the first module in the list. However, if the majority of requests will run as the connection user with occasional switches, it is recommended to place the Remoting login module first and this one second.

    +

    The login module loads the properties file delegation-mapping.properties from the deployment. The location of this properties file can be overridden with the module-option delegationProperties. At runtime, this login module is used to decide if the user of the connection to the server is allowed to execute the request as the specified user.

    +

    There are four ways the key can be specified in the properties file:

    +
    user@realm  - Exact match of user and realm.
+user@*      - Allow a match of user for any realm.
+*@realm     - Match for any user in the realm specified.
+*           - Match for all users in all realms.
+
    +

    When a request is received to switch the user, the identity of the user that opened the connection is used to check the properties file for an entry. The check is performed in the order listed above until the first match is found. Once a match is found, further entries that could match are not read. The value in the properties file can either be a wildcard "*" or it can be a comma separated list of users. Be aware that in the value/mapping side there is no notion of the realm. For this quickstart we use the following entry:

    +
    ConnectionUser@ApplicationRealm=AppUserOne,AppUserTwo
+
    +

    This means that the ConnectionUser added above can only ask that a request is executed as either AppUserOne or AppUserTwo. It is not allowed to ask to be executed as AppUserThree.

    +

    All users are permitted to execute requests as themselves. In that case, the login module is not called. This is the default behavior that exists without the addition of the interceptors in this quickstart.

    +

    Taking this further, the DelegationLoginModule can be extended to provide custom delegation checks. One thing not currently checked is if the user being switched to actually exists. If the module is extended, the following method can be overridden to provide a custom check.

    +
     protected boolean delegationAcceptable(String requestedUser, OuterUserCredential connectionUser);
+
    +

    For the purpose of the quickstart we just need an outbound connection that loops back to the same server. This will be sufficient to demonstrate the server-to-server capabilities.

    +
    2. +
  2. The following ejb-outbound-realm security-realm was added to the management security-realms. Note the Base64-encoded password is for the ConnectionUser account created above. +
    <security-realm name="ejb-outbound-realm">
+    <server-identities>
+        <secret value="Q29ubmVjdGlvblBhc3N3b3JkMSE="/>
+    </server-identities>
+</security-realm>
+
    +
    3. +
  3. The following ejb-outbound outbound-socket-binding connection was created within the standard-sockets socket-binding-group: +
    <outbound-socket-binding name="ejb-outbound">
+    <remote-destination host="localhost" port="8080"/>
+</outbound-socket-binding>
+
    +
    4. +
  4. The following ejb-outbound-connection remote-outbound-connection was added to the outbound-connections within the remoting subsytem: +
    <outbound-connections>
+    <remote-outbound-connection name="ejb-outbound-connection" outbound-socket-binding-ref="ejb-outbound" security-realm="ejb-outbound-realm" username="ConnectionUser">
+        <properties>
+            <property name="SSL_ENABLED" value="false"/>
+        </properties>
+    </remote-outbound-connection>
+</outbound-connections>
+
    +
    5. +
  5. If you chose to run the script to suppress system exceptions, you should see the following configuration in the ejb3 subsystem. +
    <log-system-exceptions value="false"/>
+
    +
    6. +
+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/ejb-security-interceptors.jar to the running instance of the server.

    +
    5. +
+

Run the Client

+

Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your command prompt is still in the same folder.

+

Type this command to execute the client:

+
    mvn exec:exec
+
+

Investigate the Console Output

+

When you run the mvn exec:exec command, you see the following output. Note there may be other log messages interspersed between these.

+
-------------------------------------------------
+* * About to perform test as ConnectionUser * *
+
+* Making Direct Calls to the SecuredEJB
+
+* getSecurityInformation()=[Principal={ConnectionUser}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=false]
+* Can call roleOneMethod()=false
+* Can call roleTwoMethod()=false
+
+* Calling the IntermediateEJB to repeat the test server to server
+
+* * IntermediateEJB - Begin Testing * *
+SecuredEJBRemote.getSecurityInformation()=[Principal={ConnectionUser}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=false]
+Can call roleOneMethod=false
+Can call roleTwoMethod=false
+* * IntermediateEJB - End Testing * *
+* * Test Complete * *
+
+-------------------------------------------------
+* * About to perform test as AppUserOne * *
+
+* Making Direct Calls to the SecuredEJB
+
+* getSecurityInformation()=[Principal={AppUserOne}, In role {User}=true, In role {RoleOne}=true, In role {RoleTwo}=false]
+* Can call roleOneMethod()=true
+* Can call roleTwoMethod()=false
+
+* Calling the IntermediateEJB to repeat the test server to server
+
+* * IntermediateEJB - Begin Testing * *
+SecuredEJBRemote.getSecurityInformation()=[Principal={AppUserOne}, In role {User}=true, In role {RoleOne}=true, In role {RoleTwo}=false]
+Can call roleOneMethod=true
+Can call roleTwoMethod=false
+* * IntermediateEJB - End Testing * *
+* * Test Complete * *
+
+-------------------------------------------------
+* * About to perform test as AppUserTwo * *
+
+* Making Direct Calls to the SecuredEJB
+
+* getSecurityInformation()=[Principal={AppUserTwo}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=true]
+* Can call roleOneMethod()=false
+* Can call roleTwoMethod()=true
+
+* Calling the IntermediateEJB to repeat the test server to server
+
+* * IntermediateEJB - Begin Testing * *
+SecuredEJBRemote.getSecurityInformation()=[Principal={AppUserTwo}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=true]
+Can call roleOneMethod=false
+Can call roleTwoMethod=true
+* * IntermediateEJB - End Testing * *
+* * Test Complete * *
+
+-------------------------------------------------
+* * About to perform test as AppUserThree * *
+
+* Making Direct Calls to the SecuredEJB
+
+* * Test Complete * *
+
+-------------------------------------------------
+Call as 'AppUserThree' correctly rejected.
+
+This second round of tests is using the (PicketBox) ClientLoginModule with LoginContext API to set the desired Principal.
+
+-------------------------------------------------
+* * About to perform test as ConnectionUser * *
+
+
+* Making Direct Calls to the SecuredEJB
+
+* getSecurityInformation()=[Principal={ConnectionUser}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=false]
+* Can call roleOneMethod()=false
+* Can call roleTwoMethod()=false
+
+* Calling the IntermediateEJB to repeat the test server to server
+
+* * IntermediateEJB - Begin Testing * *
+SecuredEJBRemote.getSecurityInformation()=[Principal={ConnectionUser}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=false]
+Can call roleOneMethod=false
+Can call roleTwoMethod=false
+* * IntermediateEJB - End Testing * *
+* * Test Complete * *
+
+-------------------------------------------------
+* * About to perform test as AppUserOne * *
+
+* Making Direct Calls to the SecuredEJB
+
+* getSecurityInformation()=[Principal={AppUserOne}, In role {User}=true, In role {RoleOne}=true, In role {RoleTwo}=false]
+* Can call roleOneMethod()=true
+* Can call roleTwoMethod()=false
+
+* Calling the IntermediateEJB to repeat the test server to server
+
+* * IntermediateEJB - Begin Testing * *
+SecuredEJBRemote.getSecurityInformation()=[Principal={AppUserOne}, In role {User}=true, In role {RoleOne}=true, In role {RoleTwo}=false]
+Can call roleOneMethod=true
+Can call roleTwoMethod=false
+* * IntermediateEJB - End Testing * *
+* * Test Complete * *
+
+-------------------------------------------------
+* * About to perform test as AppUserTwo * *
+
+* Making Direct Calls to the SecuredEJB
+
+* getSecurityInformation()=[Principal={AppUserTwo}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=true]
+* Can call roleOneMethod()=false
+* Can call roleTwoMethod()=true
+
+* Calling the IntermediateEJB to repeat the test server to server
+
+* * IntermediateEJB - Begin Testing * *
+SecuredEJBRemote.getSecurityInformation()=[Principal={AppUserTwo}, In role {User}=true, In role {RoleOne}=false, In role {RoleTwo}=true]
+Can call roleOneMethod=false
+Can call roleTwoMethod=true
+* * IntermediateEJB - End Testing * *
+* * Test Complete * *
+
+-------------------------------------------------
+* * About to perform test as AppUserThree * *
+
+* Making Direct Calls to the SecuredEJB
+
+* * Test Complete * *
+
+-------------------------------------------------
+Call as 'AppUserThree' correctly rejected.
+
+* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+

Investigate the Server Console Output

+

If you chose not to run the script to suppress system exceptions, you should see the following exceptions in the JBoss EAP server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not authorized. The stacktraces were removed from this text for readability.

+
ERROR [org.jboss.as.ejb3.invocation] (EJB default - 3) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 7) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 6) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 9) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 1) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 6) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 5) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 7) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 9) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.getSecurityInformation(): javax.ejb.EJBAccessException: WFLYSEC0027: Invalid User
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 10) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 5) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 7) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 8) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 3) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 7) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleTwoMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 2) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 5) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed
+...
+ERROR [org.jboss.as.ejb3.invocation] (EJB default - 8) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.getSecurityInformation(): javax.ejb.EJBAccessException: WFLYSEC0027: Invalid User
+
+

Server Log: Expected warnings and errors

+

Note: You will see the following warning appear twice in the server log. You can ignore these warnings.

+
WARN  [org.jboss.as.dependency.deprecated] (MSC service thread 1-7) WFLYSRV0221: Deployment "deployment.jboss-ejb-security-interceptors.jar" is using a deprecated module ("org.jboss.as.core-security-api:main") which may be removed in future versions without notice.
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Original Server Configuration

+

You can remove the security domain configuration by running the remove-security-domain.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore the Original Server Configuration by Running the JBoss CLI Script

+
    For Linux:  EAP7_HOME/bin/standalone.sh
+    For Windows:  EAP7_HOME\bin\standalone.bat
+
+
    +
  1. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh  --connect --file=remove-security-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat  --connect --file=remove-security-domain.cli
+
    +

    This script removes the test queue from the messaging subsystem in the server configuration. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    2. +
  2. If you chose to run the script to suppress system exceptions, run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-system-exception.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-system-exception.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+
    +
    3. +
+

Restore the Original Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart requires additional configuration and deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+
    +
  1. Be sure to Add the Application Users as described above.
    2. +
  2. Follow the steps above to Configure the Server. Stop the server at the end of that step.
    3. +
  3. To deploy the application to the JBoss EAP server, right-click on the ejb-security-interceptors project and choose Run As --> Run on Server.
    4. +
  4. To access the application, right-click on the ejb-security-interceptors project and choose Run As --> Java Application.
    5. +
  5. Choose RemoteClient - org.jboss.as.quickstarts.ejb_security_interceptors and click OK.
    6. +
  6. Review the output in the console window.
    7. +
  7. To undeploy the project, right-click on the ejb-security-interceptors project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    8. +
  8. Be sure to Restore the Original Server Configuration when you have completed testing this quickstart.
    9. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-security-interceptors/README.md b/ejb-security-interceptors/README.md index b294ac817a..0995968156 100644 --- a/ejb-security-interceptors/README.md +++ b/ejb-security-interceptors/README.md @@ -4,13 +4,13 @@ Author: Darran Lofthouse, Stefan Guilhen Level: Advanced Technologies: EJB, Security Summary: The `ejb-security-interceptors` quickstart demonstrates how to use client and server side interceptors to switch the identity for an EJB call. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: Deprecated: This quickstart is deprecated in favour of ejb-security-context-propagation and ejb-security-programatic-auth ## What is it? -The `ejb-security-interceptors` quickstart demonstrates how to use client and server side interceptors to switch the identity for an EJB call in ${product.name.full}. +The `ejb-security-interceptors` quickstart demonstrates how to use client and server side interceptors to switch the identity for an EJB call in Red Hat JBoss Enterprise Application Platform. By default, when you make a remote call to an EJB deployed to the application server, the connection to the server is authenticated and any request received over this connection is executed as the identity that authenticated the connection. This is true for both client-to-server and server-to-server calls. If you need to use different identities from the same client, you normally need to open multiple connections to the server so that each one is authenticated as a different identity. @@ -48,7 +48,7 @@ In the real world, remote calls between servers in the servers-to-server scenari ## Note on EJB client interceptors -${product.name} allows client side interceptors for EJB invocations. Such interceptors are expected to implement the `org.jboss.ejb.client.EJBClientInterceptor` interface. User applications can then plug in such interceptors in the 'EJBClientContext' either programatically or through the ServiceLoader mechanism. +JBoss EAP allows client side interceptors for EJB invocations. Such interceptors are expected to implement the `org.jboss.ejb.client.EJBClientInterceptor` interface. User applications can then plug in such interceptors in the 'EJBClientContext' either programatically or through the ServiceLoader mechanism. - The programmatic way involves calling the `org.jboss.ejb.client.EJBClientContext.registerInterceptor(int order, EJBClientInterceptor interceptor)` API and passing the 'order' and the 'interceptor' instance. The 'order' is used to decide where exactly in the client interceptor chain, this 'interceptor' is going to be placed. - The ServiceLoader mechanism is an alternate approach which involves creating a `META-INF/services/org.jboss.ejb.client.EJBClientInterceptor` file and placing/packaging it in the classpath of the client application. The rules for such a file are dictated by the [Java ServiceLoader Mechanism](http://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html). This file is expected to contain in each separate line the fully qualified class name of the EJB client interceptor implementation, which is expected to be available in the classpath. EJB client interceptors added via the ServiceLoader mechanism are added to the end of the client interceptor chain, in the order they were found in the classpath. @@ -63,9 +63,9 @@ This quickstart uses the ServiceLoader mechanism for registering the EJB client ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version}. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Prerequisites @@ -73,13 +73,13 @@ This quickstart uses the default standalone configuration plus the modifications It is recommended that you test this approach in a separate and clean environment before you attempt to port the changes in your own environment. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add the Application Users -This quickstart uses secured management interfaces and is built around the default `ApplicationRealm` as configured in the ${product.name} distribution. You must create the following application users to access the running application: +This quickstart uses secured management interfaces and is built around the default `ApplicationRealm` as configured in the JBoss EAP distribution. You must create the following application users to access the running application: | **UserName** | **Realm** | **Password** | **Roles** | |:-----------|:-----------|:-----------|:-----------| @@ -91,16 +91,16 @@ This quickstart uses secured management interfaces and is built around the defau To add the users, open a command prompt and type the following commands: For Linux: - ${jboss.home.name}/bin/add-user.sh -a -u 'ConnectionUser' -p 'ConnectionPassword1!' -g 'User' - ${jboss.home.name}/bin/add-user.sh -a -u 'AppUserOne' -p 'AppPasswordOne1!' -g 'User,RoleOne' - ${jboss.home.name}/bin/add-user.sh -a -u 'AppUserTwo' -p 'AppPasswordTwo1!' -g 'User,RoleTwo' - ${jboss.home.name}/bin/add-user.sh -a -u 'AppUserThree' -p 'AppPasswordThree1!' -g 'User,RoleOne,RoleTwo' + EAP7_HOME/bin/add-user.sh -a -u 'ConnectionUser' -p 'ConnectionPassword1!' -g 'User' + EAP7_HOME/bin/add-user.sh -a -u 'AppUserOne' -p 'AppPasswordOne1!' -g 'User,RoleOne' + EAP7_HOME/bin/add-user.sh -a -u 'AppUserTwo' -p 'AppPasswordTwo1!' -g 'User,RoleTwo' + EAP7_HOME/bin/add-user.sh -a -u 'AppUserThree' -p 'AppPasswordThree1!' -g 'User,RoleOne,RoleTwo' For Windows: - ${jboss.home.name}\bin\add-user.bat -a -u 'ConnectionUser' -p 'ConnectionPassword1!' -g 'User' - ${jboss.home.name}\bin\add-user.bat -a -u 'AppUserOne' -p 'AppPasswordOne1!' -g 'User,RoleOne' - ${jboss.home.name}\bin\add-user.bat -a -u 'AppUserTwo' -p 'AppPasswordTwo1!' -g 'User,RoleTwo' - ${jboss.home.name}\bin\add-user.bat -a -u 'AppUserThree' -p 'AppPasswordThree1!' -g 'User,RoleOne,RoleTwo' + EAP7_HOME\bin\add-user.bat -a -u 'ConnectionUser' -p 'ConnectionPassword1!' -g 'User' + EAP7_HOME\bin\add-user.bat -a -u 'AppUserOne' -p 'AppPasswordOne1!' -g 'User,RoleOne' + EAP7_HOME\bin\add-user.bat -a -u 'AppUserTwo' -p 'AppPasswordTwo1!' -g 'User,RoleTwo' + EAP7_HOME\bin\add-user.bat -a -u 'AppUserThree' -p 'AppPasswordThree1!' -g 'User,RoleOne,RoleTwo' The first user establishes the actual connection to the server. The subsequent two users demonstrate how to switch identities on demand. The final user can access everything but can not participate in identity switching. @@ -116,35 +116,35 @@ These steps assume you are running the server in standalone mode and using the d You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-security-domain.cli` file in the root of this quickstart directory. This script adds the `quickstart-domain` security domain to the `security` subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-security-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-security-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-security-domain.cli You should see the following result when you run the script: The batch executed successfully -5. Because this example quickstart demonstrates security, exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing ${jboss.home.name} with the path to your server: +5. Because this example quickstart demonstrates security, exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-system-exception.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-system-exception.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-system-exception.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-system-exception.cli You should see the following result when you run the script: The batch executed successfully -6. Stop the ${product.name} server. +6. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following `quickstart-domain` security-domain was added to the `security` subsystem. @@ -216,21 +216,21 @@ After stopping the server, open the `${jboss.home.name}/standalone/configuration ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.jar` to the running instance of the server. +4. This will deploy `target/ejb-security-interceptors.jar` to the running instance of the server. ## Run the Client @@ -379,7 +379,7 @@ When you run the `mvn exec:exec` command, you see the following output. Note the ## Investigate the Server Console Output -If you chose not to run the script to suppress system exceptions, you should see the following exceptions in the ${product.name} server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not authorized. The stacktraces were removed from this text for readability. +If you chose not to run the script to suppress system exceptions, you should see the following exceptions in the JBoss EAP server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not authorized. The stacktraces were removed from this text for readability. ERROR [org.jboss.as.ejb3.invocation] (EJB default - 3) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security_interceptors.SecuredEJBRemote.roleOneMethod() of bean: SecuredEJB is not allowed ... @@ -425,7 +425,7 @@ _Note:_ You will see the following warning appear twice in the server log. You c ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -437,20 +437,20 @@ You can remove the security domain configuration by running the `remove-securit ### Restore the Original Server Configuration by Running the JBoss CLI Script - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=remove-security-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=remove-security-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-security-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-security-domain.cli This script removes the `test` queue from the `messaging` subsystem in the server configuration. You should see the following result when you run the script: The batch executed successfully process-state: reload-required -3. If you chose to run the script to suppress system exceptions, run the following command, replacing ${jboss.home.name} with the path to your server: +3. If you chose to run the script to suppress system exceptions, run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-system-exception.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-system-exception.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-system-exception.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-system-exception.cli You should see the following result when you run the script: @@ -458,23 +458,23 @@ You can remove the security domain configuration by running the `remove-securit ### Restore the Original Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). This quickstart requires additional configuration and deploys and runs differently in JBoss Developer Studio than the other quickstarts. 1. Be sure to [Add the Application Users](#add-the-application-users) as described above. 2. Follow the steps above to [Configure the Server](#configure-the-server). Stop the server at the end of that step. -3. To deploy the application to the ${product.name} server, right-click on the `${project.artifactId}` project and choose `Run As` --> `Run on Server`. -4. To access the application, right-click on the `${project.artifactId}` project and choose `Run As` --> `Java Application`. +3. To deploy the application to the JBoss EAP server, right-click on the `ejb-security-interceptors` project and choose `Run As` --> `Run on Server`. +4. To access the application, right-click on the `ejb-security-interceptors` project and choose `Run As` --> `Java Application`. 5. Choose `RemoteClient - org.jboss.as.quickstarts.ejb_security_interceptors` and click `OK`. 6. Review the output in the console window. -7. To undeploy the project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +7. To undeploy the project, right-click on the `ejb-security-interceptors` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. 8. Be sure to [Restore the Original Server Configuration](#restore-the-original-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/ejb-security-interceptors/pom.xml b/ejb-security-interceptors/pom.xml index a4236b282c..6c06125004 100644 --- a/ejb-security-interceptors/pom.xml +++ b/ejb-security-interceptors/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-security-interceptors diff --git a/ejb-security-jaas/README.html b/ejb-security-jaas/README.html new file mode 100644 index 0000000000..fd839cd3b4 --- /dev/null +++ b/ejb-security-jaas/README.html @@ -0,0 +1,301 @@ + + + ejb-security-jaas: Using the legacy JAAS security domains to secure JEE applications + + + +

ejb-security-jaas: Using the legacy JAAS security domains to secure JEE applications

+

Author: Stefan Guilhen
+Level: Intermediate
+Technologies: EJB, Security
+Summary: The ejb-security-jaas quickstart demonstrates how legacy JAAS security domains can be used in conjunction with Elytron to secure JEE applications.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-security-jaas quickstart demonstrates how legacy JAAS-based security domains can be used in conjunction with WildFly Elytron to secure JEE applications. The secured EJB component can be accessed indirectly using a web application and it can also be directly invoked by a remote client. This quickstart shows how Red Hat JBoss Enterprise Application Platform must be configured to support both scenarios using the legacy JAAS integration.

+

The overall steps required to use the JAAS integration are as follows: 1. Specify a JAAS security domain in the legacy security subsystem. 2. Export an Elytron-compatible security realm that delegates to the legacy JAAS security domain. 3. Create a security-domain in the elytron subsystem that uses the exported realm. 4. Setup an http-authentication-factory in the elytron subsystem to handle the web requests. 5. Setup a sasl-authentication-factory in the elytron subsystem to handle the requests made by remote clients. 6. Add the application-security-domain mappings to both ejb3 and undertow subsystems to enable Elytron security for the EJB3 and web components.

+

System Requirements

+

The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the Red Hat JBoss Enterprise Application Platform Documentation Getting Started Guide located on the Customer Portal.

+

You can also use JBoss Developer Studio or Eclipse to run the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Create the Properties Files for the JAAS Security Domain

+
    +
  1. Open a command line and navigate to the JBoss EAP server configuration directory: +
    For Linux:   EAP7_HOME/standalone/configuration
+For Windows: EAP7_HOME\standalone\configuration
+
    +
    2. +
  2. Create a file named users.properties and add the following username/password pair: +
    quickstartUser=quickstartPwd1!
+
    +
    3. +
  3. Create a file named roles.properties and add the following username/roles pair: +
    quickstartUser=guest
+
    +

    This concludes the configuration required by the legacy JAAS login module used in this quickstart.

    +
    4. +
+

Configure the Server

+

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

+

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-elytron-jaas.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-elytron-jaas.cli file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-elytron-jaas.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-elytron-jaas.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    5. +
  5. Stop the JBoss EAP server.
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. +

    The following security-domain was added to the legacy security subsystem:

    +
    <security-domain name="quickstart-domain" cache-type="default">
+    <authentication>
+        <login-module code="Remoting" flag="optional">
+            <module-option name="password-stacking" value="useFirstPass"/>
+        </login-module>
+        <login-module code="UsersRoles" flag="required">
+            <module-option name="usersProperties" value="${jboss.server.config.dir}/users.properties"/>
+            <module-option name="rolesProperties" value="${jboss.server.config.dir}/roles.properties"/>
+            <module-option name="password-stacking" value="useFirstPass"/>
+        </login-module>
+    </authentication>
+    <mapping>
+        <mapping-module code="SimpleRoles" type="role">
+            <module-option name="quickstartUser" value="admin"/>
+        </mapping-module>
+    </mapping>
+</security-domain>
+
    +

    The quickstart-domainis used to authenticate and authorize users. The Remoting login module is added to properly authenticate requests made from remote clients. A mapping-module is added that can be used to provide an extra role (admin). It is used later on to show how the legacy role mappers can be enabled and disabled.

    +
    2. +
  2. +

    The following elytron-realm was added to the legacy security subsystem:

    +
    <elytron-integration>
+    <security-realms>
+        <elytron-realm name="LegacyRealm" legacy-jaas-config="quickstart-domain" apply-role-mappers="false"/>
+    </security-realms>
+</elytron-integration>
+
    +

    This block tells the security subsystem to export an Elytron-compatible realm called LegacyRealm that will delegate authentication and authorization decisions to the legacy quickstart-domain. Setting the apply-role-mappers attribute to false indicates to the exported realm that it should not use any role mappers defined in the legacy security domain.

    +
    3. +
  3. +

    The following security-domain was added to the elytron subsystem:

    +
    <security-domain name="LegacyDomain" default-realm="LegacyRealm" permission-mapper="default-permission-mapper" security-event-listener="local-audit">
+    <realm name="LegacyRealm"/>
+</security-domain>
+
    +
    4. +
  4. +

    The following http-authentication-factory was added to the elytron subsystem:

    +
    <http-authentication-factory name="quickstart-http-authentication" http-server-mechanism-factory="global" security-domain="LegacyDomain">
+    <mechanism-configuration>
+        <mechanism mechanism-name="BASIC">
+            <mechanism-realm realm-name="Legacy Realm"/>
+        </mechanism>
+    </mechanism-configuration>
+</http-authentication-factory>
+
    +

    It creates the HTTP authentication factory that will handle BASIC requests by delegating the security domain created in step 3.

    +
    5. +
  5. +

    The following application-security-domain mapping was added to the undertow subsystem:

    +
    <application-security-domains>
+    <application-security-domain name="legacy-domain" http-authentication-factory="quickstart-http-authentication"/>
+</application-security-domains>
+
    +

    It tells Undertow to use the HTTP authentication factory created in step 4 for web applications that specify the security domain legacy-domain in their metadata. The quickstart application specifies this domain both for the web layer, in the jboss-web.xml file, and the EJB component, using annotation in the code.

    +
    6. +
  6. +

    The following sasl-authentication-factory was added to the elytron subsystem:

    +
    <sasl-authentication-factory name="quickstart-sasl-authentication" sasl-server-factory="configured" security-domain="LegacyDomain">
+    <mechanism-configuration>
+        <mechanism mechanism-name="PLAIN"/>
+    </mechanism-configuration>
+</sasl-authentication-factory>
+
    +
    7. +
  7. +

    The http-remoting-connector in the remoting subsystem was updated to use the sasl-authentication-factory created in step 6:

    +
    <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm" sasl-authentication-factory="quickstart-sasl-authentication"/>
+
    +

    Authentication performed by the quickstart remote client is handled by this SASL authentication factory.

    +
    8. +
  8. +

    Finally, the following application-security-domain mapping was added to the ejb3 subsystem:

    +
    <application-security-domains>
+    <application-security-domain name="legacy-domain" security-domain="LegacyDomain"/>
+</application-security-domains>
+
    +

    This mapping basically enables Elytron security for EJB3 applications that specify the security domain legacy-domain in their metadata (either via jboss-ejb3.xml or annotations). The quickstart application uses the @SecurityDomain annotation in the bean class to specify this security domain.

    +
    9. +
+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/ejb-security-jaas.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/ejb-security-jaas/.

+

When you access the application, you are presented with a browser login challenge.

+
    +
  1. If you attempt to login with a user name and password combination that has not been added to the server, the login challenge will be redisplayed.
    2. +
  2. When you login successfully using quickstartUser/quickstartPwd1!, the browser displays the following security info: +
    Successfully called Secured EJB
+
+Principal : quickstartUser
+Remote User : quickstartUser
+Has admin permission : false
+Authentication Type : BASIC
+
    +
    3. +
  3. +

    The application can also be accessed directly by a remote client. Type the following command in the root directory of the quickstart:

    +
    mvn exec:exec
+
    +

    The remote client application runs and displays the results of calling the secured bean:

    +
        * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+
+    Called secured bean, caller principal quickstartUser
+
+    Principal has admin permission: false
+
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
    +
    4. +
  4. +

    Next, change the exported realm so that it now uses the legacy role mappers as defined in the legacy JAAS security domain.

    +

    Make sure you are still in the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=enable-role-mappers.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=enable-role-mappers.cli
+
    +

    You should see the following result when you run the script:

    +
    {
+    "outcome" => "success",
+    "response-headers" => {
+        "operation-requires-reload" => true,
+        "process-state" => "reload-required"
+    }
+}
+
    +
    5. +
  5. +

    If you didn't close your web browser, re-load the quickstart application page. Otherwise open a new browser, point it to the URL http://localhost:8080/ejb-security-jaas/ and login with quickstartUser/quickstartPwd1!. It should now display a page confirming the user now has the admin role that was provided by the legacy role mapper:

    +
    Successfully called Secured EJB
+
+Principal : quickstartUser
+Remote User : quickstartUser
+Has admin permission : true
+Authentication Type : BASIC
+
    +
    6. +
  6. +

    The same result can be observed when re-running the remote client application:

    +
        * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+
+    Called secured bean, caller principal quickstartUser
+
+    Principal has admin permission: true
+
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
    +
    7. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can restore the original server configuration by running the restore-configuration.cli script provided in the root directory of this quickstart or by manually restoring the backup copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli
+
    +

    This script reverts the changes made to the ejb3, elytron, security and undertow subsystems. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    3. +
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the backup copy of the file.
    3. +
+

Remove the Properties Files from the Server

+

After you are done with this quickstart, remember to remove the users.properties and roles.properties files from the server configuration directory (EAP7_HOME/standalone/configuration/).

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+
    +
  • Be sure to Create the Properties Files for the JAAS Security Domain as described above.
    • +
  • Be sure to configure the server by running the JBoss CLI script as described above under Configure the Server. Stop the server at the end of that step.
    • +
  • To deploy the application to the JBoss EAP server, right-click on the ejb-security-jaas project and choose Run As --> Run on Server.
    • +
  • You are presented with a browser login challenge. Enter the credentials as described above under Access the Application to see the running application. Note that Has admin permission is false.
    • +
  • Leave the application running in JBoss Developer Studio. To configure the server to use the legacy role mappers, open a terminal, and run the enable-role-mappers.cli script as described above under Access the Application.
    • +
  • Go back to JBoss Developer Studio and click Refresh the current page. Note that Has admin permission is now true.
    • +
  • To undeploy the project, right-click on the ejb-security-jaas project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    • +
  • Be sure to Restore the Server Configuration when you have completed testing this quickstart.
    • +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-security-jaas/README.md b/ejb-security-jaas/README.md index 3f42ad7816..4f27295b04 100644 --- a/ejb-security-jaas/README.md +++ b/ejb-security-jaas/README.md @@ -5,12 +5,12 @@ Level: Intermediate Technologies: EJB, Security Summary: The `ejb-security-jaas` quickstart demonstrates how legacy `JAAS` security domains can be used in conjunction with `Elytron` to secure JEE applications. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-security-jaas` quickstart demonstrates how legacy `JAAS`-based security domains can be used in conjunction with `WildFly Elytron` to secure JEE applications. The secured EJB component can be accessed indirectly using a web application and it can also be directly invoked by a remote client. This quickstart shows how ${product.name.full} must be configured to support both scenarios using the legacy `JAAS` integration. +The `ejb-security-jaas` quickstart demonstrates how legacy `JAAS`-based security domains can be used in conjunction with `WildFly Elytron` to secure JEE applications. The secured EJB component can be accessed indirectly using a web application and it can also be directly invoked by a remote client. This quickstart shows how Red Hat JBoss Enterprise Application Platform must be configured to support both scenarios using the legacy `JAAS` integration. The overall steps required to use the `JAAS` integration are as follows: 1. Specify a `JAAS` security domain in the legacy `security` subsystem. @@ -22,24 +22,24 @@ The overall steps required to use the `JAAS` integration are as follows: ## System Requirements -The applications these projects produce are designed to be run on ${product.name.full} ${product.version} or later. +The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build these projects is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on how to install and run JBoss, see the [${product.name.full} Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. +To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the [Red Hat JBoss Enterprise Application Platform Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) to run the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Create the Properties Files for the JAAS Security Domain -1. Open a command line and navigate to the ${product.name} server `configuration` directory: +1. Open a command line and navigate to the JBoss EAP server `configuration` directory: - For Linux: ${jboss.home.name}/standalone/configuration - For Windows: ${jboss.home.name}\standalone\configuration + For Linux: EAP7_HOME/standalone/configuration + For Windows: EAP7_HOME\standalone\configuration 2. Create a file named `users.properties` and add the following username/password pair: quickstartUser=quickstartPwd1! @@ -54,29 +54,29 @@ These steps assume you are running the server in standalone mode and using the d You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron-jaas.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-elytron-jaas.cli` file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-elytron-jaas.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-elytron-jaas.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-elytron-jaas.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-elytron-jaas.cli You should see the following result when you run the script: The batch executed successfully process-state: reload-required -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following `security-domain` was added to the legacy `security` subsystem: @@ -158,25 +158,25 @@ After stopping the server, open the `${jboss.home.name}/standalone/configuration ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/ejb-security-jaas.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . When you access the application, you are presented with a browser login challenge. @@ -207,11 +207,11 @@ When you access the application, you are presented with a browser login challeng 4. Next, change the exported realm so that it now uses the legacy role mappers as defined in the legacy `JAAS` security domain. - Make sure you are still in the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} + Make sure you are still in the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=enable-role-mappers.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=enable-role-mappers.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=enable-role-mappers.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=enable-role-mappers.cli You should see the following result when you run the script: { @@ -223,7 +223,7 @@ When you access the application, you are presented with a browser login challeng } 5. If you didn't close your web browser, re-load the quickstart application page. Otherwise open a new browser, point it to the -URL and login with `quickstartUser/quickstartPwd1!`. It should now display a +URL and login with `quickstartUser/quickstartPwd1!`. It should now display a page confirming the user now has the `admin` role that was provided by the legacy role mapper: Successfully called Secured EJB @@ -247,7 +247,7 @@ page confirming the user now has the `admin` role that was provided by the legac ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -259,14 +259,14 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-configuration.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-configuration.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli This script reverts the changes made to the `ejb3`, `elytron`, `security` and `undertow` subsystems. You should see the following result when you run the script: The batch executed successfully @@ -274,25 +274,25 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the backup copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the backup copy of the file. ## Remove the Properties Files from the Server After you are done with this quickstart, remember to remove the `users.properties` and `roles.properties` files from the -server configuration directory (`${jboss.home.name}/standalone/configuration/`). +server configuration directory (`EAP7_HOME/standalone/configuration/`). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). * Be sure to [Create the Properties Files for the JAAS Security Domain](#create-the-properties-files-for-the-jaas-security-domain) as described above. * Be sure to configure the server by running the JBoss CLI script as described above under [Configure the Server](#configure-the-server). Stop the server at the end of that step. -* To deploy the application to the ${product.name} server, right-click on the `${project.artifactId}` project and choose `Run As` --> `Run on Server`. +* To deploy the application to the JBoss EAP server, right-click on the `ejb-security-jaas` project and choose `Run As` --> `Run on Server`. * You are presented with a browser login challenge. Enter the credentials as described above under [Access the Application](#access-the-application) to see the running application. Note that `Has admin permission` is `false`. * Leave the application running in JBoss Developer Studio. To configure the server to use the legacy role mappers, open a terminal, and run the `enable-role-mappers.cli` script as described above under [Access the Application](#access-the-application). * Go back to JBoss Developer Studio and click `Refresh the current page`. Note that `Has admin permission` is now `true`. -* To undeploy the project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +* To undeploy the project, right-click on the `ejb-security-jaas` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. * Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/ejb-security-jaas/pom.xml b/ejb-security-jaas/pom.xml index 8cd2182a98..44db77437b 100644 --- a/ejb-security-jaas/pom.xml +++ b/ejb-security-jaas/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-security-jaas diff --git a/ejb-security-programmatic-auth/README.html b/ejb-security-programmatic-auth/README.html new file mode 100644 index 0000000000..b3f3faea44 --- /dev/null +++ b/ejb-security-programmatic-auth/README.html @@ -0,0 +1,209 @@ + + + ejb-security-programmatic-auth: Using the programmatic API to invoke a remote EJB using different identities + + + +

ejb-security-programmatic-auth: Using the programmatic API to invoke a remote EJB using different identities

+

Author: Stefan Guilhen
+Level: Intermediate
+Technologies: EJB, Security
+Summary: The ejb-security-programmatic-auth quickstart demonstrates how to programmatically setup different identities when invoking a remote secured EJB.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-security-programmatic-auth quickstart demonstrates how to invoke a remote secured EJB using the Elytron client API to establish different identities. The quickstart client application accomplishes that by looking up and invoking the secured EJB under different AuthenticationContexts. Each context is setup to use a different identities and credentials.

+

System Requirements

+

The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the Red Hat JBoss Enterprise Application Platform Documentation Getting Started Guide located on the Customer Portal.

+

You can also use JBoss Developer Studio or Eclipse to run the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add the Application Users

+

Using the add-user utility script, you must add the following users to the ApplicationRealm:

+ + + + + + + + +
UserName Realm Password Roles
quickstartUser ApplicationRealm quickstartPwd1! guest
superUser ApplicationRealm superPwd1! guest,admin
+

The first application user has guest access rights to the application but no admin rights. The second user has both rights.

+

To add the application users, open a command prompt and type the following commands:

+
For Linux:
+   EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+   EAP7_HOME/bin/add-user.sh -a -u 'superUser' -p 'superPwd1!' -g 'guest,admin'
+
+For Windows:
+   EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+   EAP7_HOME\bin\add-user.bat -a -u 'superUser' -p 'superPwd1!' -g 'guest,admin'
+
+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Configure the Server

+

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

+

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-elytron.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-elytron.cli file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-elytron.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-elytron.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    5. +
  5. Stop the JBoss EAP server.
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. +

    The following application-security-domain mapping was added to the ejb3 subsystem:

    +
    <application-security-domains>
+    <application-security-domain name="quickstart-domain" security-domain="ApplicationDomain"/>
+</application-security-domains>
+
    +

    The application-security-domain essentially enables Elytron security for the quickstart EJBs. It maps the quickstart-domain that was set in the EJBs via annotation to the Elytron ApplicationDomain that will be responsible for authenticating and authorizing access to the EJBs.

    +
    2. +
  2. +

    The http-connector in the remoting subsystem was updated to use the application-sasl-authentication authentication factory:

    +
    <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm" sasl-authentication-factory="application-sasl-authentication"/>
+
    +

    This allows for the identity that was established in the connection authentication to be propagated to the components.

    +
    3. +
+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/ejb-security-programmatic-auth.jar to the running instance of the server.

    +
    5. +
+

Access the Application

+

Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your command prompt is still in the same folder.

+

Type this command to execute the client:

+
mvn exec:exec
+
+

Investigate the Console Output

+

When you run the mvn exec:exec command, you see the following output. Note there may be other log messages interspersed between these.

+
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+    Called secured bean, caller principal quickstartUser
+
+    Principal has admin permission: false
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+    Called secured bean, caller principal superUser
+
+    Principal has admin permission: true
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+

As expected, the quickstart user is able to call the methods available for guests but does not have the admin permission to call administrative methods on the remote EJB. The superUser on the other hand has permissions to call both methods.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can restore the original server configuration by running the restore-configuration.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli
+
    +

    This script reverts the changes made to the ejb3 and remoting subsystems. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    3. +
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+
    +
  • Be sure to Add the Application Users as described above.
    • +
  • Be sure to configure the server by running the JBoss CLI script as described above under Configure the Server.
    • +
  • Right-click on the ejb-security-programmatic-auth project and choose Run As --> Maven build. Enter clean package wildfly:deploy for the Goals: and click Run. This deploys the ejb-security-programmatic-auth JAR to the JBoss EAP server.
    • +
  • Right-click on the ejb-security-programmatic-auth project and choose Run As --> Run Configurations....
    • +
  • Enter exec:exec for the Goals and click Run.
    • +
  • Review the output in the console window. You should see the following output. +
        * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+    Called secured bean, caller principal quickstartUser
+
+    Principal has admin permission: false
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+    Called secured bean, caller principal superUser
+
+    Principal has admin permission: true
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
    +
    • +
  • +

    To undeploy the project, right-click on the ejb-security-programmatic-auth project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.

    +
    • +
  • Be sure to Restore the Server Configuration when you have completed testing this quickstart.
    • +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-security-programmatic-auth/README.md b/ejb-security-programmatic-auth/README.md index 91ac800d9c..eed5dd5eaf 100644 --- a/ejb-security-programmatic-auth/README.md +++ b/ejb-security-programmatic-auth/README.md @@ -4,8 +4,8 @@ Author: Stefan Guilhen Level: Intermediate Technologies: EJB, Security Summary: The `ejb-security-programmatic-auth` quickstart demonstrates how to programmatically setup different identities when invoking a remote secured EJB. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? @@ -13,17 +13,17 @@ The `ejb-security-programmatic-auth` quickstart demonstrates how to invoke a rem ## System Requirements -The applications these projects produce are designed to be run on ${product.name.full} ${product.version} or later. +The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build these projects is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on how to install and run JBoss, see the [${product.name.full} Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. +To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the [Red Hat JBoss Enterprise Application Platform Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) to run the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add the Application Users @@ -39,12 +39,12 @@ The first application user has `guest` access rights to the application but no ` To add the application users, open a command prompt and type the following commands: For Linux: - ${jboss.home.name}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' - ${jboss.home.name}/bin/add-user.sh -a -u 'superUser' -p 'superPwd1!' -g 'guest,admin' + EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' + EAP7_HOME/bin/add-user.sh -a -u 'superUser' -p 'superPwd1!' -g 'guest,admin' For Windows: - ${jboss.home.name}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' - ${jboss.home.name}\bin\add-user.bat -a -u 'superUser' -p 'superPwd1!' -g 'guest,admin' + EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' + EAP7_HOME\bin\add-user.bat -a -u 'superUser' -p 'superPwd1!' -g 'guest,admin' If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: [Add an Application User](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user). @@ -56,29 +56,29 @@ These steps assume you are running the server in standalone mode and using the d You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-elytron.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-elytron.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-elytron.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-elytron.cli You should see the following result when you run the script: The batch executed successfully process-state: reload-required -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following `application-security-domain` mapping was added to the `ejb3` subsystem: @@ -94,21 +94,21 @@ After stopping the server, open the `${jboss.home.name}/standalone/configuration ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.jar` to the running instance of the server. +4. This will deploy `target/ejb-security-programmatic-auth.jar` to the running instance of the server. ## Access the Application @@ -142,7 +142,7 @@ As expected, the `quickstart` user is able to call the methods available for `gu ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -154,15 +154,15 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-configuration.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-configuration.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli This script reverts the changes made to the `ejb3` and `remoting` subsystems. You should see the following result when you run the script: The batch executed successfully @@ -170,18 +170,18 @@ with the path to your server: ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). * Be sure to [Add the Application Users](#add-the-application-users) as described above. * Be sure to configure the server by running the JBoss CLI script as described above under [Configure the Server](#configure-the-server). -* Right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. -Enter `clean package wildfly:deploy` for the `Goals:` and click `Run`. This deploys the `${project.artifactId}` JAR to the ${product.name} server. -* Right-click on the `${project.artifactId}` project and choose `Run As` --> `Run Configurations...`. +* Right-click on the `ejb-security-programmatic-auth` project and choose `Run As` --> `Maven build`. +Enter `clean package wildfly:deploy` for the `Goals:` and click `Run`. This deploys the `ejb-security-programmatic-auth` JAR to the JBoss EAP server. +* Right-click on the `ejb-security-programmatic-auth` project and choose `Run As` --> `Run Configurations...`. * Enter `exec:exec` for the `Goals` and click `Run`. * Review the output in the console window. You should see the following output. @@ -201,7 +201,7 @@ Enter `clean package wildfly:deploy` for the `Goals:` and click `Run`. This depl * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -* To undeploy the project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +* To undeploy the project, right-click on the `ejb-security-programmatic-auth` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. * Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/ejb-security-programmatic-auth/pom.xml b/ejb-security-programmatic-auth/pom.xml index f3de722205..487755a71d 100644 --- a/ejb-security-programmatic-auth/pom.xml +++ b/ejb-security-programmatic-auth/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-security-programmatic-auth diff --git a/ejb-security/README.html b/ejb-security/README.html new file mode 100644 index 0000000000..9e4f604f6f --- /dev/null +++ b/ejb-security/README.html @@ -0,0 +1,208 @@ + + + ejb-security: Using Java EE Declarative Security to Control Access + + + +

ejb-security: Using Java EE Declarative Security to Control Access

+

Author: Sherif F. Makary, Stefan Guilhen
+Level: Intermediate
+Technologies: EJB, Security
+Summary: The ejb-security quickstart demonstrates the use of Java EE declarative security to control access to EJBs in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-security quickstart demonstrates the use of Java EE declarative security to control access to EJBs in Red Hat JBoss Enterprise Application Platform.

+

This quickstart takes the following steps to implement EJB security:

+
    +
  1. Add an application-security-domain mapping in the ejb3 subsystem to enable Elytron security for the SecuredEJB.
    2. +
  2. Add the @SecurityDomain("other") security annotation to the EJB declaration to tell the EJB container to apply authorization to this EJB.
    3. +
  3. Add the @RolesAllowed({ "guest" }) annotation to the EJB declaration to authorize access only to users with guest role access rights.
    4. +
  4. Add the @RolesAllowed({ "admin" }) annotation to the administrative method in the SecuredEJB to authorize access only to users with admin role access rights.
    5. +
  5. Add an application user with guest role access rights to the EJB. This quickstart defines a user quickstartUser with password quickstartPwd1! in the guest role. The guest role matches the allowed user role defined in the @RolesAllowed annotation in the EJB but it should not be granted access to the administrative method annotated with RolesAllowed({"admin"}).
    6. +
+

System Requirements

+

The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss EAP, see the Red Hat JBoss Enterprise Application Platform Getting Started Guide located on the Customer Portal.

+

You can also run the quickstart in Red Hat JBoss Developer Studio or Eclipse.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add the Application Users

+

Using the add-user utility script, you must add the following users to the ApplicationRealm:

+ + + + + + + +
UserName Realm Password Roles
quickstartUser ApplicationRealm quickstartPwd1! guest
+

The application user has guest access rights to the application but no admin rights.

+

To add the application users, open a command prompt and type the following commands:

+
For Linux:
+  EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+
+For Windows:
+  EAP7_HOME\bin\add-user.bat  -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+
+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Configure the Server

+

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

+

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-elytron.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-elytron.cli file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-elytron.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-elytron.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    5. +
  5. +

    Stop the JBoss EAP server.

    +
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. The following application-security-domain mapping was added to the ejb3 subsystem: +
    <application-security-domains>
+    <application-security-domain name="other" security-domain="ApplicationDomain"/>
+</application-security-domains>
+
    +

    The application-security-domain essentially enables Elytron security for the quickstart EJBs. It maps the other security domain that was set in the EJBs via annotation to the Elytron ApplicationDomain that will be responsible for authenticating and authorizing access to the EJBs.

    +
    2. +
  2. The http-remoting-connector in the remoting subsystem was updated to use the application-sasl-authentication factory: +
        <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm" sasl-authentication-factory="application-sasl-authentication"/>
+
    +

    This configuration allows for the identity that was established at the connection level to be propagated to the components.

    +
    3. +
+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/ejb-security.jar to the running instance of the server.

    +
    5. +
+

Run the Client

+

Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your command prompt is still in the root directory of this quickstart.

+

Type this command to execute the client:

+
mvn exec:exec
+
+

Investigate the Console Output

+

When you run the mvn exec:exec command, you see the following output. Note there may be other log messages interspersed between these messages.

+
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+
+    Successfully called secured bean, caller principal quickstartUser
+
+    Principal has admin permission: false
+
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+

The username and credentials used to establish the connection to the application server are configured in the wildfly-config.xml file. As expected, the quickstartUser was able to invoke the method available for the guestrole, but not the administrative method that requires the admin role.

+

NOTE: You should also see the following EJBAccessException printed in the server log, followed by a stack trace. This is to be expected because the user does not have the correct permissions to access the EJB.

+
07:00:15,364 ERROR [org.jboss.as.ejb3.invocation] (default task-38) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract boolean org.jboss.as.quickstarts.ejb_security.SecuredEJBRemote.administrativeMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract boolean org.jboss.as.quickstarts.ejb_security.SecuredEJBRemote.administrativeMethod() of bean: SecuredEJB is not allowed
+
+

As an exercise, you can rerun the add-user script described in the Add the Application Users section, but this time grant the quickstartUser the admin role as follows:

+
    For Linux:
+      EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin'
+
+    For Windows:
+      EAP7_HOME\bin\add-user.bat  -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin'
+
+

After you update the quickstartUser user role, you must restart the server for it to take effect. Running the client again should immediately reflect the new permission level of the user:

+
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+
+    Successfully called secured bean, caller principal quickstartUser
+
+    Principal has admin permission: true
+
+
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can restore the original server configuration by running the restore-configuration.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli
+
    +

    This script reverts the changes made to the ejb3 and undertow subsystems. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    3. +
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+
    +
  1. Be sure to Add the Application Users as described above.
    2. +
  2. Be sure to configure the server by running the JBoss CLI script as described above under Configure the Server.
    3. +
  3. To deploy the server project, right-click on the ejb-security project and choose Run As --> Maven build. Enter clean package wildfly:deploy for the Goals: and click Run. This deploys the ejb-security JAR to the JBoss EAP server.
    4. +
  4. Right-click on the ejb-security project and choose Run As --> Run Configurations. Enter exec:exec for the Goals, and then click Run.
    5. +
  5. Review the output in the console window. You should see the same results as when running Maven in the command line.
    6. +
  6. To undeploy the project, right-click on the ejb-security project and choose Run As --> Run Configurations. Enter wildfly:undeploy for the Goals and click Run.
    7. +
  7. Be sure to Restore the Server Configuration when you have completed testing this quickstart.
    8. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-security/README.md b/ejb-security/README.md index 4d3520ad74..a38d47f908 100644 --- a/ejb-security/README.md +++ b/ejb-security/README.md @@ -3,13 +3,13 @@ Author: Sherif F. Makary, Stefan Guilhen Level: Intermediate Technologies: EJB, Security -Summary: The `ejb-security` quickstart demonstrates the use of Java EE declarative security to control access to EJBs in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `ejb-security` quickstart demonstrates the use of Java EE declarative security to control access to EJBs in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-security` quickstart demonstrates the use of Java EE declarative security to control access to EJBs in ${product.name.full}. +The `ejb-security` quickstart demonstrates the use of Java EE declarative security to control access to EJBs in Red Hat JBoss Enterprise Application Platform. This quickstart takes the following steps to implement EJB security: @@ -24,18 +24,18 @@ annotation in the EJB but it should not be granted access to the administrative ## System Requirements -The applications these projects produce are designed to be run on ${product.name.full} ${product.version} or later. +The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build these projects is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on how to install and run ${product.name}, see the ${product.name.full} [_Getting Started Guide_](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) located on the Customer Portal. +To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss EAP, see the Red Hat JBoss Enterprise Application Platform [_Getting Started Guide_](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) located on the Customer Portal. You can also [run the quickstart in Red Hat JBoss Developer Studio or Eclipse](#run-the-quickstart-in-red-hat-jboss-developer-studio-or-eclipse). -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The -installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The +installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add the Application Users @@ -50,10 +50,10 @@ The application user has `guest` access rights to the application but no `admin` To add the application users, open a command prompt and type the following commands: For Linux: - ${jboss.home.name}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' + EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' For Windows: - ${jboss.home.name}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' + EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: [Add an Application User](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user). @@ -65,30 +65,30 @@ These steps assume you are running the server in standalone mode and using the d You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-elytron.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-elytron.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-elytron.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-elytron.cli You should see the following result when you run the script: The batch executed successfully process-state: reload-required -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following `application-security-domain` mapping was added to the `ejb3` subsystem: @@ -105,21 +105,21 @@ After stopping the server, open the `${jboss.home.name}/standalone/configuration ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.jar` to the running instance of the server. +4. This will deploy `target/ejb-security.jar` to the running instance of the server. ## Run the Client @@ -153,10 +153,10 @@ _NOTE:_ You should also see the following `EJBAccessException` printed in the se As an exercise, you can rerun the `add-user` script described in the [Add the Application Users](#add-the-application-users) section, but this time grant the `quickstartUser` the admin role as follows: For Linux: - ${jboss.home.name}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin' + EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin' For Windows: - ${jboss.home.name}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin' + EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin' After you update the `quickstartUser` user role, you must restart the server for it to take effect. Running the client again should immediately reflect the new permission level of the user: @@ -173,7 +173,7 @@ After you update the `quickstartUser` user role, you must restart the server for ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -185,14 +185,14 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-configuration.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-configuration.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli This script reverts the changes made to the `ejb3` and `undertow` subsystems. You should see the following result when you run the script: The batch executed successfully @@ -200,19 +200,19 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). 1. Be sure to [Add the Application Users](#add-the-application-users) as described above. 2. Be sure to configure the server by running the JBoss CLI script as described above under [Configure the Server](#configure-the-server). -3. To deploy the server project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. Enter `clean package wildfly:deploy` for the `Goals:` and click `Run`. This deploys the `${project.artifactId}` JAR to the ${product.name} server. -4. Right-click on the `${project.artifactId}` project and choose `Run As` --> `Run Configurations`. Enter `exec:exec` for the `Goals`, and then click `Run`. +3. To deploy the server project, right-click on the `ejb-security` project and choose `Run As` --> `Maven build`. Enter `clean package wildfly:deploy` for the `Goals:` and click `Run`. This deploys the `ejb-security` JAR to the JBoss EAP server. +4. Right-click on the `ejb-security` project and choose `Run As` --> `Run Configurations`. Enter `exec:exec` for the `Goals`, and then click `Run`. 5. Review the output in the console window. You should see the same results as when running Maven in the command line. -6. To undeploy the project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Run Configurations`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +6. To undeploy the project, right-click on the `ejb-security` project and choose `Run As` --> `Run Configurations`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. 7. Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/ejb-security/pom.xml b/ejb-security/pom.xml index 4b8abaa0be..108150779e 100644 --- a/ejb-security/pom.xml +++ b/ejb-security/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-security diff --git a/ejb-throws-exception/README.html b/ejb-throws-exception/README.html new file mode 100644 index 0000000000..3db90520c2 --- /dev/null +++ b/ejb-throws-exception/README.html @@ -0,0 +1,94 @@ + + + ejb-throws-exception: Handle Exceptions across JARs in an EAR + + + +

ejb-throws-exception: Handle Exceptions across JARs in an EAR

+

Author: Brad Maxwell
+Level: Intermediate
+Technologies: EJB, EAR
+Summary: The ejb-throws-exception quickstart demonstrates how to throw and handle Exceptions across JARs in an EAR.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-throws-exception quickstart extends the ejb-in-ear quickstart and demonstrates how to handle Exceptions across JARs in an EAR deployed to Red Hat JBoss Enterprise Application Platform. In this quickstart, an EJB in the EJB JAR throws a custom Exception. The web application in the client JAR catches the Exception and displays it in a nicely formatted message. The EAR contains: JSF WAR, an EJB JAR and a client library JAR containg classes that both the WAR and EJB JAR use.

+

The example is composed of three Maven projects, each with a shared parent. The projects are as follows:

+
    +
  1. +

    ejb: This project contains the EJB code and can be built independently to produce the JAR archive. The EJB has a single method sayHello which will take in a String name and return Hello <name> if the name is not null or an empty String. If the name is null or an empty String, then it will throw a custom Exception (GreeterException) back to the client.

    +
    2. +
  2. +

    web: This project contains the JSF pages and the CDI managed bean. The CDI Managed Bean (GreeterBean) will be bound to the JSF page (index.xhtml) and will invoke the GreeterEJB and display the response back from the EJB. The GreeterBean catches the custom Exception (GreeterException) thrown by GreeterEJB and displays the Exception message in the response text on the JSF page.

    +
    3. +
  3. +

    ear: This project builds the EAR artifact and pulls in the ejb, web, and client artifacts.

    +
    4. +
  4. +

    ejb-api: This project builds the ejb-api library artifact which is used by the ejb, web, as well as remote client artifacts. The ejb-api directory contains the EJB interfaces, custom exceptions the EJB throws and any other transfer objects which the EJB may receive or send back to the client. The EJB interfaces, custom exceptions, and other transfer objects are split into a separate JAR which is packaged in the ear/lib. This allows all sub deployments of the EAR to see the classes of the ejb-api JAR in the classpath. This is also useful for remote clients. The ejb-api JAR can be distributed to a remote client and give the remote clients the classes that are needed to interact with the EJB.

    +
    5. +
+

The root pom.xml builds each of the subprojects in the above order and deploys the EAR archive to the server.

+

The example follows the common Hello World pattern. These are the steps that occur:

+
    +
  1. A JSF page (http://localhost:8080/ejb-throws-exception/) asks for the user name.
    2. +
  2. On clicking Say Hello, the value of the Name input text is sent to a managed bean named GreeterBean.
    3. +
  3. On setting the name, the Greeter invokes the GreeterEJB, which was injected to the managed bean. Notice the field annotated with @EJB.
    4. +
  4. The EJB responds with Hello <name> or throws an Exception if the name is empty or null.
    5. +
  5. The response or exception's message from invoking the GreeterEJB is stored in a field (response) of the managed bean.
    6. +
  6. The managed bean is annotated as @RequestScoped, so the same managed bean instance is used only for the request/response.
    7. +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy ear/target/ejb-throws-exception.ear to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/ejb-throws-exception/.

+

Enter a name in the input field Name and click the Say Hello button to see the response.

+

The Response output text will display the response from the EJB. If the Name input text box is not empty, then the Response output text will display Hello <name> If the Name input text box is empty, then the Response output text will display the message of the exception throw back from the EJB.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

For this quickstart, follow the special instructions to build Quickstarts Containing an EAR

+
    +
  1. Right-click on the ejb-throws-exception-ear subproject, and choose Run As --> Run on Server.
    2. +
  2. Choose the server and click Finish.
    3. +
  3. This starts the server, deploys the application, and opens a browser window that accesses the running application.
    4. +
  4. To undeploy the project, right-click on the ejb-throws-exception-ear project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-throws-exception/README.md b/ejb-throws-exception/README.md index 853812644a..f6b2adddc7 100644 --- a/ejb-throws-exception/README.md +++ b/ejb-throws-exception/README.md @@ -4,12 +4,12 @@ Author: Brad Maxwell Level: Intermediate Technologies: EJB, EAR Summary: The `ejb-throws-exception` quickstart demonstrates how to throw and handle Exceptions across JARs in an EAR. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-throws-exception` quickstart extends the [ejb-in-ear](../ejb-in-ear/README.md) quickstart and demonstrates how to handle Exceptions across JARs in an EAR deployed to ${product.name.full}. In this quickstart, an EJB in the EJB JAR throws a custom Exception. The web application in the client JAR catches the Exception and displays it in a nicely formatted message. The EAR contains: *JSF WAR*, an *EJB* JAR and a client library JAR containg classes that both the WAR and EJB JAR use. +The `ejb-throws-exception` quickstart extends the [ejb-in-ear](../ejb-in-ear/README.md) quickstart and demonstrates how to handle Exceptions across JARs in an EAR deployed to Red Hat JBoss Enterprise Application Platform. In this quickstart, an EJB in the EJB JAR throws a custom Exception. The web application in the client JAR catches the Exception and displays it in a nicely formatted message. The EAR contains: *JSF WAR*, an *EJB* JAR and a client library JAR containg classes that both the WAR and EJB JAR use. The example is composed of three Maven projects, each with a shared parent. The projects are as follows: @@ -26,7 +26,7 @@ The root `pom.xml` builds each of the subprojects in the above order and deploys The example follows the common `Hello World` pattern. These are the steps that occur: -1. A JSF page (http://localhost:8080/${project.artifactId}/) asks for the user name. +1. A JSF page (http://localhost:8080/ejb-throws-exception/) asks for the user name. 2. On clicking `Say Hello`, the value of the `Name` input text is sent to a managed bean named `GreeterBean`. 3. On setting the name, the `Greeter` invokes the `GreeterEJB`, which was injected to the managed bean. Notice the field annotated with `@EJB`. 4. The EJB responds with `Hello ` or throws an Exception if the name is empty or null. @@ -35,39 +35,39 @@ The example follows the common `Hello World` pattern. These are the steps that o ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `ear/target/${project.artifactId}.ear` to the running instance of the server. +4. This will deploy `ear/target/ejb-throws-exception.ear` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . Enter a name in the input field `Name` and click the `Say Hello` button to see the response. @@ -78,7 +78,7 @@ If the `Name` input text box is empty, then the `Response` output text will disp ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -87,14 +87,14 @@ If the `Name` input text box is empty, then the `Response` output text will disp ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). For this quickstart, follow the special instructions to build [Quickstarts Containing an EAR](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-ear-project) -1. Right-click on the `${project.artifactId}-ear` subproject, and choose `Run As` --> `Run on Server`. +1. Right-click on the `ejb-throws-exception-ear` subproject, and choose `Run As` --> `Run on Server`. 2. Choose the server and click `Finish`. 3. This starts the server, deploys the application, and opens a browser window that accesses the running application. -4. To undeploy the project, right-click on the `${project.artifactId}-ear` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +4. To undeploy the project, right-click on the `ejb-throws-exception-ear` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/ejb-throws-exception/ear/pom.xml b/ejb-throws-exception/ear/pom.xml index 3c1bdf6d1b..dbcc52ee5a 100644 --- a/ejb-throws-exception/ear/pom.xml +++ b/ejb-throws-exception/ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-throws-exception - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-throws-exception-ear ear diff --git a/ejb-throws-exception/ejb-api/pom.xml b/ejb-throws-exception/ejb-api/pom.xml index d956e35ce8..2ecec1e344 100644 --- a/ejb-throws-exception/ejb-api/pom.xml +++ b/ejb-throws-exception/ejb-api/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-throws-exception - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-throws-exception-ejb-api jar diff --git a/ejb-throws-exception/ejb/pom.xml b/ejb-throws-exception/ejb/pom.xml index 81d5093201..bcbb6fefea 100644 --- a/ejb-throws-exception/ejb/pom.xml +++ b/ejb-throws-exception/ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-throws-exception - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-throws-exception-ejb ejb diff --git a/ejb-throws-exception/pom.xml b/ejb-throws-exception/pom.xml index 0d9f317bce..f3c538ef32 100644 --- a/ejb-throws-exception/pom.xml +++ b/ejb-throws-exception/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-throws-exception diff --git a/ejb-throws-exception/web/pom.xml b/ejb-throws-exception/web/pom.xml index 77ee3cdf0a..b7b18d7526 100644 --- a/ejb-throws-exception/web/pom.xml +++ b/ejb-throws-exception/web/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts ejb-throws-exception - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ejb-throws-exception-web war diff --git a/ejb-timer/README.html b/ejb-timer/README.html new file mode 100644 index 0000000000..743a5e88fd --- /dev/null +++ b/ejb-timer/README.html @@ -0,0 +1,81 @@ + + + ejb-timer: Example of EJB Timer Service - @Schedule and @Timeout + + + +

ejb-timer: Example of EJB Timer Service - @Schedule and @Timeout

+

Author: Ondrej Zizka ozizka@redhat.com
+Level: Beginner
+Technologies: EJB Timer
+Summary: The ejb-timer quickstart demonstrates how to use the EJB timer service @Schedule and @Timeout annotations with JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ejb-timer quickstart demonstrates how to use the EJB timer service in Red Hat JBoss Enterprise Application Platform. This example creates a timer service that uses the @Schedule and @Timeout annotations.

+

The following EJB Timer services are demonstrated:

+
    +
  • @Schedule: Uses this annotation to mark a method to be executed according to the calendar schedule specified in the attributes of the annotation. This example schedules a message to be printed to the server console every 6 seconds.
    • +
  • @Timeout: Uses this annotation to mark a method to execute when a programmatic timer goes off. This example sets the timer to go off every 3 seconds, at which point the method prints a message to the server console.
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
+

This will deploy target/ejb-timer.war to the running instance of the server.

+

Access the Application

+

This application only prints messages to stdout. To see it working, check the server log. You should see similar output:

+
INFO  [stdout] (EJB default - 10) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:12 EST
+INFO  [stdout] (EJB default - 2) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:12 EST
+INFO  [stdout] (EJB default - 4) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:15 EST
+INFO  [stdout] (EJB default - 3) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:18 EST
+INFO  [stdout] (EJB default - 5) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:18 EST
+INFO  [stdout] (EJB default - 7) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:21 EST
+INFO  [stdout] (EJB default - 9) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:24 EST
+INFO  [stdout] (EJB default - 6) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:24 EST
+INFO  [stdout] (EJB default - 8) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:27 EST
+INFO  [stdout] (EJB default - 1) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:30 EST
+INFO  [stdout] (EJB default - 10) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:30 EST
+INFO  [stdout] (EJB default - 2) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:33 EST
+INFO  [stdout] (EJB default - 4) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:36 EST
+INFO  [stdout] (EJB default - 3) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:36 EST
+INFO  [stdout] (EJB default - 5) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:39 EST
+INFO  [stdout] (EJB default - 7) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:42 EST
+
+

Existing threads in the thread pool handle the invocations. They are rotated and the name of the thread that handles the invocation is printed within the parenthesis (EJB Default - #).

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ejb-timer/README.md b/ejb-timer/README.md index 02e25441e1..b4b721a2bb 100644 --- a/ejb-timer/README.md +++ b/ejb-timer/README.md @@ -2,13 +2,13 @@ Author: Ondrej Zizka Level: Beginner Technologies: EJB Timer -Summary: The `ejb-timer` quickstart demonstrates how to use the EJB timer service `@Schedule` and `@Timeout` annotations with ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `ejb-timer` quickstart demonstrates how to use the EJB timer service `@Schedule` and `@Timeout` annotations with JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `ejb-timer` quickstart demonstrates how to use the EJB timer service in ${product.name.full}. This example creates a timer service that uses the `@Schedule` and `@Timeout` annotations. +The `ejb-timer` quickstart demonstrates how to use the EJB timer service in Red Hat JBoss Enterprise Application Platform. This example creates a timer service that uses the `@Schedule` and `@Timeout` annotations. The following EJB Timer services are demonstrated: @@ -19,34 +19,34 @@ The following EJB Timer services are demonstrated: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -This will deploy `target/${project.artifactId}.war` to the running instance of the server. +This will deploy `target/ejb-timer.war` to the running instance of the server. ## Access the Application @@ -76,7 +76,7 @@ Existing threads in the thread pool handle the invocations. They are rotated and ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -84,7 +84,7 @@ Existing threads in the thread pool handle the invocations. They are rotated and ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/ejb-timer/pom.xml b/ejb-timer/pom.xml index c1af05c60c..dfa939d3ce 100644 --- a/ejb-timer/pom.xml +++ b/ejb-timer/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml ejb-timer diff --git a/forge-from-scratch/README.html b/forge-from-scratch/README.html new file mode 100644 index 0000000000..54caafefc0 --- /dev/null +++ b/forge-from-scratch/README.html @@ -0,0 +1,109 @@ + + + forge-from-scratch: Shows How Forge Can Generate an Application + + + +

forge-from-scratch: Shows How Forge Can Generate an Application

+

Author: Lincoln Baxter, Matej Briskar
+Level: Intermediate
+Technologies: Forge
+Summary: The forge-from-scratch quickstart demonstrates how JBoss Forge can generate a Java EE (JPA, EJB, JAX-RS, JSF) web-enabled database application.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The forge-from-scratch quickstart demonstrates how to create a fully Java EE compliant project using JBoss Forge and Red Hat JBoss Developer Studio and deploy it to Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

The generated example will be a standard Maven, Java Web project with JPA, EJB, CDI, JSF with complete JAX-RS endpoints for all data Entities. It will also provide views to Create, Read, Update, and Delete records.

+

But that is not all! You can use Forge on your new or existing projects to continue to enhance any application.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Red Hat JBoss Developer Studio 10.0 or greater. These versions of JBoss Developer Studio embed Maven 3.3.3, so you do not need to install it separately.

+

Run the Quickstart in Red Hat JBoss Developer Studio

+

JBoss Developer Studio 10.3 ships with Forge 3.5.1.Final.

+

Generate and Build the Application

+
    +
  1. Start JBoss Developer Studio.
    2. +
  2. Open the Forge Console Window. To open it, navigate to menu item Window -> Show View -> Other. Locate Forge -> Forge Console and click OK.
    3. +
  3. Click the Start button (green triangle) in top right corner of the Forge Console to start the default Forge runtime.
    4. +
  4. In the Forge Console Window, navigate to the root directory of this quickstart. +
    $ cd QUICKSTART_HOME/forge-from-scratch/
+
    +
    5. +
  5. Notice there is a file in this directory named generate.fsh. Run this file from the Forge console using the run command: +
    $ run generate.fsh
+
    +
    6. +
  6. +

    At this point, Forge creates the new project and builds it.

    +
      +
    • The script issues this command: $ project-new --named forge-example --top-level-package org.example;
      • +
    • You next see the console message: ***SUCCESS*** Project named 'forge-example' has been created.
      • +
    • This is followed by a number of commands that set up JPA, create an entity and its fields, set up and generate the scaffold, and set up CDI and REST. Each command should result in a ***SUCCESS*** message.
      • +
    • Finally, the build command is executed, which should result in ***SUCCESS*** Build Success near the end of the console output.
      • +
    +
    7. +
+

NOTE: After you run the run generate.fsh command, you will see the following warnings in the Problems window for the generated files. You can ignore these warnings.

+
  Web XML Problem: location references to "/faces/error.xhtml" that does not exist in web content	web.xml	/forge-example/src/main/webapp/WEB-INF	line 17
+  Web XML Problem: location references to "/faces/error.xhtml" that does not exist in web content	web.xml	/forge-example/src/main/webapp/WEB-INF	line 21
+  JPA Problem: No connection specified for project. No database-specific validation will be performed.	forge-example
+
+

What Did This Create?

+

This quickstart created a native Java EE 7 application.

+
    +
  • After the command completes, look in your QUICKSTART_HOME/forge-from-scratch/ folder. You see a folder with the name forge-example.
    • +
  • This project also appears in the Project Explorer view in JBoss Developer Studio.
    • +
  • Browse through this project to see the code that was generated as a result of this command.
    • +
+

Deploy the Generated Application

+
    +
  1. If you have not yet done so, add the JBoss EAP 7.1 runtime server to Red Hat JBoss Developer Studio. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.
    2. +
  2. Right-click on the project name and choose Run As --> Run on Server. If you have more than one server, choose the JBoss EAP 7.1 Runtime server. Then click Finish.
    3. +
  3. Upon successful deployment, a Welcome to Forge Window opens with the application running at the following URL: http://localhost:8080/forge-example/
    4. +
+

Server Log: Expected warnings and errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYTX0013: Node identifier property is set to the default value. Please make sure it is unique.
+WFLYDM0111: Keystore /home/user/eap-7.1/standalone/configuration/application.keystore not found, it will be auto generated on first use with a self signed certificate for host localhost
+HHH000059: Defining hibernate.transaction.flush_before_completion=true ignored in HEM
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Access the Running Application

+

The application appears in a 'Welcome to Forge' Window and displays the following:

+
Welcome to Forge
+
+Your application is running.
+
+

The following entities are displayed on the lower left side of the page:

+
    +
  • Address
    • +
  • Customer
    • +
  • Item
    • +
  • Product Order
    • +
  • Profile
    • +
  • Zip Code
    • +
+

When you click on an entity, you are provided with a form that allows you to:

+
    +
  • Search for an existing entity
    • +
  • Create a new entity
    • +
  • Edit or delete an existing entity
    • +
+

The running application also provides links to find more information about the Forge.

+

Undeploy the Application

+

When you are ready to undeploy the application from JBoss EAP:

+
    +
  1. Go to the Red Hat JBoss Developer Studio Servers window.
    2. +
  2. Expand the JBoss EAP Server to see the list of deployed applications.
    3. +
  3. Choose the forge-example project created by this quickstart, right-click, and choose Remove.
    4. +
  4. Click OK when asked if you are sure you want to remove resource from the server. You should see the following message: +
    INFO  [org.jboss.as.server] (DeploymentScanner-threads - 1) WFLYSRV0009: Undeployed "forge-example.war" (runtime-name: "forge-example.war")
+
    +
    5. +
+

Next Steps

+

Open generate.fsh and take a look inside! There is not much magic happening here. All of the commands used to generate this project are clearly listed just as if they were typed by your own hands.

+

Play around with creating more entities, relationships, UI, and generating JAX-RS endpoints,all with just a few simple commands.

+ + \ No newline at end of file diff --git a/forge-from-scratch/README.md b/forge-from-scratch/README.md index 2a18e6ece9..293b5f4837 100644 --- a/forge-from-scratch/README.md +++ b/forge-from-scratch/README.md @@ -4,22 +4,22 @@ Author: Lincoln Baxter, Matej Briskar Level: Intermediate Technologies: Forge Summary: The `forge-from-scratch` quickstart demonstrates how *JBoss Forge* can generate a Java EE (JPA, EJB, JAX-RS, JSF) web-enabled database application. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `forge-from-scratch` quickstart demonstrates how to create a fully **Java EE compliant** project using **JBoss Forge** and **Red Hat JBoss Developer Studio** and deploy it to **${product.name.full} ${product.version}** or later. +The `forge-from-scratch` quickstart demonstrates how to create a fully **Java EE compliant** project using **JBoss Forge** and **Red Hat JBoss Developer Studio** and deploy it to **Red Hat JBoss Enterprise Application Platform 7.1** or later. The generated example will be a standard Maven, Java Web project with **JPA, EJB, CDI, JSF** with complete **JAX-RS** endpoints for all data Entities. It will also provide views to `Create`, `Read`, `Update`, and `Delete` records. But that is not all! You can use Forge on your new or existing projects to continue to enhance any application. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Red Hat JBoss Developer Studio 10.0 or greater. These versions of JBoss Developer Studio embed Maven 3.3.3, so you do not need to install it separately. @@ -63,8 +63,8 @@ This quickstart created a native Java EE 7 application. ### Deploy the Generated Application -1. If you have not yet done so, add the ${product.name} ${product.version} runtime server to Red Hat JBoss Developer Studio. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md). -2. Right-click on the project name and choose `Run As` --> `Run on Server`. If you have more than one server, choose the ${product.name} ${product.version} Runtime server. Then click `Finish`. +1. If you have not yet done so, add the JBoss EAP 7.1 runtime server to Red Hat JBoss Developer Studio. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md). +2. Right-click on the project name and choose `Run As` --> `Run on Server`. If you have more than one server, choose the JBoss EAP 7.1 Runtime server. Then click `Finish`. 3. Upon successful deployment, a **Welcome to Forge Window** opens with the application running at the following URL: ### Server Log: Expected warnings and errors @@ -105,11 +105,11 @@ The running application also provides links to find more information about the F ## Undeploy the Application -When you are ready to undeploy the application from ${product.name}: +When you are ready to undeploy the application from JBoss EAP: 1. Go to the Red Hat JBoss Developer Studio `Servers` window. -2. Expand the ${product.name} Server to see the list of deployed applications. +2. Expand the JBoss EAP Server to see the list of deployed applications. 3. Choose the `forge-example` project created by this quickstart, right-click, and choose `Remove`. 4. Click `OK` when asked if you are sure you want to remove resource from the server. You should see the following message: diff --git a/forge-from-scratch/pom.xml b/forge-from-scratch/pom.xml index a52763b671..a494a4610d 100644 --- a/forge-from-scratch/pom.xml +++ b/forge-from-scratch/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml forge-from-scratch diff --git a/greeter/README.html b/greeter/README.html new file mode 100644 index 0000000000..ee552958c5 --- /dev/null +++ b/greeter/README.html @@ -0,0 +1,77 @@ + + + greeter: Demonstrates CDI, JPA, JTA, EJB, and JSF + + + +

greeter: Demonstrates CDI, JPA, JTA, EJB, and JSF

+

Author: Pete Muir
+Level: Beginner
+Technologies: CDI, JSF, JPA, EJB, JTA
+Summary: The greeter quickstart demonstrates the use of CDI, JPA, JTA, EJB and JSF in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The greeter quickstart demonstrates the use of CDI, JPA, JTA, EJB and JSF in Red Hat JBoss Enterprise Application Platform.

+

When you deploy this example, two users are automatically created for you: emuster and jdoe. This data is located in the src/main/resources/import.sql file.

+

To test this example:

+
    +
  1. Enter a name in the username field and click on Greet!.
    2. +
  2. If you enter a username that is not in the database, you get a message No such user exists!.
    3. +
  3. If you enter a valid username, you get a message Hello, followed by the user's first and last name.
    4. +
  4. To create a new user, click the Add a new user link. Enter the username, first name, and last name and then click Add User. The user is added and a message displays the new user id number.
    5. +
  5. Click on the Greet a user! link to return to the Greet! page.
    6. +
+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/greeter.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/greeter/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/greeter/README.md b/greeter/README.md index c4c16c6f5b..6860145865 100644 --- a/greeter/README.md +++ b/greeter/README.md @@ -3,13 +3,13 @@ Author: Pete Muir Level: Beginner Technologies: CDI, JSF, JPA, EJB, JTA -Summary: The `greeter` quickstart demonstrates the use of *CDI*, *JPA*, *JTA*, *EJB* and *JSF* in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `greeter` quickstart demonstrates the use of *CDI*, *JPA*, *JTA*, *EJB* and *JSF* in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `greeter` quickstart demonstrates the use of *CDI*, *JPA*, *JTA*, *EJB* and *JSF* in ${product.name.full}. +The `greeter` quickstart demonstrates the use of *CDI*, *JPA*, *JTA*, *EJB* and *JSF* in Red Hat JBoss Enterprise Application Platform. When you deploy this example, two users are automatically created for you: `emuster` and `jdoe`. This data is located in the `src/main/resources/import.sql file`. @@ -22,51 +22,51 @@ To test this example: 5. Click on the `Greet a user!` link to return to the `Greet!` page. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/greeter.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -84,7 +84,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/greeter/pom.xml b/greeter/pom.xml index 10c1700c22..373d789dcc 100644 --- a/greeter/pom.xml +++ b/greeter/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml greeter diff --git a/h2-console/README.html b/h2-console/README.html new file mode 100644 index 0000000000..3c92ea8ead --- /dev/null +++ b/h2-console/README.html @@ -0,0 +1,53 @@ + + + h2-console: Example Using the H2 Console with JBoss EAP + + + +

h2-console: Example Using the H2 Console with JBoss EAP

+

Author: Pete Muir
+Level: Beginner
+Technologies: H2
+Summary: The h2-console quickstart demonstrates how to use the H2 Console that is bundled with and built specifically for JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

Red Hat JBoss Enterprise Application Platform bundles H2 as an in-memory, in-process database. H2 is written in Java so it can run on any platform that JBoss EAP runs on.

+

The h2-console quickstart comes bundled with a version of the H2 Console built for JBoss EAP. To make the H2 console run on JBoss EAP, the H2 libraries were removed from the WAR and a dependency on the H2 module was added to the META-INF/MANIFEST.MF file. The rebuilt console is provided in the root directory of this quickstart.

+

This quickstart demonstrates how to use the H2 console with Red Hat JBoss Enterprise Application Platform. It uses the greeter quickstart as a GUI for entering data.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Prerequisites

+

This quickstart depends on the deployment of the greeter quickstart. Before running this quickstart, see the greeter README file for details on how to deploy it.

+

You can verify the deployment of the greeter quickstart by accessing the following URL: http://localhost:8080/greeter/

+

When you have completed testing this quickstart, see the greeter README file for instructions to undeploy the archive.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Deploy the H2 Console

+

Deploy the console by copying the h2-console.war located in the root directory of this quickstart to the EAP7_HOME/standalone/deployments directory.

+

Note: You will see the following warning in the server log. You can ignore this warning.

+
WFLYSRV0019: Deployment "deployment.h2-console.war" is using an unsupported module ("com.h2database.h2:main") which may be changed or removed in future versions without notice.
+
+

Access the H2 Console

+

You can access the console at the following URL: http://localhost:8080/h2-console/.

+

You need to enter the JDBC URL, and credentials. To access the test database that the greeter quickstart uses, enter these details:

+
    +
  • JDBC URL: jdbc:h2:mem:greeter-quickstart;DB_CLOSE_ON_EXIT=FALSE;DB_CLOSE_DELAY=-1
    • +
  • User Name: sa
    • +
  • Password: sa
    • +
+

Click on the Test Connection button to make sure you can connect. If you can, go ahead and click Connect.

+

Investigate the H2 Console

+

Take a look at the data added by the greeter application. Run the following SQL command:

+
    select * from users;
+
+

You should see the two users seeded by the greeter quickstart, plus any users you added when testing that application.

+

Undeploy the Archive

+

To undeploy this example, simply delete the h2-console.war from the EAP7_HOME/standalone/deployments directory.

+
 cd EAP7_HOME/standalone/deployments
+ rm h2-console.war
+
+ + \ No newline at end of file diff --git a/h2-console/README.md b/h2-console/README.md index c22fef42fa..036627f12e 100644 --- a/h2-console/README.md +++ b/h2-console/README.md @@ -1,27 +1,27 @@ -# h2-console: Example Using the H2 Console with ${product.name} +# h2-console: Example Using the H2 Console with JBoss EAP Author: Pete Muir Level: Beginner Technologies: H2 -Summary: The `h2-console` quickstart demonstrates how to use the H2 Console that is bundled with and built specifically for ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `h2-console` quickstart demonstrates how to use the H2 Console that is bundled with and built specifically for JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -${product.name.full} bundles H2 as an in-memory, in-process database. H2 is written in Java so it can run on any platform that ${product.name} runs on. +Red Hat JBoss Enterprise Application Platform bundles H2 as an in-memory, in-process database. H2 is written in Java so it can run on any platform that JBoss EAP runs on. -The `h2-console` quickstart comes bundled with a version of the H2 Console built for ${product.name}. To make the H2 console run on ${product.name}, the H2 libraries were removed from the WAR and a dependency on the H2 module was added to the `META-INF/MANIFEST.MF` file. The rebuilt console is provided in the root directory of this quickstart. +The `h2-console` quickstart comes bundled with a version of the H2 Console built for JBoss EAP. To make the H2 console run on JBoss EAP, the H2 libraries were removed from the WAR and a dependency on the H2 module was added to the `META-INF/MANIFEST.MF` file. The rebuilt console is provided in the root directory of this quickstart. -This quickstart demonstrates how to use the H2 console with ${product.name.full}. It uses the `greeter` quickstart as a GUI for entering data. +This quickstart demonstrates how to use the H2 console with Red Hat JBoss Enterprise Application Platform. It uses the `greeter` quickstart as a GUI for entering data. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Prerequisites @@ -33,14 +33,14 @@ You can verify the deployment of the `greeter` quickstart by accessing the follo When you have completed testing this quickstart, see the [greeter README](../greeter/README.md) file for instructions to undeploy the archive. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Deploy the H2 Console -Deploy the console by copying the `h2-console.war` located in the root directory of this quickstart to the `${jboss.home.name}/standalone/deployments` directory. +Deploy the console by copying the `h2-console.war` located in the root directory of this quickstart to the `EAP7_HOME/standalone/deployments` directory. _Note:_ You will see the following warning in the server log. You can ignore this warning. @@ -48,7 +48,7 @@ _Note:_ You will see the following warning in the server log. You can ignore thi ## Access the H2 Console -You can access the console at the following URL: . +You can access the console at the following URL: . You need to enter the JDBC URL, and credentials. To access the `test` database that the `greeter` quickstart uses, enter these details: @@ -69,7 +69,7 @@ You should see the two users seeded by the `greeter` quickstart, plus any users ## Undeploy the Archive -To undeploy this example, simply delete the `h2-console.war` from the `${jboss.home.name}/standalone/deployments` directory. +To undeploy this example, simply delete the `h2-console.war` from the `EAP7_HOME/standalone/deployments` directory. - cd ${jboss.home.name}/standalone/deployments + cd EAP7_HOME/standalone/deployments rm h2-console.war diff --git a/h2-console/pom.xml b/h2-console/pom.xml index 3cc9ac40be..1587d043a4 100644 --- a/h2-console/pom.xml +++ b/h2-console/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml h2-console diff --git a/ha-singleton-deployment/README.html b/ha-singleton-deployment/README.html new file mode 100644 index 0000000000..83afca03dc --- /dev/null +++ b/ha-singleton-deployment/README.html @@ -0,0 +1,166 @@ + + + ha-singleton-deployment: Deploying Cluster-wide Singleton Services Using Singleton Deployments + + + +

ha-singleton-deployment: Deploying Cluster-wide Singleton Services Using Singleton Deployments

+

Author: Radoslav Husar
+Level: Advanced
+Technologies: EJB, Singleton Deployments, Clustering
+Summary: The ha-singleton-deployment quickstart demonstrates the recommended way to deploy any service packaged in an application archive as a cluster-wide singleton.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ha-singleton-deployment quickstart demonstrates the deployment of a service packaged in an application as a cluster-wide singleton using singleton deployments. In this example, the service is a timer that is initialized by a @Startup @Singleton bean. The example is built and packaged as a single EJB archive.

+

For more information about singleton deployments, see HA Singleton Deployments in the Development Guide for JBoss EAP.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

Everything needed to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure the environment is configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Setting Up the Test Environment

+

To demonstrate the singleton behavior, at least two application server instances must be started. Begin by making a copy of the entire JBoss EAP directory to be used as second cluster member. Note that the example can be run on a single node as well, but without observation of the singleton properties.

+

Start the two JBoss EAP servers with the same HA profile using the following commands. Note that a socket binding port offset and a unique node name must be passed to the second server if the servers are binding to the same host.

+

For Linux:

+
Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1
+Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100
+
+

For Windows:

+
Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node1
+Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100
+
+

The demonstration is not limited to two servers. Additional servers can be started by specifying a unique port offset for each one.

+

Running the Quickstart

+
    +
  1. Start the JBoss EAP servers as described in the above section.
    2. +
  2. Navigate to the root directory of this quickstart in the command prompt.
    3. +
  3. Use the following command to clean up previously built artifacts, and build and deploy the EJB archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    Ensure the target/ha-singleton-deployment.jar archive is deployed to node1 (the one without port offset) by observing the log.

    +
    INFO [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.jar" (runtime-name: "ha-singleton-deployment.jar")
+...
+INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node1 elected as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.jar".FIRST_MODULE_USE service
+INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.jar".FIRST_MODULE_USE service
+INFO [org.jboss.as.server] (management-handler-thread - 4) WFLYSRV0010: Deployed "ha-singleton-deployment.jar" (runtime-name : "ha-singleton-deployment.jar")
+...
+WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 68) SingletonTimer is initializing.
+INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World!
+
    +

    Note that the following warnings might appear in the server output after the applications are deployed. These can be safely ignored in a development environment.

    +
    WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+
    +
    5. +
  5. +

    Use the following command to deploy the already built archive to the second server. Note that since the default socket binding port is 9990 and the second server has ports offsetted by 100, the sum, 10090 must be passed as an argument to the deploy maven goal.

    +
    mvn wildfly:deploy -Dwildfly.port=10090
+
    +
    6. +
  6. +

    Ensure the service/target/ha-singleton-deployment.jar archive is deployed to node2 by observing the log. Note that even though the logs indicate "Deployed", the deployment does not actually deploy completely and the timer is not operating on this node.

    +
    INFO  [org.jboss.as.server.deployment] (MSC service thread 1-6) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.jar" (runtime-name: "ha-singleton-deployment.jar")
+INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000078: Starting JGroups channel server
+...
+INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2]
+...
+INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000079: Channel server local address is node2, physical addresses are [127.0.0.1:55300]
+INFO  [org.infinispan.factories.GlobalComponentRegistry] (MSC service thread 1-6) ISPN000128: Infinispan version: Infinispan 'Chakra' 8.2.7.Final
+INFO  [org.jboss.as.clustering.infinispan] (ServerService Thread Pool -- 68) WFLYCLINF0002: Started default cache from server container
+INFO  [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "ha-singleton-deployment.jar" (runtime-name : "ha-singleton-deployment.jar")
+
    +
    7. +
  7. +

    Verify the timer is running only on one instance by observing the logs. The node running the timer will output the following every 5 seconds:

    +
    INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World!
+
    +

    While the instance not running, the timer will display the following as the last log line:

    +
    INFO  [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "ha-singleton-deployment.jar" (runtime-name : "ha-singleton-deployment.jar")
+
    +
    8. +
  8. +

    Verify failover of the singleton deployment. Shutdown the server operating as the singleton master, for instance by using the Ctrl + C key combination in the command prompt. Observe the following messages on the node being shutdown:

    +
    INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 3) SingletonTimer: Hello World!
+INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 4) SingletonTimer: Hello World!
+INFO  [org.jboss.as.server] (Thread-2) WFLYSRV0220: Server shutdown has been requested via an OS signal
+WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 31) SingletonTimer is stopping: the server is either being shutdown or another node has become elected to be the singleton master.
+...
+INFO  [org.jboss.as] (MSC service thread 1-6) WFLYSRV0050: WildFly Core 3.0.0.Final stopped in 88ms
+
    +

    You might also see the following error in the singleton master log. This is due to the shutdown not finishing cleanly and is documented in JBEAP-9408. You can ignore this error.

    +
    ERROR [org.jboss.as.clustering.jgroups.protocol.NAKACK2] (thread-20) JGRP000039: node1: failed to deliver OOB message [dst: <null>, src: node2 (3 headers), size=73 bytes, flags=OOB|DONT_BUNDLE]: java.lang.IllegalStateException: channel is not connected
+
    +

    Now observe the log messages on the second server. The node will now be elected as the singleton master, deployment will complete, and the timer will start operating:

    +
    INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.jar".FIRST_MODULE_USE service
+INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.jar".FIRST_MODULE_USE service
+INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-4) ISPN000094: Received new cluster view for channel server: [node2|2] (1) [node2]
+...
+WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 68) SingletonTimer is initializing.
+INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World!
+INFO  [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 2) SingletonTimer: Hello World!
+
    +
    9. +
+

Troubleshooting

+

Should the singleton be running on multiple nodes, the most common causes are accidentally starting with the standalone.xml or standalone-full.xml profile instead of with the standalone-ha.xml or standalone-full-ha.xml profile. Make sure to start the server with an HA profile using -c standalone-ha.xml.

+

Another common cause is that the server instances did not discover each other and each server is operating as a singleton cluster. Ensure that multicast is enabled or change the jgroups subsystem configuration to use a different discovery mechanism. Observe the following log line to ensure that the discovery was successful:

+
INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2]
+
+

Making Existing Deployments Singleton

+

In this quickstart, the deployment is made singleton by a configuration file bundled in the archive. Inspect the content in src/main/resources/META-INF/singleton-deployment.xml. Any existing deployment can be made singleton by using deployment overlays mechanism. To demonstrate how to use deployment overlays, follow these steps:

+
    +
  1. Move the src/main/resources/META-INF/singleton-deployment.xml file into root directory of this quickstart.
    2. +
  2. Rebuild the project. Ensure that the servers are started, and redeploy the application, which will no longer be configured by singleton deployment by the archive: +
    mvn clean install
+mvn wildfly:deploy
+mvn wildfly:deploy -Dwildfly.port=10090
+
    +
    3. +
  3. +

    Start the management CLI and set up a deployment overlay on both servers:

    +
    EAP7_HOME_1/bin/jboss-cli.sh --connect
+deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.jar --content=META-INF/singleton-deployment.xml=singleton-deployment.xml
+deployment-overlay redeploy-affected --name=singleton-deployment
+
    +

    Repeat this process for the second server using the port offset:

    +
    EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090
+deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.jar --content=META-INF/singleton-deployment.xml=singleton-deployment.xml
+deployment-overlay redeploy-affected --name=singleton-deployment
+
    +
    4. +
  4. +

    Review the deployment overlay changes in the standalone-ha.xml server profile:

    +
    <deployment-overlays>
+    <deployment-overlay name="singleton-deployment">
+        <content path="META-INF/singleton-deployment.xml" content="60a35e2bb6a1886f0a4abe499c7af16833d2a533"/>
+        <deployment name="ha-singleton-deployment.jar"/>
+    </deployment-overlay>
+</deployment-overlays>
+
    +
    5. +
  5. +

    Observe the server output. The deployments are now set up as singleton deployments.

    +
    6. +
  6. +

    To remove the deployment overlay run the following CLI command:

    +
    deployment-overlay remove --name=singleton-deployment
+deployment-overlay redeploy-affected --name=singleton-deployment
+
    +
    7. +
+

For convenience, the management CLI scripts to add the deployment overlay, singleton-deployment-overlay-add.cli, and to remove the deployment overlay, singleton-deployment-overlay-remove.cli, are located in the root directory of this quickstart.

+

Undeploy the Archives

+
    +
  1. Ensure all JBoss EAP servers are started.
    2. +
  2. Navigate to the root directory of this quickstart in the command prompt.
    3. +
  3. Use the following commands to undeploy the artifacts: +
    mvn wildfly:undeploy
+mvn wildfly:undeploy -Dwildfly.port=10090
+
    +
    4. +
+ + \ No newline at end of file diff --git a/ha-singleton-deployment/README.md b/ha-singleton-deployment/README.md index 50a44008b2..857513316b 100644 --- a/ha-singleton-deployment/README.md +++ b/ha-singleton-deployment/README.md @@ -4,8 +4,8 @@ Author: Radoslav Husar Level: Advanced Technologies: EJB, Singleton Deployments, Clustering Summary: The `ha-singleton-deployment` quickstart demonstrates the recommended way to deploy any service packaged in an application archive as a cluster-wide singleton. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? @@ -18,47 +18,47 @@ For more information about singleton deployments, see _HA Singleton Deployments_ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -Everything needed to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure the environment is configured correctly for testing the quickstarts. +Everything needed to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure the environment is configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Setting Up the Test Environment To demonstrate the singleton behavior, at least two application server instances must be started. -Begin by making a copy of the entire ${product.name} directory to be used as second cluster member. +Begin by making a copy of the entire JBoss EAP directory to be used as second cluster member. Note that the example can be run on a single node as well, but without observation of the singleton properties. -Start the two ${product.name} servers with the same HA profile using the following commands. +Start the two JBoss EAP servers with the same HA profile using the following commands. Note that a socket binding port offset and a unique node name must be passed to the second server if the servers are binding to the same host. For Linux: - Server 1: ${jboss.home.name}_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 - Server 2: ${jboss.home.name}_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 + Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 For Windows: - Server 1: ${jboss.home.name}_1\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node1 - Server 2: ${jboss.home.name}_2\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node1 + Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 The demonstration is not limited to two servers. Additional servers can be started by specifying a unique port offset for each one. ## Running the Quickstart -1. Start the ${product.name} servers as described in the above section. +1. Start the JBoss EAP servers as described in the above section. 2. Navigate to the root directory of this quickstart in the command prompt. 3. Use the following command to clean up previously built artifacts, and build and deploy the EJB archive: mvn clean install wildfly:deploy -4. Ensure the `target/${project.artifactId}.jar` archive is deployed to `node1` (the one without port offset) by observing the log. +4. Ensure the `target/ha-singleton-deployment.jar` archive is deployed to `node1` (the one without port offset) by observing the log. INFO [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.jar" (runtime-name: "ha-singleton-deployment.jar") ... @@ -78,7 +78,7 @@ The demonstration is not limited to two servers. Additional servers can be start mvn wildfly:deploy -Dwildfly.port=10090 -6. Ensure the `service/target/${project.artifactId}.jar` archive is deployed to `node2` by observing the log. Note that even though the logs indicate "Deployed", the deployment does not actually deploy completely and the timer is not operating on this node. +6. Ensure the `service/target/ha-singleton-deployment.jar` archive is deployed to `node2` by observing the log. Note that even though the logs indicate "Deployed", the deployment does not actually deploy completely and the timer is not operating on this node. INFO [org.jboss.as.server.deployment] (MSC service thread 1-6) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.jar" (runtime-name: "ha-singleton-deployment.jar") INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000078: Starting JGroups channel server @@ -149,13 +149,13 @@ To demonstrate how to use deployment overlays, follow these steps: 3. Start the management CLI and set up a deployment overlay on both servers: - ${jboss.home.name}_1/bin/jboss-cli.sh --connect + EAP7_HOME_1/bin/jboss-cli.sh --connect deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.jar --content=META-INF/singleton-deployment.xml=singleton-deployment.xml deployment-overlay redeploy-affected --name=singleton-deployment Repeat this process for the second server using the port offset: - ${jboss.home.name}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 + EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.jar --content=META-INF/singleton-deployment.xml=singleton-deployment.xml deployment-overlay redeploy-affected --name=singleton-deployment @@ -181,7 +181,7 @@ For convenience, the management CLI scripts to add the deployment overlay, `sing ## Undeploy the Archives -1. Ensure all ${product.name} servers are started. +1. Ensure all JBoss EAP servers are started. 2. Navigate to the root directory of this quickstart in the command prompt. 3. Use the following commands to undeploy the artifacts: diff --git a/ha-singleton-deployment/pom.xml b/ha-singleton-deployment/pom.xml index fc9ff268a6..d948755010 100644 --- a/ha-singleton-deployment/pom.xml +++ b/ha-singleton-deployment/pom.xml @@ -27,7 +27,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/ha-singleton-service/README.html b/ha-singleton-service/README.html new file mode 100644 index 0000000000..5368943743 --- /dev/null +++ b/ha-singleton-service/README.html @@ -0,0 +1,384 @@ + + + ha-singleton-service: Deploying Cluster-wide Singleton MSC Services + + + +

ha-singleton-service: Deploying Cluster-wide Singleton MSC Services

+

Author: Radoslav Husar
+Level: Advanced
+Technologies: MSC, Singleton Service, Clustering
+Summary: The ha-singleton-service quickstart demonstrates how to deploy a cluster-wide singleton MSC service.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The ha-singleton-services quickstart demonstrates two patterns, or ways, to deploy a cluster-wide singleton MSC service.

+
    +
  1. The first example, located in the primary-only/ directory of the quickstart, demonstrates a singleton service and a querying service deployed on all nodes that regularly queries for the value provided by the singleton service.
    2. +
  2. The second example, located in the with-backups/ directory of the quickstart, demonstrates a singleton service that is installed with a backup service. The backup services are running on all nodes that were not elected to be running the singleton service itself.
    3. +
+

Singleton service's getValue() always returns the value of the primary node unless a backup service is installed. If no backup service is installed, a default backup service is used whose getValue() returns the service value of the primary node. Should a backup service be installed then the getValue() is delegated to the primary or backup service depending on the state of the local node.

+

Be sure to inspect the activate() method of the ServiceActivator class for each example. Although the default election policy is used to build the singleton services for each of these examples, scripts and instructions are provided later in this document to demonstrate how to configure other election policies.

+

These examples are built and packaged as JAR archives.

+

For more information about clustered singleton services, see HA Singleton Service in the Development Guide for JBoss EAP.

+

System Requirements

+

The deployments this project produces are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

Everything needed to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure the environment is configured correctly for testing the quickstarts.

+

Use of EAP7_HOME_1 and EAP7_HOME_2

+

This quickstart requires that you clone your EAP7_HOME installation directory and run two servers. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

In the following instructions, replace EAP7_HOME_1 with the path to your first JBoss EAP server and replace EAP7_HOME_2 with the path to your second cloned JBoss EAP server.

+

Clone the JBoss EAP Directory

+

While you can run this example starting only one instance of the server, if you want to see the singleton behavior, you must start at least two instances of the server. Copy the entire JBoss EAP directory to a new location to use for the second cluster member.

+

Start the Servers with the HA Profile

+

Note: You must start the server using the HA profile or the singleton service will not start correctly.

+

Start the two JBoss EAP servers with the HA profile, passing a unique node ID. These logical node names are used in the log to identify which node is elected. If you are running the servers on the same host, you must also pass a socket binding port offset on the command line to start the second server. To start the servers, type the following commands.

+

For Linux:

+
Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1
+Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100
+
+

For Windows:

+
Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node1
+Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100
+
+

This example is not limited to two servers. Additional servers can be started by specifying a unique node name and port offset for each one.

+

Run the primary-only Example

+

This example demonstrates a singleton service and a querying service that regularly queries for the value that the singleton service provides.

+

Build and Deploy primary-only to Server 1

+
    +
  1. Start the JBoss EAP servers as described in the above section.
    2. +
  2. Open a command prompt and navigate to the primary-only/ directory located in the root directory of this quickstart.
    3. +
  3. Use the following command to clean up any previously built artifacts, and to build and deploy the JAR archive. +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    Investigate the primary-only Console Output for Server 1. Verify that the target/ha-singleton-service-primary-only.jar archive is deployed to node1, which is the first server started without port offset, by checking the server log.

    +
    INFO  [org.jboss.as.server.deployment] (MSC service thread 1-7) WFLYSRV0027: Starting deployment of "ha-singleton-service-primary-only.jar" (runtime-name: "ha-singleton-service-primary-only.jar")
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.ServiceActivator] (MSC service thread 1-5) Singleton and querying services activated.
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (MSC service thread 1-3) Querying service is starting.
+...
+INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.SingletonService] (MSC service thread 1-7) Singleton service is starting on node 'node1'.
+...
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-4-thread-1) Singleton service is running on node 'node1'.
+
    +
    5. +
+

NOTE: You might see the following warnings in the server log after the applications are deployed. These warnings can be ignored in a development environment.

+
WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+WARN  [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+
+

Deploy the primary-only Archive to Server 2

+
    +
  1. +

    Use the following command to deploy the same archive to the second server. Because the default socket binding port for deployment is 9990 and the second server ports are offset by 100, you must pass the sum, 10090, for the socket binding port as the argument to the deploy Maven goal.

    +
    mvn wildfly:deploy -Dwildfly.port=10090
+
    +
    2. +
  2. +

    Investigate the primary-only console output for both servers. Verify that the target/ha-singleton-service-primary-only.jar archive is deployed to node2 by checking the server log.

    +
    INFO  [org.jboss.as.repository] (management-handler-thread - 4) WFLYDR0001: Content added at location /Users/rhusar/wildfly/build/target/y/standalone/data/content/18/6efcc6c07b471f641cfcc97f9120505726e6bd/content
+INFO  [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ha-singleton-service-primary-only.jar" (runtime-name: "ha-singleton-service-primary-only.jar")
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.ServiceActivator] (MSC service thread 1-6) Singleton and querying services activated.
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (MSC service thread 1-5) Querying service is starting.
+...
+INFO  [org.jboss.as.server] (management-handler-thread - 4) WFLYSRV0010: Deployed "ha-singleton-service-primary-only.jar" (runtime-name : "ha-singleton-service-primary-only.jar")
+...
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-4-thread-1) Singleton service is running on node 'node1'.
+
    +
    3. +
  3. +

    Inspect the server log of the first node. Since the cluster membership has changed, the election policy determines which node will run the singleton.

    +
    INFO  [org.infinispan.CLUSTER] (remote-thread--p7-t1) ISPN000336: Finished cluster-wide rebalance for cache default, topology id = 5
+INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node1 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service
+
    +
    4. +
  4. +

    Verify that the querying service is running on all nodes and that all are querying the same singleton service instance by confirming that the same node name is printed in the log. Both nodes will output the following message every 5 seconds:

    +
    INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-4-thread-1) Singleton service is running on node 'node1'.
+
    +
    5. +
+

Test Singleton Service Failover for the primary-only Example

+
    +
  1. +

    To verify failover of the singleton service, shut down the server operating as the singleton master by using the Ctrl + C key combination in the command prompt. The following messages confirm that the node is shut down.

    +
    INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-4-thread-1) Singleton service is running on node 'node1'.
+INFO  [org.jboss.as.server] (Thread-2) WFLYSRV0220: Server shutdown has been requested via an OS signal
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.SingletonService] (MSC service thread 1-3) Singleton service is stopping on node 'node1'.
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (MSC service thread 1-6) Querying service is stopping.
+...
+INFO  [org.jboss.as] (MSC service thread 1-6) WFLYSRV0050: JBoss EAP 7.1.0.Beta1 (WildFly Core 3.0.0.Beta26-redhat-1) stopped in 66ms
+
    +

    Note that during shutdown of the server an exception relating to clean shutdown of the Infinispan component might appear in the log, for instance:

    +
    ERROR [org.infinispan.remoting.transport.jgroups.CommandAwareRpcDispatcher] (thread-19) ISPN000065: Exception while marshalling object: CacheNotFoundResponse: org.infinispan.IllegalLifecycleStateException: Cache marshaller has been stopped
+
    +

    The issue can be safely ignored for now and will be fixed in future versions of the application server.

    +
    2. +
  2. +

    Now observe the log messages on the second server. The second node is now elected as the singleton master.

    +
    INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service
+INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.SingletonService] (MSC service thread 1-8) Singleton service is starting on node 'node2'.
+
    +
    3. +
+

Undeploy the primary-only Example

+
    +
  1. Start the JBoss EAP servers as described in the above section.
    2. +
  2. Open a command prompt and navigate to the primary-only/ directory located in the root directory of this quickstart.
    3. +
  3. Use the following command to undeploy the JAR archive from Server 1. +
    mvn wildfly:undeploy
+
    +
    4. +
  4. +

    Use the following command to undeploy the JAR archive from Server 2.

    +
    mvn wildfly:undeploy -Dwildfly.port=10090
+
    +
    5. +
+

Run the with-backups Example

+

Build and Deploy with-backups to Server 1

+

This example demonstrates a singleton service that is installed with a backup service. The backup service is running on all nodes that are not elected to be running the singleton service.

+
    +
  1. Start the JBoss EAP servers as described in the above section.
    2. +
  2. Open a command prompt and navigate to the with-backups/ directory located in the root directory of this quickstart.
    3. +
  3. Use the following command to clean up any previously built artifacts, and build and deploy the JAR archive. +
    mvn clean install wildfly:deploy
+
    +
    4. +
+

Deploy the with-backups Archive to Server 2

+

Use the following command to deploy the same archive to the second server. Because the default socket binding port for deployment is 9990 and the second server ports are offset by 100, you must pass the sum, 10090, for the socket binding port as the argument to the deploy Maven goal.

+
mvn wildfly:deploy -Dwildfly.port=10090
+
+

Investigate the with-backups Console Output for Both Servers

+

Verify that the target/ha-singleton-service-with-backups.jar archive is deployed to node1, which is the first server started without port offset, by checking the server log to see that the primary service is running.

+
INFO  [org.jboss.as.quickstarts.ha.singleton.service.backups.SingletonService] (pool-18-thread-1) Primary singleton service is running on node 'node1'.
+
+

All other nodes log that the backup singleton service is running.

+
INFO  [org.jboss.as.quickstarts.ha.singleton.service.backups.SingletonService] (pool-20-thread-1) Backup singleton service is running on node 'node2'.
+
+

Undeploy the with-backups Example

+
    +
  1. Start the JBoss EAP servers as described in the above section.
    2. +
  2. Open a command prompt and navigate to the with-backups/ directory located in the root directory of this quickstart.
    3. +
  3. Use the following command to undeploy the JAR archive from Server 1. +
    mvn wildfly:undeploy
+
    +
    4. +
  4. +

    Use the following command to undeploy the JAR archive from Server 2.

    +
    mvn wildfly:undeploy -Dwildfly.port=10090
+
    +
    5. +
+

Configuring Election Policies

+

As mentioned previously, the activate() method in the ServiceActivator class for each example in this quickstart uses the default election policy to build the singleton services. Once you have successfully deployed and verified these examples, you might want to test different election policy configurations to see how they work.

+

Election policies are configured using JBoss EAP management CLI commands. Scripts are provided to configure a simple name preference election policy and a random election policy. A script is also provided to configure a quorum for the singleton policy.

+

Configure a Name Preference Election Policy

+

This example configures the default election policy to be based on logical names.

+
    +
  1. If you have tested other election policies that configured the singleton subsystem, see Restoring the Default Singleton Subsystem Configuration for instructions to restore the singleton election policy to the default configuration.
    2. +
  2. Start the two servers with the HA profile as described above.
    3. +
  3. Review the contents of the name-preference-election-policy-add.cli file located in the root of this quickstart directory. This script configures the default election policy to choose nodes in a preferred order of node3, node2, and node1 using this command. +
    /subsystem=singleton/singleton-policy=default/election-policy=simple:write-attribute(name=name-preferences,value=[node3,node2,node1])
+
    +
    4. +
  4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace EAP7_HOME_1 with the path to the target Server 1. +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=name-preference-election-policy-add.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=name-preference-election-policy-add.cli
+
    +

    You should see the following result when you run the script.

    +
    {
+    "outcome" => "success",
+    "response-headers" => {
+        "operation-requires-reload" => true,
+        "process-state" => "reload-required"
+    }
+}
+
    +

    Note that the name-preference-election-policy-add.cli script executes the reload command, so a reload is not required.

    +
    5. +
  5. +

    Stop the server and review the changes made to the standalone-ha.xml server configuration file by the management CLI commands. The singleton subsystem now contains a name-preferences element under the simple-election-policy that specifies the preferences node3 node2 node1.

    +
    <subsystem xmlns="urn:jboss:domain:singleton:1.0">
+    <singleton-policies default="default">
+        <singleton-policy name="default" cache-container="server">
+            <simple-election-policy>
+                <name-preferences>node3 node2 node1</name-preferences>
+            </simple-election-policy>
+        </singleton-policy>
+    </singleton-policies>
+</subsystem>
+
    +
    6. +
  6. +

    Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding --controller=localhost:10090.

    +
    For Linux: EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli
+For Windows: EAP7_HOME_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli
+
    +
    7. +
  7. +

    Be sure both servers are started, deploy one of the examples to both servers, and verify that the election policy is now in effect. The server running the election policy should now log the following message.

    +
    INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service
+
    +

    The other nodes should log the following message.

    +
    INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-7-thread-1) Singleton service is running on node 'node2'.
+
    +
    8. +
+

Configure a Random Election Policy

+

This example configures an election policy that elects a random cluster member when the cluster membership changes.

+
    +
  1. If you have tested other election policies that configured the singleton subsystem, see Restoring the Default Singleton Subsystem Configuration for instructions to restore the singleton election policy to the default configuration.
    2. +
  2. Start the two servers with the HA profile as described above.
    3. +
  3. Review the contents of the random-election-policy-add.cli file located in the root of this quickstart directory. This script removes the default simple election policy and configures the default election policy to elect a random cluster member using these commands. +
    /subsystem=singleton/singleton-policy=default/election-policy=simple:remove(){allow-resource-service-restart=true}
+/subsystem=singleton/singleton-policy=default/election-policy=random:add()
+
    +
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace EAP7_HOME_1 with the path to the target Server 1.

    +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=random-election-policy-add.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=random-election-policy-add.cli
+
    +

    You should see the following result when you run the script.

    +
    The batch executed successfully
+process-state: reload-required
+
    +

    Note that the random-election-policy-add.cli script executes the reload command, so a reload is not required.

    +
    5. +
  5. +

    Stop the server and review the changes made to the standalone-ha.xml server configuration file by the management CLI commands. The singleton subsystem now contains a random-election-policy element under the singleton-policy that specifies the preferences node3 node2 node1.

    +
    <subsystem xmlns="urn:jboss:domain:singleton:1.0">
+    <singleton-policies default="default">
+        <singleton-policy name="default" cache-container="server">
+            <random-election-policy/>
+        </singleton-policy>
+    </singleton-policies>
+</subsystem>
+
    +
    6. +
  6. +

    Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding --controller=localhost:10090.

    +
    For Linux: EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=random-election-policy-add.cli
+For Windows: EAP7_HOME_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=random-election-policy-add.cli
+
    +
    7. +
  7. +

    Be sure both servers are started, deploy one of the examples to both servers, and verify that the election policy is now in effect.

    +
    8. +
+

Configure a Quorum for the Singleton Policy

+

A quorum specifies the minimum number of cluster members that must be present for the election to even begin. This mechanism is used to mitigate a split brain problem by sacrificing the availability of the singleton service. If there are less members than the specified quorum, no election is performed and the singleton service is not run on any node.

+
    +
  1. Quorum can be configured for any singleton policy. Optionally, if you have reconfigured the singleton subsystem, see Restoring the Default Singleton Subsystem Configuration for instructions to restore the singleton election policy to the default configuration.
    2. +
  2. Start the two servers with the HA profile as described above.
    3. +
  3. Review the contents of the quorum-add.cli file located in the root of this quickstart directory. This script specifies the minimum number of cluster members required for the singleton policy using this command. +
    /subsystem=singleton/singleton-policy=default:write-attribute(name=quorum,value=2)
+
    +
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace EAP7_HOME_1 with the path to the target Server 1.

    +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=quorum-add.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=quorum-add.cli
+
    +

    You should see the following result when you run the script.

    +
    {
+    "outcome" => "success",
+    "response-headers" => {
+        "operation-requires-reload" => true,
+        "process-state" => "reload-required"
+    }
+}
+
    +

    Note that the quorum-add.cli script executes the reload command, so a reload is not required.

    +
    5. +
  5. +

    Review the changes made to the standalone-ha.xml server configuration file by the management CLI commands. The singleton subsystem now contains a quorum attribute for the singleton-policy element that specifies the minimum number.

    +
    <subsystem xmlns="urn:jboss:domain:singleton:1.0">
+    <singleton-policies default="default">
+        <singleton-policy name="default" cache-container="server" quorum="2">
+            <simple-election-policy/>
+        </singleton-policy>
+    </singleton-policies>
+</subsystem>
+
    +
    6. +
  6. +

    Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding --controller=localhost:10090.

    +
      For Linux: EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=quorum-add.cli
+  For Windows: EAP7_HOME_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=quorum-add.cli
+
    +
    7. +
  7. +

    Be sure both servers are started, deploy one of the examples to both servers. While both servers are running, observe the server logs. The server running the election policy should now log the following message.

    +
    INFO  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0007: Just reached required quorum of 2 for org.jboss.as.quickstarts.ha.singleton.service.primary-only service. If this cluster loses another member, no node will be chosen to provide this service.
+
    +
    8. +
  8. +

    Shut down one of the servers by using the Ctrl + C key combination in the command prompt to verify that no singleton service will be running after the quorum is not reached.

    +
    WARN  [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0006: Failed to reach quorum of 2 for org.jboss.as.quickstarts.ha.singleton.service.primary-only service. No singleton master will be elected.
+INFO  [org.wildfly.clustering.server] (thread-20) WFLYCLSV0002: This node will no longer operate as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service
+INFO  [org.jboss.as.quickstarts.ha.singleton.service.primary.SingletonService] (MSC service thread 1-3) Singleton service is stopping on node 'node2'.
+INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-2) ISPN000094: Received new cluster view for channel server: [node2|4] (1) [node2]
+...
+WARN  [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-4-thread-1) Failed to query singleton service.
+
    +
    9. +
  9. +

    A quorum-remove.cli script is provided in the root directory of this quickstart that removes the quorum from the singleton subsystem.

    +
    10. +
+

Troubleshooting Runtime Problems

+

If the singleton is running on multiple nodes, check for the following issues.

+
    +
  • +

    The most common cause of this problem is starting the servers with the standalone.xml or standalone-full.xml profile instead of with the standalone-ha.xml or standalone-full-ha.xml profile. Make sure to start the server with an HA profile using -c standalone-ha.xml.

    +
    • +
  • +

    Another common cause is because the server instances did not discover each other and each server is operating as a singleton cluster. Ensure that multicast is enabled or change the jgroups subsystem configuration to use a different discovery mechanism. Confirm the following message in the server log to ensure that the discovery was successful.

    +
    INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2]
+
    +
    • +
+

Undeploy the Deployments

+

If you have not yet done so, you can undeploy all of the deployed artifacts by following these steps.

+
    +
  1. Start the two servers with the HA profile as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Use the following commands to undeploy all of the artifacts. +
    mvn wildfly:undeploy
+mvn wildfly:undeploy -Dwildfly.port=10090
+
    +
    4. +
+

Restoring the Default Singleton Subsystem Configuration

+

Some of these examples require that you modify the election policies for the singleton subsystem by running management CLI scripts. After you have completed testing each configuration, it is important to restore the singleton subsystem to its default configuration before you run any other examples.

+
    +
  1. Start both servers with the HA profile as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Restore your default server configurations by running these commands. +
      +
    • +

      For Linux:

      +
      EAP7_HOME_1/bin/jboss-cli.sh --connect --file=restore-singleton-subsystem.cli
+EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli
+
      +
      • +
    • +

      For Windows:

      +
      EAP7_HOME_1\bin\jboss-cli.bat --connect --file=restore-singleton-subsystem.cli
+EAP7_HOME_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli
+
      +
      • +
    +
    4. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/ha-singleton-service/README.md b/ha-singleton-service/README.md index 82be5bf60b..7aabdb1633 100644 --- a/ha-singleton-service/README.md +++ b/ha-singleton-service/README.md @@ -4,8 +4,8 @@ Author: Radoslav Husar Level: Advanced Technologies: MSC, Singleton Service, Clustering Summary: The `ha-singleton-service` quickstart demonstrates how to deploy a cluster-wide singleton MSC service. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? @@ -27,37 +27,37 @@ For more information about clustered singleton services, see _HA Singleton Servi ## System Requirements -The deployments this project produces are designed to be run on ${product.name.full} ${product.version} or later. +The deployments this project produces are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -Everything needed to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure the environment is configured correctly for testing the quickstarts. +Everything needed to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure the environment is configured correctly for testing the quickstarts. -## Use of ${jboss.home.name}_1 and ${jboss.home.name}_2 +## Use of EAP7_HOME_1 and EAP7_HOME_2 -This quickstart requires that you clone your `${jboss.home.name}` installation directory and run two servers. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +This quickstart requires that you clone your `EAP7_HOME` installation directory and run two servers. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). -In the following instructions, replace `${jboss.home.name}_1` with the path to your first ${product.name} server and replace `${jboss.home.name}_2` with the path to your second cloned ${product.name} server. +In the following instructions, replace `EAP7_HOME_1` with the path to your first JBoss EAP server and replace `EAP7_HOME_2` with the path to your second cloned JBoss EAP server. -## Clone the ${product.name} Directory +## Clone the JBoss EAP Directory -While you can run this example starting only one instance of the server, if you want to see the singleton behavior, you must start at least two instances of the server. Copy the entire ${product.name} directory to a new location to use for the second cluster member. +While you can run this example starting only one instance of the server, if you want to see the singleton behavior, you must start at least two instances of the server. Copy the entire JBoss EAP directory to a new location to use for the second cluster member. ## Start the Servers with the HA Profile _Note: You must start the server using the HA profile or the singleton service will not start correctly._ -Start the two ${product.name} servers with the HA profile, passing a unique node ID. These logical node names are used in the log to identify which node is elected. If you are running the servers on the same host, you must also pass a socket binding port offset on the command line to start the second server. +Start the two JBoss EAP servers with the HA profile, passing a unique node ID. These logical node names are used in the log to identify which node is elected. If you are running the servers on the same host, you must also pass a socket binding port offset on the command line to start the second server. To start the servers, type the following commands. For Linux: - Server 1: ${jboss.home.name}_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 - Server 2: ${jboss.home.name}_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 + Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 For Windows: - Server 1: ${jboss.home.name}_1\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node1 - Server 2: ${jboss.home.name}_2\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node1 + Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 This example is not limited to two servers. Additional servers can be started by specifying a unique node name and port offset for each one. @@ -67,7 +67,7 @@ This example demonstrates a singleton service and a querying service that regula ### Build and Deploy primary-only to Server 1 -1. Start the ${product.name} servers as described in the above section. +1. Start the JBoss EAP servers as described in the above section. 2. Open a command prompt and navigate to the `primary-only/` directory located in the root directory of this quickstart. 3. Use the following command to clean up any previously built artifacts, and to build and deploy the JAR archive. @@ -140,7 +140,7 @@ _NOTE:_ You might see the following warnings in the server log after the applica ### Undeploy the primary-only Example -1. Start the ${product.name} servers as described in the above section. +1. Start the JBoss EAP servers as described in the above section. 2. Open a command prompt and navigate to the `primary-only/` directory located in the root directory of this quickstart. 3. Use the following command to undeploy the JAR archive from Server 1. @@ -155,7 +155,7 @@ _NOTE:_ You might see the following warnings in the server log after the applica ### Build and Deploy with-backups to Server 1 This example demonstrates a singleton service that is installed with a backup service. The backup service is running on all nodes that are _not_ elected to be running the singleton service. -1. Start the ${product.name} servers as described in the above section. +1. Start the JBoss EAP servers as described in the above section. 2. Open a command prompt and navigate to the `with-backups/` directory located in the root directory of this quickstart. 3. Use the following command to clean up any previously built artifacts, and build and deploy the JAR archive. @@ -180,7 +180,7 @@ All other nodes log that the backup singleton service is running. ### Undeploy the with-backups Example -1. Start the ${product.name} servers as described in the above section. +1. Start the JBoss EAP servers as described in the above section. 2. Open a command prompt and navigate to the `with-backups/` directory located in the root directory of this quickstart. 3. Use the following command to undeploy the JAR archive from Server 1. @@ -195,7 +195,7 @@ All other nodes log that the backup singleton service is running. As mentioned previously, the `activate()` method in the `ServiceActivator` class for each example in this quickstart uses the default election policy to build the singleton services. Once you have successfully deployed and verified these examples, you might want to test different election policy configurations to see how they work. -Election policies are configured using ${product.name} management CLI commands. Scripts are provided to configure a simple [name preference election policy](#configure-a-name-preference-election-policy) and a [random election policy](#configure-a-random-election-policy). A script is also provided to configure a [quorum for the singleton policy](#configure-a-singleton-policy-that-defines-a-quorum). +Election policies are configured using JBoss EAP management CLI commands. Scripts are provided to configure a simple [name preference election policy](#configure-a-name-preference-election-policy) and a [random election policy](#configure-a-random-election-policy). A script is also provided to configure a [quorum for the singleton policy](#configure-a-singleton-policy-that-defines-a-quorum). ### Configure a Name Preference Election Policy @@ -206,10 +206,10 @@ This example configures the default election policy to be based on logical names 3. Review the contents of the `name-preference-election-policy-add.cli` file located in the root of this quickstart directory. This script configures the default election policy to choose nodes in a preferred order of `node3`, `node2`, and `node1` using this command. /subsystem=singleton/singleton-policy=default/election-policy=simple:write-attribute(name=name-preferences,value=[node3,node2,node1]) -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace ${jboss.home.name}_1 with the path to the target Server 1. +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace EAP7_HOME_1 with the path to the target Server 1. - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=name-preference-election-policy-add.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=name-preference-election-policy-add.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=name-preference-election-policy-add.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=name-preference-election-policy-add.cli You should see the following result when you run the script. @@ -237,8 +237,8 @@ This example configures the default election policy to be based on logical names 6. Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. - For Linux: ${jboss.home.name}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli - For Windows: ${jboss.home.name}_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli + For Linux: EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli + For Windows: EAP7_HOME_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli 7. Be sure both servers are started, deploy one of the examples to both servers, and verify that the election policy is now in effect. The server running the election policy should now log the following message. @@ -260,10 +260,10 @@ This example configures an election policy that elects a random cluster member w /subsystem=singleton/singleton-policy=default/election-policy=simple:remove(){allow-resource-service-restart=true} /subsystem=singleton/singleton-policy=default/election-policy=random:add() -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace ${jboss.home.name}_1 with the path to the target Server 1. +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace EAP7_HOME_1 with the path to the target Server 1. - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=random-election-policy-add.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=random-election-policy-add.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=random-election-policy-add.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=random-election-policy-add.cli You should see the following result when you run the script. @@ -284,8 +284,8 @@ This example configures an election policy that elects a random cluster member w 6. Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. - For Linux: ${jboss.home.name}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=random-election-policy-add.cli - For Windows: ${jboss.home.name}_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=random-election-policy-add.cli + For Linux: EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=random-election-policy-add.cli + For Windows: EAP7_HOME_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=random-election-policy-add.cli 7. Be sure both servers are started, deploy one of the examples to both servers, and verify that the election policy is now in effect. @@ -299,10 +299,10 @@ A quorum specifies the minimum number of cluster members that must be present fo /subsystem=singleton/singleton-policy=default:write-attribute(name=quorum,value=2) -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace ${jboss.home.name}_1 with the path to the target Server 1. +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace EAP7_HOME_1 with the path to the target Server 1. - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=quorum-add.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=quorum-add.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=quorum-add.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=quorum-add.cli You should see the following result when you run the script. @@ -328,8 +328,8 @@ A quorum specifies the minimum number of cluster members that must be present fo 6. Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. - For Linux: ${jboss.home.name}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=quorum-add.cli - For Windows: ${jboss.home.name}_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=quorum-add.cli + For Linux: EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=quorum-add.cli + For Windows: EAP7_HOME_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=quorum-add.cli 7. Be sure both servers are started, deploy one of the examples to both servers. While both servers are running, observe the server logs. The server running the election policy should now log the following message. @@ -377,13 +377,13 @@ Some of these examples require that you modify the election policies for the `si * For Linux: - ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=restore-singleton-subsystem.cli - ${jboss.home.name}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli + EAP7_HOME_1/bin/jboss-cli.sh --connect --file=restore-singleton-subsystem.cli + EAP7_HOME_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli * For Windows: - ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=restore-singleton-subsystem.cli - ${jboss.home.name}_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli + EAP7_HOME_1\bin\jboss-cli.bat --connect --file=restore-singleton-subsystem.cli + EAP7_HOME_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli ## Debug the Application diff --git a/ha-singleton-service/pom.xml b/ha-singleton-service/pom.xml index ae44591813..0b671393d2 100644 --- a/ha-singleton-service/pom.xml +++ b/ha-singleton-service/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/ha-singleton-service/primary-only/pom.xml b/ha-singleton-service/primary-only/pom.xml index b65814cf45..4bfb21050d 100644 --- a/ha-singleton-service/primary-only/pom.xml +++ b/ha-singleton-service/primary-only/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts ha-singleton-service - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/ha-singleton-service/with-backups/pom.xml b/ha-singleton-service/with-backups/pom.xml index ef73fad49d..8a222f980c 100644 --- a/ha-singleton-service/with-backups/pom.xml +++ b/ha-singleton-service/with-backups/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts ha-singleton-service - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/helloworld-html5/README.html b/helloworld-html5/README.html new file mode 100644 index 0000000000..3a36602b2f --- /dev/null +++ b/helloworld-html5/README.html @@ -0,0 +1,129 @@ + + + helloworld-html5: HTML5 and REST Hello World Example + + + +

helloworld-html5: HTML5 and REST Hello World Example

+

Author: Jay Balunas, Burr Sutter, Douglas Campos, Bruno Olivera
+Level: Beginner
+Technologies: CDI, JAX-RS, HTML5
+Summary: The helloworld-html5 quickstart demonstrates the use of CDI 1.2 and JAX-RS 2.0 using the HTML5 architecture and RESTful services on the backend.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld-html5 quickstart demonstrates the use of CDI 1.2 and JAX-RS 2.0 in Red Hat JBoss Enterprise Application Platform 7.1 or later using the HTML5 + REST architecture.

+

The application is basically a smart, HTML5+CSS3+JavaScript front-end using RESTful services on the backend.

+
    +
  • HelloWorld.java - establishes the RESTful endpoints using JAX-RS
    • +
  • Web.xml - maps RESTful endpoints to /hello
    • +
  • index.html - is a jQuery augmented plain old HTML5 web page
    • +
+

The example can be deployed using Maven from the command line or from Eclipse using JBoss Tools.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ is required.

+

With the prerequisites out of the way, you are ready to build and deploy.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+

NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See Build and Deploy the Quickstarts for complete instructions and additional options.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy both the client and service applications: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-html5.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/helloworld-html5/.

+

You can also test the REST endpoint by sending an HTTP POST request to the URLs below. Feel free to replace YOUR_NAME with a name of your choosing.

+
    +
  • +

    The XML content can be tested by sending an HTTP POST to the following URL: http://localhost:8080/helloworld-html5/hello/xml/YOUR_NAME

    +

    To issue the POST command using cURL, type the following command in terminal:

    +
    curl -i -X POST http://localhost:8080/helloworld-html5/hello/xml/YOUR_NAME
+
    +

    You will see the following response:

    +
    HTTP/1.1 200 OK
+Connection: keep-alive
+X-Powered-By: Undertow/1
+Server: JBoss-EAP/7
+Content-Type: application/xml
+Content-Length: 44
+Date: Tue, 13 Oct 2015 18:40:04 GMT
+
+<xml><result>Hello YOUR_NAME!</result></xml>
+
    +
    • +
  • +

    The JSON content can be tested by sending an HTTP POST to the following URL: http://localhost:8080/helloworld-html5/hello/json/YOUR_NAME

    +

    To issue the POST command using cURL, type the following command in terminal:

    +
    curl -i -X POST http://localhost:8080/helloworld-html5/hello/json/YOUR_NAME
+
    +

    You will see the following response:

    +
    HTTP/1.1 200 OK
+Connection: keep-alive
+X-Powered-By: Undertow/1
+Server: JBoss-EAP/7
+Content-Type: application/json
+Content-Length: 29
+Date: Tue, 13 Oct 2015 06:32:20 GMT
+
+{"result":"Hello YOUR_NAME!"}
+
    +
    • +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type fhe following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + + \ No newline at end of file diff --git a/helloworld-html5/README.md b/helloworld-html5/README.md index 21f3571bbf..72d85bca99 100644 --- a/helloworld-html5/README.md +++ b/helloworld-html5/README.md @@ -4,12 +4,12 @@ Author: Jay Balunas, Burr Sutter, Douglas Campos, Bruno Olivera Level: Beginner Technologies: CDI, JAX-RS, HTML5 Summary: The `helloworld-html5` quickstart demonstrates the use of *CDI 1.2* and *JAX-RS 2.0* using the HTML5 architecture and RESTful services on the backend. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld-html5` quickstart demonstrates the use of *CDI 1.2* and *JAX-RS 2.0* in ${product.name.full} ${product.version} or later using the HTML5 + REST architecture. +The `helloworld-html5` quickstart demonstrates the use of *CDI 1.2* and *JAX-RS 2.0* in Red Hat JBoss Enterprise Application Platform 7.1 or later using the HTML5 + REST architecture. The application is basically a smart, HTML5+CSS3+JavaScript front-end using RESTful services on the backend. @@ -21,9 +21,9 @@ The example can be deployed using Maven from the command line or from Eclipse us ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ is required. @@ -32,37 +32,37 @@ With the prerequisites out of the way, you are ready to build and deploy. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart _NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._ -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy both the client and service applications: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/helloworld-html5.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . You can also test the REST endpoint by sending an HTTP *POST* request to the URLs below. Feel free to replace `YOUR_NAME` with a name of your choosing. -* The *XML* content can be tested by sending an HTTP *POST* to the following URL: +* The *XML* content can be tested by sending an HTTP *POST* to the following URL: To issue the *POST* command using cURL, type the following command in terminal: - curl -i -X POST http://localhost:8080/${project.artifactId}/hello/xml/YOUR_NAME + curl -i -X POST http://localhost:8080/helloworld-html5/hello/xml/YOUR_NAME You will see the following response: @@ -76,11 +76,11 @@ You can also test the REST endpoint by sending an HTTP *POST* request to the URL Hello YOUR_NAME! -* The *JSON* content can be tested by sending an HTTP *POST* to the following URL: +* The *JSON* content can be tested by sending an HTTP *POST* to the following URL: To issue the *POST* command using cURL, type the following command in terminal: - curl -i -X POST http://localhost:8080/${project.artifactId}/hello/json/YOUR_NAME + curl -i -X POST http://localhost:8080/helloworld-html5/hello/json/YOUR_NAME You will see the following response: @@ -97,7 +97,7 @@ You can also test the REST endpoint by sending an HTTP *POST* request to the URL ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -116,17 +116,17 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the server for you, type fhe following command: +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type fhe following command: mvn clean verify -Parq-managed ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/helloworld-html5/functional-tests/pom.xml b/helloworld-html5/functional-tests/pom.xml index ce1a0f42ee..394c0c92c4 100644 --- a/helloworld-html5/functional-tests/pom.xml +++ b/helloworld-html5/functional-tests/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml helloworld-html5-test-webdriver diff --git a/helloworld-html5/pom.xml b/helloworld-html5/pom.xml index 0c77f0c1b4..984e021565 100644 --- a/helloworld-html5/pom.xml +++ b/helloworld-html5/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-html5 diff --git a/helloworld-jms/README.html b/helloworld-jms/README.html new file mode 100644 index 0000000000..1d28e7581a --- /dev/null +++ b/helloworld-jms/README.html @@ -0,0 +1,209 @@ + + + helloworld-jms: Helloworld JMS Example + + + +

helloworld-jms: Helloworld JMS Example

+

Author: Weston Price
+Level: Intermediate
+Technologies: JMS
+Summary: The helloworld-jms quickstart demonstrates the use of external JMS clients with JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld-jms quickstart demonstrates the use of external JMS clients with Red Hat JBoss Enterprise Application Platform.

+

It contains the following:

+
    +
  1. +

    A message producer that sends messages to a JMS destination deployed to a JBoss EAP server.

    +
    2. +
  2. +

    A message consumer that receives message from a JMS destination deployed to a JBoss EAP server.

    +
    3. +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add an Application User

+

This quickstart uses secured management interfaces and requires that you create the following application user to access the running application.

+ + + + + + + +
UserName Realm Password Roles
quickstartUser ApplicationRealm quickstartPwd1! guest
+

To add the application user, open a command prompt and type the following command:

+
    For Linux:   EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+    For Windows: EAP7_HOME\bin\add-user.bat  -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+
+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Configure the Server

+

You configure the JMS test queue by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-jms.cli script provided in the root directory of this quickstart.

+
    +
  1. Before you begin, back up your server configuration file +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone-full.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows:  EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    3. +
  3. Review the configure-jms.cli file in the root of this quickstart directory. This script adds the test queue to the messaging subsystem in the server configuration file.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-jms.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-jms.cli
+
    +
    5. +
  5. You should see the following result when you run the script: +
    The batch executed successfully
+
    +
    6. +
  6. Stop the JBoss EAP server.
    7. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone-full.xml file and review the changes.

+

The following testQueue jms-queue was configured in the default server configuration of the messaging-activemq subsystem.

+
  <jms-queue name="testQueue" entries="queue/test java:jboss/exported/jms/queue/test"/>
+
+

Start the Server with the Full Profile

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the full profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    3. +
+

Build and Execute the Quickstart

+

To run the quickstart from the command line:

+
    +
  1. +

    Make sure you have started the JBoss EAP server. See the instructions in the previous section.

    +
    2. +
  2. +

    Open a command prompt and navigate to the root of the helloworld-jms quickstart directory:

    +
    cd PATH_TO_QUICKSTARTS/helloworld-jms
+
    +
    3. +
  3. +

    Type the following command to compile and execute the quickstart:

    +
    mvn clean compile exec:java
+
    +
    4. +
+

NOTE: If you execute this command multiple times, you may see the following warning and exception, followed by a stacktrace. This is caused by a bug in Artemis that has been fixed, but not yet released. For details, see https://issues.apache.org/jira/browse/ARTEMIS-158. You can ignore this warning.

+
WARN: AMQ212007: connector.create or connectorFactory.createConnector should never throw an exception, implementation is badly behaved, but we will deal with it anyway.
+java.lang.IllegalArgumentException: port out of range:-1
+
+

Investigate the Console Output

+

If the Maven command is successful, with the default configuration you will see output similar to this:

+
timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
+INFO: Attempting to acquire connection factory "jms/RemoteConnectionFactory"
+SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
+SLF4J: Defaulting to no-operation (NOP) logger implementation
+SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
+timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
+INFO: Found connection factory "jms/RemoteConnectionFactory" in JNDI
+timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
+INFO: Attempting to acquire destination "jms/queue/test"
+timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
+INFO: Found destination "jms/queue/test" in JNDI
+timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
+INFO: Sending 1 messages with content: Hello, World!
+timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
+INFO: Received message with content Hello, World!
+
+

Optional Properties

+

The example provides for a certain amount of customization for the mvn:exec plug-in using the system properties.

+
    +
  • +

    username

    +

    This username is used for both the JMS connection and the JNDI look-up. Instructions to set up the quickstart application user can be found here: Add an Application User.

    +

    Default: quickstartUser

    +
    • +
  • +

    password

    +

    This password is used for both the JMS connection and the JNDI look-up. Instructions to set up the quickstart application user can be found here: Add an Application User

    +

    Default: quickstartPwd1!

    +
    • +
  • +

    connection.factory

    +

    The name of the JMS ConnectionFactory you want to use.

    +

    Default: jms/RemoteConnectionFactory

    +
    • +
  • +

    destination

    +

    The name of the JMS Destination you want to use.

    +

    Default: jms/queue/test

    +
    • +
  • +

    message.count

    +

    The number of JMS messages you want to produce and consume.

    +

    Default: 1

    +
    • +
  • +

    message.content

    +

    The content of the JMS TextMessage.

    +

    Default: "Hello, World!"

    +
    • +
  • +

    java.naming.provider.url

    +

    This property allows configuration of the JNDI directory used to lookup the JMS destination. This is useful when the client resides on another host.

    +

    Default: "localhost"

    +
    • +
+

Remove the JMS Configuration

+

You can remove the JMS configuration by running the remove-jms.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Remove the JMS Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows:  EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-jms.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-jms.cli
+
    +
    3. +
  3. This script removes the test queue from the messaging subsystem in the server configuration. You should see the following result when you run the script: +
    The batch executed successfully
+
    +
    4. +
+

Remove the JMS Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone-full.xml file with the back-up copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+
    +
  1. Be sure to Add an Application User as described above.
    2. +
  2. Configure and start the JBoss EAP server in Red Hat JBoss Developer Studio: +
      +
    • Define a server runtime environment that uses the standalone-full.xml configuration file.
      • +
    • Start the server defined in the previous step.
      • +
    +
    3. +
  3. Outside of JBoss Developer Studio, configure the JMS test queue by running the JBoss CLI commands as described above under Configure the Server.
    4. +
  4. In JBoss Developer Studio, right-click on the helloworld-jms project and choose Run As --> Java Application. In the Select Java Application window, choose HellowWorldJMSClient - org.jboss.as.quickstarts.jms and click OK. The client output displays in the Console window. The output messages appear in the Console window.
    5. +
  5. Be sure to Remove the JMS Configuration when you have completed testing this quickstart.
    6. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/helloworld-jms/README.md b/helloworld-jms/README.md index f22a397651..50bcc402a1 100644 --- a/helloworld-jms/README.md +++ b/helloworld-jms/README.md @@ -3,31 +3,31 @@ Author: Weston Price Level: Intermediate Technologies: JMS -Summary: The `helloworld-jms` quickstart demonstrates the use of external JMS clients with ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `helloworld-jms` quickstart demonstrates the use of external JMS clients with JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld-jms` quickstart demonstrates the use of external JMS clients with ${product.name.full}. +The `helloworld-jms` quickstart demonstrates the use of external JMS clients with Red Hat JBoss Enterprise Application Platform. It contains the following: -1. A message producer that sends messages to a JMS destination deployed to a ${product.name} server. +1. A message producer that sends messages to a JMS destination deployed to a JBoss EAP server. -2. A message consumer that receives message from a JMS destination deployed to a ${product.name} server. +2. A message consumer that receives message from a JMS destination deployed to a JBoss EAP server. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add an Application User @@ -40,8 +40,8 @@ This quickstart uses secured management interfaces and requires that you create To add the application user, open a command prompt and type the following command: - For Linux: ${jboss.home.name}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' - For Windows: ${jboss.home.name}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' + For Linux: EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' + For Windows: EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: [Add an Application User](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user). @@ -52,28 +52,28 @@ For an example of how to use the add-user utility, see the instructions located You configure the JMS `test` queue by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-jms.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone-full.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone-full.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml 3. Review the `configure-jms.cli` file in the root of this quickstart directory. This script adds the `test` queue to the `messaging` subsystem in the server configuration file. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-jms.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-jms.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-jms.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-jms.cli 5. You should see the following result when you run the script: The batch executed successfully -6. Stop the ${product.name} server. +6. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone-full.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone-full.xml` file and review the changes. The following `testQueue` jms-queue was configured in the default server configuration of the `messaging-activemq` subsystem. @@ -82,18 +82,18 @@ The following `testQueue` jms-queue was configured in the default server configu ## Start the Server with the Full Profile -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the full profile: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml ## Build and Execute the Quickstart To run the quickstart from the command line: -1. Make sure you have started the ${product.name} server. See the instructions in the previous section. +1. Make sure you have started the JBoss EAP server. See the instructions in the previous section. 2. Open a command prompt and navigate to the root of the helloworld-jms quickstart directory: @@ -183,35 +183,35 @@ You can remove the JMS configuration by running the `remove-jms.cli` script pro ### Remove the JMS Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=remove-jms.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=remove-jms.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-jms.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-jms.cli 3. This script removes the `test` queue from the `messaging` subsystem in the server configuration. You should see the following result when you run the script: The batch executed successfully ### Remove the JMS Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. 1. Be sure to [Add an Application User](#add-an-application-user) as described above. -2. Configure and start the ${product.name} server in Red Hat JBoss Developer Studio: +2. Configure and start the JBoss EAP server in Red Hat JBoss Developer Studio: * Define a server runtime environment that uses the `standalone-full.xml` configuration file. * Start the server defined in the previous step. 3. Outside of JBoss Developer Studio, configure the JMS `test` queue by running the JBoss CLI commands as described above under [Configure the Server](#configure-the-server). -4. In JBoss Developer Studio, right-click on the `${project.artifactId}` project and choose `Run As` --> `Java Application`. In the `Select Java Application` window, choose `HellowWorldJMSClient - org.jboss.as.quickstarts.jms` and click `OK`. The client output displays in the `Console` window. +4. In JBoss Developer Studio, right-click on the `helloworld-jms` project and choose `Run As` --> `Java Application`. In the `Select Java Application` window, choose `HellowWorldJMSClient - org.jboss.as.quickstarts.jms` and click `OK`. The client output displays in the `Console` window. The output messages appear in the `Console` window. 5. Be sure to [Remove the JMS Configuration](#remove-the-jms-configuration) when you have completed testing this quickstart. diff --git a/helloworld-jms/pom.xml b/helloworld-jms/pom.xml index 3774311a32..f199077172 100644 --- a/helloworld-jms/pom.xml +++ b/helloworld-jms/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-jms diff --git a/helloworld-mbean/README.html b/helloworld-mbean/README.html new file mode 100644 index 0000000000..e0303a2d4e --- /dev/null +++ b/helloworld-mbean/README.html @@ -0,0 +1,124 @@ + + + helloworld-mbean: Helloworld Using MBean and CDI component + + + +

helloworld-mbean: Helloworld Using MBean and CDI component

+

Author: Lagarde Jeremie
+Level: Intermediate
+Technologies: CDI, JMX, MBean
+Summary: The helloworld-mbean quickstart demonstrates the use of CDI and MBean in JBoss EAP and includes JConsole instructions and Arquillian tests.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld-mbean quickstart demonstrates the use of CDI and MBean in Red Hat JBoss Enterprise Application Platform. The project also includes a set of Arquillian tests for MBeans.

+

The example is composed of the following MBeans:

+
    +
  • +

    AnnotatedComponentHelloWorld: This MBean is a managed bean with @MXBean annotation.

    +
    • +
  • +

    MXComponentHelloWorld: This MBean is a managed bean with MXBean interface.

    +
    • +
  • +

    MXPojoHelloWorld: This MBean is a pojo using MXBean interface and declared in the jboss-service.xml file.

    +
    • +
  • +

    SarMXPojoHelloWorld: This MBean is a pojo using MXBean interface and declared in jboss-service.xml in SAR packaging.

    +
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the JBoss EAP Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy helloworld-mbean-webapp/target/helloworld-mbean-webapp.war and helloworld-mbean-service/target/helloworld-mbean-service.sar to the running instance of the server.

    +
    5. +
+

Access and Test the MBeans

+

This quickstart differs from the other quickstarts in that it uses JConsole to access and test the quickstart rather than access an URL in the browser. If you do access http://localhost:8080/helloworld-mbean-webapp/, you will see a screen shot image of the JConsole application,

+

The following sections describe how to use JConsole to inspect and test the MBeans.

+

Start JConsole

+

To connect to the JBoss EAP server using JConsole, open a command prompt and type the following command :

+
For Linux:   JDK_HOME/bin/jconsole
+For Windows: JDK_HOME\bin\jconsole.exe
+
+

Select the local org.jboss.modules.Main process and click Connect.

+

MBeans in JConsole Connection

+

A dialog displays with the warning Secure connection failed. Retry insecurely?. Click Insecure to continue.

+

Test the MBeans in JConsole

+

You can use JConsole to inspect and use the MBeans : MBeans in JConsole

+
    +
  1. Click on the MBeans tab.
    2. +
  2. Expand quickstarts in the left column of the console.
    3. +
  3. Under quickstarts, you see the 4 MBeans: AnnotatedComponentHelloWorld, MXComponentHelloWorld, MXPojoHelloWorld, and SarMXPojoHelloWorld
    4. +
  4. Expand each MBean and choose: Operations --> sayHello.
    5. +
  5. Type your name in the (p0 String ) input text box and click the sayHello button.
    6. +
+
    +
  • For the AnnotatedComponentHelloWorld and MXComponentHelloWorld examples, you will see a popup Window displaying Hello <your name>!.
    • +
  • For the MXPojoHelloWorld and SarMXPojoHelloWorld examples, you will see a popup Window displaying Welcome <your name>!.
    • +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart consists of multiple projects and requires installation of the JBoss Tools Maven Packaging Configurator, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+
    +
  1. Install the JBoss Tools Maven Packaging Configurator +
      +
    • If the Red Hat Central page is not showing, open it by choosing Help --> Red Hat Central.
      • +
    • Click the Software/Update tab at the bottom of the Red Hat Central.
      • +
    • Scroll down to the Maven section, select the JBoss Tools Maven Packaging Configurator and click Install/Update.
      • +
    +
    2. +
  2. Right click on the parent helloworld-mbean parent project and choose Maven --> Update Project.... Select all projects and click OK.
    3. +
  3. Right-click on the helloworld-mbean-service project and choose Run As --> Run on Server.
    4. +
  4. Right-click on the helloworld-mbean-webapp project and choose Run As --> Run on Server.
    5. +
  5. Start JConsole and Test the MBeans in JConsole as described above.
    6. +
  6. To undeploy the web application, right-click on the helloworld-mbean-wepapp project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    7. +
  7. To undeploy the web service, right-click on the helloworld-mbean-service project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    8. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/helloworld-mbean/README.md b/helloworld-mbean/README.md index 344c67d635..310c304f2d 100644 --- a/helloworld-mbean/README.md +++ b/helloworld-mbean/README.md @@ -3,13 +3,13 @@ Author: Lagarde Jeremie Level: Intermediate Technologies: CDI, JMX, MBean -Summary: The `helloworld-mbean` quickstart demonstrates the use of *CDI* and *MBean* in ${product.name} and includes JConsole instructions and Arquillian tests. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `helloworld-mbean` quickstart demonstrates the use of *CDI* and *MBean* in JBoss EAP and includes JConsole instructions and Arquillian tests. +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld-mbean` quickstart demonstrates the use of *CDI* and *MBean* in ${product.name.full}. The project also includes a set of Arquillian tests for MBeans. +The `helloworld-mbean` quickstart demonstrates the use of *CDI* and *MBean* in Red Hat JBoss Enterprise Application Platform. The project also includes a set of Arquillian tests for MBeans. The example is composed of the following MBeans: @@ -24,59 +24,59 @@ The example is composed of the following MBeans: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). -## Start the ${product.name} Server +## Start the JBoss EAP Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `${project.artifactId}-webapp/target/${project.artifactId}-webapp.war` and `${project.artifactId}-service/target/${project.artifactId}-service.sar` to the running instance of the server. +4. This will deploy `helloworld-mbean-webapp/target/helloworld-mbean-webapp.war` and `helloworld-mbean-service/target/helloworld-mbean-service.sar` to the running instance of the server. ## Access and Test the MBeans -This quickstart differs from the other quickstarts in that it uses _JConsole_ to access and test the quickstart rather than access an URL in the browser. If you do access , you will see a screen shot image of the _JConsole_ application, +This quickstart differs from the other quickstarts in that it uses _JConsole_ to access and test the quickstart rather than access an URL in the browser. If you do access , you will see a screen shot image of the _JConsole_ application, The following sections describe how to use _JConsole_ to inspect and test the MBeans. ## Start JConsole -To connect to the ${product.name} server using _JConsole_, open a command prompt and type the following command : +To connect to the JBoss EAP server using _JConsole_, open a command prompt and type the following command : For Linux: JDK_HOME/bin/jconsole For Windows: JDK_HOME\bin\jconsole.exe Select the local `org.jboss.modules.Main` process and click `Connect`. -![MBeans in JConsole Connection](${project.artifactId}-webapp/src/main/webapp/jconsole_connection.png) +![MBeans in JConsole Connection](helloworld-mbean-webapp/src/main/webapp/jconsole_connection.png) A dialog displays with the warning `Secure connection failed. Retry insecurely?`. Click `Insecure` to continue. ## Test the MBeans in JConsole You can use _JConsole_ to inspect and use the MBeans : -![MBeans in JConsole](${project.artifactId}-webapp/src/main/webapp/jconsole.png) +![MBeans in JConsole](helloworld-mbean-webapp/src/main/webapp/jconsole.png) 1. Click on the MBeans tab. 2. Expand `quickstarts` in the left column of the console. @@ -89,7 +89,7 @@ You can use _JConsole_ to inspect and use the MBeans : ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -100,18 +100,18 @@ You can use _JConsole_ to inspect and use the MBeans : This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). This quickstart consists of multiple projects and requires installation of the `JBoss Tools Maven Packaging Configurator`, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. @@ -119,12 +119,12 @@ This quickstart consists of multiple projects and requires installation of the ` * If the `Red Hat Central` page is not showing, open it by choosing `Help` --> `Red Hat Central`. * Click the `Software/Update` tab at the bottom of the `Red Hat Central`. * Scroll down to the `Maven` section, select the `JBoss Tools Maven Packaging Configurator` and click `Install/Update`. -2. Right click on the parent `${project.artifactId}` parent project and choose `Maven` --> `Update Project...`. Select all projects and click `OK`. -3. Right-click on the `${project.artifactId}-service` project and choose `Run As` --> `Run on Server`. -4. Right-click on the `${project.artifactId}-webapp` project and choose `Run As` --> `Run on Server`. +2. Right click on the parent `helloworld-mbean` parent project and choose `Maven` --> `Update Project...`. Select all projects and click `OK`. +3. Right-click on the `helloworld-mbean-service` project and choose `Run As` --> `Run on Server`. +4. Right-click on the `helloworld-mbean-webapp` project and choose `Run As` --> `Run on Server`. 5. [Start JConsole](#start-jconsole) and [Test the MBeans in JConsole](#test-the-mbeans-in-jconsole) as described above. -6. To undeploy the web application, right-click on the `${project.artifactId}-wepapp` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. -7. To undeploy the web service, right-click on the `${project.artifactId}-service` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +6. To undeploy the web application, right-click on the `helloworld-mbean-wepapp` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +7. To undeploy the web service, right-click on the `helloworld-mbean-service` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/helloworld-mbean/helloworld-mbean-service/pom.xml b/helloworld-mbean/helloworld-mbean-service/pom.xml index 5f18a899e1..3019c79a00 100644 --- a/helloworld-mbean/helloworld-mbean-service/pom.xml +++ b/helloworld-mbean/helloworld-mbean-service/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts helloworld-mbean - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-mbean-service diff --git a/helloworld-mbean/helloworld-mbean-webapp/pom.xml b/helloworld-mbean/helloworld-mbean-webapp/pom.xml index 7b7dc22fee..d67e3698d6 100644 --- a/helloworld-mbean/helloworld-mbean-webapp/pom.xml +++ b/helloworld-mbean/helloworld-mbean-webapp/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts helloworld-mbean - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-mbean-webapp diff --git a/helloworld-mbean/pom.xml b/helloworld-mbean/pom.xml index 139586f4c2..5f376602f5 100644 --- a/helloworld-mbean/pom.xml +++ b/helloworld-mbean/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-mbean diff --git a/helloworld-mdb-propertysubstitution/README.html b/helloworld-mdb-propertysubstitution/README.html new file mode 100644 index 0000000000..aa0d17e153 --- /dev/null +++ b/helloworld-mdb-propertysubstitution/README.html @@ -0,0 +1,157 @@ + + + helloworld-mdb-propertysubstitution: MDB (Message-Driven Bean) Using Property Substitution + + + +

helloworld-mdb-propertysubstitution: MDB (Message-Driven Bean) Using Property Substitution

+

Author: Serge Pagop, Andy Taylor, Jeff Mesnil
+Level: Intermediate
+Technologies: JMS, EJB, MDB
+Summary: The helloworld-mdb-propertysubstitution quickstart demonstrates the use of JMS and EJB MDB, enabling property substitution with annotations.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld-mdb-propertysubstitution quickstart demonstrates the use of JMS and EJB Message-Driven Bean in Red Hat JBoss Enterprise Application Platform.

+

It is based on the helloworld-mdb quickstart, but has been enhanced to enable property substitution using the @Resource and @ActivationConfigProperty annotations.

+

This project creates two JMS resources:

+
    +
  • A queue named HELLOWORLDMDBQueue bound in JNDI as java:/${property.helloworldmdb.queue}
    • +
  • A topic named HELLOWORLDMDBTopic bound in JNDI as java:/${property.helloworldmdb.topic}
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Configure the Server

+

You enable MDB property substitution by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a enable-mdb-property-substitution.cli script provided in the root directory of this quickstart.

+
    +
  1. Before you begin, back up your server configuration file +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone-full.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows:  EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    3. +
  3. Review the enable-mdb-property-substitution.cli script file in the root of this quickstart directory. This script first enables MDB annotation property substitution the ee subsystem of the server configuration file by creating an annotation-property-replacement property with a value of true. It then defines the system properties that are used in the substitution.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=enable-mdb-property-substitution.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=enable-mdb-property-substitution.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+
    +
    5. +
  5. Stop the JBoss EAP server.
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone-full.xml file and review the changes.

+

The <annotation-property-replacement> attribute is set to true in the ee subsystem :

+
    <subsystem xmlns="urn:jboss:domain:ee:4.0">
+        ...
+        <annotation-property-replacement>true</annotation-property-replacement>
+        ...
+    </subsystem>
+
+

The following system properties are defined and appear after the <extensions>:

+
<system-properties>
+    <property name="property.helloworldmdb.queue" value="java:/queue/HELLOWORLDMDBPropQueue"/>
+    <property name="property.helloworldmdb.topic" value="java:/topic/HELLOWORLDMDBPropTopic"/>
+    <property name="property.connection.factory" value="java:/ConnectionFactory"/>
+</system-properties>
+
+

Start the Server with the Full Profile

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the full profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-mdb-propertysubstitution.war to the running instance of the server. Look at the JBoss EAP console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations:

    +
    INFO  [org.wildfly.extension.messaging-activemq] (MSC service thread 1-8) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/${property.helloworldmdb.queue}
+INFO  [org.wildfly.extension.messaging-activemq] (MSC service thread 1-5) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/${property.helloworldmdb.topic}
+...
+INFO  [org.wildfly.extension.messaging-activemq] (ServerService Thread Pool -- 70) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/queue/HELLOWORLDMDBPropQueue
+INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 73) AMQ221003: trying to deploy queue jms.topic.HelloWorldMDBTopic
+INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 72) AMQ221003: trying to deploy queue jms.topic.HELLOWORLDMDBTopic
+INFO  [org.wildfly.extension.messaging-activemq] (ServerService Thread Pool -- 72) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/topic/HELLOWORLDMDBPropTopic
+INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 71) AMQ221003: trying to deploy queue jms.queue.HelloWorldMDBQueue
+INFO  [org.jboss.as.ejb3] (MSC service thread 1-7) WFLYEJB0042: Started message driven bean 'HelloWorldQTopicMDB' with 'activemq-ra.rar' resource adapter
+INFO  [org.jboss.as.ejb3] (MSC service thread 1-6) WFLYEJB0042: Started message driven bean 'HelloWorldQueueMDB' with 'activemq-ra.rar' resource adapter
+
    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/helloworld-mdb-propertysubstitution/ and will send some messages to the queue.

+

To send messages to the topic, use the following URL: http://localhost:8080/helloworld-mdb-propertysubstitution/HelloWorldMDBServletClient?topic

+

Investigate the Server Console Output

+

Look at the JBoss EAP console or Server log and you should see log messages like the following:

+
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-9 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 5
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 1
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-7 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 4
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-5 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 2
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 3
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can remove the server configuration by running the disable-mdb-property-substitution.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows:  EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=disable-mdb-property-substitution.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=disable-mdb-property-substitution.cli
+
    +
    3. +
+

This script removes the system properties and sets the <annotation-property-replacement> value to false in the ee subsystem of the server configuration. You should see the following result when you run the script:

+
    The batch executed successfully
+
+

Restore the Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone-full.xml file with the back-up copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+
    +
  • Be sure to enable MDB property substitution by running the JBoss CLI commands as described above under Configure the JBoss EAP Server. Stop the server at the end of that step.
    • +
  • Within JBoss Developer Studio, be sure to define a server runtime environment that uses the standalone-full.xml configuration file.
    • +
  • Be sure to Restore the JBoss EAP Server Configuration when you have completed testing this quickstart.
    • +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/helloworld-mdb-propertysubstitution/README.md b/helloworld-mdb-propertysubstitution/README.md index c6d4d6b3e8..2921f76e97 100644 --- a/helloworld-mdb-propertysubstitution/README.md +++ b/helloworld-mdb-propertysubstitution/README.md @@ -4,12 +4,12 @@ Author: Serge Pagop, Andy Taylor, Jeff Mesnil Level: Intermediate Technologies: JMS, EJB, MDB Summary: The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of *JMS* and *EJB MDB*, enabling property substitution with annotations. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of *JMS* and *EJB Message-Driven Bean* in ${product.name.full}. +The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of *JMS* and *EJB Message-Driven Bean* in Red Hat JBoss Enterprise Application Platform. It is based on the [helloworld-mdb](../helloworld-mdb/README.md) quickstart, but has been enhanced to enable property substitution using the `@Resource` and `@ActivationConfigProperty` annotations. @@ -21,14 +21,14 @@ This project creates two JMS resources: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Configure the Server @@ -36,27 +36,27 @@ In the following instructions, replace `${jboss.home.name}` with the actual path You enable MDB property substitution by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `enable-mdb-property-substitution.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone-full.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone-full.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml 3. Review the `enable-mdb-property-substitution.cli` script file in the root of this quickstart directory. This script first enables MDB annotation property substitution the `ee` subsystem of the server configuration file by creating an `annotation-property-replacement` property with a value of `true`. It then defines the system properties that are used in the substitution. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=enable-mdb-property-substitution.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=enable-mdb-property-substitution.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=enable-mdb-property-substitution.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=enable-mdb-property-substitution.cli You should see the following result when you run the script: The batch executed successfully -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone-full.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone-full.xml` file and review the changes. The `` attribute is set to true in the `ee` subsystem : @@ -77,22 +77,22 @@ The following system properties are defined and appear after the ``: ## Start the Server with the Full Profile -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the full profile: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. Look at the ${product.name} console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations: +4. This will deploy `target/helloworld-mdb-propertysubstitution.war` to the running instance of the server. Look at the JBoss EAP console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations: INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-8) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/${property.helloworldmdb.queue} INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-5) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/${property.helloworldmdb.topic} @@ -108,13 +108,13 @@ The following system properties are defined and appear after the ``: ## Access the Application -The application will be running at the following URL: and will send some messages to the queue. +The application will be running at the following URL: and will send some messages to the queue. -To send messages to the topic, use the following URL: +To send messages to the topic, use the following URL: ## Investigate the Server Console Output -Look at the ${product.name} console or Server log and you should see log messages like the following: +Look at the JBoss EAP console or Server log and you should see log messages like the following: INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-9 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 5 INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 1 @@ -124,7 +124,7 @@ Look at the ${product.name} console or Server log and you should see log message ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -136,30 +136,30 @@ You can remove the server configuration by running the `disable-mdb-property-su ### Restore Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=disable-mdb-property-substitution.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=disable-mdb-property-substitution.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=disable-mdb-property-substitution.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=disable-mdb-property-substitution.cli This script removes the system properties and sets the `` value to `false` in the `ee` subsystem of the server configuration. You should see the following result when you run the script: The batch executed successfully ### Restore the Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -* Be sure to enable MDB property substitution by running the JBoss CLI commands as described above under [Configure the ${product.name} Server](#configure-the-server). Stop the server at the end of that step. +* Be sure to enable MDB property substitution by running the JBoss CLI commands as described above under [Configure the JBoss EAP Server](#configure-the-server). Stop the server at the end of that step. * Within JBoss Developer Studio, be sure to define a server runtime environment that uses the `standalone-full.xml` configuration file. -* Be sure to [Restore the ${product.name} Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. +* Be sure to [Restore the JBoss EAP Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/helloworld-mdb-propertysubstitution/pom.xml b/helloworld-mdb-propertysubstitution/pom.xml index 4f503d71de..9443509be1 100644 --- a/helloworld-mdb-propertysubstitution/pom.xml +++ b/helloworld-mdb-propertysubstitution/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-mdb-propertysubstitution diff --git a/helloworld-mdb/README.html b/helloworld-mdb/README.html new file mode 100644 index 0000000000..9c7679d7b4 --- /dev/null +++ b/helloworld-mdb/README.html @@ -0,0 +1,86 @@ + + + helloworld-mdb: Helloworld Using an MDB (Message-Driven Bean) + + + +

helloworld-mdb: Helloworld Using an MDB (Message-Driven Bean)

+

Author: Serge Pagop, Andy Taylor, Jeff Mesnil
+Level: Intermediate
+Technologies: JMS, EJB, MDB
+Summary: The helloworld-mdb quickstart uses JMS and EJB Message-Driven Bean (MDB) to create and deploy JMS topic and queue resources in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld-mdb quickstart demonstrates the use of JMS and EJB Message-Driven Bean in Red Hat JBoss Enterprise Application Platform.

+

This project creates two JMS resources:

+
    +
  • A queue named HELLOWORLDMDBQueue bound in JNDI as java:/queue/HELLOWORLDMDBQueue
    • +
  • A topic named HELLOWORLDMDBTopic bound in JNDI as java:/topic/HELLOWORLDMDBTopic
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server with the Full Profile

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the full profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-mdb.war to the running instance of the server. Look at the JBoss EAP console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations:

    +
    ...
+INFO  [org.wildfly.extension.messaging-activemq] (MSC service thread 1-4) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/queue/HELLOWORLDMDBQueue
+INFO  [org.wildfly.extension.messaging-activemq] (MSC service thread 1-2) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/topic/HELLOWORLDMDBTopic
+....
+INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 67) AMQ221003: trying to deploy queue jms.queue.HelloWorldMDBQueue
+...
+INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 12) AMQ221003: trying to deploy queue jms.topic.HelloWorldMDBTopic
+INFO  [org.jboss.as.ejb3] (MSC service thread 1-7) WFLYEJB0042: Started message driven bean 'HelloWorldQueueMDB' with 'activemq-ra.rar' resource adapter
+INFO  [org.jboss.as.ejb3] (MSC service thread 1-6) WFLYEJB0042: Started message driven bean 'HelloWorldQTopicMDB' with 'activemq-ra.rar' resource adapter
+
    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/helloworld-mdb/ and will send some messages to the queue.

+

To send messages to the topic, use the following URL: http://localhost:8080/helloworld-mdb/HelloWorldMDBServletClient?topic

+

Investigate the Server Console Output

+

Look at the JBoss EAP console or Server log and you should see log messages like the following:

+
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-9 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 5
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 1
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-7 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 4
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-5 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 2
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 3
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

NOTE: Within JBoss Developer Studio, be sure to define a server runtime environment that uses the standalone-full.xml configuration file.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + + \ No newline at end of file diff --git a/helloworld-mdb/README.md b/helloworld-mdb/README.md index 1cd1e9699c..16d5e037c2 100644 --- a/helloworld-mdb/README.md +++ b/helloworld-mdb/README.md @@ -3,13 +3,13 @@ Author: Serge Pagop, Andy Taylor, Jeff Mesnil Level: Intermediate Technologies: JMS, EJB, MDB -Summary: The `helloworld-mdb` quickstart uses *JMS* and *EJB Message-Driven Bean* (MDB) to create and deploy JMS topic and queue resources in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `helloworld-mdb` quickstart uses *JMS* and *EJB Message-Driven Bean* (MDB) to create and deploy JMS topic and queue resources in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld-mdb` quickstart demonstrates the use of *JMS* and *EJB Message-Driven Bean* in ${product.name.full}. +The `helloworld-mdb` quickstart demonstrates the use of *JMS* and *EJB Message-Driven Bean* in Red Hat JBoss Enterprise Application Platform. This project creates two JMS resources: @@ -19,34 +19,34 @@ This project creates two JMS resources: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server with the Full Profile -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the full profile: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. Look at the ${product.name} console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations: +4. This will deploy `target/helloworld-mdb.war` to the running instance of the server. Look at the JBoss EAP console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations: ... INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-4) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/queue/HELLOWORLDMDBQueue @@ -61,13 +61,13 @@ In the following instructions, replace `${jboss.home.name}` with the actual path ## Access the Application -The application will be running at the following URL: and will send some messages to the queue. +The application will be running at the following URL: and will send some messages to the queue. -To send messages to the topic, use the following URL: +To send messages to the topic, use the following URL: ## Investigate the Server Console Output -Look at the ${product.name} console or Server log and you should see log messages like the following: +Look at the JBoss EAP console or Server log and you should see log messages like the following: INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-9 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 5 INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 1 @@ -78,7 +78,7 @@ Look at the ${product.name} console or Server log and you should see log message ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -87,7 +87,7 @@ Look at the ${product.name} console or Server log and you should see log message ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). _NOTE:_ Within JBoss Developer Studio, be sure to define a server runtime environment that uses the `standalone-full.xml` configuration file. diff --git a/helloworld-mdb/pom.xml b/helloworld-mdb/pom.xml index 5934117591..898250d507 100644 --- a/helloworld-mdb/pom.xml +++ b/helloworld-mdb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-mdb diff --git a/helloworld-mutual-ssl-secured/README.html b/helloworld-mutual-ssl-secured/README.html new file mode 100644 index 0000000000..991ff959bf --- /dev/null +++ b/helloworld-mutual-ssl-secured/README.html @@ -0,0 +1,383 @@ + + + helloworld-mutual-ssl-secured: Securing a Web Application with Mutual (two-way) SSL Configuration and Role-based Access Control + + + +

helloworld-mutual-ssl-secured: Securing a Web Application with Mutual (two-way) SSL Configuration and Role-based Access Control

+

Author: Giriraj Sharma, Stefan Guilhen
+Level: Intermediate
+Technologies: Mutual SSL, Security, Undertow
+Summary: The helloworld-mutual-ssl-secured quickstart demonstrates securing a Web application using client mutual SSL authentication and role-based access control
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

This example demonstrates the configuration of mutual SSL authentication in Red Hat JBoss Enterprise Application Platform 7.1 to secure a war application.

+

Mutual SSL provides the same security as SSL, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. When mutual authentication is used, the server would request the client to provide a certificate in addition to the server certificate issued to the client. Mutual authentication requires an extra round trip time for client certificate exchange. In addition, the client must buy and maintain a digital certificate. We can secure our war application deployed over JBoss EAP with mutual(two-way) client certificate authentication and provide access permissions or privileges to legitimate users.

+

This quickstart shows how to configure JBoss EAP to enable TLS/SSL configuration for the new JBoss EAP undertow subsystem and enable mutual (two-way) SSL authentication for clients in order to secure a WAR application with restricted access.

+

System Requirements

+

The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss EAP, see the Red Hat JBoss Enterprise Application Platform Documentation Getting Started Guide located on the Customer Portal.

+

You can also use JBoss Developer Studio or Eclipse to run the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add the Application Users

+

Using the add-user utility script, you must add the following user to the ApplicationRealm:

+ + + + + + + +
UserName Realm Password Roles
quickstartUser ApplicationRealm quickstartPwd1! JBossAdmin
+

For the purpose of this quickstart the password can contain any valid value because the ApplicationRealm will be used for authorization only, for example, to obtain the security roles.

+

To add the application user, open a command prompt and type the following commands:

+
    For Linux:
+      EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'JBossAdmin'
+
+    For Windows:
+      EAP7_HOME\bin\add-user.bat  -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'JBossAdmin'
+
+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Setup Client and Server Keystores Using Java Keytool

+
    +
  1. Open a command line and navigate to the JBoss EAP server configuration directory: +
    For Linux:   EAP7_HOME/standalone/configuration
+For Windows: EAP7_HOME\standalone\configuration
+
    +
    2. +
  2. Create a certificate for your server using the following command: +
    $>keytool -genkey -keyalg RSA -keystore server.keystore -storepass secret -keypass secret -validity 365
+
+What is your first and last name?
+   [Unknown]:  localhost
+What is the name of your organizational unit?
+   [Unknown]:  wildfly
+What is the name of your organization?
+   [Unknown]:  jboss
+What is the name of your City or Locality?
+   [Unknown]:  Raleigh
+What is the name of your State or Province?
+   [Unknown]:  Carolina
+What is the two-letter country code for this unit?
+   [Unknown]:  US
+Is CN=localhost, OU=wildfly, O=jboss, L=Raleigh, ST=Carolina, C=US correct?
+   [no]:  yes
+
    +
    3. +
  3. +

    Create the client certificate, which is used to authenticate against the server when accessing a resource through SSL.

    +
    $>keytool -genkey -keystore client.keystore -storepass secret -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12
+
+What is your first and last name?
+    [Unknown]:  quickstartUser
+What is the name of your organizational unit?
+    [Unknown]:  Sales
+What is the name of your organization?
+    [Unknown]:  My Company
+What is the name of your City or Locality?
+    [Unknown]:  Sao Paulo
+What is the name of your State or Province?
+    [Unknown]:  Sao Paulo
+What is the two-letter country code for this unit?
+    [Unknown]:  BR
+Is CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR correct?
+    [no]:  yes
+
    +

    Notice that we set the fisrt and last name to quickstartUser and that this matches the user we've added to the ApplicationRealm. When authorizing access to a resource, the CN (common name) of the client's certificate is extracted by a principal decoder and this name is then used by the ApplicationRealm to obtain the client's roles.

    +
    4. +
  4. +

    Export the client certificate and create a truststore by importing this certificate:

    +
    $>keytool -exportcert -keystore client.keystore  -storetype pkcs12 -storepass secret -keypass secret -file client.crt
+$>keytool -import -file client.crt -alias quickstartUser -keystore client.truststore -storepass secret
+
+Owner: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR
+Issuer: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR
+Serial number: 7fd95ce4
+Valid from: Mon Jul 24 16:14:03 BRT 2017 until: Tue Jul 24 16:14:03 BRT 2018
+Certificate fingerprints:
+     MD5:  87:41:C5:CC:E6:79:91:F0:9D:90:AD:9E:DD:57:81:80
+     SHA1: 55:35:CA:B0:DC:DD:4F:E6:B8:9F:45:4B:4B:98:93:B5:3B:7C:55:84
+     SHA256: 0A:FC:93:B6:25:5A:74:42:B8:A1:C6:5F:69:88:72:7F:27:A9:81:B0:17:0C:F1:AF:3D:DE:B7:E5:F1:69:66:4B
+     Signature algorithm name: SHA256withRSA
+     Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: 95 84 BE C6 32 BB 2B 13   4C 7F 5D D4 C4 C8 22 12  ....2.+.L.]...".
+0010: CB 09 39 09                                        ..9.
+]
+]
+
+Trust this certificate? [no]:  yes
+Certificate was added to keystore
+
    +

    It is worth noticing that the client certificate was imported under the quickstartUser alias. When authenticating a client in a CLIENT_CERT configuration, the CN (common name) of the client's certificate is extracted by a principal decoder and this name is then used by the KeyStoreRealm to match an alias in the trust store. If a trusted certificate is found under this alas, the client is considered authenticated.

    +
    5. +
  5. +

    Export client certificate to pkcs12 format

    +
    $>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret
+
    +
    6. +
  6. +

    The certificates and keystores are now properly configured.

    +
    7. +
+

Configure the Server

+

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

+

You configure the SSL context and required security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-ssl.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-ssl.cli file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-ssl.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-ssl.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    5. +
  5. +

    Stop the JBoss EAP server.

    +
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. +

    The following key-stores were added to the elytron subsystem:

    +
    <key-store name="qsKeyStore">
+    <credential-reference clear-text="secret"/>
+    <implementation type="JKS"/>
+    <file path="server.keystore" relative-to="jboss.server.config.dir"/>
+</key-store>
+<key-store name="qsTrustStore">
+    <credential-reference clear-text="secret"/>
+    <implementation type="JKS"/>
+    <file path="client.truststore" relative-to="jboss.server.config.dir"/>
+</key-store>
+
    +
    2. +
  2. +

    The following key-manager was added to the elytron subsystem:

    +
    <key-managers>
+    <key-manager name="qsKeyManager" key-store="qsKeyStore">
+        <credential-reference clear-text="secret"/>
+    </key-manager>
+</key-managers>
+
    +
    3. +
  3. +

    The following trust-manager was added to the elytron subsystem:

    +
    <trust-managers>
+    <trust-manager name="qsTrustManager" key-store="qsTrustStore"/>
+</trust-managers>
+
    +
    4. +
  4. +

    The following ssl-context was added to the elytron subsystem:

    +
    <server-ssl-contexts>
+    <server-ssl-context name="qsSSLContext" protocols="TLSv1.2" need-client-auth="true" key-manager="qsKeyManager" trust-manager="qsTrustManager"/>
+</server-ssl-contexts>
+
    +
    5. +
  5. +

    The following realms were added to the elytron subsystem:

    +
    <key-store-realm name="KeyStoreRealm" key-store="qsTrustStore"/>
+
+<aggregate-realm name="QuickstartRealm" authentication-realm="KeyStoreRealm" authorization-realm="ApplicationRealm"/>
+
    +

    The aggregate-realm defines different security realms for authentication and authorization. In this case, the KeyStoreRealm is responsible for authenticating the principal extracted from the client's certificate and the ApplicationRealm is responsible for obtaining the roles required to access the application.

    +
    6. +
  6. +

    The following principal-decoder and security-domain were added to the elytron subsystem:

    +
    <x500-attribute-principal-decoder name="QuickstartDecoder" attribute-name="cn"/>
+
+<security-domain name="QuickstartDomain" default-realm="QuickstartRealm" permission-mapper="default-permission-mapper" principal-decoder="QuickstartDecoder">
+    <realm name="QuickstartRealm" role-decoder="groups-to-roles"/>
+</security-domain>
+
    +

    The x500-attribute-principal-decoder creates a new Principal from the CN attribute of the X500Principal obtained from the client's certificate. This new principal is supplied to the security realms and is also the principal returned in methods like getUserPrincipal and getCallerPrincipal.

    +
    7. +
  7. +

    The following http-authentication-factory was added to the elytron subsystem:

    +
    <http-authentication-factory name="quickstart-http-authentication" http-server-mechanism-factory="global" security-domain="QuickstartDomain">
+    <mechanism-configuration>
+        <mechanism mechanism-name="CLIENT_CERT"/>
+    </mechanism-configuration>
+</http-authentication-factory>
+
    +

    It defines the security domain that will handle requests using the CLIENT_CERT HTTP mechanism.

    +
    8. +
  8. +

    The https-listener in the undertow subsystem was changed to reference the qsSSLContext ssl-context:

    +
    <https-listener name="https" socket-binding="https" ssl-context="qsSSLContext" enable-http2="true"/>
+
    +
    9. +
  9. +

    The following application-security-domain was added to the undertow subsystem:

    +
    <application-security-domains>
+    <application-security-domain name="client_cert_domain" http-authentication-factory="quickstart-http-authentication"/>
+</application-security-domains>
+
    +

    It maps the client_cert_domain from the quickstart application to the http-authentication-factory shown above, so requests made to the application go through the configured HTTP authentication factory.

    +
    10. +
+

Test the Server SSL Configuration

+

To test the SSL configuration, access: https://localhost:8443

+

If it is configured correctly, you should be asked to trust the server certificate.

+

Import the Certificate into Your Browser

+

Before you access the application, you must import the clientCert.p12, which holds the client certificate, into your browser.

+

Import the Certificate into Google Chrome

+
    +
  1. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/.
    2. +
  2. Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings.
    3. +
  3. Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it.
    4. +
  4. In the 'Manage certificates' screen, select the 'Your Certificates' tab and click on the 'Import' button.
    5. +
  5. Select the clientCert.p12 file. You will be prompted to enter the password: secret.
    6. +
  6. The client certificate is now installed in the Google Chrome browser.
    7. +
+

Import the Certificate into Mozilla Firefox

+
    +
  1. Click the 'Edit' menu item on the browser menu and choose 'Preferences'.
    2. +
  2. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab.
    3. +
  3. On the 'Certificates' tab, mark the option 'Ask me every time' and click the 'View Certificates' button.
    4. +
  4. A new window will open. Select the 'Your Certificates' tab and click the 'Import' button.
    5. +
  5. Select the clientCert.p12 file. You will be prompted to enter the password: secret.
    6. +
  6. The certificate is now installed in the Mozilla Firefox browser.
    7. +
+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the web profile: +
    For Linux:   bin/standalone.sh
+For Windows: bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+

NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See Build and Deploy the Quickstarts for complete instructions and additional options.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of one of the quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-mutual-ssl-secured.war to the running instance of the server.

    +
    5. +
  5. In case mutual ssl is configured properly and war app is secured, you will be able to access the application only if the DN of client certificate i.e., clientCert.p12 is same as the one mentioned in app-roles.properties file. It will otherwise result into a HTTP Status 403 or forbidden error.
    6. +
+

Access the Application

+

The application will be running at the following URL: <https://localhost:8443/helloworld-mutual-ssl-secured>. A page displaying the caller principal and the client certificate used for mutual SSL should be visible:

+
    Hello World ! Mutual SSL client authentication is successful and your war app is secured.!!
+
+    Caller Principal: quickstartUser
+
+    Client Certificate Pem: MIIDhTCCAm2gAwIBAgIEf9lc5DANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJCUjESMBAGA1UECBMJU2FvIFBhdW
+    xvMRIwEAYDVQQHEwlTYW8gUGF1bG8xEzARBgNVBAoTCk15IENvbXBhbnkxDjAMBgNVBAsTBVNhbGVzMRcwFQYDVQQDEw5xdWlja3N0YXJ0VXNlcjAe
+    Fw0xNzA3MjQxOTE0MDNaFw0xODA3MjQxOTE0MDNaMHMxCzAJBgNVBAYTAkJSMRIwEAYDVQQIEwlTYW8gUGF1bG8xEjAQBgNVBAcTCVNhbyBQYXVsbz
+    ETMBEGA1UEChMKTXkgQ29tcGFueTEOMAwGA1UECxMFU2FsZXMxFzAVBgNVBAMTDnF1aWNrc3RhcnRVc2VyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
+    MIIBCgKCAQEAnHwflE8K/ArTPbTeZZEFK+1jtpg9grPSD62GIz/awoIDr6Rf9vCBTpAg4lom62A0BNZDEJKdab/ExNOOBRY+/pOnYlXZTYlDpdQQap
+    0E7UP5EfHNZsafgpfILCop2LdTuUbcV7tLKBsthJLJ0ZCoG5QJFble+OPxEbissOvIqHfvUJZi34k9ULteLJc330g0uTuDrLgtoFQ0cbHa4FCQ86o8
+    5EuRPpFeW6EBA3iYE/tKHSYsK7QSajefX6jZjXoZiUflw97SAGL43ZtvNbrKRywEfsVqDpDurjBg2HI+YahuDz5R1QWTSyTHWMZzcyJYqxjXiSf0oK
+    1cUahn6m5t1wIDAQABoyEwHzAdBgNVHQ4EFgQUlYS+xjK7KxNMf13UxMgiEssJOQkwDQYJKoZIhvcNAQELBQADggEBADkp+R6kSNXJNfihqbDRp3uF
+    tNMG6OgaYsfC7RtNLMdrhvoLlU7uWzxVCFuifvNlWVRiADBHDCRQU2uNRFW35GQSfHQyok4KoBuKlfBtQ+Xu7c8R0JzxN/rPJPXoCbShzDHo1uoz5/
+    dzXZz0EjjWCPJk+LVEhEvH0GcWAp3x3irpNU4hRZLd0XomY0Z4NnUt7VMBNYDOxVxgT9qcLnEaEpIfYULubLLCFHwAga2YgsKzZYLuwMaEWK4zhPVF
+    ynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9wcMzIIkP2Mk14gJGHUnA8=
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can restore the original server configuration by running the restore-configuration.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli
+
    +

    This script reverts the changes made to the undertow and elytron subsystems. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    3. +
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Remove the keystores and certificates created for this quickstart

+
    +
  1. Open a command line and navigate to the JBoss EAP server configuration directory: +
    For Linux:   standalone/configuration
+For Windows: standalone\configuration
+
    +
    2. +
  2. Remove the clientCert.p12, client.crt, client.keystore, client.truststore and server.keystore files that were generated for this quickstart.
    3. +
+

Remove the Client Certificate from Your Browser

+

After you are done with this quickstart, remember to remove the certificate that was imported into your browser.

+

Remove the Client Certificate from Google Chrome

+
    +
  1. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/.
    2. +
  2. Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings.
    3. +
  3. Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it.
    4. +
  4. In the 'Manage certificates' screen, select the 'Your Certificates' tab and then click on the arrow to the right of the certificate to be removed.
    5. +
  5. The certificate is expanded, displaying the quickstartUser entry. Click on the icon (3 dots) to the right of it and then select 'Delete'.
    6. +
  6. Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser.
    7. +
+

Remove the Client Certificate from Mozilla Firefox

+
    +
  1. Click the 'Edit' menu item on the browser menu and choose 'Preferences'.
    2. +
  2. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab.
    3. +
  3. On the 'Certificates' tab click the 'View Certificates' button.
    4. +
  4. A new window will open. Select the 'Your Certificates' tab.
    5. +
  5. Select the quickstartUser certificate and click the Delete button.
    6. +
  6. The certificate has now been removed from the Mozilla Firefox browser.
    7. +
+

Run the Quickstart in JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+ +

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources  
+
+ + \ No newline at end of file diff --git a/helloworld-mutual-ssl-secured/README.md b/helloworld-mutual-ssl-secured/README.md index 60ed7feb8e..96309a999d 100644 --- a/helloworld-mutual-ssl-secured/README.md +++ b/helloworld-mutual-ssl-secured/README.md @@ -4,30 +4,30 @@ Author: Giriraj Sharma, Stefan Guilhen Level: Intermediate Technologies: Mutual SSL, Security, Undertow Summary: The `helloworld-mutual-ssl-secured` quickstart demonstrates securing a Web application using client mutual SSL authentication and role-based access control -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -This example demonstrates the configuration of *mutual SSL authentication* in ${product.name.full} ${product.version} to secure a war application. +This example demonstrates the configuration of *mutual SSL authentication* in Red Hat JBoss Enterprise Application Platform 7.1 to secure a war application. -Mutual SSL provides the same security as SSL, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. When mutual authentication is used, the server would request the client to provide a certificate in addition to the server certificate issued to the client. Mutual authentication requires an extra round trip time for client certificate exchange. In addition, the client must buy and maintain a digital certificate. We can secure our war application deployed over ${product.name} with mutual(two-way) client certificate authentication and provide access permissions or privileges to legitimate users. +Mutual SSL provides the same security as SSL, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. When mutual authentication is used, the server would request the client to provide a certificate in addition to the server certificate issued to the client. Mutual authentication requires an extra round trip time for client certificate exchange. In addition, the client must buy and maintain a digital certificate. We can secure our war application deployed over JBoss EAP with mutual(two-way) client certificate authentication and provide access permissions or privileges to legitimate users. -This quickstart shows how to configure ${product.name} to enable TLS/SSL configuration for the new ${product.name} `undertow` subsystem and enable mutual (two-way) SSL authentication for clients in order to secure a WAR application with restricted access. +This quickstart shows how to configure JBoss EAP to enable TLS/SSL configuration for the new JBoss EAP `undertow` subsystem and enable mutual (two-way) SSL authentication for clients in order to secure a WAR application with restricted access. ## System Requirements -The applications these projects produce are designed to be run on ${product.name.full} ${product.version} or later. +The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build these projects is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on how to install and run ${product.name}, see the [${product.name.full} Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. +To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss EAP, see the [Red Hat JBoss Enterprise Application Platform Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) to run the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add the Application Users @@ -42,20 +42,20 @@ For the purpose of this quickstart the password can contain any valid value beca To add the application user, open a command prompt and type the following commands: For Linux: - ${jboss.home.name}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'JBossAdmin' + EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'JBossAdmin' For Windows: - ${jboss.home.name}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'JBossAdmin' + EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'JBossAdmin' If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: [Add an Application User](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user). ## Setup Client and Server Keystores Using Java Keytool -1. Open a command line and navigate to the ${product.name} server `configuration` directory: +1. Open a command line and navigate to the JBoss EAP server `configuration` directory: - For Linux: ${jboss.home.name}/standalone/configuration - For Windows: ${jboss.home.name}\standalone\configuration + For Linux: EAP7_HOME/standalone/configuration + For Windows: EAP7_HOME\standalone\configuration 2. Create a certificate for your server using the following command: $>keytool -genkey -keyalg RSA -keystore server.keystore -storepass secret -keypass secret -validity 365 @@ -145,30 +145,30 @@ These steps assume you are running the server in standalone mode and using the d You configure the SSL context and required security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-ssl.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-ssl.cli` file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-ssl.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-ssl.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-ssl.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-ssl.cli You should see the following result when you run the script: The batch executed successfully process-state: reload-required -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following `key-store`s were added to the `elytron` subsystem: @@ -276,7 +276,7 @@ Before you access the application, you must import the *clientCert.p12*, which h ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the web profile: For Linux: bin/standalone.sh @@ -286,18 +286,18 @@ Before you access the application, you must import the *clientCert.p12*, which h _NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._ -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of one of the quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/helloworld-mutual-ssl-secured.war` to the running instance of the server. 5. In case mutual ssl is configured properly and war app is secured, you will be able to access the application only if the DN of client certificate i.e., `clientCert.p12` is same as the one mentioned in `app-roles.properties` file. It will otherwise result into a `HTTP Status 403` or forbidden error. ## Access the Application -The application will be running at the following URL: ``. A page displaying the caller +The application will be running at the following URL: ``. A page displaying the caller principal and the client certificate used for mutual SSL should be visible: Hello World ! Mutual SSL client authentication is successful and your war app is secured.!! @@ -318,7 +318,7 @@ principal and the client certificate used for mutual SSL should be visible: ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -330,14 +330,14 @@ You can restore the original server configuration by running the `restore-config ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-configuration.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-configuration.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli This script reverts the changes made to the `undertow` and `elytron` subsystems. You should see the following result when you run the script: The batch executed successfully @@ -345,12 +345,12 @@ You can restore the original server configuration by running the `restore-config ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Remove the keystores and certificates created for this quickstart -1. Open a command line and navigate to the ${product.name} server `configuration` directory: +1. Open a command line and navigate to the JBoss EAP server `configuration` directory: For Linux: standalone/configuration For Windows: standalone\configuration @@ -380,9 +380,9 @@ After you are done with this quickstart, remember to remove the certificate that ## Run the Quickstart in JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -* Be sure to configure the server by running the JBoss CLI commands as described above under [Configure the ${product.name} Server](#configure-the-server). Stop the server at the end of that step. +* Be sure to configure the server by running the JBoss CLI commands as described above under [Configure the JBoss EAP Server](#configure-the-server). Stop the server at the end of that step. * Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/helloworld-mutual-ssl-secured/pom.xml b/helloworld-mutual-ssl-secured/pom.xml index 5272340a02..62447eff11 100644 --- a/helloworld-mutual-ssl-secured/pom.xml +++ b/helloworld-mutual-ssl-secured/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/helloworld-mutual-ssl/README.html b/helloworld-mutual-ssl/README.html new file mode 100644 index 0000000000..05f8ff996b --- /dev/null +++ b/helloworld-mutual-ssl/README.html @@ -0,0 +1,329 @@ + + + helloworld-mutual-ssl: JBoss EAP Mutual SSL(two-way) Configuration Example + + + +

helloworld-mutual-ssl: JBoss EAP Mutual SSL(two-way) Configuration Example

+

Author: Giriraj Sharma, Stefan Guilhen
+Level: Intermediate
+Technologies: Mutual SSL, Undertow
+Summary: The helloworld-mutual-ssl quickstart is a basic example that demonstrates mutual SSL configuration in JBoss EAP
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

Mutual SSL provides the same security as SSL, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. When mutual authentication is used, the server requests the client to provide a certificate in addition to the server certificate issued to the client. Mutual authentication requires an extra round trip each time for client certificate exchange. In addition, the client must buy and maintain a digital certificate.

+

This quickstart shows how to configure JBoss EAP to enable TLS/SSL configuration for the new JBoss EAP undertow subsystem and enable mutual (two-way) SSL authentication.

+

Before you run this example, you must create certificates and configure the server to use two-way SSL.

+

System Requirements

+

The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the Red Hat JBoss Enterprise Application Platform Documentation Getting Started Guide located on the Customer Portal.

+

You can also use JBoss Developer Studio or Eclipse to run the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Set Up Client and Server Keystores Using Java Keytool

+
    +
  1. Open a command line and navigate to the JBoss EAP server configuration directory: +
    For Linux:   EAP7_HOME/standalone/configuration
+For Windows: EAP7_HOME\standalone\configuration
+
    +
    2. +
  2. Create a certificate for your server using the following command: +
    $>keytool -genkey -keyalg RSA -keystore server.keystore -storepass secret -keypass secret -validity 365
+
+What is your first and last name?
+   [Unknown]:  localhost
+What is the name of your organizational unit?
+   [Unknown]:  wildfly
+What is the name of your organization?
+   [Unknown]:  jboss
+What is the name of your City or Locality?
+   [Unknown]:  Raleigh
+What is the name of your State or Province?
+   [Unknown]:  Carolina
+What is the two-letter country code for this unit?
+   [Unknown]:  US
+Is CN=localhost, OU=wildfly, O=jboss, L=Raleigh, ST=Carolina, C=US correct?
+   [no]:  yes
+
    +
    3. +
  3. +

    Create the client certificate, which is used to authenticate against the server when accessing a resource through SSL.

    +
    $>keytool -genkey -keystore client.keystore -storepass secret -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12
+
+What is your first and last name?
+    [Unknown]:  quickstartUser
+What is the name of your organizational unit?
+    [Unknown]:  Sales
+What is the name of your organization?
+    [Unknown]:  My Company
+What is the name of your City or Locality?
+    [Unknown]:  Sao Paulo
+What is the name of your State or Province?
+    [Unknown]:  Sao Paulo
+What is the two-letter country code for this unit?
+    [Unknown]:  BR
+Is CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR correct?
+    [no]:  yes
+
    +
    4. +
  4. +

    Export the client certificate and create a truststore by importing this certificate:

    +
    $>keytool -exportcert -keystore client.keystore  -storetype pkcs12 -storepass secret -keypass secret -file client.crt
+$>keytool -import -file client.crt -alias quickstartUser -keystore client.truststore -storepass secret
+
+Owner: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR
+Issuer: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR
+Serial number: 7fd95ce4
+Valid from: Mon Jul 24 16:14:03 BRT 2017 until: Tue Jul 24 16:14:03 BRT 2018
+Certificate fingerprints:
+     MD5:  87:41:C5:CC:E6:79:91:F0:9D:90:AD:9E:DD:57:81:80
+     SHA1: 55:35:CA:B0:DC:DD:4F:E6:B8:9F:45:4B:4B:98:93:B5:3B:7C:55:84
+     SHA256: 0A:FC:93:B6:25:5A:74:42:B8:A1:C6:5F:69:88:72:7F:27:A9:81:B0:17:0C:F1:AF:3D:DE:B7:E5:F1:69:66:4B
+     Signature algorithm name: SHA256withRSA
+     Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: 95 84 BE C6 32 BB 2B 13   4C 7F 5D D4 C4 C8 22 12  ....2.+.L.]...".
+0010: CB 09 39 09                                        ..9.
+]
+]
+
+Trust this certificate? [no]:  yes
+Certificate was added to keystore
+
    +
    5. +
  5. +

    Export client certificate to pkcs12 format

    +
    $>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret
+
    +
    6. +
  6. +

    The certificates and keystores are now properly configured.

    +
    7. +
+

Configure the Server

+

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

+

You configure the SSL context by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-ssl.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-ssl.cli file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-ssl.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-ssl.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    5. +
  5. +

    Stop the JBoss EAP server.

    +
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. +

    The following key-stores were added to the elytron subsystem:

    +
    <key-store name="qsKeyStore">
+    <credential-reference clear-text="secret"/>
+    <implementation type="JKS"/>
+    <file path="server.keystore" relative-to="jboss.server.config.dir"/>
+</key-store>
+<key-store name="qsTrustStore">
+    <credential-reference clear-text="secret"/>
+    <implementation type="JKS"/>
+    <file path="client.truststore" relative-to="jboss.server.config.dir"/>
+</key-store>
+
    +
    2. +
  2. +

    The following key-manager was added to the elytron subsystem:

    +
    <key-managers>
+    <key-manager name="qsKeyManager" key-store="qsKeyStore">
+        <credential-reference clear-text="secret"/>
+    </key-manager>
+</key-managers>
+
    +
    3. +
  3. +

    The following trust-manager was added to the elytron subsystem:

    +
    <trust-managers>
+    <trust-manager name="qsTrustManager" key-store="qsTrustStore"/>
+</trust-managers>
+
    +
    4. +
  4. +

    The following ssl-context was added to the elytron subsystem:

    +
    <server-ssl-contexts>
+    <server-ssl-context name="qsSSLContext" protocols="TLSv1.2" need-client-auth="true" key-manager="qsKeyManager" trust-manager="qsTrustManager"/>
+</server-ssl-contexts>
+
    +
    5. +
  5. +

    The https-listener in the undertow subsystem was changed to reference the qsSSLContext ssl-context:

    +
    <https-listener name="https" socket-binding="https" ssl-context="qsSSLContext" enable-http2="true"/>
+
    +
    6. +
+

Test the Server SSL Configuration

+

To test the SSL configuration, access: https://localhost:8443

+

If it is configured correctly, you should be asked to trust the server certificate.

+

Import the Client Certificate into Your Browser

+

Before you access the application, you must import the clientCert.p12, which holds the client certificate, into your browser.

+

Import the Client Certificate into Google Chrome

+
    +
  1. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/.
    2. +
  2. Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings.
    3. +
  3. Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it.
    4. +
  4. In the 'Manage certificates' screen, select the 'Your Certificates' tab and click on the 'Import' button.
    5. +
  5. Select the clientCert.p12 file. You will be prompted to enter the password: secret.
    6. +
  6. The client certificate is now installed in the Google Chrome browser.
    7. +
+

Import the Client Certificate into Mozilla Firefox

+
    +
  1. Click the 'Edit' menu item on the browser menu and choose 'Preferences'.
    2. +
  2. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab.
    3. +
  3. On the 'Certificates' tab, mark the option 'Ask me every time' and click the 'View Certificates' button.
    4. +
  4. A new window will open. Select the 'Your Certificates' tab and click the 'Import' button.
    5. +
  5. Select the clientCert.p12 file. You will be prompted to enter the password: secret.
    6. +
  6. The certificate is now installed in the Mozilla Firefox browser.
    7. +
+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss server directory.
    2. +
  2. The following shows the command line to start the server with the web profile: +
    For Linux:   /bin/standalone.sh
+For Windows: bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+

NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See Build and Deploy the Quickstarts for complete instructions and additional options.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of one of the quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-mutual-ssl.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: https://localhost:8443/helloworld-mutual-ssl/HelloWorld.

+

A page displaying the client certificate should be visible:

+
    Hello World ! Wildfly mutual SSL is configured and client certificate is verified !!
+
+    Client Certificate Pem: MIIDhTCCAm2gAwIBAgIEf9lc5DANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJCUjESMBAGA1UECBMJU2FvIFBhd
+    WxvMRIwEAYDVQQHEwlTYW8gUGF1bG8xEzARBgNVBAoTCk15IENvbXBhbnkxDjAMBgNVBAsTBVNhbGVzMRcwFQYDVQQDEw5xdWlja3N0YXJ0VXNlcj
+    AeFw0xNzA3MjQxOTE0MDNaFw0xODA3MjQxOTE0MDNaMHMxCzAJBgNVBAYTAkJSMRIwEAYDVQQIEwlTYW8gUGF1bG8xEjAQBgNVBAcTCVNhbyBQYXV
+    sbzETMBEGA1UEChMKTXkgQ29tcGFueTEOMAwGA1UECxMFU2FsZXMxFzAVBgNVBAMTDnF1aWNrc3RhcnRVc2VyMIIBIjANBgkqhkiG9w0BAQEFAAOC
+    AQ8AMIIBCgKCAQEAnHwflE8K/ArTPbTeZZEFK+1jtpg9grPSD62GIz/awoIDr6Rf9vCBTpAg4lom62A0BNZDEJKdab/ExNOOBRY+/pOnYlXZTYlDp
+    dQQap0E7UP5EfHNZsafgpfILCop2LdTuUbcV7tLKBsthJLJ0ZCoG5QJFble+OPxEbissOvIqHfvUJZi34k9ULteLJc330g0uTuDrLgtoFQ0cbHa4F
+    CQ86o85EuRPpFeW6EBA3iYE/tKHSYsK7QSajefX6jZjXoZiUflw97SAGL43ZtvNbrKRywEfsVqDpDurjBg2HI+YahuDz5R1QWTSyTHWMZzcyJYqxj
+    XiSf0oK1cUahn6m5t1wIDAQABoyEwHzAdBgNVHQ4EFgQUlYS+xjK7KxNMf13UxMgiEssJOQkwDQYJKoZIhvcNAQELBQADggEBADkp+R6kSNXJNfih
+    qbDRp3uFtNMG6OgaYsfC7RtNLMdrhvoLlU7uWzxVCFuifvNlWVRiADBHDCRQU2uNRFW35GQSfHQyok4KoBuKlfBtQ+Xu7c8R0JzxN/rPJPXoCbShz
+    DHo1uoz5/dzXZz0EjjWCPJk+LVEhEvH0GcWAp3x3irpNU4hRZLd0XomY0Z4NnUt7VMBNYDOxVxgT9qcLnEaEpIfYULubLLCFHwAga2YgsKzZYLuwM
+    aEWK4zhPVFynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9wcMzIIkP2Mk14gJGHUnA8=
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss Server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can restore the original server configuration by running the restore-configuration.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli
+
    +

    This script reverts the changes made to the undertow subsystem and it also removes the ssl-context, key-manager, trust-manager and key-stores from the elytron subsystem. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    3. +
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Remove the keystores and certificates created for this quickstart

+
    +
  1. Open a command line and navigate to the JBoss EAP server configuration directory: +
    For Linux:   standalone/configuration
+For Windows: standalone\configuration
+
    +
    2. +
  2. Remove the clientCert.p12, client.crt, client.keystore, client.truststore and server.keystore files that were generated for this quickstart.
    3. +
+

Remove the Client Certificate from Your Browser

+

After you are done with this quickstart, remember to remove the certificate that was imported into your browser.

+

Remove the Client Certificate from Google Chrome

+
    +
  1. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/.
    2. +
  2. Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings.
    3. +
  3. Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it.
    4. +
  4. In the 'Manage certificates' screen, select the 'Your Certificates' tab and then click on the arrow to the right of the certificate to be removed.
    5. +
  5. The certificate is expanded, displaying the quickstartUser entry. Click on the icon (3 dots) to the right of it and then select 'Delete'.
    6. +
  6. Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser.
    7. +
+

Remove the Client Certificate from Mozilla Firefox

+
    +
  1. Click the 'Edit' menu item on the browser menu and choose 'Preferences'.
    2. +
  2. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab.
    3. +
  3. On the 'Certificates' tab click the 'View Certificates' button.
    4. +
  4. A new window will open. Select the 'Your Certificates' tab.
    5. +
  5. Select the quickstartUser certificate and click the Delete button.
    6. +
  6. The certificate has now been removed from the Mozilla Firefox browser.
    7. +
+

Run the Quickstart in JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+ +

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/helloworld-mutual-ssl/README.md b/helloworld-mutual-ssl/README.md index ccb1fc6e17..5ea31faead 100644 --- a/helloworld-mutual-ssl/README.md +++ b/helloworld-mutual-ssl/README.md @@ -1,40 +1,40 @@ -# helloworld-mutual-ssl: ${product.name} Mutual SSL(two-way) Configuration Example +# helloworld-mutual-ssl: JBoss EAP Mutual SSL(two-way) Configuration Example Author: Giriraj Sharma, Stefan Guilhen Level: Intermediate Technologies: Mutual SSL, Undertow -Summary: The `helloworld-mutual-ssl` quickstart is a basic example that demonstrates mutual SSL configuration in ${product.name} -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `helloworld-mutual-ssl` quickstart is a basic example that demonstrates mutual SSL configuration in JBoss EAP +Target Product: JBoss EAP +Source: ## What is it? Mutual SSL provides the same security as SSL, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. When mutual authentication is used, the server requests the client to provide a certificate in addition to the server certificate issued to the client. Mutual authentication requires an extra round trip each time for client certificate exchange. In addition, the client must buy and maintain a digital certificate. -This quickstart shows how to configure ${product.name} to enable TLS/SSL configuration for the new ${product.name} `undertow` subsystem and enable mutual (two-way) SSL authentication. +This quickstart shows how to configure JBoss EAP to enable TLS/SSL configuration for the new JBoss EAP `undertow` subsystem and enable mutual (two-way) SSL authentication. Before you run this example, you must create certificates and configure the server to use two-way SSL. ## System Requirements -The applications these projects produce are designed to be run on ${product.name.full} ${product.version} or later. +The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build these projects is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on how to install and run JBoss, see the [${product.name.full} Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. +To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the [Red Hat JBoss Enterprise Application Platform Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) to run the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Set Up Client and Server Keystores Using Java Keytool -1. Open a command line and navigate to the ${product.name} server `configuration` directory: +1. Open a command line and navigate to the JBoss EAP server `configuration` directory: - For Linux: ${jboss.home.name}/standalone/configuration - For Windows: ${jboss.home.name}\standalone\configuration + For Linux: EAP7_HOME/standalone/configuration + For Windows: EAP7_HOME\standalone\configuration 2. Create a certificate for your server using the following command: $>keytool -genkey -keyalg RSA -keystore server.keystore -storepass secret -keypass secret -validity 365 @@ -115,30 +115,30 @@ These steps assume you are running the server in standalone mode and using the d You configure the SSL context by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-ssl.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-ssl.cli` file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-ssl.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-ssl.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-ssl.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-ssl.cli You should see the following result when you run the script: The batch executed successfully process-state: reload-required -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following `key-store`s were added to the `elytron` subsystem: @@ -217,17 +217,17 @@ Before you access the application, you must import the *clientCert.p12*, which h _NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._ -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of one of the quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/helloworld-mutual-ssl.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . A page displaying the client certificate should be visible: @@ -259,14 +259,14 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-configuration.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-configuration.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli This script reverts the changes made to the `undertow` subsystem and it also removes the `ssl-context`, `key-manager`, `trust-manager` and `key-store`s from the `elytron` subsystem. You should see the following result when you run the script: @@ -275,12 +275,12 @@ from the `elytron` subsystem. You should see the following result when you run t ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Remove the keystores and certificates created for this quickstart -1. Open a command line and navigate to the ${product.name} server `configuration` directory: +1. Open a command line and navigate to the JBoss EAP server `configuration` directory: For Linux: standalone/configuration For Windows: standalone\configuration @@ -311,13 +311,13 @@ After you are done with this quickstart, remember to remove the certificate that ## Run the Quickstart in JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). * Be sure to configure the keystores and client certificates as described under [Set Up Client and Server Keystores Using Java Keytool](#set-up-client-and-server-keystores-using-java-keytool). * Depending on the browser you choose, be sure to either [import the certificate into Chrome](#import-the-client-certificate-into-google-chrome) or [import the certificate into Firefox](#import-the-client-certificate-into-mozilla-firefox). -* Be sure to configure the server by running the JBoss CLI commands as described above under [Configure the ${product.name} Server](#configure-the-server). Stop the server at the end of that step. +* Be sure to configure the server by running the JBoss CLI commands as described above under [Configure the JBoss EAP Server](#configure-the-server). Stop the server at the end of that step. * In JBoss Developer Studio, choose *Window* --> *Web Browser*, then select the browser you chose to import the certificate. -* To deploy the application, right-click on the `${project.artifactId}` project and choose `Run As` --> `Run on Server`. +* To deploy the application, right-click on the `helloworld-mutual-ssl` project and choose `Run As` --> `Run on Server`. * Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/helloworld-mutual-ssl/pom.xml b/helloworld-mutual-ssl/pom.xml index 531fbb4cb5..6c8edf87f5 100644 --- a/helloworld-mutual-ssl/pom.xml +++ b/helloworld-mutual-ssl/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-mutual-ssl diff --git a/helloworld-rs/README.html b/helloworld-rs/README.html new file mode 100644 index 0000000000..cc39a06375 --- /dev/null +++ b/helloworld-rs/README.html @@ -0,0 +1,63 @@ + + + helloworld-rs: Helloworld Using JAX-RS (Java API for RESTful Web Services) + + + +

helloworld-rs: Helloworld Using JAX-RS (Java API for RESTful Web Services)

+

Author: Gustavo A. Brey, Gaston Coco
+Level: Intermediate
+Technologies: CDI, JAX-RS
+Summary: The helloworld-rs quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses JAX-RS to say Hello.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld-rs quickstart demonstrates the use of CDI and JAX-RS in Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-rs.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application is deployed to http://localhost:8080/helloworld-rs/.

+

The XML content can be viewed by accessing the following URL: http://localhost:8080/helloworld-rs/rest/xml

+

The JSON content can be viewed by accessing this URL: http://localhost:8080/helloworld-rs/rest/json

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + + \ No newline at end of file diff --git a/helloworld-rs/README.md b/helloworld-rs/README.md index 1594d1afa0..ee5f2d51be 100644 --- a/helloworld-rs/README.md +++ b/helloworld-rs/README.md @@ -4,58 +4,58 @@ Author: Gustavo A. Brey, Gaston Coco Level: Intermediate Technologies: CDI, JAX-RS Summary: The `helloworld-rs` quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses *JAX-RS* to say Hello. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld-rs` quickstart demonstrates the use of *CDI* and *JAX-RS* in ${product.name.full}. +The `helloworld-rs` quickstart demonstrates the use of *CDI* and *JAX-RS* in Red Hat JBoss Enterprise Application Platform. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/helloworld-rs.war` to the running instance of the server. ## Access the Application -The application is deployed to . +The application is deployed to . -The *XML* content can be viewed by accessing the following URL: +The *XML* content can be viewed by accessing the following URL: -The *JSON* content can be viewed by accessing this URL: +The *JSON* content can be viewed by accessing this URL: ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -64,7 +64,7 @@ The *JSON* content can be viewed by accessing this URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-rs diff --git a/helloworld-singleton/README.html b/helloworld-singleton/README.html new file mode 100644 index 0000000000..de6c0f8d1a --- /dev/null +++ b/helloworld-singleton/README.html @@ -0,0 +1,63 @@ + + + helloworld-singleton: Helloworld Using a Singleton EJB + + + +

helloworld-singleton: Helloworld Using a Singleton EJB

+

Author: Serge Pagop
+Level: Beginner
+Technologies: EJB, Singleton
+Summary: The helloworld-singleton quickstart demonstrates an EJB Singleton Bean that is instantiated once and maintains state for the life of the session.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld-singleton quickstart demonstrates the use of an EJB Singleton Bean in Red Hat JBoss Enterprise Application Platform. It is instantiated once and maintains its state for the life of the session.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-singleton.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/helloworld-singleton/.

+

This example demonstrates a singleton session bean that maintains state information for 2 variables: Increment A and Increment B.

+

A counter is incremented when you click on the link to the variable name. If you close and restart your browser, or if you have multiple browsers, you can see that the counter always increments the last value. These values are maintained until you restart the server.

+

To test the singleton bean, click on either Increment A or Increment B. The result page will give you the current value of the variable.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/helloworld-singleton/README.md b/helloworld-singleton/README.md index 0f65d79521..5f8b8f8618 100644 --- a/helloworld-singleton/README.md +++ b/helloworld-singleton/README.md @@ -4,48 +4,48 @@ Author: Serge Pagop Level: Beginner Technologies: EJB, Singleton Summary: The `helloworld-singleton` quickstart demonstrates an *EJB Singleton Bean* that is instantiated once and maintains state for the life of the session. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld-singleton` quickstart demonstrates the use of an *EJB Singleton Bean* in ${product.name.full}. It is instantiated once and maintains its state for the life of the session. +The `helloworld-singleton` quickstart demonstrates the use of an *EJB Singleton Bean* in Red Hat JBoss Enterprise Application Platform. It is instantiated once and maintains its state for the life of the session. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/helloworld-singleton.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . This example demonstrates a singleton session bean that maintains state information for 2 variables: `Increment A` and `Increment B`. @@ -56,7 +56,7 @@ To test the singleton bean, click on either `Increment A` or `Increment B`. The ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -65,7 +65,7 @@ To test the singleton bean, click on either `Increment A` or `Increment B`. The ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/helloworld-singleton/pom.xml b/helloworld-singleton/pom.xml index a66515bfbe..7e0a3a9d77 100644 --- a/helloworld-singleton/pom.xml +++ b/helloworld-singleton/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-singleton diff --git a/helloworld-ssl/README.html b/helloworld-ssl/README.html new file mode 100644 index 0000000000..f09bb7afac --- /dev/null +++ b/helloworld-ssl/README.html @@ -0,0 +1,202 @@ + + + helloworld-ssl: JBoss EAP Server Side SSL Configuration Example + + + +

helloworld-ssl: JBoss EAP Server Side SSL Configuration Example

+

Author: Giriraj Sharma, Stefan Guilhen
+Level: Beginner
+Technologies: SSL, Undertow
+Summary: The helloworld-ssl quickstart is a basic example that demonstrates server side SSL configuration in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

This helloworld-ssl quickstart demonstrates the configuration of SSL in Red Hat JBoss Enterprise Application Platform.

+

This quickstart shows how to configure JBoss EAP to enable TLS/SSL configuration for the new undertow web subsystem.

+

Before you run this example, you must create certificates and configure the server to use SSL.

+

System Requirements

+

The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the Red Hat JBoss Enterprise Application Platform Documentation Getting Started Guide located on the Customer Portal.

+

You can also use JBoss Developer Studio or Eclipse to run the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Generate a Keystore and Self-signed Certificate

+
    +
  1. Open a command line and navigate to the JBoss EAP server configuration directory: +
    For Linux:   standalone/configuration
+For Windows: standalone\configuration
+
    +
    2. +
  2. Create a certificate for your server using the following command: +
    $>keytool -genkey -alias mycert -keyalg RSA -sigalg MD5withRSA -keystore server.keystore -storepass secret -keypass secret -validity 9999
+
+What is your first and last name?
+   [Unknown]:  localhost
+What is the name of your organizational unit?
+   [Unknown]:  wildfly
+What is the name of your organization?
+   [Unknown]:  jboss
+What is the name of your City or Locality?
+   [Unknown]:  Raleigh
+What is the name of your State or Province?
+   [Unknown]:  Carolina
+What is the two-letter country code for this unit?
+   [Unknown]:  US
+Is CN=localhost, OU=wildfly, O=jboss, L=Raleigh, ST=Carolina, C=US correct?
+   [no]:  yes
+
    +

    Make sure to put your desired "hostname" into the "first and last name" field, otherwise you might run into issues while permanently accepting this certificate as an exception in some browsers. Chrome does not have an issue with that though.

    +
    3. +
+

Configure the Server

+

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

+

You configure the SSL context by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-ssl.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-ssl.cli file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-ssl.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-ssl.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    5. +
  5. +

    Stop the JBoss EAP server.

    +
    6. +
+

Now you're ready to connect to the SSL port of your instance https://localhost:8443/. Note, that you get the privacy error as the server certificate is self-signed. If you need to use a fully signed certificate you mostly get a PEM file from the Certificate Authority. In such a case, you need to import the PEM into the keystore.

+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. +

    The following key-store was added to the elytron subsystem:

    +
    <key-stores>
+    <key-store name="qsKeyStore">
+        <credential-reference clear-text="secret"/>
+        <implementation type="JKS"/>
+        <file path="server.keystore" relative-to="jboss.server.config.dir"/>
+    </key-store>
+</key-stores>
+
    +
    2. +
  2. +

    The following key-manager was added to the elytron subsystem:

    +
    <key-managers>
+    <key-manager name="qsKeyManager" key-store="qsKeyStore">
+        <credential-reference clear-text="secret"/>
+    </key-manager>
+</key-managers>
+
    +
    3. +
  3. +

    The following ssl-context was added to the elytron subsystem:

    +
    <server-ssl-contexts>
+    <server-ssl-context name="qsSSLContext" protocols="TLSv1.2" key-manager="qsKeyManager"/>
+</server-ssl-contexts>
+
    +
    4. +
  4. +

    The https-listener in the undertow subsystem was changed to reference the qsSSLContext ssl-context:

    +
    <https-listener name="https" socket-binding="https" ssl-context="qsSSLContext" enable-http2="true"/>
+
    +
    5. +
+

Test the Server SSL Configuration

+

To test the SSL configuration, access: https://localhost:8443

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the web profile: +
    For Linux:   bin/standalone.sh
+For Windows: bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+

NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See Build and Deploy the Quickstarts for complete instructions and additional options.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of one of the quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-ssl.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: https://localhost:8443/helloworld-ssl/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss Server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can restore the original server configuration by running the restore-configuration.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli
+
    +

    This script reverts the changes made to the undertow subsystem and it also removes the ssl-context, key-manager and key-store from the elytron subsystem. You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    3. +
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Remove the keystore created for this quickstart

+
    +
  1. Open a command line and navigate to the JBoss EAP server configuration directory: +
    For Linux:   standalone/configuration
+For Windows: standalone\configuration
+
    +
    2. +
  2. Remove the keystore generated for this quickstart.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+ +

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources        
+
+ + \ No newline at end of file diff --git a/helloworld-ssl/README.md b/helloworld-ssl/README.md index 4bc33206c5..1c45cbca44 100644 --- a/helloworld-ssl/README.md +++ b/helloworld-ssl/README.md @@ -1,38 +1,38 @@ -# helloworld-ssl: ${product.name} Server Side SSL Configuration Example +# helloworld-ssl: JBoss EAP Server Side SSL Configuration Example Author: Giriraj Sharma, Stefan Guilhen Level: Beginner Technologies: SSL, Undertow -Summary: The `helloworld-ssl` quickstart is a basic example that demonstrates server side SSL configuration in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `helloworld-ssl` quickstart is a basic example that demonstrates server side SSL configuration in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -This `helloworld-ssl` quickstart demonstrates the configuration of *SSL* in *${product.name.full}*. +This `helloworld-ssl` quickstart demonstrates the configuration of *SSL* in *Red Hat JBoss Enterprise Application Platform*. -This quickstart shows how to configure ${product.name} to enable TLS/SSL configuration for the new `undertow` web subsystem. +This quickstart shows how to configure JBoss EAP to enable TLS/SSL configuration for the new `undertow` web subsystem. Before you run this example, you must create certificates and configure the server to use SSL. ## System Requirements -The applications these projects produce are designed to be run on ${product.name.full} ${product.version} or later. +The applications these projects produce are designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build these projects is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on how to install and run JBoss, see the [${product.name.full} Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. +To run these quickstarts with the provided build scripts, you need the JBoss EAP distribution ZIP. For information on how to install and run JBoss, see the [Red Hat JBoss Enterprise Application Platform Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal. You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) to run the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Generate a Keystore and Self-signed Certificate -1. Open a command line and navigate to the ${product.name} server `configuration` directory: +1. Open a command line and navigate to the JBoss EAP server `configuration` directory: For Linux: standalone/configuration For Windows: standalone\configuration @@ -64,32 +64,32 @@ These steps assume you are running the server in standalone mode and using the d You configure the SSL context by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-ssl.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-ssl.cli` file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-ssl.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-ssl.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-ssl.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-ssl.cli You should see the following result when you run the script: The batch executed successfully process-state: reload-required -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. Now you're ready to connect to the SSL port of your instance https://localhost:8443/. Note, that you get the privacy error as the server certificate is self-signed. If you need to use a fully signed certificate you mostly get a PEM file from the Certificate Authority. In such a case, you need to import the PEM into the keystore. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following `key-store` was added to the `elytron` subsystem: @@ -125,7 +125,7 @@ To test the SSL configuration, access: ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the web profile: For Linux: bin/standalone.sh @@ -135,17 +135,17 @@ To test the SSL configuration, access: _NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._ -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of one of the quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/helloworld-ssl.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive @@ -161,14 +161,14 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-configuration.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-configuration.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli This script reverts the changes made to the `undertow` subsystem and it also removes the `ssl-context`, `key-manager` and `key-store` from the `elytron` subsystem. You should see the following result when you run the script: @@ -177,12 +177,12 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Remove the keystore created for this quickstart -1. Open a command line and navigate to the ${product.name} server `configuration` directory: +1. Open a command line and navigate to the JBoss EAP server `configuration` directory: For Linux: standalone/configuration For Windows: standalone\configuration @@ -190,9 +190,9 @@ You can restore the original server configuration by running the `restore-confi ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -* Be sure to configure the server by running the JBoss CLI commands as described above under [Configure the ${product.name} Server](#configure-the-server). Stop the server at the end of that step. +* Be sure to configure the server by running the JBoss CLI commands as described above under [Configure the JBoss EAP Server](#configure-the-server). Stop the server at the end of that step. * Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/helloworld-ssl/pom.xml b/helloworld-ssl/pom.xml index 003607bca7..89cb624536 100644 --- a/helloworld-ssl/pom.xml +++ b/helloworld-ssl/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-ssl diff --git a/helloworld-ws/README.html b/helloworld-ws/README.html new file mode 100644 index 0000000000..9c7f58469f --- /dev/null +++ b/helloworld-ws/README.html @@ -0,0 +1,98 @@ + + + helloworld-ws: Hello World JAX-WS Web Service + + + +

helloworld-ws: Hello World JAX-WS Web Service

+

Author: Lee Newson
+Level: Beginner
+Technologies: JAX-WS
+Summary: The helloworld-ws quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses JAX-WS to say Hello.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld-ws quickstart demonstrates the use of JAX-WS in Red Hat JBoss Enterprise Application Platform as a simple Hello World application.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld-ws.war to the running instance of the server.

    +
    5. +
  5. Review the server log to see useful information about the deployed web service endpoint. +
    JBWS024061: Adding service endpoint metadata: id=org.jboss.as.quickstarts.wshelloworld.HelloWorldServiceImpl
+ address=http://localhost:8080/helloworld-ws/HelloWorldService
+ implementor=org.jboss.as.quickstarts.wshelloworld.HelloWorldServiceImpl
+ serviceName={http://www.jboss.org/eap/quickstarts/wshelloworld/HelloWorld}HelloWorldService
+ portName={http://www.jboss.org/eap/quickstarts/wshelloworld/HelloWorld}HelloWorld
+ annotationWsdlLocation=null
+ wsdlLocationOverride=null
+ mtomEnabled=false
+
    +
    6. +
+

Access the Application

+

You can verify that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/helloworld-ws/HelloWorldService?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Client Tests Using Arquillian

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

The following expected output should appear. The output shows what was said to the Web Service by the client and the responses it received.

+
-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.jboss.as.quickstarts.wshelloworld.ClientArqTest
+[Client] Requesting the WebService to say Hello.
+[WebService] Hello World!
+[Client] Requesting the WebService to say Hello to John.
+[WebService] Hello John!
+[Client] Requesting the WebService to say Hello to John, Mary and Mark.
+[WebService] Hello John, Mary & Mark!
+Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.988 sec
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

When you deploy this quickstart, you are presented with a window that explains there is no user interface for this quickstart and directs you to click on a link to view the WSDL definition. However, the Eclipse browser does not support the display of WSDL definitions. Instead, open an external browser and access the following URL: http://localhost:8080/helloworld-ws/HelloWorldService?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + + \ No newline at end of file diff --git a/helloworld-ws/README.md b/helloworld-ws/README.md index efb1a66be2..0e85404edb 100644 --- a/helloworld-ws/README.md +++ b/helloworld-ws/README.md @@ -4,47 +4,47 @@ Author: Lee Newson Level: Beginner Technologies: JAX-WS Summary: The `helloworld-ws` quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses *JAX-WS* to say Hello. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld-ws` quickstart demonstrates the use of *JAX-WS* in ${product.name.full} as a simple Hello World application. +The `helloworld-ws` quickstart demonstrates the use of *JAX-WS* in Red Hat JBoss Enterprise Application Platform as a simple Hello World application. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/helloworld-ws.war` to the running instance of the server. 5. Review the server log to see useful information about the deployed web service endpoint. JBWS024061: Adding service endpoint metadata: id=org.jboss.as.quickstarts.wshelloworld.HelloWorldServiceImpl - address=http://localhost:8080/${project.artifactId}/HelloWorldService + address=http://localhost:8080/helloworld-ws/HelloWorldService implementor=org.jboss.as.quickstarts.wshelloworld.HelloWorldServiceImpl serviceName={http://www.jboss.org/eap/quickstarts/wshelloworld/HelloWorld}HelloWorldService portName={http://www.jboss.org/eap/quickstarts/wshelloworld/HelloWorld}HelloWorld @@ -55,12 +55,12 @@ In the following instructions, replace `${jboss.home.name}` with the actual path ## Access the Application -You can verify that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. +You can verify that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -71,13 +71,13 @@ You can verify that the Web Service is running and deployed correctly by accessi This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -98,9 +98,9 @@ The following expected output should appear. The output shows what was said to t ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -When you deploy this quickstart, you are presented with a window that explains there is no user interface for this quickstart and directs you to click on a link to view the WSDL definition. However, the Eclipse browser does not support the display of WSDL definitions. Instead, open an external browser and access the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. +When you deploy this quickstart, you are presented with a window that explains there is no user interface for this quickstart and directs you to click on a link to view the WSDL definition. However, the Eclipse browser does not support the display of WSDL definitions. Instead, open an external browser and access the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. ## Debug the Application diff --git a/helloworld-ws/pom.xml b/helloworld-ws/pom.xml index 025a01a01e..b5e1e3ef56 100644 --- a/helloworld-ws/pom.xml +++ b/helloworld-ws/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld-ws diff --git a/helloworld/README.html b/helloworld/README.html new file mode 100644 index 0000000000..df47753478 --- /dev/null +++ b/helloworld/README.html @@ -0,0 +1,60 @@ + + + helloworld: Helloworld Example + + + +

helloworld: Helloworld Example

+

Author: Pete Muir
+Level: Beginner
+Technologies: CDI, Servlet
+Summary: The helloworld quickstart demonstrates the use of CDI and Servlet 3 and is a good starting point to verify JBoss EAP is configured correctly.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The helloworld quickstart demonstrates the use of CDI and Servlet 3 in Red Hat JBoss Enterprise Application Platform 7.1.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.1.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   bin/standalone.sh
+For Windows: bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/helloworld.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/helloworld/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/helloworld/README.md b/helloworld/README.md index 79eab8e43d..dd564ec762 100644 --- a/helloworld/README.md +++ b/helloworld/README.md @@ -3,30 +3,30 @@ Author: Pete Muir Level: Beginner Technologies: CDI, Servlet -Summary: The `helloworld` quickstart demonstrates the use of *CDI* and *Servlet 3* and is a good starting point to verify ${product.name} is configured correctly. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `helloworld` quickstart demonstrates the use of *CDI* and *Servlet 3* and is a good starting point to verify JBoss EAP is configured correctly. +Target Product: JBoss EAP +Source: ## What is it? -The `helloworld` quickstart demonstrates the use of *CDI* and *Servlet 3* in ${product.name.full} ${product.version}. +The `helloworld` quickstart demonstrates the use of *CDI* and *Servlet 3* in Red Hat JBoss Enterprise Application Platform 7.1. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.1.1 or later. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.1.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: For Linux: bin/standalone.sh @@ -35,23 +35,23 @@ In the following instructions, replace `${jboss.home.name}` with the actual path ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/helloworld.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -60,7 +60,7 @@ The application will be running at the following URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml helloworld diff --git a/hibernate/README.html b/hibernate/README.html new file mode 100644 index 0000000000..633746824d --- /dev/null +++ b/hibernate/README.html @@ -0,0 +1,90 @@ + + + hibernate: How to Use Hibernate 5 in an Application + + + +

hibernate: How to Use Hibernate 5 in an Application

+

Author: Madhumita Sadhukhan
+Level: Intermediate
+Technologies: Hibernate
+Summary: The hibernate quickstart demonstrates how to use Hibernate ORM 5 API over JPA, using Hibernate-Core and Hibernate Bean Validation, and EJB.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The hibernate quickstart is based upon the kitchensink example, but demonstrates how to use Hibernate Object/Relational Mapping (ORM) 5 over JPA in Red Hat JBoss Enterprise Application Platform.

+

This project is setup to allow you to create a compliant Java EE 7 application using JSF, CDI, EJB, JPA , Hibernate-Core and Hibernate Bean Validation. It includes a persistence unit associated with Hibernate session and some sample persistence and transaction code to help you with database access in enterprise Java.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add the Correct Dependencies

+

JBoss EAP provides Hibernate 5 and JPA support.

+

If you use Hibernate 5 packaged within JBoss EAP, you will need to first import the JPA API.

+

This quickstart demonstrates usage of Hibernate Session and Hibernate Validators.

+

If you look at the pom.xml file in the root of the hibernate quickstart directory, you will see that the dependencies for the Hibernate modules have been added with the scope as provided. For example:

+
  <dependency>
+     <groupId>org.hibernate</groupId>
+     <artifactId>hibernate-validator</artifactId>
+      <scope>provided</scope>
+     <exclusions>
+        <exclusion>
+           <groupId>org.slf4j</groupId>
+           <artifactId>slf4j-api</artifactId>
+        </exclusion>
+     </exclusions>
+  </dependency>
+
+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/hibernate.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/hibernate/.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+

You may see the following message when you run the command. It indicates the source is not provided in the third-party antlr JAR.

+
    [INFO] The following files have NOT been resolved:
+    [INFO]    antlr:antlr:jar:sources:2.7.7:provided
+
+ + \ No newline at end of file diff --git a/hibernate/README.md b/hibernate/README.md index 803c75a5d8..f88cd12d1c 100644 --- a/hibernate/README.md +++ b/hibernate/README.md @@ -4,36 +4,36 @@ Author: Madhumita Sadhukhan Level: Intermediate Technologies: Hibernate Summary: The `hibernate` quickstart demonstrates how to use Hibernate ORM 5 API over JPA, using Hibernate-Core and Hibernate Bean Validation, and EJB. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `hibernate` quickstart is based upon the [kitchensink](../kitchensink/README.md) example, but demonstrates how to use Hibernate Object/Relational Mapping (ORM) 5 over JPA in ${product.name.full}. +The `hibernate` quickstart is based upon the [kitchensink](../kitchensink/README.md) example, but demonstrates how to use Hibernate Object/Relational Mapping (ORM) 5 over JPA in Red Hat JBoss Enterprise Application Platform. This project is setup to allow you to create a compliant Java EE 7 application using JSF, CDI, EJB, JPA , Hibernate-Core and Hibernate Bean Validation. It includes a persistence unit associated with Hibernate session and some sample persistence and transaction code to help you with database access in enterprise Java. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add the Correct Dependencies -${product.name} provides Hibernate 5 and JPA support. +JBoss EAP provides Hibernate 5 and JPA support. -If you use Hibernate 5 packaged within ${product.name}, you will need to first import the JPA API. +If you use Hibernate 5 packaged within JBoss EAP, you will need to first import the JPA API. This quickstart demonstrates usage of Hibernate Session and Hibernate Validators. @@ -55,27 +55,27 @@ For example: ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/hibernate.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Server Log: Expected Warnings and Errors @@ -89,7 +89,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -98,7 +98,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/hibernate/pom.xml b/hibernate/pom.xml index f0fa1470cf..f6afac5ab7 100644 --- a/hibernate/pom.xml +++ b/hibernate/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml hibernate diff --git a/inter-app/README.html b/inter-app/README.html new file mode 100644 index 0000000000..80fdfa8d42 --- /dev/null +++ b/inter-app/README.html @@ -0,0 +1,91 @@ + + + inter-app: Communicate Between Two Applications Using EJB and CDI + + + +

inter-app: Communicate Between Two Applications Using EJB and CDI

+

Author: Pete Muir
+Level: Advanced
+Technologies: EJB, CDI, JSF
+Summary: The inter-app quickstart shows you how to use a shared API JAR and an EJB to provide inter-application communication between two WAR deployments.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The inter-app quickstart shows you how to easily communicate between two modular deployments to Red Hat JBoss Enterprise Application Platform. Two WARs, with a shared API JAR, are deployed to the application server. EJB is used to provide inter-application communication, with EJB beans alised to CDI beans, making the inter-application communication transparent to clients of the bean.

+

CDI only provides intra-application injection within a top level deployment, for example, an EAR, WAR, or JAR. This improves performance of the application server, as to satisfy an injection point all possible candidates have to be scanned / analyzed. If inter-app injection was supported by CDI, performance would scale according to the number of deployments you have (the more deployments in the running system, the slower the deployment). Java EE injection uses unique JNDI names for the wiring, so each injection point is O(1). The approach shown here combines the two approaches such that you limit the name based wiring to one location in your code, and the main consumers of components can use CDI injection to reference these name wired components. For the name approach to work though, you still need to publish instances, and EJB singletons allow you to do that with just one extra annotation.

+

In all, the project has three modules:

+
    +
  • inter-app-app-shared.jar - this module contains the interfaces which define the contract between the beans exposed by the WARs. It is deployed as an EJB JAR module because Eclipse Web Tools Platform can not deploy simple JARs.
    • +
  • inter-app-app-appA.war - the first WAR, whiches exposes an EJB singleton, and a simple UI that allows you to read the value set on the bean in appB
    • +
  • inter-app-app-appB.war - the second WAR, whiches exposes an EJB singleton, and a simple UI that allows you to read the value set on the bean in appA
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. This will deploy shared/target/inter-app-app-shared.jar, appA/target/inter-app-app-appA.war and appB/target/inter-app-app-appB.war to the running instance of the server.
    5. +
+

Access the Application

+

Access the running application in a browser at the following URLs:

+ +

You are presented with a form that allows you to set the value on the bean in the other application, as well as display of the value on this application's bean. Enter a new value and press Update and Send! to update the value on the other application. Do the same on the other application, and hit the button again on the first application. You should see the values shared between the applications.

+

Undeploy the Archive

+

This quickstart undeploys differently than some of the others because of the WAR and JAR interdependencies.

+

When you are finished testing, follow these steps to undeploy the archives:

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to undeploy the inter-app-appA.war and inter-app-appB.war archives. +
    mvn wildfly:undeploy -pl appA,appB
+
    +
    4. +
  4. +

    Type the following command to undeploy the inter-app-shared.jar archive.

    +
    mvn wildfly:undeploy -pl shared
+
    +
    5. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart consists of multiple projects containing interdependencies on each other, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+
    +
  1. In the Servers tab, right-click on the JBoss EAP server and choose Start.
    2. +
  2. Deploy the projects in one of the following ways. +
      +
    • Drag and Drop mode: Click to multi-select the inter-app-app-shared, inter-app-app-appA, and inter-app-app-appB projects, then drag and drop them on the running JBoss EAP server. This deploys the projects to the server without opening the browser.
      • +
    • Batch mode: In the Servers tab, right-click on the server and choose Add and Remove. If the inter-app-app-shared, inter-app-app-appA, and inter-app-app-appB projects are the only projects in the list, click Add All. Otherwise, use multi-select to select them and click Add. Then click Finish.
      • +
    +
    3. +
  3. Right-click on the inter-app-app-appA project and choose Run As --> Run on Server. A browser window appears that accesses the running appA application.
    4. +
  4. Right-click on the inter-app-app-appB project and choose Run As --> Run on Server. A browser window appears that accesses the running appB application.
    5. +
  5. To undeploy the inter-app-app-appBproject, right-click on it and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    6. +
  6. To undeploy the inter-app-app-appAproject, right-click on it and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    7. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/inter-app/README.md b/inter-app/README.md index ae2c788535..0001a8de8f 100644 --- a/inter-app/README.md +++ b/inter-app/README.md @@ -4,58 +4,58 @@ Author: Pete Muir Level: Advanced Technologies: EJB, CDI, JSF Summary: The `inter-app` quickstart shows you how to use a shared API JAR and an EJB to provide inter-application communication between two WAR deployments. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `inter-app` quickstart shows you how to easily communicate between two modular deployments to ${product.name.full}. Two WARs, with a shared API JAR, are deployed to the application server. EJB is used to provide inter-application communication, with EJB beans alised to CDI beans, making the inter-application communication transparent to clients of the bean. +The `inter-app` quickstart shows you how to easily communicate between two modular deployments to Red Hat JBoss Enterprise Application Platform. Two WARs, with a shared API JAR, are deployed to the application server. EJB is used to provide inter-application communication, with EJB beans alised to CDI beans, making the inter-application communication transparent to clients of the bean. CDI only provides intra-application injection within a top level deployment, for example, an EAR, WAR, or JAR. This improves performance of the application server, as to satisfy an injection point all possible candidates have to be scanned / analyzed. If inter-app injection was supported by CDI, performance would scale according to the number of deployments you have (the more deployments in the running system, the slower the deployment). Java EE injection uses unique JNDI names for the wiring, so each injection point is O(1). The approach shown here combines the two approaches such that you limit the name based wiring to one location in your code, and the main consumers of components can use CDI injection to reference these name wired components. For the name approach to work though, you still need to publish instances, and EJB singletons allow you to do that with just one extra annotation. In all, the project has three modules: -* `${project.artifactId}-app-shared.jar` - this module contains the interfaces which define the contract between the beans exposed by the WARs. It is deployed as an EJB JAR module because Eclipse Web Tools Platform can not deploy simple JARs. -* `${project.artifactId}-app-appA.war` - the first WAR, whiches exposes an EJB singleton, and a simple UI that allows you to read the value set on the bean in appB -* `${project.artifactId}-app-appB.war` - the second WAR, whiches exposes an EJB singleton, and a simple UI that allows you to read the value set on the bean in appA +* `inter-app-app-shared.jar` - this module contains the interfaces which define the contract between the beans exposed by the WARs. It is deployed as an EJB JAR module because Eclipse Web Tools Platform can not deploy simple JARs. +* `inter-app-app-appA.war` - the first WAR, whiches exposes an EJB singleton, and a simple UI that allows you to read the value set on the bean in appB +* `inter-app-app-appB.war` - the second WAR, whiches exposes an EJB singleton, and a simple UI that allows you to read the value set on the bean in appA ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `shared/target/${project.artifactId}-app-shared.jar`, `appA/target/${project.artifactId}-app-appA.war` and `appB/target/${project.artifactId}-app-appB.war` to the running instance of the server. +4. This will deploy `shared/target/inter-app-app-shared.jar`, `appA/target/inter-app-app-appA.war` and `appB/target/inter-app-app-appB.war` to the running instance of the server. ## Access the Application Access the running application in a browser at the following URLs: -* -* +* +* You are presented with a form that allows you to set the value on the bean in the other application, as well as display of the value on this application's bean. Enter a new value and press `Update and Send!` to update the value on the other application. Do the same on the other application, and hit the button again on the first application. You should see the values shared between the applications. @@ -66,7 +66,7 @@ This quickstart undeploys differently than some of the others because of the WAR When you are finished testing, follow these steps to undeploy the archives: -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to undeploy the `inter-app-appA.war` and `inter-app-appB.war` archives. @@ -79,18 +79,18 @@ When you are finished testing, follow these steps to undeploy the archives: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). This quickstart consists of multiple projects containing interdependencies on each other, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. -1. In the `Servers` tab, right-click on the ${product.name} server and choose `Start`. +1. In the `Servers` tab, right-click on the JBoss EAP server and choose `Start`. 2. Deploy the projects in one of the following ways. - * `Drag and Drop` mode: Click to multi-select the `${project.artifactId}-app-shared`, `${project.artifactId}-app-appA`, and `${project.artifactId}-app-appB` projects, then drag and drop them on the running ${product.name} server. This deploys the projects to the server without opening the browser. - * `Batch` mode: In the `Servers` tab, right-click on the server and choose `Add and Remove`. If the `${project.artifactId}-app-shared`, `${project.artifactId}-app-appA`, and `${project.artifactId}-app-appB` projects are the only projects in the list, click `Add All`. Otherwise, use multi-select to select them and click `Add`. Then click `Finish`. -3. Right-click on the `${project.artifactId}-app-appA` project and choose `Run As` --> `Run on Server`. A browser window appears that accesses the running `appA` application. -4. Right-click on the `${project.artifactId}-app-appB` project and choose `Run As` --> `Run on Server`. A browser window appears that accesses the running `appB` application. -5. To undeploy the `${project.artifactId}-app-appB`project, right-click on it and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. -6. To undeploy the `${project.artifactId}-app-appA`project, right-click on it and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. + * `Drag and Drop` mode: Click to multi-select the `inter-app-app-shared`, `inter-app-app-appA`, and `inter-app-app-appB` projects, then drag and drop them on the running JBoss EAP server. This deploys the projects to the server without opening the browser. + * `Batch` mode: In the `Servers` tab, right-click on the server and choose `Add and Remove`. If the `inter-app-app-shared`, `inter-app-app-appA`, and `inter-app-app-appB` projects are the only projects in the list, click `Add All`. Otherwise, use multi-select to select them and click `Add`. Then click `Finish`. +3. Right-click on the `inter-app-app-appA` project and choose `Run As` --> `Run on Server`. A browser window appears that accesses the running `appA` application. +4. Right-click on the `inter-app-app-appB` project and choose `Run As` --> `Run on Server`. A browser window appears that accesses the running `appB` application. +5. To undeploy the `inter-app-app-appB`project, right-click on it and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +6. To undeploy the `inter-app-app-appA`project, right-click on it and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/inter-app/appA/pom.xml b/inter-app/appA/pom.xml index 6a6aafccf6..e693fd0fe5 100644 --- a/inter-app/appA/pom.xml +++ b/inter-app/appA/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts inter-app - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/inter-app/appB/pom.xml b/inter-app/appB/pom.xml index 4d02833759..8235e4a9be 100644 --- a/inter-app/appB/pom.xml +++ b/inter-app/appB/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts inter-app - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/inter-app/pom.xml b/inter-app/pom.xml index b6f5ce16e7..24a584dc40 100644 --- a/inter-app/pom.xml +++ b/inter-app/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml inter-app diff --git a/inter-app/shared/pom.xml b/inter-app/shared/pom.xml index 67d176980d..e303106208 100644 --- a/inter-app/shared/pom.xml +++ b/inter-app/shared/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts inter-app - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/jaxrs-client/README.html b/jaxrs-client/README.html new file mode 100644 index 0000000000..f10e1cbe49 --- /dev/null +++ b/jaxrs-client/README.html @@ -0,0 +1,134 @@ + + + jaxrs-client: JAX-RS Client API example + + + +

jaxrs-client: JAX-RS Client API example

+

Author: Rafael Benevides
+Level: Beginner
+Technologies: JAX-RS
+Summary: The jaxrs-client quickstart demonstrates JAX-RS Client API, which interacts with a JAX-RS Web service that runs on JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jaxrs-client quickstart demonstrates the JAX-RS Client API which interacts with a JAX-RS Web service.

+

This client "calls" many POST, GET, DELETE operations using different ways: synchronized, asynchronous, delayed and filtered invocations.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn package wildfly:deploy
+
    +
    4. +
  4. This will deploy target/jaxrs-client.war to the running instance of the server.
    5. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+
    -------------------------------------------------------
+     T E S T S
+    -------------------------------------------------------
+    Running org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest
+    Dec 29, 2014 3:34:44 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest requestResponseFiltersTest
+    INFO: ### Testing Request and Response Filters ###
+    Dec 29, 2014 3:34:44 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest requestResponseFiltersTest
+    INFO: dropping all contacts
+    Dec 29, 2014 3:34:45 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest requestResponseFiltersTest
+    INFO: Invoking create new contact using a ClientRequestFilter
+    Dec 29, 2014 3:34:45 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest requestResponseFiltersTest
+    INFO: Invoking list all contacts using a ClientResponseFilter
+    Dec 29, 2014 3:34:45 PM org.jboss.as.quickstarts.jaxrsclient.test.LogResponseFilter filter
+    INFO: Date: Mon Dec 29 15:34:45 BRST 2014- Status: 200
+    Dec 29, 2014 3:34:45 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest delayedInvocationTest
+    INFO: ### Testing Delayed invocaton ###
+    Dec 29, 2014 3:34:45 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest delayedInvocationTest
+    INFO: dropping all contacts
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest delayedInvocationTest
+    INFO: Creating a new contact invocation
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest delayedInvocationTest
+    INFO: Creating list all contacts invocation
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest delayedInvocationTest
+    INFO: invoking the new contact
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest delayedInvocationTest
+    INFO: invoking list all contacts ASYNC
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest asyncCrudTest
+    INFO: ### CRUD tests  ASYNC ###
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest asyncCrudTest
+    INFO: dropping all contacts ASYNC
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest asyncCrudTest
+    INFO: creating a new contact ASYNC
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest asyncCrudTest
+    INFO: delete a contact by id ASYNC
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest asyncCrudTest
+    INFO: fetching all contacts ASYNC
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest invocationCallBackTest
+    INFO: ### Testing invocation callback ###
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest invocationCallBackTest
+    INFO: dropping all contacts
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest invocationCallBackTest
+    INFO: Creating a InvocationCallback
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest invocationCallBackTest
+    INFO: Invoking a service using the InvocationCallback
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest cruedTest
+    INFO: ### CRUD tests ###
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest cruedTest
+    INFO: dropping all contacts
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest cruedTest
+    INFO: creating a new contact
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest cruedTest
+    INFO: fetching a contact by id
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest cruedTest
+    INFO: fetching all contacts
+    Dec 29, 2014 3:34:46 PM org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest cruedTest
+    INFO: delete a contact by id
+    Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.51 sec - in org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientTest
+
+    Results :
+
+    Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

To run the tests in Red Hat JBoss Developer Studio:

+
    +
  1. You must first set the active Maven profile in project properties to be either arq-managed for running on managed server or arq-remote for running on remote server.
    2. +
  2. Then, to run the tests, right click on the project or individual classes and select Run As --> JUnit Test in the context menu.
    3. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/jaxrs-client/README.md b/jaxrs-client/README.md index 3ba97c182c..2b07840ef6 100644 --- a/jaxrs-client/README.md +++ b/jaxrs-client/README.md @@ -3,9 +3,9 @@ Author: Rafael Benevides Level: Beginner Technologies: JAX-RS -Summary: The `jaxrs-client` quickstart demonstrates JAX-RS Client API, which interacts with a JAX-RS Web service that runs on ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `jaxrs-client` quickstart demonstrates JAX-RS Client API, which interacts with a JAX-RS Web service that runs on JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? @@ -17,28 +17,28 @@ This client "calls" many POST, GET, DELETE operations using different ways: sync ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/jaxrs-client.war` to the running instance of the server. @@ -46,13 +46,13 @@ All you need to build this project is ${build.requirements}. See [Configure Mave This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -123,7 +123,7 @@ You can also let Arquillian manage the ${product.name} server by using the `arq- ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -132,7 +132,7 @@ You can also let Arquillian manage the ${product.name} server by using the `arq- ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). To run the tests in Red Hat JBoss Developer Studio: diff --git a/jaxrs-client/pom.xml b/jaxrs-client/pom.xml index c32b67a086..c9a7e43626 100644 --- a/jaxrs-client/pom.xml +++ b/jaxrs-client/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jaxrs-client diff --git a/jaxws-addressing/README.html b/jaxws-addressing/README.html new file mode 100644 index 0000000000..50dc01ccde --- /dev/null +++ b/jaxws-addressing/README.html @@ -0,0 +1,105 @@ + + + jaxws-addressing: A WS-addressing JAX-WS Web Service + + + +

jaxws-addressing: A WS-addressing JAX-WS Web Service

+

Author: R Searls
+Level: Beginner
+Technologies: JAX-WS
+Summary: The jaxws-addressing quickstart is a working example of the web service using WS-Addressing.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jaxws-addressing quickstart demonstrates the use of JAX-WS in Red Hat JBoss Enterprise Application Platform as a simple WS-addressing application.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will create the jaxws-addressing-client.jar and deploy service/target/jaxws-addressing-service.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

You can check that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/jaxws-addressing/AddressingService?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.

+

Run the Client

+
    +
  1. +

    Make sure the service deployed properly.

    +
    2. +
  2. +

    Open a command prompt and navigate into the client directory of this quickstart.

    +
    cd client/
+
    +
    3. +
  3. Type this command to run the client. +
    mvn exec:java        
+
    +

    Note: This quickstart requires quickstart-parent artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command:

    +
    mvn clean install
+
    +
    4. +
  4. +

    You should see the following output in the client console.

    +
    Hello World!
+
    +
    5. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

For this quickstart, follow the special instructions to Deploy and Undeploy a Quickstart Containing Server and Java Client Projects

+
    +
  1. To build all of the artifacts, right-click on the jaxws-addressing parent project, and choose Run As --> Maven install.
    2. +
  2. To deploy the service: +
      +
    • Right-click on the jaxws-addressing-service subproject, and choose Run As --> Run on Server.
      • +
    • Choose the server and click Finish.
      • +
    • This starts the server and deploys the service to the server.
      • +
    • You also see the "404 - Not Found" error in the application window. This is because there is no user interface for this quickstart. You can ignore this error.
      • +
    +
    3. +
  3. To access the application: +
      +
    • Right-click on the jaxws-addressing-client subproject and choose Run As --> Java Application.
      • +
    • You should see the following message in the Console tab: +
      Hello World!
+
      +
      • +
    +
    4. +
  4. To undeploy the project, right-click on the jaxws-addressing parent project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/jaxws-addressing/README.md b/jaxws-addressing/README.md index 8a1e5f5154..deb7f2e4af 100644 --- a/jaxws-addressing/README.md +++ b/jaxws-addressing/README.md @@ -4,46 +4,46 @@ Author: R Searls Level: Beginner Technologies: JAX-WS Summary: The `jaxws-addressing` quickstart is a working example of the web service using WS-Addressing. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `jaxws-addressing` quickstart demonstrates the use of *JAX-WS* in ${product.name.full} as a simple WS-addressing application. +The `jaxws-addressing` quickstart demonstrates the use of *JAX-WS* in Red Hat JBoss Enterprise Application Platform as a simple WS-addressing application. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will create the `${project.artifactId}-client.jar` and deploy `service/target/${project.artifactId}-service.war` to the running instance of the server. +4. This will create the `jaxws-addressing-client.jar` and deploy `service/target/jaxws-addressing-service.war` to the running instance of the server. ## Access the Application -You can check that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. +You can check that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. ## Run the Client @@ -66,7 +66,7 @@ You can check that the Web Service is running and deployed correctly by accessin ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -75,22 +75,22 @@ You can check that the Web Service is running and deployed correctly by accessin ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). For this quickstart, follow the special instructions to [Deploy and Undeploy a Quickstart Containing Server and Java Client Projects](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-containing-server-and-java-client-projects) -1. To build all of the artifacts, right-click on the `${project.artifactId}` parent project, and choose `Run As` --> `Maven install`. +1. To build all of the artifacts, right-click on the `jaxws-addressing` parent project, and choose `Run As` --> `Maven install`. 2. To deploy the service: - * Right-click on the `${project.artifactId}-service` subproject, and choose `Run As` --> `Run on Server`. + * Right-click on the `jaxws-addressing-service` subproject, and choose `Run As` --> `Run on Server`. * Choose the server and click `Finish`. * This starts the server and deploys the service to the server. * You also see the "404 - Not Found" error in the application window. This is because there is no user interface for this quickstart. You can ignore this error. 3. To access the application: - * Right-click on the `${project.artifactId}-client` subproject and choose `Run As` --> `Java Application`. + * Right-click on the `jaxws-addressing-client` subproject and choose `Run As` --> `Java Application`. * You should see the following message in the `Console` tab: Hello World! -4. To undeploy the project, right-click on the `${project.artifactId}` parent project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +4. To undeploy the project, right-click on the `jaxws-addressing` parent project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/jaxws-addressing/client/pom.xml b/jaxws-addressing/client/pom.xml index 62048e9986..d114e583ed 100644 --- a/jaxws-addressing/client/pom.xml +++ b/jaxws-addressing/client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jaxws-addressing - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jaxws-addressing-client diff --git a/jaxws-addressing/pom.xml b/jaxws-addressing/pom.xml index ea7acea336..8b092c48af 100644 --- a/jaxws-addressing/pom.xml +++ b/jaxws-addressing/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jaxws-addressing diff --git a/jaxws-addressing/service/pom.xml b/jaxws-addressing/service/pom.xml index 4e5bba3815..2b64a3c0c4 100644 --- a/jaxws-addressing/service/pom.xml +++ b/jaxws-addressing/service/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jaxws-addressing - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jaxws-addressing-service diff --git a/jaxws-ejb/README.html b/jaxws-ejb/README.html new file mode 100644 index 0000000000..855a2345d1 --- /dev/null +++ b/jaxws-ejb/README.html @@ -0,0 +1,110 @@ + + + jaxws-ejb: An EJB JAX-WS Web Service + + + +

jaxws-ejb: An EJB JAX-WS Web Service

+

Author: R Searls
+Level: Beginner
+Technologies: JAX-WS
+Summary: The jaxws-ejb quickstart is a working example of the web service endpoint created from an EJB.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jaxws-ejb quickstart demonstrates the use of JAX-WS in Red Hat JBoss Enterprise Application Platform as a simple EJB web service application.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy service/target/jaxws-ejb-service.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

You can check that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/jaxws-ejb/EJB3Bean?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.

+

Run the Client

+
    +
  1. +

    Make sure the service deployed properly.

    +
    2. +
  2. +

    Open a command prompt and navigate into the client directory of this quickstart.

    +
    cd client/
+
    +
    3. +
  3. Type this command to run the client. +
    mvn exec:java        
+
    +

    Note: This quickstart requires quickstart-parent artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command:

    +
    mvn clean install
+
    +
    4. +
  4. +

    You should see the following output in the client console.

    +
    EJB3Bean returning: ejbClient calling
+
    +
    5. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

For this quickstart, follow the special instructions to Deploy and Undeploy a Quickstart Containing Server and Java Client Projects

+
    +
  1. To build all of the artifacts, right-click on the jaxws-ejb parent project, and choose Run As --> Maven install.
    2. +
  2. To deploy the service: +
      +
    • Right-click on the jaxws-ejb-service subproject, and choose Run As --> Run on Server.
      • +
    • Choose the server and click Finish.
      • +
    • This starts the server and deploys the service to the server.
      • +
    +
    3. +
  3. To access the application: +
      +
    • Right-click on the jaxws-ejb-client subproject and choose Run As --> Java Application.
      • +
    • You should see the following message in the Console tab: +
      EJB3Bean returning: ejbClient calling
+
      +
      • +
    +
    4. +
  4. To undeploy the project, right-click on the jaxws-ejb parent project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+

Note: You will see the following informational messages. This is because the source files for these JARs are not available in the Maven repository. The jaxws-ejb-service source files are available in the jaxws-ejb project.

+
[INFO] The following files have NOT been resolved:
+[INFO]    xerces:xercesImpl:jar:sources:2.9.1:compile
+[INFO]    com.wutka:dtdparser:jar:sources:1.21:compile
+[INFO]    org.jboss.quickstarts.eap:jaxws-ejb-service:jar:sources:7.0.0.GA:compile
+
+ + \ No newline at end of file diff --git a/jaxws-ejb/README.md b/jaxws-ejb/README.md index 03cc3ce7b1..675df0ca4c 100644 --- a/jaxws-ejb/README.md +++ b/jaxws-ejb/README.md @@ -4,47 +4,47 @@ Author: R Searls Level: Beginner Technologies: JAX-WS Summary: The `jaxws-ejb` quickstart is a working example of the web service endpoint created from an EJB. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `jaxws-ejb` quickstart demonstrates the use of *JAX-WS* in ${product.name.full} as a simple EJB web service application. +The `jaxws-ejb` quickstart demonstrates the use of *JAX-WS* in Red Hat JBoss Enterprise Application Platform as a simple EJB web service application. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `service/target/${project.artifactId}-service.war` to the running instance of the server. +4. This will deploy `service/target/jaxws-ejb-service.war` to the running instance of the server. ## Access the Application -You can check that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. +You can check that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. ## Run the Client @@ -67,7 +67,7 @@ You can check that the Web Service is running and deployed correctly by accessin ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -76,21 +76,21 @@ You can check that the Web Service is running and deployed correctly by accessin ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). For this quickstart, follow the special instructions to [Deploy and Undeploy a Quickstart Containing Server and Java Client Projects](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-containing-server-and-java-client-projects) -1. To build all of the artifacts, right-click on the `${project.artifactId}` parent project, and choose `Run As` --> `Maven install`. +1. To build all of the artifacts, right-click on the `jaxws-ejb` parent project, and choose `Run As` --> `Maven install`. 2. To deploy the service: - * Right-click on the `${project.artifactId}-service` subproject, and choose `Run As` --> `Run on Server`. + * Right-click on the `jaxws-ejb-service` subproject, and choose `Run As` --> `Run on Server`. * Choose the server and click `Finish`. * This starts the server and deploys the service to the server. 3. To access the application: - * Right-click on the `${project.artifactId}-client` subproject and choose `Run As` --> `Java Application`. + * Right-click on the `jaxws-ejb-client` subproject and choose `Run As` --> `Java Application`. * You should see the following message in the `Console` tab: EJB3Bean returning: ejbClient calling -4. To undeploy the project, right-click on the `${project.artifactId}` parent project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +4. To undeploy the project, right-click on the `jaxws-ejb` parent project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/jaxws-ejb/client/pom.xml b/jaxws-ejb/client/pom.xml index 2d3d78ed75..b12a0f9322 100644 --- a/jaxws-ejb/client/pom.xml +++ b/jaxws-ejb/client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jaxws-ejb - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA jaxws-ejb-client jar diff --git a/jaxws-ejb/pom.xml b/jaxws-ejb/pom.xml index 40515e30f3..1b0f365b95 100644 --- a/jaxws-ejb/pom.xml +++ b/jaxws-ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jaxws-ejb diff --git a/jaxws-ejb/service/pom.xml b/jaxws-ejb/service/pom.xml index d555c980a6..54fde4168f 100644 --- a/jaxws-ejb/service/pom.xml +++ b/jaxws-ejb/service/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jaxws-ejb - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA jaxws-ejb-service war diff --git a/jaxws-pojo/README.html b/jaxws-pojo/README.html new file mode 100644 index 0000000000..4e5f293ac1 --- /dev/null +++ b/jaxws-pojo/README.html @@ -0,0 +1,102 @@ + + + jaxws-pojo: An POJO JAX-WS Web Service + + + +

jaxws-pojo: An POJO JAX-WS Web Service

+

Author: R Searls
+Level: Beginner
+Technologies: JAX-WS
+Summary: The jaxws-pojo quickstart is a working example of the web service endpoint created from a POJO.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jaxws-pojo quickstart demonstrates the use of JAX-WS in Red Hat JBoss Enterprise Application Platform as a simple POJO web service application.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy service/target/jaxws-pojo-service.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

You can check that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/jaxws-pojo/JSEBean?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.

+

Run the Client

+
    +
  1. Make sure the service deployed properly.
    2. +
  2. Open a command prompt and navigate into the client directory of this quickstart. +
    cd client/
+
    +
    3. +
  3. +

    Type this command to run the client.

    +
    mvn exec:java        
+
    +

    Note: This quickstart requires quickstart-parent artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command:

    +
    mvn clean install
+
    +
    4. +
  4. +

    You should see the following response.

    +
    JSEBean pojo: pojoClient calling
+
    +
    5. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

For this quickstart, follow the special instructions to Deploy and Undeploy a Quickstart Containing Server and Java Client Projects

+
    +
  1. To build all of the artifacts, right-click on the jaxws-pojo parent project, and choose Run As --> Maven install.
    2. +
  2. To deploy the service: +
      +
    • Right-click on the jaxws-pojo-service subproject, and choose Run As --> Run on Server.
      • +
    • Choose the server and click Finish.
      • +
    • This starts the server and deploys the service to the server.
      • +
    +
    3. +
  3. To access the application: +
      +
    • Right-click on the jaxws-pojo-client subproject and choose Run As --> Java Application.
      • +
    • You should see the following message in the Console tab: +
      JSEBean pojo: pojoClient calling
+
      +
      • +
    +
    4. +
  4. To undeploy the project, right-click on the jaxws-pojo parent project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/jaxws-pojo/README.md b/jaxws-pojo/README.md index 96eefe3a15..8ff80dc8ee 100644 --- a/jaxws-pojo/README.md +++ b/jaxws-pojo/README.md @@ -4,47 +4,47 @@ Author: R Searls Level: Beginner Technologies: JAX-WS Summary: The `jaxws-pojo` quickstart is a working example of the web service endpoint created from a POJO. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `jaxws-pojo` quickstart demonstrates the use of *JAX-WS* in ${product.name.full} as a simple POJO web service application. +The `jaxws-pojo` quickstart demonstrates the use of *JAX-WS* in Red Hat JBoss Enterprise Application Platform as a simple POJO web service application. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `service/target/${project.artifactId}-service.war` to the running instance of the server. +4. This will deploy `service/target/jaxws-pojo-service.war` to the running instance of the server. ## Access the Application -You can check that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. +You can check that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. ## Run the Client 1. Make sure the service deployed properly. @@ -68,7 +68,7 @@ You can check that the Web Service is running and deployed correctly by accessin ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -77,21 +77,21 @@ You can check that the Web Service is running and deployed correctly by accessin ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). For this quickstart, follow the special instructions to [Deploy and Undeploy a Quickstart Containing Server and Java Client Projects](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-containing-server-and-java-client-projects) -1. To build all of the artifacts, right-click on the `${project.artifactId}` parent project, and choose `Run As` --> `Maven install`. +1. To build all of the artifacts, right-click on the `jaxws-pojo` parent project, and choose `Run As` --> `Maven install`. 2. To deploy the service: - * Right-click on the `${project.artifactId}-service` subproject, and choose `Run As` --> `Run on Server`. + * Right-click on the `jaxws-pojo-service` subproject, and choose `Run As` --> `Run on Server`. * Choose the server and click `Finish`. * This starts the server and deploys the service to the server. 3. To access the application: - * Right-click on the `${project.artifactId}-client` subproject and choose `Run As` --> `Java Application`. + * Right-click on the `jaxws-pojo-client` subproject and choose `Run As` --> `Java Application`. * You should see the following message in the `Console` tab: JSEBean pojo: pojoClient calling -4. To undeploy the project, right-click on the `${project.artifactId}` parent project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +4. To undeploy the project, right-click on the `jaxws-pojo` parent project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/jaxws-pojo/client/pom.xml b/jaxws-pojo/client/pom.xml index e6ae12281f..3d4a06409e 100644 --- a/jaxws-pojo/client/pom.xml +++ b/jaxws-pojo/client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jaxws-pojo - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA jaxws-pojo-client jar diff --git a/jaxws-pojo/pom.xml b/jaxws-pojo/pom.xml index 0ee96a44b1..49516ae77d 100644 --- a/jaxws-pojo/pom.xml +++ b/jaxws-pojo/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jaxws-pojo diff --git a/jaxws-pojo/service/pom.xml b/jaxws-pojo/service/pom.xml index f744566f0a..e39e191629 100644 --- a/jaxws-pojo/service/pom.xml +++ b/jaxws-pojo/service/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jaxws-pojo - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA jaxws-pojo-service war diff --git a/jaxws-retail/README.html b/jaxws-retail/README.html new file mode 100644 index 0000000000..cad146f202 --- /dev/null +++ b/jaxws-retail/README.html @@ -0,0 +1,134 @@ + + + jaxws-retail: A Retail JAX-WS Web Service + + + +

jaxws-retail: A Retail JAX-WS Web Service

+

Author: R Searls
+Level: Beginner
+Technologies: JAX-WS
+Summary: The jaxws-retail quickstart is a working example of a simple web service endpoint.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jaxws-retail quickstart demonstrates the use of JAX-WS in Red Hat JBoss Enterprise Application Platform as a simple profile management application. It also demonstrates usage of wsconsume to generate classes from WSDL file.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy service/target/jaxws-retail-service.war to the running instance of the server.

    +
    5. +
+

Note: You will see the following errors and warnings in the server log. These messages come from the jaxws-tools-maven-plugin plugin that generates source files based on the WSDL. You can ignore these warnings.

+
[INFO] Could not find log4j.xml configuration, logging to console.
+[INFO]
+[INFO] TODO! Cheek SOAP 1.2 extension
+[ERROR] log4j:WARN No appenders could be found for logger (org.apache.cxf.common.logging.LogUtils).
+[ERROR] log4j:WARN Please initialize the log4j system properly.
+[ERROR] log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
+
+

Note: You may also see the following errors if your Linux environment defines a BASH_FUNC_scl() function. You can ignore these errors.

+
[ERROR] /bin/sh: scl: line 1: syntax error: unexpected end of file
+[ERROR] /bin/sh: error importing function definition for `BASH_FUNC_scl`
+
+

Access the Application

+

You can check that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/jaxws-retail/ProfileMgmtService/ProfileMgmt?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.

+

Run the Client

+
    +
  1. +

    Make sure the service deployed properly.

    +
    2. +
  2. +

    Open a command prompt and navigate into the client directory of this quickstart.

    +
    cd client/
+
    +
    3. +
  3. Type this command to run the client. +
    mvn exec:java
+
    +

    Note: This quickstart requires quickstart-parent artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command:

    +
    mvn clean install
+
    +
    4. +
  4. +

    You should see the following output in the client console.

    +
    Jay Boss's discount is 10.00
+
    +
    5. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart is dependent on a WSDL file that is included in the jaxws-retail-service project, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+

When you import this project into JBoss Developer Studio, you see 17 errors. These Java Problems are because these classes are not included in this project. Instead, they are defined in and generated from the jaxws-retail-service/src/main/webapp/WEB-INF/wsdl/ProfileMgmtService.wsdl WSDL file. You can ignore these errors.

+

This quickstart requires that you build the parent project, deploy the service, and then run the client.

+
    +
  1. To build the parent project, right-click on the jaxws-retail project and choose Run As --> Maven install.
    2. +
  2. To deploy the service: +
      +
    • Right-click on the jaxws-retail-service project and choose Run As --> Maven install.
      • +
    • In the jaxws-retail-service project, select the target/generated-sources/wsconsume folder and choose Build Path --> Use as Source Folder.
      • +
    • Right-click on the jaxws-retail-service project and choose Run As --> Run on Server.
      • +
    • Select the JBoss EAP server and click Finish.
      • +
    • You should see the following message in the Console tab: +

      WFLYSRV0010: Deployed "jaxws-retail-service.war"

      +
      • +
    • +

      You also see the "404 - Not Found" error in the application window. This is because there is no user interface for this quickstart. You can ignore this error.

      +
      • +
    +
    3. +
  3. +

    To run the application:

    +
      +
    • To access the application, right-click on the jaxws-retail-client project and choose Run As --> Java Application.
      • +
    • Choose the Client class and click OK.
      • +
    • Review the output in the console window. You should see the following message: +

      Jay Boss's discount is 10.00

      +
      • +
    +
    4. +
  4. +

    To undeploy the project, right-click on the jaxws-retail-service project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.

    +
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+

Note: You will see the following informational messages. This is because the source files for this JAR are not available in the Maven repository.

+
[INFO] The following files have NOT been resolved:
+[INFO]    org.apache.ant:ant-launcher:jar:sources:1.7.0:provided
+[INFO]    com.sun:tools:jar:sources:1.6:system
+[INFO]    asm:asm:jar:sources:3.3.1:provided
+
+ + \ No newline at end of file diff --git a/jaxws-retail/README.md b/jaxws-retail/README.md index c6b5e40472..42dffc8482 100644 --- a/jaxws-retail/README.md +++ b/jaxws-retail/README.md @@ -4,43 +4,43 @@ Author: R Searls Level: Beginner Technologies: JAX-WS Summary: The `jaxws-retail` quickstart is a working example of a simple web service endpoint. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `jaxws-retail` quickstart demonstrates the use of *JAX-WS* in ${product.name.full} as a simple profile management application. It also demonstrates usage of wsconsume to generate classes from WSDL file. +The `jaxws-retail` quickstart demonstrates the use of *JAX-WS* in Red Hat JBoss Enterprise Application Platform as a simple profile management application. It also demonstrates usage of wsconsume to generate classes from WSDL file. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `service/target/${project.artifactId}-service.war` to the running instance of the server. +4. This will deploy `service/target/jaxws-retail-service.war` to the running instance of the server. _Note:_ You will see the following errors and warnings in the server log. These messages come from the `jaxws-tools-maven-plugin` plugin that generates source files based on the WSDL. You can ignore these warnings. @@ -59,7 +59,7 @@ _Note:_ You may also see the following errors if your Linux environment defines ## Access the Application -You can check that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. +You can check that the Web Service is running and deployed correctly by accessing the following URL: . This URL will display the deployed WSDL endpoint for the Web Service. ## Run the Client @@ -84,7 +84,7 @@ You can check that the Web Service is running and deployed correctly by accessin ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -93,36 +93,36 @@ You can check that the Web Service is running and deployed correctly by accessin ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -This quickstart is dependent on a WSDL file that is included in the `${project.artifactId}-service` project, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. +This quickstart is dependent on a WSDL file that is included in the `jaxws-retail-service` project, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. -When you import this project into JBoss Developer Studio, you see 17 errors. These `Java Problems` are because these classes are not included in this project. Instead, they are defined in and generated from the `${project.artifactId}-service/src/main/webapp/WEB-INF/wsdl/ProfileMgmtService.wsdl` WSDL file. You can ignore these errors. +When you import this project into JBoss Developer Studio, you see 17 errors. These `Java Problems` are because these classes are not included in this project. Instead, they are defined in and generated from the `jaxws-retail-service/src/main/webapp/WEB-INF/wsdl/ProfileMgmtService.wsdl` WSDL file. You can ignore these errors. This quickstart requires that you build the parent project, deploy the service, and then run the client. -1. To build the parent project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven install`. +1. To build the parent project, right-click on the `jaxws-retail` project and choose `Run As` --> `Maven install`. 2. To deploy the service: - * Right-click on the `${project.artifactId}-service` project and choose `Run As` --> `Maven install`. - * In the `${project.artifactId}-service` project, select the `target/generated-sources/wsconsume` folder and choose `Build Path` --> `Use as Source Folder`. + * Right-click on the `jaxws-retail-service` project and choose `Run As` --> `Maven install`. + * In the `jaxws-retail-service` project, select the `target/generated-sources/wsconsume` folder and choose `Build Path` --> `Use as Source Folder`. * Right-click on the `jaxws-retail-service` project and choose `Run As` --> `Run on Server`. * Select the JBoss EAP server and click `Finish`. * You should see the following message in the `Console` tab: - `WFLYSRV0010: Deployed "${project.artifactId}-service.war"` + `WFLYSRV0010: Deployed "jaxws-retail-service.war"` * You also see the "404 - Not Found" error in the application window. This is because there is no user interface for this quickstart. You can ignore this error. 3. To run the application: - * To access the application, right-click on the `${project.artifactId}-client` project and choose `Run As` --> `Java Application`. + * To access the application, right-click on the `jaxws-retail-client` project and choose `Run As` --> `Java Application`. * Choose the `Client` class and click `OK`. * Review the output in the console window. You should see the following message: `Jay Boss's discount is 10.00` -4. To undeploy the project, right-click on the `${project.artifactId}-service` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +4. To undeploy the project, right-click on the `jaxws-retail-service` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/jaxws-retail/client/pom.xml b/jaxws-retail/client/pom.xml index b57917f013..05dd3fa837 100644 --- a/jaxws-retail/client/pom.xml +++ b/jaxws-retail/client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jaxws-retail - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA jaxws-retail-client jar diff --git a/jaxws-retail/pom.xml b/jaxws-retail/pom.xml index 66209812fc..64200312bb 100644 --- a/jaxws-retail/pom.xml +++ b/jaxws-retail/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jaxws-retail diff --git a/jaxws-retail/service/pom.xml b/jaxws-retail/service/pom.xml index 77af457a48..667d15be0f 100644 --- a/jaxws-retail/service/pom.xml +++ b/jaxws-retail/service/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jaxws-retail - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jaxws-retail-service diff --git a/jsonp/README.html b/jsonp/README.html new file mode 100644 index 0000000000..5de4b73681 --- /dev/null +++ b/jsonp/README.html @@ -0,0 +1,62 @@ + + + jsonp: JSON-P Object-based JSON generation and Stream-based JSON consuming + + + +

jsonp: JSON-P Object-based JSON generation and Stream-based JSON consuming

+

Author: Rafael Benevides
+Level: Beginner
+Technologies: CDI, JSF, JSON-P
+Summary: The jsonp quickstart demonstrates how to use the JSON-P API to produce object-based structures and then parse and consume them as stream-based JSON strings.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jsonp quickstart creates a JSON string through object-based JSON generation and then parses and consumes it using stream-based JSON.

+

It shows how to use the JSON-P API to generate, parse, and consume JSON files.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. This will deploy target/jsonp to the running instance of the server.
    5. +
+

Access the Application

+

Access the running application in a browser at the following URL: http://localhost:8080/jsonp/

+

You are presented with a simple form that is pre-filled with personal data. You can change those values if you prefer.

+

Click on Generate JSON String from Personal Data button. The textarea below the button presents a JSON string representing the data and values from the completed form.

+

Note that the JSON string contains String, number, boolean and array values.

+

Now, click on Parse JSON String using Stream button. The textarea below the button shows the events generated from the parsed JSON string.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + + \ No newline at end of file diff --git a/jsonp/README.md b/jsonp/README.md index 9d44be30d3..d5314ae277 100644 --- a/jsonp/README.md +++ b/jsonp/README.md @@ -4,8 +4,8 @@ Author: Rafael Benevides Level: Beginner Technologies: CDI, JSF, JSON-P Summary: The `jsonp` quickstart demonstrates how to use the JSON-P API to produce object-based structures and then parse and consume them as stream-based JSON strings. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? @@ -17,33 +17,33 @@ It shows how to use the JSON-P API to generate, parse, and consume JSON files. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}` to the running instance of the server. +4. This will deploy `target/jsonp` to the running instance of the server. ## Access the Application -Access the running application in a browser at the following URL: +Access the running application in a browser at the following URL: You are presented with a simple form that is pre-filled with personal data. You can change those values if you prefer. @@ -56,7 +56,7 @@ Now, click on `Parse JSON String using Stream` button. The textarea below the bu ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -65,7 +65,7 @@ Now, click on `Parse JSON String using Stream` button. The textarea below the bu ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/jsonp/pom.xml b/jsonp/pom.xml index 6c7688a4e7..b54a06b7b2 100644 --- a/jsonp/pom.xml +++ b/jsonp/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jsonp diff --git a/jta-crash-rec/README.html b/jta-crash-rec/README.html new file mode 100644 index 0000000000..03a50ba9dc --- /dev/null +++ b/jta-crash-rec/README.html @@ -0,0 +1,183 @@ + + + jta-crash-rec: Example of JTA Crash Recovery + + + +

jta-crash-rec: Example of JTA Crash Recovery

+

Author: Mike Musgrove
+Level: Advanced
+Technologies: JTA, Crash Recovery
+Summary: The jta-crash-rec quickstart uses JTA and Byteman to show how to code distributed (XA) transactions in order to preserve ACID properties on server crash.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jta-crash-rec quickstart demonstrates how to code distributed or XA (eXtended Architecture) transactions so that the ACID properties are preserved across participating resources deployed to Red Hat JBoss Enterprise Application Platform after a server crash. An XA transaction is one in which multiple resources, such as MDBs and databases, participate within the same transaction. It ensures all operations are performed as a single entity of work. ACID is a set of 4 properties that guarantee the resources are processed in the following manner:

+
    +
  • Atomic - if any part of the transaction fails, all resources remain unchanged.
    • +
  • Consistent - the state will be consistent across resources after a commit
    • +
  • Isolated - the execution of the transaction for each resource is isolated from each others
    • +
  • Durable - the data will persist after the transaction is committed
    • +
+

This quickstart shows how to atomically update multiple resources within one transaction. It updates a relational database table using JPA and sends a message using JMS. This type of paired updates to two different resources are called XA transactions and are defined by the Java EE JTA specification JSR-907. JTA transactions are not distributed across multiple application servers.

+

The relational database table in this example contains two columns that represent a key / value pair. The application presents an HTML form containing two input text boxes and allows you to create, update, delete or list these pairs. When you add or update a key / value pair, the quickstart starts a transaction, updates the database table, produces a JMS message containing the update, and then commits the transaction. If all goes well, eventually the consumer gets the message and generates a database update, setting the value corresponding to the key to something that indicates it was changed by the message consumer.

+

In this example, you halt the JBoss EAP server in the middle of an XA transaction after the database modification has been committed, but before the JMS producer is committed. You can verify that the transaction was started, then restart the JBoss EAP server to complete the transaction. You then verify that everything is in a consistent state.

+

JBoss EAP ships with H2, an in-memory database written in Java. In this example, we use H2 for the database. Although H2 XA support is not recommended for production systems, the example does illustrate the general steps you need to perform for any datasource vendor. This example provides its own H2 XA datasource configuration. It is defined in the jta-crash-rec-ds.xml file in the WEB-INF folder of the WAR archive.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Download and Configure Byteman

+

This quickstart uses Byteman to help demonstrate crash recovery. You can find more information about Byteman here: Configure Byteman for Use with the Quickstarts

+

Follow the instructions here to download and configure Byteman: Download and Configure Byteman

+

Configure the Server

+

NOTE: The Byteman scripts only work in JTA mode. They do not work in JTS mode. If you have configured the server for a quickstart that uses JTS, you must follow the quickstart instructions to remove the JTS configuration from the JBoss EAP server before making the following changes. Otherwise Byteman will not halt the server.

+

Start the Server

+

Start the JBoss EAP Server with the Full Profile

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the JBoss EAP server with the full profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/jta-crash-rec.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/jta-crash-rec/XA.

+

Test the Application

+
    +
  1. +

    When you access the application, you will find a web page containing two html input boxes for adding key / value pairs to a database. Instructions for using the application are shown at the top of the application web page.

    +
    2. +
  2. +

    When you add a new key / value pair, the change is committed to the database and a JMS message sent. The message consumer then updates the newly inserted row by appending the text updated via JMS to the value. Since the consumer updates the row asynchronously, you may need to click Refresh Table to see the text added to the key / value pair you previously entered.

    +
    3. +
  3. +

    When an XA transaction is committed, the application server completes the transaction in two phases.

    +
      +
    • In phase 1 each of the resources, in this example the database and the JMS message producer, are asked to prepare to commit any changes made during the transaction.
      • +
    • If all resources vote to commit then the application server starts phase 2 in which it tells each resource to commit those changes.
      • +
    • The added complexity is to cope with failures, especially failures that occur during phase 2. Some failure modes require cooperation between the application server and the resources in order to guarantee that any pending changes are recovered.
      • +
    +
    4. +
  4. +

    To demonstrate XA recovery, you must enable the Byteman tool to terminate the application server while phase 2 is running as follows:

    +
      +
    • Stop the JBoss EAP server.
      • +
    • Follow the instructions here to clear the transaction objectstore remaining from any previous tests: Clear the Transaction ObjectStore
      • +
    • The following line of text must be appended to the server configuration file using the instructions located here: Use Byteman to Halt the Application +

      For Linux:

      +
      JAVA_OPTS="-javaagent:/BYTEMAN_HOME/lib/byteman.jar=script:/QUICKSTART_HOME/jta-crash-rec/src/main/scripts/xa.btm ${JAVA_OPTS}"
+
      +

      For Windows:

      +
       JAVA_OPTS=%JAVA_OPTS% -javaagent:C:BYTEMAN_HOME\lib\byteman.jar=script:C:\QUICKSTART_HOME\jta-crash-rec\src\main\scripts\xa.btm %JAVA_OPTS%
+
      +
      • +
    • Start the server as instructed above.
      • +
    +
    5. +
  5. +

    Once you complete step 4, you are ready to create a recovery record. Go to the application URL http://localhost:8080/jta-crash-rec/XA and insert another row into the database. At this point, Byteman halts the application server.

    +
    6. +
  6. +

    If you want to verify the database insert was committed but that message delivery is still pending, you can use an SQL client such as the H2 database console tool. Issue a query to show that the value is present but does not contain the message added by the consumer (updated via JMS). Here is how you can do it using H2:

    +
      +
    • Start the H2 console by typing: +
      java -cp EAP7_HOME/modules/system/layers/base/com/h2database/h2/main/h2*.jar org.h2.tools.Console
+
      +
      • +
    • Log in: +
      Database URL: jdbc:h2:file:~/jta-crash-rec-quickstart
+User name:    sa
+Password:     sa
+
      +
      • +
    • The console is available at the url http://localhost:8082. If you receive an error such as Exception opening port "8082" it is most likely because some other application has that port open. You will need to find which application is using the port and close it.
      • +
    • Once you are logged in enter the following query to see that the pair you entered is present but does not contain "updated via JMS". +
      select * from kvpair
+
      +
      • +
    • Log out of the H2 console and be sure to close out the command prompt. H2 is limited to one connection and the application will need it from this point forward.
      • +
    • If you are using the default file based transaction logging store, there will be a record in the file system corresponding to the pending transaction. +
        +
      • Open a command prompt and navigate to the EAP7_HOME directory
        • +
      • List the contents of the following directory: +
        ls EAP7_HOME/standalone/data/tx-object-store/ShadowNoFileLockStore/defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction/
+
        +
        • +
      • An example of a logging record file name is: +
        0_ffff7f000001_-7f1cf331_4f0b0ad4_15
+
        +
        • +
      • After recovery, log records are normally deleted automatically. However, logs may remain in the case where the Transaction Manager (TM) commit request was received and acted upon by a resource, but the TM crashed before it had time to clean up the logs of that resource.
        • +
      +
      • +
    +
    7. +
  7. To observe XA recovery +
      +
    • Stop the H2 console and exit the command prompt to close the database connections. Otherwise, you may see messages like the following when you start your server: +
      Database may be already in use: "Locked by another process"
+
      +
      • +
    • Disable the Byteman script by restoring the backup server configuration file.
      • +
    • Start the server as instructed above.
      • +
    • Load the web interface to the application
      • +
    • By the time the JBoss EAP server is ready, the transaction should have recovered.
      • +
    • A message is printed on the JBoss EAP server console when the consumer has completed the update. Look for a line that reads: +
      JTA Crash Record Quickstart: key value pair updated via JMS
+
      +
      • +
    • +

      Check that the row you inserted in step 4 now contains the text updated via JMS, showing that the JMS message was recovered successfully. Use the application URL to perform this check.

      +
      • +
    • You will most likely see the following messages in the server log. +
      WARN  [com.arjuna.ats.jta] (Periodic Recovery) ARJUNA016037: Could not find new XAResource to use for recovering non-serializable XAResource XAResourceRecord < resource:null, txid:< formatId=131077, gtrid_length=29, bqual_length=36, tx_uid=0:ffff7f000001:1040a11d:534ede43:1c, node_name=1, branch_uid=0:ffff7f000001:1040a11d:534ede43:20, subordinatenodename=null, eis_name=java:jboss/datasources/JTACrashRecQuickstartDS >, heuristic: TwoPhaseOutcome.FINISH_OK, product: H2/1.3.168-redhat-2 (2012-07-13), jndiName: java:jboss/datasources/JTACrashRecQuickstartDS com.arjuna.ats.internal.jta.resources.arjunacore.XAResourceRecord@788f0ec1 >
+WARN  [com.arjuna.ats.jta] (Periodic Recovery) ARJUNA016038: No XAResource to recover < formatId=131077, gtrid_length=29, bqual_length=36, tx_uid=0:ffff7f000001:1040a11d:534ede43:1c, node_name=1, branch_uid=0:ffff7f000001:1040a11d:534ede43:20, subordinatenodename=null, eis_name=java:jboss/datasources/JTACrashRecQuickstartDS >
+
      +

      This is normal. What actually happened is that the first resource (JTACrashRecQuickstartDS) committed before the JBoss EAP server was halted in step 5. The transaction logs are only updated/deleted after the outcome of the transaction is determined. If the transaction manager did update the log as each participant (database and JMS queue) completed then throughput would suffer. Notice you do not get a similar message for the JMS resource since that is the resource that recovered and the log record was updated to reflect this change. You need to manually remove the record for the first participant if you know which one is which or, if you are using the community version of the JBoss EAP server, then you can also inspect the transaction logs using a JMX browser. For the demo it is simplest to delete the records from the file system, however, be wary of doing this on a production system.

      +
      • +
    +
    8. +
  8. +

    Do NOT forget to Disable the Byteman script by restoring the backup server configuration file. The Byteman rule must be removed to ensure that your application server will be able to commit 2PC transactions!

    +
    9. +
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

NOTE: Within JBoss Developer Studio, be sure to define a server runtime environment that uses the standalone-full.xml configuration file.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/jta-crash-rec/README.md b/jta-crash-rec/README.md index 2c5761c0f4..f8ecd67b0e 100644 --- a/jta-crash-rec/README.md +++ b/jta-crash-rec/README.md @@ -4,12 +4,12 @@ Author: Mike Musgrove Level: Advanced Technologies: JTA, Crash Recovery Summary: The `jta-crash-rec` quickstart uses JTA and Byteman to show how to code distributed (XA) transactions in order to preserve ACID properties on server crash. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `jta-crash-rec` quickstart demonstrates how to code distributed or XA (eXtended Architecture) transactions so that the ACID properties are preserved across participating resources deployed to ${product.name.full} after a server crash. An XA transaction is one in which multiple resources, such as MDBs and databases, participate within the same transaction. It ensures all operations are performed as a single entity of work. ACID is a set of 4 properties that guarantee the resources are processed in the following manner: +The `jta-crash-rec` quickstart demonstrates how to code distributed or XA (eXtended Architecture) transactions so that the ACID properties are preserved across participating resources deployed to Red Hat JBoss Enterprise Application Platform after a server crash. An XA transaction is one in which multiple resources, such as MDBs and databases, participate within the same transaction. It ensures all operations are performed as a single entity of work. ACID is a set of 4 properties that guarantee the resources are processed in the following manner: * Atomic - if any part of the transaction fails, all resources remain unchanged. * Consistent - the state will be consistent across resources after a commit @@ -20,25 +20,25 @@ This quickstart shows how to atomically update multiple resources within one tra The relational database table in this example contains two columns that represent a `key` / `value` pair. The application presents an HTML form containing two input text boxes and allows you to create, update, delete or list these pairs. When you add or update a `key` / `value` pair, the quickstart starts a transaction, updates the database table, produces a JMS message containing the update, and then commits the transaction. If all goes well, eventually the consumer gets the message and generates a database update, setting the `value` corresponding to the `key` to something that indicates it was changed by the message consumer. -In this example, you halt the ${product.name} server in the middle of an XA transaction after the database modification has been committed, but before the JMS producer is committed. You can verify that the transaction was started, then restart the ${product.name} server to complete the transaction. You then verify that everything is in a consistent state. +In this example, you halt the JBoss EAP server in the middle of an XA transaction after the database modification has been committed, but before the JMS producer is committed. You can verify that the transaction was started, then restart the JBoss EAP server to complete the transaction. You then verify that everything is in a consistent state. -${product.name} ships with H2, an in-memory database written in Java. In this example, we use H2 for the database. Although H2 XA support is not recommended for production systems, the example does illustrate the general steps you need to perform for any datasource vendor. This example provides its own H2 XA datasource configuration. It is defined in the `jta-crash-rec-ds.xml` file in the WEB-INF folder of the WAR archive. +JBoss EAP ships with H2, an in-memory database written in Java. In this example, we use H2 for the database. Although H2 XA support is not recommended for production systems, the example does illustrate the general steps you need to perform for any datasource vendor. This example provides its own H2 XA datasource configuration. It is defined in the `jta-crash-rec-ds.xml` file in the WEB-INF folder of the WAR archive. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Download and Configure Byteman @@ -50,34 +50,34 @@ Follow the instructions here to download and configure _Byteman_: [Download and ## Configure the Server -_NOTE_: The _Byteman_ scripts only work in JTA mode. They do not work in JTS mode. If you have configured the server for a quickstart that uses JTS, you must follow the quickstart instructions to remove the JTS configuration from the ${product.name} server before making the following changes. Otherwise _Byteman_ will not halt the server. +_NOTE_: The _Byteman_ scripts only work in JTA mode. They do not work in JTS mode. If you have configured the server for a quickstart that uses JTS, you must follow the quickstart instructions to remove the JTS configuration from the JBoss EAP server before making the following changes. Otherwise _Byteman_ will not halt the server. ## Start the Server -Start the ${product.name} Server with the Full Profile +Start the JBoss EAP Server with the Full Profile -1. Open a command prompt and navigate to the root of the ${product.name} directory. -2. The following shows the command line to start the ${product.name} server with the full profile: +1. Open a command prompt and navigate to the root of the JBoss EAP directory. +2. The following shows the command line to start the JBoss EAP server with the full profile: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/jta-crash-rec.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Test the Application @@ -92,7 +92,7 @@ The application will be running at the following URL: and insert another row into the database. At this point, Byteman halts the application server. +5. Once you complete step 4, you are ready to create a _recovery record_. Go to the application URL and insert another row into the database. At this point, Byteman halts the application server. 6. If you want to verify the database insert was committed but that message delivery is still pending, you can use an SQL client such as the H2 database console tool. Issue a query to show that the value is present but does not contain the message added by the consumer (`updated via JMS`). Here is how you can do it using H2: * Start the H2 console by typing: - java -cp ${jboss.home.name}/modules/system/layers/base/com/h2database/h2/main/h2*.jar org.h2.tools.Console + java -cp EAP7_HOME/modules/system/layers/base/com/h2database/h2/main/h2*.jar org.h2.tools.Console * Log in: Database URL: jdbc:h2:file:~/jta-crash-rec-quickstart @@ -122,10 +122,10 @@ The application will be running at the following URL: , heuristic: TwoPhaseOutcome.FINISH_OK, product: H2/1.3.168-redhat-2 (2012-07-13), jndiName: java:jboss/datasources/JTACrashRecQuickstartDS com.arjuna.ats.internal.jta.resources.arjunacore.XAResourceRecord@788f0ec1 > WARN [com.arjuna.ats.jta] (Periodic Recovery) ARJUNA016038: No XAResource to recover < formatId=131077, gtrid_length=29, bqual_length=36, tx_uid=0:ffff7f000001:1040a11d:534ede43:1c, node_name=1, branch_uid=0:ffff7f000001:1040a11d:534ede43:20, subordinatenodename=null, eis_name=java:jboss/datasources/JTACrashRecQuickstartDS > - This is normal. What actually happened is that the first resource (JTACrashRecQuickstartDS) committed before the ${product.name} server was halted in step 5. The transaction logs are only updated/deleted after the outcome of the transaction is determined. If the transaction manager did update the log as each participant (database and JMS queue) completed then throughput would suffer. Notice you do not get a similar message for the JMS resource since that is the resource that recovered and the log record was updated to reflect this change. You need to manually remove the record for the first participant if you know which one is which or, if you are using the community version of the ${product.name} server, then you can also inspect the transaction logs using a JMX browser. For the demo it is simplest to delete the records from the file system, however, *be wary of doing this on a production system*. + This is normal. What actually happened is that the first resource (JTACrashRecQuickstartDS) committed before the JBoss EAP server was halted in step 5. The transaction logs are only updated/deleted after the outcome of the transaction is determined. If the transaction manager did update the log as each participant (database and JMS queue) completed then throughput would suffer. Notice you do not get a similar message for the JMS resource since that is the resource that recovered and the log record was updated to reflect this change. You need to manually remove the record for the first participant if you know which one is which or, if you are using the community version of the JBoss EAP server, then you can also inspect the transaction logs using a JMX browser. For the demo it is simplest to delete the records from the file system, however, *be wary of doing this on a production system*. @@ -164,7 +164,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -173,7 +173,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). _NOTE:_ Within JBoss Developer Studio, be sure to define a server runtime environment that uses the `standalone-full.xml` configuration file. diff --git a/jta-crash-rec/pom.xml b/jta-crash-rec/pom.xml index ad2ad5d00e..7b79520d80 100644 --- a/jta-crash-rec/pom.xml +++ b/jta-crash-rec/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jta-crash-rec diff --git a/jts-distributed-crash-rec/README.html b/jts-distributed-crash-rec/README.html new file mode 100644 index 0000000000..31f1cc441e --- /dev/null +++ b/jts-distributed-crash-rec/README.html @@ -0,0 +1,235 @@ + + + jts-distributed-crash-rec: JTS and distributed crash recovery + + + +

jts-distributed-crash-rec: JTS and distributed crash recovery

+

Author: Tom Jenkinson
+Level: Advanced
+Technologies: JTS, Crash Recovery
+Summary: The jts-distributed-crash-rec quickstart uses JTS and Byteman to demonstrate distributed crash recovery across multiple application servers.
+Prerequisites: jts
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jts-distributed-crash-rec quickstart demonstrates a distributed crash recovery across multiple application servers in Red Hat JBoss Enterprise Application Platform.

+

Crash recovery is a key feature provided by an application server and ensures an application's data consistency, even in the presence of failure. Providing reliable crash recovery helps qualify the pedigree of an application server, distributed crash recovery even more so.

+

This quickstart uses the application components from the jts quickstart. It provides a Byteman rule to inject a halt into the application server at a crucial point in the phase2 commit of the transaction. Byteman is used solely to raise an artificial fault. An IDE could also provide this simulation, although it is more complex to use an IDE for this purpose.

+

Apart from that, this quickstart works the same as the jts quickstart and if the Byteman rule is left out, this quickstart is the JTS quickstart.

+

As an overview, the sequence of events to expect:

+
    +
  1. Configure and start two JBoss EAP servers.
    2. +
  2. Build and deploy the two application components.
    3. +
  3. Open a web browser and attempt to invoice two customers as with the jts quickstart.
    4. +
  4. JBoss EAP server 1 will run through a two-phase commit (2PC), preparing the resources in JBoss EAP server 1 and JBoss EAP server 2. JBoss EAP server 1 will then crash before it can call commit.
    5. +
  5. The user is invited to inspect the content of the transaction objectstore.
    6. +
  6. JBoss EAP server 1 should be restarted. It will then recover the "invoices" delivered to the MDBs, just as it does in the jts quickstart.
    7. +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Download and Configure Byteman

+

This quickstart uses Byteman to help demonstrate crash recovery. You can find more information about Byteman here: Configure Byteman for Use with the Quickstarts

+

Follow the instructions here to download and configure Byteman: Download and Configure Byteman

+

Prerequisites

+

Developers should be familiar with the concepts introduced in the following quickstarts:

+
    +
  • cmt
    • +
  • jts
    • +
+

IMPORTANT: This quickstart depends on the deployment of the jts quickstart for its test. Before running this quickstart, see the jts README file for details on how to deploy it.

+

You can verify the deployment of the jts quickstart by accessing the following URL: http://localhost:8080/jts-application-component-1/.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Test the Application

+

Note: This quickstart README file uses the following replaceable values. When you encounter these values in a README file, be sure to replace them with the actual path to the correct JBoss EAP server.

+
`EAP7_HOME` denotes the path to the original JBoss EAP installation.
+`EAP7_HOME_1` denotes the path to the modified JBoss EAP server 1 configuration.
+`EAP7_HOME_2` denotes the path to the modified JBoss EAP server 2 configuration.
+
+
    +
  1. +

    If you have not yet done so, configure the two application servers and deploy the jts quickstart. Follow the instructions in the jts README file.

    +
    2. +
  2. +

    Configure Byteman to halt JBoss EAP server 1

    +
      +
    • Stop both JBoss EAP servers.
      • +
    • Follow the instructions here to clear the transaction objectstore remaining from any previous tests: Clear the Transaction ObjectStore
      • +
    • The following 2 lines of text must be appended to the server configuration file for server 1 only using the instructions located here: Use Byteman to Halt the Application +

      For Linux:

      +
      JAVA_OPTS="-javaagent:/BYTEMAN_HOME/lib/byteman.jar=script:/QUICKSTART_HOME/jts-distributed-crash-rec/byteman-scripts/failAfterPrepare.btm ${JAVA_OPTS}"
+JAVA_OPTS="-Dorg.jboss.byteman.transform.all -Djboss.modules.system.pkgs=org.jboss.byteman -Dorg.jboss.byteman.verbose=true ${JAVA_OPTS}"
+
      +

      For Windows:

      +
      JAVA_OPTS=%JAVA_OPTS% -javaagent:C:BYTEMAN_HOME\lib\byteman.jar=script:C:\QUICKSTART_HOME\jts-distributed-crash-rec\byteman-scripts\failAfterPrepare.btm %JAVA_OPTS%
+JAVA_OPTS=%JAVA_OPTS% -Dorg.jboss.byteman.transform.all -Djboss.modules.system.pkgs=org.jboss.byteman -Dorg.jboss.byteman.verbose=true
+
      +
      • +
    +
    3. +
  3. +

    Start both of the JBoss EAP servers

    +

    If you are using Linux:

    +
    Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100
+
    +

    If you are using Windows

    +
    Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100
+
    +
    4. +
  4. +

    Access the application at the following URL: http://localhost:8080/jts-application-component-1/

    +
      +
    • When you enter a name and click to "add" that customer, you will see the following in the application server 1 console: +
      INFO  [org.jboss.ejb.client] (default task-2) JBoss EJB Client version 2.1.4.Final-redhat-1
+INFO  [stdout] (default task-2) Rule.execute called for Fail 2PC after prepare_0
+INFO  [stdout] (default task-2) HelperManager.install for helper class org.jboss.byteman.rule.helper.Helper
+INFO  [stdout] (default task-2) calling activated() for helper class org.jboss.byteman.rule.helper.Helper
+INFO  [stdout] (default task-2) Default helper activated
+INFO  [stdout] (default task-2) calling installed(Fail 2PC after prepare) for helper classorg.jboss.byteman.rule.helper.Helper
+INFO  [stdout] (default task-2) Installed rule using default helper : Fail 2PC after prepare
+INFO  [stdout] (default task-2) Fail 2PC after prepare execute
+INFO  [stdout] (default task-2) rule.debug{Fail 2PC after prepare} : Prepare completed
+INFO  [stdout] (default task-2) rule.debug{Fail 2PC after prepare} : !!!killing JVM!!!
+
      +
      • +
    +
    5. +
  5. +

    At this point, Byteman halts or crashes server 1. You should be able to view the contents of the object store for this server by typing the following in the terminal for server 1. Be sure to replace EAP7_HOME_1 with the path to the first server.

    +
    tree EAP7_HOME_1/standalone/data/tx-object-store
+
    +

    This should display:

    +
    EAP7_HOME_1/standalone/data/tx-object-store
+ -- ShadowNoFileLockStore
+     -- defaultStore
+        |-- CosTransactions
+        |   -- XAResourceRecord
+        |       -- 0_ffffc0a8013c_38e104bd_4f280cdb_1d
+        |-- Recovery
+        |   -- FactoryContact
+        |       |-- 0_ffffc0a8013c_38e104bd_4f280cdb_17
+        |       |-- 0_ffffc0a8013c_-671009a_4f280e7e_17
+        |       -- 0_ffffc0a8013c_6d5d82b5_4f280a16_f
+        |-- RecoveryCoordinator
+        |   -- 0_ffff52e38d0c_c91_4140398c_0
+         -- StateManager
+            -- BasicAction
+                -- TwoPhaseCoordinator
+                    -- ArjunaTransactionImple
+                        -- 0_ffffc0a8013c_38e104bd_4f280cdb_19
+
    +

    View the contents of the object store for the second server by typing the following in the terminal for server 2. Be sure to replace EAP7_HOME_2 with the path to the second server.

    +
     tree EAP7_HOME_2/standalone/data/tx-object-store
+
    +

    This should display:

    +
    EAP7_HOME_2/standalone/data/tx-object-store
+-- ShadowNoFileLockStore
+    -- defaultStore
+        |-- CosTransactions
+        |   -- XAResourceRecord
+        |       -- 0_ffffc0a8013c_-2eb1158b_4f280ce3_1e
+        |-- Recovery
+        |   -- FactoryContact
+        |       |-- 0_ffffc0a8013c_-2eb1158b_4f280ce3_18
+        |       -- 0_ffffc0a8013c_4f6459f0_4f280a24_f
+        |-- RecoveryCoordinator
+        |   -- 0_ffff52e38d0c_c91_4140398c_0
+         -- StateManager
+            -- BasicAction
+                -- TwoPhaseCoordinator
+                    -- ArjunaTransactionImple
+                        -- ServerTransaction
+                            -- 0_ffffc0a8013c_-2eb1158b_4f280ce3_1a
+
    +
    6. +
  6. +

    Disable the Byteman script by restoring the backup configuration file for server 1.

    +
    7. +
  7. +

    Follow the steps above to restart server 1 and wait for recovery to complete.

    +

    IMPORTANT: By default, the recovery process checks the transactional state every two minutes, therefore it can take a while for recovery to happen. Also recovery for each server will take place at its own recovery interval.

    +
      +
    • You will know when recovery is complete for server 2 as you will see the following in application-server-2 console: +
      INFO  [org.jboss.ejb.client] (RequestProcessor-10) JBoss EJB Client version 2.1.2.Final
+INFO  [class org.jboss.as.quickstarts.cmt.jts.mdb.HelloWorldMDB] (Thread-3 (group:ActiveMQ-client-global-threads-649946595)) Received Message: Created invoice for customer named: Tom
+
      +
      • +
    • NOTE: You will also get several stack traces in JBoss EAP server 1 console during recovery, these are to be expected as not all resources are available at all stages of recovery. +
      WARN  [com.arjuna.ats.jts] (Periodic Recovery) ARJUNA022223: ExtendedResourceRecord.topLevelCommit caught exception: org.omg.CORBA.OBJECT_NOT_EXIST: ----------BEGIN server-side stack trace----------
+org.omg.CORBA.OBJECT_NOT_EXIST:   vmcid: SUN  minor code: 1004  completed: No
+    at com.sun.corba.se.impl.logging.POASystemException.nullServant(POASystemException.java:2040)
+    at com.sun.corba.se.impl.logging.POASystemException.nullServant(POASystemException.java:2062)
+    at com.sun.corba.se.impl.oa.poa.POAPolicyMediatorImpl_R_AOM.internalGetServant(POAPolicyMediatorImpl_R_AOM.java:68)
+    at com.sun.corba.se.impl.oa.poa.POAPolicyMediatorBase.getInvocationServant(POAPolicyMediatorBase.java:121)
+    at com.sun.corba.se.impl.oa.poa.POAImpl.getInvocationServant(POAImpl.java:1634)
+    at com.sun.corba.se.impl.protocol.CorbaServerRequestDispatcherImpl.getServant(CorbaServerRequestDispatcherImpl.java:326)
+    at com.sun.corba.se.impl.protocol.CorbaServerRequestDispatcherImpl.getServantWithPI(CorbaServerRequestDispatcherImpl.java:360)
+    at com.sun.corba.se.impl.protocol.CorbaServerRequestDispatcherImpl.dispatch(CorbaServerRequestDispatcherImpl.java:202)
+    at com.sun.corba.se.impl.protocol.CorbaMessageMediatorImpl.handleRequestRequest(CorbaMessageMediatorImpl.java:1700)
+    at com.sun.corba.se.impl.protocol.SharedCDRClientRequestDispatcherImpl.marshalingComplete(SharedCDRClientRequestDispatcherImpl.java:180)
+    at com.sun.corba.se.impl.protocol.CorbaClientDelegateImpl.invoke(CorbaClientDelegateImpl.java:148)
+    at org.omg.CORBA.portable.ObjectImpl._invoke(ObjectImpl.java:475)
+    at com.arjuna.ArjunaOTS._ArjunaSubtranAwareResourceStub.commit(_ArjunaSubtranAwareResourceStub.java:124)
+    at com.arjuna.ats.internal.jts.resources.ExtendedResourceRecord.topLevelCommit(ExtendedResourceRecord.java:502)
+  ...
+
      +
      • +
    • The easiest way to check when JBoss EAP server 1 is recovered is to look in the object store and check that all the records are now cleaned up. The records that should be cleared are the ones in the defaultStore/CosTransactions/XAResourceRecord and defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/ArjunaTransactionImple.
      • +
    • Records will remain in defaultStore/Recovery/FactoryContact and defaultStore/RecoveryCoordinator for server 1 and that is to be expected. Run: +
      tree EAP7_HOME_1/standalone/data/tx-object-store
+
      +

      You should see this output:

      +
      EAP7_HOME_1/standalone/data/tx-object-store
+-- ShadowNoFileLockStore
+    -- defaultStore
+        |-- CosTransactions
+        |   -- XAResourceRecord
+        |-- Recovery
+        |   -- FactoryContact
+        |       |-- 0_ffffc0a8013c_38e104bd_4f280cdb_17
+        |       |-- 0_ffffc0a8013c_-671009a_4f280e7e_17
+        |       -- 0_ffffc0a8013c_6d5d82b5_4f280a16_f
+        |-- RecoveryCoordinator
+        |   -- 0_ffff52e38d0c_c91_4140398c_0
+         -- StateManager
+            -- BasicAction
+                -- TwoPhaseCoordinator
+                  -- ArjunaTransactionImple
+
      +

      View the contents of the object store for the second server by typing the following in the terminal for server 2. Be sure to replace EAP7_HOME_2 with the path to the second server.

      +
      tree EAP7_HOME_2/standalone/data/tx-object-store
+
      +

      This should display:

      +
      EAP7_HOME_2/standalone/data/tx-object-store
+-- ShadowNoFileLockStore
+    -- defaultStore
+        |-- CosTransactions
+        |   -- XAResourceRecord
+        |-- Recovery
+        |   -- FactoryContact
+        |       |-- 0_ffffc0a8013c_-2eb1158b_4f280ce3_18
+        |       -- 0_ffffc0a8013c_4f6459f0_4f280a24_f
+        |-- RecoveryCoordinator
+        |   -- 0_ffff52e38d0c_c91_4140398c_0
+        -- StateManager
+            -- BasicAction
+                -- TwoPhaseCoordinator
+                    -- ArjunaTransactionImple
+                        -- ServerTransaction
+
      +
      • +
    +
    8. +
  8. +

    After recovery is complete, access the application URL http://localhost:8080/jts-application-component-1/customers.jsf. The user you created should now appear in the list.

    +
    9. +
  9. +

    Do NOT forget to Disable the Byteman script by restoring the backup server configuration file. The Byteman rule must be removed to ensure that your application server will be able to commit 2PC transactions!

    +
    10. +
+ + \ No newline at end of file diff --git a/jts-distributed-crash-rec/README.md b/jts-distributed-crash-rec/README.md index 0d5a613bbc..012529422d 100644 --- a/jts-distributed-crash-rec/README.md +++ b/jts-distributed-crash-rec/README.md @@ -5,12 +5,12 @@ Level: Advanced Technologies: JTS, Crash Recovery Summary: The `jts-distributed-crash-rec` quickstart uses JTS and Byteman to demonstrate distributed crash recovery across multiple application servers. Prerequisites: jts -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `jts-distributed-crash-rec` quickstart demonstrates a distributed crash recovery across multiple application servers in ${product.name.full}. +The `jts-distributed-crash-rec` quickstart demonstrates a distributed crash recovery across multiple application servers in Red Hat JBoss Enterprise Application Platform. Crash recovery is a key feature provided by an application server and ensures an application's data consistency, even in the presence of failure. Providing reliable crash recovery helps qualify the pedigree of an application server, distributed crash recovery even more so. @@ -20,19 +20,19 @@ Apart from that, this quickstart works the same as the `jts` quickstart and if t As an overview, the sequence of events to expect: -1. Configure and start two ${product.name} servers. +1. Configure and start two JBoss EAP servers. 2. Build and deploy the two application components. 3. Open a web browser and attempt to invoice two customers as with the `jts` quickstart. -4. ${product.name} server 1 will run through a two-phase commit (2PC), preparing the resources in ${product.name} server 1 and ${product.name} server 2. ${product.name} server 1 will then crash before it can call commit. +4. JBoss EAP server 1 will run through a two-phase commit (2PC), preparing the resources in JBoss EAP server 1 and JBoss EAP server 2. JBoss EAP server 1 will then crash before it can call commit. 5. The user is invited to inspect the content of the transaction objectstore. -6. ${product.name} server 1 should be restarted. It will then recover the "invoices" delivered to the MDBs, just as it does in the `jts` quickstart. +6. JBoss EAP server 1 should be restarted. It will then recover the "invoices" delivered to the MDBs, just as it does in the `jts` quickstart. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Download and Configure Byteman @@ -54,24 +54,24 @@ IMPORTANT: This quickstart depends on the deployment of the `jts` quickstart for You can verify the deployment of the `jts` quickstart by accessing the following URL: . -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Test the Application -_Note:_ This quickstart README file uses the following replaceable values. When you encounter these values in a README file, be sure to replace them with the actual path to the correct ${product.name} server. +_Note:_ This quickstart README file uses the following replaceable values. When you encounter these values in a README file, be sure to replace them with the actual path to the correct JBoss EAP server. - `${jboss.home.name}` denotes the path to the original ${product.name} installation. - `${jboss.home.name}_1` denotes the path to the modified ${product.name} server 1 configuration. - `${jboss.home.name}_2` denotes the path to the modified ${product.name} server 2 configuration. + `EAP7_HOME` denotes the path to the original JBoss EAP installation. + `EAP7_HOME_1` denotes the path to the modified JBoss EAP server 1 configuration. + `EAP7_HOME_2` denotes the path to the modified JBoss EAP server 2 configuration. 1. If you have not yet done so, configure the two application servers and deploy the `jts` quickstart. Follow the instructions in the [jts README](../jts/README.md) file. -2. Configure _Byteman_ to halt ${product.name} server 1 - * Stop both ${product.name} servers. +2. Configure _Byteman_ to halt JBoss EAP server 1 + * Stop both JBoss EAP servers. * Follow the instructions here to clear the transaction objectstore remaining from any previous tests: [Clear the Transaction ObjectStore](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#clear-the-transaction-objectstore) * The following 2 lines of text must be appended to the server configuration file for server 1 only using the instructions located here: [Use Byteman to Halt the Application](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#use-byteman-to-halt-the-application) @@ -85,17 +85,17 @@ _Note:_ This quickstart README file uses the following replaceable values. When JAVA_OPTS=%JAVA_OPTS% -javaagent:C:BYTEMAN_HOME\lib\byteman.jar=script:C:\QUICKSTART_HOME\jts-distributed-crash-rec\byteman-scripts\failAfterPrepare.btm %JAVA_OPTS% JAVA_OPTS=%JAVA_OPTS% -Dorg.jboss.byteman.transform.all -Djboss.modules.system.pkgs=org.jboss.byteman -Dorg.jboss.byteman.verbose=true -3. Start both of the ${product.name} servers +3. Start both of the JBoss EAP servers If you are using Linux: - Server 1: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 - Server 2: ${jboss.home.name}_2/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 + Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 If you are using Windows - Server 1: ${jboss.home.name}_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 - Server 2: ${jboss.home.name}_2\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 + Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 4. Access the application at the following URL: * When you enter a name and click to "add" that customer, you will see the following in the application server 1 console: @@ -111,13 +111,13 @@ _Note:_ This quickstart README file uses the following replaceable values. When INFO [stdout] (default task-2) rule.debug{Fail 2PC after prepare} : Prepare completed INFO [stdout] (default task-2) rule.debug{Fail 2PC after prepare} : !!!killing JVM!!! -5. At this point, Byteman halts or crashes server 1. You should be able to view the contents of the object store for this server by typing the following in the terminal for server 1. Be sure to replace `${jboss.home.name}_1` with the path to the first server. +5. At this point, Byteman halts or crashes server 1. You should be able to view the contents of the object store for this server by typing the following in the terminal for server 1. Be sure to replace `EAP7_HOME_1` with the path to the first server. - tree ${jboss.home.name}_1/standalone/data/tx-object-store + tree EAP7_HOME_1/standalone/data/tx-object-store This should display: - ${jboss.home.name}_1/standalone/data/tx-object-store + EAP7_HOME_1/standalone/data/tx-object-store -- ShadowNoFileLockStore -- defaultStore |-- CosTransactions @@ -136,13 +136,13 @@ _Note:_ This quickstart README file uses the following replaceable values. When -- ArjunaTransactionImple -- 0_ffffc0a8013c_38e104bd_4f280cdb_19 - View the contents of the object store for the second server by typing the following in the terminal for server 2. Be sure to replace `${jboss.home.name}_2` with the path to the second server. + View the contents of the object store for the second server by typing the following in the terminal for server 2. Be sure to replace `EAP7_HOME_2` with the path to the second server. - tree ${jboss.home.name}_2/standalone/data/tx-object-store + tree EAP7_HOME_2/standalone/data/tx-object-store This should display: - ${jboss.home.name}_2/standalone/data/tx-object-store + EAP7_HOME_2/standalone/data/tx-object-store -- ShadowNoFileLockStore -- defaultStore |-- CosTransactions @@ -172,7 +172,7 @@ _Note:_ This quickstart README file uses the following replaceable values. When INFO [org.jboss.ejb.client] (RequestProcessor-10) JBoss EJB Client version 2.1.2.Final INFO [class org.jboss.as.quickstarts.cmt.jts.mdb.HelloWorldMDB] (Thread-3 (group:ActiveMQ-client-global-threads-649946595)) Received Message: Created invoice for customer named: Tom - * _NOTE:_ You will also get several stack traces in ${product.name} server 1 console during recovery, these are to be expected as not all resources are available at all stages of recovery. + * _NOTE:_ You will also get several stack traces in JBoss EAP server 1 console during recovery, these are to be expected as not all resources are available at all stages of recovery. WARN [com.arjuna.ats.jts] (Periodic Recovery) ARJUNA022223: ExtendedResourceRecord.topLevelCommit caught exception: org.omg.CORBA.OBJECT_NOT_EXIST: ----------BEGIN server-side stack trace---------- org.omg.CORBA.OBJECT_NOT_EXIST: vmcid: SUN minor code: 1004 completed: No @@ -191,14 +191,14 @@ _Note:_ This quickstart README file uses the following replaceable values. When at com.arjuna.ArjunaOTS._ArjunaSubtranAwareResourceStub.commit(_ArjunaSubtranAwareResourceStub.java:124) at com.arjuna.ats.internal.jts.resources.ExtendedResourceRecord.topLevelCommit(ExtendedResourceRecord.java:502) ... - * The easiest way to check when ${product.name} server 1 is recovered is to look in the object store and check that all the records are now cleaned up. The records that should be cleared are the ones in the `defaultStore/CosTransactions/XAResourceRecord` and `defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/ArjunaTransactionImple`. + * The easiest way to check when JBoss EAP server 1 is recovered is to look in the object store and check that all the records are now cleaned up. The records that should be cleared are the ones in the `defaultStore/CosTransactions/XAResourceRecord` and `defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/ArjunaTransactionImple`. * Records will remain in `defaultStore/Recovery/FactoryContact` and `defaultStore/RecoveryCoordinator` for server 1 and that is to be expected. Run: - tree ${jboss.home.name}_1/standalone/data/tx-object-store + tree EAP7_HOME_1/standalone/data/tx-object-store You should see this output: - ${jboss.home.name}_1/standalone/data/tx-object-store + EAP7_HOME_1/standalone/data/tx-object-store -- ShadowNoFileLockStore -- defaultStore |-- CosTransactions @@ -214,13 +214,13 @@ _Note:_ This quickstart README file uses the following replaceable values. When -- BasicAction -- TwoPhaseCoordinator -- ArjunaTransactionImple - View the contents of the object store for the second server by typing the following in the terminal for server 2. Be sure to replace `${jboss.home.name}_2` with the path to the second server. + View the contents of the object store for the second server by typing the following in the terminal for server 2. Be sure to replace `EAP7_HOME_2` with the path to the second server. - tree ${jboss.home.name}_2/standalone/data/tx-object-store + tree EAP7_HOME_2/standalone/data/tx-object-store This should display: - ${jboss.home.name}_2/standalone/data/tx-object-store + EAP7_HOME_2/standalone/data/tx-object-store -- ShadowNoFileLockStore -- defaultStore |-- CosTransactions diff --git a/jts-distributed-crash-rec/pom.xml b/jts-distributed-crash-rec/pom.xml index d16e2979e9..52e5243d50 100644 --- a/jts-distributed-crash-rec/pom.xml +++ b/jts-distributed-crash-rec/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml jts-distributed-crash-rec diff --git a/jts/README.html b/jts/README.html new file mode 100644 index 0000000000..48d150a285 --- /dev/null +++ b/jts/README.html @@ -0,0 +1,269 @@ + + + jts: Java Transaction Service - Distributed EJB Transactions + + + +

jts: Java Transaction Service - Distributed EJB Transactions

+

Author: Tom Jenkinson
+Level: Intermediate
+Technologies: JTS, EJB, JMS
+Summary: The jts quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction.
+Prerequisites: cmt
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The jts quickstart demonstrates how to perform distributed transactions across multiple containers in an application deployed to Red Hat JBoss Enterprise Application Platform. A distributed transaction is a set of operations performed by two or more nodes, participating in an activity coordinated as a single entity of work, and fulfilling the properties of an ACID transaction.

+

ACID is a set of 4 properties that guarantee the resources are processed in the following manner:

+
    +
  • Atomic - if any part of the transaction fails, all resources remain unchanged.
    • +
  • Consistent - the state will be consistent across resources after a commit
    • +
  • Isolated - the execution of the transaction for each resource is isolated from each others
    • +
  • Durable - the data will persist after the transaction is committed
    • +
+

The example uses Java Transaction Service (JTS) to propagate a transaction context across two Container-Managed Transaction (CMT) EJBs that, although deployed in separate servers, participate in the same transaction. In this example, one server processes the Customer and Account data and the other server processes the Invoice data.

+

The code base is essentially the same as the cmt quickstart, however in this case the InvoiceManager has been separated to a different deployment archive to demonstrate the usage of JTS. You can see the changes in the following ways:

+
    +
  • cmt/src/main/java/org/jboss/as/quickstarts/cmt/ejb/InvoiceManagerEJB.java has been moved to application-component-2/src/main/java/org/jboss/as/quickstarts/cmt/jts/ejb/InvoiceManagerEJB
    • +
  • cmt/src/main/java/org/jboss/as/quickstarts/cmt/ejb/CustomerManagerEJB.java has been moved to jts/application-component-1/src/main/java/org/jboss/as/quickstarts/cmt/jts/ejb/CustomerManagerEJB.java
    • +
+

The changes to CustomerManagerEJB are purely to accommodate the fact that InvoiceManager is now distributed.

+

You will see that the CustomerManagerEJB uses the EJB home for the remote EJB, this is expected to connect to remote EJBs. The example expects the EJBs to be deployed onto the same physical machine. This is not a restriction of JTS and the example can easily be converted to run on separate machines by editing the hostname value for the InvoiceManagerEJB in org.jboss.as.quickstarts.cmt.jts.ejb.CustomerManagerEJB.

+

A simple MDB has been provided that prints out the messages sent but this is not a transactional MDB and is purely provided for debugging purposes.

+

Also, while the cmt quickstart uses the Java EE container default datasource, which is not distributed, this quickstart instead uses an external PostgreSQL database.

+

After you complete this quickstart, you are invited to run through the jts-distributed-crash-rec quickstart. The crash recovery quickstart builds upon this quickstart by demonstrating the fault tolerance of Red Hat JBoss Enterprise Application Platform.

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Prerequisites

+

Developers should be familiar with the concepts introduced in the cmt quickstart.

+

This quickstart requires the configuration of two servers. The first server must be configured to use the PostgreSQL database. Instructions to install and configure PostgreSQL are below.

+

Configure the PostgreSQL Database for Use with this Quickstart

+

This quickstart requires the PostgreSQL database.

+

Instructions to install and configure PostgreSQL can be found here: Download and Install PostgreSQL

+

Note: For the purpose of this quickstart, replace the word QUICKSTART_DATABASE_NAME with jts-quickstart-database in the PostgreSQL instructions.

+

Be sure to Create a Database User for the PostgeSQL database.

+

When you have completed these steps, be sure to start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions to start the database server for your operating system every time you reboot your machine.

+

Wait until later in these instructions to add the PostgreSQL module and driver configuration to the first JBoss EAP server.

+

Configure the Servers

+

For this example, you will need two instances of the application server, with a subtle startup configuration difference. Application server 2 must be started up with a port offset parameter provided to the startup script as -Djboss.socket.binding.port-offset=100.

+

Since both application servers must be configured in the same way, you must configure the first server and then clone it. After you clone the second server, the first server must be configured for PostgreSQL.

+

Note: This quickstart README file use the following replaceable values. When you encounter these values in a README file, be sure to replace them with the actual path to the correct JBoss EAP server.

+
    +
  • EAP7_HOME denotes the path to the original JBoss EAP installation.
    • +
  • EAP7_HOME_1 denotes the path to the modified JBoss EAP server 1 configuration.
    • +
  • EAP7_HOME_2 denotes the path to the modified JBoss EAP server 2 configuration.
    • +
+

Configure the First Server

+

You configure JTS transactions by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-jts-transactions.cli script provided in the root directory of this quickstart.

+
    +
  1. Before you begin, back up your server configuration file +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone-full.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. Start the JBoss EAP server with the full profile, passing a unique node ID by typing the following command. Be sure to replace UNIQUE_NODE_ID_1 with a node identifier that is unique to both servers. +
    For Linux:  EAP7_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+For Windows:  EAP7_HOME\bin\standalone.bat -c standalone-full.xml  -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+
    +
    3. +
  3. Review the configure-jts-transactions.cli file in the root of this quickstart directory. This script configures the server to use jts transaction processing.
    4. +
  4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-jts-transactions.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-jts-transactions.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: restart-required
+
    +
    5. +
  5. +

    Stop the JBoss EAP server.

    +
    6. +
+

NOTE: When you have completed testing this quickstart, it is important to Remove the JTS Configuration from the JBoss EAP Server.

+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone-full.xml file and review the changes.

+
    +
  1. +

    The orb initializers transactions attribute is changed from spec to full in the iiop-openjdk subsystem to enable JTS.

    +
    <subsystem xmlns="urn:jboss:domain:iiop-openjdk:2.0">
+    <initializers transactions="full" security="identity"/>
+</subsystem>
+
    +
    2. +
  2. +

    An empty <jts/> element is added to the end of the transactions subsystem to enable JTS.

    +
    <subsystem xmlns="urn:jboss:domain:transactions:4.0">
+    <core-environment node-identifier="${jboss.tx.node.id}">
+        <process-id>
+            <uuid/>
+        </process-id>
+    </core-environment>
+    <recovery-environment socket-binding="txn-recovery-environment" status-socket-binding="txn-status-manager"/>
+    <jts/>
+</subsystem>
+
    +
    3. +
+

NOTE: When you have completed testing this quickstart, it is important to Remove the JTS Configuration from the JBoss EAP Server.

+

Clone the Server Directory

+

Make a copy of this JBoss EAP directory structure to use for the second server.

+

Configure Server1 to use PostgreSQL

+

Application server 1 must be now configured to use the PostgreSQL database created previously in the Configure the PostgreSQL Database for Use with this Quickstart section.

+
    +
  1. Be sure to start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions "Start the database server" for your operating system every time you reboot your machine.
    2. +
  2. Follow the instructions to Add the PostgreSQL Module to the JBoss EAP Server to the server 1 install only.
    3. +
  3. Follow the instructions to Configure the PostgreSQL Driver in the JBoss EAP Server for the server 1 configuration. Be sure to pass the -Djboss.tx.node.id=UNIQUE_NODE_ID_1 on the command line when you start the first server to configure PostgreSQL.
    4. +
+

Start the Servers

+

Start the two JBoss EAP servers with the full profile, passing a unique node ID by typing the following command. You must pass a socket binding port offset on the command to start the second server. Be sure to replace UNIQUE_NODE_ID with a node identifier that is unique to both servers.

+

If you are using Linux:

+
    Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+    Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100
+
+

If you are using Windows

+
    Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+    Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100
+
+

Build and Deploy the Quickstart

+

Since this quickstart builds two separate components, you can not use the standard Build and Deploy commands used by most of the other quickstarts. You must follow these steps to build, deploy, and run this quickstart.

+
    +
  1. Make sure you have started the JBoss EAP server with the PostgreSQL driver
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy jts-application-component-1.war and jts-application-component-2.jar to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/jts-application-component-1/.

+

When you enter a name and click to Add that customer, you will see the following in the application server 1 console:

+
INFO  [org.hibernate.hql.internal.QueryTranslatorFactoryInitiator] (default task-2) HHH000397: Using ASTQueryTranslatorFactory
+INFO  [org.jboss.ejb.client] (default task-4) JBoss EJB Client version 2.1.4.Final-redhat-1
+
+

You will also see the following in application-server-2 console:

+
INFO  [org.jboss.ejb.client] (p: default-threadpool; w: Idle) JBoss EJB Client version 2.1.4.Final-redhat-1
+INFO  [class org.jboss.as.quickstarts.cmt.jts.mdb.HelloWorldMDB] (Thread-97 (ActiveMQ-client-global-threads-6840624)) Received Message: Created invoice for customer named: Tom
+
+

The web page will also change and show you the new list of customers.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn package wildfly:undeploy
+
    +
    4. +
+

Remove the JTS Configuration From the Server

+

You must remove the JTS server configuration you did during setup because it interferes with the JTA quickstarts.

+

You can modify the server configuration by running the remove-jts-transactions.cli script provided in the root directory of this quickstart, by using the JBoss CLI interactively, or by manually editing the configuration file.

+

Remove the JTS Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server with the full profile. +
    For Linux:  EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml  -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+For Windows:  EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml  -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=remove-jts-transactions.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=remove-jts-transactions.cli
+
    +
    3. +
+

This script removes the JTS configuration from the iiop-openjdk and transactions subsystems in the server configuration. You should see the following result when you run the script:

+
    The batch executed successfully
+    process-state: restart-required
+    {
+        "outcome" => "success",
+        "result" => undefined
+    }
+
+

Remove the JTS Server Configuration using the JBoss CLI Tool

+
    +
  1. Start the JBoss EAP server with the full profile. +
    For Linux:  EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+For Windows:  EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1
+
    +
    2. +
  2. To start the JBoss CLI tool, open a new command prompt, navigate to the EAP7_HOME directory, and type the following: +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect
+
    +
    3. +
  3. At the prompt, type the following: +
    /subsystem=iiop-openjdk/:write-attribute(name=transactions,value=spec)
+/subsystem=transactions/:undefine-attribute(name=jts)
+/subsystem=transactions/:undefine-attribute(name=node-identifier)
+
    +
    4. +
+

You should see the following result when you run the script:

+
    {
+        "outcome" => "success",
+        "response-headers" => {
+            "operation-requires-reload" => true,
+            "process-state" => "restart-required"
+        }
+    }
+
+    {
+
+        "outcome" => "success",
+        "response-headers" => {
+            "operation-requires-restart" => true,
+            "process-state" => "restart-required"
+        }
+    }
+
+    {
+        "outcome" => "success",
+        "response-headers" => {
+            "operation-requires-reload" => true,
+            "process-state" => "restart-required"
+        }
+    }
+
+

Remove the JTS Server Configuration Manually

+
    +
  1. Stop the server.
    2. +
  2. If you backed up the EAP7_HOME/standalone/configuration/standalone-full.xml,simply replace the edited configuration file with the backup copy.
    3. +
  3. If you did not make a backup copy, open the file EAP7_HOME/standalone/configuration/standalone-full.xml and disable JTS as follows: +
      +
    • +

      Find the orb subsystem and change the configuration back to its original state.

      +
      <subsystem xmlns="urn:jboss:domain:iiop-openjdk:2.0">
+    <initializers transactions="spec" security="identity"/>
+</subsystem>
+
      +
      • +
    • +

      Find the transaction subsystem and remove the node-identifier attribute from the core-environment element. Also remove the <jts/> element.

      +
      <subsystem xmlns="urn:jboss:domain:transactions:4.0">
+    <core-environment>
+        <process-id>
+            <uuid/>
+        </process-id>
+    </core-environment>
+    <recovery-environment socket-binding="txn-recovery-environment" status-socket-binding="txn-status-manager"/>
+</subsystem>
+
      +
      • +
    +
    4. +
+ + \ No newline at end of file diff --git a/jts/README.md b/jts/README.md index 3260cd6e9e..2b661a786a 100755 --- a/jts/README.md +++ b/jts/README.md @@ -5,13 +5,13 @@ Level: Intermediate Technologies: JTS, EJB, JMS Summary: The `jts` quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction. Prerequisites: cmt -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `jts` quickstart demonstrates how to perform distributed transactions across multiple containers in an application deployed to ${product.name.full}. A distributed transaction is a set of operations performed by two or more nodes, participating in an activity coordinated as a single entity of work, and fulfilling the properties of an ACID transaction. +The `jts` quickstart demonstrates how to perform distributed transactions across multiple containers in an application deployed to Red Hat JBoss Enterprise Application Platform. A distributed transaction is a set of operations performed by two or more nodes, participating in an activity coordinated as a single entity of work, and fulfilling the properties of an ACID transaction. ACID is a set of 4 properties that guarantee the resources are processed in the following manner: @@ -37,21 +37,21 @@ A simple MDB has been provided that prints out the messages sent but this is not Also, while the `cmt` quickstart uses the Java EE container default datasource, which is not distributed, this quickstart instead uses an external PostgreSQL database. -After you complete this quickstart, you are invited to run through the [jts-distributed-crash-rec](../jts-distributed-crash-rec/README.md) quickstart. The crash recovery quickstart builds upon this quickstart by demonstrating the fault tolerance of ${product.name.full}. +After you complete this quickstart, you are invited to run through the [jts-distributed-crash-rec](../jts-distributed-crash-rec/README.md) quickstart. The crash recovery quickstart builds upon this quickstart by demonstrating the fault tolerance of Red Hat JBoss Enterprise Application Platform. -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Prerequisites @@ -73,7 +73,7 @@ Be sure to [Create a Database User](https://github.com/jboss-developer/jboss-dev When you have completed these steps, be sure to start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions to start the database server for your operating system every time you reboot your machine. -Wait until later in these instructions to add the PostgreSQL module and driver configuration to the first ${product.name} server. +Wait until later in these instructions to add the PostgreSQL module and driver configuration to the first JBoss EAP server. ## Configure the Servers @@ -82,42 +82,42 @@ For this example, you will need two instances of the application server, with a Since both application servers must be configured in the same way, you must configure the first server and then clone it. After you clone the second server, the first server must be configured for PostgreSQL. -_Note:_ This quickstart README file use the following replaceable values. When you encounter these values in a README file, be sure to replace them with the actual path to the correct ${product.name} server. +_Note:_ This quickstart README file use the following replaceable values. When you encounter these values in a README file, be sure to replace them with the actual path to the correct JBoss EAP server. - * `${jboss.home.name}` denotes the path to the original ${product.name} installation. - * `${jboss.home.name}_1` denotes the path to the modified ${product.name} server 1 configuration. - * `${jboss.home.name}_2` denotes the path to the modified ${product.name} server 2 configuration. + * `EAP7_HOME` denotes the path to the original JBoss EAP installation. + * `EAP7_HOME_1` denotes the path to the modified JBoss EAP server 1 configuration. + * `EAP7_HOME_2` denotes the path to the modified JBoss EAP server 2 configuration. ### Configure the First Server You configure JTS transactions by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-jts-transactions.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone-full.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone-full.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server with the full profile, passing a unique node ID by typing the following command. Be sure to replace `UNIQUE_NODE_ID_1` with a node identifier that is unique to both servers. +2. Start the JBoss EAP server with the full profile, passing a unique node ID by typing the following command. Be sure to replace `UNIQUE_NODE_ID_1` with a node identifier that is unique to both servers. - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 3. Review the `configure-jts-transactions.cli` file in the root of this quickstart directory. This script configures the server to use jts transaction processing. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-jts-transactions.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-jts-transactions.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-jts-transactions.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-jts-transactions.cli You should see the following result when you run the script: The batch executed successfully process-state: restart-required -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. -_NOTE:_ When you have completed testing this quickstart, it is important to [Remove the JTS Configuration from the ${product.name} Server](#remove-the-jts-configuration-from-the-server). +_NOTE:_ When you have completed testing this quickstart, it is important to [Remove the JTS Configuration from the JBoss EAP Server](#remove-the-jts-configuration-from-the-server). ### Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone-full.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone-full.xml` file and review the changes. 1. The orb initializers `transactions` attribute is changed from `spec` to `full` in the `iiop-openjdk` subsystem to enable JTS. @@ -137,34 +137,34 @@ After stopping the server, open the `${jboss.home.name}/standalone/configuration -_NOTE:_ When you have completed testing this quickstart, it is important to [Remove the JTS Configuration from the ${product.name} Server](#remove-the-jts-configuration-from-the-server). +_NOTE:_ When you have completed testing this quickstart, it is important to [Remove the JTS Configuration from the JBoss EAP Server](#remove-the-jts-configuration-from-the-server). ### Clone the Server Directory -Make a copy of this ${product.name} directory structure to use for the second server. +Make a copy of this JBoss EAP directory structure to use for the second server. ### Configure Server1 to use PostgreSQL Application server 1 must be now configured to use the PostgreSQL database created previously in the [Configure the PostgreSQL Database for Use with this Quickstart](#configure-the-postgresql-database-for-use-with-this-quickstart) section. 1. Be sure to start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions "Start the database server" for your operating system every time you reboot your machine. -2. Follow the instructions to [Add the PostgreSQL Module to the ${product.name} Server](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#add-the-postgresql-module-to-the-red-hat-jboss-enterprise-application-platform-server) to the server 1 install only. -3. Follow the instructions to [Configure the PostgreSQL Driver in the ${product.name} Server](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#configure-the-postgresql-driver-in-the-red-hat-jboss-enterprise-application-platform-server) for the server 1 configuration. Be sure to pass the `-Djboss.tx.node.id=UNIQUE_NODE_ID_1` on the command line when you start the first server to configure PostgreSQL. +2. Follow the instructions to [Add the PostgreSQL Module to the JBoss EAP Server](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#add-the-postgresql-module-to-the-red-hat-jboss-enterprise-application-platform-server) to the server 1 install only. +3. Follow the instructions to [Configure the PostgreSQL Driver in the JBoss EAP Server](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#configure-the-postgresql-driver-in-the-red-hat-jboss-enterprise-application-platform-server) for the server 1 configuration. Be sure to pass the `-Djboss.tx.node.id=UNIQUE_NODE_ID_1` on the command line when you start the first server to configure PostgreSQL. ## Start the Servers -Start the two ${product.name} servers with the full profile, passing a unique node ID by typing the following command. You must pass a socket binding port offset on the command to start the second server. Be sure to replace `UNIQUE_NODE_ID` with a node identifier that is unique to both servers. +Start the two JBoss EAP servers with the full profile, passing a unique node ID by typing the following command. You must pass a socket binding port offset on the command to start the second server. Be sure to replace `UNIQUE_NODE_ID` with a node identifier that is unique to both servers. If you are using Linux: - Server 1: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 - Server 2: ${jboss.home.name}_2/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 + Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 If you are using Windows - Server 1: ${jboss.home.name}_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 - Server 2: ${jboss.home.name}_2\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 + Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 ## Build and Deploy the Quickstart @@ -172,17 +172,17 @@ If you are using Windows Since this quickstart builds two separate components, you can not use the standard *Build and Deploy* commands used by most of the other quickstarts. You must follow these steps to build, deploy, and run this quickstart. -1. Make sure you have started the ${product.name} server with the PostgreSQL driver +1. Make sure you have started the JBoss EAP server with the PostgreSQL driver 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `${project.artifactId}-application-component-1.war` and `${project.artifactId}-application-component-2.jar` to the running instance of the server. +4. This will deploy `jts-application-component-1.war` and `jts-application-component-2.jar` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . When you enter a name and click to `Add` that customer, you will see the following in the application server 1 console: @@ -205,7 +205,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -220,14 +220,14 @@ You can modify the server configuration by running the `remove-jts-transactions. ### Remove the JTS Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server with the full profile. +1. Start the JBoss EAP server with the full profile. - For Linux: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 - For Windows: ${jboss.home.name}_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 + For Windows: EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=remove-jts-transactions.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=remove-jts-transactions.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=remove-jts-transactions.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=remove-jts-transactions.cli This script removes the JTS configuration from the `iiop-openjdk` and `transactions` subsystems in the server configuration. You should see the following result when you run the script: The batch executed successfully @@ -239,14 +239,14 @@ This script removes the JTS configuration from the `iiop-openjdk` and `transacti ### Remove the JTS Server Configuration using the JBoss CLI Tool -1. Start the ${product.name} server with the full profile. +1. Start the JBoss EAP server with the full profile. - For Linux: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 - For Windows: ${jboss.home.name}_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 -2. To start the JBoss CLI tool, open a new command prompt, navigate to the ${jboss.home.name} directory, and type the following: + For Linux: EAP7_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 + For Windows: EAP7_HOME_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 +2. To start the JBoss CLI tool, open a new command prompt, navigate to the EAP7_HOME directory, and type the following: - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect 3. At the prompt, type the following: /subsystem=iiop-openjdk/:write-attribute(name=transactions,value=spec) @@ -283,8 +283,8 @@ This script removes the JTS configuration from the `iiop-openjdk` and `transacti ### Remove the JTS Server Configuration Manually 1. Stop the server. -2. If you backed up the ${jboss.home.name}/standalone/configuration/standalone-full.xml,simply replace the edited configuration file with the backup copy. -3. If you did not make a backup copy, open the file ${jboss.home.name}/standalone/configuration/standalone-full.xml and disable JTS as follows: +2. If you backed up the EAP7_HOME/standalone/configuration/standalone-full.xml,simply replace the edited configuration file with the backup copy. +3. If you did not make a backup copy, open the file EAP7_HOME/standalone/configuration/standalone-full.xml and disable JTS as follows: * Find the `orb` subsystem and change the configuration back to its original state. diff --git a/jts/application-component-1/pom.xml b/jts/application-component-1/pom.xml index 8c635dea09..1570f188bb 100644 --- a/jts/application-component-1/pom.xml +++ b/jts/application-component-1/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jts - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA jts-application-component-1 war diff --git a/jts/application-component-2/pom.xml b/jts/application-component-2/pom.xml index 77d4107fc4..977adedee2 100644 --- a/jts/application-component-2/pom.xml +++ b/jts/application-component-2/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts jts - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA jts-application-component-2 jar diff --git a/jts/pom.xml b/jts/pom.xml index 29b2197fd0..add997f2d1 100644 --- a/jts/pom.xml +++ b/jts/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml diff --git a/kitchensink-angularjs/README.html b/kitchensink-angularjs/README.html new file mode 100644 index 0000000000..cb0245e8fc --- /dev/null +++ b/kitchensink-angularjs/README.html @@ -0,0 +1,105 @@ + + + kitchensink-angularjs: Demonstrates AngularJS with JAX-RS + + + +

kitchensink-angularjs: Demonstrates AngularJS with JAX-RS

+

Author: Pete Muir
+Level: Intermediate
+Technologies: AngularJS, CDI, JPA, EJB, JPA, JAX-RS, BV
+Summary: The kitchensink-angularjs quickstart demonstrates a Java EE 7 application using AngularJS with JAX-RS, CDI, EJB, JPA, and Bean Validation.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The kitchensink-angularjs quickstart is a deployable Maven 3 project to help you get your foot in the door developing with AngularJS on Java EE 7 with Red Hat JBoss Enterprise Application Platform.

+

This project is setup to allow you to create a compliant Java EE 7 application using CDI 1.2, EJB 3.2, JPA 2.1 and Bean Validation 1.1. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   bin/standalone.sh
+For Windows: bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/kitchensink-angularjs.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/kitchensink-angularjs/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type fhe following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Note: If you have not installed the AngularJS Eclipse plugin into JBoss Developer Studio, you may see one or more of the following warnings when you import this project. You can ignore these warnings.

+
HTML Problem: Undefined attribute name (ng-app)
+HTML Problem: Undefined attribute name (ng-click)
+HTML Problem: Undefined attribute name (ng-disabled)
+HTML Problem: Undefined attribute name (ng-hide)
+HTML Problem: Undefined attribute name (ng-model)
+HTML Problem: Undefined attribute name (ng-pattern)
+HTML Problem: Undefined attribute name (ng-repeat)
+HTML Problem: Undefined attribute name (ng-show)
+HTML Problem: Undefined attribute name (ng-submit)
+HTML Problem: Undefined attribute name (ng-view)
+
+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/kitchensink-angularjs/README.md b/kitchensink-angularjs/README.md index e4f8b86bf7..63fadf1302 100644 --- a/kitchensink-angularjs/README.md +++ b/kitchensink-angularjs/README.md @@ -4,24 +4,24 @@ Author: Pete Muir Level: Intermediate Technologies: AngularJS, CDI, JPA, EJB, JPA, JAX-RS, BV Summary: The `kitchensink-angularjs` quickstart demonstrates a Java EE 7 application using AngularJS with JAX-RS, CDI, EJB, JPA, and Bean Validation. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `kitchensink-angularjs` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with AngularJS on Java EE 7 with ${product.name.full}. +The `kitchensink-angularjs` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with AngularJS on Java EE 7 with Red Hat JBoss Enterprise Application Platform. This project is setup to allow you to create a compliant Java EE 7 application using CDI 1.2, EJB 3.2, JPA 2.1 and Bean Validation 1.1. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: For Linux: bin/standalone.sh @@ -30,23 +30,23 @@ All you need to build this project is ${build.requirements}. See [Configure Mave ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/kitchensink-angularjs.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -57,13 +57,13 @@ The application will be running at the following URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml kitchensink-angularjs-test-webdriver diff --git a/kitchensink-angularjs/pom.xml b/kitchensink-angularjs/pom.xml index 7b34773052..381b0650a0 100644 --- a/kitchensink-angularjs/pom.xml +++ b/kitchensink-angularjs/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml kitchensink-angularjs diff --git a/kitchensink-ear/README.html b/kitchensink-ear/README.html new file mode 100644 index 0000000000..fef97e6030 --- /dev/null +++ b/kitchensink-ear/README.html @@ -0,0 +1,112 @@ + + + kitchensink-ear: Using Multiple Java EE 7 Technologies Deployed as an EAR + + + +

kitchensink-ear: Using Multiple Java EE 7 Technologies Deployed as an EAR

+

Author: Pete Muir
+Level: Intermediate
+Technologies: CDI, JSF, JPA, EJB, JAX-RS, BV, EAR
+Summary: The kitchensink-ear quickstart demonstrates web-enabled database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The kitchensink-ear quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on Red Hat JBoss Enterprise Application Platform.

+

It demonstrates how to create a compliant Java EE 7 application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. It is based on the kitchensink quickstart but is packaged as an EAR archive.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy ear/target/kitchensink-ear.ear to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/kitchensink-ear/.

+
    +
  1. Enter a name, email address, and Phone nubmer in the input field and click the Register button.
    2. +
  2. If the data entered is valid, the new member will be registered and added to the Members display list.
    3. +
  3. If the data is not valid, you must fix the validation errors and try again.
    4. +
  4. When the registration is successful, you will see a log message in the server console: +
    Registering _the_name_you_entered_
+
    +
    5. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

You should see the following console output when you run the tests:

+
Results :
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+
+

Investigate the Server Console Output

+

You should see messages similar to the following:

+
INFO  [org.jboss.as.server.deployment] (MSC service thread 1-3) WFLYSRV0027: Starting deployment of "test.war" (runtime-name: "test.war")
+...
+INFO  [org.jboss.as.quickstarts.kitchensink_ear.service.MemberRegistration] (default task-102) Registering Jane Doe
+INFO  [org.jboss.as.quickstarts.kitchensink_ear.test.MemberRegistrationTest] (default task-102) Jane Doe was persisted with id 1
+...
+INFO  [org.jboss.as.server.deployment] (MSC service thread 1-2) WFLYSRV0028: Stopped deployment test.war (runtime-name: test.war) in 38ms
+....
+INFO  [org.jboss.as.server] (management-handler-thread - 22) WFLYSRV0009: Undeployed "test.war" (runtime-name: "test.war")
+
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

For this quickstart, follow the special instructions to build Quickstarts Containing an EAR

+
    +
  1. Right-click on the kitchensink-ear-ear subproject, and choose Run As --> Run on Server.
    2. +
  2. Choose the server and click Finish.
    3. +
  3. This starts the server, deploys the application, and opens a browser window that accesses the running application at http://localhost:8080/kitchensink-ear-web.
    4. +
  4. To undeploy the project, right-click on the kitchensink-ear-ear project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/kitchensink-ear/README.md b/kitchensink-ear/README.md index c415d22298..09893df6dd 100644 --- a/kitchensink-ear/README.md +++ b/kitchensink-ear/README.md @@ -4,50 +4,50 @@ Author: Pete Muir Level: Intermediate Technologies: CDI, JSF, JPA, EJB, JAX-RS, BV, EAR Summary: The `kitchensink-ear` quickstart demonstrates web-enabled database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `kitchensink-ear` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on ${product.name.full}. +The `kitchensink-ear` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on Red Hat JBoss Enterprise Application Platform. It demonstrates how to create a compliant Java EE 7 application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. It is based on the [kitchensink](../kitchensink/README.md) quickstart but is packaged as an EAR archive. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `ear/target/${project.artifactId}.ear` to the running instance of the server. +4. This will deploy `ear/target/kitchensink-ear.ear` to the running instance of the server. ## Access the Application @@ -64,7 +64,7 @@ The application will be running at the following URL: `Run on Server`. +1. Right-click on the `kitchensink-ear-ear` subproject, and choose `Run As` --> `Run on Server`. 2. Choose the server and click `Finish`. 3. This starts the server, deploys the application, and opens a browser window that accesses the running application at . -4. To undeploy the project, right-click on the `${project.artifactId}-ear` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +4. To undeploy the project, right-click on the `kitchensink-ear-ear` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/kitchensink-ear/ear/pom.xml b/kitchensink-ear/ear/pom.xml index a062b040f8..a1b5994674 100644 --- a/kitchensink-ear/ear/pom.xml +++ b/kitchensink-ear/ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts kitchensink-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA kitchensink-ear-ear ear diff --git a/kitchensink-ear/ejb/pom.xml b/kitchensink-ear/ejb/pom.xml index 47edf7a6cb..8bbce2b2ed 100644 --- a/kitchensink-ear/ejb/pom.xml +++ b/kitchensink-ear/ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts kitchensink-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA kitchensink-ear-ejb ejb diff --git a/kitchensink-ear/pom.xml b/kitchensink-ear/pom.xml index 48e0641a49..1fa4875a54 100644 --- a/kitchensink-ear/pom.xml +++ b/kitchensink-ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml kitchensink-ear diff --git a/kitchensink-ear/web/pom.xml b/kitchensink-ear/web/pom.xml index 31f1ac5952..1e5bfaf540 100644 --- a/kitchensink-ear/web/pom.xml +++ b/kitchensink-ear/web/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts kitchensink-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA kitchensink-ear-web war diff --git a/kitchensink-html5-mobile/README.html b/kitchensink-html5-mobile/README.html new file mode 100644 index 0000000000..0a81e210c4 --- /dev/null +++ b/kitchensink-html5-mobile/README.html @@ -0,0 +1,97 @@ + + + kitchensink-html5-mobile: More Complex Example of HTML5, Mobile and JAX-RS + + + +

kitchensink-html5-mobile: More Complex Example of HTML5, Mobile and JAX-RS

+

Author: Jay Balunas
+Level: Beginner
+Technologies: CDI, HTML5, REST
+Summary: The kitchensink-html5-mobile quickstart is based on kitchensink, but uses HTML5 and jQuery Mobile, making it suitable for mobile and tablet computers.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The kitchensink-html5-mobile quickstart is based on the kitchensink quickstart and demonstrates a Java EE 7 mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST in Red Hat JBoss Enterprise Application Platform.

+

This application is built using a HTML5 + REST approach. This uses a pure HTML client that interacts with the application server via restful end-points (JAX-RS). This application also uses some of the latest HTML5 features and advanced JAX-RS. And since testing is just as important with client side as it is server side, this application uses QUnit to show you how to unit test your JavaScript.

+

What is a modern web application without mobile web support? This application also integrates jQuery mobile and basic client side device detection to give you both a desktop and mobile version of the interface. Both support the same features, including form validation, member registration, etc. However the mobile version adds in mobile layout, touch, and performance improvements needed to get you started with mobile web development on JBoss.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ are required. and note that some behaviors will vary slightly (ex. validations) based on browser support, especially IE 9.

+

Mobile web support is limited to Android and iOS devices. It should run on HP, and Black Berry devices as well. Windows Phone, and others will be supported as jQuery Mobile announces support.

+

With the prerequisites out of the way, you are ready to build and deploy.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Note: Adding -b 0.0.0.0 to the above commands will allow external clients, such as phones, tablets, and desktops, connect through your local network.

+

For example

+
    For Linux:   EAP7_HOME/bin/standalone.sh -b 0.0.0.0
+    For Windows: EAP7_HOME\bin\standalone.bat -b 0.0.0.0
+
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean wildfly:deploy
+
    +
    4. +
  4. +

    This deploys target/kitchensink-html5-mobile.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

Access the running client application in a browser at the following URL: http://localhost:8080/kitchensink-html5-mobile/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+ +

Minification

+

By default, the project uses the wro4j plugin, which provides the ability to concatenate, validate and minify JavaScript and CSS files. These minified files, as well as their unmodified versions are deployed with the project.

+

With just a few quick changes to the project, you can link to the minified versions of your JavaScript and CSS files.

+

First, in the <project-root>/src/main/webapp/index.html file, search for references to minification and comment or uncomment the appropriate lines.

+

Finally, wro4j runs in the compile phase so any standard build command like package, install, etc. will trigger it. The plugin is in a profile with an id of minify so you will want to specify that profile in your maven build.

+

NOTE: By default there are turn off tests so you must use the arquillian test profile to run tests when minifying. For example:

+
#No Tests
+mvn clean wildfly:deploy -Pminify
+
+

OR

+
#With Tests
+mvn clean verify wildfly:deploy -Pminify,arq-remote
+
+

Run the Arquillian Tests

+

By default, tests are configured to be skipped. The reason is that the sample test is an Arquillian test, which requires the use of a container. You can activate this test by selecting one of the container configuration provided for JBoss.

+

To run the test in JBoss, first start the container instance. Then, run the test goal with the following profile activated:

+
mvn clean verify -Parq-remote
+
+

Run the QUnit tests

+

QUnit is a JavaScript unit testing framework used and built by jQuery. Because JavaScript code is the core of an HTML5 application, this quickstart provides a set of QUnit tests that automate testing of this code in various browsers.

+

Executing QUnit test cases is quite easy. Simply load the following HTML file in the browser you want to test.

+
    QUICKSTART_HOME/kitchensink-html5-mobile/src/test/qunit/index.html
+
+

You can also display the QUnit tests using the Eclipse built-in browser.

+

For more information on QUnit tests see http://qunitjs.com/

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to be able to debug into the source code or look at the Javadocs of any library in the project, you can run either of the following two commands to pull them into your local repository. The IDE should then detect them.

+
mvn dependency:sources
+mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/kitchensink-html5-mobile/README.md b/kitchensink-html5-mobile/README.md index 8ed430c891..da851e9ce5 100644 --- a/kitchensink-html5-mobile/README.md +++ b/kitchensink-html5-mobile/README.md @@ -4,12 +4,12 @@ Author: Jay Balunas Level: Beginner Technologies: CDI, HTML5, REST Summary: The `kitchensink-html5-mobile` quickstart is based on `kitchensink`, but uses HTML5 and jQuery Mobile, making it suitable for mobile and tablet computers. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `kitchensink-html5-mobile` quickstart is based on the `kitchensink` quickstart and demonstrates a Java EE 7 mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST in ${product.name.full}. +The `kitchensink-html5-mobile` quickstart is based on the `kitchensink` quickstart and demonstrates a Java EE 7 mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST in Red Hat JBoss Enterprise Application Platform. This application is built using a HTML5 + REST approach. This uses a pure HTML client that interacts with the application server via restful end-points (JAX-RS). This application also uses some of the latest HTML5 features and advanced JAX-RS. And since testing is just as important with client side as it is server side, this application uses QUnit to show you how to unit test your JavaScript. @@ -17,9 +17,9 @@ What is a modern web application without mobile web support? This application al ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ are required. and note that some behaviors will vary slightly (ex. validations) based on browser support, especially IE 9. @@ -29,36 +29,36 @@ With the prerequisites out of the way, you are ready to build and deploy. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat Note: Adding `-b 0.0.0.0` to the above commands will allow external clients, such as phones, tablets, and desktops, connect through your local network. For example - For Linux: ${jboss.home.name}/bin/standalone.sh -b 0.0.0.0 - For Windows: ${jboss.home.name}\bin\standalone.bat -b 0.0.0.0 + For Linux: EAP7_HOME/bin/standalone.sh -b 0.0.0.0 + For Windows: EAP7_HOME\bin\standalone.bat -b 0.0.0.0 ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean wildfly:deploy -4. This deploys `target/${project.artifactId}.war` to the running instance of the server. +4. This deploys `target/kitchensink-html5-mobile.war` to the running instance of the server. ## Access the Application -Access the running client application in a browser at the following URL: . +Access the running client application in a browser at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -66,7 +66,7 @@ Access the running client application in a browser at the following URL: @@ -115,7 +115,7 @@ For more information on QUnit tests see ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/kitchensink-html5-mobile/SERVICES.html b/kitchensink-html5-mobile/SERVICES.html new file mode 100644 index 0000000000..1e34ffd5ac --- /dev/null +++ b/kitchensink-html5-mobile/SERVICES.html @@ -0,0 +1,47 @@ + + +kitchensink-html5-mobile: JAX-RS Services Documentation + + + +

kitchensink-html5-mobile: JAX-RS Services Documentation

+

Author: Jay Balunas, Marius Bogoevici

+

This example supports various RESTFul end points which also includes JSONP support for cross domain requests.

+

By default the base URL for services is /jboss-as-kitchensink-html5-mobile/rest.

+

MemberService End Points

+

List all members

+

/rest/members

+
    +
  • Request type: GET
    • +
  • Return type: JSON
    • +
  • Response example:
    • +
+
[{"id":1,"name":"Jane Smith","email":"jane.smith@mailinator.com","phoneNumber":"2125551212"},{"id":0,"name":"John Smith","email":"john.smith@mailinator.com","phoneNumber":"2125551212"}]
+
+

Create a new member

+

/rest/members

+
    +
  • Request type: POST
    • +
  • Request type: JSON
    • +
  • Return type: JSON
    • +
  • Request example:
    • +
+
[{"name":"Jane Smith","email":"jane.smith@mailinator.com","phoneNumber":"4160000000"}]
+
+* Response example:
+ * Success: 200 OK
+ * Validation error: Collection of `<field name>:<error msg>` for each error
+
+```JavaScript
+{"phoneNumber":"10-12 Numbers","email":"Invalid format"}
+
+

/rest/members/<id>

+
    +
  • Request type: GET
    • +
  • Return type: JSON
    • +
  • Response example:
    • +
+
{"id":0,"name":"John Smith","email":"john.smith@mailinator.com","phoneNumber":"2125551212"}
+
+ + \ No newline at end of file diff --git a/kitchensink-html5-mobile/pom.xml b/kitchensink-html5-mobile/pom.xml index 02792e1505..16516c70f7 100644 --- a/kitchensink-html5-mobile/pom.xml +++ b/kitchensink-html5-mobile/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml kitchensink-html5-mobile diff --git a/kitchensink-jsp/README.html b/kitchensink-jsp/README.html new file mode 100644 index 0000000000..eb7d56986e --- /dev/null +++ b/kitchensink-jsp/README.html @@ -0,0 +1,85 @@ + + + kitchensink-jsp: Kitchensink with a JSP (JavaServer Pages) Front End + + + +

kitchensink-jsp: Kitchensink with a JSP (JavaServer Pages) Front End

+

Author: Elvadas Nono
+Level: Intermediate
+Technologies: JSP, JSTL, CDI, JPA, EJB, JAX-RS, BV
+Summary: The kitchensink-jsp quickstart demonstrates how to use JSP, JSTL, CDI, EJB, JPA, and Bean Validation in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The kitchensink-jsp quickstart is a deployable Maven 3 project and demonstrates how to create a compliant Java EE 7 application using JSP 2.0, EL 2.0, JSTL 1.2, CDI, EJB, JPA, and Bean Validation in Red Hat JBoss Enterprise Application Platform.

+

This example is based on the kitchensink quickstart, but recreates the presentation tier using JSP and JSTL instead of JSF features. It reuses all other components from the Member Registration template. It also reuses the persistence unit and some sample persistence and transaction code to help you with database access in enterprise Java.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/kitchensink-jsp.war to the running instance of the server.

    +
    5. +
+

Access the application

+

The application will be running at the following URL: http://localhost:8080/kitchensink-jsp/.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

You may see the following warnings for the index.jsp file when you import this quickstart into JBoss Developer Studio.

+
    The tag handler class for "c:forEach" (org.apache.taglibs.standard.tag.rt.core.ForEachTag) was not found on the Java Build Path
+    The tag handler class for "c:out" (org.apache.taglibs.standard.tag.rt.core.OutTag) was not found on the Java Build Path
+
+

You can ignore this warning as it does not impact building or deploying the quickstart in JBoss Developer Studio. See JBIDE-22175 for the latest updates on this issue.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/kitchensink-jsp/README.md b/kitchensink-jsp/README.md index daa91ba411..f6cfd1687e 100644 --- a/kitchensink-jsp/README.md +++ b/kitchensink-jsp/README.md @@ -2,55 +2,55 @@ Author: Elvadas Nono Level: Intermediate Technologies: JSP, JSTL, CDI, JPA, EJB, JAX-RS, BV -Summary: The `kitchensink-jsp` quickstart demonstrates how to use JSP, JSTL, CDI, EJB, JPA, and Bean Validation in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `kitchensink-jsp` quickstart demonstrates how to use JSP, JSTL, CDI, EJB, JPA, and Bean Validation in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `kitchensink-jsp` quickstart is a deployable Maven 3 project and demonstrates how to create a compliant Java EE 7 application using JSP 2.0, EL 2.0, JSTL 1.2, CDI, EJB, JPA, and Bean Validation in ${product.name.full}. +The `kitchensink-jsp` quickstart is a deployable Maven 3 project and demonstrates how to create a compliant Java EE 7 application using JSP 2.0, EL 2.0, JSTL 1.2, CDI, EJB, JPA, and Bean Validation in Red Hat JBoss Enterprise Application Platform. This example is based on the [kitchensink](../kitchensink/README.md) quickstart, but recreates the presentation tier using JSP and JSTL instead of JSF features. It reuses all other components from the Member Registration template. It also reuses the persistence unit and some sample persistence and transaction code to help you with database access in enterprise Java. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/kitchensink-jsp.war` to the running instance of the server. ## Access the application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Server Log: Expected Warnings and Errors @@ -63,7 +63,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -74,18 +74,18 @@ _Note:_ You will see the following warnings in the server log. You can ignore th This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). You may see the following warnings for the `index.jsp` file when you import this quickstart into JBoss Developer Studio. diff --git a/kitchensink-jsp/pom.xml b/kitchensink-jsp/pom.xml index a69d2cb4c4..f202567d7d 100644 --- a/kitchensink-jsp/pom.xml +++ b/kitchensink-jsp/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml kitchensink-jsp diff --git a/kitchensink-ml-ear/README.html b/kitchensink-ml-ear/README.html new file mode 100644 index 0000000000..49e78a6f6d --- /dev/null +++ b/kitchensink-ml-ear/README.html @@ -0,0 +1,200 @@ + + + kitchensink-ml-ear: Localized Version of the kitchensink-ear Quickstart + + + +

kitchensink-ml-ear: Localized Version of the kitchensink-ear Quickstart

+

Author: Sande Gilda
+Level: Intermediate
+Technologies: CDI, JSF, JPA, EJB, JAX-RS, BV, EAR, i18n, l10n
+Summary: The kitchensink-ml-ear quickstart demonstrates a localized database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The kitchensink-ml-ear quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on Red Hat JBoss Enterprise Application Platform.

+

It demonstrates how to create a localized Java EE 7 compliant application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. A localized application is one that supports multiple languages. That is what the -ml suffix denotes in the quickstart name kitchensink-ml-ear. This quickstart also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java.

+

This quickstart uses the kitchensink-ear quickstart as its starting point. It has been enhanced to provide localization of labels and messages. A user sets the preferred language choice in the browser and, if the application supports that language, the application web page is rendered in that language. For demonstration purposes, this quickstart has been tranlated into French(fr) and Spanish (es) using http://translate.google.com, so the translations may not be ideal.

+

Note: This quickstart uses the H2 database included with JBoss EAP. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

Localization Code Changes

+

The following changes were made to the quickstart to enable it to use the browser preferred locale setting when displaying the web page:

+
    +
  • +

    Properties files were created for the supported languages.

    +
      +
    • +

      This quickstart is localized for Spanish and French. You can add additional language support by creating properties files with the appropriate suffix and populating the properties with translated values.

      +
      • +
    • +

      The JSF resource Bundle is located at `kitchensink-ml-ear-web/src/main/resources/org/jboss/as/quickstarts/kitchensink-ml/bundle/Resources_(es|fr).properties

      +
      • +
    • +

      Messages generated by Java code (e.g. log messages and messages sent to the UI) are internationalized using JBoss Logging. The log messages are accessed via the org.jboss.as.quickstarts.kitchensink.util.KitchensinkMessages interface, and the message bundles are located at: kitchensink-ml-ear-ejb/src/main/resources/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.i18_(es|fr).properties

      +
      • +
    • +

      The message bundle consumed by Bean Validation is located at kitchensink-ml-ear-ejb/src/main/resources/ValidationMessages.properties. This is defined by the bean validation specification.

      +
      • +
    +
    • +
  • +

    The following XML was added to the kitchensink-ml-ear-web/src/main/webapp/WEB-INF/faces-config.xml file. When you create a property file for a new language, you must add the supported locale to this file.

    +
    <application>
+  <locale-config>
+    <default-locale>en</default-locale>
+    <supported-locale>en-US</supported-locale>
+    <supported-locale>fr</supported-locale>
+    <supported-locale>fr-FR</supported-locale>
+    <supported-locale>es</supported-locale>
+    <supported-locale>es-ES</supported-locale>
+  </locale-config>
+  <resource-bundle>
+    <base-name>org/jboss/as/quickstarts/kitchensink_ear/bundle/Resources</base-name>
+    <var>bundle</var>
+  </resource-bundle>
+</application>
+
    +
    • +
  • +

    The kitchensink-ml-ear-ejb/src/main/java/org/jboss/as/quickstarts/kitchensink/model/Member.java file was modififed to add the message key to @Pattern annotation.

    +
     @NotNull
+ @Size(min = 1, max = 25)
+ @Pattern(regexp = "[A-Za-z ]*", message = "{name_validation_message}")
+ private String name;                
+
    +
    • +
  • +

    The kitchensink-ml-ear-ejb/src/main/java/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.java file was created, which defines default messages in English. The jboss-logging-processor will automatically generate an implementation for you, which can be accesssed via the MESSAGES static variable.

    +
    @MessageBundle(projectCode = "")
+public interface KitchensinkMessages {
+
+   KitchensinkMessages MESSAGES = Messages.getBundle(KitchensinkMessages.class, FacesContext.getCurrentInstance().getViewRoot().getLocale());
+
+   @Message("Registered!")
+   String registeredMessage();
+
+   @Message("Successfully registered!")
+   String registerSuccessfulMessage();
+
+   @Message("Registration failed:")
+   String registerFailMessage();
+
+   @Message("Registration failed. See server log for more information.")
+   String defaultErrorMessage();
+}
+
    +
    • +
  • +

    The kitchensink-ml-ear-web/src/main/java/org/jboss/as/quickstarts/kitchensink/controller/MemberController.java file was modified as follows:

    +
      +
    • Messages strings were replaced with strings retrieved using the resource bundle property names. For example: +
      FacesMessage m = new FacesMessage(FacesMessage.SEVERITY_INFO,
+        KitchensinkMessages.MESSAGES.registeredMessage(),
+        KitchensinkMessages.MESSAGES.registerSuccessfulMessage());
+
      +
      • +
    +
    • +
  • +

    The kitchensink-ml-ear-web/src/main/webapp/index.xhtml file were modified.

    +
      +
    • Strings for headers, messages, labels were replaced with the appropriate # {bundle.<property>}, for example: # {bundle.memberWelcomeHeader}.
      • +
    +
    • +
+

Set the Browser Preferred Locale

+

How you set your browser preferred locale depends on the browser and version you use. Use your browser help option to search for instructions to change the preferred language setting.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy kitchensink-ml-ear.ear to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/kitchensink-ml-ear/.

+
    +
  1. Enter a name, email address, and Phone nubmer in the input field and click the Register button.
    2. +
  2. If the data entered is valid, the new member will be registered and added to the Members display list.
    3. +
  3. If the data is not valid, you must fix the validation errors and try again.
    4. +
  4. When the registration is successful, you will see a log message in the server console: +
    Registering _TheNameYouEntered_
+
    +
    5. +
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

You should see the following console output when you run the tests:

+
Results :
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+
+

Investigate the Server Console Output

+

You should see messages similar to the following:

+
INFO  [org.jboss.as.server.deployment] (MSC service thread 1-3) WFLYSRV0027: Starting deployment of "test.war" (runtime-name: "test.war")
+...
+INFO  [org.jboss.as.quickstarts.kitchensink_ear.service.MemberRegistration] (default task-105) Registering Jane Doe
+INFO  [org.jboss.as.quickstarts.kitchensink_ear.test.MemberRegistrationTest] (default task-105) Jane Doe was persisted with id 1
+...
+INFO  [org.jboss.as.server.deployment] (MSC service thread 1-4) WFLYSRV0028: Stopped deployment test.war (runtime-name: test.war) in 18ms
+...
+INFO  [org.jboss.as.server] (management-handler-thread - 26) WFLYSRV0009: Undeployed "test.war" (runtime-name: "test.war")
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

For this quickstart, follow the special instructions to build Quickstarts Containing an EAR

+
    +
  1. Right-click on the kitchensink-ml-ear-web subproject, and choose Run As --> Run on Server.
    2. +
  2. Choose the server and click Finish.
    3. +
  3. This starts the server, deploys the application, and opens a browser window that accesses the running application at http://localhost:8080/kitchensink-ml-ear-web/.
    4. +
  4. To undeploy the project, right-click on the kitchensink-ml-ear-web project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/kitchensink-ml-ear/README.md b/kitchensink-ml-ear/README.md index 7389a5559e..246a7c3653 100644 --- a/kitchensink-ml-ear/README.md +++ b/kitchensink-ml-ear/README.md @@ -4,20 +4,20 @@ Author: Sande Gilda Level: Intermediate Technologies: CDI, JSF, JPA, EJB, JAX-RS, BV, EAR, i18n, l10n Summary: The `kitchensink-ml-ear` quickstart demonstrates a localized database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `kitchensink-ml-ear` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on ${product.name.full}. +The `kitchensink-ml-ear` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on Red Hat JBoss Enterprise Application Platform. It demonstrates how to create a _localized_ Java EE 7 compliant application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. A localized application is one that supports multiple languages. That is what the _-ml_ suffix denotes in the quickstart name _kitchensink-ml-ear_. This quickstart also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. This quickstart uses the [kitchensink-ear](../kitchensink-ear/README.md) quickstart as its starting point. It has been enhanced to provide localization of labels and messages. A user sets the preferred language choice in the browser and, if the application supports that language, the application web page is rendered in that language. For demonstration purposes, this quickstart has been tranlated into French(fr) and Spanish (es) using , so the translations may not be ideal. -_Note: This quickstart uses the H2 database included with ${product.name}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with JBoss EAP. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ### Localization Code Changes @@ -27,13 +27,13 @@ The following changes were made to the quickstart to enable it to use the browse * This quickstart is localized for Spanish and French. You can add additional language support by creating properties files with the appropriate suffix and populating the properties with translated values. - * The JSF resource Bundle is located at `${project.artifactId}-web/src/main/resources/org/jboss/as/quickstarts/kitchensink-ml/bundle/Resources_(es|fr).properties + * The JSF resource Bundle is located at `kitchensink-ml-ear-web/src/main/resources/org/jboss/as/quickstarts/kitchensink-ml/bundle/Resources_(es|fr).properties - * Messages generated by Java code (e.g. log messages and messages sent to the UI) are internationalized using JBoss Logging. The log messages are accessed via the `org.jboss.as.quickstarts.kitchensink.util.KitchensinkMessages` interface, and the message bundles are located at: `${project.artifactId}-ejb/src/main/resources/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.i18_(es|fr).properties` + * Messages generated by Java code (e.g. log messages and messages sent to the UI) are internationalized using JBoss Logging. The log messages are accessed via the `org.jboss.as.quickstarts.kitchensink.util.KitchensinkMessages` interface, and the message bundles are located at: `kitchensink-ml-ear-ejb/src/main/resources/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.i18_(es|fr).properties` - * The message bundle consumed by Bean Validation is located at `${project.artifactId}-ejb/src/main/resources/ValidationMessages.properties`. This is defined by the bean validation specification. + * The message bundle consumed by Bean Validation is located at `kitchensink-ml-ear-ejb/src/main/resources/ValidationMessages.properties`. This is defined by the bean validation specification. -* The following XML was added to the `${project.artifactId}-web/src/main/webapp/WEB-INF/faces-config.xml` file. When you create a property file for a new language, you must add the supported locale to this file. +* The following XML was added to the `kitchensink-ml-ear-web/src/main/webapp/WEB-INF/faces-config.xml` file. When you create a property file for a new language, you must add the supported locale to this file. @@ -50,14 +50,14 @@ The following changes were made to the quickstart to enable it to use the browse -* The `${project.artifactId}-ejb/src/main/java/org/jboss/as/quickstarts/kitchensink/model/Member.java` file was modififed to add the message key to @Pattern annotation. +* The `kitchensink-ml-ear-ejb/src/main/java/org/jboss/as/quickstarts/kitchensink/model/Member.java` file was modififed to add the message key to @Pattern annotation. @NotNull @Size(min = 1, max = 25) @Pattern(regexp = "[A-Za-z ]*", message = "{name_validation_message}") private String name; -* The `${project.artifactId}-ejb/src/main/java/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.java` file was created, which defines default messages in English. The `jboss-logging-processor` will automatically generate an implementation for you, which can be accesssed via the `MESSAGES` static variable. +* The `kitchensink-ml-ear-ejb/src/main/java/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.java` file was created, which defines default messages in English. The `jboss-logging-processor` will automatically generate an implementation for you, which can be accesssed via the `MESSAGES` static variable. @MessageBundle(projectCode = "") public interface KitchensinkMessages { @@ -77,7 +77,7 @@ The following changes were made to the quickstart to enable it to use the browse String defaultErrorMessage(); } -* The `${project.artifactId}-web/src/main/java/org/jboss/as/quickstarts/kitchensink/controller/MemberController.java` file was modified as follows: +* The `kitchensink-ml-ear-web/src/main/java/org/jboss/as/quickstarts/kitchensink/controller/MemberController.java` file was modified as follows: * Messages strings were replaced with strings retrieved using the resource bundle property names. For example: @@ -85,7 +85,7 @@ The following changes were made to the quickstart to enable it to use the browse KitchensinkMessages.MESSAGES.registeredMessage(), KitchensinkMessages.MESSAGES.registerSuccessfulMessage()); -* The `${project.artifactId}-web/src/main/webapp/index.xhtml` file were modified. +* The `kitchensink-ml-ear-web/src/main/webapp/index.xhtml` file were modified. * Strings for headers, messages, labels were replaced with the appropriate `# {bundle.}`, for example: `# {bundle.memberWelcomeHeader}`. @@ -96,39 +96,39 @@ How you set your browser preferred locale depends on the browser and version you ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `${project.artifactId}.ear` to the running instance of the server. +4. This will deploy `kitchensink-ml-ear.ear` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . 1. Enter a name, email address, and Phone nubmer in the input field and click the _Register_ button. 2. If the data entered is valid, the new member will be registered and added to the _Members_ display list. @@ -148,7 +148,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -159,13 +159,13 @@ _Note:_ You will see the following warnings in the server log. You can ignore th This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -191,14 +191,14 @@ You should see messages similar to the following: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). For this quickstart, follow the special instructions to build [Quickstarts Containing an EAR](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-ear-project) -1. Right-click on the `${project.artifactId}-web` subproject, and choose `Run As` --> `Run on Server`. +1. Right-click on the `kitchensink-ml-ear-web` subproject, and choose `Run As` --> `Run on Server`. 2. Choose the server and click `Finish`. -3. This starts the server, deploys the application, and opens a browser window that accesses the running application at . -4. To undeploy the project, right-click on the `${project.artifactId}-web` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +3. This starts the server, deploys the application, and opens a browser window that accesses the running application at . +4. To undeploy the project, right-click on the `kitchensink-ml-ear-web` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. ## Debug the Application diff --git a/kitchensink-ml-ear/ear/pom.xml b/kitchensink-ml-ear/ear/pom.xml index b41f3439db..98f5ebe1e5 100644 --- a/kitchensink-ml-ear/ear/pom.xml +++ b/kitchensink-ml-ear/ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts kitchensink-ml-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA kitchensink-ml-ear-ear ear diff --git a/kitchensink-ml-ear/ejb/pom.xml b/kitchensink-ml-ear/ejb/pom.xml index 9578fa5bc7..9d9f21d26e 100644 --- a/kitchensink-ml-ear/ejb/pom.xml +++ b/kitchensink-ml-ear/ejb/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts kitchensink-ml-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA kitchensink-ml-ear-ejb ejb diff --git a/kitchensink-ml-ear/pom.xml b/kitchensink-ml-ear/pom.xml index 486b96d2bb..773b044e9f 100644 --- a/kitchensink-ml-ear/pom.xml +++ b/kitchensink-ml-ear/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml kitchensink-ml-ear diff --git a/kitchensink-ml-ear/web/pom.xml b/kitchensink-ml-ear/web/pom.xml index c984607a1d..27fd6081de 100644 --- a/kitchensink-ml-ear/web/pom.xml +++ b/kitchensink-ml-ear/web/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts kitchensink-ml-ear - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA kitchensink-ml-ear-web war diff --git a/kitchensink-ml/README.html b/kitchensink-ml/README.html new file mode 100644 index 0000000000..33dcfaea93 --- /dev/null +++ b/kitchensink-ml/README.html @@ -0,0 +1,169 @@ + + + kitchensink-ml: Localized Version of the kitchensink Quickstart + + + +

kitchensink-ml: Localized Version of the kitchensink Quickstart

+

Author: Sande Gilda
+Level: Intermediate
+Technologies: CDI, JSF, JPA, EJB, JAX-RS, BV, i18n, l10n
+Summary: The kitchensink-ml quickstart demonstrates a localized Java EE 7 compliant application using JSF, CDI, EJB, JPA, and Bean Validation.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The kitchensink-ml quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on Red Hat JBoss Enterprise Application Platform.

+

It demonstrates how to create a localized Java EE 7 compliant application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. A localized application is one that supports multiple languages. That is what the -ml suffix denotes in the quickstart name kitchensink-ml. This quickstart also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java.

+

This quickstart uses the kitchensink quickstart as its starting point. It has been enhanced to provide localization of labels and messages. A user sets the preferred language choice in the browser and, if the application supports that language, the application web page is rendered in that language. For demonstration purposes, this quickstart has been tranlated into French(fr) and Spanish (es) using http://translate.google.com, so the translations may not be ideal.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

Localization Code Changes

+

The following changes were made to the quickstart to enable it to use the browser preferred locale setting when displaying the web page:

+
    +
  • +

    Properties files were created for the supported languages.

    +
      +
    • +

      This quickstart is localized for Spanish and French. You can add additional language support by creating properties files with the appropriate suffix and populating the properties with translated values.

      +
      • +
    • +

      The JSF resource Bundle is located at `src/main/resources/org/jboss/as/quickstarts/kitchensink/bundle/Resources_(es|fr).properties

      +
      • +
    • +

      Messages generated by Java code (e.g. log messages and messages sent to the UI) are internationalized using JBoss Logging. The log messages are accessed via the org.jboss.as.quickstarts.kitchensink.util.KitchensinkMessages interface, and the message bundles are located at: src/main/resources/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.i18_(es|fr).properties

      +
      • +
    • +

      The message bundle consumed by Bean Validation is located at src/main/resources/ValidationMessages.properties. This is defined by the bean validation specification.

      +
      • +
    +
    • +
  • +

    The following XML was added to the src/main/webapp/WEB-INF/faces-config.xml file. When you create a property file for a new language, you must add the supported locale to this file.

    +
    <application>
+  <locale-config>
+    <default-locale>en</default-locale>
+    <supported-locale>en-US</supported-locale>
+    <supported-locale>fr</supported-locale>
+    <supported-locale>fr-FR</supported-locale>
+    <supported-locale>es</supported-locale>
+    <supported-locale>es-ES</supported-locale>
+  </locale-config>
+  <resource-bundle>
+    <base-name>org/jboss/as/quickstarts/kitchensink/bundle/Resources</base-name>
+    <var>bundle</var>
+  </resource-bundle>
+</application>
+
    +
    • +
  • +

    The src/main/java/org/jboss/as/quickstarts/kitchensink/model/Member.java file was modififed to add the message key to @Pattern annotation.

    +
     @NotNull
+ @Size(min = 1, max = 25)
+ @Pattern(regexp = "[A-Za-z ]*", message = "{name_validation_message}")
+ private String name;                
+
    +
    • +
  • +

    The src/main/java/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.java file was created, which defines default messages in English. The jboss-logging-processor will automatically generate an implementation for you, which can be accesssed via the MESSAGES static variable.

    +
    @MessageBundle(projectCode = "")
+public interface KitchensinkMessages {
+
+   KitchensinkMessages MESSAGES = Messages.getBundle(KitchensinkMessages.class, FacesContext.getCurrentInstance().getViewRoot().getLocale());
+
+   @Message("Registered!")
+   String registeredMessage();
+
+   @Message("Successfully registered!")
+   String registerSuccessfulMessage();
+
+   @Message("Registration failed:")
+   String registerFailMessage();
+
+   @Message("Registration failed. See server log for more information.")
+   String defaultErrorMessage();
+}
+
    +
    • +
  • +

    The src/main/java/org/jboss/as/quickstarts/kitchensink/controller/MemberController.java file was modified as follows:

    +
      +
    • Messages strings were replaced with strings retrieved using the resource bundle property names. For example: +
      FacesMessage m = new FacesMessage(FacesMessage.SEVERITY_INFO,
+        KitchensinkMessages.MESSAGES.registeredMessage(),
+        KitchensinkMessages.MESSAGES.registerSuccessfulMessage());
+
      +
      • +
    +
    • +
  • +

    The src/main/webapp/index.xhtml file were modified.

    +
      +
    • Strings for headers, messages, labels were replaced with the appropriate # {bundle.<property>}, for example: # {bundle.memberWelcomeHeader}.
      • +
    +
    • +
+

Set the Browser Preferred Locale

+

How you set your browser preferred locale depends on the browser and version you use. Use your browser help option to search for instructions to change the preferred language setting.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/kitchensink-ml.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/kitchensink-ml/.

+

Change your browser preferred language to French or Spanish and refresh the page to see it displayed in the new language.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/kitchensink-ml/README.md b/kitchensink-ml/README.md index 0b41ff1219..2ba00a37d5 100644 --- a/kitchensink-ml/README.md +++ b/kitchensink-ml/README.md @@ -4,20 +4,20 @@ Author: Sande Gilda Level: Intermediate Technologies: CDI, JSF, JPA, EJB, JAX-RS, BV, i18n, l10n Summary: The `kitchensink-ml` quickstart demonstrates a localized Java EE 7 compliant application using JSF, CDI, EJB, JPA, and Bean Validation. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `kitchensink-ml` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on ${product.name.full}. +The `kitchensink-ml` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on Red Hat JBoss Enterprise Application Platform. It demonstrates how to create a _localized_ Java EE 7 compliant application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. A localized application is one that supports multiple languages. That is what the _-ml_ suffix denotes in the quickstart name _kitchensink-ml_. This quickstart also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. This quickstart uses the [kitchensink](../kitchensink/README.md) quickstart as its starting point. It has been enhanced to provide localization of labels and messages. A user sets the preferred language choice in the browser and, if the application supports that language, the application web page is rendered in that language. For demonstration purposes, this quickstart has been tranlated into French(fr) and Spanish (es) using , so the translations may not be ideal. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ### Localization Code Changes @@ -97,39 +97,39 @@ How you set your browser preferred locale depends on the browser and version you ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/kitchensink-ml.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . Change your browser preferred language to French or Spanish and refresh the page to see it displayed in the new language. @@ -144,7 +144,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -155,18 +155,18 @@ _Note:_ You will see the following warnings in the server log. You can ignore th This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/kitchensink-ml/pom.xml b/kitchensink-ml/pom.xml index c00ddb7a73..06484ebab6 100644 --- a/kitchensink-ml/pom.xml +++ b/kitchensink-ml/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml kitchensink-ml diff --git a/kitchensink/README.html b/kitchensink/README.html new file mode 100644 index 0000000000..117831271c --- /dev/null +++ b/kitchensink/README.html @@ -0,0 +1,80 @@ + + + kitchensink: Assortment of technologies including Arquillian + + + +

kitchensink: Assortment of technologies including Arquillian

+

Author: Pete Muir
+Level: Intermediate
+Technologies: CDI, JSF, JPA, EJB, JAX-RS, BV
+Summary: The kitchensink quickstart demonstrates a Java EE 7 web-enabled database application using JSF, CDI, EJB, JPA, and Bean Validation.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The kitchensink quickstart is a deployable Maven 3 project designed to help you get your foot in the door developing with Java EE 7 on Red Hat JBoss Enterprise Application Platform.

+

It demonstrates how to create a compliant Java EE 7 application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. It also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/kitchensink.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/kitchensink/.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/kitchensink/README.md b/kitchensink/README.md index 1c5c0accad..a3425e2d2c 100644 --- a/kitchensink/README.md +++ b/kitchensink/README.md @@ -4,54 +4,54 @@ Author: Pete Muir Level: Intermediate Technologies: CDI, JSF, JPA, EJB, JAX-RS, BV Summary: The `kitchensink` quickstart demonstrates a Java EE 7 web-enabled database application using JSF, CDI, EJB, JPA, and Bean Validation. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `kitchensink` quickstart is a deployable Maven 3 project designed to help you get your foot in the door developing with Java EE 7 on ${product.name.full}. +The `kitchensink` quickstart is a deployable Maven 3 project designed to help you get your foot in the door developing with Java EE 7 on Red Hat JBoss Enterprise Application Platform. It demonstrates how to create a compliant Java EE 7 application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. It also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/kitchensink.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Server Log: Expected Warnings and Errors @@ -65,7 +65,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -76,18 +76,18 @@ _Note:_ You will see the following warnings in the server log. You can ignore th This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/kitchensink/pom.xml b/kitchensink/pom.xml index 7bffeb52bb..fff42b876a 100644 --- a/kitchensink/pom.xml +++ b/kitchensink/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml kitchensink diff --git a/log4j/README.html b/log4j/README.html new file mode 100644 index 0000000000..7ddc2a10c8 --- /dev/null +++ b/log4j/README.html @@ -0,0 +1,62 @@ + + + log4j: Define a Module Dependency and Use log4j in an Application + + + +

log4j: Define a Module Dependency and Use log4j in an Application

+

Author: Bartosz Baranowski
+Level: Beginner
+Technologies: JBoss Modules
+Summary: The log4j quickstart demonstrates how to use container defined modules to add dependencies on 3rd party libraries and limit the application package size.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The log4j quickstart is a simple JSF application that shows how to use container defined modules to limit the size of the application package in Red Hat JBoss Enterprise Application Platform. It also shows how to use common versions of certain classes at runtime.

+

Applications must often depend on third-party libraries. By default, Java EE packages allow you to include dependencies in a deployable unit which can lead to uncontrolled growth of the deployable unit. This can be avoided by the use of container defined modules. A module is nothing more than a container managed binary dependency which is shared by all deployed applications.

+

This example is very simple. It declares dependency on the Apache Log4j module which allows it to use a custom logging framework. This is achieved with a simple addition to the xml file: src/main/webapp/WEB-INF/jboss-deployment-structure.xml. This file and modular class loading are described in more detail in the Red Hat JBoss Enterprise Application Platform documentation.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/log4j.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/log4j/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/log4j/README.md b/log4j/README.md index 2b11c4e04a..59df212885 100644 --- a/log4j/README.md +++ b/log4j/README.md @@ -4,58 +4,58 @@ Author: Bartosz Baranowski Level: Beginner Technologies: JBoss Modules Summary: The `log4j` quickstart demonstrates how to use container defined modules to add dependencies on 3rd party libraries and limit the application package size. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `log4j` quickstart is a simple JSF application that shows how to use container defined modules to limit the size of the application package in ${product.name.full}. It also shows how to use common versions of certain classes at runtime. +The `log4j` quickstart is a simple JSF application that shows how to use container defined modules to limit the size of the application package in Red Hat JBoss Enterprise Application Platform. It also shows how to use common versions of certain classes at runtime. Applications must often depend on third-party libraries. By default, Java EE packages allow you to include dependencies in a deployable unit which can lead to uncontrolled growth of the deployable unit. This can be avoided by the use of container defined modules. A module is nothing more than a container managed binary dependency which is shared by all deployed applications. -This example is very simple. It declares dependency on the Apache Log4j module which allows it to use a custom logging framework. This is achieved with a simple addition to the xml file: `src/main/webapp/WEB-INF/jboss-deployment-structure.xml`. This file and modular class loading are described in more detail in the [${product.name.full}](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) documentation. +This example is very simple. It declares dependency on the Apache Log4j module which allows it to use a custom logging framework. This is achieved with a simple addition to the xml file: `src/main/webapp/WEB-INF/jboss-deployment-structure.xml`. This file and modular class loading are described in more detail in the [Red Hat JBoss Enterprise Application Platform](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) documentation. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/log4j.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -63,7 +63,7 @@ The application will be running at the following URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml log4j diff --git a/logging-tools/README.html b/logging-tools/README.html new file mode 100644 index 0000000000..afd0d223a7 --- /dev/null +++ b/logging-tools/README.html @@ -0,0 +1,129 @@ + + + logging-tools: Internationalization and Localization with JBoss Logging Tools + + + +

logging-tools: Internationalization and Localization with JBoss Logging Tools

+

Author: Darrin Mison
+Level: Beginner
+Technologies: JBoss Logging Tools
+Summary: The logging-tools quickstart shows how to use JBoss Logging Tools to create internationalized loggers, exceptions, and messages and localize them.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The logging-tools quickstart demonstrates the use of JBoss Logging Tools in Red Hat JBoss Enterprise Application Platform. The logging tools create internationalized loggers, exceptions, and generic messages; and then provide localizations for them. This is done using a simple JAX-RS service. Translations in French(fr-FR), German(de-DE), and Swedish (sv-SE) are provided courtesy of http://translate.google.com for demonstration. My apologies if they are less than ideal translations.

+

Once the quick start is deployed you can access it using URLs documented below.

+

Instructions are included below for starting JBoss EAP with a different locale than the system default.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Configure the Server to Start With a Different Locale (Optional)

+

To start the JBoss EAP server with a different locale than the system default:

+
    +
  1. Make a backup copy of the EAP7_HOME/bin/standalone.conf file.
    2. +
  2. Edit the file and append commands to set the JVM parameters for the required country and language. The following example sets the country to Germany (DE) and the language to German (de). +
    JAVA_OPTS="$JAVA_OPTS -Duser.country=DE"
+JAVA_OPTS="$JAVA_OPTS -Duser.language=de"
+
    +
    3. +
+

This can be done as a single line if you prefer:

+
    JAVA_OPTS="$JAVA_OPTS -Duser.country=DE -Duser.language=de"   
+
+

For more information about internationalization and localization, see http://www.oracle.com/technetwork/java/javase/tech/intl-139810.html.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/logging-tools.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/logging-tools/

+

This landing page provides details and links to test the quickstart features. You can also directly access the following URLs.

+
    +
  1. +

    http://localhost:8080/logging-tools/rest/greetings/'name'

    +
      +
    • Example: http://localhost:8080/logging-tools/rest/greetings/Harold
      • +
    • Demonstrates simple use of localized messages (with parameter) and logging.
      • +
    • It returns the localized hello NAME string where NAME is the last component of the URL.
      • +
    • It also logs the localized Hello message sent in the server log.
      • +
    +
    2. +
  2. +

    http://localhost:8080/logging-tools/rest/greetings/'locale'/'name'

    +
      +
    • Example: http://localhost:8080/logging-tools/rest/greetings/fr-FR/Harold
      • +
    • Demonstrates how to obtain a message bundle for a specified locale and how to throw a localized exceptions. Note that the localized exception is a wrapper around WebApplicationException.
      • +
    • Returns a localized hello NAME string where NAME is the last component of the URL and the locale used is the one supplied in the locale URL.
      • +
    • Logs a localized Hello message sent in LOCALE message using the JVM locale for the translation.
      • +
    • If the supplied locale is invalid (in this case if it contains more than 3 components, eg. fr-FR-POSIX-FOO), it throws a WebApplicationException (404) using a localizable sub-class of WebApplicationException.
      • +
    +

    Note that WebApplicationException cannot be directly localized by JBoss Logging Tools using the @Message annotation due to the message parameter being ignored by the WebApplicationException constructors. Cases like this can be worked around by creating a subclass with a constructor that does deal with the message parameter.

    +
    3. +
  3. +

    http://localhost:8080/logging-tools/rest/greetings/crashme

    +
      +
    • Demonstrates how to throw a localized exception with another exception specified as the cause. This is a completely contrived example.
      • +
    • Attempts to divide by zero, catches the exception, and throws the localized one.
      • +
    +
    4. +
  4. +

    http://localhost:8080/logging-tools/rest/dates/daysuntil/'targetdate'

    +
      +
    • Example: http://localhost:8080/logging-tools/rest/dates/daysuntil/2020-12-25
      • +
    • Demonstrates how to pass parameters through to the constructor of a localized exception, and how to specify an exception as a cause of a log message.
      • +
    • Attempts to turn the targetdate URL component into a date object using the format yyyy-MM-dd
      • +
    • Returns number of days (as an integer) until that date
      • +
    • If the targetdate is invalid, for example, http://localhost:8080/logging-tools/rest/dates/daysuntil/2015-02-31: +
        +
      • Catches the ParseException
        • +
      • Creates a localized ParseException passing values from the caught exception as parameters to its constructor
        • +
      • Logs a localized message with the localized exception as the cause
        • +
      • Throws a WebApplicationException(400) with the text from the localized ParseException
        • +
      +
      • +
    +
    5. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

You may see the following warning when you import this quickstart into JBoss Developer Studio. You can ignore this warning as it occurs in a generated file.

+
    The import org.jboss.as.quickstarts.loggingToolsQS.exceptions.LocaleInvalidException is never used
+    GreeterExceptionBundle_$bundle.java
+    /logging-tools/target/generated-sources/annotations/org/jboss/as/quickstarts/loggingToolsQS/exceptions	line 8
+    Java Problem
+
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
  mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/logging-tools/README.md b/logging-tools/README.md index 6959710579..73da5e0e83 100644 --- a/logging-tools/README.md +++ b/logging-tools/README.md @@ -4,35 +4,35 @@ Author: Darrin Mison Level: Beginner Technologies: JBoss Logging Tools Summary: The `logging-tools` quickstart shows how to use JBoss Logging Tools to create internationalized loggers, exceptions, and messages and localize them. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `logging-tools` quickstart demonstrates the use of JBoss Logging Tools in ${product.name.full}. The logging tools create internationalized loggers, exceptions, and generic messages; and then provide localizations for them. This is done using a simple JAX-RS service. Translations in French(fr-FR), German(de-DE), and Swedish (sv-SE) are provided courtesy of for demonstration. My apologies if they are less than ideal translations. +The `logging-tools` quickstart demonstrates the use of JBoss Logging Tools in Red Hat JBoss Enterprise Application Platform. The logging tools create internationalized loggers, exceptions, and generic messages; and then provide localizations for them. This is done using a simple JAX-RS service. Translations in French(fr-FR), German(de-DE), and Swedish (sv-SE) are provided courtesy of for demonstration. My apologies if they are less than ideal translations. Once the quick start is deployed you can access it using URLs documented below. -Instructions are included below for starting ${product.name} with a different locale than the system default. +Instructions are included below for starting JBoss EAP with a different locale than the system default. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Configure the Server to Start With a Different Locale (Optional) -To start the ${product.name} server with a different locale than the system default: +To start the JBoss EAP server with a different locale than the system default: -1. Make a backup copy of the `${jboss.home.name}/bin/standalone.conf` file. +1. Make a backup copy of the `EAP7_HOME/bin/standalone.conf` file. 2. Edit the file and append commands to set the JVM parameters for the required country and language. The following example sets the country to Germany (`DE`) and the language to German (`de`). @@ -46,38 +46,38 @@ To start the ${product.name} server with a different locale than the system defa ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/logging-tools.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: +The application will be running at the following URL: This landing page provides details and links to test the quickstart features. You can also directly access the following URLs. -1. `http://localhost:8080/${project.artifactId}/rest/greetings/'name'` - * Example: +1. `http://localhost:8080/logging-tools/rest/greetings/'name'` + * Example: * Demonstrates simple use of localized messages (with parameter) and logging. * It returns the localized `hello NAME` string where `NAME` is the last component of the URL. * It also logs the localized `Hello message sent` in the server log. -2. `http://localhost:8080/${project.artifactId}/rest/greetings/'locale'/'name'` - * Example: +2. `http://localhost:8080/logging-tools/rest/greetings/'locale'/'name'` + * Example: * Demonstrates how to obtain a message bundle for a specified locale and how to throw a localized exceptions. Note that the localized exception is a wrapper around `WebApplicationException`. * Returns a localized `hello NAME` string where `NAME` is the last component of the URL and the locale used is the one supplied in the `locale` URL. * Logs a localized `Hello message sent in LOCALE` message using the JVM locale for the translation. @@ -85,16 +85,16 @@ This landing page provides details and links to test the quickstart features. Yo Note that `WebApplicationException` cannot be directly localized by JBoss Logging Tools using the `@Message` annotation due to the message parameter being ignored by the `WebApplicationException` constructors. Cases like this can be worked around by creating a subclass with a constructor that does deal with the message parameter. -3. +3. * Demonstrates how to throw a localized exception with another exception specified as the cause. This is a completely contrived example. * Attempts to divide by zero, catches the exception, and throws the localized one. -4. `http://localhost:8080/${project.artifactId}/rest/dates/daysuntil/'targetdate'` - * Example: +4. `http://localhost:8080/logging-tools/rest/dates/daysuntil/'targetdate'` + * Example: * Demonstrates how to pass parameters through to the constructor of a localized exception, and how to specify an exception as a cause of a log message. * Attempts to turn the `targetdate` URL component into a date object using the format `yyyy-MM-dd` * Returns number of days (as an integer) until that date - * If the `targetdate` is invalid, for example, : + * If the `targetdate` is invalid, for example, : * Catches the `ParseException` * Creates a localized `ParseException` passing values from the caught exception as parameters to its constructor * Logs a localized message with the localized exception as the cause @@ -103,7 +103,7 @@ This landing page provides details and links to test the quickstart features. Yo ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -111,13 +111,13 @@ This landing page provides details and links to test the quickstart features. Yo ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). You may see the following warning when you import this quickstart into JBoss Developer Studio. You can ignore this warning as it occurs in a generated file. The import org.jboss.as.quickstarts.loggingToolsQS.exceptions.LocaleInvalidException is never used GreeterExceptionBundle_$bundle.java - /${project.artifactId}/target/generated-sources/annotations/org/jboss/as/quickstarts/loggingToolsQS/exceptions line 8 + /logging-tools/target/generated-sources/annotations/org/jboss/as/quickstarts/loggingToolsQS/exceptions line 8 Java Problem diff --git a/logging-tools/pom.xml b/logging-tools/pom.xml index 01e01c31a1..263c033c9b 100644 --- a/logging-tools/pom.xml +++ b/logging-tools/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml logging-tools diff --git a/logging/README.html b/logging/README.html new file mode 100644 index 0000000000..2aab43d557 --- /dev/null +++ b/logging/README.html @@ -0,0 +1,268 @@ + + + logging: Example That Sets Up Different Logging Levels + + + +

logging: Example That Sets Up Different Logging Levels

+

Author: Joel Tosi
+Level: Intermediate
+Technologies: Logging
+Summary: The logging quickstart demonstrates how to configure different logging levels in JBoss EAP. It also includes an asynchronous logging example.
+Prerequisites: None
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The logging quickstart demonstrates how to set up and log different levels of information in Red Hat JBoss Enterprise Application Platform. An example of asynchronous logging is also included in the configuration examples.

+

This quickstart contains just one class file and one JSP file. When you access the application, it fires off the logging information.

+

To better visualize how the logging configuration works, you first deploy and access the application before configuring the logs and view the resulting log files. Then you configure the logs, redeploy and access the application, and look at the log files again to see the differences.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the JBoss EAP server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This deploys target/logging.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application is running at the following URL: http://localhost:8080/logging/.

+

You will see the following message in the server console:

+
    FATAL [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS A FATAL MESSAGE
+    ERROR [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS AN ERROR MESSAGE
+    WARN  [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS A WARNING MESSAGE
+    INFO  [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS AN INFO MESSAGE
+    ERROR [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS AN ERROR MESSAGE
+    FATAL [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS A FATAL MESSAGE
+    INFO  [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS AN INFO MESSAGE
+    WARN  [org.jboss.as.quickstarts.logging.LoggingExample] (default task-1) THIS IS A WARNING MESSAGE
+
+

Check the Server Logs

+

The log files are located in the EAP7_HOME/standalone/log log directory. At this point you should see the following log files.

+
    * `server.log` - This is the standard log produced by the application server. By default, it contains all the server log messages, including the server startup messages.
+    * `gc.log.0.current` - This is a garbage collection log. It contains garbage collection activity and can be used for diagnostic purposes. This log can be ignored as it is not used in this quickstart.
+
+

Configure the Server

+

You configure server logging by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-logging.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-logging.cli file in the root of this quickstart directory. This script configures the logging subsytem in the server configuration file. It configures the periodic rotating file handlers and the async handlers, creates the logger for our quickstart class and sets the level to TRACE, and assigns the async handlers for our quickstart class.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-logging.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-logging.cli
+
    +
    5. +
+

You should see the following result when you run the script:

+
    The batch executed successfully
+
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+

The following XML was added to the logging subsystem.

+
    <async-handler name="TRACE_QS_ASYNC">
+        <level name="TRACE"/>
+        <queue-length value="1024"/>
+        <overflow-action value="block"/>
+        <subhandlers>
+            <handler name="FILE_QS_TRACE"/>
+        </subhandlers>
+    </async-handler>
+    <async-handler name="DEBUG_QS_ASYNC">
+        <level name="DEBUG"/>
+        <queue-length value="1024"/>
+        <overflow-action value="block"/>
+        <subhandlers>
+            <handler name="FILE_QS_DEBUG"/>
+        </subhandlers>
+    </async-handler>
+    <async-handler name="INFO_QS_ASYNC">
+        <level name="INFO"/>
+        <queue-length value="1024"/>
+        <overflow-action value="block"/>
+        <subhandlers>
+            <handler name="FILE_QS_INFO"/>
+        </subhandlers>
+    </async-handler>
+    <async-handler name="WARN_QS_ASYNC">
+        <level name="WARN"/>
+        <queue-length value="1024"/>
+        <overflow-action value="block"/>
+        <subhandlers>
+            <handler name="FILE_QS_WARN"/>
+        </subhandlers>
+    </async-handler>
+    <async-handler name="ERROR_QS_ASYNC">
+        <level name="ERROR"/>
+        <queue-length value="1024"/>
+        <overflow-action value="block"/>
+        <subhandlers>
+            <handler name="FILE_QS_ERROR"/>
+        </subhandlers>
+    </async-handler>
+    <async-handler name="FATAL_QS_ASYNC">
+        <level name="FATAL"/>
+        <queue-length value="1024"/>
+        <overflow-action value="block"/>
+        <subhandlers>
+            <handler name="FILE_QS_FATAL"/>
+        </subhandlers>
+    </async-handler>
+    ...
+    <periodic-rotating-file-handler name="FILE_QS_TRACE">
+        <file relative-to="jboss.server.log.dir" path="quickstart.trace.log"/>
+        <suffix value=".yyyy.MM.dd"/>
+    </periodic-rotating-file-handler>
+    <periodic-rotating-file-handler name="FILE_QS_DEBUG">
+        <file relative-to="jboss.server.log.dir" path="quickstart.debug.log"/>
+        <suffix value=".yyyy.MM.dd"/>
+    </periodic-rotating-file-handler>
+    <periodic-rotating-file-handler name="FILE_QS_INFO">
+        <file relative-to="jboss.server.log.dir" path="quickstart.info.log"/>
+        <suffix value=".yyyy.MM.dd"/>
+    </periodic-rotating-file-handler>
+    <periodic-rotating-file-handler name="FILE_QS_WARN">
+        <file relative-to="jboss.server.log.dir" path="quickstart.warn.log"/>
+        <suffix value=".yyyy.MM.dd"/>
+    </periodic-rotating-file-handler>
+    <periodic-rotating-file-handler name="FILE_QS_ERROR">
+        <file relative-to="jboss.server.log.dir" path="quickstart.error.log"/>
+        <suffix value=".yyyy.MM.dd"/>
+    </periodic-rotating-file-handler>
+    <periodic-rotating-file-handler name="FILE_QS_FATAL">
+        <file relative-to="jboss.server.log.dir" path="quickstart.fatal.log"/>
+        <suffix value=".yyyy.MM.dd"/>
+    </periodic-rotating-file-handler>
+    ...
+    <logger category="org.jboss.as.quickstarts.logging">
+        <level name="TRACE"/>
+        <handlers>
+            <handler name="TRACE_QS_ASYNC"/>
+            <handler name="DEBUG_QS_ASYNC"/>
+            <handler name="INFO_QS_ASYNC"/>
+            <handler name="WARN_QS_ASYNC"/>
+            <handler name="ERROR_QS_ASYNC"/>
+            <handler name="FATAL_QS_ASYNC"/>
+        </handlers>
+    </logger>
+
+

Test the New Logging Configuration

+
    +
  1. If your server is not started, then Start the JBoss EAP server.
    2. +
  2. Build and deploy the quickstart.
    3. +
  3. Access the application.
    4. +
+

Recheck the Server Logs

+

The log files are located in the EAP7_HOME/standalone/log log directory. You should now see 8 log files.

+
    +
  • +

    The following logs are the standard log files produced by the application server:

    +
      +
    • server.log - The standard log produced by the application server.
      • +
    • gc.log.0.current - The garbage collection log can be ignored as it is not used in this quickstart.
      • +
    +
    • +
  • +

    The following logs are produced by the quickstart. They are listed below in hierarchical order from the largest file containing the most messages to the smallest file containing the least messages.

    +
      +
    • quickstart.trace.log
      • +
    • quickstart.debug.log
      • +
    • quickstart.info.log
      • +
    • quickstart.warn.log
      • +
    • quickstart.error.log
      • +
    • quickstart.fatal.log
      • +
    +
    • +
+

The following describes what happens when you access this quickstart:

+
    +
  1. The application class file fires off logs of the various types (INFO, DEBUG, TRACE, WARN, ERROR, FATAL). Each log message goes to a different file, as defined in the standalone.xml file. Also notice in the standalone.xml that the application package defines its own log level.
    2. +
  2. The class file demonstrates the usage of log guards. Log guards are a development best practice. Simply put, instead of just writing out logs, we wrap the log writes in a check for that log level being enabled. While this may seem like overhead, that boolean check is more efficient than relying on the underlying framework to do the check at write time.
    3. +
  3. Finally, the class file logs various levels, each to its own file as configured in standalone.xml. Note that log levels are hierarchical. When set, all log levels above the specified level are logged as well.
    4. +
  4. Common uses of the 6 log levels are outlined below. You should use the level that makes the most sense in your environment. +
    FATAL - Used to track critical system failures.  When this log message is written, it is writing application error that has caused service to cease.  This is the most narrow logging.  
+ERROR - Used to track application errors that may cause one request to fail (not a service ceasement).
+WARN - This is setting is used in most production environments.  At this level, all *WARN*, *ERROR*, and *FATAL* messages are written.  Use this level message  as a predictive measure for possible forthcoming issues.  
+INFO - Usually only used in a development environment.  This provides any information - state transition, object values, etc
+DEBUG - Turned on in any environment when a problem is occuring.  The information captured may be throughput, communication, object values, etc.
+TRACE - Turned on in any environment where you are trying to follow an execution path, for optimization or debugging.  This is the most broad logging level and all messages are written.
+
    +
    5. +
  5. +

    To view log file differences for different logging levels, change the level for the "org.jboss.as.quickstarts.logging" logger from TRACE to DEBUG, INFO, WARN, ERROR, or FATAL, then access the application.

    +
    6. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Remove the Logging Configuration

+

You can remove the logging configuration by running the remove-logging.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Remove the Logging Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-logging.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-logging.cli
+
    +
    3. +
+

This script removes the log and file handlers from the logging subsystem in the server configuration. You should see the following result when you run the script:

+
    The batch executed successfully
+
+

Remove the Logging Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+ +

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/logging/README.md b/logging/README.md index c65ab081b1..51b7f2d017 100644 --- a/logging/README.md +++ b/logging/README.md @@ -3,14 +3,14 @@ Author: Joel Tosi Level: Intermediate Technologies: Logging -Summary: The `logging` quickstart demonstrates how to configure different logging levels in ${product.name}. It also includes an asynchronous logging example. +Summary: The `logging` quickstart demonstrates how to configure different logging levels in JBoss EAP. It also includes an asynchronous logging example. Prerequisites: None -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `logging` quickstart demonstrates how to set up and log different levels of information in ${product.name.full}. An example of asynchronous logging is also included in the configuration examples. +The `logging` quickstart demonstrates how to set up and log different levels of information in Red Hat JBoss Enterprise Application Platform. An example of asynchronous logging is also included in the configuration examples. This quickstart contains just one class file and one JSP file. When you access the application, it fires off the logging information. @@ -19,39 +19,39 @@ To better visualize how the logging configuration works, you first deploy and ac ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. -2. The following shows the command line to start the ${product.name} server with the default profile: +1. Open a command prompt and navigate to the root of the JBoss EAP directory. +2. The following shows the command line to start the JBoss EAP server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This deploys `target/${project.artifactId}.war` to the running instance of the server. +4. This deploys `target/logging.war` to the running instance of the server. ## Access the Application -The application is running at the following URL: . +The application is running at the following URL: . You will see the following message in the server console: @@ -67,7 +67,7 @@ You will see the following message in the server console: ## Check the Server Logs -The log files are located in the `${jboss.home.name}/standalone/log` log directory. At this point you should see the following log files. +The log files are located in the `EAP7_HOME/standalone/log` log directory. At this point you should see the following log files. * `server.log` - This is the standard log produced by the application server. By default, it contains all the server log messages, including the server startup messages. * `gc.log.0.current` - This is a garbage collection log. It contains garbage collection activity and can be used for diagnostic purposes. This log can be ignored as it is not used in this quickstart. @@ -78,20 +78,20 @@ The log files are located in the `${jboss.home.name}/standalone/log` log directo You configure server logging by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-logging.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-logging.cli` file in the root of this quickstart directory. This script configures the logging subsytem in the server configuration file. It configures the periodic rotating file handlers and the async handlers, creates the logger for our quickstart class and sets the level to TRACE, and assigns the async handlers for our quickstart class. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-logging.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-logging.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-logging.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-logging.cli You should see the following result when you run the script: The batch executed successfully @@ -99,7 +99,7 @@ You should see the following result when you run the script: ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. The following XML was added to the `logging` subsystem. @@ -192,14 +192,14 @@ The following XML was added to the `logging` subsystem. ## Test the New Logging Configuration -1. If your server is not started, then [Start the ${product.name} server](#start-the-server). +1. If your server is not started, then [Start the JBoss EAP server](#start-the-server). 2. [Build and deploy the quickstart](#build-and-deploy-the-quickstart). 3. [Access the application](#access-the-application). ## Recheck the Server Logs -The log files are located in the `${jboss.home.name}/standalone/log` log directory. You should now see 8 log files. +The log files are located in the `EAP7_HOME/standalone/log` log directory. You should now see 8 log files. * The following logs are the standard log files produced by the application server: * `server.log` - The standard log produced by the application server. @@ -234,7 +234,7 @@ from TRACE to DEBUG, INFO, WARN, ERROR, or FATAL, then access the application. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -247,29 +247,29 @@ You can remove the logging configuration by running the `remove-logging.cli` sc ### Remove the Logging Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=remove-logging.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=remove-logging.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-logging.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-logging.cli This script removes the log and file handlers from the `logging` subsystem in the server configuration. You should see the following result when you run the script: The batch executed successfully ### Remove the Logging Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -* Be sure to configure ${product.name} server logging as described above under [Configure the ${product.name} Server](#configure-the-server). Stop the server at the end of that step. +* Be sure to configure JBoss EAP server logging as described above under [Configure the JBoss EAP Server](#configure-the-server). Stop the server at the end of that step. * Be sure to [Remove the Logging Configuration](#remove-the-logging-configuration) when you have completed testing this quickstart. diff --git a/logging/pom.xml b/logging/pom.xml index 3b3a44f7aa..8612c66a11 100644 --- a/logging/pom.xml +++ b/logging/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml logging diff --git a/mail/README.html b/mail/README.html new file mode 100644 index 0000000000..a7920ea741 --- /dev/null +++ b/mail/README.html @@ -0,0 +1,158 @@ + + + mail: E-Mail Example using CDI and JSF + + + +

mail: E-Mail Example using CDI and JSF

+

Author: Joel Tosi
+Level: Beginner
+Technologies: JavaMail, CDI, JSF
+Summary: The mail quickstart demonstrates how to send email using CDI and JSF and the default Mail provider that ships with JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The mail quickstart demonstrates sending email with the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in Red Hat JBoss Enterprise Application Platform.

+

The mail provider is configured in the mail subsystem of the EAP7_HOME/standalone/configuration/standalone.xml configuration file if you are running a standalone server or in the EAP7_HOME/domain/configuration/domain.xml configuration file if you are running in a managed domain.

+

You can use the default mail provider that comes out of the box with JBoss EAP. It uses your local mail relay and the default SMTP port of 25. However, this quickstart demonstrates how to define and use a custom mail provider.

+

This example is a web application that takes To, From, Subject, and Message Body input and sends mail to that address. The front end is a JSF page with a simple POJO backing, leveraging CDI for resource injection.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Configure an SMTP Server on Your Local Machine

+

This quickstart expects that you have an SMTP mail server running on your machine and configured for the default port localhost:25. To configure an SMTP mail server, consult the documentation for your operating system. It is beyond the scope of this quickstart to provide these instructions.

+

If you do not configure an SMTP mail server on your local machine, you will see the exception com.sun.mail.util.MailConnectException: Couldn't connect to host, port: localhost, 25; timeout -1; when you access the application and attempt to send an email.

+

Configure the Server

+

You configure the custom mail session in JBoss EAP by running Management CLI commands. For your convenience, this quickstart batches the commands into a configure-mail-session.cli script provided in the root directory of this quickstart.

+
    +
  1. Before you begin, back up your server configuration file +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-mail-session.cli file in the root of this quickstart directory. This script creates custom outbound socket binding port for SMTP, POP3, and IMAP. It then creates the custom MyOtherMail mail session and configures it to use the custom outbound socket binding ports.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-mail-session.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-mail-session.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    5. +
  5. +

    Stop the JBoss EAP server.

    +
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+

The following outbound-socket-binding groups are added to the standard-sockets <socket-binding-group> element.

+
  <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
+    ...
+    </outbound-socket-binding>
+    <outbound-socket-binding name="my-smtp-binding">
+        <remote-destination host="localhost" port="25"/>
+    </outbound-socket-binding>
+    <outbound-socket-binding name="my-pop3-binding">
+        <remote-destination host="localhost" port="110"/>
+    </outbound-socket-binding>
+    <outbound-socket-binding name="my-imap-binding">
+        <remote-destination host="localhost" port="143"/>
+    </outbound-socket-binding>
+ </socket-binding-group>
+
+

The MyOtherMail mail session is added to the mail subsystem and configured to use the custom outbound socket binding ports.

+
  <subsystem xmlns="urn:jboss:domain:mail:2.0">
+     <mail-session name="default" jndi-name="java:jboss/mail/Default">
+        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
+     </mail-session>
+     <mail-session name="MyOtherMail" jndi-name="java:jboss/mail/MyOtherMail">
+        <smtp-server password="pass" username="nobody" tls="true" outbound-socket-binding-ref="my-smtp-binding"/>
+        <pop3-server outbound-socket-binding-ref="my-pop3-binding"/>
+        <imap-server password="pass" username="nobody" outbound-socket-binding-ref="my-imap-binding"/>
+     </mail-session>
+  </subsystem>
+
+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/mail.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/mail/.

+

Note: If you see Error processing request in the browser when you access the application and attempt to send email, followed by javax.servlet.ServletException: com.sun.mail.util.MailConnectException: Couldn't connect to host, port: localhost, 25; timeout -1; nested exception is: java.net.ConnectException: Connction refused, make sure you followed the instructions above to Configure an SMTP Server on Your Local Machine.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Remove the Mail Configuration

+

You can remove the mail configuration by running the remove-mail-session.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Remove the Custom Mail Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-mail-session.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-mail-session.cli
+
    +
    3. +
+

This script removes the custom MyOtherMail session from the mail subsystem in the server configuration. file You should see the following result when you run the script:

+
    The batch executed successfully
+    process-state: reload-required
+
+

Remove the Custom Mail Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone-full.xml file with the back-up copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

NOTE:

+
    +
  • Be sure to Configure an SMTP Server on Your Local Machine.
    • +
  • Be sure to configure the JBoss EAP custom mail configuration as described above under Configure the JBoss EAP Server. Stop the server at the end of that step.
    • +
  • To deploy the server project, right-click on the mail project and choose Run As --> Run on Server. A browser window appears that accesses the running application.
    • +
  • To undeploy the project, right-click on the mail project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    • +
  • Be sure to Remove the Mail Configuration when you have completed testing this quickstart.
    • +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/mail/README.md b/mail/README.md index e5cb099e58..6eecbda1ab 100644 --- a/mail/README.md +++ b/mail/README.md @@ -3,31 +3,31 @@ Author: Joel Tosi Level: Beginner Technologies: JavaMail, CDI, JSF -Summary: The `mail` quickstart demonstrates how to send email using CDI and JSF and the default Mail provider that ships with ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `mail` quickstart demonstrates how to send email using CDI and JSF and the default Mail provider that ships with JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `mail` quickstart demonstrates sending email with the use of *CDI* (Contexts and Dependency Injection) and *JSF* (JavaServer Faces) in ${product.name.full}. +The `mail` quickstart demonstrates sending email with the use of *CDI* (Contexts and Dependency Injection) and *JSF* (JavaServer Faces) in Red Hat JBoss Enterprise Application Platform. -The mail provider is configured in the `mail` subsystem of the `${jboss.home.name}/standalone/configuration/standalone.xml` configuration file if you are running a standalone server or in the `${jboss.home.name}/domain/configuration/domain.xml` configuration file if you are running in a managed domain. +The mail provider is configured in the `mail` subsystem of the `EAP7_HOME/standalone/configuration/standalone.xml` configuration file if you are running a standalone server or in the `EAP7_HOME/domain/configuration/domain.xml` configuration file if you are running in a managed domain. -You can use the default mail provider that comes out of the box with ${product.name}. It uses your local mail relay and the default SMTP port of 25. However, this quickstart demonstrates how to define and use a custom mail provider. +You can use the default mail provider that comes out of the box with JBoss EAP. It uses your local mail relay and the default SMTP port of 25. However, this quickstart demonstrates how to define and use a custom mail provider. This example is a web application that takes `To`, `From`, `Subject`, and `Message Body` input and sends mail to that address. The front end is a JSF page with a simple POJO backing, leveraging CDI for resource injection. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Configure an SMTP Server on Your Local Machine @@ -38,33 +38,33 @@ If you do not configure an SMTP mail server on your local machine, you will see ## Configure the Server -You configure the custom mail session in ${product.name} by running Management CLI commands. For your convenience, this quickstart batches the commands into a `configure-mail-session.cli` script provided in the root directory of this quickstart. +You configure the custom mail session in JBoss EAP by running Management CLI commands. For your convenience, this quickstart batches the commands into a `configure-mail-session.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-mail-session.cli` file in the root of this quickstart directory. This script creates custom outbound socket binding port for SMTP, POP3, and IMAP. It then creates the custom `MyOtherMail` mail session and configures it to use the custom outbound socket binding ports. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-mail-session.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-mail-session.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-mail-session.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-mail-session.cli You should see the following result when you run the script: The batch executed successfully process-state: reload-required -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. The following `outbound-socket-binding` groups are added to the `standard-sockets` `` element. @@ -97,33 +97,33 @@ The `MyOtherMail` mail session is added to the `mail` subsystem and configured t ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/mail.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . Note: If you see `Error processing request` in the browser when you access the application and attempt to send email, followed by `javax.servlet.ServletException: com.sun.mail.util.MailConnectException: Couldn't connect to host, port: localhost, 25; timeout -1; nested exception is: java.net.ConnectException: Connction refused`, make sure you followed the instructions above to [Configure an SMTP Server on Your Local Machine](#configure-an-smtp-server-on-your-local-machine). ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -136,14 +136,14 @@ You can remove the mail configuration by running the `remove-mail-session.cli` ### Remove the Custom Mail Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=remove-mail-session.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=remove-mail-session.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-mail-session.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-mail-session.cli This script removes the custom `MyOtherMail` session from the `mail` subsystem in the server configuration. file You should see the following result when you run the script: The batch executed successfully @@ -151,20 +151,20 @@ You can remove the mail configuration by running the `remove-mail-session.cli` ### Remove the Custom Mail Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). _NOTE:_ * Be sure to [Configure an SMTP Server on Your Local Machine](#configure-an-smtp-server-on-your-local-machine). -* Be sure to configure the ${product.name} custom mail configuration as described above under [Configure the ${product.name} Server](#configure-the-server). Stop the server at the end of that step. -* To deploy the server project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Run on Server`. A browser window appears that accesses the running application. -* To undeploy the project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +* Be sure to configure the JBoss EAP custom mail configuration as described above under [Configure the JBoss EAP Server](#configure-the-server). Stop the server at the end of that step. +* To deploy the server project, right-click on the `mail` project and choose `Run As` --> `Run on Server`. A browser window appears that accesses the running application. +* To undeploy the project, right-click on the `mail` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. * Be sure to [Remove the Mail Configuration](#remove-the-mail-configuration) when you have completed testing this quickstart. diff --git a/mail/pom.xml b/mail/pom.xml index 01b2685370..c592db7f91 100644 --- a/mail/pom.xml +++ b/mail/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml mail diff --git a/managed-executor-service/README.html b/managed-executor-service/README.html new file mode 100644 index 0000000000..7f930361cf --- /dev/null +++ b/managed-executor-service/README.html @@ -0,0 +1,114 @@ + + + managed-executor-service: Managed Executor Service example + + + +

managed-executor-service: Managed Executor Service example

+

Author: Rafael Benevides
+Level: Beginner
+Technologies: EE Concurrency Utilities, JAX-RS, JAX-RS Client API
+Summary: The managed-executor-service quickstart demonstrates how Java EE applications can submit tasks for asynchronous execution.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The Managed Executor Service (javax.enterprise.concurrent.ManagedExecutorService) allows Java EE applications to submit tasks for asynchronous execution. It is an extension of Java SE's Executor Service (java.util.concurrent.ExecutorService) adapted to the Java EE platform requirements.

+

Managed Executor Service instances are managed by the application server, thus Java EE applications are forbidden to invoke any lifecycle related method.

+

A JAX-RS resource provides access to some operations that are executed asynchronously.

+

This quickstart does not contain any user interface. The tests must be run to verify everything is working correctly.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+
-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.jboss.as.quickstarts.managedexecutorservice.test.ProductsRestClientIT
+feb. 22, 2017 4:22:22 PM org.xnio.Xnio <clinit>
+INFO: XNIO version 3.3.4.Final
+feb. 22, 2017 4:22:22 PM org.xnio.nio.NioXnio <clinit>
+INFO: XNIO NIO Implementation Version 3.3.4.Final
+feb. 22, 2017 4:22:22 PM org.jboss.remoting3.EndpointImpl <clinit>
+INFO: JBoss Remoting version 4.0.18.Final
+feb. 22, 2017 4:22:23 PM org.jboss.as.quickstarts.managedexecutorservice.test.ProductsRestClientIT testRestResources
+INFO: creating a new product
+feb. 22, 2017 4:22:23 PM org.jboss.as.quickstarts.managedexecutorservice.test.ProductsRestClientIT testRestResources
+INFO: Product created. Executing a long running task
+feb. 22, 2017 4:22:26 PM org.jboss.as.quickstarts.managedexecutorservice.test.ProductsRestClientIT testRestResources
+INFO: Deleting all products
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 5.619 sec - in org.jboss.as.quickstarts.managedexecutorservice.test.ProductsRestClientIT
+
+Results :
+
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+
+

Investigate the Server Console Output

+

Look at the JBoss EAP console or Server log and you should see log messages like the following:

+
13:34:07,940 INFO  [ProductResourceRESTService] (default task-51) Will create a new Product on other Thread
+13:34:07,940 INFO  [ProductResourceRESTService] (default task-51) Returning response
+13:34:07,941 INFO  [PersitTask] (EE-ManagedExecutorService-default-Thread-5) Begin transaction
+13:34:07,941 INFO  [PersitTask] (EE-ManagedExecutorService-default-Thread-5) Persisting a new product
+13:34:07,946 INFO  [PersitTask] (EE-ManagedExecutorService-default-Thread-5) Commit transaction
+13:34:08,002 INFO  [ProductResourceRESTService] (default task-52) Submitting a new long running task to be executed
+13:34:08,003 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:08,009 INFO  [LongRunningTask] (EE-ManagedExecutorService-default-Thread-5) Starting a long running task
+13:34:08,010 INFO  [LongRunningTask] (EE-ManagedExecutorService-default-Thread-5) Analysing A Product
+13:34:08,306 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:08,608 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:08,912 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:09,215 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:09,519 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:09,823 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:10,128 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:10,431 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:10,735 INFO  [ProductResourceRESTService] (default task-52) Waiting for the result to be available...
+13:34:11,040 INFO  [ProductResourceRESTService] (default task-52) Result is available. Returning result...56
+13:34:11,082 INFO  [ProductResourceRESTService] (default task-53) Will delete all Products on other Thread
+13:34:11,082 INFO  [ProductResourceRESTService] (default task-53) Returning response
+13:34:11,082 INFO  [DeleteTask] (EE-ManagedExecutorService-default-Thread-5) Begin transaction
+13:34:11,083 INFO  [DeleteTask] (EE-ManagedExecutorService-default-Thread-5) Deleting all products
+13:34:11,092 INFO  [DeleteTask] (EE-ManagedExecutorService-default-Thread-5) Commit transaction. Products deleted: 1
+
+

Note that the PersistTask and DeleteTask were executed after ProductResourceRESTService sends a Response. The only exception is for LongRunningTask where ProductResourceRESTService waits for its response.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

To run the tests in Red Hat JBoss Developer Studio, you must first set the active Maven profile in project properties to one of the following:

+
    +
  • arq-remote: This setting is used for a remote server. JBoss Developer Studio starts the server for you.
    • +
  • arq-managed: This setting is used for a managed server. If you use this setting, you must start the server before you run the tests.
    • +
+

Then, to run the tests, right click on the project or individual classes and select Run As --> JUnit Test in the context menu.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/managed-executor-service/README.md b/managed-executor-service/README.md index 3585541142..4041034cad 100644 --- a/managed-executor-service/README.md +++ b/managed-executor-service/README.md @@ -4,8 +4,8 @@ Author: Rafael Benevides Level: Beginner Technologies: EE Concurrency Utilities, JAX-RS, JAX-RS Client API Summary: The `managed-executor-service` quickstart demonstrates how Java EE applications can submit tasks for asynchronous execution. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? @@ -18,37 +18,37 @@ A JAX-RS resource provides access to some operations that are executed asynchron This quickstart does not contain any user interface. The tests must be run to verify everything is working correctly. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -77,7 +77,7 @@ You can also let Arquillian manage the ${product.name} server by using the `arq- ## Investigate the Server Console Output -Look at the ${product.name} console or Server log and you should see log messages like the following: +Look at the JBoss EAP console or Server log and you should see log messages like the following: 13:34:07,940 INFO [ProductResourceRESTService] (default task-51) Will create a new Product on other Thread 13:34:07,940 INFO [ProductResourceRESTService] (default task-51) Returning response @@ -118,7 +118,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). To run the tests in Red Hat JBoss Developer Studio, you must first set the active Maven profile in project properties to one of the following: diff --git a/managed-executor-service/pom.xml b/managed-executor-service/pom.xml index 434f1bd2e9..2f6cdf61d6 100644 --- a/managed-executor-service/pom.xml +++ b/managed-executor-service/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml managed-executor-service diff --git a/messaging-clustering-singleton/README.html b/messaging-clustering-singleton/README.html new file mode 100644 index 0000000000..7d01d5e304 --- /dev/null +++ b/messaging-clustering-singleton/README.html @@ -0,0 +1,367 @@ + + + messaging-clustering-singleton: Messaging Example that Demonstrates Clustering + + + +

messaging-clustering-singleton: Messaging Example that Demonstrates Clustering

+

Author: Flavia Rainone, Jess Sightler
+Level: Advanced
+Technologies: JMS, MDB, Clustering
+Summary: The messaging-clustering-singleton quickstart uses a JMS topic and a queue to demonstrate clustering using JBoss EAP messaging with MDB singleton configuration where only one node in the cluster will be active.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The messaging-clustering-singleton quickstart demonstrates the use of clustering with integrated Apache ActiveMQ Artemis. It uses the same code as in helloworld-mdb quickstart, with only a difference in the configuration to run it as a clustered singleton. Instructions are provided to run the quickstart on either a standalone server or in a managed domain.

+

These are the two JMS resources contained in this quickstart:

+
    +
  • A queue named HELLOWORLDMDBQueue bound in JNDI as java:/queue/HELLOWORLDMDBQueue
    • +
  • A topic named HELLOWORLDMDBTopic bound in JNDI as java:/topic/HELLOWORLDMDBTopic
    • +
+

Both contain a singleton configuration as specified in the file WEB-INF/jboss-ejb3.xml:

+
<c:clustering>
+    <ejb-name>*</ejb-name>
+    <c:clustered-singleton>true</c:clustered-singleton>
+</c:clustering>
+
+

The wildcard (*) in the <ejb-name> element indicates that all MDBs contained in the application will be clustered singleton. As a result, only one node in the cluster will have those MDBs active at a specific time. If that node shuts down, another node in the cluster will become the active node with MDBs, called the singleton provider.

+

Also, we can find a configuration for delivery group in the same file:

+
<d:delivery>
+    <ejb-name>HelloWorldTopicMDB</ejb-name>
+    <d:group>my-mdb-delivery-group</d:group>
+</d:delivery>
+
+

Here, you can see that only one of the MDBs, HelloWorldTopicMDB, is associated with a delivery group. All delivery groups used by an MDB must be declared in the ejb subsystem configuration, and they can be enabled or disabled. If the delivery group is disabled in a cluster node, all MDBs belonging to that group will be inactive in that node. Notice that delivery groups can be used in non-clustered environments as well. In that case, the MDB will be active in the server whenever the delivery group is enabled in the server. A delivery group can be enabled using the management CLI as you will see in this quickstart.

+

If a delivery group is used in conjunction with singleton, as is the case of this quickstart, the MDB will be active in the singleton provider node only if that node has delivery-group enabled. If not, the MDB will be inactive in that node and all remainder nodes of the cluster.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Build the Project

+

Follow these steps to build the project without deploying it.

+
    +
  1. Open a command prompt and navigate to the root directory of this quickstart.
    2. +
  2. Type this command to build the archive: +
    mvn clean install
+
    +
    3. +
+

Configure the Server and Deploy the Quickstart

+

You can choose to configure and deploy this quickstart to a managed domain or to a standalone server. The sections below describe how to configure and start the server for each configuration.

+

Configure the Server and Deploy the Quickstart to a Managed Domain

+

You configure the server by running the install-domain.cli script provided in the root directory of this quickstart.

+

Back up the Server Configuration Files for a Managed Domain

+

Before you begin, back up your server configuration files.

+
    +
  1. +

    If it is running, stop the JBoss EAP server.

    +
    2. +
  2. +

    Back up the following files:

    +
    EAP7_HOME/domain/configuration/domain.xml
+EAP7_HOME/domain/configuration/host.xml
+
    +
    3. +
+

After you have completed testing this quickstart, you can replace these files to restore the server to its original configuration.

+

Start the Managed Domain

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server in a managed domain: +
    For Linux:   EAP7_HOME/bin/domain.sh
+For Windows: EAP7_HOME\bin\domain.bat
+
    +
    3. +
+

Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI

+
    +
  1. +

    Review the install-domain.cli file located in the root of this quickstart directory. This script creates the server group and servers and configures messaging clustering for testing this quickstart. You will note it does the following:

    +
      +
    • Stops the servers.
      • +
    • Creates the quickstart-messaging-clustering-singleton-group server group to test ActiveMQ clustering.
      • +
    • Enables console logging to allow you to view the quickstart output.
      • +
    • Adds two servers to the server-group.
      • +
    • Configures ActiveMQ clustering in the full-ha profile.
      • +
    • Creates a delivery group named my-mdb-delivery-group, with initial active value set to true.
      • +
    • Deploys the messaging-clustering-singleton.war archive.
      • +
    • Starts the servers that were added to the managed domain.
      • +
    +
    2. +
  2. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=install-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=install-domain.cli
+
    +

    You should see the following output:

    +
    {
+    "outcome" => "success",
+    "result" => undefined,
+    "server-groups" => undefined
+}
+The batch executed successfully
+{
+    "outcome" => "success",
+    "result" => "STARTED"
+}
+{
+    "outcome" => "success",
+    "result" => "STARTED"
+}
+
    +
    3. +
+

Configure the Server and Deploy the Quickstart to a Standalone Server

+

If you choose to use standalone servers rather than a managed domain, you need two instances of the application server. The second server must be started with a port offset parameter provided to the startup script as -Djboss.socket.binding.port-offset=100.

+

Since both application servers must be configured in the same way, you must configure the first server and then clone it.

+

Back up the Server Configuration File for a Standalone Server

+

Before you begin, back up your server configuration file.

+
    +
  1. +

    If it is running, stop the JBoss EAP server.

    +
    2. +
  2. +

    Back up the following file:

    +
    EAP7_HOME/standalone/configuration/standalone-full-ha.xml
+
    +
    3. +
+

After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.

+

Start the Standalone Server Using the Full HA Profile.

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the full-ha profile. This profile supports HA clustering. +
    For Linux:   EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml
+For Windows: EAP7_HOME_1\bin\standalone.bat -c standalone-full-ha.xml
+
    +
    3. +
+

Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI

+
    +
  1. +

    Review the install-standalone.cli file located in the root of this quickstart directory. This script configures clustering for a standalone server. You will note it does the following:

    +
      +
    • Because the console is disabled by default in the Full HA profile, it enables console logging to allow you to view the quickstart output.
      • +
    • Enables clustering and sets a cluster password.
      • +
    • Creates a delivery group named my-mdb-delivery-group, with initial active value set to true.
      • +
    • Deploys the messaging-clustering-singleton.war archive.
      • +
    • Reloads the server configuration.
      • +
    +
    2. +
  2. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=install-standalone.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=install-standalone.cli
+
    +

    You should see the following output:

    +
    The batch executed successfully
+process-state: reload-required
+
    +
    3. +
+

Clone the JBoss EAP Directory

+

After you have successfully configured the server, you must make a copy of this JBoss EAP directory structure to use for the second server.

+
    +
  1. Stop the server.
    2. +
  2. Make a copy of this JBoss EAP directory structure to use for the second server.
    3. +
  3. Remove the following directories from the cloned instance: +
    EAP7_HOME_2/standalone/data/activemq/bindings
+EAP7_HOME_2/standalone/data/activemq/journal
+EAP7_HOME_2/standalone/data/activemq/largemessages
+
    +
    4. +
+

Start the JBoss EAP Standalone Servers with the Full HA Profile

+

If you are using Linux:

+
Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml
+Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100
+
+

If you are using Windows:

+
Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full-ha.xml
+Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100
+
+

Access the Application

+

Access the Application Running in a Managed Domain

+

The application will be running at the following URL: http://localhost:9080/messaging-clustering-singleton/HelloWorldMDBServletClient.

+

It will send some messages to the queue.

+

To send messages to the topic, use the following URL: http://localhost:9080/messaging-clustering-singleton/HelloWorldMDBServletClient?topic

+

Access the Application Running in a Standalone Server

+

The application will be running at the following URL: http://localhost:8080/messaging-clustering-singleton/HelloWorldMDBServletClient.

+

It will send some messages to the queue.

+

To send messages to the topic, use the following URL: http://localhost:8080/messaging-clustering-singleton/HelloWorldMDBServletClient?topic

+

Investigate the Server Console Output

+

Review the messages in both JBoss EAP server consoles or logs.

+

The following messages are sent to the queue:

+
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-0 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 1
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-2 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 3
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 5
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-3 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 4
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-1 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 2
+
+

The following messages are sent to the topic:

+
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-5 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 1
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-6 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 2
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-8 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 4
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-7 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 3
+INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-9 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 5
+
+

You will notice that only one of the nodes, elected as the singleton provider node, will be receiving the messages. For that, check both servers, only one will contain the received message log entries.

+

Note: You will see the following warnings in the server logs. You can ignore these warnings as they are intended for production servers.

+
WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the send buffer of socket DatagramSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
+WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the receive buffer of socket DatagramSocket was set to 20MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
+WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+
+

Electing a New Singleton Provider Server

+

If you reboot the singleton server node, the other node will be elected the new singleton provider, and will start receiving the MDB messages instead.

+

You should see the following output in the new singleton provider server:

+
WFLYCLSV0003: master:quickstart-messagingcluster-nodeX elected as the singleton provider of the org.wildfly.ejb3.clustered.singleton service
+
+

Where nodeX will be either node1 or node2, depending on which node is the new singleton provider.

+

If you now try to access the servlet urls, you will see that the new provider is receiving all new messages.

+

Note: You will see the following warnings in the log of the server that is not the singleton provider. These messages show that the other node went down unexpectedly, which is exactly the scenario we are reproducing in this quickstart. For that reason, those warnings can be ignored.

+
    WARN  [org.apache.activemq.artemis.core.client] (Thread-2 (ActiveMQ-client-global-threads)) AMQ212037: Connection failure has been detected: AMQ119015: The connection was disconnected because of server shutdown [code=DISCONNECTED]
+    WARN  [org.apache.activemq.artemis.core.server] (Thread-2 (ActiveMQ-client-global-threads)) AMQ222095: Connection failed with failedOver=false
+
+

Note: You may see the following log message as well. When a server is restarted, it may broadcast that it is up and running (with its nodeID) while other nodes still reference the previous server instance for the same nodeID. Eventually, the cluster will be informed of the new instance representing the given nodeID but as the warning explains, it is possible to see this log (once or more) when a server is restarted.

+
    WARN  [org.apache.activemq.artemis.core.client] (activemq-discovery-group-thread-dg-group1) AMQ212034: There are more than one servers on the network broadcasting the same node id. You will see this message exactly once (per node) if a node is restarted, in which case it can be safely ignored. But if it is logged continuously it means you really do have more than one node on the same network active concurrently with the same node id. This could occur if you have a backup node active at the same time as its live node. nodeID=a114b652-689e-11e7-a2f4-54ee751c6182
+
+

Note: The next error message is a known issue. You can ignore it, as it does not affect the scenario that this quickstart reproduces:

+
    ERROR [org.apache.activemq.artemis.core.server] (Thread-3 (ActiveMQ-client-global-threads)) AMQ224037: cluster connection Failed to handle message: java.lang.IllegalStateException: Cannot find binding for jms.queue.HelloWorldMDBQueuedea3e995-713c-11e7-85f2-b8f6b112daf7 on ClusterConnectionImpl@1129705701[nodeUUID=dabaa1fa-713c-11e7-8f3a-b8f6b112daf7, connector=TransportConfiguration(name=http-connector, factory=org-apache-activemq-artemis-core-remoting-impl-netty-NettyConnectorFactory) ?httpUpgradeEndpoint=http-acceptor&activemqServerName=default&httpUpgradeEnabled=true&port=9080&host=localhost, address=jms, server=ActiveMQServerImpl::serverUUID=dabaa1fa-713c-11e7-8f3a-b8f6b112daf7]
+
+at org.apache.activemq.artemis.core.server.cluster.impl.ClusterConnectionImpl$MessageFlowRecordImpl.doConsumerCreated(ClusterConnectionImpl.java:1294)
+
+at org.apache.activemq.artemis.core.server.cluster.impl.ClusterConnectionImpl$MessageFlowRecordImpl.handleNotificationMessage(ClusterConnectionImpl.java:1029)
+
+at org.apache.activemq.artemis.core.server.cluster.impl.ClusterConnectionImpl$MessageFlowRecordImpl.onMessage(ClusterConnectionImpl.java:1004)
+
+at org.apache.activemq.artemis.core.client.impl.ClientConsumerImpl.callOnMessage(ClientConsumerImpl.java:1001)
+
+at org.apache.activemq.artemis.core.client.impl.ClientConsumerImpl.access$400(ClientConsumerImpl.java:49)
+
+at org.apache.activemq.artemis.core.client.impl.ClientConsumerImpl$Runner.run(ClientConsumerImpl.java:1124)
+
+at org.apache.activemq.artemis.utils.OrderedExecutorFactory$OrderedExecutor$ExecutorTask.run(OrderedExecutorFactory.java:101)
+
+at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
+
+at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
+
+at java.lang.Thread.run(Thread.java:745)
+
+

Rebooting the Singleton Provider Server Node in a Managed Domain

+

Run the following command, replacing EAP7_HOME with the path to your server, and replacing NODE_X in the script name with either node1 or node2, depending on whether the current singleton provider is node1 or node2.

+
For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restart-NODE_X-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restart-NODE_X-domain.cli
+
+

Rebooting the Singleton Provider Server Node in a Standalone Server

+

Stop the provider server and restart it again, using the same command you used to start the server initially.

+

Disable and Enable the Delivery Group

+

To disable the delivery group "my-mdb-delivery-group" to which the topic belongs, run the disable-delivery-group-domain.cli or disable-delivery-group-standalone.cli script, located in the root directory of this quickstart. Follow the instructions in the next sections, depending on the server configuration you choose to run.

+

After disabling the delivery group, try sending messages to the topic, You should notice that the topic messages are not delivered when the delivery group is inactive.

+

Next, enable the delivery group using the appropriate enable-delivery-group-domain.cli or enable-delivery-group-standalone.cli script, also located in the root directory of this quickstart, so that the topic messages can be delivered again.

+

Disable and Enable Delivery Group in a Managed Domain

+

To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the disable-delivery-group-domain.cli script, replacing EAP7_HOME with the path to your server:

+
For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=disable-delivery-group-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=disable-delivery-group-domain.cli
+
+

Similarly, to enable the delivery group, run the enable-delivery-group-domain.cli script:

+
For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=enable-delivery-group-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=enable-delivery-group-domain.cli
+
+

Disable and Enable Delivery Group in a Standalone Server

+

To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the disable-delivery-group-standalone.cli script on both servers, replacing EAP7_HOME with the path to your server:

+
For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=disable-delivery-group-standalone.cli
+           EAP7_HOME_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=disable-delivery-group-standalone.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=disable-delivery-group-standalone.cli
+               EAP7_HOME_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=disable-delivery-group-standalone.cli
+
+

Similarly, to enable the delivery group, run the enable-delivery-group-standalone.cli script in both servers:

+
For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=enable-delivery-group-standalone.cli
+           EAP7_HOME_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=enable-delivery-group-standalone.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=enable-delivery-group-standalone.cli
+                 EAP7_HOME_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=enable-delivery-group-standalone.cli
+
+

Undeploy the Archive

+

When you are finished testing, use the following instructions to undeploy the quickstart.

+

Undeploy the quickstart in a Managed Domain

+
    +
  1. Make sure you have started the managed domain as described above.
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the undeploy-domain.cli script, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=undeploy-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=undeploy-domain.cli
+
    +
    3. +
+

Undeploy the quickstart in a Standalone Server

+
    +
  1. Make sure you have started the standalone server as described above.
    2. +
  2. Open a command prompt, navigate to the root directory of this quickstart, and run the undeploy-standalone.cli script, replacing EAP7_HOME_1 and EAP7_HOME_2 with the path to the appropriate server: +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=undeploy-standalone.cli
+           EAP7_HOME_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=undeploy-standalone.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=undeploy-standalone.cli
+             EAP7_HOME_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=undeploy-standalone.cli
+
    +
    3. +
+

Remove the Server Configuration

+

Remove the Domain Server Configuration

+

You can remove the domain configuration by manually restoring the backup configuration files or by running the management CLI script.

+

Remove the Domain Server Configuration Manually

+

Note: This method ensures the server is restored to its prior configuration.

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Restore the EAP7_HOME/domain/configuration/domain.xml and EAP7_HOME/domain/configuration/host.xml files with the back-up copies of the files. Be sure to replace EAP7_HOME with the path to your server.
    3. +
+

Remove the Domain Server Configuration by Running the Management CLI Script

+

Note: This script returns the server to a default configuration and the result might not match the server configuration prior to testing this quickstart. If you were not running with the default configuration before testing this quickstart, you should follow the intructions above to manually restore the configuration to its previous state.

+
    +
  1. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:   EAP7_HOME/bin/domain.sh
+For Windows: EAP7_HOME\bin\domain.bat
+
    +
    2. +
  2. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the remove-domain.cli script, replacing EAP7_HOME with the path to your server.

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-domain.cli
+
    +
    3. +
+

This script removes the server configuration that was done by the install-domain.cli script. You should see the following result following the script commands:

+
The batch executed successfully
+
+

Remove the Standalone Server Configuration

+

You can remove the domain configuration by manually restoring the back-up copies the configuration files or by running the management CLI script.

+

Remove the Standalone Server Configuration Manually

+

Note: This method ensures the server is restored to its prior configuration.

+
    +
  1. If they are running, stop both JBoss EAP servers.
    2. +
  2. Restore the EAP7_HOME_1/standalone/configuration/standalone-full-ha.xml file with the back-up copies of the file. Be sure to replace EAP7_HOME_1 with the path to your server.
    3. +
+

Remove the Standalone Configuration by Running the Management CLI Script

+

Note: This script returns the server to a default configuration and the result might not match the server configuration prior to testing this quickstart. If you were not running with the default configuration before testing this quickstart, you should follow the intructions above to manually restore the configuration to its previous state.

+
    +
  1. Start the JBoss EAP server by typing the following, replacing EAP7_HOME_1 with the path to your first server: +
    For Linux:   EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml
+For Windows: EAP7_HOME_1\bin\domain.bat -c standalone-full-ha.xml
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the remove-standalone.cli script, replacing EAP7_HOME_2 with the path to your second server. +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=remove-standalone.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=remove-standalone.cli
+
    +
    3. +
+

This script removes the server configuration that was done by the install-standalone.cli script. You should see the following result following the script commands:

+
The batch executed successfully
+
+

Delete the Cloned Standalone JBoss EAP Directory

+
    +
  1. If it is running, stop the second instance of the JBoss EAP server.
    2. +
  2. Delete the cloned directory.
    3. +
+ + \ No newline at end of file diff --git a/messaging-clustering-singleton/README.md b/messaging-clustering-singleton/README.md index 1ab75e7eb8..30c9214d4e 100644 --- a/messaging-clustering-singleton/README.md +++ b/messaging-clustering-singleton/README.md @@ -3,9 +3,9 @@ Author: Flavia Rainone, Jess Sightler Level: Advanced Technologies: JMS, MDB, Clustering -Summary: The `messaging-clustering-singleton` quickstart uses a JMS topic and a queue to demonstrate clustering using ${product.name} messaging with MDB singleton configuration where only one node in the cluster will be active. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `messaging-clustering-singleton` quickstart uses a JMS topic and a queue to demonstrate clustering using JBoss EAP messaging with MDB singleton configuration where only one node in the cluster will be active. +Target Product: JBoss EAP +Source: ## What is it? @@ -38,14 +38,14 @@ If a delivery group is used in conjunction with singleton, as is the case of thi ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Build the Project @@ -70,22 +70,22 @@ You configure the server by running the `install-domain.cli` script provided in Before you begin, back up your server configuration files. -1. If it is running, stop the ${product.name} server. +1. If it is running, stop the JBoss EAP server. 2. Back up the following files: - ${jboss.home.name}/domain/configuration/domain.xml - ${jboss.home.name}/domain/configuration/host.xml + EAP7_HOME/domain/configuration/domain.xml + EAP7_HOME/domain/configuration/host.xml After you have completed testing this quickstart, you can replace these files to restore the server to its original configuration. #### Start the Managed Domain -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server in a managed domain: - For Linux: ${jboss.home.name}/bin/domain.sh - For Windows: ${jboss.home.name}\bin\domain.bat + For Linux: EAP7_HOME/bin/domain.sh + For Windows: EAP7_HOME\bin\domain.bat #### Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI @@ -97,14 +97,14 @@ After you have completed testing this quickstart, you can replace these files to * Adds two servers to the `server-group`. * Configures ActiveMQ clustering in the `full-ha` profile. * Creates a delivery group named `my-mdb-delivery-group`, with initial active value set to `true`. - * Deploys the `${project.artifactId}.war` archive. + * Deploys the `messaging-clustering-singleton.war` archive. * Starts the servers that were added to the managed domain. -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=install-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=install-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=install-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=install-domain.cli You should see the following output: @@ -134,22 +134,22 @@ Since both application servers must be configured in the same way, you must conf Before you begin, back up your server configuration file. -1. If it is running, stop the ${product.name} server. +1. If it is running, stop the JBoss EAP server. 2. Back up the following file: - ${jboss.home.name}/standalone/configuration/standalone-full-ha.xml + EAP7_HOME/standalone/configuration/standalone-full-ha.xml After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. #### Start the Standalone Server Using the Full HA Profile. -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the `full-ha` profile. This profile supports HA clustering. - For Linux: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full-ha.xml - For Windows: ${jboss.home.name}_1\bin\standalone.bat -c standalone-full-ha.xml + For Linux: EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml + For Windows: EAP7_HOME_1\bin\standalone.bat -c standalone-full-ha.xml #### Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI @@ -158,65 +158,65 @@ After you have completed testing this quickstart, you can replace this file to r * Because the console is disabled by default in the Full HA profile, it enables console logging to allow you to view the quickstart output. * Enables clustering and sets a cluster password. * Creates a delivery group named `my-mdb-delivery-group`, with initial active value set to `true`. - * Deploys the `${project.artifactId}.war` archive. + * Deploys the `messaging-clustering-singleton.war` archive. * Reloads the server configuration. -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=install-standalone.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=install-standalone.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=install-standalone.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=install-standalone.cli You should see the following output: The batch executed successfully process-state: reload-required -#### Clone the ${product.name} Directory +#### Clone the JBoss EAP Directory -After you have successfully configured the server, you must make a copy of this ${product.name} directory structure to use for the second server. +After you have successfully configured the server, you must make a copy of this JBoss EAP directory structure to use for the second server. 1. Stop the server. -2. Make a copy of this ${product.name} directory structure to use for the second server. +2. Make a copy of this JBoss EAP directory structure to use for the second server. 3. Remove the following directories from the cloned instance: - ${jboss.home.name}_2/standalone/data/activemq/bindings - ${jboss.home.name}_2/standalone/data/activemq/journal - ${jboss.home.name}_2/standalone/data/activemq/largemessages + EAP7_HOME_2/standalone/data/activemq/bindings + EAP7_HOME_2/standalone/data/activemq/journal + EAP7_HOME_2/standalone/data/activemq/largemessages -#### Start the ${product.name} Standalone Servers with the Full HA Profile +#### Start the JBoss EAP Standalone Servers with the Full HA Profile If you are using Linux: - Server 1: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full-ha.xml - Server 2: ${jboss.home.name}_2/bin/standalone.sh -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml + Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 If you are using Windows: - Server 1: ${jboss.home.name}_1\bin\standalone.bat -c standalone-full-ha.xml - Server 2: ${jboss.home.name}_2\bin\standalone.bat -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full-ha.xml + Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 ## Access the Application ### Access the Application Running in a Managed Domain -The application will be running at the following URL: . +The application will be running at the following URL: . It will send some messages to the queue. -To send messages to the topic, use the following URL: +To send messages to the topic, use the following URL: ### Access the Application Running in a Standalone Server -The application will be running at the following URL: . +The application will be running at the following URL: . It will send some messages to the queue. -To send messages to the topic, use the following URL: +To send messages to the topic, use the following URL: ## Investigate the Server Console Output -Review the messages in both ${product.name} server consoles or logs. +Review the messages in both JBoss EAP server consoles or logs. The following messages are sent to the queue: @@ -297,10 +297,10 @@ _Note:_ The next error message is a [known issue](https://issues.jboss.org/brows ### Rebooting the Singleton Provider Server Node in a Managed Domain -Run the following command, replacing ${jboss.home.name} with the path to your server, and replacing `NODE_X` in the script name with either `node1` or `node2`, depending on whether the current singleton provider is `node1` or `node2`. +Run the following command, replacing EAP7_HOME with the path to your server, and replacing `NODE_X` in the script name with either `node1` or `node2`, depending on whether the current singleton provider is `node1` or `node2`. - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restart-NODE_X-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restart-NODE_X-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restart-NODE_X-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restart-NODE_X-domain.cli ### Rebooting the Singleton Provider Server Node in a Standalone Server Stop the provider server and restart it again, using the same command you used to start the server initially. @@ -316,33 +316,33 @@ Next, enable the delivery group using the appropriate `enable-delivery-group-dom ### Disable and Enable Delivery Group in a Managed Domain -To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the `disable-delivery-group-domain.cli` script, replacing ${jboss.home.name} with the path to your server: +To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the `disable-delivery-group-domain.cli` script, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=disable-delivery-group-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=disable-delivery-group-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=disable-delivery-group-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=disable-delivery-group-domain.cli Similarly, to enable the delivery group, run the `enable-delivery-group-domain.cli` script: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=enable-delivery-group-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=enable-delivery-group-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=enable-delivery-group-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=enable-delivery-group-domain.cli ### Disable and Enable Delivery Group in a Standalone Server -To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the `disable-delivery-group-standalone.cli` script on both servers, replacing ${jboss.home.name} with the path to your server: +To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the `disable-delivery-group-standalone.cli` script on both servers, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=disable-delivery-group-standalone.cli - ${jboss.home.name}_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=disable-delivery-group-standalone.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=disable-delivery-group-standalone.cli - ${jboss.home.name}_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=disable-delivery-group-standalone.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=disable-delivery-group-standalone.cli + EAP7_HOME_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=disable-delivery-group-standalone.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=disable-delivery-group-standalone.cli + EAP7_HOME_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=disable-delivery-group-standalone.cli Similarly, to enable the delivery group, run the `enable-delivery-group-standalone.cli` script in both servers: - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=enable-delivery-group-standalone.cli - ${jboss.home.name}_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=enable-delivery-group-standalone.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=enable-delivery-group-standalone.cli - ${jboss.home.name}_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=enable-delivery-group-standalone.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=enable-delivery-group-standalone.cli + EAP7_HOME_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=enable-delivery-group-standalone.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=enable-delivery-group-standalone.cli + EAP7_HOME_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=enable-delivery-group-standalone.cli ## Undeploy the Archive @@ -352,21 +352,21 @@ When you are finished testing, use the following instructions to undeploy the qu ### Undeploy the quickstart in a Managed Domain 1. Make sure you have started the managed domain as described above. -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the `undeploy-domain.cli` script, replacing ${jboss.home.name} with the path to your server: +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the `undeploy-domain.cli` script, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=undeploy-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=undeploy-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=undeploy-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=undeploy-domain.cli ### Undeploy the quickstart in a Standalone Server 1. Make sure you have started the standalone server as described above. -2. Open a command prompt, navigate to the root directory of this quickstart, and run the `undeploy-standalone.cli` script, replacing ${jboss.home.name}_1 and ${jboss.home.name}_2 with the path to the appropriate server: +2. Open a command prompt, navigate to the root directory of this quickstart, and run the `undeploy-standalone.cli` script, replacing EAP7_HOME_1 and EAP7_HOME_2 with the path to the appropriate server: - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=undeploy-standalone.cli - ${jboss.home.name}_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=undeploy-standalone.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=undeploy-standalone.cli - ${jboss.home.name}_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=undeploy-standalone.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=undeploy-standalone.cli + EAP7_HOME_2/bin/jboss-cli.sh --connect controller=localhost:10090 --file=undeploy-standalone.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=undeploy-standalone.cli + EAP7_HOME_2\bin\jboss-cli.bat --connect controller=localhost:10090 --file=undeploy-standalone.cli ## Remove the Server Configuration @@ -379,23 +379,23 @@ You can remove the domain configuration by manually restoring the backup configu _Note: This method ensures the server is restored to its prior configuration._ -1. If it is running, stop the ${product.name} server. -2. Restore the `${jboss.home.name}/domain/configuration/domain.xml` and `${jboss.home.name}/domain/configuration/host.xml` files with the back-up copies -of the files. Be sure to replace ${jboss.home.name} with the path to your server. +1. If it is running, stop the JBoss EAP server. +2. Restore the `EAP7_HOME/domain/configuration/domain.xml` and `EAP7_HOME/domain/configuration/host.xml` files with the back-up copies +of the files. Be sure to replace EAP7_HOME with the path to your server. #### Remove the Domain Server Configuration by Running the Management CLI Script _Note: This script returns the server to a default configuration and the result might not match the server configuration prior to testing this quickstart. If you were not running with the default configuration before testing this quickstart, you should follow the intructions above to manually restore the configuration to its previous state._ -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/domain.sh - For Windows: ${jboss.home.name}\bin\domain.bat + For Linux: EAP7_HOME/bin/domain.sh + For Windows: EAP7_HOME\bin\domain.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the `remove-domain.cli` script, replacing ${jboss.home.name} with the path to your server. +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the `remove-domain.cli` script, replacing EAP7_HOME with the path to your server. - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=remove-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=remove-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-domain.cli This script removes the server configuration that was done by the `install-domain.cli` script. You should see the following result following the script commands: @@ -410,26 +410,26 @@ You can remove the domain configuration by manually restoring the back-up copies _Note: This method ensures the server is restored to its prior configuration._ -1. If they are running, stop both ${product.name} servers. -2. Restore the `${jboss.home.name}_1/standalone/configuration/standalone-full-ha.xml` file with the back-up copies of the file. Be sure to replace ${jboss.home.name}_1 with the path to your server. +1. If they are running, stop both JBoss EAP servers. +2. Restore the `EAP7_HOME_1/standalone/configuration/standalone-full-ha.xml` file with the back-up copies of the file. Be sure to replace EAP7_HOME_1 with the path to your server. #### Remove the Standalone Configuration by Running the Management CLI Script _Note: This script returns the server to a default configuration and the result might not match the server configuration prior to testing this quickstart. If you were not running with the default configuration before testing this quickstart, you should follow the intructions above to manually restore the configuration to its previous state._ -1. Start the ${product.name} server by typing the following, replacing ${jboss.home.name}_1 with the path to your first server: +1. Start the JBoss EAP server by typing the following, replacing EAP7_HOME_1 with the path to your first server: - For Linux: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full-ha.xml - For Windows: ${jboss.home.name}_1\bin\domain.bat -c standalone-full-ha.xml -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the `remove-standalone.cli` script, replacing ${jboss.home.name}_2 with the path to your second server. + For Linux: EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml + For Windows: EAP7_HOME_1\bin\domain.bat -c standalone-full-ha.xml +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the `remove-standalone.cli` script, replacing EAP7_HOME_2 with the path to your second server. - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=remove-standalone.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=remove-standalone.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=remove-standalone.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=remove-standalone.cli This script removes the server configuration that was done by the `install-standalone.cli` script. You should see the following result following the script commands: The batch executed successfully -### Delete the Cloned Standalone ${product.name} Directory +### Delete the Cloned Standalone JBoss EAP Directory -1. If it is running, stop the second instance of the ${product.name} server. +1. If it is running, stop the second instance of the JBoss EAP server. 2. Delete the cloned directory. diff --git a/messaging-clustering-singleton/pom.xml b/messaging-clustering-singleton/pom.xml index ad42dd8baa..401dcee581 100644 --- a/messaging-clustering-singleton/pom.xml +++ b/messaging-clustering-singleton/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml messaging-clustering-singleton diff --git a/messaging-clustering/README.html b/messaging-clustering/README.html new file mode 100644 index 0000000000..3ba4d2dba8 --- /dev/null +++ b/messaging-clustering/README.html @@ -0,0 +1,242 @@ + + + messaging-clustering: Messaging Example that Demonstrates Clustering + + + +

messaging-clustering: Messaging Example that Demonstrates Clustering

+

Author: Jess Sightler
+Level: Intermediate
+Technologies: JMS, MDB
+Summary: The messaging-clustering quickstart does not contain any code and instead uses the helloworld-mdb quickstart to demonstrate clustering using ActiveMQ Messaging.
+Prerequisites: helloworld-mdb
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The messaging-clustering quickstart demonstrates the use of clustering with Apache ActiveMQ and Red Hat JBoss Enterprise Application Platform. It uses the helloworld-mdb quickstart for its tests, so there is no code associated with this quickstart. Instructions are provided to run the quickstart on either a standalone server or in a managed domain.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Prerequisites

+

IMPORTANT: This quickstart depends on the deployment of the helloworld-mdb quickstart WAR for its tests. Before you continue, you must build the helloworld-mdb quickstart WAR.

+

Open a command prompt and navigate to the root directory of the helloworld-mdb quickstart. Type this command to build the WAR archive:

+
    mvn clean install
+
+

See the helloworld-mdb README for further information about this quickstart.

+

Configure the Server and Deploy the Quickstart

+

You can choose to deploy and run this quickstart in a managed domain or on a standalone server. The sections below describe how to configure and start the server for both modes.

+

NOTE - Before you begin:

+
    +
  1. +

    If it is running, stop the JBoss EAP server.

    +
    2. +
  2. +

    If you plan to test using a standalone server, back up the file:

    +
    EAP7_HOME/standalone/configuration/standalone-full-ha.xml
+
    +
    3. +
  3. +

    If you plan to test using a managed domain, back up the following files:

    +
    EAP7_HOME/domain/configuration/domain.xml
+EAP7_HOME/domain/configuration/host.xml
+
    +
    4. +
+

After you have completed testing this quickstart, you can replace these files to restore the server to its original configuration.

+

Configure the Server and Deploy the Quickstart to a Managed Domain

+

You configure the server by running the install-domain.cli script provided in the root directory of this quickstart.

+

Start the server in domain mode.

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server in domain mode: +
    For Linux:   EAP7_HOME/bin/domain.sh
+For Windows: EAP7_HOME\bin\domain.bat
+
    +
    3. +
+

Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI

+
    +
  1. +

    Review the install-domain.cli file in the root of this quickstart directory. This script creates the server group and servers and configures messaging clustering for testing this quickstart. You will note it does the following:

    +
      +
    • Stops the servers
      • +
    • Creates a server-group to test ActiveMQ Clustering
      • +
    • Adds 2 servers to the server-group
      • +
    • Configures ActiveMQ clustering in the full-ha profile
      • +
    • Deploys the helloworld-mdb.war archive
      • +
    • Restarts the servers.
      • +
    +

    NOTE: If your helloworld-mdb quickstart is not located at the same level in the file structure as this quickstart, you must modify its path in this script. Find the NOTE: in the file for instructions.

    +
    2. +
  2. +

    Open a command prompt, navigate to the root directory of this quickstart, and run the following command to run the script:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=install-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=install-domain.cli
+
    +
    3. +
+

You should see "outcome" => "success" for all of the commands. 3. Restart the server in domain mode as described above.

+

Configure the Server and Deploy the Quickstart to a Standalone Server

+

If you choose to use standalone servers rather than domain mode, you will need two instances of the application server. Application server 2 must be started with a port offset parameter provided to the startup script as -Djboss.socket.binding.port-offset=100.

+

Since both application servers must be configured in the same way, you must configure the first server and then clone it.

+

Start the Server in Standalone Mode using the Full HA Profile.

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the full-ha profile. This profile supports clustering/HA +
    For Linux:   EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml
+For Windows: EAP7_HOME_1\bin\standalone.bat -c standalone-full-ha.xml
+
    +
    3. +
+

Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI

+
    +
  1. Review the install-standalone.cli file in the root of this quickstart directory. This script configures clustering for a standalone server. You will note it does the following: +
      +
    • Enables console logging. By default, the full HA profile does not log to the console, so this script enables it.
      • +
    • Enables clustering and sets a cluster password
      • +
    • Enables clustering in the RemoteConnectionFactory
      • +
    • Deploys the helloworld-mdb.war archive
      • +
    • Reloads the server configuration
      • +
    +

    NOTE: If your helloworld-mdb quickstart is not located at the same level in the file structure as this quickstart, you must modify its path in this script. Find the NOTE: in the file for instructions.

    +
    2. +
  2. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to run the script: +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=install-standalone.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=install-standalone.cli
+
    +
    3. +
+

You should see "outcome" => "success" for all of the commands.

+

Clone the JBoss EAP Directory

+

After you have successfully configured the server, you must make a copy of this JBoss EAP directory structure to use for the second server.

+
    +
  1. Stop the server.
    2. +
  2. Make a copy of this JBoss EAP directory structure to use for the second server.
    3. +
  3. Remove the following directories from the cloned instance: +
    EAP7_HOME_2/standalone/data/activemq/bindings
+EAP7_HOME_2/standalone/data/activemq/journal
+EAP7_HOME_2/standalone/data/activemq/largemessages
+
    +
    4. +
+

Start the JBoss EAP Standalone Servers with the Full HA Profile

+

When you start the servers, you must pass the cluster password on the command line to avoid the warning "AMQ222186: unable to authorise cluster control".

+

If you are using Linux:

+
    Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml
+    Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100
+
+

If you are using Windows:

+
    Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full-ha.xml
+    Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100
+
+

Access the Application

+

Access the Application Running in Domain Dode

+

The application will be running at the following URL: http://localhost:9080/helloworld-mdb/HelloWorldMDBServletClient.

+

It will send some messages to the queue.

+

To send messages to the topic, use the following URL: http://localhost:9080/helloworld-mdb/HelloWorldMDBServletClient?topic

+

Access the Application Running in Standalone Mode

+

The application will be running at the following URL: http://localhost:8080/helloworld-mdb/HelloWorldMDBServletClient.

+

It will send some messages to the queue.

+

To send messages to the topic, use the following URL: http://localhost:8080/helloworld-mdb/HelloWorldMDBServletClient?topic

+

Investigate the Server Console Output

+

Look at the JBoss EAP server console or log and you should see log messages like the following:

+
    [Server:quickstart-messagingcluster-node1] 16:34:41,165 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-8 (ActiveMQ-client-global-threads-1067469862)) Received Message from queue: This is message 1
+    [Server:quickstart-messagingcluster-node1] 16:34:41,274 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-8 (ActiveMQ-client-global-threads-1067469862)) Received Message from queue: This is message 3
+    [Server:quickstart-messagingcluster-node1] 16:34:41,323 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1067469862)) Received Message from queue: This is message 5
+    [Server:quickstart-messagingcluster-node2] 16:34:41,324 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-8 (ActiveMQ-client-global-threads-1771031398)) Received Message from queue: This is message 2
+    [Server:quickstart-messagingcluster-node2] 16:34:41,330 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-7 (ActiveMQ-client-global-threads-1771031398)) Received Message from queue: This is message 4
+
+

Note that the logging indicates messages have arrived from both node 1 (quickstart-messagingcluster-node1) as well as node 2 (quickstart-messagingcluster-node2).

+

Note: You will see the following warnings in the server logs. You can ignore these warnings as they are intended for production servers.

+
    WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the send buffer of socket DatagramSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
+    WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the receive buffer of socket DatagramSocket was set to 20MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+    WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
+    WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
+
+

NOTE: After the server has been running for a period of time, you may see the following warnings in the server log, which are followed by a stacktrace. You can ignore these warnings as this is is a known issue and is harmless. See JBEAP-794 for more information.

+
    WARN  [org.infinispan.topology.ClusterTopologyManagerImpl] (transport-thread--p15-t6) ISPN000197: Error updating cluster member list: org.infinispan.util.concurrent.TimeoutException: Replication timeout for <application-name>
+
+

Undeploy the Archive

+

When you are finished testing, use the following instructions to undeploy the quickstart.

+

Undeploy the quickstart in Domain Mode

+
    +
  1. Make sure you have started the JBoss EAP server in domain mode as described above.
    2. +
  2. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to undeploy the helloworld-mdb quickstart: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=undeploy-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=undeploy-domain.cli
+
    +
    3. +
+

Undeploy the quickstart in Standalone Mode

+
    +
  1. Make sure you have started the JBoss EAP server in standalone mode as described above.
    2. +
  2. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to undeploy the helloworld-mdb quickstart: +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=undeploy-standalone.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=undeploy-standalone.cli
+
    +
    3. +
+

Remove the Server Configuration

+

Remove the Domain Server Configuration

+

You can remove the domain configuration by manually restoring the back-up copies the configuration files or by running the JBoss CLI Script.

+

Remove the Domain Server Configuration Manually

+

Note: This method ensures the server is restored to its prior configuration.

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Restore the EAP7_HOME/domain/configuration/domain.xml and EAP7_HOME/domain/configuration/host.xml files with the back-up copies of the files. Be sure to replace EAP7_HOME with the path to your server.
    3. +
+

Remove the Domain Server Configuration by Running the JBoss CLI Script

+

Note: This script returns the server to a default configuration and the result may not match the server configuration prior to testing this quickstart. If you were not running with the default configuration before testing this quickstart, you should follow the intructions above to manually restore the configuration to its previous state.

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:   EAP7_HOME/bin/domain.sh
+For Windows: EAP7_HOME\bin\domain.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server. +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=remove-domain.cli
+
    +
    3. +
+

This script removes the server configuration that was done by the install-domain.cli script. You should see the following result following the script commands:

+
    The batch executed successfully
+
+

_Note: If the :stop-server command does not complete before the next commands are issued, you may see an error similar to the following:

+
     {"JBAS014653: Composite operation failed and was rolled back. Steps that failed:" => {"Operation step-1" => "JBAS010977: Server (quickstart-messagingcluster-node1) still running"}}
+
+

Simply wait a few seconds and run the command a second time._

+

Remove the Standalone Server Configuration

+

You can remove the domain configuration by manually restoring the back-up copies the configuration files or by running the JBoss CLI Script.

+

Remove the Standalone Server Configuration Manually

+

Note: This method ensures the server is restored to its prior configuration.

+
    +
  1. If they are running, stop both JBoss EAP servers.
    2. +
  2. Restore the EAP7_HOME_1/standalone/configuration/standalone-full-ha.xml file with the back-up copies of the file. Be sure to replace EAP7_HOME_1 with the path to your server.
    3. +
+

Remove the Standalone Configuration by Running the JBoss CLI Script

+

Note: This script returns the server to a default configuration and the result may not match the server configuration prior to testing this quickstart. If you were not running with the default configuration before testing this quickstart, you should follow the intructions above to manually restore the configuration to its previous state.

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:   EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml
+For Windows: EAP7_HOME_1\bin\domain.bat -c standalone-full-ha.xml
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME_1 with the path to your server. +
    For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=remove-standalone.cli
+For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=remove-standalone.cli
+
    +
    3. +
+

This script removes the server configuration that was done by the install-standalone.cli script. You should see the following result following the script commands:

+
    The batch executed successfully
+
+

Delete the Cloned Standalone JBoss EAP Directory

+
    +
  1. If it is running, stop the second instance of the JBoss EAP server.
    2. +
  2. Delete the cloned directory.
    3. +
+ + \ No newline at end of file diff --git a/messaging-clustering/README.md b/messaging-clustering/README.md index e2a9d3de99..f7fe888039 100644 --- a/messaging-clustering/README.md +++ b/messaging-clustering/README.md @@ -5,23 +5,23 @@ Level: Intermediate Technologies: JMS, MDB Summary: The `messaging-clustering` quickstart does not contain any code and instead uses the `helloworld-mdb` quickstart to demonstrate clustering using ActiveMQ Messaging. Prerequisites: helloworld-mdb -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `messaging-clustering` quickstart demonstrates the use of clustering with Apache ActiveMQ and ${product.name.full}. It uses the [helloworld-mdb](../helloworld-mdb/README.md) quickstart for its tests, so there is no code associated with this quickstart. Instructions are provided to run the quickstart on either a standalone server or in a managed domain. +The `messaging-clustering` quickstart demonstrates the use of clustering with Apache ActiveMQ and Red Hat JBoss Enterprise Application Platform. It uses the [helloworld-mdb](../helloworld-mdb/README.md) quickstart for its tests, so there is no code associated with this quickstart. Instructions are provided to run the quickstart on either a standalone server or in a managed domain. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Prerequisites @@ -42,17 +42,17 @@ You can choose to deploy and run this quickstart in a managed domain or on a sta _NOTE - Before you begin:_ -1. If it is running, stop the ${product.name} server. +1. If it is running, stop the JBoss EAP server. 2. If you plan to test using a standalone server, back up the file: - ${jboss.home.name}/standalone/configuration/standalone-full-ha.xml + EAP7_HOME/standalone/configuration/standalone-full-ha.xml 3. If you plan to test using a managed domain, back up the following files: - ${jboss.home.name}/domain/configuration/domain.xml - ${jboss.home.name}/domain/configuration/host.xml + EAP7_HOME/domain/configuration/domain.xml + EAP7_HOME/domain/configuration/host.xml After you have completed testing this quickstart, you can replace these files to restore the server to its original configuration. @@ -62,11 +62,11 @@ After you have completed testing this quickstart, you can replace these files to You configure the server by running the install-domain.cli script provided in the root directory of this quickstart. #### Start the server in domain mode. -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server in domain mode: - For Linux: ${jboss.home.name}/bin/domain.sh - For Windows: ${jboss.home.name}\bin\domain.bat + For Linux: EAP7_HOME/bin/domain.sh + For Windows: EAP7_HOME\bin\domain.bat #### Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI @@ -84,8 +84,8 @@ You configure the server by running the install-domain.cli script provided in th 2. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to run the script: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=install-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=install-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=install-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=install-domain.cli You should see "outcome" => "success" for all of the commands. 3. Restart the server in domain mode as described above. @@ -99,11 +99,11 @@ Since both application servers must be configured in the same way, you must conf #### Start the Server in Standalone Mode using the Full HA Profile. -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the full-ha profile. This profile supports clustering/HA - For Linux: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full-ha.xml - For Windows: ${jboss.home.name}_1\bin\standalone.bat -c standalone-full-ha.xml + For Linux: EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml + For Windows: EAP7_HOME_1\bin\standalone.bat -c standalone-full-ha.xml #### Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI @@ -119,36 +119,36 @@ Since both application servers must be configured in the same way, you must conf must modify its path in this script. Find the `NOTE:` in the file for instructions._ 2. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to run the script: - For Linux: ${jboss.home.name}_1/bin/jboss-cli.sh --connect --file=install-standalone.cli - For Windows: ${jboss.home.name}_1\bin\jboss-cli.bat --connect --file=install-standalone.cli + For Linux: EAP7_HOME_1/bin/jboss-cli.sh --connect --file=install-standalone.cli + For Windows: EAP7_HOME_1\bin\jboss-cli.bat --connect --file=install-standalone.cli You should see "outcome" => "success" for all of the commands. -#### Clone the ${product.name} Directory +#### Clone the JBoss EAP Directory -After you have successfully configured the server, you must make a copy of this ${product.name} directory structure to use for the second server. +After you have successfully configured the server, you must make a copy of this JBoss EAP directory structure to use for the second server. 1. Stop the server. -2. Make a copy of this ${product.name} directory structure to use for the second server. +2. Make a copy of this JBoss EAP directory structure to use for the second server. 3. Remove the following directories from the cloned instance: - ${jboss.home.name}_2/standalone/data/activemq/bindings - ${jboss.home.name}_2/standalone/data/activemq/journal - ${jboss.home.name}_2/standalone/data/activemq/largemessages + EAP7_HOME_2/standalone/data/activemq/bindings + EAP7_HOME_2/standalone/data/activemq/journal + EAP7_HOME_2/standalone/data/activemq/largemessages -#### Start the ${product.name} Standalone Servers with the Full HA Profile +#### Start the JBoss EAP Standalone Servers with the Full HA Profile When you start the servers, you must pass the cluster password on the command line to avoid the warning "AMQ222186: unable to authorise cluster control". If you are using Linux: - Server 1: ${jboss.home.name}_1/bin/standalone.sh -c standalone-full-ha.xml - Server 2: ${jboss.home.name}_2/bin/standalone.sh -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1/bin/standalone.sh -c standalone-full-ha.xml + Server 2: EAP7_HOME_2/bin/standalone.sh -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 If you are using Windows: - Server 1: ${jboss.home.name}_1\bin\standalone.bat -c standalone-full-ha.xml - Server 2: ${jboss.home.name}_2\bin\standalone.bat -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 + Server 1: EAP7_HOME_1\bin\standalone.bat -c standalone-full-ha.xml + Server 2: EAP7_HOME_2\bin\standalone.bat -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 ## Access the Application @@ -172,7 +172,7 @@ To send messages to the topic, use the following URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml messaging-clustering diff --git a/numberguess/README.html b/numberguess/README.html new file mode 100644 index 0000000000..8314c43759 --- /dev/null +++ b/numberguess/README.html @@ -0,0 +1,60 @@ + + + numberguess: Example Using CDI and JSF + + + +

numberguess: Example Using CDI and JSF

+

Author: Pete Muir
+Level: Beginner
+Technologies: CDI, JSF
+Summary: The numberguess quickstart demonstrates the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The numberguess quickstart demonstrates the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
     For Linux:   EAP7_HOME/bin/standalone.sh
+ For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/numberguess.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/numberguess/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
  mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/numberguess/README.md b/numberguess/README.md index add67f43e1..0645b5d68c 100644 --- a/numberguess/README.md +++ b/numberguess/README.md @@ -3,55 +3,55 @@ Author: Pete Muir Level: Beginner Technologies: CDI, JSF -Summary: The `numberguess` quickstart demonstrates the use of *CDI* (Contexts and Dependency Injection) and *JSF* (JavaServer Faces) in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `numberguess` quickstart demonstrates the use of *CDI* (Contexts and Dependency Injection) and *JSF* (JavaServer Faces) in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `numberguess` quickstart demonstrates the use of *CDI* (Contexts and Dependency Injection) and *JSF* (JavaServer Faces) in ${product.name.full}. +The `numberguess` quickstart demonstrates the use of *CDI* (Contexts and Dependency Injection) and *JSF* (JavaServer Faces) in Red Hat JBoss Enterprise Application Platform. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/numberguess.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -60,7 +60,7 @@ The application will be running at the following URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml numberguess diff --git a/payment-cdi-event/README.html b/payment-cdi-event/README.html new file mode 100644 index 0000000000..efccc17eea --- /dev/null +++ b/payment-cdi-event/README.html @@ -0,0 +1,94 @@ + + + payment-cdi-event: Use CDI Events to Process Debit and Credit Operations + + + +

payment-cdi-event: Use CDI Events to Process Debit and Credit Operations

+

Author: Elvadas Nono
+Level: Beginner
+Technologies: CDI, JSF
+Summary: The payment-cdi-event quickstart demonstrates how to create credit and debit CDI Events in JBoss EAP, using a JSF front-end client.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The payment-cdi-event quickstart demonstrates how to use CDI Events in Red Hat JBoss Enterprise Application Platform.

+

The JSF front-end client allows you to create both credit and debit operation events.

+

To test this quickstart, enter an amount, choose either a Credit or Debit operation, and then click on Pay to create the event.

+

A Session scoped (@SessionScoped) payment event handler catches the operation and produces (@Produces) a named list of all operations performed during this session. The event is logged in the JBoss EAP server log and the event list is displayed in a table at the bottom of the form.

+

The payment-cdi-event quickstart defines the following classes and interfaces:

+
    +
  • The beans package contains the PaymentBean bean class:
    • +
  • This is a session scoped bean that stores the payment form information: +
      +
    • payment amount
      • +
    • operation type: debit or credit
      • +
    +
    • +
  • It contains the following utility methods: +
      +
    • private void init(): This is a PostConstruct (@PostConstruct) method that performs initialization before the class is put into service. It resets the amount to $0 and the paymentOption to the default type of debit.
      • +
    • public String pay(): This method processes the operation when the user clicks on submit. We have only one JSF page, so the method does not return anything and the flow of control does not change.
      • +
    • public void reset(): Reset calls the init() method reinitialize the form values.
      • +
    +
    • +
  • The events package contains the PaymentEvent class and the enum PaymentTypeEnum.
    • +
  • PaymentEvent: We have only one event that handles both credit and debit operations. Qualifiers help us to make the difference at injection point.
    • +
  • PaymentTypeEnum: A typesafe enum is used to represent the operation payment type. It contains utility methods to convert between String and Enum.
    • +
  • The qualifiers package contains the Credit and Debit interfaces. The annotation determines the operation of the injecting Event.
    • +
  • The handler package contains interfaces and implementations of PaymentEvent observers.
    • +
  • ICreditEventObserver: Interface to listen to CREDIT event only (@Observes @Credit).
    • +
  • IDebitEventObserver: Interface to listen to DEBIT event (@Observes @Debit).
    • +
  • PaymentHandler: The concrete implementation of the payment handler. +
      +
    • It implements both ICreditEventObserver and IDebitEventObserver.
      • +
    • The payment handler exposes the list of events caught during a session (@Named name=payments).
      • +
    +
    • +
  • The resources package contains the Resources class that produces the logger for the application.
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the JBoss EAP Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/payment-cdi-event.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/payment-cdi-event/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/payment-cdi-event/README.md b/payment-cdi-event/README.md index 7ad74d797f..3fd9d07728 100644 --- a/payment-cdi-event/README.md +++ b/payment-cdi-event/README.md @@ -3,19 +3,19 @@ Author: Elvadas Nono Level: Beginner Technologies: CDI, JSF -Summary: The `payment-cdi-event` quickstart demonstrates how to create credit and debit *CDI Events* in ${product.name}, using a JSF front-end client. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `payment-cdi-event` quickstart demonstrates how to create credit and debit *CDI Events* in JBoss EAP, using a JSF front-end client. +Target Product: JBoss EAP +Source: ## What is it? -The `payment-cdi-event` quickstart demonstrates how to use *CDI Events* in ${product.name.full}. +The `payment-cdi-event` quickstart demonstrates how to use *CDI Events* in Red Hat JBoss Enterprise Application Platform. The JSF front-end client allows you to create both credit and debit operation events. To test this quickstart, enter an amount, choose either a Credit or Debit operation, and then click on *Pay* to create the event. -A Session scoped (`@SessionScoped`) payment event handler catches the operation and produces (`@Produces`) a named list of all operations performed during this session. The event is logged in the ${product.name} server log and the event list is displayed in a table at the bottom of the form. +A Session scoped (`@SessionScoped`) payment event handler catches the operation and produces (`@Produces`) a named list of all operations performed during this session. The event is logged in the JBoss EAP server log and the event list is displayed in a table at the bottom of the form. The `payment-cdi-event` quickstart defines the following classes and interfaces: @@ -42,44 +42,44 @@ The `payment-cdi-event` quickstart defines the following classes and interfaces: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). -## Start the ${product.name} Server +## Start the JBoss EAP Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/payment-cdi-event.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -88,7 +88,7 @@ The application will be running at the following URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml payment-cdi-event diff --git a/picketlink-sts/README.html b/picketlink-sts/README.html new file mode 100644 index 0000000000..ffc0af2ca3 --- /dev/null +++ b/picketlink-sts/README.html @@ -0,0 +1,204 @@ + + + picketlink-sts: PicketLink Federation: WS-Trust Security Token Service + + + +

picketlink-sts: PicketLink Federation: WS-Trust Security Token Service

+

Author: Peter Skopek
+Level: Advanced
+Technologies: WS-Trust, SAML
+Summary: The picketlink-sts quickstart demonstrates how to deploy a fully compliant WS-Trust Security Token Service (STS).
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The picketlink-sts quickstart demonstrates how to deploy a fully compliant WS-Trust Security Token Service (STS) to Red Hat JBoss Enterprise Application Platform.

+

WS-Trust extends the WS-Security specification to allow the issuance, renewal, and validation of security tokens. Many WS-Trust functions center around the use of a Security Token Service, or STS. The STS is contacted to obtain security tokens that are used to create messages to talk to the services. The primary use of the STS is to acquire SAML tokens used to talk to the service. The STS also plays an important role when you need to propagate credentials between different layers, for example, the web and service layer.

+

PicketLink also supports different token providers, which means you can provide your own custom security tokens.

+

Note: This quickstart is not a fully functional application. It is a JAX-WS Endpoint based on PicketLink's WS-Trust implementation, which by default, allows you to issue, renew and validate SAML assertions. It is a service intended to be called by other applications.

+

How to Use This Quickstart

+

This quickstart is preconfigured to use the picketlink-sts security domain. By default, the STS is protected to only allow requests from authenticated users. All users and also their roles, are defined in two properties files:

+
    Users: src/main/resources/users.properties
+    Roles: src/main/resources/roles.properties
+
+

You can view the WSDL for the STS at the following URL: http://localhost:8080/picketlink-sts?wsdl.

+

From a JAX-WS perspective, you can use any tool you want to start using the STS. Below is an example of a SOAP envelope asking the STS to issue a SAML v2.0 Assertion:

+
    <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:picketlink:identity-federation:sts">
+        <soap:Header/>
+        <soap:Body>
+            <wst:RequestSecurityToken xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
+                <wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</wst:TokenType>
+                <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</wst:RequestType>
+            </wst:RequestSecurityToken>
+        </soap:Body>
+    </soap:Envelope>
+
+

There is a simple example of WS-Trust client usage provided by PicketLink. To use this example deploy PicketLink STS as described below and run the mvn exec:java command. The assertion from PicketLink STS is printed to the console. This process is described in detail below in the section entitled Access the Application.

+

Note: This example is not suitable for production use. You must change the application security to comply with your organization's standards.

+

Where to Find Additional Information

+ +

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Configure the Server

+

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-security-domain.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-security-domain.cli file in the root of this quickstart directory. This script adds the picketlink-sts security domain to the security subsystem in the server configuration and configures authentication access.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-security-domain.cli
+
    +
    5. +
+

If you are running the controller on different host, pass the following argument, replacing HOST_NAME and PORT_NUMBER with the correct values:

+
    --controller=HOST_NAME:PORT_NUMBER
+
+

You should see the following result when you run the script:

+
    The batch executed successfully
+    {"outcome" => "success"}
+
+

The batch file also restarts the server. 5. Stop the JBoss EAP server.

+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+

The following picketlink-sts security-domain was added to the security subsystem.

+
    <security-domain name="picketlink-sts">
+        <authentication>
+            <login-module code="UsersRoles " flag="required">
+                <module-option name="usersProperties" value="users.properties"/>
+                <module-option name="rolesProperties" value="roles.properties"/>
+            </login-module>
+        </authentication>
+    </security-domain>
+
+

Start the Server

+

If you do not have a running server:

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. This deploys target/picketlink-sts.war to the running instance of the server.
    5. +
+

Note: When you deploy the quickstart, you will see the following warnings in the server log. These warnings are expected.

+
    WARN  [org.jboss.as.dependency.deprecated] (MSC service thread 1-5) WFLYSRV0221: Deployment "deployment.picketlink-sts.war" is using a deprecated module ("org.picketlink:main") which may be removed in future versions without notice.
+    WARN  [org.jboss.as.dependency.deprecated] (MSC service thread 1-5) WFLYSRV0221: Deployment "deployment.picketlink-sts.war" is using a deprecated module ("org.picketlink:main") which may be removed in future versions without notice.
+
+

Access the Application

+

You can test the service as follows:

+
    +
  1. Open a command prompt and navigate to the root directory of this quickstart.
    2. +
  2. Type the following command: +
    mvn exec:java
+
    +
    3. +
  3. You should see a <saml:Assertion assertion from PicketLink STS along with a BUILD SUCCESS printed to the console. +
    Invoking token service to get SAML assertion for user:UserA with password:PassA
+SAML assertion for user:UserA successfully obtained!
+<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="ID_79157aa6-38ab-4e5e-a562-78bade9ffb82" IssueInstant="2013-11-18T18:19:35.955Z" Version="2.0"><saml:Issuer>PicketLinkSTS</saml:Issuer><dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:SignedInfo><dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#WithComments"/><dsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><dsig:Reference URI="#ID_79157aa6-38ab-4e5e-a562-78bade9ffb82"><dsig:Transforms><dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><dsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></dsig:Transforms><dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><dsig:DigestValue>7LaVacKTsP6wnuNlsQ6KASNDgdE=</dsig:DigestValue></dsig:Reference></dsig:SignedInfo><dsig:SignatureValue>jiyC63KG65d019PY7ThZzyojiU6iJMAr9N39uqrPr3HBGPfW7JjwFH9tahsFKjgoQQH7ToRLKZJKvm12TmDured+s+5VyI+Py6TsDiaQCRnNSeARvYdXFwNCA1D8Sx0xDkXKWpgB3YZenBV6U0IZtmAa5CxXFKmdqxEzHweAPq0=</dsig:SignatureValue><dsig:KeyInfo><dsig:KeyValue><dsig:RSAKeyValue><dsig:Modulus>suGIyhVTbFvDwZdx8Av62zmP+aGOlsBN8WUE3eEEcDtOIZgO78SImMQGwB2C0eIVMhiLRzVPqoW1dCPAveTm653zHOmubaps1fY0lLJDSZbTbhjeYhoQmmaBro/tDpVw5lKJns2qVnMuRK19ju2dxpKwlYGGtrP5VQv00dfNPbs=</dsig:Modulus><dsig:Exponent>AQAB</dsig:Exponent></dsig:RSAKeyValue></dsig:KeyValue></dsig:KeyInfo></dsig:Signature><saml:Subject><saml:NameID NameQualifier="urn:picketlink:identity-federation">UserA</saml:NameID><saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/></saml:Subject><saml:Conditions NotBefore="2013-11-18T18:19:35.955Z" NotOnOrAfter="2013-11-18T20:19:35.955Z"/><saml:AuthnStatement AuthnInstant="2013-11-18T18:19:35.955Z"><saml:AuthnContext><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:cm:bearer</saml:AuthnContextClassRef></saml:AuthnContext></saml:AuthnStatement></saml:Assertion>
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 1.404s
+[INFO] Finished at: Mon Nov 18 13:19:36 EST 2013
+[INFO] Final Memory: 7M/146M
+[INFO] ------------------------------------------------------------------------
+
    +
    4. +
+

Note:: You also see the following warnings in the server log. These warnings are expected because the quickstart does not provide a configuration that persists tokens.

+
    INFO  [org.picketlink.common] (http-/127.0.0.1:8080-4) Loading STS configuration
+    WARN  [org.picketlink.common] (http-/127.0.0.1:8080-4) Security Token registry option not specified: Issued Tokens will not be persisted!
+    WARN  [org.picketlink.common] (http-/127.0.0.1:8080-4) Security Token registry option not specified: Issued Tokens will not be persisted!
+    INFO  [org.picketlink.common] (http-/127.0.0.1:8080-4) picketlink-sts.xml configuration file loaded
+    WARN  [org.picketlink.common] (http-/127.0.0.1:8080-4) Lifetime has not been specified. Using the default timeout value.
+
+

Undeploy and Remove the Security Domain Configuration

+

Undeploy and Remove the Security Domain Using the JBoss CLI

+

You can undeploy the quickstart and remove the security domain configuration in one easy step using the undeploy-and-remove-security-domain.cli script located in the root directory of this quickstart.

+
    +
  1. Open a new command prompt, navigate to the root directory of this quickstart.
    2. +
  2. Run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --file=undeploy-and-remove-security-domain.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --file=undeploy-and-remove-security-domain.cli
+
    +
    3. +
+

You should see the following result when you run the script:

+
    The batch executed successfully
+    process-state: reload-required
+
+

Undeploy the quickstart and Remove the Security Domain Manually

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
  4. Stop the JBoss EAP server.
    5. +
  5. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+
    +
  1. Be sure to configure the security domain by running the JBoss CLI commands as described above under Configure the JBoss EAP Server. Stop the server at the end of that step.
    2. +
  2. To deploy the server project, right-click on the picketlink-sts project and choose Run As --> Run on Server.
    3. +
  3. You are presented with a server message PicketLinkSTSRealm and challenged to enter valid authentication credentials. Enter the following information and then click OK. +
        UserName: JBoss
+    Password: JBoss
+
    +

    JBoss Developer Studio then displays the welcome file.

    +
    4. +
  4. Follow these steps to test the service. +
      +
    • Right-click on the picketlink-sts project and choose Run As --> Maven Build.
      • +
    • Enter picketlink-sts for the Name.
      • +
    • Enter exec:java for the Goals:.
      • +
    • Click Run.
      • +
    • Review the output in the console window.
      • +
    +
    5. +
  5. To undeploy the project, right-click on the picketlink-sts project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    6. +
+

NOTE: Be sure to Undeploy and Remove the Security Domain Configuration when you have completed testing this quickstart.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
  mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/picketlink-sts/README.md b/picketlink-sts/README.md index c021d0af8f..5ab1b38ff8 100644 --- a/picketlink-sts/README.md +++ b/picketlink-sts/README.md @@ -4,13 +4,13 @@ Author: Peter Skopek Level: Advanced Technologies: WS-Trust, SAML Summary: The `picketlink-sts` quickstart demonstrates how to deploy a fully compliant WS-Trust Security Token Service (STS). -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `picketlink-sts` quickstart demonstrates how to deploy a fully compliant WS-Trust Security Token Service (STS) to ${product.name.full}. +The `picketlink-sts` quickstart demonstrates how to deploy a fully compliant WS-Trust Security Token Service (STS) to Red Hat JBoss Enterprise Application Platform. WS-Trust extends the WS-Security specification to allow the issuance, renewal, and validation of security tokens. Many WS-Trust functions center around the use of a Security Token Service, or STS. @@ -30,7 +30,7 @@ This quickstart is preconfigured to use the `picketlink-sts` security domain. By Users: src/main/resources/users.properties Roles: src/main/resources/roles.properties -You can view the WSDL for the STS at the following URL: . +You can view the WSDL for the STS at the following URL: . From a JAX-WS perspective, you can use any tool you want to start using the STS. Below is an example of a SOAP envelope asking the STS to issue a SAML v2.0 Assertion: @@ -58,14 +58,14 @@ _Note: This example is not suitable for production use. You must change the appl ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Configure the Server @@ -73,20 +73,20 @@ In the following instructions, replace `${jboss.home.name}` with the actual path You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-security-domain.cli` file in the root of this quickstart directory. This script adds the `picketlink-sts` security domain to the `security` subsystem in the server configuration and configures authentication access. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-security-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-security-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-security-domain.cli If you are running the controller on different host, pass the following argument, replacing HOST_NAME and PORT_NUMBER with the correct values: @@ -97,11 +97,11 @@ You configure the security domain by running JBoss CLI commands. For your conven {"outcome" => "success"} The batch file also restarts the server. -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. The following `picketlink-sts` security-domain was added to the `security` subsystem. @@ -119,26 +119,26 @@ The following `picketlink-sts` security-domain was added to the `security` subsy If you do not have a running server: -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This deploys `target/${project.artifactId}.war` to the running instance of the server. +4. This deploys `target/picketlink-sts.war` to the running instance of the server. _Note:_ When you deploy the quickstart, you will see the following warnings in the server log. These warnings are expected. - WARN [org.jboss.as.dependency.deprecated] (MSC service thread 1-5) WFLYSRV0221: Deployment "deployment.${project.artifactId}.war" is using a deprecated module ("org.picketlink:main") which may be removed in future versions without notice. - WARN [org.jboss.as.dependency.deprecated] (MSC service thread 1-5) WFLYSRV0221: Deployment "deployment.${project.artifactId}.war" is using a deprecated module ("org.picketlink:main") which may be removed in future versions without notice. + WARN [org.jboss.as.dependency.deprecated] (MSC service thread 1-5) WFLYSRV0221: Deployment "deployment.picketlink-sts.war" is using a deprecated module ("org.picketlink:main") which may be removed in future versions without notice. + WARN [org.jboss.as.dependency.deprecated] (MSC service thread 1-5) WFLYSRV0221: Deployment "deployment.picketlink-sts.war" is using a deprecated module ("org.picketlink:main") which may be removed in future versions without notice. ## Access the Application @@ -178,10 +178,10 @@ _Note:_: You also see the following warnings in the server log. These warnings a You can undeploy the quickstart and remove the security domain configuration in one easy step using the `undeploy-and-remove-security-domain.cli` script located in the root directory of this quickstart. 1. Open a new command prompt, navigate to the root directory of this quickstart. -2. Run the following command, replacing ${jboss.home.name} with the path to your server: +2. Run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --file=undeploy-and-remove-security-domain.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --file=undeploy-and-remove-security-domain.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --file=undeploy-and-remove-security-domain.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --file=undeploy-and-remove-security-domain.cli You should see the following result when you run the script: The batch executed successfully @@ -190,21 +190,21 @@ You can undeploy the quickstart and remove the security domain configuration in ### Undeploy the quickstart and Remove the Security Domain Manually -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: mvn wildfly:undeploy -4. Stop the ${product.name} server. -5. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +4. Stop the JBoss EAP server. +5. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -1. Be sure to configure the security domain by running the JBoss CLI commands as described above under [Configure the ${product.name} Server](#configure-the-server). Stop the server at the end of that step. -2. To deploy the server project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Run on Server`. +1. Be sure to configure the security domain by running the JBoss CLI commands as described above under [Configure the JBoss EAP Server](#configure-the-server). Stop the server at the end of that step. +2. To deploy the server project, right-click on the `picketlink-sts` project and choose `Run As` --> `Run on Server`. 3. You are presented with a server message `PicketLinkSTSRealm` and challenged to enter valid authentication credentials. Enter the following information and then click `OK`. UserName: JBoss @@ -212,12 +212,12 @@ You can also start the server and deploy the quickstarts or run the Arquillian t JBoss Developer Studio then displays the welcome file. 4. Follow these steps to test the service. - * Right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven Build`. + * Right-click on the `picketlink-sts` project and choose `Run As` --> `Maven Build`. * Enter `picketlink-sts` for the `Name`. * Enter `exec:java` for the `Goals:`. * Click `Run`. * Review the output in the console window. -5. To undeploy the project, right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +5. To undeploy the project, right-click on the `picketlink-sts` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. _NOTE:_ Be sure to [Undeploy and Remove the Security Domain Configuration](#undeploy-and-remove-the-security-domain-configuration) when you have completed testing this quickstart. diff --git a/picketlink-sts/pom.xml b/picketlink-sts/pom.xml index 120da2190c..3bb60e40f6 100644 --- a/picketlink-sts/pom.xml +++ b/picketlink-sts/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml picketlink-sts diff --git a/pom.xml b/pom.xml index 2dd4a01cf7..b4b7b655ca 100644 --- a/pom.xml +++ b/pom.xml @@ -26,7 +26,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA pom ${qs.name.prefix} Parent JBoss EAP Quickstarts Parent @@ -245,10 +245,6 @@ - - org.apache.maven.plugins - maven-checkstyle-plugin - diff --git a/resteasy-jaxrs-client/README.html b/resteasy-jaxrs-client/README.html new file mode 100644 index 0000000000..0c77cab972 --- /dev/null +++ b/resteasy-jaxrs-client/README.html @@ -0,0 +1,78 @@ + + + resteasy-jaxrs-client: External JAX-RS Client + + + +

resteasy-jaxrs-client: External JAX-RS Client

+

Author: Blaine Mincey
+Level: Intermediate
+Technologies: JAX-RS, CDI
+Summary: The resteasy-jaxrs-client quickstart demonstrates an external JAX-RS RestEasy client, which interacts with a JAX-RS Web service that uses CDI and JAX-RS.
+Prerequisites: helloworld-rs
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The resteasy-jaxrs-client quickstart demonstrates an external JAX-RS RestEasy client which interacts with a JAX-RS Web service that uses CDI and JAX-RS in Red Hat JBoss Enterprise Application Platform.

+

This client "calls" the HelloWorld JAX-RS Web Service that was created in the helloworld-rs quickstart. See the Prerequisite section below for details on how to build and deploy the helloworld-rs quickstart.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Prerequisites

+

IMPORTANT: This quickstart depends on the deployment of the helloworld-rs quickstart for its test. Before running this quickstart, see the helloworld-rs README file for details on how to deploy it.

+

You can verify the deployment of the helloworld-rs quickstart by accessing the following content:

+ +

Run the Client

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Make sure the helloworld-rs quickstart has been deployed on the server as noted in the Prerequisites section above.
    3. +
  3. Open a command prompt and navigate to the root directory of this quickstart.
    4. +
  4. Type the following command to run the client: +
    mvn clean package exec:java
+
    +
    5. +
+

Investigate the Console Output

+

This command will compile the example and execute a test to make two separate requests to the Web Service. Towards the end of the Maven build output, you should see the following if the execution is successful:

+
    ===============================================
+    URL: http://localhost:8080/helloworld-rs/rest/xml
+    MediaType: application/xml
+
+    *** Response from Server ***
+
+    <xml><result>Hello World!</result></xml>
+
+    ===============================================
+    ===============================================
+    URL: http://localhost:8080/helloworld-rs/rest/json
+    MediaType: application/json
+
+    *** Response from Server ***
+
+    {"result":"Hello World!"}
+    ===============================================
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+
    +
  1. +

    Before you run this quickstart, be sure to import, deploy, and test the helloworld-rs quickstart as described in the Prerequisites section of this file.

    +
    2. +
  2. +

    Import this quickstart into JBoss Developer Studio.

    +
    3. +
  3. +

    Build and run the quickstart project.

    +
      +
    • Right-click on the resteasy-jaxrs-client project and choose Run As --> Maven build.
      • +
    • Enter clean package exec:java for the Goals: and click Run.
      • +
    • The client output displays in the Console window.
      • +
    +
    4. +
  4. To undeploy the helloworld-rs quickstart, right-click on the helloworld-rs project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    5. +
+ + \ No newline at end of file diff --git a/resteasy-jaxrs-client/README.md b/resteasy-jaxrs-client/README.md index 722527b3aa..70129036e6 100644 --- a/resteasy-jaxrs-client/README.md +++ b/resteasy-jaxrs-client/README.md @@ -5,22 +5,22 @@ Level: Intermediate Technologies: JAX-RS, CDI Summary: The `resteasy-jaxrs-client` quickstart demonstrates an external JAX-RS RestEasy client, which interacts with a JAX-RS Web service that uses *CDI* and *JAX-RS*. Prerequisites: helloworld-rs -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? The `resteasy-jaxrs-client` quickstart demonstrates an external JAX-RS RestEasy client which interacts with a JAX-RS Web service that uses *CDI* and *JAX-RS* -in ${product.name.full}. +in Red Hat JBoss Enterprise Application Platform. This client "calls" the HelloWorld JAX-RS Web Service that was created in the [helloworld-rs](../helloworld-rs/README.md) quickstart. See the **Prerequisite** section below for details on how to build and deploy the [helloworld-rs](../helloworld-rs/README.md) quickstart. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Prerequisites @@ -36,7 +36,7 @@ You can verify the deployment of the [helloworld-rs](../helloworld-rs/README.md) ## Run the Client -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Make sure the `helloworld-rs` quickstart has been deployed on the server as noted in the **Prerequisites** section above. 3. Open a command prompt and navigate to the root directory of this quickstart. 4. Type the following command to run the client: @@ -68,14 +68,14 @@ should see the following if the execution is successful: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). 1. Before you run this quickstart, be sure to import, deploy, and test the `helloworld-rs` quickstart as described in the [Prerequisites](#prerequisites) section of this file. 2. Import this quickstart into JBoss Developer Studio. 3. Build and run the quickstart project. - * Right-click on the `${project.artifactId}` project and choose `Run As` --> `Maven build`. + * Right-click on the `resteasy-jaxrs-client` project and choose `Run As` --> `Maven build`. * Enter `clean package exec:java` for the `Goals:` and click `Run`. * The client output displays in the `Console` window. 4. To undeploy the `helloworld-rs` quickstart, right-click on the `helloworld-rs` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. diff --git a/resteasy-jaxrs-client/pom.xml b/resteasy-jaxrs-client/pom.xml index 3389c7e838..c00f53d180 100644 --- a/resteasy-jaxrs-client/pom.xml +++ b/resteasy-jaxrs-client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml resteasy-jaxrs-client diff --git a/servlet-async/README.html b/servlet-async/README.html new file mode 100644 index 0000000000..1e5286856b --- /dev/null +++ b/servlet-async/README.html @@ -0,0 +1,62 @@ + + + servlet-async: How to Write an Asynchronous Servlet + + + +

servlet-async: How to Write an Asynchronous Servlet

+

Author: Christian Sadilek
+Level: Intermediate
+Technologies: Asynchronous Servlet, CDI, EJB
+Summary: The servlet-async quickstart demonstrates how to use asynchronous servlets to detach long-running tasks and free up the request processing thread.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The servlet-async quickstart is a sample project showing the use of asynchronous servlets in Red Hat JBoss Enterprise Application Platform.

+

It shows how to detach the execution of a long-running task from the request processing thread, so the thread is free to serve other client requests. The long-running tasks are executed using a dedicated thread pool and create the client response asynchronously.

+

A long-running task in this context does not refer to a computation intensive task executed on the same machine but could for example be contacting a third-party service that has limited resources or only allows for a limited number of concurrent connections. Moving the calls to this service into a separate and smaller sized thread pool ensures that less threads will be busy interacting with the long-running service and that more requests can be served that do not depend on this service.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/servlet-async.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/servlet-async/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/servlet-async/README.md b/servlet-async/README.md index e0c51e8028..469c4c0d83 100644 --- a/servlet-async/README.md +++ b/servlet-async/README.md @@ -4,12 +4,12 @@ Author: Christian Sadilek Level: Intermediate Technologies: Asynchronous Servlet, CDI, EJB Summary: The `servlet-async` quickstart demonstrates how to use asynchronous servlets to detach long-running tasks and free up the request processing thread. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `servlet-async` quickstart is a sample project showing the use of asynchronous servlets in ${product.name.full}. +The `servlet-async` quickstart is a sample project showing the use of asynchronous servlets in Red Hat JBoss Enterprise Application Platform. It shows how to detach the execution of a long-running task from the request processing thread, so the thread is free to serve other client requests. The long-running tasks are executed using a dedicated thread pool and create the @@ -23,44 +23,44 @@ not depend on this service. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/servlet-async.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -69,7 +69,7 @@ The application will be running at the following URL org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml servlet-async diff --git a/servlet-filterlistener/README.html b/servlet-filterlistener/README.html new file mode 100644 index 0000000000..6153bbf3b9 --- /dev/null +++ b/servlet-filterlistener/README.html @@ -0,0 +1,99 @@ + + + servlet-filterlistener: How to Write Servlet Filters and Listeners + + + +

servlet-filterlistener: How to Write Servlet Filters and Listeners

+

Author: Jonathan Fuerth
+Level: Intermediate
+Technologies: Servlet Filter, Servlet Listener
+Summary: The servlet-filterlistener quickstart demonstrates how to use Servlet filters and listeners in an application.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The servlet-filterlistener quickstart demonstrates how to use Servlet filters and listeners in Red Hat JBoss Enterprise Application Platform.

+

This example contains the following classes:

+
    +
  • FilterExampleServlet: A simple servlet that prints a form that contains an input field and a Send button.
    • +
  • VowelRemoverFilter: A servlet filter that removes the vowels from the text entered in the form.
    • +
  • ParameterDumpingRequestListener: A simple servlet request listener that creates a map of the original HTTP request parameter values before the filter is applied.
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/servlet-filterlistener.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/servlet-filterlistener/.

+

You are presented with a form containing an input field and a Send button. To test the quickstart:

+
    +
  1. Enter some text in the field, for example: +
    This is only a test!
+
    +
    2. +
  2. Click Send.
    3. +
  3. The servlet filter intercepts and removes the vowels from the text entered in the form and displays: +
    You Typed: Ths s nly tst!
+
    +
    4. +
  4. The server console displays the following log messages.
    5. +
+

The following messages appear in the log when you access the application URL. This is because the ParameterDumpingRequestListener, which is a ServletRequestListener, and the VowelRemoverFilter both map to the application context and print logs for every request. Note that the VowelRemoveFilter contains logic to handle empty input field arguments.

+
    INFO  [io.undertow.servlet] (default task-46) ParameterDumpingRequestListener: request has been initialized. It has 0 parameters:
+    INFO  [io.undertow.servlet] (default task-46) VowelRemoverFilter initialized
+    INFO  [io.undertow.servlet] (default task-46) VowelRemoverFilter invoking filter chain...
+    INFO  [io.undertow.servlet] (default task-46) VowelRemoverFilter done filtering request
+    INFO  [io.undertow.servlet] (default task-46) ParameterDumpingRequestListener: request has been destroyed
+    INFO  [io.undertow.servlet] (default task-48) ParameterDumpingRequestListener: request has been initialized. It has 0 parameters:
+    INFO  [io.undertow.servlet] (default task-48) VowelRemoverFilter invoking filter chain...
+    INFO  [io.undertow.servlet] (default task-48) VowelRemoverFilter done filtering request
+    INFO  [io.undertow.servlet] (default task-48) ParameterDumpingRequestListener: request has been destroyed
+
+
+The following messages appear in the log when you type "This is only a test!" in the input field and click `Send`.
+
+    INFO  [io.undertow.servlet] (default task-50) ParameterDumpingRequestListener: request has been initialized. It has 1 parameters:
+    INFO  [io.undertow.servlet] (default task-50)   userInput=This is only a test!
+    INFO  [io.undertow.servlet] (default task-50) VowelRemoverFilter invoking filter chain...
+    INFO  [io.undertow.servlet] (default task-50) VowelRemoverFilter done filtering request
+    INFO  [io.undertow.servlet] (default task-50) ParameterDumpingRequestListener: request has been destroyed
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/servlet-filterlistener/README.md b/servlet-filterlistener/README.md index c8c62d2db5..45fed1c3b1 100644 --- a/servlet-filterlistener/README.md +++ b/servlet-filterlistener/README.md @@ -4,12 +4,12 @@ Author: Jonathan Fuerth Level: Intermediate Technologies: Servlet Filter, Servlet Listener Summary: The `servlet-filterlistener` quickstart demonstrates how to use Servlet filters and listeners in an application. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `servlet-filterlistener` quickstart demonstrates how to use Servlet filters and listeners in ${product.name.full}. +The `servlet-filterlistener` quickstart demonstrates how to use Servlet filters and listeners in Red Hat JBoss Enterprise Application Platform. This example contains the following classes: @@ -20,39 +20,39 @@ This example contains the following classes: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/servlet-filterlistener.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . You are presented with a form containing an input field and a *Send* button. To test the quickstart: @@ -88,7 +88,7 @@ You are presented with a form containing an input field and a *Send* button. To ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -97,7 +97,7 @@ You are presented with a form containing an input field and a *Send* button. To ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/servlet-filterlistener/pom.xml b/servlet-filterlistener/pom.xml index 60ab4ddc00..d451da156a 100644 --- a/servlet-filterlistener/pom.xml +++ b/servlet-filterlistener/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml servlet-filterlistener diff --git a/servlet-security/README.html b/servlet-security/README.html new file mode 100644 index 0000000000..796b5678c5 --- /dev/null +++ b/servlet-security/README.html @@ -0,0 +1,230 @@ + + + servlet-security: Using Java EE Declarative Security to Control Servlet Access + + + +

servlet-security: Using Java EE Declarative Security to Control Servlet Access

+

Author: Sherif F. Makary, Pedro Igor, Stefan Guilhen
+Level: Intermediate
+Technologies: Servlet, Security
+Summary: The servlet-security quickstart demonstrates the use of Java EE declarative security to control access to Servlets and Security in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The servlet-security quickstart demonstrates the use of Java EE declarative security to control access to Servlets and Security in Red Hat JBoss Enterprise Application Platform.

+

When you deploy this example, two users are automatically created for you: user quickstartUser with password quickstartPwd1! and user guest with password guestPwd1!. This data is located in the src/main/resources/import.sql file.

+

This quickstart takes the following steps to implement Servlet security:

+
    +
  1. Web Application: +
      +
    • Adds a security constraint to the Servlet using the @ServletSecurity and @HttpConstraint annotations.
      • +
    • Adds a security domain reference to WEB-INF/jboss-web.xml.
      • +
    • Adds a login-config that sets the auth-method to BASIC in the WEB-INF/web.xml.
      • +
    +
    2. +
  2. Application Server (standalone.xml): +
      +
    • Defines a security domain in the elytron subsystem that uses the JDBC security realm to obtain the security data used to authenticate and authorize users.
      • +
    • Defines an http-authentication-factory in the elytron subsystem that uses the security domain created in step 1 for BASIC authentication.
      • +
    • Adds an application-security-domain mapping in the undertow subsystem to map the Servlet security domain to the HTTP authentication factory defined in step 2.
      • +
    +
    3. +
  3. Database Configuration: +
      +
    • Adds an application user with access rights to the application. +
      User Name: quickstartUser
+Password: quickstartPwd1!
+Role: quickstarts
+
      +
      • +
    • Adds another user with no access rights to the application. +
      User Name: guest
+Password: guestPwd1!
+Role: notauthorized
+
      +
      • +
    +
    4. +
+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Configure the Server

+

You can configure the server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-server.cli script provided in the root directory of this quickstart.

+
    +
  1. +

    Before you begin, back up your server configuration file

    +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. +

    Start the JBoss EAP server by typing the following:

    +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-server.cli file in the root of this quickstart directory. This script adds security domain and HTTP authentication factory to the elytron subsystem in the server configuration and also configures the undertow subsystem to use the configured HTTP authentication factory for the Web application.
    4. +
  4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-server.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-server.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+
    +
    5. +
  5. Stop the JBoss EAP server.
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+
    +
  1. +

    The following datasource was added to the datasources subsystem.

    +
    <datasource jndi-name="java:jboss/datasources/ServletSecurityDS" pool-name="ServletSecurityDS">
+    <connection-url>jdbc:h2:mem:servlet-security;DB_CLOSE_ON_EXIT=FALSE</connection-url>
+    <driver>h2</driver>
+    <security>
+        <user-name>sa</user-name>
+        <password>sa</password>
+    </security>
+</datasource>
+
    +
    2. +
  2. +

    The following security-realm was added to the elytron subsystem.

    +
    <jdbc-realm name="servlet-security-jdbc-realm">
+    <principal-query sql="SELECT PASSWORD FROM USERS WHERE USERNAME = ?" data-source="ServletSecurityDS">
+        <clear-password-mapper password-index="1"/>
+    </principal-query>
+    <principal-query sql="SELECT R.NAME, 'Roles' FROM USERS_ROLES UR INNER JOIN ROLES R ON R.ID = UR.ROLE_ID INNER JOIN USERS U ON U.ID = UR.USER_ID WHERE U.USERNAME = ?" data-source="ServletSecurityDS">
+        <attribute-mapping>
+            <attribute to="roles" index="1"/>
+        </attribute-mapping>
+    </principal-query>
+</jdbc-realm>
+
    +

    The security-realm is responsible for verifying the credentials for a given principal and for obtaining security attributes (like roles) that are associated with the authenticated identity.

    +
    3. +
  3. +

    The following role-decoder was added to the elytron subsystem.

    +
    <simple-role-decoder name="from-roles-attribute" attribute="roles"/>
+
    +

    The jdbc-realm in this quickstart stores the roles associated with a principal in an attribute named roles. Other realms might use different attributes for roles (such as group). The purpose of a role-decoder is to instruct the security domain how roles are to be retrieved from an authorized identity.

    +
    4. +
  4. +

    The following security-domain was added to the elytron subsystem.

    +
    <security-domain name="servlet-security-quickstart-sd" default-realm="servlet-security-jdbc-realm" permission-mapper="default-permission-mapper">
+    <realm name="servlet-security-jdbc-realm" role-decoder="from-roles-attribute"/>
+</security-domain>
+
    +
    5. +
  5. +

    The following http-authentication-factory was added to the elytron subsystem.

    +
    <http-authentication-factory name="servlet-security-quickstart-http-auth" http-server-mechanism-factory="global" security-domain="servlet-security-quickstart-sd">
+    <mechanism-configuration>
+        <mechanism mechanism-name="BASIC">
+            <mechanism-realm realm-name="RealmUsersRoles"/>
+        </mechanism>
+    </mechanism-configuration>
+</http-authentication-factory>
+
    +

    It basically defines an HTTP authentication factory for the BASIC mechanism that relies on the servlet-security-quickstart-sd security domain to authenticate and authorize access to Web applications.

    +
    6. +
  6. +

    The following application-security-domain was added to the undertow subsystem.

    +
    <application-security-domains>
+    <application-security-domain name="servlet-security-quickstart" http-authentication-factory="servlet-security-quickstart-http-auth"/>
+</application-security-domains>
+
    +
    7. +
+

This configuration tells Undertow that applications with the servlet-security-quickstart security domain, as defined in the jboss-web.xml or by using the @SecurityDomain annotation in the Servlet class, should use the http-authentication-factory named servlet-security-quickstart-http-auth. If no application-security-domain is defined for a particular security domain, Undertow assumes the legacy JAAS based security domains should be used for authentication/authorization and, in this case, the security domain defined in the Web application must match a security domain in the legacy security subsystem. The presence of an application-security-domain configuration is what enables Elytron authentication for a Web application.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/servlet-security.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/servlet-security/.

+

When you access the application, you should get a browser login challenge.

+

Log in using the username quickstartUser and password quickstartPwd1!. The browser will display the following security info:

+
Successfully called Secured Servlet
+
+Principal : quickstartUser
+Remote User : quickstartUser
+Authentication Type : BASIC
+
+

Now close the browser. Open a new browser and log in with username guest and password guestPwd1!. The browser will display the following error:

+
Forbidden
+
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warning in the server log. You can ignore it.

+
HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Restore the Server Configuration

+

You can restore the original server configuration by running the restore-configuration.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli
+
    +
    3. +
+

This script removes the application-security-domain configuration from the undertow subsystem, the http-authentication-factory, security-domain, security-realm and role-decoder configuration from the elytron subsystem and it also removes the datasource used for this quickstart. You should see the following result when you run the script:

+
    The batch executed successfully
+    process-state: reload-required
+
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+ +

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
  mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/servlet-security/README.md b/servlet-security/README.md index 843aa19d35..ae91dd715f 100644 --- a/servlet-security/README.md +++ b/servlet-security/README.md @@ -3,13 +3,13 @@ Author: Sherif F. Makary, Pedro Igor, Stefan Guilhen Level: Intermediate Technologies: Servlet, Security -Summary: The `servlet-security` quickstart demonstrates the use of Java EE declarative security to control access to Servlets and Security in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `servlet-security` quickstart demonstrates the use of Java EE declarative security to control access to Servlets and Security in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `servlet-security` quickstart demonstrates the use of Java EE declarative security to control access to Servlets and Security in ${product.name.full}. +The `servlet-security` quickstart demonstrates the use of Java EE declarative security to control access to Servlets and Security in Red Hat JBoss Enterprise Application Platform. When you deploy this example, two users are automatically created for you: user `quickstartUser` with password `quickstartPwd1!` and user `guest` with password `guestPwd1!`. This data is located in the `src/main/resources/import.sql` file. @@ -35,18 +35,18 @@ This quickstart takes the following steps to implement Servlet security: Password: guestPwd1! Role: notauthorized -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Configure the Server @@ -54,28 +54,28 @@ In the following instructions, replace `${jboss.home.name}` with the actual path You can configure the server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-server.cli` script provided in the root directory of this quickstart. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-server.cli` file in the root of this quickstart directory. This script adds security domain and HTTP authentication factory to the `elytron` subsystem in the server configuration and also configures the `undertow` subsystem to use the configured HTTP authentication factory for the Web application. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-server.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-server.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-server.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-server.cli You should see the following result when you run the script: The batch executed successfully -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. 1. The following datasource was added to the `datasources` subsystem. @@ -137,26 +137,26 @@ This configuration tells `Undertow` that applications with the `servlet-security ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/servlet-security.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . When you access the application, you should get a browser login challenge. @@ -182,7 +182,7 @@ _Note:_ You will see the following warning in the server log. You can ignore it. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -195,29 +195,29 @@ You can restore the original server configuration by running the `restore-confi ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-configuration.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-configuration.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-configuration.cli This script removes the `application-security-domain` configuration from the `undertow` subsystem, the `http-authentication-factory`, `security-domain`, `security-realm` and `role-decoder` configuration from the `elytron` subsystem and it also removes the `datasource` used for this quickstart. You should see the following result when you run the script: The batch executed successfully process-state: reload-required ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -* Be sure to configure the server by running the JBoss CLI commands as described above under [Configure the ${product.name} Server](#configure-the-server). Stop the server at the end of that step. +* Be sure to configure the server by running the JBoss CLI commands as described above under [Configure the JBoss EAP Server](#configure-the-server). Stop the server at the end of that step. * Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/servlet-security/pom.xml b/servlet-security/pom.xml index ff5d55d75f..2c2cb12f39 100644 --- a/servlet-security/pom.xml +++ b/servlet-security/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml servlet-security diff --git a/shopping-cart/README.html b/shopping-cart/README.html new file mode 100644 index 0000000000..32ec12a4b0 --- /dev/null +++ b/shopping-cart/README.html @@ -0,0 +1,185 @@ + + + shopping-cart: EJB Stateful Session Bean (SFSB) Example + + + +

shopping-cart: EJB Stateful Session Bean (SFSB) Example

+

Author: Serge Pagop
+Level: Intermediate
+Technologies: SFSB EJB
+Summary: The shopping-cart quickstart demonstrates how to deploy and run a simple Java EE 7 shopping cart application that uses a stateful session bean (SFSB).
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The shopping-cart quickstart demonstrates how to deploy and run a simple Java EE 7 application that uses a stateful session bean (SFSB) in Red Hat JBoss Enterprise Application Platform. The application allows customers to buy, checkout, and view their cart contents.

+

The shopping-cart application consists of the following:

+
    +
  1. A server side component: +

    This standalone Java EE module is a JAR containing EJBs. It is responsible for managing the shopping cart.

    +
    2. +
  2. A Java client: +

    This simple Java client is launched using a main method. The remote client looks up a reference to the server module's API, via JNDI. It then uses this API to perform the operations the customer requests.

    +
    3. +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Configure the Server

+

This example quickstart purposely throws a NoSuchEJBException exception when the shopping cart is empty. This is the expected result because method is annotated with @Remove. This means the next invocation after the shopping cart checkout fails because the container has destroyed the instance and it is no longer available. If you do not run this script, you see the following ERROR in the server log, followed by the stacktrace

+
ERROR [org.jboss.as.ejb3.invocation] (EJB default - 7) WFLYEJB0034: EJB Invocation failed on component ShoppingCartBean for method public abstract java.util.Map org.jboss.as.quickstarts.sfsb.ShoppingCart.getCartContents(): javax.ejb.NoSuchEJBException: WFLYEJB0168: Could not find EJB with id UnknownSessionID [5168576665505352655054705267485457555457535250485552546568575254]
+
+

Follow the steps below to suppress system exception logging.

+
    +
  1. Before you begin, back up your server configuration file +
      +
    • If it is running, stop the JBoss EAP server.
      • +
    • Back up the file: EAP7_HOME/standalone/configuration/standalone.xml
      • +
    • After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
      • +
    +
    2. +
  2. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    3. +
  3. Review the configure-system-exception.cli file in the root of this quickstart directory. This script sets the log-system-exceptions attribute to false in the ejb3 subsystem in the server configuration file.
    4. +
  4. +

    Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server:

    +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-system-exception.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-system-exception.cli
+
    +

    You should see the following result when you run the script:

    +
    The batch executed successfully
+
    +
    5. +
  5. Stop the JBoss EAP server.
    6. +
+

Review the Modified Server Configuration

+

After stopping the server, open the EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.

+

You should see the following configuration in the ejb3 subsystem.

+
  <log-system-exceptions value="false"/>
+
+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. +

    Make sure you have started the JBoss EAP server. See the instructions in the previous section.

    +
    2. +
  2. +

    Open a command prompt and navigate to the shopping-cart quickstart directory

    +
    3. +
  3. To build both the server component and the remote client program, deploy the server module, change into the examples shopping-cart directory and type the following: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. This Maven goal will deploy server/target/shopping-cart-server.jar. You can check the server console to see information messages regarding the deployment. +
    INFO  [org.jboss.as.ejb3.deployment] (MSC service thread 1-2) WFLYEJB0473: JNDI bindings for session bean named 'ShoppingCartBean' in deployment unit 'deployment "shopping-cart-server.jar"' are as follows:
+
+  java:global/shopping-cart-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart
+  java:app/shopping-cart-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart
+  java:module/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart
+  java:jboss/exported/shopping-cart-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart
+  java:global/shopping-cart-server/ShoppingCartBean
+  java:app/shopping-cart-server/ShoppingCartBean
+  java:module/ShoppingCartBean
+
+INFO  [org.jboss.weld.deployer] (MSC service thread 1-4) WFLYWELD0006: Starting Services for CDI deployment: shopping-cart-server.jar
+INFO  [org.jboss.weld.deployer] (MSC service thread 1-8) WFLYWELD0009: Starting weld service for deployment shopping-cart-server.jar
+INFO  [org.jboss.as.server] (management-handler-thread - 3) WFLYSRV0010: Deployed "shopping-cart-server.jar" (runtime-name : "shopping-cart-server.jar")
+
    +
    5. +
+

Run the Client Application

+

Now start a client that will access the beans you just deployed.

+

You can use the command prompt from the previous step or open a new one and navigate to the root of the shopping-cart quickstart directory.

+

Type the following command:

+
    mvn exec:java -f client/pom.xml         
+
+

Note: This quickstart requires quickstart-parent artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command:

+
    mvn clean install
+
+

Investigate the Console Output

+

You should see the following:

+
    +
  1. The client sends a remote method invocation to the stateful session bean to buy two 32 GB USB 2.0 Flash Drive and one Wireless Ergonomic Keyboard and Mouse.
    2. +
  2. The client sends a remote method invocation to get the contents of the cart and prints it to the console.
    3. +
  3. The client sends a remote method invocation to invoke checkout. Note the checkout() method in the server ShoppingCartBean has the @Remove annotation. This means the container will destroy shopping cart after the call and it will no longer be available.
    4. +
  4. The client calls getCartContents() to make sure the shopping cart was removed after checkout. This results in a javax.ejb.NoSuchEJBException trace in the server, proving the cart was removed.
    5. +
+

On the client console, you should see output similar to:

+
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
+Obtained the remote interface to the shopping cart
+Buying a "32 GB USB 2.0 Flash Drive".
+Buying another "32 GB USB 2.0 Flash Drive".
+Buying a "Wireless Ergonomic Keyboard and Mouse"
+
+Print cart:
+1     Wireless Ergonomic Keyboard and Mouse
+2     32 GB USB 2.0 Flash Drive
+
+Checkout
+Cart was correctly removed, as expected, after Checkout
+&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
+
+

In the server log, you should see:

+
INFO  [stdout] (pool-9-thread-8) implementing checkout() left as exercise for the reader!
+
+

Restore the Server Configuration

+

You can restore the system exception configuration by running the restore-system-exception.cli script provided in the root directory of this quickstart or by manually restoring the back-up copy the configuration file.

+

Restore the Server Configuration by Running the JBoss CLI Script

+
    +
  1. Start the JBoss EAP server by typing the following: +
    For Linux:  EAP7_HOME/bin/standalone.sh
+For Windows:  EAP7_HOME\bin\standalone.bat
+
    +
    2. +
  2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: +
    For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-system-exception.cli
+For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-system-exception.cli
+
    +
    3. +
+

This script restores the the log-system-exceptions attribute value to true. You should see the following result when you run the script:

+
    The batch executed successfully
+
+

Restore the Server Configuration Manually

+
    +
  1. If it is running, stop the JBoss EAP server.
    2. +
  2. Replace the EAP7_HOME/standalone/configuration/standalone.xml file with the back-up copy of the file.
    3. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

+
    +
  • Be sure to configure JBoss EAP to suppress system exception logging as described above under Configure the Server. Stop the server at the end of that step.
    • +
  • To deploy the server project, right-click on the shopping-cart-server project and choose Run As --> Run on Server.
    • +
  • To run the client, right-click on the shopping-cart-client project and choose Run As --> Java Application. In the Select Java Application window, choose Client - org.jboss.as.quickstarts.client and click OK. The client output displays in the Console window.
    • +
  • To undeploy the project, right-click on the shopping-cart-server project and choose Run As --> Maven build. Enter wildfly:undeploy for the Goals and click Run.
    • +
  • Be sure to Restore the Server Configuration when you have completed testing this quickstart.
    • +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/shopping-cart/README.md b/shopping-cart/README.md index 22aac55803..fab2928355 100644 --- a/shopping-cart/README.md +++ b/shopping-cart/README.md @@ -4,12 +4,12 @@ Author: Serge Pagop Level: Intermediate Technologies: SFSB EJB Summary: The `shopping-cart` quickstart demonstrates how to deploy and run a simple Java EE 7 shopping cart application that uses a stateful session bean (SFSB). -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `shopping-cart` quickstart demonstrates how to deploy and run a simple Java EE 7 application that uses a stateful session bean (SFSB) in ${product.name.full}. The application allows customers to buy, checkout, and view their cart contents. +The `shopping-cart` quickstart demonstrates how to deploy and run a simple Java EE 7 application that uses a stateful session bean (SFSB) in Red Hat JBoss Enterprise Application Platform. The application allows customers to buy, checkout, and view their cart contents. The `shopping-cart` application consists of the following: @@ -23,14 +23,14 @@ The `shopping-cart` application consists of the following: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Configure the Server @@ -42,28 +42,28 @@ This example quickstart purposely throws a `NoSuchEJBException` exception when t Follow the steps below to suppress system exception logging. 1. Before you begin, back up your server configuration file - * If it is running, stop the ${product.name} server. - * Back up the file: `${jboss.home.name}/standalone/configuration/standalone.xml` + * If it is running, stop the JBoss EAP server. + * Back up the file: `EAP7_HOME/standalone/configuration/standalone.xml` * After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. -2. Start the ${product.name} server by typing the following: +2. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat 3. Review the `configure-system-exception.cli` file in the root of this quickstart directory. This script sets the `log-system-exceptions` attribute to `false` in the `ejb3` subsystem in the server configuration file. -4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: +4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=configure-system-exception.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=configure-system-exception.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-system-exception.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-system-exception.cli You should see the following result when you run the script: The batch executed successfully -5. Stop the ${product.name} server. +5. Stop the JBoss EAP server. ## Review the Modified Server Configuration -After stopping the server, open the `${jboss.home.name}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `EAP7_HOME/standalone/configuration/standalone.xml` file and review the changes. You should see the following configuration in the `ejb3` subsystem. @@ -72,36 +72,36 @@ You should see the following configuration in the `ejb3` subsystem. ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server. See the instructions in the previous section. +1. Make sure you have started the JBoss EAP server. See the instructions in the previous section. 2. Open a command prompt and navigate to the `shopping-cart` quickstart directory 3. To build both the server component and the remote client program, deploy the server module, change into the examples shopping-cart directory and type the following: mvn clean install wildfly:deploy -4. This Maven goal will deploy `server/target/${project.artifactId}-server.jar`. You can check the server console to see information messages regarding the deployment. +4. This Maven goal will deploy `server/target/shopping-cart-server.jar`. You can check the server console to see information messages regarding the deployment. - INFO [org.jboss.as.ejb3.deployment] (MSC service thread 1-2) WFLYEJB0473: JNDI bindings for session bean named 'ShoppingCartBean' in deployment unit 'deployment "${project.artifactId}-server.jar"' are as follows: + INFO [org.jboss.as.ejb3.deployment] (MSC service thread 1-2) WFLYEJB0473: JNDI bindings for session bean named 'ShoppingCartBean' in deployment unit 'deployment "shopping-cart-server.jar"' are as follows: - java:global/${project.artifactId}-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart - java:app/${project.artifactId}-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart + java:global/shopping-cart-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart + java:app/shopping-cart-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart java:module/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart - java:jboss/exported/${project.artifactId}-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart - java:global/${project.artifactId}-server/ShoppingCartBean - java:app/${project.artifactId}-server/ShoppingCartBean + java:jboss/exported/shopping-cart-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart + java:global/shopping-cart-server/ShoppingCartBean + java:app/shopping-cart-server/ShoppingCartBean java:module/ShoppingCartBean - INFO [org.jboss.weld.deployer] (MSC service thread 1-4) WFLYWELD0006: Starting Services for CDI deployment: ${project.artifactId}-server.jar - INFO [org.jboss.weld.deployer] (MSC service thread 1-8) WFLYWELD0009: Starting weld service for deployment ${project.artifactId}-server.jar - INFO [org.jboss.as.server] (management-handler-thread - 3) WFLYSRV0010: Deployed "${project.artifactId}-server.jar" (runtime-name : "${project.artifactId}-server.jar") + INFO [org.jboss.weld.deployer] (MSC service thread 1-4) WFLYWELD0006: Starting Services for CDI deployment: shopping-cart-server.jar + INFO [org.jboss.weld.deployer] (MSC service thread 1-8) WFLYWELD0009: Starting weld service for deployment shopping-cart-server.jar + INFO [org.jboss.as.server] (management-handler-thread - 3) WFLYSRV0010: Deployed "shopping-cart-server.jar" (runtime-name : "shopping-cart-server.jar") ## Run the Client Application @@ -157,26 +157,26 @@ You can restore the system exception configuration by running the `restore-syste ### Restore the Server Configuration by Running the JBoss CLI Script -1. Start the ${product.name} server by typing the following: +1. Start the JBoss EAP server by typing the following: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat -2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing ${jboss.home.name} with the path to your server: + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: - For Linux: ${jboss.home.name}/bin/jboss-cli.sh --connect --file=restore-system-exception.cli - For Windows: ${jboss.home.name}\bin\jboss-cli.bat --connect --file=restore-system-exception.cli + For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=restore-system-exception.cli + For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=restore-system-exception.cli This script restores the the `log-system-exceptions` attribute value to `true`. You should see the following result when you run the script: The batch executed successfully ### Restore the Server Configuration Manually -1. If it is running, stop the ${product.name} server. -2. Replace the `${jboss.home.name}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +1. If it is running, stop the JBoss EAP server. +2. Replace the `EAP7_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -184,14 +184,14 @@ You can restore the system exception configuration by running the `restore-syste ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. -* Be sure to configure ${product.name} to suppress system exception logging as described above under [Configure the Server](#configure-the-server). Stop the server at the end of that step. -* To deploy the server project, right-click on the `${project.artifactId}-server` project and choose `Run As` --> `Run on Server`. -* To run the client, right-click on the `${project.artifactId}-client` project and choose `Run As` --> `Java Application`. In the `Select Java Application` window, choose `Client - org.jboss.as.quickstarts.client` and click `OK`. The client output displays in the `Console` window. -* To undeploy the project, right-click on the `${project.artifactId}-server` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +* Be sure to configure JBoss EAP to suppress system exception logging as described above under [Configure the Server](#configure-the-server). Stop the server at the end of that step. +* To deploy the server project, right-click on the `shopping-cart-server` project and choose `Run As` --> `Run on Server`. +* To run the client, right-click on the `shopping-cart-client` project and choose `Run As` --> `Java Application`. In the `Select Java Application` window, choose `Client - org.jboss.as.quickstarts.client` and click `OK`. The client output displays in the `Console` window. +* To undeploy the project, right-click on the `shopping-cart-server` project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. * Be sure to [Restore the Server Configuration](#restore-the-server-configuration) when you have completed testing this quickstart. ## Debug the Application diff --git a/shopping-cart/client/pom.xml b/shopping-cart/client/pom.xml index beea33b518..fb1847241e 100644 --- a/shopping-cart/client/pom.xml +++ b/shopping-cart/client/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts shopping-cart - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA shopping-cart-client jar diff --git a/shopping-cart/pom.xml b/shopping-cart/pom.xml index 070194978d..5ebecd09af 100644 --- a/shopping-cart/pom.xml +++ b/shopping-cart/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml shopping-cart diff --git a/shopping-cart/server/pom.xml b/shopping-cart/server/pom.xml index 3177df5a01..8b6cee48b0 100644 --- a/shopping-cart/server/pom.xml +++ b/shopping-cart/server/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts shopping-cart - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA shopping-cart-server ejb diff --git a/shrinkwrap-resolver/README.html b/shrinkwrap-resolver/README.html new file mode 100644 index 0000000000..56ba452ffe --- /dev/null +++ b/shrinkwrap-resolver/README.html @@ -0,0 +1,86 @@ + + + shrinkwrap-resolver: Demonstrates Usage of Shrinkwrap Resolver + + + +

shrinkwrap-resolver: Demonstrates Usage of Shrinkwrap Resolver

+

Author: Rafael Benevides
+Level: Intermediate
+Technologies: CDI, Arquillian, Shrinkwrap
+Summary: The shrinkwrap-resolver quickstart demonstrates three common use cases for ShrinkWrap Resolver in Red Hat JBoss Enterprise Application Platform.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

This quickstart demonstrates the use of ShrinkWrap Resolver in Red Hat JBoss Enterprise Application Platform.

+

With the advent of Maven and other build systems, typically third party libraries and our own dependent modules are obtained from a backing software repository. In this case we supply a series of coordinates which uniquely identifies an artifact in the repository, and resolve the target files from there.

+

That is precisely the aim of the ShrinkWrap Resolver project; it is a Java API to obtain artifacts from a repository system.

+

The shrinkwrap-resolver quickstart demonstrates various use cases for ShrinkWrap Resolver. This Quickstart has 3 Test Classes that demonstrates the following Shrinkwrap use cases:

+
    +
  • ShrinkwrapResolveGAVWithoutTransitiveDepsTest
    • +
  • resolve an artifact via G:A:V without transitive dependencies
    • +
  • return resolution result as single java.io.File
    • +
  • +

    ShrinkwrapImportFromPomTest

    +
    • +
  • loading pom.xml from file activating and deactivating profiles
    • +
  • importing dependencies of specified scope into list of artifacts to be resolved
    • +
  • return resolution results as a java.io.File array
    • +
  • +

    ShrinkwrapResolveGAPCVCustomRepoWithoutCentralTest

    +
    • +
  • resolve an artifact via G:A:P:C:V without transitive dependencies
    • +
  • resolve an artifact with classifier
    • +
  • disabling Maven Central
    • +
  • loading settings.xml from file (with custom repository)
    • +
  • return resolution results as a java.io.File array
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

You must first set the active Maven profile in project properties to be either arq-managed for running on managed server or arq-remote for running on remote server. Then, to run the tests, right click on the project or individual classes and select Run As --> JUnit Test in the context menu.

+

Investigate the Console Output

+

When you run the tests, you are presented with the test report summary:

+
-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.jboss.as.quickstarts.shrinkwrap.resolver.ShrinkwrapImportFromPomTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.633 sec
+Running org.jboss.as.quickstarts.shrinkwrap.resolver.ShrinkwrapResolveGAPCVCustomRepoWithoutCentralTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.439 sec
+Running org.jboss.as.quickstarts.shrinkwrap.resolver.ShrinkwrapResolveGAVWithoutTransitiveDepsTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.016 sec
+
+Results :
+
+Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
+
+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
mvn dependency:sources
+mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/shrinkwrap-resolver/README.md b/shrinkwrap-resolver/README.md index e08812461d..da33849288 100644 --- a/shrinkwrap-resolver/README.md +++ b/shrinkwrap-resolver/README.md @@ -3,14 +3,14 @@ Author: Rafael Benevides Level: Intermediate Technologies: CDI, Arquillian, Shrinkwrap -Summary: The `shrinkwrap-resolver` quickstart demonstrates three common use cases for ShrinkWrap Resolver in ${product.name.full}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `shrinkwrap-resolver` quickstart demonstrates three common use cases for ShrinkWrap Resolver in Red Hat JBoss Enterprise Application Platform. +Target Product: JBoss EAP +Source: ## What is it? -This quickstart demonstrates the use of ShrinkWrap Resolver in ${product.name.full}. +This quickstart demonstrates the use of ShrinkWrap Resolver in Red Hat JBoss Enterprise Application Platform. With the advent of Maven and other build systems, typically third party libraries and our own dependent modules are obtained from a backing software repository. In this case we supply a series of coordinates which uniquely identifies an artifact in the repository, and resolve the target files from there. @@ -37,35 +37,35 @@ The `shrinkwrap-resolver` quickstart demonstrates various use cases for ShrinkWr ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). You must first set the active Maven profile in project properties to be either `arq-managed` for running on managed server or `arq-remote` for running on remote server. Then, to run the tests, right click on the project or individual classes and select Run As --> JUnit Test in the context menu. diff --git a/shrinkwrap-resolver/pom.xml b/shrinkwrap-resolver/pom.xml index 9c06405d6d..69f7d97610 100644 --- a/shrinkwrap-resolver/pom.xml +++ b/shrinkwrap-resolver/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml shrinkwrap-resolver diff --git a/spring-greeter/README.html b/spring-greeter/README.html new file mode 100644 index 0000000000..ef7949ae4a --- /dev/null +++ b/spring-greeter/README.html @@ -0,0 +1,99 @@ + + + spring-greeter: Greeter Example using Spring 4.x + + + +

spring-greeter: Greeter Example using Spring 4.x

+

Author: Marius Bogoevici
+Level: Beginner
+Technologies: Spring MVC, JSP, JPA
+Summary: The spring-greeter quickstart is based on the greeter quickstart, but differs in that it uses Spring MVC for Mapping GET and POST requests.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

The spring-greeter quickstart is based on the greeter quickstart, but differs in that it uses Spring MVC for Mapping GET and POST requests:

+
    +
  • <mvc:annotation-driven\> configured in src/main/webapp/WEB-INF/spring-mvc-context.xml tells Spring to look for @RequestMapping in our controllers.
    • +
  • Spring then routes the HTTP requests to the correct methods in CreateController.java and GreetController
    • +
+

Spring's XML configurations are used to get hold of the database and entity manager (via jndi) to perform transactional operations:

+
    +
  • <tx:jta-transaction-manager/> and <tx:annotation-driven/> are configured in /src/main/webapp/WEB-INF/spring-business-context.xml
    • +
  • Methods in UserDaoImpl are marked as @Transactional, which Spring, using aspect oriented programming, surrounds with boilerplate code to make the methods transactional
    • +
+

When you deploy this example, two users are automatically created for you: emuster and jdoe. This data is located in the src/main/resources/init-db.sql file.

+

To test this example:

+
    +
  1. Enter a name in the username field and click on Greet!.
    2. +
  2. If you enter a username that is not in the database, you get a message No such user exists!.
    3. +
  3. If you enter a valid username, you get a message "Hello, " followed by the user's first and last name.
    4. +
  4. To create a new user, click the Add a new user link. Enter the username, first name, and last name and then click Add User. The user is added and a message displays the new user id number.
    5. +
  5. Click on the Greet a user! link to return to the Greet! page.
    6. +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   bin/standalone.sh
+For Windows: bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy
    4. +
  4. +

    This will deploy target/spring-greeter.war to the running instance of the server.

    +
    5. +
+

If you do not have maven configured you can manually copy target/spring-greeter.war to EAP7_HOME/standalone/deployments.

+

Access the application

+

The application will be running at the following URL: http://localhost:8080/spring-greeter/

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Or you can manually remove the application by removing spring-greeter.war from EAP7_HOME/standalone/deployments

+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/spring-greeter/README.md b/spring-greeter/README.md index 0c48a0e4cb..bf4047f6eb 100644 --- a/spring-greeter/README.md +++ b/spring-greeter/README.md @@ -4,12 +4,12 @@ Author: Marius Bogoevici Level: Beginner Technologies: Spring MVC, JSP, JPA Summary: The `spring-greeter` quickstart is based on the `greeter` quickstart, but differs in that it uses Spring MVC for Mapping GET and POST requests. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. The `spring-greeter` quickstart is based on the `greeter` quickstart, but differs in that it uses Spring MVC for Mapping GET and POST requests: @@ -38,14 +38,14 @@ The user is added and a message displays the new user id number. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: For Linux: bin/standalone.sh @@ -53,28 +53,28 @@ All you need to build this project is ${build.requirements}. See [Configure Mave ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy 4. This will deploy target/spring-greeter.war to the running instance of the server. -If you do not have maven configured you can manually copy target/spring-greeter.war to ${jboss.home.name}/standalone/deployments. +If you do not have maven configured you can manually copy target/spring-greeter.war to EAP7_HOME/standalone/deployments. ## Access the application -The application will be running at the following URL: +The application will be running at the following URL: ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: mvn wildfly:undeploy -Or you can manually remove the application by removing spring-greeter.war from ${jboss.home.name}/standalone/deployments +Or you can manually remove the application by removing spring-greeter.war from EAP7_HOME/standalone/deployments ## Run the Arquillian Functional Tests @@ -90,11 +90,11 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: mvn clean verify -Parq-managed @@ -102,7 +102,7 @@ server for you, type the following command: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/spring-greeter/functional-tests/pom.xml b/spring-greeter/functional-tests/pom.xml index aedfe4c426..397f1fbc22 100644 --- a/spring-greeter/functional-tests/pom.xml +++ b/spring-greeter/functional-tests/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml diff --git a/spring-greeter/pom.xml b/spring-greeter/pom.xml index 7419a5a522..739b06c637 100644 --- a/spring-greeter/pom.xml +++ b/spring-greeter/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml spring-greeter diff --git a/spring-kitchensink-asyncrequestmapping/README.html b/spring-kitchensink-asyncrequestmapping/README.html new file mode 100644 index 0000000000..b624fd0015 --- /dev/null +++ b/spring-kitchensink-asyncrequestmapping/README.html @@ -0,0 +1,98 @@ + + + spring-kitchensink-asyncrequestmapping: Kitchensink AsynRequestMapping Using Spring 4.x + + + +

spring-kitchensink-asyncrequestmapping: Kitchensink AsynRequestMapping Using Spring 4.x

+

Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson
+Level: Intermediate
+Technologies: JSP, JPA, JSON, Spring, JUnit
+Summary: The spring-kitchensink-asyncrequestmapping quickstart showcases the use of asynchronous requests is an example using JSP, JPA and Spring 4.x.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The spring-kitchensink-asyncrequestmapping quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x in Red Hat JBoss Enterprise Application Platform. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java:

+
    +
  • +

    This module showcases the use of asynchronous requests in MemberRestController.java, introduced in the Spring 3.2. More on Spring's Asynchronous Request Processing

    +
    • +
  • +

    In jboss-as-spring-mvc-context.xml <context:component-scan base-package="org.jboss.as.quickstarts.kitchensink.spring.asyncrequestmapping.controller"/> and <mvc:annotation-driven/> are used to register both the non-rest and rest controllers.

    +
    • +
  • +

    The controllers map the respective urls to methods using @RequestMapping(url).

    +
    • +
  • +

    To return JSON, the rest controller uses @ResponseBody.

    +
    • +
  • +

    The datasource and entitymanager are retrieved via JNDI.

    +
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/spring-kitchensink-asyncrequestmapping.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/spring-kitchensink-asyncrequestmapping/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/spring-kitchensink-asyncrequestmapping/README.md b/spring-kitchensink-asyncrequestmapping/README.md index 24d1f3d4ad..0352baa40e 100644 --- a/spring-kitchensink-asyncrequestmapping/README.md +++ b/spring-kitchensink-asyncrequestmapping/README.md @@ -4,12 +4,12 @@ Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson Level: Intermediate Technologies: JSP, JPA, JSON, Spring, JUnit Summary: The `spring-kitchensink-asyncrequestmapping` quickstart showcases the use of asynchronous requests is an example using JSP, JPA and Spring 4.x. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `spring-kitchensink-asyncrequestmapping` quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x in ${product.name.full}. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java: +The `spring-kitchensink-asyncrequestmapping` quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x in Red Hat JBoss Enterprise Application Platform. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java: * This module showcases the use of asynchronous requests in `MemberRestController.java`, introduced in the Spring 3.2. [More on Spring's Asynchronous Request Processing](http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/mvc.html#mvc-ann-async) @@ -26,39 +26,39 @@ and `` are used to register both the non-rest and rest c ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/spring-kitchensink-asyncrequestmapping.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -79,11 +79,11 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: mvn clean verify -Parq-managed @@ -91,7 +91,7 @@ server for you, type the following command: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/spring-kitchensink-asyncrequestmapping/pom.xml b/spring-kitchensink-asyncrequestmapping/pom.xml index 8917a714fb..82992580e2 100644 --- a/spring-kitchensink-asyncrequestmapping/pom.xml +++ b/spring-kitchensink-asyncrequestmapping/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml spring-kitchensink-asyncrequestmapping diff --git a/spring-kitchensink-basic/README.html b/spring-kitchensink-basic/README.html new file mode 100644 index 0000000000..d9ea14062b --- /dev/null +++ b/spring-kitchensink-basic/README.html @@ -0,0 +1,95 @@ + + + spring-kitchensink-basic: Kitchensink Example using Spring 4.x + + + +

spring-kitchensink-basic: Kitchensink Example using Spring 4.x

+

Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson
+Level: Intermediate
+Technologies: JSP, JPA, JSON, Spring, JUnit
+Summary: The spring-kitchensink-basic quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The spring-kitchensink-basic quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x in Red Hat JBoss Enterprise Application Platform. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java:

+
    +
  • +

    In jboss-as-spring-mvc-context.xml <context:component-scan base-package="org.jboss.as.quickstarts.kitchensink.spring.basic.controller"/> and <mvc:annotation-driven/> are used to register both the non-rest and rest controllers.

    +
    • +
  • +

    The controllers map the respective urls to methods using @RequestMapping(url).

    +
    • +
  • +

    To return JSON, the rest controller uses @ResponseBody.

    +
    • +
  • +

    The datasource and entitymanager are retrieved via JNDI.

    +
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/spring-kitchensink-basic.war to the running instance of the server.

    +
    5. +
+

Access the application

+

The application will be running at the following URL: http://localhost:8080/spring-kitchensink-basic/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/spring-kitchensink-basic/README.md b/spring-kitchensink-basic/README.md index ebf24cc026..0b2c911916 100644 --- a/spring-kitchensink-basic/README.md +++ b/spring-kitchensink-basic/README.md @@ -4,12 +4,12 @@ Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson Level: Intermediate Technologies: JSP, JPA, JSON, Spring, JUnit Summary: The `spring-kitchensink-basic` quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `spring-kitchensink-basic` quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x in ${product.name.full}. It +The `spring-kitchensink-basic` quickstart is an example of a Java EE 7 application using JSP, JPA and Spring 4.x in Red Hat JBoss Enterprise Application Platform. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java: * In `jboss-as-spring-mvc-context.xml` `` @@ -24,39 +24,39 @@ and `` are used to register both the non-rest and rest c ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/spring-kitchensink-basic.war` to the running instance of the server. ## Access the application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -77,11 +77,11 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: mvn clean verify -Parq-managed @@ -89,7 +89,7 @@ server for you, type the following command: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/spring-kitchensink-basic/functional-tests/pom.xml b/spring-kitchensink-basic/functional-tests/pom.xml index e3b137003d..d0d799ed20 100644 --- a/spring-kitchensink-basic/functional-tests/pom.xml +++ b/spring-kitchensink-basic/functional-tests/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml spring-kitchensink-basic-test-webdriver diff --git a/spring-kitchensink-basic/pom.xml b/spring-kitchensink-basic/pom.xml index c3759caa80..b33a338cc5 100644 --- a/spring-kitchensink-basic/pom.xml +++ b/spring-kitchensink-basic/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml spring-kitchensink-basic diff --git a/spring-kitchensink-controlleradvice/README.html b/spring-kitchensink-controlleradvice/README.html new file mode 100644 index 0000000000..6265c0a2ff --- /dev/null +++ b/spring-kitchensink-controlleradvice/README.html @@ -0,0 +1,99 @@ + + + spring-kitchensink-controlleradvice: Kitchensink ControllerAdvice Example using Spring 4.x + + + +

spring-kitchensink-controlleradvice: Kitchensink ControllerAdvice Example using Spring 4.x

+

Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson
+Level: Intermediate
+Technologies: JSP, JPA, JSON, Spring, JUnit
+Summary: The spring-kitchensink-controlleradvice quickstart showcases Spring 4.x's @ControllerAdvice, which was introduced in Spring 3.2.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The spring-kitchensink-controlleradvice quickstart is a deployable Maven 3 project that demonstrates how to use JSP, JPA, and Spring 4.x in Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

This example showcases Spring 4.x's @ControllerAdvice, introduced in Spring 3.2, and used by MemberControllerAdvice.java.

+
    +
  • +

    MemberControllerAdvice uses @ExceptionHandler, @InitBinder and @ModelAttribute to configure global actions to be performed.

    +
    • +
  • +

    In jboss-as-spring-mvc-context.xml <context:component-scan base-package="org.jboss.as.quickstarts.kitchensink.spring.controlleradvice.controller"/> and <mvc:annotation-driven/> are used to register both the non-rest and rest controllers.

    +
    • +
  • +

    The controllers map the respective urls to methods using @RequestMapping(url).

    +
    • +
  • +

    To return JSON, the rest controller uses @ResponseBody.

    +
    • +
  • +

    The datasource and entitymanager are retrieved via JNDI.

    +
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/spring-kitchensink-controlleradvice.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/spring-kitchensink-controlleradvice/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/spring-kitchensink-controlleradvice/README.md b/spring-kitchensink-controlleradvice/README.md index 4e95a4dfd6..135e29abc5 100644 --- a/spring-kitchensink-controlleradvice/README.md +++ b/spring-kitchensink-controlleradvice/README.md @@ -4,12 +4,12 @@ Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson Level: Intermediate Technologies: JSP, JPA, JSON, Spring, JUnit Summary: The `spring-kitchensink-controlleradvice` quickstart showcases Spring 4.x's `@ControllerAdvice`, which was introduced in Spring 3.2. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `spring-kitchensink-controlleradvice` quickstart is a deployable Maven 3 project that demonstrates how to use JSP, JPA, and Spring 4.x in ${product.name.full} ${product.version} or later. +The `spring-kitchensink-controlleradvice` quickstart is a deployable Maven 3 project that demonstrates how to use JSP, JPA, and Spring 4.x in Red Hat JBoss Enterprise Application Platform 7.1 or later. This example showcases Spring 4.x's `@ControllerAdvice`, introduced in Spring 3.2, and used by `MemberControllerAdvice.java`. @@ -27,39 +27,39 @@ and `` are used to register both the non-rest and rest c ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/spring-kitchensink-controlleradvice.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -80,11 +80,11 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: mvn clean verify -Parq-managed @@ -92,7 +92,7 @@ server for you, type the following command: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/spring-kitchensink-controlleradvice/functional-tests/pom.xml b/spring-kitchensink-controlleradvice/functional-tests/pom.xml index 7664e5ffbf..162fb079a8 100644 --- a/spring-kitchensink-controlleradvice/functional-tests/pom.xml +++ b/spring-kitchensink-controlleradvice/functional-tests/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml spring-kitchensink-controlleradvice-test-webdriver diff --git a/spring-kitchensink-controlleradvice/pom.xml b/spring-kitchensink-controlleradvice/pom.xml index 512c3009bc..a4de9648c9 100644 --- a/spring-kitchensink-controlleradvice/pom.xml +++ b/spring-kitchensink-controlleradvice/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml spring-kitchensink-controlleradvice diff --git a/spring-kitchensink-matrixvariables/README.html b/spring-kitchensink-matrixvariables/README.html new file mode 100644 index 0000000000..47073584f5 --- /dev/null +++ b/spring-kitchensink-matrixvariables/README.html @@ -0,0 +1,105 @@ + + + spring-kitchensink-matrixvariables: Kitchensink MatrixVariables Using Spring 4.x + + + +

spring-kitchensink-matrixvariables: Kitchensink MatrixVariables Using Spring 4.x

+

Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson
+Level: Intermediate
+Technologies: JSP, JPA, JSON, Spring, JUnit
+Summary: The spring-kitchensink-matrixvariables quickstart showcases Spring 4.x's support for Matrix Variables in URLs that was introduced in Spring 3.2.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

This is your project! It is a sample, deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 and Spring in Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

This project is setup to allow you to create a compliant Java EE 7 application using JSP, JPA and Spring 4.x. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java:

+
    +
  • +

    This module showcases Spring 4.x's support for Matrix Variables in urls introduced in Spring 3.2.

    +
    • +
  • +

    In jboss-as-spring-mvc-context.xml <context:component-scan base-package="org.jboss.as.quickstarts.kitchensink.spring.matrixvariables.controller"/> and <mvc:annotation-driven/> are used to register both the non-rest and rest controllers. This is how it works normally, however if we want to use @MatrixVariable we must set the removeSemicolonContent property of RequestMappingHandlerMapping to false. This has been done by commenting out <mvc:annotation-driven/> and using <bean class='org.jboss.as.quickstarts.kitchensink.spring.matrixvariables.config.WebConfig'/>. Then in the WebConfig class we set the removeSemicolonContent property to false.

    +
    • +
  • +

    The controllers map the respective urls to methods using @RequestMapping(url).

    +
    • +
  • +

    To return JSON, the rest controller uses @ResponseBody.

    +
    • +
  • +

    The datasource and entitymanager are retrieved via JNDI.

    +
    • +
  • +

    An additional form is added in index.jsp which allows the user to filter the member list. The form is submitted in the url form: /filter;n=Name;e=Email.

    +
    • +
  • +

    Using @MatrixVariable the controller method captures the values and feeds them to the memberDao.

    +
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/spring-kitchensink-matrixvariables.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/spring-kitchensink-matrixvariables/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/spring-kitchensink-matrixvariables/README.md b/spring-kitchensink-matrixvariables/README.md index bdc1acb9ac..818156b604 100644 --- a/spring-kitchensink-matrixvariables/README.md +++ b/spring-kitchensink-matrixvariables/README.md @@ -4,13 +4,13 @@ Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson Level: Intermediate Technologies: JSP, JPA, JSON, Spring, JUnit Summary: The `spring-kitchensink-matrixvariables` quickstart showcases Spring 4.x's support for **Matrix Variables** in URLs that was introduced in Spring 3.2. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? This is your project! It is a sample, deployable Maven 3 project to help you get your foot in the door developing with -Java EE 7 and Spring in ${product.name.full} ${product.version} or later. +Java EE 7 and Spring in Red Hat JBoss Enterprise Application Platform 7.1 or later. This project is setup to allow you to create a compliant Java EE 7 application using JSP, JPA and Spring 4.x. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java: @@ -37,39 +37,39 @@ the url form: `/filter;n=Name;e=Email`. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/spring-kitchensink-matrixvariables.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -90,11 +90,11 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: mvn clean verify -Parq-managed @@ -102,7 +102,7 @@ server for you, type the following command: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/spring-kitchensink-matrixvariables/functional-tests/pom.xml b/spring-kitchensink-matrixvariables/functional-tests/pom.xml index dddf170462..296dafcb25 100644 --- a/spring-kitchensink-matrixvariables/functional-tests/pom.xml +++ b/spring-kitchensink-matrixvariables/functional-tests/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml spring-kitchensink-matrixvariables-test-webdriver diff --git a/spring-kitchensink-matrixvariables/pom.xml b/spring-kitchensink-matrixvariables/pom.xml index 35c72cb380..b6221298dd 100644 --- a/spring-kitchensink-matrixvariables/pom.xml +++ b/spring-kitchensink-matrixvariables/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml spring-kitchensink-matrixvariables diff --git a/spring-kitchensink-springmvctest/README.html b/spring-kitchensink-springmvctest/README.html new file mode 100644 index 0000000000..01f9d4ae0f --- /dev/null +++ b/spring-kitchensink-springmvctest/README.html @@ -0,0 +1,101 @@ + + + spring-kitchensink-springmvctest: Kitchensink MVC Example Using Spring 4.x + + + +

spring-kitchensink-springmvctest: Kitchensink MVC Example Using Spring 4.x

+

Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson
+Level: Intermediate
+Technologies: JSP, JPA, JSON, Spring, JUnit
+Summary: The spring-kitchensink-springmvctest quickstart demonstrates how to create an MVC application using JSP, JPA and Spring 4.x.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The spring-kitchensink-springmvctest quickstart demonstrates how to create an MVC application using JSP, JPA and Spring 4.x in Red Hat JBoss Enterprise Application Platform.

+
    +
  • +

    This module adds MemberMockMVCTest.java to showcase a use case of MockMVC and RestTemplate to test the MVC aspect of the application.

    +
    • +
  • +

    By using @WebAppConfiguration and @ContextConfiguration we tell Spring the configuration files we would like the tests to use.

    +
    • +
  • +

    In jboss-as-spring-mvc-context.xml <context:component-scan base-package="org.jboss.as.quickstarts.kitchensink.spring.springmvctest.controller"/> and <mvc:annotation-driven/> are used to register both the non-rest and rest controllers.

    +
    • +
  • +

    The controllers map the respective urls to methods using @RequestMapping(url).

    +
    • +
  • +

    To return JSON, the rest controller uses @ResponseBody.

    +
    • +
  • +

    The datasource and entitymanager are retrieved via JNDI.

    +
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/spring-kitchensink-springmvctest.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/spring-kitchensink-springmvctest/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/spring-kitchensink-springmvctest/README.md b/spring-kitchensink-springmvctest/README.md index 2b36819bf0..7c0be401c8 100644 --- a/spring-kitchensink-springmvctest/README.md +++ b/spring-kitchensink-springmvctest/README.md @@ -4,12 +4,12 @@ Author: Marius Bogoevici, Tejas Mehta, Joshua Wilson Level: Intermediate Technologies: JSP, JPA, JSON, Spring, JUnit Summary: The `spring-kitchensink-springmvctest` quickstart demonstrates how to create an MVC application using JSP, JPA and Spring 4.x. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `spring-kitchensink-springmvctest` quickstart demonstrates how to create an MVC application using JSP, JPA and Spring 4.x in ${product.name.full}. +The `spring-kitchensink-springmvctest` quickstart demonstrates how to create an MVC application using JSP, JPA and Spring 4.x in Red Hat JBoss Enterprise Application Platform. * This module adds `MemberMockMVCTest.java` to showcase a use case of `MockMVC` and `RestTemplate` to test the MVC aspect of the application. @@ -27,39 +27,39 @@ and `` are used to register both the non-rest and rest c ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/spring-kitchensink-springmvctest.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -80,11 +80,11 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: mvn clean verify -Parq-managed @@ -92,7 +92,7 @@ server for you, type the following command: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/spring-kitchensink-springmvctest/functional-tests/pom.xml b/spring-kitchensink-springmvctest/functional-tests/pom.xml index 6e154a658d..25d59693e6 100644 --- a/spring-kitchensink-springmvctest/functional-tests/pom.xml +++ b/spring-kitchensink-springmvctest/functional-tests/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml spring-kitchensink-springmvctest-test-webdriver diff --git a/spring-kitchensink-springmvctest/pom.xml b/spring-kitchensink-springmvctest/pom.xml index 6804e2f47f..0b9b4ba297 100644 --- a/spring-kitchensink-springmvctest/pom.xml +++ b/spring-kitchensink-springmvctest/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml spring-kitchensink-springmvctest diff --git a/spring-petclinic/CHANGES.html b/spring-petclinic/CHANGES.html new file mode 100644 index 0000000000..ae864ce991 --- /dev/null +++ b/spring-petclinic/CHANGES.html @@ -0,0 +1,21 @@ + + +CHANGES TO SPRING PETCLINIC EXAMPLE + + + +

CHANGES TO SPRING PETCLINIC EXAMPLE

+

ORIGINAL SOURCE

+

Spring PetClinic

+

CHANGES

+
    +
  1. Addition of webapp/WEB-INF/jboss-deployment-structure.xml, ensuring no conflict with JBOSS' Hibernate module with those packaged by this quickstart. See JBOSS DEPLOYMENT STRUCTURE for more details.
    2. +
  2. Configured to use Red Hat JBoss EAP BOMs.
    3. +
  3. Regressed the jQuery version to 1.9 as that is what is currently certified on EAP.
    4. +
  4. Add plug-in to deploy directly to running JBoss from mvn build.
    5. +
  5. Add OpenShift support.
    6. +
  6. Add Apache license text.
    7. +
  7. Regress Hibernate core to 4.2.7.SP1 or before to ensure that it runs on EAP 7.
    8. +
+ + \ No newline at end of file diff --git a/spring-petclinic/CHANGES.md b/spring-petclinic/CHANGES.md index dd8b01f1c9..6e190f7551 100644 --- a/spring-petclinic/CHANGES.md +++ b/spring-petclinic/CHANGES.md @@ -10,7 +10,7 @@ CHANGES 1. Addition of `webapp/WEB-INF/jboss-deployment-structure.xml`, ensuring no conflict with JBOSS' Hibernate module with those packaged by this quickstart. See [JBOSS DEPLOYMENT STRUCTURE]() for more details. -2. Configured to use Red Hat ${product.name} BOMs. +2. Configured to use Red Hat JBoss EAP BOMs. 3. Regressed the jQuery version to 1.9 as that is what is currently certified on EAP. 4. Add plug-in to deploy directly to running JBoss from mvn build. 6. Add OpenShift support. diff --git a/spring-petclinic/README.html b/spring-petclinic/README.html new file mode 100644 index 0000000000..62131662c7 --- /dev/null +++ b/spring-petclinic/README.html @@ -0,0 +1,125 @@ + + + spring-petclinic: PetClinic Example using Spring 4.x + + + +

spring-petclinic: PetClinic Example using Spring 4.x

+

Author: Ken Krebs, Juergen Hoeller, Rob Harrop, Costin Leau, Sam Brannen, Scott Andrews
+Level: Advanced
+Technologies: JPA, Junit, JMX, Spring MVC Annotations, AOP, Spring Data, JSP, webjars, Dandellion
+Summary: The spring-petclinic quickstart shows how to run the Spring PetClinic Application in JBoss EAP using the JBoss EAP BOMs.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The spring-petclinic quickstart shows how to run the Spring PetClinic Application in Red Hat JBoss Enterprise Application Platform with the use of Red Hat JBoss EAP BOMs (for the best compatibility). One of the major changes is the use of the webapp/WEB-INF/jboss-deployment-structure.xml file. This file specifies which modules to include or exclude when building the application. In this case, we exclude Hibernate libraries since the application uses Spring Data JPA. Additionally, this is only required when using the spring-data-jpa profile, see resources/spring/business-config.xml.

+

For detailed explanation of the changes made to adapt the Quickstart to Red Hat JBoss Enterprise Application Platform see: CHANGES.md

+

PetClinic features alternative DAO implementations and application configurations for JDBC, JPA, and Spring Data JPA, with HSQLDB and MySQL as target databases. The default PetClinic configuration is JPA on HSQLDB.

+
    +
  • The src/main/resources/spring/business-config.xml pulls in src/main/resources/spring/data-access.properties to set the JDBC-related settings for the JPA EntityManager definition. +
      +
    • A simple comment change in data-access.properties switches between the data access strategies.
      • +
    +
    • +
  • In webapp/WEB_INF/web.xml the <param-name>spring.profiles.active</param-name> using <param-value>jpa</param-value> (as the default) refers to the bean to be used in src/main/resources/spring/business-config.xml. +
      +
    • Setting the <param-value> to jdbc, jpa, or spring-data-jpa is all that is needed to change the DAO implementation.
      • +
    +
    • +
+

All versions of PetClinic also demonstrate JMX support via the use of <context:mbean-export/> in resources/spring/tools-config.xml for exporting MBeans. The CallMonitoringAspect.java is exposed using Spring's @ManagedResource and @ManagedOperation annotations and with @Around annotation we add monitoring around all org.springframework.stereotype.Repository * functions. You can start up the JDK's JConsole to manage the exported bean.

+

The use of @Cacheable is also demonstrated in ClinicServiceImpl.java by caching the results of the method findVets. The cacheManager in configured in tools-config.xml and ehcache.xml specifies the vets cache properties.

+

The default transaction manager for JDBC is DataSourceTransactionManager and for JPA and Spring Data JPA, JpaTransactionManager. Those local strategies allow for working with any locally defined DataSource. These are defined in the business-config.xml

+

Note that the sample configurations for JDBC, JPA, and Spring Data JPA configure a DataSource from the Apachce Tomcat JDBC Pool project for connection pooling. See datasource-config.xml.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy spring-petclinic/target/spring-petclinic.war to the running instance of the server.

    +
    5. +
+

If you do not have maven configured you can manually copy spring-petclinic/target/spring-petclinic.war to EAP7_HOME/standalone/deployments.

+

For MySQL, you need to use the corresponding schema and SQL scripts in the db/mysql subdirectory.

+

In you intend to use a local DataSource, the JDBC settings can be adapted in src/main/resources/spring/datasource-config.xml. To use a JTA DataSource, you need to set up corresponding DataSources in your Java EE container.

+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/spring-petclinic/.

+

Note: You see the following warning in the server log when you access the application. This example does not provide a dandelion.properties file because it does not require any changes to the dandelion default configuration. You can ignore this warning.

+
WARN  [com.github.dandelion.core.config.StandardConfigurationLoader] (default task-1) No file "dandelion.properties" was found in "dandelion/dandelion.properties" (classpath). The default configuration will be used.
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

NOTE: The arquillian-based functional tests deploy the application, so be sure you have undeployed it before you begin. To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. If the application is still deployed from the previous section, undeploy it now. +
    mvn wildfly:undeploy
+
    +
    3. +
  3. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    4. +
  4. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    5. +
  5. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    6. +
  6. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    mvn clean verify -Parq-managed
+
    +
    7. +
  7. +

    The spring-petclinic quickstart contains three configurations: JDBC, JPA, and Spring Data JPA. You should see the tests run 3 times, one for each configuration.

    +
    8. +
  8. +

    Review the server log. You will see an exception for each test configuration run similar to the following in the server log. This is intentional to demonstrate how exceptions are handled within application. This the same exception you can test by clicking on the Error menu item in the upper right corner in the deployed application. The application shows a nice error page in the browser instead of the exception.

    +
    WARN  [warn] (default task-15) Handler execution resulted in exception: java.lang.RuntimeException: Expected: controller used to showcase what happens when an exception is thrown
+    at org.springframework.samples.petclinic.web.CrashController.triggerException(CrashController.java:35)
+    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
+    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
+    at java.lang.reflect.Method.invoke(Method.java:497)
+    at org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:221)
+  (remainder of StackTrace removed for readability)
+
    +
    9. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

Note: Eclipse/JBDS may generate a persistence.xml file in the src/main/resources/META-INF/ directory. In order to avoid errors, delete this file.

+

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

+
    mvn dependency:sources
+    mvn dependency:resolve -Dclassifier=javadoc
+
+ + \ No newline at end of file diff --git a/spring-petclinic/README.md b/spring-petclinic/README.md index d70d75a4d6..6e165d1301 100644 --- a/spring-petclinic/README.md +++ b/spring-petclinic/README.md @@ -3,19 +3,19 @@ Author: Ken Krebs, Juergen Hoeller, Rob Harrop, Costin Leau, Sam Brannen, Scott Andrews Level: Advanced Technologies: JPA, Junit, JMX, Spring MVC Annotations, AOP, Spring Data, JSP, webjars, Dandellion -Summary: The `spring-petclinic` quickstart shows how to run the Spring PetClinic Application in ${product.name} using the ${product.name} BOMs. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `spring-petclinic` quickstart shows how to run the Spring PetClinic Application in JBoss EAP using the JBoss EAP BOMs. +Target Product: JBoss EAP +Source: ## What is it? The `spring-petclinic` quickstart shows how to run the [Spring PetClinic]() Application -in ${product.name.full} with the use of Red Hat ${product.name} BOMs (_for the best compatibility_). One of the major +in Red Hat JBoss Enterprise Application Platform with the use of Red Hat JBoss EAP BOMs (_for the best compatibility_). One of the major changes is the use of the `webapp/WEB-INF/jboss-deployment-structure.xml` file. This file specifies which modules to include or exclude when building the application. In this case, we exclude Hibernate libraries since the application uses Spring Data JPA. Additionally, this is only required when using the spring-data-jpa profile, see `resources/spring/business-config.xml`. -For detailed explanation of the changes made to adapt the Quickstart to ${product.name.full} see: [CHANGES.md](CHANGES.md) +For detailed explanation of the changes made to adapt the Quickstart to Red Hat JBoss Enterprise Application Platform see: [CHANGES.md](CHANGES.md) PetClinic features alternative DAO implementations and application configurations for JDBC, JPA, and Spring Data JPA, with HSQLDB and MySQL as target databases. The default PetClinic configuration is JPA on HSQLDB. @@ -42,31 +42,31 @@ _Note that the sample configurations for JDBC, JPA, and Spring Data JPA configur ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `spring-petclinic/target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `spring-petclinic/target/spring-petclinic.war` to the running instance of the server. -If you do not have maven configured you can manually copy `spring-petclinic/target/${project.artifactId}.war` to ${jboss.home.name}/standalone/deployments. +If you do not have maven configured you can manually copy `spring-petclinic/target/spring-petclinic.war` to EAP7_HOME/standalone/deployments. For MySQL, you need to use the corresponding schema and SQL scripts in the `db/mysql` subdirectory. @@ -76,7 +76,7 @@ To use a JTA DataSource, you need to set up corresponding DataSources in your Ja ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . _Note:_ You see the following warning in the server log when you access the application. This example does not provide a `dandelion.properties` file because it does not require any changes to the dandelion default configuration. You can ignore this warning. @@ -85,7 +85,7 @@ _Note:_ You see the following warning in the server log when you access the appl ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -107,11 +107,11 @@ NOTE: The arquillian-based functional tests deploy the application, so be sure y mvn clean package 4. Navigate to the functional-tests/ directory in this quickstart. -5. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +5. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -6. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the server for you, type the following command: +6. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: mvn clean verify -Parq-managed @@ -131,7 +131,7 @@ NOTE: The arquillian-based functional tests deploy the application, so be sure y ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/spring-petclinic/functional-tests/pom.xml b/spring-petclinic/functional-tests/pom.xml index 263d398232..6e43adde8d 100644 --- a/spring-petclinic/functional-tests/pom.xml +++ b/spring-petclinic/functional-tests/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../../pom.xml spring-petclinic-test-webdriver diff --git a/spring-petclinic/pom.xml b/spring-petclinic/pom.xml index d5943dd882..c1975ee78c 100644 --- a/spring-petclinic/pom.xml +++ b/spring-petclinic/pom.xml @@ -20,7 +20,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml spring-petclinic diff --git a/spring-resteasy/README.html b/spring-resteasy/README.html new file mode 100644 index 0000000000..3acbf5f55b --- /dev/null +++ b/spring-resteasy/README.html @@ -0,0 +1,90 @@ + + + spring-resteasy: Example Using Resteasy Spring Integration + + + +

spring-resteasy: Example Using Resteasy Spring Integration

+

Author: Weinan Li l.weinan@gmail.com, Paul Gier pgier@redhat.com
+Level: Beginner
+Technologies: Resteasy, Spring
+Summary: The spring-resteasy quickstart demonstrates how to package and deploy a web application that includes resteasy-spring integration.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The spring-resteasy quickstart demonstrates how to package and deploy a web application, which includes resteasy-spring integration, in Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the full profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. +

    This deploys the target/spring-resteasy.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/spring-resteasy/.

+

That will provide links to the following URLs that demonstrate various path and parameter configurations.

+ +

And the same set as above but using the locating path.

+ +

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Functional Tests

+

This quickstart provides Arquillian functional tests as well. They are located in the functional-tests/ subdirectory under the root directory of this quickstart. Functional tests verify that your application behaves correctly from the user's point of view. The tests open a browser instance, simulate clicking around the page as a normal user would do, and then close the browser instance.

+

To run these tests, you must build the main project as described above.

+
    +
  1. Open a command line and navigate to the root directory of this quickstart.
    2. +
  2. Build the quickstart WAR using the following command: +
    mvn clean package
+
    +
    3. +
  3. +

    Navigate to the functional-tests/ directory in this quickstart.

    +
    4. +
  4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: +
    mvn clean verify -Parq-remote
+
    +
    5. +
  5. +

    If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command:

    +
    mvn clean verify -Parq-managed
+
    +
    6. +
+ + \ No newline at end of file diff --git a/spring-resteasy/README.md b/spring-resteasy/README.md index 4c23105951..6469a8fec6 100644 --- a/spring-resteasy/README.md +++ b/spring-resteasy/README.md @@ -4,64 +4,64 @@ Author: Weinan Li , Paul Gier Level: Beginner Technologies: Resteasy, Spring Summary: The `spring-resteasy` quickstart demonstrates how to package and deploy a web application that includes resteasy-spring integration. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? The `spring-resteasy` quickstart demonstrates how to package and deploy a web application, which includes resteasy-spring integration, in -${product.name.full}. +Red Hat JBoss Enterprise Application Platform. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the full profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This deploys the `target/${project.artifactId}.war` to the running instance of the server. +4. This deploys the `target/spring-resteasy.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . That will provide links to the following URLs that demonstrate various path and parameter configurations. -* [${project.artifactId}/hello?name=yourname](http://localhost:8080/${project.artifactId}/hello?name=yourname) -* [${project.artifactId}/basic](http://localhost:8080/${project.artifactId}/basic) -* [${project.artifactId}/queryParam?param=query](http://localhost:8080/${project.artifactId}/queryParam?param=query) -* [${project.artifactId}/matrixParam;param=matrix](http://localhost:8080/${project.artifactId}/matrixParam;param=matrix) -* [${project.artifactId}/uriParam/789](http://localhost:8080/${project.artifactId}/uriParam/789) +* [spring-resteasy/hello?name=yourname](http://localhost:8080/spring-resteasy/hello?name=yourname) +* [spring-resteasy/basic](http://localhost:8080/spring-resteasy/basic) +* [spring-resteasy/queryParam?param=query](http://localhost:8080/spring-resteasy/queryParam?param=query) +* [spring-resteasy/matrixParam;param=matrix](http://localhost:8080/spring-resteasy/matrixParam;param=matrix) +* [spring-resteasy/uriParam/789](http://localhost:8080/spring-resteasy/uriParam/789) And the same set as above but using the `locating` path. -* [${project.artifactId}/locating/hello?name=yourname](http://localhost:8080/${project.artifactId}/locating/hello?name=yourname) -* [${project.artifactId}/locating/basic](http://localhost:8080/${project.artifactId}/locating/basic) -* [${project.artifactId}/locating/queryParam?param=query](http://localhost:8080/${project.artifactId}/locating/queryParam?param=query) -* [${project.artifactId}/locating/matrixParam;param=matrix](http://localhost:8080/${project.artifactId}/locating/matrixParam;param=matrix) -* [${project.artifactId}/locating/uriParam/789](http://localhost:8080/${project.artifactId}/locating/uriParam/789) +* [spring-resteasy/locating/hello?name=yourname](http://localhost:8080/spring-resteasy/locating/hello?name=yourname) +* [spring-resteasy/locating/basic](http://localhost:8080/spring-resteasy/locating/basic) +* [spring-resteasy/locating/queryParam?param=query](http://localhost:8080/spring-resteasy/locating/queryParam?param=query) +* [spring-resteasy/locating/matrixParam;param=matrix](http://localhost:8080/spring-resteasy/locating/matrixParam;param=matrix) +* [spring-resteasy/locating/uriParam/789](http://localhost:8080/spring-resteasy/locating/uriParam/789) ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -81,11 +81,11 @@ To run these tests, you must build the main project as described above. mvn clean package 3. Navigate to the functional-tests/ directory in this quickstart. -4. If you have a running instance of the ${product.name} server, as described above, run the remote tests by typing the following command: +4. If you have a running instance of the JBoss EAP server, as described above, run the remote tests by typing the following command: mvn clean verify -Parq-remote -5. If you prefer to run the functional tests using managed instance of the ${product.name} server, meaning the tests will start the +5. If you prefer to run the functional tests using managed instance of the JBoss EAP server, meaning the tests will start the server for you, type the following command: mvn clean verify -Parq-managed diff --git a/spring-resteasy/pom.xml b/spring-resteasy/pom.xml index 750d6720a5..aa1e83c3d9 100644 --- a/spring-resteasy/pom.xml +++ b/spring-resteasy/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml spring-resteasy diff --git a/tasks-jsf/README.html b/tasks-jsf/README.html new file mode 100644 index 0000000000..d850a6045c --- /dev/null +++ b/tasks-jsf/README.html @@ -0,0 +1,87 @@ + + + tasks-jsf: JSF, JPA quickstart + + + +

tasks-jsf: JSF, JPA quickstart

+

Author: Lukas Fryc
+Level: Intermediate
+Technologies: JSF, JPA
+Summary: The tasks-jsf quickstart demonstrates how to use JPA persistence with JSF as the view layer.
+Prerequisites: tasks
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The tasks-jsf quickstart demonstrates how to use JPA persistence with JSF as view layer in an application deployed to Red Hat JBoss Enterprise Application Platform. It provides a JSF front end for the tasks quickstart.

+

The theme of this application is simple Task management with simple login. The project contains two entities - a user and a task.

+

This sample includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java. Persistence code is covered by tests to help you write business logic without the need to use any view layer.

+

JSF is used to present the user two views.

+
    +
  • authentication form: This provides the simple login
    • +
  • task view: This view contains the task list, a task detail, and a task addition form. The task view uses AJAX.
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the JBoss EAP Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/tasks-jsf.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL http://localhost:8080/tasks-jsf/.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/tasks-jsf/README.md b/tasks-jsf/README.md index 0452b49355..1415abcdab 100644 --- a/tasks-jsf/README.md +++ b/tasks-jsf/README.md @@ -5,12 +5,12 @@ Level: Intermediate Technologies: JSF, JPA Summary: The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as the view layer. Prerequisites: tasks -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as view layer in an application deployed to ${product.name.full}. It provides a JSF front end for the [tasks](../tasks/README.md) quickstart. +The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as view layer in an application deployed to Red Hat JBoss Enterprise Application Platform. It provides a JSF front end for the [tasks](../tasks/README.md) quickstart. The theme of this application is simple Task management with simple login. The project contains two entities - a `user` and a `task`. @@ -23,43 +23,43 @@ JSF is used to present the user two views. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). -## Start the ${product.name} Server +## Start the JBoss EAP Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/tasks-jsf.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL . +The application will be running at the following URL . ## Server Log: Expected Warnings and Errors @@ -73,7 +73,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -84,18 +84,18 @@ _Note:_ You will see the following warnings in the server log. You can ignore th This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/tasks-jsf/pom.xml b/tasks-jsf/pom.xml index c4120a52ba..bf65c5e743 100644 --- a/tasks-jsf/pom.xml +++ b/tasks-jsf/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml tasks-jsf diff --git a/tasks-rs/README.html b/tasks-rs/README.html new file mode 100644 index 0000000000..78f8709050 --- /dev/null +++ b/tasks-rs/README.html @@ -0,0 +1,242 @@ + + + tasks-rs: JAX-RS, JPA quickstart + + + +

tasks-rs: JAX-RS, JPA quickstart

+

Author: Mike Musgrove
+Level: Intermediate
+Technologies: JPA, JAX-RS
+Summary: The tasks-rs quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence.
+Prerequisites: tasks
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The tasks-rs quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence deployed to Red Hat JBoss Enterprise Application Platform.

+
    +
  • +

    The client uses HTTP to interact with the service. It builds on the tasks quickstart, which provides simple task management with secure login.

    +
    • +
  • +

    The service interface is implemented using JAX-RS. The SecurityContext JAX-RS annotation is used to inject the security details into each REST method.

    +
    • +
+

The application manages User and Task JPA entities. A user represents an authenticated principal and is associated with zero or more tasks. Service methods validate that there is an authenticated principal and the first time a principal is seen, a JPA User entity is created to correspond to the principal. JAX-RS annotated methods are provided for associating tasks with this user and for listing and removing tasks.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Add an Application User

+

This quickstart uses secured management interfaces and requires that you create the following application user to access the running application.

+ + + + + + + +
UserName Realm Password Roles
quickstartUser ApplicationRealm quickstartPwd1! guest
+

To add the application user, open a command prompt and type the following command:

+
  For Linux:   EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+  For Windows: EAP7_HOME\bin\add-user.bat  -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+
+

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/tasks-rs.war to the running instance of the server.

    +
    5. +
+

Access the Application Resources

+

Application resources for this quickstart are prefixed with the URL http://localhost:8080/tasks-rs/ and can be accessed by an HTTP client.

+
    +
  • A web browser can be used for methods that accept GET.
    • +
  • Otherwise, you must use cURL or some other command line tool that supports HTTP POST and DELETE methods.
    • +
+

Below you will find instructions to create, display, and delete tasks.

+

Create a Task

+

To associate a task called task1 with the user quickstartUser, you must authenticate as user quickstartUser and send an HTTP POST request to the url http://localhost:8080/tasks-rs/tasks/title/task1.

+

To issue the POST command using cURL, type the following command:

+
curl -i -u 'quickstartUser:quickstartPwd1!' -H "Content-Length: 0" -X POST http://localhost:8080/tasks-rs/tasks/title/task1
+
+

You will see the following response:

+
HTTP/1.1 201 Created
+Expires: 0
+Cache-Control: no-cache, no-store, must-revalidate
+X-Powered-By: Undertow/1
+Server: JBoss-EAP/7
+Pragma: no-cache
+Location: http://localhost:8080/tasks-rs/tasks/id/1
+Date: Thu, 20 Aug 2015 17:30:24 GMT
+
+

This is what happens when the command is issued:

+
    +
  • The -i flag tells cURL to print the returned headers.
    • +
  • The -u flag provides the authentication information for the request.
    • +
  • The -H flag adds a header to the outgoing request.
    • +
  • The -X flag tells cURL which HTTP method to use. The HTTP POST is used to create resources.
    • +
  • The Location header of the response contains the URI of the resource representing the newly created task.
    • +
+

The final argument to cURL determines the title of the task. Note that this approach is perhaps not very restful but it simplifies this quickstart. A better approach would be to POST to http://localhost:8080/tasks-rs/tasks/title passing the task title in the body of the request.

+

Display the XML Representation of a Task

+

To display the XML representation of the newly created resource, issue a GET request on the task URI returned in the Location header during the create.

+
    +
  1. To issue a GET using a browser, open a browser and access the URI. You will be challenged to enter valid authentication credentials. +

    http://localhost:8080/tasks-rs/tasks/id/1

    +
    2. +
  2. To issue a GET using cURL, type the following command: +
    curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/tasks-rs/tasks/id/1
+
    +

    The -H flag tells the server that the client wishes to accept XML content.

    +
    3. +
+

Using either of the above GET methods, you should see the following XML:

+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+   <task id="1" ownerName="quickstartUser">
+      <title>task1</title>
+   </task>
+
+

Display the XML Representation of all Tasks for a User

+

To obtain a list of all tasks for user quickstartUser in XML format, authenticate as user quickstartUser and send an HTTP GET request to the resource tasks URL.

+
    +
  1. +

    To issue a GET using a browser, open a browser and access the following URL. You will be challenged to enter valid authentication credentials.

    +

    http://localhost:8080/tasks-rs/tasks/title

    +
    2. +
  2. +

    To list all tasks associated with the user quickstartUser using cURL, type:

    +
    curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/tasks-rs/tasks/title
+
    +
    3. +
+

Using either of the above GET methods, you should see the following XML:

+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<collection>
+    <task id="1" ownerName="quickstartUser">
+    <title>task1</title>
+    </task>
+</collection>
+
+

Delete a Task

+

To delete a task, again authenticate as principal quickstartUser and send an HTTP DELETE request to the URI that represents the task.

+

To delete the task with id 1:

+
curl -i -u 'quickstartUser:quickstartPwd1!' -X DELETE http://localhost:8080/tasks-rs/tasks/id/1
+
+

You will see this response:

+
HTTP/1.1 204 No Content
+Expires: 0
+Cache-Control: no-cache, no-store, must-revalidate
+X-Powered-By: Undertow/1
+Server: JBoss-EAP/7
+Pragma: no-cache
+Date: Thu, 20 Aug 2015 17:32:39 GMT
+
+

Now list all tasks associated with user quickstartUser:

+
curl -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/tasks-rs/tasks/title
+
+

You will see a response with an empty collection:

+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<collection/>
+
+

Modify this Quickstart to Support JSON Representations of Tasks

+

JSON is not part of the JAX-RS standard but most JAX-RS implementations do support it. This quickstart can be modified to support JSON by uncommenting a few lines. Look for comment lines containing JSON::

+
    +
  1. +

    Open the pom.xml file and remove the comments from the dependency with artifactId resteasy-jackson2-provider.

    +
    <!-- JSON: uncomment to include json support (note json is not part of the JAX-RS standard) -->
+<!--
+<dependency>
+    <groupId>org.jboss.resteasy</groupId>
+    <artifactId>resteasy-jackson2-provider</artifactId>
+    <scope>provided</scope>
+</dependency>
+-->
+
    +
    2. +
  2. +

    Open the src/main/java/org/jboss/as/quickstarts/tasksrs/model/Task.java file and remove the comments from the following two lines.

    +
    // import com.fasterxml.jackson.annotation.JsonIgnore;
+
+// @JsonIgnore
+
    +
    3. +
  3. +

    Open the src/main/java/org/jboss/as/quickstarts/tasksrs/service/TaskResource.java file and make sure the GET methods produce "application/json" as well as "application/xml". Again, look for lines beginning with // JSON:.

    +
      +
    • Remove comments from this line: +
      // @Produces({ "application/xml", "application/json" })
+
      +
      • +
    • Add comments to this line: +
      @Produces({ "application/xml" })
+
      +
      • +
    +
    4. +
  4. Rebuild and redeploy the quickstart.
    5. +
  5. +

    Create a Task as you did for the XML version of this quickstart.

    +
    6. +
  6. +

    View task resources in JSON media type by specifying the correct Accept header. For example, using the cURL tool, type the following command:

    +
    curl -H "Accept: application/json" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/tasks-rs/tasks/id/1
+
    +
    7. +
+

You will see the following response:

+
    {"id":1,"title":"task1","ownerName":"quickstartUser"}
+
+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Be sure to Add an Application User as described above.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/tasks-rs/README.md b/tasks-rs/README.md index 12e7df3086..4057d70695 100644 --- a/tasks-rs/README.md +++ b/tasks-rs/README.md @@ -5,12 +5,12 @@ Level: Intermediate Technologies: JPA, JAX-RS Summary: The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence. Prerequisites: tasks -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence deployed to ${product.name.full}. +The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence deployed to Red Hat JBoss Enterprise Application Platform. * The client uses HTTP to interact with the service. It builds on the *tasks* quickstart, which provides simple task management with secure login. @@ -18,21 +18,21 @@ The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that us The application manages `User` and `Task` JPA entities. A user represents an authenticated principal and is associated with zero or more tasks. Service methods validate that there is an authenticated principal and the first time a principal is seen, a JPA User entity is created to correspond to the principal. JAX-RS annotated methods are provided for associating tasks with this user and for listing and removing tasks. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Add an Application User @@ -45,8 +45,8 @@ This quickstart uses secured management interfaces and requires that you create To add the application user, open a command prompt and type the following command: - For Linux: ${jboss.home.name}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' - For Windows: ${jboss.home.name}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' + For Linux: EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' + For Windows: EAP7_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: [Add an Application User](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user). @@ -54,27 +54,27 @@ For an example of how to use the add-user utility, see the instructions located ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/tasks-rs.war` to the running instance of the server. ## Access the Application Resources -Application resources for this quickstart are prefixed with the URL and can be accessed by an HTTP client. +Application resources for this quickstart are prefixed with the URL and can be accessed by an HTTP client. * A web browser can be used for methods that accept *GET*. * Otherwise, you must use cURL or some other command line tool that supports HTTP *POST* and *DELETE* methods. @@ -83,11 +83,11 @@ Below you will find instructions to create, display, and delete tasks. ### Create a Task -To associate a task called `task1` with the user `quickstartUser`, you must authenticate as user `quickstartUser` and send an HTTP *POST* request to the url . +To associate a task called `task1` with the user `quickstartUser`, you must authenticate as user `quickstartUser` and send an HTTP *POST* request to the url . To issue the *POST* command using cURL, type the following command: - curl -i -u 'quickstartUser:quickstartPwd1!' -H "Content-Length: 0" -X POST http://localhost:8080/${project.artifactId}/tasks/title/task1 + curl -i -u 'quickstartUser:quickstartPwd1!' -H "Content-Length: 0" -X POST http://localhost:8080/tasks-rs/tasks/title/task1 You will see the following response: @@ -97,7 +97,7 @@ You will see the following response: X-Powered-By: Undertow/1 Server: JBoss-EAP/7 Pragma: no-cache - Location: http://localhost:8080/${project.artifactId}/tasks/id/1 + Location: http://localhost:8080/tasks-rs/tasks/id/1 Date: Thu, 20 Aug 2015 17:30:24 GMT This is what happens when the command is issued: @@ -108,7 +108,7 @@ This is what happens when the command is issued: * The `-X` flag tells cURL which HTTP method to use. The HTTP *POST* is used to create resources. * The `Location` header of the response contains the URI of the resource representing the newly created task. -The final argument to cURL determines the title of the task. Note that this approach is perhaps not very restful but it simplifies this quickstart. A better approach would be to *POST* to `http://localhost:8080/${project.artifactId}/tasks/title` passing the task title in the body of the request. +The final argument to cURL determines the title of the task. Note that this approach is perhaps not very restful but it simplifies this quickstart. A better approach would be to *POST* to `http://localhost:8080/tasks-rs/tasks/title` passing the task title in the body of the request. ### Display the XML Representation of a Task @@ -117,10 +117,10 @@ To display the XML representation of the newly created resource, issue a *GET* r 1. To issue a *GET* using a browser, open a browser and access the URI. You will be challenged to enter valid authentication credentials. - + 2. To issue a *GET* using cURL, type the following command: - curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/${project.artifactId}/tasks/id/1 + curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/tasks-rs/tasks/id/1 The `-H` flag tells the server that the client wishes to accept XML content. @@ -138,11 +138,11 @@ To obtain a list of all tasks for user `quickstartUser` in XML format, authentic 1. To issue a *GET* using a browser, open a browser and access the following URL. You will be challenged to enter valid authentication credentials. - + 2. To list all tasks associated with the user `quickstartUser` using cURL, type: - curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/${project.artifactId}/tasks/title + curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/tasks-rs/tasks/title Using either of the above *GET* methods, you should see the following XML: @@ -159,7 +159,7 @@ To delete a task, again authenticate as principal `quickstartUser` and send an H To delete the task with id `1`: - curl -i -u 'quickstartUser:quickstartPwd1!' -X DELETE http://localhost:8080/${project.artifactId}/tasks/id/1 + curl -i -u 'quickstartUser:quickstartPwd1!' -X DELETE http://localhost:8080/tasks-rs/tasks/id/1 You will see this response: @@ -173,7 +173,7 @@ You will see this response: Now list all tasks associated with user `quickstartUser`: - curl -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/${project.artifactId}/tasks/title + curl -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/tasks-rs/tasks/title You will see a response with an empty collection: @@ -216,7 +216,7 @@ JSON is not part of the JAX-RS standard but most JAX-RS implementations do suppo 6. View task resources in JSON media type by specifying the correct *Accept* header. For example, using the cURL tool, type the following command: - curl -H "Accept: application/json" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/${project.artifactId}/tasks/id/1 + curl -H "Accept: application/json" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/tasks-rs/tasks/id/1 You will see the following response: {"id":1,"title":"task1","ownerName":"quickstartUser"} @@ -233,7 +233,7 @@ _Note:_ You will see the following warnings in the server log. You can ignore th ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -244,18 +244,18 @@ _Note:_ You will see the following warnings in the server log. You can ignore th This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). Be sure to [Add an Application User](#add-an-application-user) as described above. diff --git a/tasks-rs/pom.xml b/tasks-rs/pom.xml index 152f6cb28b..c9949e18b6 100644 --- a/tasks-rs/pom.xml +++ b/tasks-rs/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml tasks-rs diff --git a/tasks/README.html b/tasks/README.html new file mode 100644 index 0000000000..c944d54da2 --- /dev/null +++ b/tasks/README.html @@ -0,0 +1,89 @@ + + + tasks: Test JPA with Arquillian + + + +

tasks: Test JPA with Arquillian

+

Author: Oliver Kiss, Lukas Fryc
+Level: Intermediate
+Technologies: JPA, Arquillian
+Summary: The tasks quickstart includes a persistence unit and sample persistence code to demonstrate how to use JPA for database access in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The tasks quickstart demonstrates how to use JPA in Red Hat JBoss Enterprise Application Platform.

+

It includes a persistence unit and some sample persistence code to demonstrate database access in enterprise Java.

+

It does not contain a user interface layer. The purpose of the project is to show you how to test JPA with Arquillian.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Console Output

+

Maven prints summary of the 8 performed tests to the console.

+
-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.jboss.as.quickstarts.tasks.UserDaoTest
+Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.084 sec
+Running org.jboss.as.quickstarts.tasks.TaskDaoTest
+Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.31 sec
+
+Results :
+
+Tests run: 8, Failures: 0, Errors: 0, Skipped: 0
+
+

Server log

+

SQL statements generated by Hibernate are written into the server log.

+

Server Log: Expected warnings and errors

+

Note: You will see the following warnings in the server log. You can ignore these warnings.

+
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.
+
+HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Example Output from the tests

+

Creating the database schema:

+
INFO  [stdout] (ServerService Thread Pool -- 104) Hibernate: drop table Task if exists
+INFO  [stdout] (ServerService Thread Pool -- 104) Hibernate: drop table User if exists
+INFO  [stdout] (ServerService Thread Pool -- 104) Hibernate: create table Task (id bigint generated by default as identity, title varchar(255), owner_id bigint, primary key (id))
+INFO  [stdout] (ServerService Thread Pool -- 104) Hibernate: create table User (id bigint generated by default as identity, username varchar(255), primary key (id))
+INFO  [stdout] (ServerService Thread Pool -- 104) Hibernate: alter table Task add constraint FK46hwvn8nayomwr7k7h13l0uxe foreign key (owner_id) references User
+INFO  [stdout] (ServerService Thread Pool -- 104) Hibernate: alter table User add constraint UK_jreodf78a7pl5qidfh43axdfb unique (username)
+
+

Generating ID for a new entity and inserting the entity into the database:

+
INFO  [stdout] (default task-83) Hibernate: select user0_.id as id1_1_, user0_.username as username2_1_ from User user0_ where user0_.username=?
+INFO  [stdout] (default task-88) Hibernate: select user0_.id as id1_1_, user0_.username as username2_1_ from User user0_ where user0_.username=?
+INFO  [stdout] (default task-90) Hibernate: insert into User (id, username) values (null, ?)
+INFO  [stdout] (default task-90) Hibernate: select user0_.id as id1_1_, user0_.username as username2_1_ from User user0_ where user0_.username=?
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/tasks/README.md b/tasks/README.md index 9ba6d9f1a2..b01813e980 100644 --- a/tasks/README.md +++ b/tasks/README.md @@ -3,56 +3,56 @@ Author: Oliver Kiss, Lukas Fryc Level: Intermediate Technologies: JPA, Arquillian -Summary: The `tasks` quickstart includes a persistence unit and sample persistence code to demonstrate how to use JPA for database access in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `tasks` quickstart includes a persistence unit and sample persistence code to demonstrate how to use JPA for database access in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `tasks` quickstart demonstrates how to use JPA in ${product.name.full}. +The `tasks` quickstart demonstrates how to use JPA in Red Hat JBoss Enterprise Application Platform. It includes a persistence unit and some sample persistence code to demonstrate database access in enterprise Java. It does not contain a user interface layer. The purpose of the project is to show you how to test JPA with Arquillian. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in ${product.name} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for ${product.name.full}._ +_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the [Configuration Guide](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: mvn clean verify -Parq-remote -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Console Output @@ -106,7 +106,7 @@ Generating ID for a new entity and inserting the entity into the database: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/tasks/pom.xml b/tasks/pom.xml index 51c3ea7fa5..4555a16152 100644 --- a/tasks/pom.xml +++ b/tasks/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml tasks diff --git a/temperature-converter/README.html b/temperature-converter/README.html new file mode 100644 index 0000000000..f67ee1a632 --- /dev/null +++ b/temperature-converter/README.html @@ -0,0 +1,74 @@ + + + temperature-converter: Stateless Session EJB (SLSB) + + + +

temperature-converter: Stateless Session EJB (SLSB)

+

Author: Bruce Wolfe
+Level: Beginner
+Technologies: CDI, JSF, SLSB EJB
+Summary: The temperature-converter quickstart does temperature conversion using an EJB Stateless Session Bean (SLSB), CDI, and a JSF front-end client.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The temperature-converter example demonstrates the use of an EJB Stateless Session Bean (SLSB) and CDI, accessed using a JSF, and deployed to Red Hat JBoss Enterprise Application Platform using a WAR archive.

+

The application does the following:

+
    +
  1. The User Interface is a JSF page that asks for a temperature and a scale (Fahrenheit or Celsius).
    2. +
  2. When you click on Convert, the temperature string is passed to the TemperatureConverter controller (managed) bean.
    3. +
  3. The managed bean then invokes the convert() method of the injected TemperatureConvertEJB (notice the field annotated with @Inject).
    4. +
  4. The response from TemperatureConvertEJB is stored in the temperature field of the managed bean.
    5. +
  5. The managed bean is annotated as @SessionScoped, so the same managed bean instance is used for the entire session.
    6. +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/temperature-converter.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/temperature-converter/.

+

You will be presented with a simple form for temperature conversion.

+
    +
  1. Optionally, Select a scale: Celsius or Fahrenheit.
    2. +
  2. Enter a temperature.
    3. +
  3. Press the Convert button to see the results.
    4. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
  mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/temperature-converter/README.md b/temperature-converter/README.md index fb8c763808..42a2544fdb 100644 --- a/temperature-converter/README.md +++ b/temperature-converter/README.md @@ -4,12 +4,12 @@ Author: Bruce Wolfe Level: Beginner Technologies: CDI, JSF, SLSB EJB Summary: The `temperature-converter` quickstart does temperature conversion using an *EJB Stateless Session Bean* (SLSB), *CDI*, and a *JSF* front-end client. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `temperature-converter` example demonstrates the use of an *EJB Stateless Session Bean* (SLSB) and *CDI*, accessed using a *JSF*, and deployed to ${product.name.full} using a WAR archive. +The `temperature-converter` example demonstrates the use of an *EJB Stateless Session Bean* (SLSB) and *CDI*, accessed using a *JSF*, and deployed to Red Hat JBoss Enterprise Application Platform using a WAR archive. The application does the following: @@ -21,39 +21,39 @@ The application does the following: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/temperature-converter.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . You will be presented with a simple form for temperature conversion. @@ -64,7 +64,7 @@ You will be presented with a simple form for temperature conversion. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -73,7 +73,7 @@ You will be presented with a simple form for temperature conversion. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/temperature-converter/pom.xml b/temperature-converter/pom.xml index 4c5114fb8f..bc0c363e82 100644 --- a/temperature-converter/pom.xml +++ b/temperature-converter/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml temperature-converter diff --git a/thread-racing/README.html b/thread-racing/README.html new file mode 100644 index 0000000000..3e93e6ea01 --- /dev/null +++ b/thread-racing/README.html @@ -0,0 +1,78 @@ + + + thread-racing: A Java EE thread racing web application + + + +

thread-racing: A Java EE thread racing web application

+

Author: Eduardo Martins
+Level: Beginner
+Technologies: Batch, CDI, EE Concurrency, JAX-RS, JMS, JPA, JSON, Web Sockets
+Summary: A thread racing web application that demonstrates technologies introduced or updated in the latest Java EE specification.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The thread-racing quickstart is a web application that demonstrates new and updated technologies introduced by the Java EE 7 specification through simple use cases.

+

The web application allows the user to trigger a race between 4 threads and follow, in real time, the progress of each thread until the race ends.

+

The race itself consists of multiple stages, each demonstrating the usage of a specific new or updated Java EE 7 technology:

+
    +
  • Batch 1.0
    • +
  • EE Concurrency 1.0
    • +
  • JAX-RS 2.0
    • +
  • JMS 2.0
    • +
  • JSON 1.0
    • +
+

WebSockets 1.0 is one of the most relevant new technologies introduced by Java EE 7. Instead of being used in a race stage, a WebSockets 1.0 ServerEndpoint provides the remote application interface. A new race is run when a client establishes a session. That session is then used to update the client in real time, with respect to the race progress and results. The src/main/java/org/jboss/as/quickstarts/threadracing/WebSocketRace.java file is the WebSocket server endpoint class and is a good entry point when studying how the application code works.

+

JPA 2.1 is also present in the application code. Specifically it is used to store race results in the default data source instance, which is also new to Java EE. Further details are included in the src/main/java/org/jboss/as/quickstarts/threadracing/results/RaceResults.java class.

+

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the JBoss EAP Server with the Full Profile

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the full profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/thread-racing.war to the running instance of the server.

    +
    5. +
+

Access the application

+

The application will be running at the following URL http://localhost:8080/thread-racing/.

+

To start a race press the Insert Coin button. The page displays the names of the threads as they join the race. It then tracks the progress of each thread through the Batch, EE Concurrency, JAX-RS, JMS, and JSON stages of the race. Finally, it displays the official race results and championship standings.

+

Server Log: Expected Warnings and Errors

+

Note: You will see the following warning in the server log. You can ignore this warning.

+
HHH000431: Unable to determine H2 database version, certain features may not work
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

NOTE: Within JBoss Developer Studio, be sure to define a server runtime environment that uses the standalone-full.xml configuration file.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/thread-racing/README.md b/thread-racing/README.md index aeee1fd954..3939b282a9 100644 --- a/thread-racing/README.md +++ b/thread-racing/README.md @@ -4,8 +4,8 @@ Author: Eduardo Martins Level: Beginner Technologies: Batch, CDI, EE Concurrency, JAX-RS, JMS, JPA, JSON, Web Sockets Summary: A thread racing web application that demonstrates technologies introduced or updated in the latest Java EE specification. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? @@ -26,44 +26,44 @@ A new race is run when a client establishes a session. That session is then used JPA 2.1 is also present in the application code. Specifically it is used to store race results in the default data source instance, which is also new to Java EE. Further details are included in the `src/main/java/org/jboss/as/quickstarts/threadracing/results/RaceResults.java` class. -_Note: This quickstart uses the H2 database included with ${product.name.full} ${product.version}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +_Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7.1. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). -## Start the ${product.name} Server with the Full Profile +## Start the JBoss EAP Server with the Full Profile -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the full profile: - For Linux: ${jboss.home.name}/bin/standalone.sh -c standalone-full.xml - For Windows: ${jboss.home.name}\bin\standalone.bat -c standalone-full.xml + For Linux: EAP7_HOME/bin/standalone.sh -c standalone-full.xml + For Windows: EAP7_HOME\bin\standalone.bat -c standalone-full.xml ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/thread-racing.war` to the running instance of the server. ## Access the application -The application will be running at the following URL . +The application will be running at the following URL . To start a race press the `Insert Coin` button. The page displays the names of the threads as they join the race. It then tracks the progress of each thread through the Batch, EE Concurrency, JAX-RS, JMS, and JSON stages of the race. Finally, it displays the official race results and championship standings. @@ -77,7 +77,7 @@ _Note:_ You will see the following warning in the server log. You can ignore thi ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -86,7 +86,7 @@ _Note:_ You will see the following warning in the server log. You can ignore thi ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). _NOTE:_ Within JBoss Developer Studio, be sure to define a server runtime environment that uses the `standalone-full.xml` configuration file. diff --git a/thread-racing/pom.xml b/thread-racing/pom.xml index d7877ec403..2b761b6649 100644 --- a/thread-racing/pom.xml +++ b/thread-racing/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml thread-racing diff --git a/websocket-client/README.html b/websocket-client/README.html new file mode 100644 index 0000000000..d1745c242b --- /dev/null +++ b/websocket-client/README.html @@ -0,0 +1,76 @@ + + + websocket-client: WebSocket Java Client Example + + + +

websocket-client: WebSocket Java Client Example

+

Author: Paul Cowan
+Level: Intermediate
+Technologies: Web Socket, CDI Events, JSON, SSL
+Summary: Demonstrates use of a Javascript WebSocket client, WebSocket configuration, programmatic binding, and secure WebSocket. Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The websocket-client quickstart demonstrates how to use the Java API for WebSockets to create Java client endpoint connected to a remote WebSocket server.

+

The example is modeled as a relay between a frontend WebSocket server endpoint and a backend WebSocket client endpoint.

+

Message Flow:
+(Browser Javascript WebSocket Client) <-> (JBoss EAP WebSocket Server Endpoint) <-> (JBoss EAP Websocket Client Endpoint) <-> (Remote WebSocket Echo Server)

+

CDI events are used to pass messages between the frontend and backend. A single backend WebSocket client endpoint is shared for all frontend clients.

+

The remote WebSocket server must be an Echo server; a simple WebSocket server that echos back messages the client sends for the purpose of testing. Such a server is publicly available at ws://echo.websocket.org, but any echo server will work.

+

Frontend does not use WebSocket annotations because it demonstrates how to use ServerEndpointConfig to modify the default Configurator to use an application scoped Endpoint, and how to deploy the Endpoint programatically.

+

Backend does not use WebSocket annotations because it demonstrates how to use ClientEndpointConfig to configure the WebSocket client to connect to a secure (wss) WebSocket.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. This will deploy target/websocket-client.war to the running instance of the server.
    5. +
+

Access the Application

+

Access the running application in a browser at the following URL: http://localhost:8080/websocket-client/

+

You are presented with the WebSocket Echo Replay page confirming the connection to the remote WebSocket Echo server.

+
Connecting to ws://localhost:8080/websocket-client/relay
+RECV: Opened frontend session FRONTEND_SESSION_ID
+
+

Type a message in the text input field at the bottom of the page and click Send. The message is processed and the form displays the relayed results. The message This is a test was used in the following example.

+
SEND: This is a test
+RECV: BROADCAST: Connecting to backend wss://echo.websocket.org
+RECV: BROADCAST: Opened backend session BACKEND_SESSION_ID
+RECV: Sending message from frontend session FRONTEND_SESSION_ID
+RECV: Received message from backend session BACKEND_SESSION_ID
+RECV: This is a test
+
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/websocket-client/README.md b/websocket-client/README.md index 242c789e0f..c2952e0a4e 100644 --- a/websocket-client/README.md +++ b/websocket-client/README.md @@ -4,8 +4,8 @@ Author: Paul Cowan Level: Intermediate Technologies: Web Socket, CDI Events, JSON, SSL Summary: Demonstrates use of a Javascript WebSocket client, WebSocket configuration, programmatic binding, and secure WebSocket. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? @@ -14,7 +14,7 @@ The `websocket-client` quickstart demonstrates how to use the Java API for WebSo The example is modeled as a relay between a *frontend* WebSocket server endpoint and a *backend* WebSocket client endpoint. Message Flow: -`(Browser Javascript WebSocket Client) <-> (${product.name} WebSocket Server Endpoint) <-> (${product.name} Websocket Client Endpoint) <-> (Remote WebSocket Echo Server)` +`(Browser Javascript WebSocket Client) <-> (JBoss EAP WebSocket Server Endpoint) <-> (JBoss EAP Websocket Client Endpoint) <-> (Remote WebSocket Echo Server)` CDI events are used to pass messages between the frontend and backend. A single backend WebSocket client endpoint is shared for all frontend clients. @@ -26,42 +26,42 @@ The remote WebSocket server must be an *Echo* server; a simple WebSocket server ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/websocket-client.war` to the running instance of the server. ## Access the Application -Access the running application in a browser at the following URL: +Access the running application in a browser at the following URL: You are presented with the `WebSocket Echo Replay` page confirming the connection to the remote WebSocket *Echo* server. - Connecting to ws://localhost:8080/${project.artifactId}/relay + Connecting to ws://localhost:8080/websocket-client/relay RECV: Opened frontend session FRONTEND_SESSION_ID Type a message in the text input field at the bottom of the page and click `Send`. The message is processed and the form displays the relayed results. The message `This is a test` was used in the following example. @@ -76,7 +76,7 @@ Type a message in the text input field at the bottom of the page and click `Send ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -85,7 +85,7 @@ Type a message in the text input field at the bottom of the page and click `Send ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/websocket-client/pom.xml b/websocket-client/pom.xml index 47e2d5daa3..bd4aea1da4 100644 --- a/websocket-client/pom.xml +++ b/websocket-client/pom.xml @@ -22,7 +22,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml websocket-client diff --git a/websocket-endpoint/README.html b/websocket-endpoint/README.html new file mode 100644 index 0000000000..312f155a07 --- /dev/null +++ b/websocket-endpoint/README.html @@ -0,0 +1,65 @@ + + + websocket-endpoint: Web application using WebSockets and JSON-P + + + +

websocket-endpoint: Web application using WebSockets and JSON-P

+

Author: Rafael Benevides
+Level: Beginner
+Technologies: CDI, WebSocket, JSON-P
+Summary: Shows how to use WebSockets with JSON to broadcast information to all open WebSocket sessions in JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The websocket-endpoint quickstart demonstrates how to use Java API for WebSockets to create server endpoints in Red Hat JBoss Enterprise Application Platform.

+

The BidWebSocketEndpoint provides the WebSocket endpoint that receives Message instances from clients/browsers and replies with the current Bidding instance. The conversion from JSON content to the specific instances are made by MessageDecoder and BiddingEncode classes.

+

Every update made on the Bidding are immediately propagated to all opened WebSocket sessions without any browser submission or AJAX polling mechanism.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server with the default profile: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command line and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean package wildfly:deploy
+
    +
    4. +
  4. This will deploy target/websocket-endpoint.war to the running instance of the server.
    5. +
+

Access the application

+

Access the running application in a browser at the following URL: http://localhost:8080/websocket-endpoint/

+

You are presented with a simple form that shows a bidding with the status NOT_STARTED.

+

Click on Do a bid! button. That will start the bidding and trigger the 1 minute countdown timer. You can also notice that every Bid will be listed under the List of bids section.

+

You should open the application URL in other browsers or tabs. You will notice that every change on the bidding is automatically update in all opened browser or tabs. The item will be SOLD once that it reaches the Buy now price. At the countdown timeout, the bidding will be EXPIRED. You can click on Buy it now button to immediately buy the item.

+

You can restart the bidding if you click on Reset bidding button.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + + \ No newline at end of file diff --git a/websocket-endpoint/README.md b/websocket-endpoint/README.md index f8becb0332..e9288f8b20 100644 --- a/websocket-endpoint/README.md +++ b/websocket-endpoint/README.md @@ -3,14 +3,14 @@ Author: Rafael Benevides Level: Beginner Technologies: CDI, WebSocket, JSON-P -Summary: Shows how to use WebSockets with JSON to broadcast information to all open WebSocket sessions in ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: Shows how to use WebSockets with JSON to broadcast information to all open WebSocket sessions in JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `websocket-endpoint` quickstart demonstrates how to use Java API for WebSockets to create server endpoints in ${product.name.full}. +The `websocket-endpoint` quickstart demonstrates how to use Java API for WebSockets to create server endpoints in Red Hat JBoss Enterprise Application Platform. The `BidWebSocketEndpoint` provides the WebSocket endpoint that receives `Message` instances from clients/browsers and replies with the current `Bidding` instance. The conversion from JSON content to the specific instances are made by `MessageDecoder` and `BiddingEncode` classes. @@ -19,39 +19,39 @@ Every update made on the `Bidding` are immediately propagated to all opened WebS ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command line and navigate to the root of the ${product.name} directory. +1. Open a command line and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server with the default profile: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command line and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean package wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/websocket-endpoint.war` to the running instance of the server. ## Access the application -Access the running application in a browser at the following URL: +Access the running application in a browser at the following URL: You are presented with a simple form that shows a bidding with the status `NOT_STARTED`. @@ -64,7 +64,7 @@ You can restart the bidding if you click on `Reset bidding` button. ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -73,7 +73,7 @@ You can restart the bidding if you click on `Reset bidding` button. ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/websocket-endpoint/pom.xml b/websocket-endpoint/pom.xml index be84d0e9e3..3d0cdb6377 100644 --- a/websocket-endpoint/pom.xml +++ b/websocket-endpoint/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml websocket-endpoint diff --git a/websocket-hello/README.html b/websocket-hello/README.html new file mode 100644 index 0000000000..4a01ae4d32 --- /dev/null +++ b/websocket-hello/README.html @@ -0,0 +1,76 @@ + + + websocket-hello: A simple WebSocket application + + + +

websocket-hello: A simple WebSocket application

+

Author: Sande Gilda, Emmanuel Hugonett
+Level: Beginner
+Technologies: WebSocket, CDI, JSF
+Summary: The websocket-hello quickstart demonstrates how to create a simple WebSocket application.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The websocket-hello quickstart demonstrates how to create a simple WebSocket-enabled application in Red Hat JBoss Enterprise Application Platform. It consists of the following:

+
    +
  • A JavaScript enabled WebSocket HTML client.
    • +
  • A WebSocket server endpoint that uses annotations to interact with the WebSocket events.
    • +
  • A jboss-web.xml file configured to enable WebSockets
    • +
+

WebSockets are a requirement of the Java EE 7 specification and are implemented in JBoss EAP 7.1. They are configured in the undertow subsystem of the server configuration file. This quickstart uses the WebSocket default settings, so it is not necessary to modify the server configuration to deploy and run this quickstart.

+

Note: This quickstart demonstrates only a few of the basic functions. A fully functional application should provide better error handling and intercept and handle additional events.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the JBoss EAP Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/websocket-hello.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/websocket-hello/.

+
    +
  1. Click on the Open Connection button to create the WebSocket connection and display current status of Open.
    2. +
  2. Type a name and click Say Hello to create and send the Say hello to <NAME> message. The message appears in the server log and a response is sent to the client.
    3. +
  3. Click on the Close Connection button to close the WebSocket connection and display the current status of Closed.
    4. +
  4. If you attempt to send another message after closing the connection, the following message appears on the page: +
    WebSocket connection is not established. Please click the Open Connection button.
+
    +
    5. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/websocket-hello/README.md b/websocket-hello/README.md index 14e9c24b25..2544888790 100644 --- a/websocket-hello/README.md +++ b/websocket-hello/README.md @@ -4,56 +4,56 @@ Author: Sande Gilda, Emmanuel Hugonett Level: Beginner Technologies: WebSocket, CDI, JSF Summary: The `websocket-hello` quickstart demonstrates how to create a simple WebSocket application. -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `websocket-hello` quickstart demonstrates how to create a simple WebSocket-enabled application in ${product.name.full}. It consists of the following: +The `websocket-hello` quickstart demonstrates how to create a simple WebSocket-enabled application in Red Hat JBoss Enterprise Application Platform. It consists of the following: * A JavaScript enabled WebSocket HTML client. * A WebSocket server endpoint that uses annotations to interact with the WebSocket events. * A `jboss-web.xml` file configured to enable WebSockets -WebSockets are a requirement of the Java EE 7 specification and are implemented in ${product.name} ${product.version}. They are configured in the `undertow` subsystem of the server configuration file. This quickstart uses the WebSocket default settings, so it is not necessary to modify the server configuration to deploy and run this quickstart. +WebSockets are a requirement of the Java EE 7 specification and are implemented in JBoss EAP 7.1. They are configured in the `undertow` subsystem of the server configuration file. This quickstart uses the WebSocket default settings, so it is not necessary to modify the server configuration to deploy and run this quickstart. _Note: This quickstart demonstrates only a few of the basic functions. A fully functional application should provide better error handling and intercept and handle additional events._ ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). -## Start the ${product.name} Server +## Start the JBoss EAP Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/websocket-hello.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . 1. Click on the `Open Connection` button to create the WebSocket connection and display current status of `Open`. 2. Type a name and click `Say Hello` to create and send the `Say hello to ` message. The message appears in the server log and a response is sent to the client. @@ -65,7 +65,7 @@ The application will be running at the following URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml websocket-hello diff --git a/wsat-simple/README.html b/wsat-simple/README.html new file mode 100644 index 0000000000..92ba3a78ad --- /dev/null +++ b/wsat-simple/README.html @@ -0,0 +1,141 @@ + + + wsat-simple: WS-AT (WS-AtomicTransaction) - Simple + + + +

wsat-simple: WS-AT (WS-AtomicTransaction) - Simple

+

Author: Paul Robinson
+Level: Intermediate
+Technologies: WS-AT, JAX-WS
+Summary: The wsat-simple quickstart demonstrates a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service, bundled as a WAR, and deployed to JBoss EAP.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The wsat-simple quickstart demonstrates the deployment of a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service bundled in a WAR archive for deployment to Red Hat JBoss Enterprise Application Platform.

+

The Web service is offered by a Restaurant for making bookings. The Service allows bookings to be made within an Atomic Transaction.

+

This example demonstrates the basics of implementing a WS-AT enabled Web service. It is beyond the scope of this quick start to demonstrate more advanced features. In particular:

+
    +
  • The Service does not implement the required hooks to support recovery in the presence of failures.
    • +
  • It also does not utilize a transactional back-end resource.
    • +
  • Only one web service participates in the protocol. As WS-AT is a 2PC coordination protocol, it is best suited to multi-participant scenarios.
    • +
+

For a more complete example, please see the XTS demonstrator application that ships with the Narayana project: http://narayana.io/.

+

It is also assumed that you have an understanding of WS-AtomicTransaction. For more details, read the XTS documentation that ships with the Narayana project: http://narayana.io/docs/product.

+

The application consists of a single JAX-WS web service that is deployed within a WAR archive. It is tested with a JBoss Arquillian enabled JUnit test.

+

When running the org.jboss.as.quickstarts.wsat.simple.ClientTest#testCommit() method, the following steps occur:

+
    +
  1. A new Atomic Transaction (AT) is created by the client.
    2. +
  2. An operation on a WS-AT enabled Web service is invoked by the client.
    3. +
  3. The JaxWSHeaderContextProcessor in the WS Client handler chain inserts the WS-AT context into the outgoing SOAP message
    4. +
  4. When the service receives the SOAP request, the JaxWSHeaderContextProcessor in its handler chain inspects the WS-AT context and associates the request with this AT.
    5. +
  5. The Web service operation is invoked...
    6. +
  6. A participant is enlisted in this AT. This allows the Web Service logic to respond to protocol events, such as Commit and Rollback.
    7. +
  7. The service invokes the business logic. In this case, a booking is made with the restaurant.
    8. +
  8. The backend resource is prepared. This ensures that the Backend resource can undo or make permanent the change when told to do so by the coordinator.
    9. +
  9. The client can then decide to commit or rollback the AT. If the client decides to commit, the coordinator will begin the 2PC protocol. If the participant decides to rollback, all participants will be told to rollback.
    10. +
+

There is another test that shows what happens if the client decides to rollback the AT.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server with the Custom Options

+

First, edit the log level to reduce the amount of log output. This should make it easier to read the logs produced by this example. To do this add the following logger block to the ./docs/examples/configs/standalone-xts.xml of your JBoss distribution. You should add it just bellow one of the other logger blocks.

+
<logger category="org.apache.cxf.service.factory.ReflectionServiceFactoryBean">
+    <level name="WARN"/>
+</logger>
+
+

Next you need to start JBoss EAP with the XTS subsystem enabled. This is enabled through the optional server configuration standalone-xts.xml. To do this, run the following commands from the top-level directory of JBoss EAP:

+
For Linux:     ./bin/standalone.sh --server-config=../../docs/examples/configs/standalone-xts.xml
+For Windows:   \bin\standalone.bat --server-config=..\..\docs\examples\configs\standalone-xts.xml
+
+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
  4. +

    You should see the following result.

    +
    Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
    +
    5. +
+

Note: You see the following warning when you run the Arquillian tests in remote mode.

+
WARNING: Configuration contain properties not supported by the backing object org.jboss.as.arquillian.container.remote.RemoteContainerConfiguration
+Unused property entries: {serverConfig=../../docs/examples/configs/standalone-xts.xml}
+Supported property names: [managementAddress, password, managementPort, managementProtocol, username]
+
+

This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the serverConfig property defined in the arquillian.xml file to start the server with the XTS subsystem enabled.

+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Server Log

+

The following messages should appear in the server log. The messages trace the steps taken by the tests. Note there may be other informational log messages interlaced between these.

+

Test rollback:

+
10:54:29,607 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) Starting 'testRollback'. This test invokes a WS within an AT. The AT is later rolled back, which causes the back-end resource(s) to be rolled back.
+10:54:29,607 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) [CLIENT] Creating a new WS-AT User Transaction
+10:54:29,608 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) [CLIENT] Beginning Atomic Transaction (All calls to Web services that support WS-AT wil be included in this transaction)
+10:54:29,932 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) [CLIENT] invoking makeBooking() on WS
+10:54:30,000 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-25) [SERVICE] Restaurant service invoked to make a booking
+10:54:30,000 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-25) [SERVICE] Enlisting a Durable2PC participant into the AT
+10:54:30,121 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-25) [SERVICE] Invoking the back-end business logic
+10:54:30,122 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-25) [SERVICE] makeBooking called on backend resource.
+10:54:30,126 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) [CLIENT] rolling back Atomic Transaction (This will cause the AT and thus the enlisted back-end resources to rollback)
+10:54:30,349 INFO  [stdout] (TaskWorker-2) [SERVICE] one or more participants voted 'aborted' or a failure occurred, so coordinator tells the participant to rollback
+10:54:30,350 INFO  [stdout] (TaskWorker-2) [SERVICE] rollback called on backend resource.
+
+

Test commit:

+
10:54:30,662 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) Starting 'testCommit'. This test invokes a WS within an AT. The AT is later committed, which causes the back-end resource(s) to be committed.
+10:54:30,663 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) [CLIENT] Creating a new WS-AT User Transaction
+10:54:30,663 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) [CLIENT] Beginning Atomic Transaction (All calls to Web services that support WS-AT wil be included in this transaction)
+10:54:30,797 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) [CLIENT] invoking makeBooking() on WS
+10:54:30,848 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-66) [SERVICE] Restaurant service invoked to make a booking
+10:54:30,849 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-66) [SERVICE] Enlisting a Durable2PC participant into the AT
+10:54:30,936 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-66) [SERVICE] Invoking the back-end business logic
+10:54:30,937 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-66) [SERVICE] makeBooking called on backend resource.
+10:54:30,942 INFO  [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) [CLIENT] committing Atomic Transaction (This will cause the AT to complete successfully)
+10:54:31,046 INFO  [stdout] (TaskWorker-2) [SERVICE] Prepare called on participant, about to prepare the back-end resource
+10:54:31,046 INFO  [stdout] (TaskWorker-2) [SERVICE] prepare called on backend resource.
+10:54:31,047 INFO  [stdout] (TaskWorker-2) [SERVICE] back-end resource prepared, participant votes prepared
+10:54:31,067 WARN  [com.arjuna.wst] (TaskWorker-2) ARJUNA043219: Could not save recovery state for non-serializable durable WS-AT participant restaurantServiceAT:ba222c73-00c3-4ecc-921c-80fd5dfdc11a
+10:54:31,209 INFO  [stdout] (TaskWorker-2) [SERVICE] all participants voted 'prepared', so coordinator tells the participant to commit
+10:54:31,210 INFO  [stdout] (TaskWorker-2) [SERVICE] commit called on backend resource.
+
+

Note: You can ignore the warning message ARJUNA043219: Could not save recovery state for non-serializable durable WS-AT participant restaurantServiceAT that is printed in the server console. This quickstart does not implement the required recovery hooks in the interest of making it easy to follow. In a real world production application, you should provide the required recovery code. For more information, see http://narayana.io/docs/product.

+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart is more complex than the others. It requires that you configure the JBoss EAP server to use the standalone-xts.xml configuration file, which is located in an external configuration directory.

+
    +
  1. Import the quickstart into JBoss Developer Studio.
    2. +
  2. If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration. +
      +
    • In the Server tab, right-click and choose New --> Server.
      • +
    • Under Select the server type:, expand Red Hat JBoss Middleware and choose Red Hat JBoss Enterprise Application Platform 7.x.
      • +
    • For the Server name, enter JBoss EAP XTS Configuration and click Next.
      • +
    • In the Create a new Server Adapter dialog, choose Create a new runtime (next page) and click Next.
      • +
    • In the JBoss Runtime dialog, enter the following information and then click Finish. +
      Name: JBoss EAP XTS Runtime
+Home Directory: (Browse to the server directory and select it)
+Execution Environment: (Choose your runtime JRE if not correct)
+Configuration base directory: (This should already point to your server configuration directory)
+Configuration file: ../../docs/examples/configs/standalone-xts.xml
+
      +
      • +
    +
    3. +
  3. +

    Start the new JBoss EAP XTS Configuration server.

    +
    4. +
  4. Right-click on the wsat-simple project, choose Run As --> Maven build, enter clean verify -Parq-remote for the Goals:, and click Run to run the Arquillian tests. The test results appear in the console.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + + \ No newline at end of file diff --git a/wsat-simple/README.md b/wsat-simple/README.md index d837635b9f..6da0fb6e10 100644 --- a/wsat-simple/README.md +++ b/wsat-simple/README.md @@ -3,13 +3,13 @@ Author: Paul Robinson Level: Intermediate Technologies: WS-AT, JAX-WS -Summary: The `wsat-simple` quickstart demonstrates a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service, bundled as a WAR, and deployed to ${product.name}. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `wsat-simple` quickstart demonstrates a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service, bundled as a WAR, and deployed to JBoss EAP. +Target Product: JBoss EAP +Source: ## What is it? -The `wsat-simple` quickstart demonstrates the deployment of a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service bundled in a WAR archive for deployment to ${product.name.full}. +The `wsat-simple` quickstart demonstrates the deployment of a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service bundled in a WAR archive for deployment to Red Hat JBoss Enterprise Application Platform. The Web service is offered by a Restaurant for making bookings. The Service allows bookings to be made within an Atomic Transaction. @@ -42,9 +42,9 @@ There is another test that shows what happens if the client decides to rollback ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server with the Custom Options @@ -56,7 +56,7 @@ following logger block to the ./docs/examples/configs/standalone-xts.xml of your -Next you need to start ${product.name} with the XTS subsystem enabled. This is enabled through the optional server configuration *standalone-xts.xml*. To do this, run the following commands from the top-level directory of ${product.name}: +Next you need to start JBoss EAP with the XTS subsystem enabled. This is enabled through the optional server configuration *standalone-xts.xml*. To do this, run the following commands from the top-level directory of JBoss EAP: For Linux: ./bin/standalone.sh --server-config=../../docs/examples/configs/standalone-xts.xml For Windows: \bin\standalone.bat --server-config=..\..\docs\examples\configs\standalone-xts.xml @@ -66,7 +66,7 @@ Next you need to start ${product.name} with the XTS subsystem enabled. This is e This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: @@ -86,7 +86,7 @@ _Note: You see the following warning when you run the Arquillian tests in remote _This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the `serverConfig` property defined in the `arquillian.xml` file to start the server with the XTS subsystem enabled._ -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Server Log @@ -130,26 +130,26 @@ _Note: You can ignore the warning message `ARJUNA043219: Could not save recovery ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -This quickstart is more complex than the others. It requires that you configure the ${product.name} server to use the *standalone-xts.xml* configuration file, which is located in an external configuration directory. +This quickstart is more complex than the others. It requires that you configure the JBoss EAP server to use the *standalone-xts.xml* configuration file, which is located in an external configuration directory. 1. Import the quickstart into JBoss Developer Studio. -2. If you have not already done so, you must configure a new ${product.name} server to use the XTS configuration. +2. If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration. * In the `Server` tab, right-click and choose `New` --> `Server`. - * Under `Select the server type:`, expand `Red Hat JBoss Middleware` and choose `${jbds.eap.server.name}`. - * For the `Server name`, enter `${product.name} XTS Configuration` and click `Next`. + * Under `Select the server type:`, expand `Red Hat JBoss Middleware` and choose `Red Hat JBoss Enterprise Application Platform 7.x`. + * For the `Server name`, enter `JBoss EAP XTS Configuration` and click `Next`. * In the `Create a new Server Adapter` dialog, choose `Create a new runtime (next page)` and click `Next`. * In the `JBoss Runtime` dialog, enter the following information and then click `Finish`. - Name: ${product.name} XTS Runtime + Name: JBoss EAP XTS Runtime Home Directory: (Browse to the server directory and select it) Execution Environment: (Choose your runtime JRE if not correct) Configuration base directory: (This should already point to your server configuration directory) Configuration file: ../../docs/examples/configs/standalone-xts.xml -3. Start the new `${product.name} XTS Configuration` server. -4. Right-click on the `${project.artifactId}` project, choose `Run As` --> `Maven build`, enter `clean verify -Parq-remote` for the `Goals:`, and click `Run` to run the Arquillian tests. The test results appear in the console. +3. Start the new `JBoss EAP XTS Configuration` server. +4. Right-click on the `wsat-simple` project, choose `Run As` --> `Maven build`, enter `clean verify -Parq-remote` for the `Goals:`, and click `Run` to run the Arquillian tests. The test results appear in the console. ## Debug the Application diff --git a/wsat-simple/pom.xml b/wsat-simple/pom.xml index 0d2486aba0..112e45096a 100644 --- a/wsat-simple/pom.xml +++ b/wsat-simple/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml wsat-simple diff --git a/wsba-coordinator-completion-simple/README.html b/wsba-coordinator-completion-simple/README.html new file mode 100644 index 0000000000..5bb1ca577d --- /dev/null +++ b/wsba-coordinator-completion-simple/README.html @@ -0,0 +1,146 @@ + + + wsba-coordinator-completion-simple: Example of a WS-BA Enabled JAX-WS Web Service + + + +

wsba-coordinator-completion-simple: Example of a WS-BA Enabled JAX-WS Web Service

+

Author: Paul Robinson
+Level: Intermediate
+Technologies: WS-BA, JAX-WS
+Summary: The wsba-coordinator-completion-simple quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (CoordinatorCompletion protocol).
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The wsba-coordinator-completion-simple quickstart demonstrates the deployment of a WS-BA (WS Business Activity) enabled JAX-WS Web service bundled in a WAR archive (Participant Completion protocol) for deployment to Red Hat JBoss Enterprise Application Platform.

+

The Web service exposes a simple set collection as a service. The Service allows items to be added to the set within a Business Activity.

+

This example demonstrates the basics of implementing a WS-BA enabled Web service. It is beyond the scope of this quick start to demonstrate more advanced features. In particular:

+
    +
  • The Service does not implement the required hooks to support recovery in the presence of failures.
    • +
  • It also does not utilize a transactional back-end resource.
    • +
  • Only one web service participates in the protocol. As WS-BA is a coordination protocol, it is best suited to multi-participant scenarios.
    • +
+

For a more complete example, please see the XTS demonstrator application that ships with the Narayana project: http://narayana.io.

+

It is also assumed that you have an understanding of WS-BusinessActivity. For more details, read the XTS documentation that ships with the Narayana project: http://narayana.io/docs/product

+

The application consists of a single JAX-WS web service that is deployed within a WAR archive. It is tested with a JBoss Arquillian enabled JUnit test.

+

When running the org.jboss.as.quickstarts.wsba.coordinatorcompletion.simple.ClientTest#testSuccess() method, the following steps occur:

+
    +
  1. A new Business Activity is created by the client.
    2. +
  2. Multiple operations on a WS-BA enabled Web service is invoked by the client.
    3. +
  3. The JaxWSHeaderContextProcessor in the WS Client handler chain inserts the BA context into the outgoing SOAP messages.
    4. +
  4. When the service receives a SOAP request, the JaxWSHeaderContextProcessor in its handler chain inspects the BA context and associates the request with this BA.
    5. +
  5. The Web service operation is invoked.
    6. +
  6. For the first request, in this BA, A participant is enlisted in this BA. This allows the Web Service logic to respond to protocol events, such as compensate and close.
    7. +
  7. The service invokes the business logic. In this case, a String value is added to the set.
    8. +
  8. The client can then make additional calls to the SetService. As the SetService participates as a CoordinatorCompletion protocol, it will continue to accept calls to addValueToSet until it is told to complete by the coordinator.
    9. +
  9. The client can then decide to complete or cancel the BA. +
      +
    • If the client decides to complete, all participants will be told to complete. Providing all participants successfully complete, the coordinator will then tell all participants to close, otherwise the completed participants will be told to compensate.
      • +
    • If the participant decides to cancel, all participants will be told to compensate.
      • +
    +
    10. +
+

There is another test that shows how the client can cancel a BA.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server with the Custom Options

+

Next you need to start JBoss EAP with the XTS subsystem enabled. This is enabled through the optional server configuration standalone-xts.xml. To do this, run the following commands from the top-level directory of JBoss EAP:

+
For Linux:     ./bin/standalone.sh --server-config=../../docs/examples/configs/standalone-xts.xml | egrep "started|stdout"
+For Windows:   \bin\standalone.bat --server-config=..\..\docs\examples\configs\standalone-xts.xml | egrep "started|stdout"
+
+

Note, the pipe to egrep (| egrep "started|stdout") is useful to just show when the server has started and the output from these tests. For normal operation, this pipe can be removed.

+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
  4. +

    You should see the following result.

    +
    Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
    +
    5. +
+

Note: You see the following warning when you run the Arquillian tests in remote mode.

+
WARNING: Configuration contain properties not supported by the backing object org.jboss.as.arquillian.container.remote.RemoteContainerConfiguration
+Unused property entries: {serverConfig=../../docs/examples/configs/standalone-xts.xml}
+Supported property names: [managementAddress, password, managementPort, managementProtocol, username]
+
+

This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the serverConfig property defined in the arquillian.xml file to start the server with the XTS subsystem enabled.

+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Server Log

+

The following messages should appear in the server log. Note there may be other log messages interlaced between these. The messages trace the steps taken by the tests.

+

Test success:

+
16:24:19,191 INFO  [stdout] (management-handler-threads - 10) Starting 'testSuccess'. This test invokes a WS twice within a BA. The BA is later closes, which causes these WS calls to complete successfully.
+16:24:19,191 INFO  [stdout] (management-handler-threads - 10) [CLIENT] Creating a new Business Activity
+16:24:19,192 INFO  [stdout] (management-handler-threads - 10) [CLIENT] Beginning Business Activity (All calls to Web services that support WS-BA wil be included in this activity)
+16:24:19,216 INFO  [stdout] (management-handler-threads - 10) [CLIENT] invoking addValueToSet(1) on WS
+16:24:19,241 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] invoked addValueToSet('1')
+16:24:19,241 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Enlisting a participant into the BA
+16:24:19,281 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Invoking the back-end business logic
+16:24:19,283 INFO  [stdout] (management-handler-threads - 10) [CLIENT] invoking addValueToSet(2) on WS
+16:24:19,308 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] invoked addValueToSet('2')
+16:24:19,308 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Re-using the existing participant, already registered for this BA
+16:24:19,308 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Invoking the back-end business logic
+16:24:19,313 INFO  [stdout] (management-handler-threads - 10) [CLIENT] Closing Business Activity (This will cause the BA to complete successfully)
+16:24:19,419 INFO  [stdout] (TaskWorker-3) [SERVICE] Participant.complete (This tells the participant that the BA completed, but may be compensated later)
+16:24:19,498 INFO  [stdout] (TaskWorker-3) [SERVICE] Participant.confirmCompleted('true') (This tells the participant that compensation information has been logged and that it is safe to commit any changes.)
+16:24:19,498 INFO  [stdout] (TaskWorker-3) [SERVICE] Commit the backend resource (e.g. commit any changes to databases so that they are visible to others)
+16:24:19,543 INFO  [stdout] (TaskWorker-1) [SERVICE] Participant.close (The participant knows that this BA is now finished and can throw away any temporary state)
+
+

Test cancel:

+
16:24:19,616 INFO  [stdout] (management-handler-threads - 10) Starting 'testCancel'. This test invokes a WS twice within a BA. The BA is later cancelled, which causes these WS calls to be compensated.
+16:24:19,616 INFO  [stdout] (management-handler-threads - 10) [CLIENT] Creating a new Business Activity
+16:24:19,616 INFO  [stdout] (management-handler-threads - 10) [CLIENT] Beginning Business Activity (All calls to Web services that support WS-BA will be included in this activity)
+16:24:19,631 INFO  [stdout] (management-handler-threads - 10) [CLIENT] invoking addValueToSet(1) on WS
+16:24:19,653 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] invoked addValueToSet('1')
+16:24:19,653 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Enlisting a participant into the BA
+16:24:19,685 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Invoking the back-end business logic
+16:24:19,688 INFO  [stdout] (management-handler-threads - 10) [CLIENT] invoking addValueToSet(2) on WS
+16:24:19,713 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] invoked addValueToSet('2')
+16:24:19,713 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Re-using the existing participant, already registered for this BA
+16:24:19,713 INFO  [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Invoking the back-end business logic
+16:24:19,756 INFO  [stdout] (management-handler-threads - 10) [CLIENT] Cancelling Business Activity (This will cause the work to be compensated)
+16:24:19,815 INFO  [stdout] (TaskWorker-3) [SERVICE] Participant.cancel (The participant should compensate any work done within this BA)
+16:24:19,815 INFO  [stdout] (TaskWorker-3) [SERVICE] SetParticipantBA: Carrying out compensation action
+16:24:19,815 INFO  [stdout] (TaskWorker-3) [SERVICE] Compensate the backend resource by removing '1' from the set (e.g. undo any changes to databases that were previously made visible to others)
+16:24:19,816 INFO  [stdout] (TaskWorker-3) [SERVICE] Compensate the backend resource by removing '2' from the set (e.g. undo any changes to databases that were previously made visible to others)
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart is more complex than the others. It requires that you configure the JBoss EAP server to use the standalone-xts.xml configuration file, which is located in an external configuration directory.

+
    +
  1. Be sure to import the quickstart into JBoss Developer Studio.
    2. +
  2. If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration. +
      +
    • In the Server tab, right-click and choose New --> Server.
      • +
    • Under Select the server type:, expand Red Hat JBoss Middleware and choose Red Hat JBoss Enterprise Application Platform 7.x.
      • +
    • For the Server name, enter JBoss EAP XTS Configuration and click Next.
      • +
    • In the Create a new Server Adapter dialog, choose Create a new runtime (next page) and click Next.
      • +
    • In the JBoss Runtime dialog, enter the following information and then click Finish. +
      Name: JBoss EAP XTS Runtime
+Home Directory: (Browse to the server directory and select it)
+Execution Environment: (Choose your runtime JRE if not correct)
+Configuration base directory: (This should already point to your server configuration directory)
+Configuration file: ../../docs/examples/configs/standalone-xts.xml
+
      +
      • +
    +
    3. +
  3. +

    Start the new JBoss EAP XTS Configuration server.

    +
    4. +
  4. Right-click on the wsba-coordinator-completion-simple project, choose Run As --> Maven build, enter clean verify -Parq-remote for the Goals:, and click Run to run the Arquillian tests. The test results appear in the console.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/wsba-coordinator-completion-simple/README.md b/wsba-coordinator-completion-simple/README.md index a3c1ffd925..510106e8fc 100644 --- a/wsba-coordinator-completion-simple/README.md +++ b/wsba-coordinator-completion-simple/README.md @@ -4,12 +4,12 @@ Author: Paul Robinson Level: Intermediate Technologies: WS-BA, JAX-WS Summary: The `wsba-coordinator-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (CoordinatorCompletion protocol). -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `wsba-coordinator-completion-simple` quickstart demonstrates the deployment of a WS-BA (WS Business Activity) enabled JAX-WS Web service bundled in a WAR archive (Participant Completion protocol) for deployment to ${product.name.full}. +The `wsba-coordinator-completion-simple` quickstart demonstrates the deployment of a WS-BA (WS Business Activity) enabled JAX-WS Web service bundled in a WAR archive (Participant Completion protocol) for deployment to Red Hat JBoss Enterprise Application Platform. The Web service exposes a simple `set` collection as a service. The Service allows items to be added to the set within a Business Activity. @@ -44,14 +44,14 @@ There is another test that shows how the client can cancel a BA. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server with the Custom Options -Next you need to start ${product.name} with the XTS subsystem enabled. This is enabled through the optional server configuration *standalone-xts.xml*. To do this, run the following commands from the top-level directory of ${product.name}: +Next you need to start JBoss EAP with the XTS subsystem enabled. This is enabled through the optional server configuration *standalone-xts.xml*. To do this, run the following commands from the top-level directory of JBoss EAP: For Linux: ./bin/standalone.sh --server-config=../../docs/examples/configs/standalone-xts.xml | egrep "started|stdout" For Windows: \bin\standalone.bat --server-config=..\..\docs\examples\configs\standalone-xts.xml | egrep "started|stdout" @@ -64,7 +64,7 @@ Note, the pipe to egrep (| egrep "started|stdout") is useful to just show when t This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: @@ -84,7 +84,7 @@ _Note: You see the following warning when you run the Arquillian tests in remote _This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the `serverConfig` property defined in the `arquillian.xml` file to start the server with the XTS subsystem enabled._ -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Server Log @@ -132,26 +132,26 @@ Test cancel: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -This quickstart is more complex than the others. It requires that you configure the ${product.name} server to use the *standalone-xts.xml* configuration file, which is located in an external configuration directory. +This quickstart is more complex than the others. It requires that you configure the JBoss EAP server to use the *standalone-xts.xml* configuration file, which is located in an external configuration directory. 1. Be sure to import the quickstart into JBoss Developer Studio. -2. If you have not already done so, you must configure a new ${product.name} server to use the XTS configuration. +2. If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration. * In the `Server` tab, right-click and choose `New` --> `Server`. - * Under `Select the server type:`, expand `Red Hat JBoss Middleware` and choose `${jbds.eap.server.name}`. - * For the `Server name`, enter `${product.name} XTS Configuration` and click `Next`. + * Under `Select the server type:`, expand `Red Hat JBoss Middleware` and choose `Red Hat JBoss Enterprise Application Platform 7.x`. + * For the `Server name`, enter `JBoss EAP XTS Configuration` and click `Next`. * In the `Create a new Server Adapter` dialog, choose `Create a new runtime (next page)` and click `Next`. * In the `JBoss Runtime` dialog, enter the following information and then click `Finish`. - Name: ${product.name} XTS Runtime + Name: JBoss EAP XTS Runtime Home Directory: (Browse to the server directory and select it) Execution Environment: (Choose your runtime JRE if not correct) Configuration base directory: (This should already point to your server configuration directory) Configuration file: ../../docs/examples/configs/standalone-xts.xml -3. Start the new `${product.name} XTS Configuration` server. -4. Right-click on the `${project.artifactId}` project, choose `Run As` --> `Maven build`, enter `clean verify -Parq-remote` for the `Goals:`, and click `Run` to run the Arquillian tests. The test results appear in the console. +3. Start the new `JBoss EAP XTS Configuration` server. +4. Right-click on the `wsba-coordinator-completion-simple` project, choose `Run As` --> `Maven build`, enter `clean verify -Parq-remote` for the `Goals:`, and click `Run` to run the Arquillian tests. The test results appear in the console. ## Debug the Application diff --git a/wsba-coordinator-completion-simple/pom.xml b/wsba-coordinator-completion-simple/pom.xml index 8d43345ec3..e262b6b900 100644 --- a/wsba-coordinator-completion-simple/pom.xml +++ b/wsba-coordinator-completion-simple/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml wsba-coordinator-completion-simple diff --git a/wsba-participant-completion-simple/README.html b/wsba-participant-completion-simple/README.html new file mode 100644 index 0000000000..2c64b378d4 --- /dev/null +++ b/wsba-participant-completion-simple/README.html @@ -0,0 +1,137 @@ + + + wsba-participant-completion-simple: Deployment of a WS-BA enabled JAX-WS Web Service + + + +

wsba-participant-completion-simple: Deployment of a WS-BA enabled JAX-WS Web Service

+

Author: Paul Robinson
+Level: Intermediate
+Technologies: WS-BA, JAX-WS
+Summary: The wsba-participant-completion-simple quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (ParticipantCompletion Protocol).
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The wsba-participant-completion-simple quickstart demonstrates the deployment of a WS-BA (WS Business Activity) enabled JAX-WS Web service bundled in a WAR archive (ParticipantCompletion Protocol) for deployment to Red Hat JBoss Enterprise Application Platform.

+

The Web service exposes a simple 'set' collection as a service. The Service allows items to be added to the set within a Business Activity.

+

The example demonstrates the basics of implementing a WS-BA enabled Web service. It is beyond the scope of this quickstart to demonstrate more advanced features. In particular

+
    +
  • The Service does not implement the required hooks to support recovery in the presence of failures.
    • +
  • It also does not utilize a transactional back-end resource.
    • +
  • Only one web service participates in the protocol. As WS-BA is a coordination protocol, it is best suited to multi-participant scenarios.
    • +
+

For a more complete example, please see the XTS demonstrator application that ships with the Narayana project: http://narayana.io.

+

It is also assumed tht you have an understanding of WS-BusinessActivity. For more details, read the XTS documentation that ships with the Narayana project: http://narayana.io/docs/product

+

The application consists of a single JAX-WS web service that is deployed within a WAR archive. It is tested with a JBoss Arquillian enabled JUnit test.

+

When running the org.jboss.as.quickstarts.wsba.participantcompletion.simple.ClientTest#testSuccess() method, the following steps occur:

+
    +
  1. A new Business Activity is created by the client.
    2. +
  2. An operation on a WS-BA enabled Web service is invoked by the client.
    3. +
  3. The JaxWSHeaderContextProcessor in the WS Client handler chain inserts the BA context into the outgoing SOAP message.
    4. +
  4. When the service receives the SOAP request, the JaxWSHeaderContextProcessor in its handler chain inspects the BA context and associates the request with this BA.
    5. +
  5. The Web service operation is invoked.
    6. +
  6. A participant is enlisted in this BA. This allows the Web Service logic to respond to protocol events, such as compensate and close.
    7. +
  7. The service invokes the business logic. In this case, a String value is added to the set.
    8. +
  8. The backend resource is prepared. This ensures that the Backend resource can undo or make permanent the change when told to do so by the coordinator.
    9. +
  9. Providing the above steps where successful, the service notifies the coordinator that it has completed. The service has now made its changes visible and is not holding any locks. Allowing the service to notify completion is an optimisation that prevents the holding of locks, whilst waiting for other participants to complete. This notification is required as the Service participates in the ParticipantCompletion protocol.
    10. +
  10. The client can then decide to complete or cancel the BA. If the client decides to complete, all participants will be told to close. If the participant decides to cancel, all participants will be told to compensate.
    11. +
+

There are additional tests that show:

+
    +
  • What happens when an application exception is thrown by the service.
    • +
  • How the client can cancel a BA.
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Start the Server

+

Next you need to start JBoss EAP with the XTS subsystem enabled. This is enabled through the optional server configuration standalone-xts.xml. To do this, run the following commands from the top-level directory of JBoss EAP:

+
For Linux:     ./bin/standalone.sh --server-config=../../docs/examples/configs/standalone-xts.xml | egrep "started|stdout"
+For Windows:   \bin\standalone.bat --server-config=..\..\docs\examples\configs\standalone-xts.xml | egrep "started|stdout"
+
+

Note, the pipe to egrep (| egrep "started|stdout") is useful to just show when the server has started and the output from these tests. For normal operation, this pipe can be removed.

+

Run the Arquillian Tests

+

This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container.

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type the following command to run the test goal with the following profile activated: +
    mvn clean verify -Parq-remote
+
    +
    4. +
  4. +

    You should see the following result.

    +
    Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
    +
    5. +
+

Note: You see the following warning when you run the Arquillian tests in remote mode.

+
WARNING: Configuration contain properties not supported by the backing object org.jboss.as.arquillian.container.remote.RemoteContainerConfiguration
+Unused property entries: {serverConfig=../../docs/examples/configs/standalone-xts.xml}
+Supported property names: [managementAddress, password, managementPort, managementProtocol, username]
+
+

This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the serverConfig property defined in the arquillian.xml file to start the server with the XTS subsystem enabled.

+

You can also let Arquillian manage the JBoss EAP server by using the arq-managed profile. For more information about how to run the Arquillian tests, see Run the Arquillian Tests.

+

Investigate the Server Log

+

The following messages should appear in the server log. Note there may be other log messages interlaced between these. The messages trace the steps taken by the tests.

+

Test success:

+
INFO  [stdout] (management-handler-threads - 6) Starting 'testSuccess'. This test invokes a WS within a BA. The BA is later closed, which causes the WS call to complete successfully.
+INFO  [stdout] (management-handler-threads - 6) [CLIENT] Creating a new Business Activity
+INFO  [stdout] (management-handler-threads - 6) [CLIENT] Beginning Business Activity (All calls to Web services that support WS-BA wil be included in this activity)
+INFO  [stdout] (management-handler-threads - 6) [CLIENT] invoking addValueToSet(1) on WS
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] invoked addValueToSet('1')
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Enlisting a participant into the BA
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Invoking the back-end business logic
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Prepare the backend resource and if successful notify the coordinator that we have completed our work
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Prepare successful, notifying coordinator of completion
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Participant.confirmCompleted('true') (This tells the participant that compensation information has been logged and that it is safe to commit any changes.)
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Commit the backend resource (e.g. commit any changes to databases so that they are visible to others)
+INFO  [stdout] (management-handler-threads - 6) [CLIENT] Closing Business Activity (This will cause the BA to complete successfully)
+INFO  [stdout] (TaskWorker-2) [SERVICE] Participant.close (The participant knows that this BA is now finished and can throw away any temporary state)
+
+

Test cancel:

+
INFO  [stdout] (management-handler-threads - 5) Starting 'testCancel'. This test invokes a WS within a BA. The BA is later cancelled, which causes these WS call to be compensated.
+INFO  [stdout] (management-handler-threads - 5) [CLIENT] Creating a new Business Activity
+INFO  [stdout] (management-handler-threads - 5) [CLIENT] Beginning Business Activity (All calls to Web services that support WS-BA will be included in this activity)
+INFO  [stdout] (management-handler-threads - 5) [CLIENT] invoking addValueToSet(1) on WS
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] invoked addValueToSet('1')
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Enlisting a participant into the BA
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Invoking the back-end business logic
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Prepare the backend resource and if successful notify the coordinator that we have completed our work
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Prepare successful, notifying coordinator of completion
+INFO  [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Participant.confirmCompleted('true') (This tells the participant that compensation information has been logged and that it is safe to commit any changes.)
+
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

This quickstart is more complex than the others. It requires that you configure the JBoss EAP server to use the standalone-xts.xml configuration file, which is located in an external configuration directory.

+
    +
  1. Import the quickstart into JBoss Developer Studio.
    2. +
  2. If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration. +
      +
    • In the Server tab, right-click and choose New --> Server.
      • +
    • Under Select the server type:, expand Red Hat JBoss Middleware and choose Red Hat JBoss Enterprise Application Platform 7.x.
      • +
    • For the Server name, enter JBoss EAP XTS Configuration and click Next.
      • +
    • In the Create a new Server Adapter dialog, choose Create a new runtime (next page) and click Next.
      • +
    • In the JBoss Runtime dialog, enter the following information and then click Finish. +
      Name: JBoss EAP XTS Runtime
+Home Directory: (Browse to the server directory and select it)
+Execution Environment: (Choose your runtime JRE if not correct)
+Configuration base directory: (This should already point to your server configuration directory)
+Configuration file: ../../docs/examples/configs/standalone-xts.xml
+
      +
      • +
    +
    3. +
  3. +

    Start the new JBoss EAP XTS Configuration server.

    +
    4. +
  4. Right-click on the wsba-participant-completion-simple project, choose Run As --> Maven build, enter clean verify -Parq-remote for the Goals:, and click Run to run the Arquillian tests. The test results appear in the console.
    5. +
+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/wsba-participant-completion-simple/README.md b/wsba-participant-completion-simple/README.md index e4e7299cbb..ff77898192 100644 --- a/wsba-participant-completion-simple/README.md +++ b/wsba-participant-completion-simple/README.md @@ -4,12 +4,12 @@ Author: Paul Robinson Level: Intermediate Technologies: WS-BA, JAX-WS Summary: The `wsba-participant-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (ParticipantCompletion Protocol). -Target Product: ${product.name} -Source: <${github.repo.url}> +Target Product: JBoss EAP +Source: ## What is it? -The `wsba-participant-completion-simple` quickstart demonstrates the deployment of a WS-BA (WS Business Activity) enabled JAX-WS Web service bundled in a WAR archive (ParticipantCompletion Protocol) for deployment to ${product.name.full}. +The `wsba-participant-completion-simple` quickstart demonstrates the deployment of a WS-BA (WS Business Activity) enabled JAX-WS Web service bundled in a WAR archive (ParticipantCompletion Protocol) for deployment to Red Hat JBoss Enterprise Application Platform. The Web service exposes a simple 'set' collection as a service. The Service allows items to be added to the set within a Business Activity. @@ -49,14 +49,14 @@ There are additional tests that show: ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. ## Start the Server -Next you need to start ${product.name} with the XTS subsystem enabled. This is enabled through the optional server configuration *standalone-xts.xml*. To do this, run the following commands from the top-level directory of ${product.name}: +Next you need to start JBoss EAP with the XTS subsystem enabled. This is enabled through the optional server configuration *standalone-xts.xml*. To do this, run the following commands from the top-level directory of JBoss EAP: For Linux: ./bin/standalone.sh --server-config=../../docs/examples/configs/standalone-xts.xml | egrep "started|stdout" For Windows: \bin\standalone.bat --server-config=..\..\docs\examples\configs\standalone-xts.xml | egrep "started|stdout" @@ -69,7 +69,7 @@ Note, the pipe to egrep (| egrep "started|stdout") is useful to just show when t This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type the following command to run the test goal with the following profile activated: @@ -89,7 +89,7 @@ _Note: You see the following warning when you run the Arquillian tests in remote _This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the `serverConfig` property defined in the `arquillian.xml` file to start the server with the XTS subsystem enabled._ -You can also let Arquillian manage the ${product.name} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). +You can also let Arquillian manage the JBoss EAP server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). ## Investigate the Server Log @@ -130,26 +130,26 @@ Test cancel: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). -This quickstart is more complex than the others. It requires that you configure the ${product.name} server to use the *standalone-xts.xml* configuration file, which is located in an external configuration directory. +This quickstart is more complex than the others. It requires that you configure the JBoss EAP server to use the *standalone-xts.xml* configuration file, which is located in an external configuration directory. 1. Import the quickstart into JBoss Developer Studio. -2. If you have not already done so, you must configure a new ${product.name} server to use the XTS configuration. +2. If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration. * In the `Server` tab, right-click and choose `New` --> `Server`. - * Under `Select the server type:`, expand `Red Hat JBoss Middleware` and choose `${jbds.eap.server.name}`. - * For the `Server name`, enter `${product.name} XTS Configuration` and click `Next`. + * Under `Select the server type:`, expand `Red Hat JBoss Middleware` and choose `Red Hat JBoss Enterprise Application Platform 7.x`. + * For the `Server name`, enter `JBoss EAP XTS Configuration` and click `Next`. * In the `Create a new Server Adapter` dialog, choose `Create a new runtime (next page)` and click `Next`. * In the `JBoss Runtime` dialog, enter the following information and then click `Finish`. - Name: ${product.name} XTS Runtime + Name: JBoss EAP XTS Runtime Home Directory: (Browse to the server directory and select it) Execution Environment: (Choose your runtime JRE if not correct) Configuration base directory: (This should already point to your server configuration directory) Configuration file: ../../docs/examples/configs/standalone-xts.xml -3. Start the new `${product.name} XTS Configuration` server. -4. Right-click on the `${project.artifactId}` project, choose `Run As` --> `Maven build`, enter `clean verify -Parq-remote` for the `Goals:`, and click `Run` to run the Arquillian tests. The test results appear in the console. +3. Start the new `JBoss EAP XTS Configuration` server. +4. Right-click on the `wsba-participant-completion-simple` project, choose `Run As` --> `Maven build`, enter `clean verify -Parq-remote` for the `Goals:`, and click `Run` to run the Arquillian tests. The test results appear in the console. ## Debug the Application diff --git a/wsba-participant-completion-simple/pom.xml b/wsba-participant-completion-simple/pom.xml index 430bca036b..52088de233 100644 --- a/wsba-participant-completion-simple/pom.xml +++ b/wsba-participant-completion-simple/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml wsba-participant-completion-simple diff --git a/xml-dom4j/README.html b/xml-dom4j/README.html new file mode 100644 index 0000000000..27039d3904 --- /dev/null +++ b/xml-dom4j/README.html @@ -0,0 +1,61 @@ + + + xml-dom4j: Use a 3rd Party XML Parsing Library + + + +

xml-dom4j: Use a 3rd Party XML Parsing Library

+

Author: Bartosz Baranowski
+Level: Intermediate
+Technologies: DOM4J, Servlet, JSF
+Summary: The xml-dom4j quickstart demonstrates how to use Servlet and JSF to upload an XML file to JBoss EAP and parse it using a 3rd party XML parsing library.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The xml-dom4j quickstart is a simple DOM4J example that demonstrates how to use Servlet 3.0 and JSF to upload an XML file to Red Hat JBoss Enterprise Application Platform and parse it using a 3rd party XML parsing library.

+

It also shows how to include 3rd-party library in a deployment.

+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/xml-dom4j.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/xml-dom4j/.

+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/xml-dom4j/README.md b/xml-dom4j/README.md index ea776fe255..75af9cf8e2 100644 --- a/xml-dom4j/README.md +++ b/xml-dom4j/README.md @@ -3,56 +3,56 @@ Author: Bartosz Baranowski Level: Intermediate Technologies: DOM4J, Servlet, JSF -Summary: The `xml-dom4j` quickstart demonstrates how to use Servlet and JSF to upload an XML file to ${product.name} and parse it using a 3rd party XML parsing library. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `xml-dom4j` quickstart demonstrates how to use Servlet and JSF to upload an XML file to JBoss EAP and parse it using a 3rd party XML parsing library. +Target Product: JBoss EAP +Source: ## What is it? -The `xml-dom4j` quickstart is a simple DOM4J example that demonstrates how to use Servlet 3.0 and JSF to upload an XML file to *${product.name.full}* and parse it using a 3rd party XML parsing library. +The `xml-dom4j` quickstart is a simple DOM4J example that demonstrates how to use Servlet 3.0 and JSF to upload an XML file to *Red Hat JBoss Enterprise Application Platform* and parse it using a 3rd party XML parsing library. It also shows how to include 3rd-party library in a deployment. ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/xml-dom4j.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -61,7 +61,7 @@ The application will be running at the following URL: org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml xml-dom4j diff --git a/xml-jaxp/README.html b/xml-jaxp/README.html new file mode 100644 index 0000000000..60b92b1207 --- /dev/null +++ b/xml-jaxp/README.html @@ -0,0 +1,85 @@ + + + xml-jaxp: Upload and Parse an XML File Using DOM or SAX + + + +

xml-jaxp: Upload and Parse an XML File Using DOM or SAX

+

Author: Bartosz Baranowski
+Level: Intermediate
+Technologies: JAXP, SAX, DOM, Servlet
+Summary: The xml-jaxp quickstart demonstrates how to use Servlet and JSF to upload an XML file to JBoss EAP and validate and parse it using DOM or SAX.
+Target Product: JBoss EAP
+Source: https://github.com/jbossas/eap-quickstarts/

+

What is it?

+

The xml-jaxp quickstart is a simple Java EE JAXP example that demonstrates how to use Servlet 3.0 and JSF to upload an XML file to Red Hat JBoss Enterprise Application Platform and parse it using DOM or SAX, both of which are built into Java. It also shows how to use modules available in JBoss EAP.

+

This quickstart provides an example XML schema and document file to use when testing this quickstart.

+
    +
  • The XML schema is located here: QUICKSTART_HOME/src/main/resources/catalog.xsd
    • +
  • The XML document is located here: QUICKSTART_HOME/src/main/resources/catalog.xml
    • +
+

System Requirements

+

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later.

+

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See Configure Maven for JBoss EAP 7.1 to make sure you are configured correctly for testing the quickstarts.

+

Use of EAP7_HOME

+

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

+

Start the Server

+
    +
  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
    2. +
  2. The following shows the command line to start the server: +
    For Linux:   EAP7_HOME/bin/standalone.sh
+For Windows: EAP7_HOME\bin\standalone.bat
+
    +
    3. +
+

Build and Deploy the Quickstart

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. Type this command to build and deploy the archive: +
    mvn clean install wildfly:deploy
+
    +
    4. +
  4. +

    This will deploy target/xml-jaxp.war to the running instance of the server.

    +
    5. +
+

Access the Application

+

The application will be running at the following URL: http://localhost:8080/xml-jaxp/.

+

To test the quickstart, follow these steps.

+
    +
  1. Click the Browse button and navigate to the QUICKSTART_HOME/src/main/resources/catalog.xml file.
    2. +
  2. Click the Upload button. The XML file content is parsed and displayed on the page.
    3. +
  3. You should see the following output in the server console that shows the DOMXMLParser was used: +
    INFO  [stdout] (http-/127.0.0.1:8080-1) Parsing the document using the DOMXMLParser!
+
    +
    4. +
+

To enable the alternative SAXXMLParser parser:

+
    +
  1. Remove the comments that surround the alternate parser element in the WEB-INF/beans.xml file.
    2. +
  2. Redeploy the application using the instructions above and access the application in a browser at the following URL: http://localhost:8080/xml-jaxp/.
    3. +
  3. Click the Browse button and navigate to the QUICKSTART_HOME/src/main/resources/catalog.xml file.
    4. +
  4. Click the Upload button. The XML file content is parsed and displayed on the page.
    5. +
  5. You should now see following output in the server console: +
    INFO  [stdout] (http-/127.0.0.1:8080-1) Parsing the document using the SAXXMLParser!
+
    +
    6. +
+

Undeploy the Archive

+
    +
  1. Make sure you have started the JBoss EAP server as described above.
    2. +
  2. Open a command prompt and navigate to the root directory of this quickstart.
    3. +
  3. When you are finished testing, type this command to undeploy the archive: +
    mvn wildfly:undeploy
+
    +
    4. +
+

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

+

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.

+

Debug the Application

+

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

+
    mvn dependency:sources
+
+ + \ No newline at end of file diff --git a/xml-jaxp/README.md b/xml-jaxp/README.md index 821b8282d5..98bf010c7a 100644 --- a/xml-jaxp/README.md +++ b/xml-jaxp/README.md @@ -3,14 +3,14 @@ Author: Bartosz Baranowski Level: Intermediate Technologies: JAXP, SAX, DOM, Servlet -Summary: The `xml-jaxp` quickstart demonstrates how to use Servlet and JSF to upload an XML file to ${product.name} and validate and parse it using DOM or SAX. -Target Product: ${product.name} -Source: <${github.repo.url}> +Summary: The `xml-jaxp` quickstart demonstrates how to use Servlet and JSF to upload an XML file to JBoss EAP and validate and parse it using DOM or SAX. +Target Product: JBoss EAP +Source: ## What is it? -The `xml-jaxp` quickstart is a simple Java EE JAXP example that demonstrates how to use Servlet 3.0 and JSF to upload an XML file to *${product.name.full}* and parse it using DOM or SAX, both of which are built into Java. It also shows how to use modules available in ${product.name}. +The `xml-jaxp` quickstart is a simple Java EE JAXP example that demonstrates how to use Servlet 3.0 and JSF to upload an XML file to *Red Hat JBoss Enterprise Application Platform* and parse it using DOM or SAX, both of which are built into Java. It also shows how to use modules available in JBoss EAP. This quickstart provides an example XML schema and document file to use when testing this quickstart. @@ -20,39 +20,39 @@ This quickstart provides an example XML schema and document file to use when tes ## System Requirements -The application this project produces is designed to be run on ${product.name.full} ${product.version} or later. +The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7.1 or later. -All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later. See [Configure Maven for JBoss EAP 7.1](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. -## Use of ${jboss.home.name} +## Use of EAP7_HOME -In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables). +In the following instructions, replace `EAP7_HOME` with the actual path to your JBoss EAP installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-eap_home-and-jboss_home-variables). ## Start the Server -1. Open a command prompt and navigate to the root of the ${product.name} directory. +1. Open a command prompt and navigate to the root of the JBoss EAP directory. 2. The following shows the command line to start the server: - For Linux: ${jboss.home.name}/bin/standalone.sh - For Windows: ${jboss.home.name}\bin\standalone.bat + For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat ## Build and Deploy the Quickstart -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. Type this command to build and deploy the archive: mvn clean install wildfly:deploy -4. This will deploy `target/${project.artifactId}.war` to the running instance of the server. +4. This will deploy `target/xml-jaxp.war` to the running instance of the server. ## Access the Application -The application will be running at the following URL: . +The application will be running at the following URL: . To test the quickstart, follow these steps. @@ -65,7 +65,7 @@ To test the quickstart, follow these steps. To enable the alternative SAXXMLParser parser: 1. Remove the comments that surround the alternate parser element in the `WEB-INF/beans.xml` file. -2. Redeploy the application using the instructions above and access the application in a browser at the following URL: . +2. Redeploy the application using the instructions above and access the application in a browser at the following URL: . 3. Click the `Browse` button and navigate to the `QUICKSTART_HOME/src/main/resources/catalog.xml` file. 4. Click the `Upload` button. The XML file content is parsed and displayed on the page. 5. You should now see following output in the server console: @@ -75,7 +75,7 @@ To enable the alternative SAXXMLParser parser: ## Undeploy the Archive -1. Make sure you have started the ${product.name} server as described above. +1. Make sure you have started the JBoss EAP server as described above. 2. Open a command prompt and navigate to the root directory of this quickstart. 3. When you are finished testing, type this command to undeploy the archive: @@ -84,7 +84,7 @@ To enable the alternative SAXXMLParser parser: ## Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}). +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts). ## Debug the Application diff --git a/xml-jaxp/pom.xml b/xml-jaxp/pom.xml index 531c9bbadb..61c8dc4ceb 100644 --- a/xml-jaxp/pom.xml +++ b/xml-jaxp/pom.xml @@ -21,7 +21,7 @@ org.jboss.eap.quickstarts quickstart-parent - 7.1.0.CR3-SNAPSHOT + 7.1.0.GA ../pom.xml xml-jaxp