The ejb-multi-server quickstart shows how to communicate between multiple applications deployed to different servers using an EJB to log the invocation.

What is it?

The ejb-multi-server quickstart demonstrates communication between applications deployed to different WildFly Application Server 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:

Project Description

app-main

An application that can be called by the client. It can also call the different sub-applications.

app-one

app-two

These simple applications contain an EJB subproject that builds the ejb.jar file and an EAR subproject that builds 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.

Browse the source

System Requirements

The application this project produces is designed to be run on WildFly Application Server 33 or later.

All you need to build this project is Java 11.0 (Java SDK 11) or later and Maven 3.6.0 or later. See Configure Maven to Build and Deploy the Quickstarts to make sure you are configured correctly for testing the quickstarts.

Use of the WILDFLY_HOME and QUICKSTART_HOME Variables

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

When you see the replaceable variable QUICKSTART_HOME, replace it with the path to the root directory of all of the quickstarts.

Start with a Clean Server Install

It is important to start with a clean version of WildFly before testing this quickstart. Make sure you unzip or install a fresh WildFly instance.

Add the Application Users

The following users must be added to the ApplicationRealm to run this quickstart. Make sure you 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

quickuser1

ApplicationRealm

quick123+

quickuser2

ApplicationRealm

quick+123

To add the users, open a terminal and type the following commands.

$ WILDFLY_HOME/bin/add-user.sh -a -u quickuser -p quick-123
$ WILDFLY_HOME/bin/add-user.sh -a -u quickuser1 -p quick123+
$ WILDFLY_HOME/bin/add-user.sh -a -u quickuser2 -p quick+123
Note
 For Windows, use the WILDFLY_HOME\bin\add-user.bat script.

Back Up the WildFly Managed Domain Configuration

Before you begin, back up your server configuration files.

  1. If it is running, stop the WildFly server.

  2. Back up the following files:

    WILDFLY_HOME/domain/configuration/domain.xml
WILDFLY_HOME/domain/configuration/host.xml

After you have completed testing this quickstart, you can replace these file to restore the server to its original configuration.

Start the WildFly Managed Domain

  1. Open a terminal and navigate to the root of the WildFly directory.

  2. Start the WildFly managed domain by typing the following command.

    $ WILDFLY_HOME/bin/domain.sh
    Note
    		 For Windows, use the WILDFLY_HOME\bin\domain.bat script.

Configure the Server

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

  1. Before you begin, make sure you do the following:

  2. Review the install-domain.cli file in the root of this quickstart directory. This script configures and starts multiple servers needed to run this quickstart.

  3. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing WILDFLY_HOME with the path to your server:

    $ WILDFLY_HOME/bin/jboss-cli.sh -c --file=install-domain.cli
    Note
    		 For Windows, use the WILDFLY_HOME\bin\jboss-cli.bat script.

    You should see a result of "outcome" ⇒ "success" for every step in the execution.

    Important
    		 Depending on your machine configuration, you might 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, you must reboot and start with a fresh instance of the server.

Review the Modified Server Configuration

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

Build and Deploy the Quickstart

  1. Make sure WildFly server is started.

  2. Open a terminal and navigate to the root directory of this quickstart.

  3. Type the following command to build the quickstart.

    $ mvn clean install

  4. Type the following command to deploy the quickstart.

    $ mvn wildfly:deploy

This deploys the ejb-multi-server/ear/target/ejb-multi-server.ear to the running instance of the server.

You should see a message in the server log indicating that the archive deployed successfully.

Access the Remote Client Application

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

  1. Make sure that the deployments are successful as described above.

  2. Navigate to the quickstart client/ subdirectory.

  3. Type this command to run the application:

    $ mvn exec:java

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

    InvokeAll succeed: MainApp[quickuser]@primary:app-main  >  [ app1[quickuser1]@primary:app-oneA > app2[quickuser2]@primary:app-twoA ; app2[quickuser2]@primary:app-twoA

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

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

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

    java -cp $WILDFLY_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
Important

  • If exec is called multiple times, the invocation for app1 might use app-oneA and app-oneB node due to cluster loadbalancing.

  • A WildFly will deny the invocation of unsecured methods of appOne/appTwo since security is enabled but the method does not include @Roles. You need to set default-missing-method-permissions-deny-access = false for the ejb3 subsystem within the domain profile ha and default to allow the method invocation. See the install-domain.cli script.

Access the JSF Application Inside the Main Application

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

  1. Make sure that the deployments are successful as described above.

  2. Use a browser to access the JSF application at the following URL: http://localhost:8080/ejb-multi-server-app-main-web/

  3. Insert a message in the Text input and invoke the different methods. The result is shown in the browser.

  4. 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.

  1. Make sure that the deployments are successful as described above.

  2. Use a browser to access the Servlet at the following URL: http://localhost:8380/ejb-multi-server-app-web/

  3. The Servlet will invoke the remote EJBs directly and show the results, compare that the invocation is successful

Run the Integration Tests

This quickstart includes integration tests, which are located under the app-web/src/test/ directory. The integration tests verify that the quickstart runs correctly when deployed on the server.

Follow these steps to run the integration tests.

  1. Make sure WildFly server is started.

  2. Make sure the quickstart is deployed.

  3. Type the following command to run the verify goal with the integration-testing profile activated.

    $ mvn verify -Pintegration-testing

Undeploy the Quickstart

When you are finished testing the quickstart, follow these steps to undeploy the archive.

  1. Make sure WildFly server is started.

  2. Open a terminal and navigate to the root directory of this quickstart.

  3. Type this command to undeploy the archive:

    $ mvn wildfly:undeploy

Restore the WildFly Managed Domain Configuration Manually

When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copies the configuration files.

  • If it is running, stop the WildFly server.

  • Replace the following files with the backup copies of the files.

    WILDFLY_HOME/domain/configuration/domain.xml
WILDFLY_HOME/domain/configuration/host.xml

WildFly for OpenShift Incompatibility

This quickstart is not compatible with WildFly for OpenShift.