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:
+-
+
-
+
Add the other repo as a remote
+
+git remote add -f <other repo> <other repo url> +
+ -
+
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>'" +
+ -
+
Review and push to upstream
+
+git push upstream HEAD:master +
+
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
+-
+
- 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/ +
- You must provide a property
gpg.passphrasein yoursettings.xmlin thereleaseprofile e.g. +
+<profile> + <id>release</id> + <properties> + <gpg.passphrase>myPassPhrase</gpg.passphrase> + </properties> + </profile> +
+ - You must have a JBoss Nexus account, configured with the server id in
settings.xmlwith the idjboss-releases-repositorye.g. +
+<server> + <id>jboss-releases-repository</id> + <username>myUserName</username> + <password>myPassword</password> + </server> +
+ -
+
Add
+org.sonatype.pluginsplug-in group to yoursettings.xmlso the Nexus plug-in can be available for publishing scripts.
+<pluginGroups> + <pluginGroup>org.sonatype.plugins</pluginGroup> + </pluginGroups> +
+
Release Procedure
+-
+
- Make sure you have access to rsync files to
filemgmt.jboss.org/download_htdocs/jbossas
+ - Release the archetypes +
- Regenerate the quickstart based on archetypes
+
+dist/release-utils.sh -r +
+ -
+
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.
+
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build the artifacts:
+
+mvn clean install wildfly:deploy +
+
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.
+-
+
- Be sure the quickstart deployed successfully as described above. +
- Navigate to the root directory of this quickstart and type the following command to run the application. Be sure to replace
EAP7_HOMEwith 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 +
+ -
+
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
+ServerApplicationis called at the jboss.nodemyhost. The application client connected automatically a server on the same machine.
+ -
+
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} +
+
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)
+-
+
- Install JBoss EAP on this machine. +
- Add the application users to the JBoss EAP server on this machine as described above. +
- Start the JBoss EAP server with the following command. Be sure to replace
MACHINE_1_IP_ADDRESSwith 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 +
+
Configure Machine_2 (Local Client Machine)
+-
+
- Install JBoss EAP on this server. There is no need to add the application users to this server. +
- Download the
app-clientquickstart to this machine.
+ - Create a
jboss-ejb-client.propertiesfile. 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, replacingMACHINE_1_IP_ADDRESSwith the IP address ofMachine_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 +
+ -
+
Open a command prompt and navigate to the root directory of the quickstart.
+
+ - Deploy the
app-clientquickstart 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 +
+ - Be sure that the quickstart deployed successfully and the server is running on
Machine_1as described above.
+ - Type this command to run the
app-clientapplication: +
+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 +
+ -
+
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
+ServerApplicationis called at the jboss.nodetheOtherHOST.
+ -
+
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.propertiesfile.
+
Undeploy the Archive from the Local Machine
+Follow these instructions if you are testing the quickstart on the same machine.
+-
+
- Make sure you have started the JBoss EAP server on the machine where the quickstart is deployed as described above. +
- Open a command prompt on that server and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive from the local machine.
+
+mvn wildfly:undeploy +
+
Undeploy the Archive from the Remote Machine
+Follow these instructions if you are testing the quickstart on a different machine.
+-
+
- Make sure you have started the JBoss EAP server on the remote server machine,
Machine_1, where the quickstart is deployed as described above.
+ - Open a command prompt on the local client machine,
Machine_2, and navigate to the root directory of this quickstart.
+ - 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 +
+
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):
+-
+
- Import the file (Chunk oriented) - The chunk size was set to
3. TheRecordsReaderis responsible for parsing the file and create an instance ofContact. TheContactsFormatterapplies the proper case to the Contact name and it also applies a mask to the phone number. Finally,ContactsPersisterwill send the Contact instance to the Database.
+ - Log the number of records imported +
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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ - This will deploy
target/batch-processing.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/bmt.warto the running instance of the server.
+
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.
+-
+
- To list all pairs leave the key input box empty. +
- To add or update the value of a key fill in the key and value input boxes. +
- Press the submit button to see the results. +
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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 extendsHttpServletand handles the incoming servlet request. It gets the tax rate and returns it to the page.
+Tax: This interface defines thegetRate()method to get the tax rate.
+TaxImpl_1: This is the default class that returns theTax_1rate.
+TaxImpl_2: This is an alternative class that returns theTax_2rate. Note the@Alternativeannotation in the class.
+WEB-INF/beans.xml: This file specifies theTaxImpl_2alternative should be used by the quickstart. To use the defaultTaxImpl_1class, 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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This deploys
+target/cdi-alternative.warto the running instance of the server.
+
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:
-
+
- You can remove the
<alternatives>tag so that it defaults to useTaxImpl_1.
+ - You can create another alternative bean class and use that class name as an alternative. +
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/cdi-decorator.warto the running instance of the server.
+
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:
-
+
- You can add a decorators tag and specify a decorator class. +
- You can specify a different decorator class name in the decorators tag. +
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/cdi-injection.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL http://localhost:8080/cdi-injection/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/cdi-interceptors.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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 implementsExtension. 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 InjectionTargetto add the field values from the XML file.
+CreatureType: An enum in themodelpackage. It defines the two types of creatures,MONSTERandNPC.
+Creature: The interface in themodelpackage. Defines the name and type of creature.
+Monster: Class in themodelpackage that implments creature with a typeMONSTER.
+NonPlayerCharacter: Class in themodelpackage that implements creature with a typeNPC.
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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:
@Loggingand@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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/cdi-stereotype.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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:
+-
+
- XA transaction control using the container managed transaction annotations +
- XA access to the standard default datasource using the JPA API +
- XA access to a JMS queue +
After users complete this quickstart, they are invited to run through the following quickstarts:
+-
+
- jts - The JTS quickstart builds upon this quickstart by distributing the CustomerManager and InvoiceManager +
- jts-distributed-crash-rec - The crash recovery quickstart builds upon the jts quickstart by demonstrating the fault tolerance of JBoss EAP. +
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/cmt.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This deploys
+target/contacts-jquerymobile.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 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
+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'}
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ - This will deploy
ejb/target/ejb-asynchronous-ejb.jarto the running instance of the server.
+
Check whether the application is deployed successfully.
+Access the Application
+-
+
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to start the client
+
+cd client +mvn exec:exec +Note: This quickstart requires
+quickstart-parentartifact 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 +
+ -
+
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] +
+ -
+
Check the server log.
+There should be two INFO log messages for the
+fireAndForgetinvocation:
+'fireAndForget' Will wait for 15000ms +and 15sec later (the client should be finished at this time)
+
+action 'fireAndForget' finished +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Install the required Maven artifacts and deploy the asynchronous EJB quickstart project.
+
-
+
- Right-click on the
ejb-asynchronous-ejbproject and chooseRun As-->Maven Install.
+ - Right-click on the
ejb-asynchronous-ejbproject and chooseRun As-->Run on Server.
+
+ - Right-click on the
- Build and run the client side of the quickstart project.
+
-
+
- Right-click on the
ejb-asynchronous-clientproject and chooseRun As-->Java Application.
+ - In the
Select Java Applicationwindow, chooseAsynchronousClient - org.jboss.as.quickstarts.ejb.asynchronous.clientand clickOK.
+ - The client output displays in the
Consolewindow.
+
+ - Right-click on the
- To undeploy the project, right-click on the
ejb-asynchronous-ejbproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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:
+-
+
-
+
+ejb: This project contains the EJB code and can be built independently to produce the JAR archive.
+ -
+
+web: This project contains the JSF pages and the managed bean.
+ -
+
+ear: This project builds the EAR artifact and pulls in the EJB and Web artifacts.
+
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:
+-
+
- A JSF page asks the user for their name. +
- On clicking Greet, the name is sent to a managed bean named
Greeter.
+ - On setting the name, the
Greeterinvokes theGreeterEJB, which was injected to the managed bean. Notice the field annotated with@EJB.
+ - The response from invoking the
GreeterEJBis stored in a field (message) of the managed bean.
+ - 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.
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+ear/target/ejb-in-ear.earto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Right-click on the
ejb-in-ear-earsubproject, and chooseRun As-->Run on Server.
+ - Choose the server and click
Finish.
+ - This starts the server, deploys the application, and opens a browser window that accesses the running application. +
- To undeploy the project, right-click on the
ejb-in-ear-earproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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:
+-
+
- A JSF page asks the user for their name. +
- On clicking submit, the name is sent to a managed bean named
Greeter.
+ - On setting the name, the
Greeterinvokes theGreeterEJB, which was injected into the managed bean. Notice the field annotated with@EJB.
+ - The response from invoking the
GreeterEJBis stored in a fieldmessageof the managed bean.
+ - 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.
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/ejb-in-war.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL http://localhost:8080/ejb-in-war/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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.
+-
+
- If it is running, stop the JBoss EAP server. +
- 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 +
+ - After you have completed testing and undeployed this quickstart, you can replace these files to restore the server to its original configuration. +
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.
-
+
-
+
Start with a fresh instance of the JBoss EAP as noted above under Start with a Clean JBoss EAP Install.
+
+ -
+
Be sure you add the required users as specified above under Add the Application Users.
+
+ -
+
Before you begin, make sure you followed the instructions above under Back Up the JBoss EAP Server Configuration Files.
+
+ - 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 +
+
+ - Review the
install-domain.clifile in the root of this quickstart directory. This script configures and starts multiple servers needed to run this quickstart.
+ -
+
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"} +
+
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
+-
+
- Make sure you have started and configured the JBoss EAP server successfully as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build the artifacts:
+
+mvn clean install +
+
You should see BUILD SUCCESS at the end of the build SUCCESS messages for each component.
-
+
- 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-*.earfiles 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) +
+
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.
+-
+
- Make sure that the deployments are successful as described above. +
- Navigate to the quickstart
client/subdirectory.
+ - 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
+MainAppis called with the useranonymousat nodemaster:app-mainand the sub-call is proceeded by themaster:app-oneAnode andmaster:app-twoAnode asquickuser2.Review the server log files to see the bean invocations on the servers.
+Note: This quickstart requires
+quickstart-parentartifact 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 +
+ -
+
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 +
+
NOTE:
+-
+
- If exec is called multiple times, the invocation for
app1might useapp-oneAandapp-oneBnode due to cluster loadbalancing.
+ - A JBoss EAP will deny the invocation of unsecured methods of
appOne/appTwosince security is enabled but the method does not include @Roles. You need to setdefault-missing-method-permissions-deny-access = falsefor theejb3subsystem within the domain profilehaanddefaultto allow the method invocation. See theinstall-domain.cliscript.
+
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.
+-
+
- Make sure that the deployments are successful as described above. +
- Use a browser to access the JSF application at the following URL: http://localhost:8080/ejb-multi-server-app-main-web/ +
- Insert a message in the Text input and invoke the different methods. The result is shown in the browser. +
- See server logfiles and find your given message logged as INFO. +
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.
+-
+
- Make sure that the deployments are successful as described above. +
- Use a browser to access the Servlet at the following URL: http://localhost:8380/ejb-multi-server-app-web/ +
- The Servlet will invoke the remote EJBs directly and show the results, compare that the invocation is successful +
Undeploy the Archives
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 +
+
Remove the Server Domain Configuration
+-
+
- If it is running, stop the JBoss EAP server. +
- Restore the
EAP7_HOME/domain/configuration/domain.xmlandEAP7_HOME/domain/configuration/host.xmlfiles 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
+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
+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:
+-
+
- 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.
+
+ - 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.
+
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+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.
+-
+
- Make sure you have started the JBoss EAP server. See the instructions in the previous section. +
- Open a command prompt and navigate to the ejb-remote quickstart directory +
- 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 +
+
+ - Build the EJB and client interfaces JARs and install them in your local Maven repository.
+
- 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-parentartifact 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 +
+ - Navigate to the client subdirectory:
+
Investigate the Console Output
+When the client application runs, it performs the following steps:
+-
+
- Obtains a stateless session bean instance. +
- Sends method invocations to the stateless bean to add two numbers, and then displays the result. +
- Sends a second invocation to the stateless bean subtract two numbers, and then displays the result. +
- Obtains a stateful session bean instance. +
- Sends several method invocations to the stateful bean to increment a field in the bean, displaying the result each time. +
- Sends several method invocations to the stateful bean to decrement a field in the bean, displaying the result each time. +
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.
+-
+
- Open a command prompt and navigate to the ejb-remote/client quickstart directory
+
+cd client +
+ - Type the following in the command line:
+
+mvn clean package assembly:single +
+ -
+
You can then run the executable JAR using the
+java -jarcommand. You will see the same console output as above.
+java -jar target/ejb-remote-client-jar-with-dependencies.jar +
+
Undeploy the Archive
+To undeploy the server-side component from the JBoss EAP server:
+-
+
- Navigate to the server-side subdirectory:
+
+cd ../server-side +
+ - Type the following command:
+
+mvn wildfly:undeploy +
+
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.
+-
+
-
+
Install the required Maven artifacts and deploy the server side of the quickstart project.
+-
+
- Right-click on the
ejb-remote-server-sideproject and chooseRun As-->Maven Install.
+ - Right-click on the
ejb-remote-server-sideproject and chooseRun As-->Run on Server.
+
+ - Right-click on the
-
+
Build and run the client side of the quickstart project.
+-
+
- Right-click on the
ejb-remote-clientproject and chooseRun As-->Java Application.
+ - In the
Select Java Applicationwindow, chooseRemoteEJBClient - org.jboss.as.quickstarts.ejb.remote.clientand clickOK.
+ - The client output displays in the
Consolewindow.
+
+ - Right-click on the
-
+
To undeploy the project, right-click on the
+ejb-remote-server-sideproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-elytron.clifile 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.
+ -
+
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 +
+ -
+
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 +
+ - 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
application-security-domainwas added to theejb3subsystem: +
+<application-security-domains> + <application-security-domain name="quickstart-domain" security-domain="ApplicationDomain"/> +</application-security-domains> +The
+application-security-domainessentially enables Elytron security for the quickstart EJBs. It maps thequickstart-domainthat was set in the EJBs via annotation to the ElytronApplicationDomainthat will be responsible for authenticating and authorizing access to the EJBs.
+ - The following
ejb-outbound-configurationauthentication configuration andejb-outbound-contextauthentication context were added to theelytronsubsystem: +
+<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-configurationcontains the authentication configuration that will be used when invoking a method on a remote EJB, for example whenIntermediateEJBcalls the methods on theSecuredEJB. The above configuration specifies that the identity that is currently authenticated to theApplicationDomainwill be used to establish the connection to the remote EJB. Thesasl-mechanism-selectordefines the SASL mechanisms that should be tried. In this quickstart thePLAINmechanism has been chosen because other challenge-response mechanisms such asDIGEST-MD5can't provide the original credential to establish the connection to the remote EJB.The
+ejb-outbound-contextis the authentication context that is used by the remote outbound connection and it automatically selects theejb-outbound-configuration.
+ -
+
The following
+ejb-outboundoutbound-socket-binding connection was created within thestandard-socketssocket-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.
+
+ - The following
ejb-outbound-connectionremote-outbound-connection was added to the outbound-connections within theremotingsubsytem: +
+<outbound-connections> + <remote-outbound-connection name="ejb-outbound-connection" outbound-socket-binding-ref="ejb-outbound" authentication-context="ejb-outbound-context"/> +</outbound-connections> +
+ - The
http-connectorin theremotingsubsystem was updated to use theapplication-sasl-authenticationauthentication 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"/> +
+ -
+
Finally, the
+application-sasl-authenticationfactory was updated in theelytronsubsystem to include thePLAINmechanism:
+<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> +
+ -
+
If you chose to run the script to suppress system exceptions, you should see the following configuration in the
+ejb3subsystem.
+<log-system-exceptions value="false"/> +
+
Start the Server
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+target/ejb-security-context-propagation.jarto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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,elytronandremotingsubsystems. You should see the following result when you run the script:
+The batch executed successfully +process-state: reload-required +
+ - 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 +
+
Restore the Server Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile 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 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.
+-
+
- Be sure to Add the Application Users as described above. +
- Follow the steps above to 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-context-propagationproject and chooseRun As-->Run on Server.
+ - To access the application, right-click on the
ejb-security-context-propagationproject and chooseRun As-->Java Application.
+ - Choose
RemoteClient - org.jboss.as.quickstarts.ejb_security_context_propagationand clickOK.
+ - Review the output in the console window. +
- To undeploy the project, right-click on the
ejb-security-context-propagationproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+ - 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
+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:
+-
+
- A client side interceptor to pass the requested identity to the remote server. +
- A server side interceptor to receive the identity and request that the call switches to that identity. +
- A JAAS LoginModule to decide if the user of the connection is allowed to execute requests as the specified identity. +
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.EJBClientInterceptorfile 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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-security-domain.clifile in the root of this quickstart directory. This script adds thequickstart-domainsecurity domain to thesecuritysubsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.
+ -
+
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 +
+ - 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 +
+ - 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
quickstart-domainsecurity-domain was added to thesecuritysubsystem. +
+<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 theApplicationRealm. TheDelegationLoginModuleis used to support identity switching in this quickstart.The login module can either be added before or after the existing
+Remotinglogin module in the domain, but it MUST be somewhere before the existingRealmDirectlogin 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 theRemotinglogin module first and this one second.The login module loads the properties file
+delegation-mapping.propertiesfrom the deployment. The location of this properties file can be overridden with the module-optiondelegationProperties. 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
+DelegationLoginModulecan 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.
+
+ - The following
ejb-outbound-realmsecurity-realm was added to themanagementsecurity-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> +
+ - The following
ejb-outboundoutbound-socket-binding connection was created within thestandard-socketssocket-binding-group: +
+<outbound-socket-binding name="ejb-outbound"> + <remote-destination host="localhost" port="8080"/> +</outbound-socket-binding> +
+ - The following
ejb-outbound-connectionremote-outbound-connection was added to the outbound-connections within theremotingsubsytem: +
+<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> +
+ - If you chose to run the script to suppress system exceptions, you should see the following configuration in the
ejb3subsystem. +
+<log-system-exceptions value="false"/> +
+
Start the Server
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/ejb-security-interceptors.jarto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- 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
+testqueue from themessagingsubsystem in the server configuration. You should see the following result when you run the script:
+The batch executed successfully +process-state: reload-required +
+ - 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 +
+
Restore the Original Server Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile 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 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.
+-
+
- Be sure to Add the Application Users as described above. +
- Follow the steps above to 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-interceptorsproject and chooseRun As-->Run on Server.
+ - To access the application, right-click on the
ejb-security-interceptorsproject and chooseRun As-->Java Application.
+ - Choose
RemoteClient - org.jboss.as.quickstarts.ejb_security_interceptorsand clickOK.
+ - Review the output in the console window. +
- To undeploy the project, right-click on the
ejb-security-interceptorsproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+ - Be sure to Restore the Original 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
+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
+-
+
- Open a command line and navigate to the JBoss EAP server
configurationdirectory: +
+For Linux: EAP7_HOME/standalone/configuration +For Windows: EAP7_HOME\standalone\configuration +
+ - Create a file named
users.propertiesand add the following username/password pair: +
+quickstartUser=quickstartPwd1! +
+ - Create a file named
roles.propertiesand add the following username/roles pair: +
+quickstartUser=guest +This concludes the configuration required by the legacy
+JAASlogin module used in this quickstart.
+
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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-elytron-jaas.clifile 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.
+ -
+
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 +
+ - 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
+security-domainwas added to the legacysecuritysubsystem:
+<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. TheRemotinglogin module is added to properly authenticate requests made from remote clients. Amapping-moduleis 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.
+ -
+
The following
+elytron-realmwas added to the legacysecuritysubsystem:
+<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
+securitysubsystem to export anElytron-compatible realm calledLegacyRealmthat will delegate authentication and authorization decisions to the legacyquickstart-domain. Setting theapply-role-mappersattribute tofalseindicates to the exported realm that it should not use any role mappers defined in the legacy security domain.
+ -
+
The following
+security-domainwas added to theelytronsubsystem:
+<security-domain name="LegacyDomain" default-realm="LegacyRealm" permission-mapper="default-permission-mapper" security-event-listener="local-audit"> + <realm name="LegacyRealm"/> +</security-domain> +
+ -
+
The following
+http-authentication-factorywas added to theelytronsubsystem:
+<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.
+
+ -
+
The following
+application-security-domainmapping was added to theundertowsubsystem:
+<application-security-domains> + <application-security-domain name="legacy-domain" http-authentication-factory="quickstart-http-authentication"/> +</application-security-domains> +It tells
+Undertowto use the HTTP authentication factory created in step 4 for web applications that specify the security domainlegacy-domainin their metadata. The quickstart application specifies this domain both for the web layer, in thejboss-web.xmlfile, and the EJB component, using annotation in the code.
+ -
+
The following
+sasl-authentication-factorywas added to theelytronsubsystem:
+<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> +
+ -
+
The
+http-remoting-connectorin theremotingsubsystem was updated to use thesasl-authentication-factorycreated 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.
+
+ -
+
Finally, the following
+application-security-domainmapping was added to theejb3subsystem:
+<application-security-domains> + <application-security-domain name="legacy-domain" security-domain="LegacyDomain"/> +</application-security-domains> +This mapping basically enables
+Elytronsecurity for EJB3 applications that specify the security domainlegacy-domainin their metadata (either via jboss-ejb3.xml or annotations). The quickstart application uses the@SecurityDomainannotation in the bean class to specify this security domain.
+
Start the Server
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/ejb-security-jaas.warto the running instance of the server.
+
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.
+-
+
- 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. +
- 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 +
+ -
+
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 + + + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +
+ -
+
Next, change the exported realm so that it now uses the legacy role mappers as defined in the legacy
+JAASsecurity 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" + } +} +
+ -
+
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 theadminrole that was provided by the legacy role mapper:
+Successfully called Secured EJB + +Principal : quickstartUser +Remote User : quickstartUser +Has admin permission : true +Authentication Type : BASIC +
+ -
+
The same result can be observed when re-running the remote client application:
+
+* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + + + Called secured bean, caller principal quickstartUser + + Principal has admin permission: true + + + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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,securityandundertowsubsystems. You should see the following result when you run the script:
+The batch executed successfully +process-state: reload-required +
+
Restore the Server Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile 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 (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-jaasproject and chooseRun 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 permissionisfalse.
+ - 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.cliscript as described above under Access the Application.
+ - Go back to JBoss Developer Studio and click
Refresh the current page. Note thatHas admin permissionis nowtrue.
+ - To undeploy the project, right-click on the
ejb-security-jaasproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+ - 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
+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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-elytron.clifile 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.
+ -
+
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 +
+ - 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
+application-security-domainmapping was added to theejb3subsystem:
+<application-security-domains> + <application-security-domain name="quickstart-domain" security-domain="ApplicationDomain"/> +</application-security-domains> +The
+application-security-domainessentially enables Elytron security for the quickstart EJBs. It maps thequickstart-domainthat was set in the EJBs via annotation to the ElytronApplicationDomainthat will be responsible for authenticating and authorizing access to the EJBs.
+ -
+
The
+http-connectorin theremotingsubsystem was updated to use theapplication-sasl-authenticationauthentication 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.
+
+
Start the Server
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+target/ejb-security-programmatic-auth.jarto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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
+ejb3andremotingsubsystems. You should see the following result when you run the script:
+The batch executed successfully +process-state: reload-required +
+
Restore the Server Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile 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 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-authproject and chooseRun As-->Maven build. Enterclean package wildfly:deployfor theGoals:and clickRun. This deploys theejb-security-programmatic-authJAR to the JBoss EAP server.
+ - Right-click on the
ejb-security-programmatic-authproject and chooseRun As-->Run Configurations....
+ - Enter
exec:execfor theGoalsand clickRun.
+ - 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-authproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+ - 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
+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:
+-
+
- Add an
application-security-domainmapping in theejb3subsystem to enable Elytron security for theSecuredEJB.
+ - Add the
@SecurityDomain("other")security annotation to the EJB declaration to tell the EJB container to apply authorization to this EJB.
+ - Add the
@RolesAllowed({ "guest" })annotation to the EJB declaration to authorize access only to users withguestrole access rights.
+ - Add the
@RolesAllowed({ "admin" })annotation to the administrative method in theSecuredEJBto authorize access only to users withadminrole access rights.
+ - Add an application user with
guestrole access rights to the EJB. This quickstart defines a userquickstartUserwith passwordquickstartPwd1!in theguestrole. Theguestrole matches the allowed user role defined in the@RolesAllowedannotation in the EJB but it should not be granted access to the administrative method annotated withRolesAllowed({"admin"}).
+
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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-elytron.clifile 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.
+ -
+
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 +
+ -
+
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
application-security-domainmapping was added to theejb3subsystem: +
+<application-security-domains> + <application-security-domain name="other" security-domain="ApplicationDomain"/> +</application-security-domains> +The
+application-security-domainessentially enables Elytron security for the quickstart EJBs. It maps theothersecurity domain that was set in the EJBs via annotation to the ElytronApplicationDomainthat will be responsible for authenticating and authorizing access to the EJBs.
+ - The
http-remoting-connectorin theremotingsubsystem was updated to use theapplication-sasl-authenticationfactory: +
+<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.
+
+
Start the Server
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+target/ejb-security.jarto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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
+ejb3andundertowsubsystems. You should see the following result when you run the script:
+The batch executed successfully +process-state: reload-required +
+
Restore the Server Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile 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 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. +
- To deploy the server project, right-click on the
ejb-securityproject and chooseRun As-->Maven build. Enterclean package wildfly:deployfor theGoals:and clickRun. This deploys theejb-securityJAR to the JBoss EAP server.
+ - Right-click on the
ejb-securityproject and chooseRun As-->Run Configurations. Enterexec:execfor theGoals, and then clickRun.
+ - Review the output in the console window. You should see the same results as when running Maven in the command line. +
- To undeploy the project, right-click on the
ejb-securityproject and chooseRun As-->Run Configurations. Enterwildfly:undeployfor theGoalsand clickRun.
+ - 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
+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:
+-
+
-
+
+ejb: This project contains the EJB code and can be built independently to produce the JAR archive. The EJB has a single methodsayHellowhich will take in a Stringnameand returnHello <name>if thenameis not null or an empty String. If thenameis null or an empty String, then it will throw a custom Exception (GreeterException) back to the client.
+ -
+
+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.
+ -
+
+ear: This project builds the EAR artifact and pulls in the ejb, web, and client artifacts.
+ -
+
+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.
+
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:
-
+
- A JSF page (http://localhost:8080/ejb-throws-exception/) asks for the user name. +
- On clicking
Say Hello, the value of theNameinput text is sent to a managed bean namedGreeterBean.
+ - On setting the name, the
Greeterinvokes theGreeterEJB, which was injected to the managed bean. Notice the field annotated with@EJB.
+ - The EJB responds with
Hello <name>or throws an Exception if the name is empty or null.
+ - The response or exception's message from invoking the
GreeterEJBis stored in a field (response) of the managed bean.
+ - The managed bean is annotated as
@RequestScoped, so the same managed bean instance is used only for the request/response.
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+ear/target/ejb-throws-exception.earto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Right-click on the
ejb-throws-exception-earsubproject, and chooseRun As-->Run on Server.
+ - Choose the server and click
Finish.
+ - This starts the server, deploys the application, and opens a browser window that accesses the running application. +
- To undeploy the project, right-click on the
ejb-throws-exception-earproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Start JBoss Developer Studio. +
- Open the
Forge ConsoleWindow. To open it, navigate to menu item Window -> Show View -> Other. Locate Forge -> Forge Console and click OK.
+ - Click the Start button (green triangle) in top right corner of the Forge Console to start the default Forge runtime. +
- In the Forge Console Window, navigate to the root directory of this quickstart.
+
+$ cd QUICKSTART_HOME/forge-from-scratch/ +
+ - Notice there is a file in this directory named
generate.fsh. Run this file from the Forge console using theruncommand: +
+$ run generate.fsh +
+ -
+
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
buildcommand is executed, which should result in***SUCCESS*** Build Successnear the end of the console output.
+
+ - The script issues this command:
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 nameforge-example.
+ - This project also appears in the
Project Explorerview 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
+-
+
- 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. +
- 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 clickFinish.
+ - Upon successful deployment, a Welcome to Forge Window opens with the application running at the following URL: http://localhost:8080/forge-example/ +
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:
+-
+
- Go to the Red Hat JBoss Developer Studio
Serverswindow.
+ - Expand the JBoss EAP Server to see the list of deployed applications. +
- Choose the
forge-exampleproject created by this quickstart, right-click, and chooseRemove.
+ - Click
OKwhen 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") +
+
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: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:
+-
+
- Enter a name in the
usernamefield and click onGreet!.
+ - If you enter a username that is not in the database, you get a message
No such user exists!.
+ - If you enter a valid username, you get a message
Hello,followed by the user's first and last name.
+ - To create a new user, click the
Add a new userlink. Enter the username, first name, and last name and then clickAdd User. The user is added and a message displays the new user id number.
+ - Click on the
Greet a user!link to return to theGreet!page.
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/greeter.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/greeter/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+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
+-
+
- Start the JBoss EAP servers as described in the above section. +
- Navigate to the root directory of this quickstart in the command prompt. +
- Use the following command to clean up previously built artifacts, and build and deploy the EJB archive:
+
+mvn clean install wildfly:deploy +
+ -
+
Ensure the
+target/ha-singleton-deployment.jararchive is deployed tonode1(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) +
+ -
+
Use the following command to deploy the already built archive to the second server. Note that since the default socket binding port is
+9990and the second server has ports offsetted by100, the sum,10090must be passed as an argument to the deploy maven goal.
+mvn wildfly:deploy -Dwildfly.port=10090 +
+ -
+
Ensure the
+service/target/ha-singleton-deployment.jararchive is deployed tonode2by 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") +
+ -
+
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") +
+ -
+
Verify failover of the singleton deployment. Shutdown the server operating as the singleton master, for instance by using the
+Ctrl+Ckey 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! +
+
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:
-
+
- Move the
src/main/resources/META-INF/singleton-deployment.xmlfile into root directory of this quickstart.
+ - 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 +
+ -
+
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 +
+ -
+
Review the deployment overlay changes in the
+standalone-ha.xmlserver 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> +
+ -
+
Observe the server output. The deployments are now set up as singleton deployments.
+
+ -
+
To remove the deployment overlay run the following CLI command:
+
+deployment-overlay remove --name=singleton-deployment +deployment-overlay redeploy-affected --name=singleton-deployment +
+
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
+-
+
- Ensure all JBoss EAP servers are started. +
- Navigate to the root directory of this quickstart in the command prompt. +
- Use the following commands to undeploy the artifacts:
+
+mvn wildfly:undeploy +mvn wildfly:undeploy -Dwildfly.port=10090 +
+
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.
-
+
- 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.
+ - 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.
+
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
+-
+
- Start the JBoss EAP servers as described in the above section. +
- Open a command prompt and navigate to the
primary-only/directory located in the root directory of this quickstart.
+ - Use the following command to clean up any previously built artifacts, and to build and deploy the JAR archive.
+
+mvn clean install wildfly:deploy +
+ -
+
Investigate the primary-only Console Output for Server 1. Verify that the
+target/ha-singleton-service-primary-only.jararchive is deployed tonode1, 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'. +
+
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
+-
+
-
+
Use the following command to deploy the same archive to the second server. Because the default socket binding port for deployment is
+9990and the second server ports are offset by100, you must pass the sum,10090, for the socket binding port as the argument to thedeployMaven goal.
+mvn wildfly:deploy -Dwildfly.port=10090 +
+ -
+
Investigate the primary-only console output for both servers. Verify that the
+target/ha-singleton-service-primary-only.jararchive is deployed tonode2by 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'. +
+ -
+
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 +
+ -
+
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'. +
+
Test Singleton Service Failover for the primary-only Example
+-
+
-
+
To verify failover of the singleton service, shut down the server operating as the singleton master by using the
+Ctrl+Ckey 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.
+
+ -
+
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'. +
+
Undeploy the primary-only Example
+-
+
- Start the JBoss EAP servers as described in the above section. +
- Open a command prompt and navigate to the
primary-only/directory located in the root directory of this quickstart.
+ - Use the following command to undeploy the JAR archive from Server 1.
+
+mvn wildfly:undeploy +
+ -
+
Use the following command to undeploy the JAR archive from Server 2.
+
+mvn wildfly:undeploy -Dwildfly.port=10090 +
+
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.
+-
+
- Start the JBoss EAP servers as described in the above section. +
- Open a command prompt and navigate to the
with-backups/directory located in the root directory of this quickstart.
+ - Use the following command to clean up any previously built artifacts, and build and deploy the JAR archive.
+
+mvn clean install wildfly:deploy +
+
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
+-
+
- Start the JBoss EAP servers as described in the above section. +
- Open a command prompt and navigate to the
with-backups/directory located in the root directory of this quickstart.
+ - Use the following command to undeploy the JAR archive from Server 1.
+
+mvn wildfly:undeploy +
+ -
+
Use the following command to undeploy the JAR archive from Server 2.
+
+mvn wildfly:undeploy -Dwildfly.port=10090 +
+
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.
+-
+
- If you have tested other election policies that configured the
singletonsubsystem, see Restoring the Default Singleton Subsystem Configuration for instructions to restore the singleton election policy to the default configuration.
+ - Start the two servers with the HA profile as described above. +
- Review the contents of the
name-preference-election-policy-add.clifile located in the root of this quickstart directory. This script configures the default election policy to choose nodes in a preferred order ofnode3,node2, andnode1using this command. +
+/subsystem=singleton/singleton-policy=default/election-policy=simple:write-attribute(name=name-preferences,value=[node3,node2,node1]) +
+ - 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.cliscript executes thereloadcommand, so a reload is not required.
+ -
+
Stop the server and review the changes made to the
+standalone-ha.xmlserver configuration file by the management CLI commands. Thesingletonsubsystem now contains aname-preferenceselement under thesimple-election-policythat specifies the preferencesnode3 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> +
+ -
+
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 +
+ -
+
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'. +
+
Configure a Random Election Policy
+This example configures an election policy that elects a random cluster member when the cluster membership changes.
+-
+
- If you have tested other election policies that configured the
singletonsubsystem, see Restoring the Default Singleton Subsystem Configuration for instructions to restore the singleton election policy to the default configuration.
+ - Start the two servers with the HA profile as described above. +
- Review the contents of the
random-election-policy-add.clifile 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() +
+ -
+
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.cliscript executes thereloadcommand, so a reload is not required.
+ -
+
Stop the server and review the changes made to the
+standalone-ha.xmlserver configuration file by the management CLI commands. Thesingletonsubsystem now contains arandom-election-policyelement under thesingleton-policythat specifies the preferencesnode3 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> +
+ -
+
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 +
+ -
+
Be sure both servers are started, deploy one of the examples to both servers, and verify that the election policy is now in effect.
+
+
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.
+-
+
- Quorum can be configured for any singleton policy. Optionally, if you have reconfigured the
singletonsubsystem, see Restoring the Default Singleton Subsystem Configuration for instructions to restore the singleton election policy to the default configuration.
+ - Start the two servers with the HA profile as described above. +
- Review the contents of the
quorum-add.clifile 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) +
+ -
+
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.cliscript executes thereloadcommand, so a reload is not required.
+ -
+
Review the changes made to the
+standalone-ha.xmlserver configuration file by the management CLI commands. Thesingletonsubsystem now contains aquorumattribute for thesingleton-policyelement 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> +
+ -
+
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 +
+ -
+
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. +
+ -
+
Shut down one of the servers by using the
+Ctrl+Ckey 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. +
+ -
+
A
+quorum-remove.cliscript is provided in the root directory of this quickstart that removes the quorum from thesingletonsubsystem.
+
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.xmlorstandalone-full.xmlprofile instead of with thestandalone-ha.xmlorstandalone-full-ha.xmlprofile. 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
+multicastis enabled or change thejgroupssubsystem 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.
+-
+
- Start the two servers with the HA profile as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Use the following commands to undeploy all of the artifacts.
+
+mvn wildfly:undeploy +mvn wildfly:undeploy -Dwildfly.port=10090 +
+
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.
-
+
- Start both servers with the HA profile as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 +
+
+ -
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy both the client and service applications:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-html5.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 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
+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:
+-
+
-
+
A message producer that sends messages to a JMS destination deployed to a JBoss EAP server.
+
+ -
+
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 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.
-
+
- 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. +
+ - 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 +
+ - Review the
configure-jms.clifile in the root of this quickstart directory. This script adds thetestqueue to themessagingsubsystem in the server configuration file.
+ -
+
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 +
+ - You should see the following result when you run the script:
+
+The batch executed successfully +
+ - Stop 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.
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Execute the Quickstart
+To run the quickstart from the command line:
+-
+
-
+
Make sure you have started the JBoss EAP server. See the instructions in the previous section.
+
+ -
+
Open a command prompt and navigate to the root of the helloworld-jms quickstart directory:
+
+cd PATH_TO_QUICKSTARTS/helloworld-jms +
+ -
+
Type the following command to compile and execute the quickstart:
+
+mvn clean compile exec:java +
+
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.
-
+
-
+
+usernameThis 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
+ -
+
+passwordThis 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.factoryThe name of the JMS ConnectionFactory you want to use.
+Default:
+jms/RemoteConnectionFactory
+ -
+
+destinationThe name of the JMS Destination you want to use.
+Default:
+jms/queue/test
+ -
+
+message.countThe number of JMS messages you want to produce and consume.
+Default:
+1
+ -
+
+message.contentThe content of the JMS TextMessage.
+Default:
+"Hello, World!"
+ -
+
+java.naming.provider.urlThis 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
+-
+
- 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 +
+ - 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 +
+ - This script removes the
testqueue from themessagingsubsystem in the server configuration. You should see the following result when you run the script: +
+The batch executed successfully +
+
Remove the JMS Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone-full.xmlfile 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 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 Add an Application User as described above. +
- Configure and start the JBoss EAP server in Red Hat JBoss Developer Studio:
+
-
+
- Define a server runtime environment that uses the
standalone-full.xmlconfiguration file.
+ - Start the server defined in the previous step. +
+ - Define a server runtime environment that uses the
- Outside of JBoss Developer Studio, configure the JMS
testqueue by running the JBoss CLI commands as described above under Configure the Server.
+ - In JBoss Developer Studio, right-click on the
helloworld-jmsproject and chooseRun As-->Java Application. In theSelect Java Applicationwindow, chooseHellowWorldJMSClient - org.jboss.as.quickstarts.jmsand clickOK. The client output displays in theConsolewindow. The output messages appear in theConsolewindow.
+ - Be sure to Remove the JMS 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
+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@MXBeanannotation.
+ -
+
+MXComponentHelloWorld: This MBean is a managed bean withMXBeaninterface.
+ -
+
+MXPojoHelloWorld: This MBean is a pojo using MXBean interface and declared in thejboss-service.xmlfile.
+ -
+
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+helloworld-mbean-webapp/target/helloworld-mbean-webapp.warandhelloworld-mbean-service/target/helloworld-mbean-service.sarto 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 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.
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 : 
-
+
- Click on the MBeans tab. +
- Expand
quickstartsin the left column of the console.
+ - Under
quickstarts, you see the 4 MBeans:AnnotatedComponentHelloWorld,MXComponentHelloWorld,MXPojoHelloWorld, andSarMXPojoHelloWorld
+ - Expand each MBean and choose:
Operations-->sayHello.
+ - Type your name in the (p0 String ) input text box and click the
sayHellobutton.
+
-
+
- For the
AnnotatedComponentHelloWorldandMXComponentHelloWorldexamples, you will see a popup Window displayingHello <your name>!.
+ - For the
MXPojoHelloWorldandSarMXPojoHelloWorldexamples, you will see a popup Window displayingWelcome <your name>!.
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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.
-
+
- Install the JBoss Tools Maven Packaging Configurator
+
-
+
- If the
Red Hat Centralpage is not showing, open it by choosingHelp-->Red Hat Central.
+ - Click the
Software/Updatetab at the bottom of theRed Hat Central.
+ - Scroll down to the
Mavensection, select theJBoss Tools Maven Packaging Configuratorand clickInstall/Update.
+
+ - If the
- Right click on the parent
helloworld-mbeanparent project and chooseMaven-->Update Project.... Select all projects and clickOK.
+ - Right-click on the
helloworld-mbean-serviceproject and chooseRun As-->Run on Server.
+ - Right-click on the
helloworld-mbean-webappproject and chooseRun As-->Run on Server.
+ - Start JConsole and Test the MBeans in JConsole as described above. +
- To undeploy the web application, right-click on the
helloworld-mbean-wepappproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+ - To undeploy the web service, right-click on the
helloworld-mbean-serviceproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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
HELLOWORLDMDBQueuebound in JNDI asjava:/${property.helloworldmdb.queue}
+ - A topic named
HELLOWORLDMDBTopicbound in JNDI asjava:/${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.
-
+
- 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. +
+ - 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 +
+ - Review the
enable-mdb-property-substitution.cliscript file in the root of this quickstart directory. This script first enables MDB annotation property substitution theeesubsystem of the server configuration file by creating anannotation-property-replacementproperty with a value oftrue. It then defines the system properties that are used in the substitution.
+ -
+
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 +
+ - Stop 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.
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-mdb-propertysubstitution.warto 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 +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- 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 +
+ - 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 +
+
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
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone-full.xmlfile 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 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.xmlconfiguration 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
+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
HELLOWORLDMDBQueuebound in JNDI asjava:/queue/HELLOWORLDMDBQueue
+ - A topic named
HELLOWORLDMDBTopicbound in JNDI asjava:/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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-mdb.warto 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 +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command line and navigate to the JBoss EAP server
configurationdirectory: +
+For Linux: EAP7_HOME/standalone/configuration +For Windows: EAP7_HOME\standalone\configuration +
+ - 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 +
+ -
+
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 nametoquickstartUserand that this matches the user we've added to theApplicationRealm. 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 theApplicationRealmto obtain the client's roles.
+ -
+
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
+quickstartUseralias. When authenticating a client in aCLIENT_CERTconfiguration, the CN (common name) of the client's certificate is extracted by a principal decoder and this name is then used by theKeyStoreRealmto match an alias in the trust store. If a trusted certificate is found under this alas, the client is considered authenticated.
+ -
+
Export client certificate to pkcs12 format
+
+$>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret +
+ -
+
The certificates and keystores are now properly configured.
+
+
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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-ssl.clifile in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands.
+ -
+
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 +
+ -
+
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
+key-stores were added to theelytronsubsystem:
+<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> +
+ -
+
The following
+key-managerwas added to theelytronsubsystem:
+<key-managers> + <key-manager name="qsKeyManager" key-store="qsKeyStore"> + <credential-reference clear-text="secret"/> + </key-manager> +</key-managers> +
+ -
+
The following
+trust-managerwas added to theelytronsubsystem:
+<trust-managers> + <trust-manager name="qsTrustManager" key-store="qsTrustStore"/> +</trust-managers> +
+ -
+
The following
+ssl-contextwas added to theelytronsubsystem:
+<server-ssl-contexts> + <server-ssl-context name="qsSSLContext" protocols="TLSv1.2" need-client-auth="true" key-manager="qsKeyManager" trust-manager="qsTrustManager"/> +</server-ssl-contexts> +
+ -
+
The following realms were added to the
+elytronsubsystem:
+<key-store-realm name="KeyStoreRealm" key-store="qsTrustStore"/> + +<aggregate-realm name="QuickstartRealm" authentication-realm="KeyStoreRealm" authorization-realm="ApplicationRealm"/> +The
+aggregate-realmdefines different security realms for authentication and authorization. In this case, theKeyStoreRealmis responsible for authenticating the principal extracted from the client's certificate and theApplicationRealmis responsible for obtaining the roles required to access the application.
+ -
+
The following
+principal-decoderandsecurity-domainwere added to theelytronsubsystem:
+<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-decodercreates a newPrincipalfrom the CN attribute of theX500Principalobtained from the client's certificate. This new principal is supplied to the security realms and is also the principal returned in methods likegetUserPrincipalandgetCallerPrincipal.
+ -
+
The following
+http-authentication-factorywas added to theelytronsubsystem:
+<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_CERTHTTP mechanism.
+ -
+
The
+https-listenerin theundertowsubsystem was changed to reference theqsSSLContextssl-context:
+<https-listener name="https" socket-binding="https" ssl-context="qsSSLContext" enable-http2="true"/> +
+ -
+
The following
+application-security-domainwas added to theundertowsubsystem:
+<application-security-domains> + <application-security-domain name="client_cert_domain" http-authentication-factory="quickstart-http-authentication"/> +</application-security-domains> +It maps the
+client_cert_domainfrom the quickstart application to thehttp-authentication-factoryshown above, so requests made to the application go through the configured HTTP authentication factory.
+
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
+-
+
- Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/. +
- Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings. +
- Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it. +
- In the 'Manage certificates' screen, select the 'Your Certificates' tab and click on the 'Import' button. +
- Select the
clientCert.p12file. You will be prompted to enter the password:secret.
+ - The client certificate is now installed in the Google Chrome browser. +
Import the Certificate into Mozilla Firefox
+-
+
- Click the 'Edit' menu item on the browser menu and choose 'Preferences'. +
- A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab. +
- On the 'Certificates' tab, mark the option 'Ask me every time' and click the 'View Certificates' button. +
- A new window will open. Select the 'Your Certificates' tab and click the 'Import' button. +
- Select the
clientCert.p12file. You will be prompted to enter the password:secret.
+ - The certificate is now installed in the Mozilla Firefox browser. +
Start the Server
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server with the web profile:
+
+For Linux: bin/standalone.sh +For Windows: 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 for complete instructions and additional options.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of one of the quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-mutual-ssl-secured.warto the running instance of the server.
+ - 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.p12is same as the one mentioned inapp-roles.propertiesfile. It will otherwise result into aHTTP Status 403or forbidden error.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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
+undertowandelytronsubsystems. You should see the following result when you run the script:
+The batch executed successfully +process-state: reload-required +
+
Restore the Server Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile with the back-up copy of the file.
+
Remove the keystores and certificates created for this quickstart
+-
+
- Open a command line and navigate to the JBoss EAP server
configurationdirectory: +
+For Linux: standalone/configuration +For Windows: standalone\configuration +
+ - Remove the
clientCert.p12,client.crt,client.keystore,client.truststoreandserver.keystorefiles that were generated for this quickstart.
+
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
+-
+
- Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/. +
- Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings. +
- Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it. +
- 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. +
- The certificate is expanded, displaying the
quickstartUserentry. Click on the icon (3 dots) to the right of it and then select 'Delete'.
+ - Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser. +
Remove the Client Certificate from Mozilla Firefox
+-
+
- Click the 'Edit' menu item on the browser menu and choose 'Preferences'. +
- A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab. +
- On the 'Certificates' tab click the 'View Certificates' button. +
- A new window will open. Select the 'Your Certificates' tab. +
- Select the
quickstartUsercertificate and click theDeletebutton.
+ - The certificate has now been removed from the Mozilla Firefox browser. +
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.
+-
+
- Be sure to configure the server by running the JBoss CLI commands as described above under Configure the JBoss EAP Server. Stop the server at the end of that step. +
- 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
+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
+-
+
- Open a command line and navigate to the JBoss EAP server
configurationdirectory: +
+For Linux: EAP7_HOME/standalone/configuration +For Windows: EAP7_HOME\standalone\configuration +
+ - 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 +
+ -
+
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 +
+ -
+
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 +
+ -
+
Export client certificate to pkcs12 format
+
+$>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret +
+ -
+
The certificates and keystores are now properly configured.
+
+
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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-ssl.clifile in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands.
+ -
+
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 +
+ -
+
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
+key-stores were added to theelytronsubsystem:
+<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> +
+ -
+
The following
+key-managerwas added to theelytronsubsystem:
+<key-managers> + <key-manager name="qsKeyManager" key-store="qsKeyStore"> + <credential-reference clear-text="secret"/> + </key-manager> +</key-managers> +
+ -
+
The following
+trust-managerwas added to theelytronsubsystem:
+<trust-managers> + <trust-manager name="qsTrustManager" key-store="qsTrustStore"/> +</trust-managers> +
+ -
+
The following
+ssl-contextwas added to theelytronsubsystem:
+<server-ssl-contexts> + <server-ssl-context name="qsSSLContext" protocols="TLSv1.2" need-client-auth="true" key-manager="qsKeyManager" trust-manager="qsTrustManager"/> +</server-ssl-contexts> +
+ -
+
The
+https-listenerin theundertowsubsystem was changed to reference theqsSSLContextssl-context:
+<https-listener name="https" socket-binding="https" ssl-context="qsSSLContext" enable-http2="true"/> +
+
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
+-
+
- Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/. +
- Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings. +
- Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it. +
- In the 'Manage certificates' screen, select the 'Your Certificates' tab and click on the 'Import' button. +
- Select the
clientCert.p12file. You will be prompted to enter the password:secret.
+ - The client certificate is now installed in the Google Chrome browser. +
Import the Client Certificate into Mozilla Firefox
+-
+
- Click the 'Edit' menu item on the browser menu and choose 'Preferences'. +
- A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab. +
- On the 'Certificates' tab, mark the option 'Ask me every time' and click the 'View Certificates' button. +
- A new window will open. Select the 'Your Certificates' tab and click the 'Import' button. +
- Select the
clientCert.p12file. You will be prompted to enter the password:secret.
+ - The certificate is now installed in the Mozilla Firefox browser. +
Start the Server
+-
+
- Open a command line and navigate to the root of the JBoss server directory. +
- The following shows the command line to start the server with the web profile:
+
+For Linux: /bin/standalone.sh +For Windows: 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 for complete instructions and additional options.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of one of the quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-mutual-ssl.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss Server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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
+undertowsubsystem and it also removes thessl-context,key-manager,trust-managerandkey-stores from theelytronsubsystem. You should see the following result when you run the script:
+The batch executed successfully +process-state: reload-required +
+
Restore the Server Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile with the back-up copy of the file.
+
Remove the keystores and certificates created for this quickstart
+-
+
- Open a command line and navigate to the JBoss EAP server
configurationdirectory: +
+For Linux: standalone/configuration +For Windows: standalone\configuration +
+ - Remove the
clientCert.p12,client.crt,client.keystore,client.truststoreandserver.keystorefiles that were generated for this quickstart.
+
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
+-
+
- Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/. +
- Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings. +
- Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it. +
- 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. +
- The certificate is expanded, displaying the
quickstartUserentry. Click on the icon (3 dots) to the right of it and then select 'Delete'.
+ - Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser. +
Remove the Client Certificate from Mozilla Firefox
+-
+
- Click the 'Edit' menu item on the browser menu and choose 'Preferences'. +
- A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab. +
- On the 'Certificates' tab click the 'View Certificates' button. +
- A new window will open. Select the 'Your Certificates' tab. +
- Select the
quickstartUsercertificate and click theDeletebutton.
+ - The certificate has now been removed from the Mozilla Firefox browser. +
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.
+-
+
- Be sure to configure the keystores and client certificates as described under Set Up Client and Server Keystores Using Java Keytool. +
- Depending on the browser you choose, be sure to either import the certificate into Chrome or import the certificate into Firefox. +
- Be sure to configure the server by running the JBoss CLI commands as described above under Configure the JBoss EAP 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
helloworld-mutual-sslproject and chooseRun As-->Run on Server.
+ - 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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-rs.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-singleton.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command line and navigate to the JBoss EAP server
configurationdirectory: +
+For Linux: standalone/configuration +For Windows: standalone\configuration +
+ - 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.
+
+
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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-ssl.clifile in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands.
+ -
+
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 +
+ -
+
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 EAP7_HOME/standalone/configuration/standalone.xml file and review the changes.
-
+
-
+
The following
+key-storewas added to theelytronsubsystem:
+<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> +
+ -
+
The following
+key-managerwas added to theelytronsubsystem:
+<key-managers> + <key-manager name="qsKeyManager" key-store="qsKeyStore"> + <credential-reference clear-text="secret"/> + </key-manager> +</key-managers> +
+ -
+
The following
+ssl-contextwas added to theelytronsubsystem:
+<server-ssl-contexts> + <server-ssl-context name="qsSSLContext" protocols="TLSv1.2" key-manager="qsKeyManager"/> +</server-ssl-contexts> +
+ -
+
The
+https-listenerin theundertowsubsystem was changed to reference theqsSSLContextssl-context:
+<https-listener name="https" socket-binding="https" ssl-context="qsSSLContext" enable-http2="true"/> +
+
Test the Server SSL Configuration
+To test the SSL configuration, access: https://localhost:8443
+Start the Server
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server with the web profile:
+
+For Linux: bin/standalone.sh +For Windows: 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 for complete instructions and additional options.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of one of the quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-ssl.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: https://localhost:8443/helloworld-ssl/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss Server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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
+undertowsubsystem and it also removes thessl-context,key-managerandkey-storefrom theelytronsubsystem. You should see the following result when you run the script:
+The batch executed successfully +process-state: reload-required +
+
Restore the Server Configuration Manually
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile with the back-up copy of the file.
+
Remove the keystore created for this quickstart
+-
+
- Open a command line and navigate to the JBoss EAP server
configurationdirectory: +
+For Linux: standalone/configuration +For Windows: standalone\configuration +
+ - Remove the keystore generated for this quickstart. +
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 configure the server by running the JBoss CLI commands as described above under Configure the JBoss EAP Server. Stop the server at the end of that step. +
- 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/helloworld-ws.warto the running instance of the server.
+ - 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 +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: bin/standalone.sh +For Windows: bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/helloworld.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/helloworld/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/hibernate.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ - This will deploy
shared/target/inter-app-app-shared.jar,appA/target/inter-app-app-appA.warandappB/target/inter-app-app-appB.warto 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.
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:
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type the following command to undeploy the
inter-app-appA.warandinter-app-appB.wararchives. +
+mvn wildfly:undeploy -pl appA,appB +
+ -
+
Type the following command to undeploy the
+inter-app-shared.jararchive.
+mvn wildfly:undeploy -pl shared +
+
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.
+-
+
- In the
Serverstab, right-click on the JBoss EAP server and chooseStart.
+ - Deploy the projects in one of the following ways.
+
-
+
Drag and Dropmode: Click to multi-select theinter-app-app-shared,inter-app-app-appA, andinter-app-app-appBprojects, then drag and drop them on the running JBoss EAP server. This deploys the projects to the server without opening the browser.
+Batchmode: In theServerstab, right-click on the server and chooseAdd and Remove. If theinter-app-app-shared,inter-app-app-appA, andinter-app-app-appBprojects are the only projects in the list, clickAdd All. Otherwise, use multi-select to select them and clickAdd. Then clickFinish.
+
+ - Right-click on the
inter-app-app-appAproject and chooseRun As-->Run on Server. A browser window appears that accesses the runningappAapplication.
+ - Right-click on the
inter-app-app-appBproject and chooseRun As-->Run on Server. A browser window appears that accesses the runningappBapplication.
+ - To undeploy the
inter-app-app-appBproject, right-click on it and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+ - To undeploy the
inter-app-app-appAproject, right-click on it and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn package wildfly:deploy +
+ - This will deploy
target/jaxrs-client.warto the running instance of the server.
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- 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 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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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 be either
arq-managedfor running on managed server orarq-remotefor 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. +
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will create the
+jaxws-addressing-client.jarand deployservice/target/jaxws-addressing-service.warto 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: http://localhost:8080/jaxws-addressing/AddressingService?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.
+Run the Client
+-
+
-
+
Make sure the service deployed properly.
+
+ -
+
Open a command prompt and navigate into the client directory of this quickstart.
+
+cd client/ +
+ - Type this command to run the client.
+
+mvn exec:java +Note: This quickstart requires
+quickstart-parentartifact 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 +
+ -
+
You should see the following output in the client console.
+
+Hello World! +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- To build all of the artifacts, right-click on the
jaxws-addressingparent project, and chooseRun As-->Maven install.
+ - To deploy the service:
+
-
+
- Right-click on the
jaxws-addressing-servicesubproject, and chooseRun 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. +
+ - Right-click on the
- To access the application:
+
-
+
- Right-click on the
jaxws-addressing-clientsubproject and chooseRun As-->Java Application.
+ - You should see the following message in the
Consoletab: +
+Hello World! +
+
+ - Right-click on the
- To undeploy the project, right-click on the
jaxws-addressingparent project and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+service/target/jaxws-ejb-service.warto 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: http://localhost:8080/jaxws-ejb/EJB3Bean?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.
+Run the Client
+-
+
-
+
Make sure the service deployed properly.
+
+ -
+
Open a command prompt and navigate into the client directory of this quickstart.
+
+cd client/ +
+ - Type this command to run the client.
+
+mvn exec:java +Note: This quickstart requires
+quickstart-parentartifact 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 +
+ -
+
You should see the following output in the client console.
+
+EJB3Bean returning: ejbClient calling +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- To build all of the artifacts, right-click on the
jaxws-ejbparent project, and chooseRun As-->Maven install.
+ - To deploy the service:
+
-
+
- Right-click on the
jaxws-ejb-servicesubproject, and chooseRun As-->Run on Server.
+ - Choose the server and click
Finish.
+ - This starts the server and deploys the service to the server. +
+ - Right-click on the
- To access the application:
+
-
+
- Right-click on the
jaxws-ejb-clientsubproject and chooseRun As-->Java Application.
+ - You should see the following message in the
Consoletab: +
+EJB3Bean returning: ejbClient calling +
+
+ - Right-click on the
- To undeploy the project, right-click on the
jaxws-ejbparent project and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+service/target/jaxws-pojo-service.warto 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: http://localhost:8080/jaxws-pojo/JSEBean?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.
+Run the Client
+-
+
- Make sure the service deployed properly. +
- Open a command prompt and navigate into the client directory of this quickstart.
+
+cd client/ +
+ -
+
Type this command to run the client.
+
+mvn exec:java +Note: This quickstart requires
+quickstart-parentartifact 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 +
+ -
+
You should see the following response.
+
+JSEBean pojo: pojoClient calling +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- To build all of the artifacts, right-click on the
jaxws-pojoparent project, and chooseRun As-->Maven install.
+ - To deploy the service:
+
-
+
- Right-click on the
jaxws-pojo-servicesubproject, and chooseRun As-->Run on Server.
+ - Choose the server and click
Finish.
+ - This starts the server and deploys the service to the server. +
+ - Right-click on the
- To access the application:
+
-
+
- Right-click on the
jaxws-pojo-clientsubproject and chooseRun As-->Java Application.
+ - You should see the following message in the
Consoletab: +
+JSEBean pojo: pojoClient calling +
+
+ - Right-click on the
- To undeploy the project, right-click on the
jaxws-pojoparent project and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+service/target/jaxws-retail-service.warto 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.
[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
+-
+
-
+
Make sure the service deployed properly.
+
+ -
+
Open a command prompt and navigate into the client directory of this quickstart.
+
+cd client/ +
+ - Type this command to run the client.
+
+mvn exec:java +Note: This quickstart requires
+quickstart-parentartifact 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 +
+ -
+
You should see the following output in the client console.
+
+Jay Boss's discount is 10.00 +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- To build the parent project, right-click on the
jaxws-retailproject and chooseRun As-->Maven install.
+ - To deploy the service:
+
-
+
- Right-click on the
jaxws-retail-serviceproject and chooseRun As-->Maven install.
+ - In the
jaxws-retail-serviceproject, select thetarget/generated-sources/wsconsumefolder and chooseBuild Path-->Use as Source Folder.
+ - Right-click on the
jaxws-retail-serviceproject and chooseRun As-->Run on Server.
+ - Select the JBoss EAP server and click
Finish.
+ - You should see the following message in the
Consoletab: +
+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.
+
+
+ - Right-click on the
-
+
To run the application:
+-
+
- To access the application, right-click on the
jaxws-retail-clientproject and chooseRun As-->Java Application.
+ - Choose the
Clientclass and clickOK.
+ - Review the output in the console window. You should see the following message:
+
+Jay Boss's discount is 10.00
+
+ - To access the application, right-click on the
-
+
To undeploy the project, right-click on the
+jaxws-retail-serviceproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ - This will deploy
target/jsonpto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/jta-crash-rec.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/jta-crash-rec/XA.
+Test the Application
+-
+
-
+
When you access the application, you will find a web page containing two html input boxes for adding
+key/valuepairs to a database. Instructions for using the application are shown at the top of the application web page.
+ -
+
When you add a new
+key/valuepair, the change is committed to the database and a JMS message sent. The message consumer then updates the newly inserted row by appending the textupdated via JMSto the value. Since the consumer updates the row asynchronously, you may need to click Refresh Table to see the text added to thekey/valuepair you previously entered.
+ -
+
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. +
+ -
+
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. +
+ -
+
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.
+
+ -
+
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_HOMEdirectory
+ - 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. +
+ - Open a command prompt and navigate to the
+ - Start the H2 console by typing:
+
- 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.
+
+
+ - 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:
+
-
+
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!
+
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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:
+-
+
- Configure and start two JBoss EAP servers. +
- Build and deploy the two application components. +
- Open a web browser and attempt to invoice two customers as with the
jtsquickstart.
+ - 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. +
- The user is invited to inspect the content of the transaction objectstore. +
- JBoss EAP server 1 should be restarted. It will then recover the "invoices" delivered to the MDBs, just as it does in the
jtsquickstart.
+
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.
+-
+
-
+
If you have not yet done so, configure the two application servers and deploy the
+jtsquickstart. Follow the instructions in the jts README file.
+ -
+
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 +
+
+ -
+
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 +
+ -
+
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!!! +
+
+ - When you enter a name and click to "add" that customer, you will see the following in the application server 1 console:
+
-
+
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_1with 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_2with 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 +
+ -
+
Disable the Byteman script by restoring the backup configuration file for server 1.
+
+ -
+
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/XAResourceRecordanddefaultStore/StateManager/BasicAction/TwoPhaseCoordinator/ArjunaTransactionImple.
+ - Records will remain in
defaultStore/Recovery/FactoryContactanddefaultStore/RecoveryCoordinatorfor 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_2with 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 +
+
+ - You will know when recovery is complete for server 2 as you will see the following in application-server-2 console:
+
-
+
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.
+
+ -
+
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!
+
+
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.javahas been moved toapplication-component-2/src/main/java/org/jboss/as/quickstarts/cmt/jts/ejb/InvoiceManagerEJB
+cmt/src/main/java/org/jboss/as/quickstarts/cmt/ejb/CustomerManagerEJB.javahas been moved tojts/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_HOMEdenotes the path to the original JBoss EAP installation.
+EAP7_HOME_1denotes the path to the modified JBoss EAP server 1 configuration.
+EAP7_HOME_2denotes 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.
-
+
- 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. +
+ - 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_1with 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 +
+ - Review the
configure-jts-transactions.clifile in the root of this quickstart directory. This script configures the server to use jts transaction processing.
+ - 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 +
+ -
+
Stop the JBoss EAP server.
+
+
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.
-
+
-
+
The orb initializers
+transactionsattribute is changed fromspectofullin theiiop-openjdksubsystem to enable JTS.
+<subsystem xmlns="urn:jboss:domain:iiop-openjdk:2.0"> + <initializers transactions="full" security="identity"/> +</subsystem> +
+ -
+
An empty
+<jts/>element is added to the end of thetransactionssubsystem 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> +
+
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.
+-
+
- 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. +
- Follow the instructions to Add the PostgreSQL Module to the JBoss EAP Server to the server 1 install only. +
- 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_1on the command line when you start the first server to configure PostgreSQL.
+
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.
+-
+
- Make sure you have started the JBoss EAP server with the PostgreSQL driver +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+jts-application-component-1.warandjts-application-component-2.jarto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn package wildfly:undeploy +
+
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
+-
+
- 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 +
+ - 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 +
+
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
+-
+
- 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 +
+ - 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 +
+ - 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) +
+
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
+-
+
- Stop the server. +
- If you backed up the EAP7_HOME/standalone/configuration/standalone-full.xml,simply replace the edited configuration file with the backup copy. +
- 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
+orbsubsystem 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
+transactionsubsystem and remove thenode-identifierattribute from thecore-environmentelement. 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> +
+
+ -
+
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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server with the default profile:
+
+For Linux: bin/standalone.sh +For Windows: bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+target/kitchensink-angularjs.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/kitchensink-angularjs/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- 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 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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the
+functional-tests/directory in this quickstart.
+ - 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 +
+ -
+
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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+ear/target/kitchensink-ear.earto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/kitchensink-ear/.
+-
+
- Enter a name, email address, and Phone nubmer in the input field and click the Register button. +
- If the data entered is valid, the new member will be registered and added to the Members display list. +
- If the data is not valid, you must fix the validation errors and try again. +
- When the registration is successful, you will see a log message in the server console:
+
+Registering _the_name_you_entered_ +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+-
+
- Right-click on the
kitchensink-ear-earsubproject, and chooseRun As-->Run on Server.
+ - Choose the server and click
Finish.
+ - This starts the server, deploys the application, and opens a browser window that accesses the running application at http://localhost:8080/kitchensink-ear-web. +
- To undeploy the project, right-click on the
kitchensink-ear-earproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean wildfly:deploy +
+ -
+
This deploys
+target/kitchensink-html5-mobile.warto the running instance of the server.
+
Access the Application
+Access the running client application in a browser at the following URL: http://localhost:8080/kitchensink-html5-mobile/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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"}
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/kitchensink-jsp.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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.KitchensinkMessagesinterface, 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.xmlfile. 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.javafile 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.javafile was created, which defines default messages in English. Thejboss-logging-processorwill automatically generate an implementation for you, which can be accesssed via theMESSAGESstatic 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.javafile 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()); +
+
+ - Messages strings were replaced with strings retrieved using the resource bundle property names. For example:
+
-
+
The
+kitchensink-ml-ear-web/src/main/webapp/index.xhtmlfile were modified.-
+
- Strings for headers, messages, labels were replaced with the appropriate
# {bundle.<property>}, for example:# {bundle.memberWelcomeHeader}.
+
+ - Strings for headers, messages, labels were replaced with the appropriate
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+kitchensink-ml-ear.earto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/kitchensink-ml-ear/.
+-
+
- Enter a name, email address, and Phone nubmer in the input field and click the Register button. +
- If the data entered is valid, the new member will be registered and added to the Members display list. +
- If the data is not valid, you must fix the validation errors and try again. +
- When the registration is successful, you will see a log message in the server console:
+
+Registering _TheNameYouEntered_ +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+-
+
- Right-click on the
kitchensink-ml-ear-websubproject, and chooseRun As-->Run on Server.
+ - Choose the server and click
Finish.
+ - 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/. +
- To undeploy the project, right-click on the
kitchensink-ml-ear-webproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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.KitchensinkMessagesinterface, 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.xmlfile. 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.javafile 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.javafile was created, which defines default messages in English. Thejboss-logging-processorwill automatically generate an implementation for you, which can be accesssed via theMESSAGESstatic 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.javafile 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()); +
+
+ - Messages strings were replaced with strings retrieved using the resource bundle property names. For example:
+
-
+
The
+src/main/webapp/index.xhtmlfile were modified.-
+
- Strings for headers, messages, labels were replaced with the appropriate
# {bundle.<property>}, for example:# {bundle.memberWelcomeHeader}.
+
+ - Strings for headers, messages, labels were replaced with the appropriate
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/kitchensink-ml.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/kitchensink.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/log4j.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/log4j/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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:
+-
+
- Make a backup copy of the
EAP7_HOME/bin/standalone.conffile.
+ - 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" +
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/logging-tools.warto the running instance of the server.
+
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.
+-
+
-
+
+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 NAMEstring whereNAMEis the last component of the URL.
+ - It also logs the localized
Hello message sentin the server log.
+
+ -
+
+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 NAMEstring whereNAMEis the last component of the URL and the locale used is the one supplied in thelocaleURL.
+ - Logs a localized
Hello message sent in LOCALEmessage 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 ofWebApplicationException.
+
Note that
+WebApplicationExceptioncannot be directly localized by JBoss Logging Tools using the@Messageannotation due to the message parameter being ignored by theWebApplicationExceptionconstructors. Cases like this can be worked around by creating a subclass with a constructor that does deal with the message parameter.
+ -
+
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. +
+ -
+
+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
targetdateURL component into a date object using the formatyyyy-MM-dd
+ - Returns number of days (as an integer) until that date +
- If the
targetdateis invalid, for example, http://localhost:8080/logging-tools/rest/dates/daysuntil/2015-02-31: +-
+
- Catches the
ParseException
+ - Creates a localized
ParseExceptionpassing 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 localizedParseException
+
+ - Catches the
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This deploys
+target/logging.warto the running instance of the server.
+
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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-logging.clifile 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.
+ -
+
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 +
+
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
+-
+
- If your server is not started, then Start the JBoss EAP server. +
- Build and deploy the quickstart. +
- Access the application. +
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:
+-
+
- 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.xmlfile. Also notice in thestandalone.xmlthat the application package defines its own log level.
+ - 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. +
- 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.
+ - 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. +
+ -
+
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.
+
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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 +
+
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
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile 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 JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.
+-
+
- Be sure to configure JBoss EAP server logging as described above under Configure the JBoss EAP Server. Stop the server at the end of that step. +
- Be sure to Remove the Logging 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
+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.
-
+
- 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. +
+ - Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-mail-session.clifile in the root of this quickstart directory. This script creates custom outbound socket binding port for SMTP, POP3, and IMAP. It then creates the customMyOtherMailmail session and configures it to use the custom outbound socket binding ports.
+ -
+
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 +
+ -
+
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 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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/mail.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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 +
+
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
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone-full.xmlfile 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 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
mailproject and chooseRun As-->Run on Server. A browser window appears that accesses the running application.
+ - To undeploy the project, right-click on the
mailproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+ - 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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- 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 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
+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
HELLOWORLDMDBQueuebound in JNDI asjava:/queue/HELLOWORLDMDBQueue
+ - A topic named
HELLOWORLDMDBTopicbound in JNDI asjava:/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.
+-
+
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build the archive:
+
+mvn clean install +
+
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.
+-
+
-
+
If it is running, stop the JBoss EAP server.
+
+ -
+
Back up the following files:
+
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI
+-
+
-
+
Review the
+install-domain.clifile 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-groupserver 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-haprofile.
+ - Creates a delivery group named
my-mdb-delivery-group, with initial active value set totrue.
+ - Deploys the
messaging-clustering-singleton.wararchive.
+ - Starts the servers that were added to the managed domain. +
+ -
+
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" +} +
+
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.
+-
+
-
+
If it is running, stop the JBoss EAP server.
+
+ -
+
Back up the following file:
+
+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.
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server with the
full-haprofile. 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 +
+
Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI
+-
+
-
+
Review the
+install-standalone.clifile 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 totrue.
+ - Deploys the
messaging-clustering-singleton.wararchive.
+ - Reloads the server configuration. +
+ -
+
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 +
+
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.
+-
+
- Stop the server. +
- Make a copy of this JBoss EAP directory structure to use for the second server. +
- 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 +
+
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
+-
+
- Make sure you have started the managed domain as described above. +
- Open a new command prompt, navigate to the root directory of this quickstart, and run the
undeploy-domain.cliscript, 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 +
+
Undeploy the quickstart in a Standalone Server
+-
+
- Make sure you have started the standalone server as described above. +
- Open a command prompt, navigate to the root directory of this quickstart, and run the
undeploy-standalone.cliscript, 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 +
+
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.
+-
+
- If it is running, stop the JBoss EAP server. +
- Restore the
EAP7_HOME/domain/configuration/domain.xmlandEAP7_HOME/domain/configuration/host.xmlfiles 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.
+-
+
-
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/domain.sh +For Windows: EAP7_HOME\bin\domain.bat +
+ -
+
Open a new command prompt, navigate to the root directory of this quickstart, and run the
+remove-domain.cliscript, 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 +
+
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.
+-
+
- If they are running, stop both JBoss EAP servers. +
- Restore the
EAP7_HOME_1/standalone/configuration/standalone-full-ha.xmlfile 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.
+-
+
- 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 +
+ - Open a new command prompt, navigate to the root directory of this quickstart, and run the
remove-standalone.cliscript, 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 +
+
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
+-
+
- If it is running, stop the second instance of the JBoss EAP server. +
- Delete the cloned directory. +
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:
+-
+
-
+
If it is running, stop the JBoss EAP server.
+
+ -
+
If you plan to test using a standalone server, back up the file:
+
+EAP7_HOME/standalone/configuration/standalone-full-ha.xml +
+ -
+
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 +
+
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.
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI
+-
+
-
+
Review the
+install-domain.clifile 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.wararchive
+ - Restarts the servers. +
NOTE: If your
+helloworld-mdbquickstart is not located at the same level in the file structure as this quickstart, you must modify its path in this script. Find theNOTE:in the file for instructions.
+ -
+
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 +
+
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.
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI
+-
+
- Review the
install-standalone.clifile 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.wararchive
+ - Reloads the server configuration +
NOTE: If your
+helloworld-mdbquickstart is not located at the same level in the file structure as this quickstart, you must modify its path in this script. Find theNOTE:in the file for instructions.
+ - 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 +
+
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.
+-
+
- Stop the server. +
- Make a copy of this JBoss EAP directory structure to use for the second server. +
- 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 +
+
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
+-
+
- Make sure you have started the JBoss EAP server in domain mode as described above. +
- 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 +
+
Undeploy the quickstart in Standalone Mode
+-
+
- Make sure you have started the JBoss EAP server in standalone mode as described above. +
- 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 +
+
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.
+-
+
- If it is running, stop the JBoss EAP server. +
- Restore the
EAP7_HOME/domain/configuration/domain.xmlandEAP7_HOME/domain/configuration/host.xmlfiles 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 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.
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/domain.sh +For Windows: EAP7_HOME\bin\domain.bat +
+ - 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 +
+
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.
+-
+
- If they are running, stop both JBoss EAP servers. +
- Restore the
EAP7_HOME_1/standalone/configuration/standalone-full-ha.xmlfile 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 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.
+-
+
- 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 +
+ - 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 +
+
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
+-
+
- If it is running, stop the second instance of the JBoss EAP server. +
- Delete the cloned directory. +
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh + For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/numberguess.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/numberguess/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
beanspackage contains thePaymentBeanbean 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 theamountto$0and thepaymentOptionto 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 theinit()method reinitialize the form values.
+
+ - The
eventspackage contains thePaymentEventclass and the enumPaymentTypeEnum.
+ 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 betweenStringandEnum.
+- The
qualifierspackage contains theCreditandDebitinterfaces. The annotation determines the operation of the injectingEvent.
+ - The
handlerpackage contains interfaces and implementations ofPaymentEventobservers.
+ ICreditEventObserver: Interface to listen toCREDITevent only (@Observes@Credit).
+IDebitEventObserver: Interface to listen toDEBITevent (@Observes@Debit).
+PaymentHandler: The concrete implementation of the payment handler. +-
+
- It implements both
ICreditEventObserverandIDebitEventObserver.
+ - The payment handler exposes the list of events caught during a session (
@Namedname=payments).
+
+- It implements both
- The
resourcespackage contains theResourcesclass 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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/payment-cdi-event.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/payment-cdi-event/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
-
+
For more information about PicketLink STS, see Security Token Service (STS) in Developing Web Services Applications.
+
+ -
+
Additional PicketLink quickstarts can be found here: PicketLink Quickstarts.
+
+
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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-security-domain.clifile in the root of this quickstart directory. This script adds thepicketlink-stssecurity domain to thesecuritysubsystem in the server configuration and configures authentication access.
+ -
+
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 +
+
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:
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ - This deploys
target/picketlink-sts.warto 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.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:
+-
+
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type the following command:
+
+mvn exec:java +
+ - You should see a
<saml:Assertionassertion from PicketLink STS along with aBUILD SUCCESSprinted 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] ------------------------------------------------------------------------ +
+
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.
-
+
- Open a new command prompt, navigate to the root directory of this quickstart. +
- 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 +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+ - Stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile 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 JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts.
+-
+
- 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. +
- To deploy the server project, right-click on the
picketlink-stsproject and chooseRun As-->Run on Server.
+ - You are presented with a server message
PicketLinkSTSRealmand challenged to enter valid authentication credentials. Enter the following information and then clickOK. +
+UserName: JBoss + Password: JBoss +JBoss Developer Studio then displays the welcome file.
+
+ - Follow these steps to test the service.
+
-
+
- Right-click on the
picketlink-stsproject and chooseRun As-->Maven Build.
+ - Enter
picketlink-stsfor theName.
+ - Enter
exec:javafor theGoals:.
+ - Click
Run.
+ - Review the output in the console window. +
+ - Right-click on the
- To undeploy the project, right-click on the
picketlink-stsproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+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:
+-
+
- 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 +
Run the Client
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Make sure the
helloworld-rsquickstart has been deployed on the server as noted in the Prerequisites section above.
+ - Open a command prompt and navigate to the root directory of this quickstart. +
- Type the following command to run the client:
+
+mvn clean package exec:java +
+
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.
+-
+
-
+
Before you run this quickstart, be sure to import, deploy, and test the
+helloworld-rsquickstart as described in the Prerequisites section of this file.
+ -
+
Import this quickstart into JBoss Developer Studio.
+
+ -
+
Build and run the quickstart project.
+-
+
- Right-click on the
resteasy-jaxrs-clientproject and chooseRun As-->Maven build.
+ - Enter
clean package exec:javafor theGoals:and clickRun.
+ - The client output displays in the
Consolewindow.
+
+ - Right-click on the
- To undeploy the
helloworld-rsquickstart, right-click on thehelloworld-rsproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/servlet-async.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL http://localhost:8080/servlet-async/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/servlet-filterlistener.warto the running instance of the server.
+
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:
+-
+
- Enter some text in the field, for example:
+
+This is only a test! +
+ - Click Send. +
- The servlet filter intercepts and removes the vowels from the text entered in the form and displays:
+
+You Typed: Ths s nly tst! +
+ - The server console displays the following log messages. +
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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:
+-
+
- Web Application:
+
-
+
- Adds a security constraint to the Servlet using the
@ServletSecurityand@HttpConstraintannotations.
+ - Adds a security domain reference to
WEB-INF/jboss-web.xml.
+ - Adds a
login-configthat sets theauth-methodtoBASICin theWEB-INF/web.xml.
+
+ - Adds a security constraint to the Servlet using the
- Application Server (
standalone.xml): +-
+
- Defines a security domain in the
elytronsubsystem that uses the JDBC security realm to obtain the security data used to authenticate and authorize users.
+ - Defines an
http-authentication-factoryin theelytronsubsystem that uses the security domain created in step 1 for BASIC authentication.
+ - Adds an
application-security-domainmapping in theundertowsubsystem to map the Servlet security domain to the HTTP authentication factory defined in step 2.
+
+ - Defines a security domain in the
- 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 +
+
+ - Adds an application user with access rights to the 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 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.
-
+
-
+
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. +
+ -
+
Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-server.clifile in the root of this quickstart directory. This script adds security domain and HTTP authentication factory to theelytronsubsystem in the server configuration and also configures theundertowsubsystem to use the configured HTTP authentication factory for the Web application.
+ - 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 +
+ - 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 datasource was added to the
+datasourcessubsystem.
+<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> +
+ -
+
The following
+security-realmwas added to theelytronsubsystem.
+<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-realmis responsible for verifying the credentials for a given principal and for obtaining security attributes (like roles) that are associated with the authenticated identity.
+ -
+
The following
+role-decoderwas added to theelytronsubsystem.
+<simple-role-decoder name="from-roles-attribute" attribute="roles"/> +The
+jdbc-realmin this quickstart stores the roles associated with a principal in an attribute named roles. Other realms might use different attributes for roles (such asgroup). The purpose of arole-decoderis to instruct the security domain how roles are to be retrieved from an authorized identity.
+ -
+
The following
+security-domainwas added to theelytronsubsystem.
+<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> +
+ -
+
The following
+http-authentication-factorywas added to theelytronsubsystem.
+<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-sdsecurity domain to authenticate and authorize access to Web applications.
+ -
+
The following
+application-security-domainwas added to theundertowsubsystem.
+<application-security-domains> + <application-security-domain name="servlet-security-quickstart" http-authentication-factory="servlet-security-quickstart-http-auth"/> +</application-security-domains> +
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/servlet-security.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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 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
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile 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 JBoss EAP server, and build and deploy a quickstart, see 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 JBoss EAP Server. Stop the server at the end of that step. +
- 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
+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:
-
+
- A server side component:
+
This standalone Java EE module is a JAR containing EJBs. It is responsible for managing the shopping cart.
+
+ - A Java client:
+
This simple Java client is launched using a
+mainmethod. 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.
+
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.
+-
+
- 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. +
+ - Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - Review the
configure-system-exception.clifile in the root of this quickstart directory. This script sets thelog-system-exceptionsattribute tofalsein theejb3subsystem in the server configuration file.
+ -
+
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 +
+ - 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.
You should see the following configuration in the ejb3 subsystem.
<log-system-exceptions value="false"/>
+Start the Server
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
-
+
Make sure you have started the JBoss EAP server. See the instructions in the previous section.
+
+ -
+
Open a command prompt and navigate to the
+shopping-cartquickstart directory
+ - 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 +
+ - 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") +
+
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:
+-
+
- The client sends a remote method invocation to the stateful session bean to buy two
32 GB USB 2.0 Flash Driveand oneWireless Ergonomic Keyboard and Mouse.
+ - The client sends a remote method invocation to get the contents of the cart and prints it to the console. +
- The client sends a remote method invocation to invoke checkout. Note the
checkout()method in the serverShoppingCartBeanhas the@Removeannotation. This means the container will destroy shopping cart after the call and it will no longer be available.
+ - The client calls
getCartContents()to make sure the shopping cart was removed after checkout. This results in ajavax.ejb.NoSuchEJBExceptiontrace in the server, proving the cart was removed.
+
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
+-
+
- Start the JBoss EAP server by typing the following:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+ - 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 +
+
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
+-
+
- If it is running, stop the JBoss EAP server. +
- Replace the
EAP7_HOME/standalone/configuration/standalone.xmlfile with the back-up copy of the file.
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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-serverproject and chooseRun As-->Run on Server.
+ - To run the client, right-click on the
shopping-cart-clientproject and chooseRun As-->Java Application. In theSelect Java Applicationwindow, chooseClient - org.jboss.as.quickstarts.clientand clickOK. The client output displays in theConsolewindow.
+ - To undeploy the project, right-click on the
shopping-cart-serverproject and chooseRun As-->Maven build. Enterwildfly:undeployfor theGoalsand clickRun.
+ - 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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- 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 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
+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 insrc/main/webapp/WEB-INF/spring-mvc-context.xmltells Spring to look for@RequestMappingin our controllers.
+- Spring then routes the HTTP requests to the correct methods in
CreateController.javaandGreetController
+
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:
+-
+
- Enter a name in the username field and click on Greet!. +
- If you enter a username that is not in the database, you get a message No such user exists!. +
- If you enter a valid username, you get a message "Hello, " followed by the user's first and last name. +
- 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. +
- Click on the Greet a user! link to return to the Greet! page. +
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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server with the default profile:
+
+For Linux: bin/standalone.sh +For Windows: bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive: mvn clean package wildfly:deploy +
-
+
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 EAP7_HOME/standalone/deployments.
+Access the application
+The application will be running at the following URL: http://localhost:8080/spring-greeter/
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- 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 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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 +
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/spring-kitchensink-asyncrequestmapping.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/spring-kitchensink-asyncrequestmapping/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 +
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/spring-kitchensink-basic.warto the running instance of the server.
+
Access the application
+The application will be running at the following URL: http://localhost:8080/spring-kitchensink-basic/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 +
+
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
+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,@InitBinderand@ModelAttributeto 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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/spring-kitchensink-controlleradvice.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/spring-kitchensink-controlleradvice/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 +
+
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
+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@MatrixVariablewe must set theremoveSemicolonContentproperty ofRequestMappingHandlerMappingtofalse. 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 theremoveSemicolonContentproperty tofalse.
+ -
+
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.jspwhich allows the user to filter the member list. The form is submitted in the url form:/filter;n=Name;e=Email.
+ -
+
Using
+@MatrixVariablethe 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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/spring-kitchensink-matrixvariables.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/spring-kitchensink-matrixvariables/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 +
+
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
+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.javato showcase a use case ofMockMVCandRestTemplateto test the MVC aspect of the application.
+ -
+
By using
+@WebAppConfigurationand@ContextConfigurationwe 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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/spring-kitchensink-springmvctest.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/spring-kitchensink-springmvctest/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 +
+
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
+CHANGES TO SPRING PETCLINIC EXAMPLE
+ORIGINAL SOURCE
+ +CHANGES
+-
+
- 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.
+ - Configured to use Red Hat JBoss EAP BOMs. +
- Regressed the jQuery version to 1.9 as that is what is currently certified on EAP. +
- Add plug-in to deploy directly to running JBoss from mvn build. +
- Add OpenShift support. +
- Add Apache license text. +
- Regress Hibernate core to 4.2.7.SP1 or before to ensure that it runs on EAP 7. +
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.xmlpulls insrc/main/resources/spring/data-access.propertiesto set the JDBC-related settings for the JPA EntityManager definition. +-
+
- A simple comment change in
data-access.propertiesswitches between the data access strategies.
+
+ - A simple comment change in
- In
webapp/WEB_INF/web.xmlthe<param-name>spring.profiles.active</param-name>using<param-value>jpa</param-value>(as the default) refers to the bean to be used insrc/main/resources/spring/business-config.xml. +-
+
- Setting the
<param-value>tojdbc,jpa, orspring-data-jpais all that is needed to change the DAO implementation.
+
+ - Setting the
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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This will deploy
+spring-petclinic/target/spring-petclinic.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- If the application is still deployed from the previous section, undeploy it now.
+
+mvn wildfly:undeploy +
+ - Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 +
+ -
+
The
+spring-petclinicquickstart contains three configurations: JDBC, JPA, and Spring Data JPA. You should see the tests run 3 times, one for each configuration.
+ -
+
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
+Errormenu 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) +
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ -
+
This deploys the
+target/spring-resteasy.warto the running instance of the server.
+
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.
+-
+
- spring-resteasy/hello?name=yourname +
- spring-resteasy/basic +
- spring-resteasy/queryParam?param=query +
- spring-resteasy/matrixParam;param=matrix +
- spring-resteasy/uriParam/789 +
And the same set as above but using the locating path.
-
+
- spring-resteasy/locating/hello?name=yourname +
- spring-resteasy/locating/basic +
- spring-resteasy/locating/queryParam?param=query +
- spring-resteasy/locating/matrixParam;param=matrix +
- spring-resteasy/locating/uriParam/789 +
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Open a command line and navigate to the root directory of this quickstart. +
- Build the quickstart WAR using the following command:
+
+mvn clean package +
+ -
+
Navigate to the functional-tests/ directory in this quickstart.
+
+ - 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 +
+ -
+
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 +
+
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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/tasks-jsf.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/tasks-rs.warto the running instance of the server.
+
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
-iflag tells cURL to print the returned headers.
+ - The
-uflag provides the authentication information for the request.
+ - The
-Hflag adds a header to the outgoing request.
+ - The
-Xflag tells cURL which HTTP method to use. The HTTP POST is used to create resources.
+ - The
Locationheader 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.
-
+
- To issue a GET using a browser, open a browser and access the URI. You will be challenged to enter valid authentication credentials. + + +
- 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
+-Hflag tells the server that the client wishes to accept XML content.
+
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.
-
+
-
+
To issue a GET using a browser, open a browser and access the following URL. You will be challenged to enter valid authentication credentials.
+ +
+ -
+
To list all tasks associated with the user
+quickstartUserusing cURL, type:
+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:
+<?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::
-
+
-
+
Open the
+pom.xmlfile and remove the comments from the dependency with artifactIdresteasy-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> +--> +
+ -
+
Open the
+src/main/java/org/jboss/as/quickstarts/tasksrs/model/Task.javafile and remove the comments from the following two lines.
+// import com.fasterxml.jackson.annotation.JsonIgnore; + +// @JsonIgnore +
+ -
+
Open the
+src/main/java/org/jboss/as/quickstarts/tasksrs/service/TaskResource.javafile 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" }) +
+
+ - Remove comments from this line:
+
- Rebuild and redeploy the quickstart. +
-
+
Create a Task as you did for the XML version of this quickstart.
+
+ -
+
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 +
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- 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 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
+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:
+-
+
- The User Interface is a JSF page that asks for a temperature and a scale (Fahrenheit or Celsius). +
- When you click on
Convert, the temperature string is passed to the TemperatureConverter controller (managed) bean.
+ - The managed bean then invokes the
convert()method of the injected TemperatureConvertEJB (notice the field annotated with @Inject).
+ - The response from TemperatureConvertEJB is stored in the
temperaturefield of the managed bean.
+ - The managed bean is annotated as @SessionScoped, so the same managed bean instance is used for the entire 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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/temperature-converter.warto the running instance of the server.
+
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.
+-
+
- Optionally, Select a scale: Celsius or Fahrenheit. +
- Enter a temperature. +
- Press the
Convertbutton to see the results.
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/thread-racing.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ - This will deploy
target/websocket-client.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command line and navigate to the root of the JBoss EAP directory. +
- 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 +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command line and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean package wildfly:deploy +
+ - This will deploy
target/websocket-endpoint.warto the running instance of the server.
+
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
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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.xmlfile 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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/websocket-hello.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/websocket-hello/.
+-
+
- Click on the
Open Connectionbutton to create the WebSocket connection and display current status ofOpen.
+ - Type a name and click
Say Helloto create and send theSay hello to <NAME>message. The message appears in the server log and a response is sent to the client.
+ - Click on the
Close Connectionbutton to close the WebSocket connection and display the current status ofClosed.
+ - 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. +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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:
-
+
- A new Atomic Transaction (AT) is created by the client. +
- An operation on a WS-AT enabled Web service is invoked by the client. +
- The JaxWSHeaderContextProcessor in the WS Client handler chain inserts the WS-AT context into the outgoing SOAP message +
- 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. +
- The Web service operation is invoked... +
- A participant is enlisted in this AT. This allows the Web Service logic to respond to protocol events, such as Commit and Rollback. +
- The service invokes the business logic. In this case, a booking is made with the restaurant. +
- 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. +
- 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. +
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type the following command to run the test goal with the following profile activated:
+
+mvn clean verify -Parq-remote +
+ -
+
You should see the following result.
+
+Results : + +Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 +
+
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.
+-
+
- Import the quickstart into JBoss Developer Studio. +
- If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration.
+
-
+
- In the
Servertab, right-click and chooseNew-->Server.
+ - Under
Select the server type:, expandRed Hat JBoss Middlewareand chooseRed Hat JBoss Enterprise Application Platform 7.x.
+ - For the
Server name, enterJBoss EAP XTS Configurationand clickNext.
+ - In the
Create a new Server Adapterdialog, chooseCreate a new runtime (next page)and clickNext.
+ - In the
JBoss Runtimedialog, enter the following information and then clickFinish. +
+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 +
+
+ - In the
-
+
Start the new
+JBoss EAP XTS Configurationserver.
+ - Right-click on the
wsat-simpleproject, chooseRun As-->Maven build, enterclean verify -Parq-remotefor theGoals:, and clickRunto run the Arquillian tests. The test results appear in the console.
+
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
+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:
-
+
- A new Business Activity is created by the client. +
- Multiple operations on a WS-BA enabled Web service is invoked by the client. +
- The
JaxWSHeaderContextProcessorin the WS Client handler chain inserts the BA context into the outgoing SOAP messages.
+ - When the service receives a SOAP request, the
JaxWSHeaderContextProcessorin its handler chain inspects the BA context and associates the request with this BA.
+ - The Web service operation is invoked. +
- 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. +
- The service invokes the business logic. In this case, a String value is added to the set. +
- The client can then make additional calls to the
SetService. As theSetServiceparticipates as aCoordinatorCompletionprotocol, it will continue to accept calls toaddValueToSetuntil it is told to complete by the coordinator.
+ - 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. +
+
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type the following command to run the test goal with the following profile activated:
+
+mvn clean verify -Parq-remote +
+ -
+
You should see the following result.
+
+Results : + +Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 +
+
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.
+-
+
- Be sure to import the quickstart into JBoss Developer Studio. +
- If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration.
+
-
+
- In the
Servertab, right-click and chooseNew-->Server.
+ - Under
Select the server type:, expandRed Hat JBoss Middlewareand chooseRed Hat JBoss Enterprise Application Platform 7.x.
+ - For the
Server name, enterJBoss EAP XTS Configurationand clickNext.
+ - In the
Create a new Server Adapterdialog, chooseCreate a new runtime (next page)and clickNext.
+ - In the
JBoss Runtimedialog, enter the following information and then clickFinish. +
+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 +
+
+ - In the
-
+
Start the new
+JBoss EAP XTS Configurationserver.
+ - Right-click on the
wsba-coordinator-completion-simpleproject, chooseRun As-->Maven build, enterclean verify -Parq-remotefor theGoals:, and clickRunto run the Arquillian tests. The test results appear in the console.
+
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
+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:
+-
+
- A new Business Activity is created by the client. +
- An operation on a WS-BA enabled Web service is invoked by the client. +
- The
JaxWSHeaderContextProcessorin the WS Client handler chain inserts the BA context into the outgoing SOAP message.
+ - When the service receives the SOAP request, the
JaxWSHeaderContextProcessorin its handler chain inspects the BA context and associates the request with this BA.
+ - The Web service operation is invoked. +
- A participant is enlisted in this BA. This allows the Web Service logic to respond to protocol events, such as compensate and close. +
- The service invokes the business logic. In this case, a String value is added to the set. +
- 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. +
- 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
ParticipantCompletionprotocol.
+ - 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. +
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.
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type the following command to run the test goal with the following profile activated:
+
+mvn clean verify -Parq-remote +
+ -
+
You should see the following result.
+
+Results : + +Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 +
+
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.
+-
+
- Import the quickstart into JBoss Developer Studio. +
- If you have not already done so, you must configure a new JBoss EAP server to use the XTS configuration.
+
-
+
- In the
Servertab, right-click and chooseNew-->Server.
+ - Under
Select the server type:, expandRed Hat JBoss Middlewareand chooseRed Hat JBoss Enterprise Application Platform 7.x.
+ - For the
Server name, enterJBoss EAP XTS Configurationand clickNext.
+ - In the
Create a new Server Adapterdialog, chooseCreate a new runtime (next page)and clickNext.
+ - In the
JBoss Runtimedialog, enter the following information and then clickFinish. +
+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 +
+
+ - In the
-
+
Start the new
+JBoss EAP XTS Configurationserver.
+ - Right-click on the
wsba-participant-completion-simpleproject, chooseRun As-->Maven build, enterclean verify -Parq-remotefor theGoals:, and clickRunto run the Arquillian tests. The test results appear in the console.
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/xml-dom4j.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/xml-dom4j/.
+Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+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
+-
+
- Open a command prompt and navigate to the root of the JBoss EAP directory. +
- The following shows the command line to start the server:
+
+For Linux: EAP7_HOME/bin/standalone.sh +For Windows: EAP7_HOME\bin\standalone.bat +
+
Build and Deploy the Quickstart
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- Type this command to build and deploy the archive:
+
+mvn clean install wildfly:deploy +
+ -
+
This will deploy
+target/xml-jaxp.warto the running instance of the server.
+
Access the Application
+The application will be running at the following URL: http://localhost:8080/xml-jaxp/.
+To test the quickstart, follow these steps.
+-
+
- Click the
Browsebutton and navigate to theQUICKSTART_HOME/src/main/resources/catalog.xmlfile.
+ - Click the
Uploadbutton. The XML file content is parsed and displayed on the page.
+ - 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! +
+
To enable the alternative SAXXMLParser parser:
+-
+
- Remove the comments that surround the alternate parser element in the
WEB-INF/beans.xmlfile.
+ - Redeploy the application using the instructions above and access the application in a browser at the following URL: http://localhost:8080/xml-jaxp/. +
- Click the
Browsebutton and navigate to theQUICKSTART_HOME/src/main/resources/catalog.xmlfile.
+ - Click the
Uploadbutton. The XML file content is parsed and displayed on the page.
+ - 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! +
+
Undeploy the Archive
+-
+
- Make sure you have started the JBoss EAP server as described above. +
- Open a command prompt and navigate to the root directory of this quickstart. +
- When you are finished testing, type this command to undeploy the archive:
+
+mvn wildfly:undeploy +
+
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
+