The app-client quickstart demonstrates how to code and package a client app and use the WildFly client container to start the client Main program.

What is it?

The app-client quickstart demonstrates how to use the WildFly client container to start the client Main program and provide Dependency Injections (DI) for client applications in WildFly Application Server. It also shows you how to use Maven to package the application according to the Jakarta EE specification.

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

Project Description

ejb

This project contains the EJB code that can be called by the client.

client-simple

This project contains a simple client application that runs in the application-client container to show the injection.

ear

This project builds the EAR artifact and pulls in the EJB and client artifacts.

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 WildFly Application Server 20 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 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.

Add the Authorized Application and Management Users

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!

quickstartAdmin

ManagementRealm

adminPwd1!

To add the application user, open a terminal and type the following command:

$ WILDFLY_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' 
$ WILDFLY_HOME/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!'
Note
 For Windows, use the WILDFLY_HOME\bin\add-user.bat script.

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 WildFly Standalone Server

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

  2. Start the WildFly server with the default profile by typing the following command.

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

Build and Deploy the Quickstart

  1. Make sure you start the WildFly server as described above.

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

  3. Type the following command to build the artifacts.

    $ mvn clean install wildfly:deploy

This deploys the app-client/ear/target/app-client.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 from the Same Machine

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

  1. Verify that the quickstart deployed successfully as described above.

  2. Navigate to the root directory of this quickstart and type the following command to run the application. Make sure you replace WILDFLY_HOME with the path to your WildFly installation.

    $ WILDFLY_HOME/bin/appclient.sh ear/target/app-client.ear#simpleClient.jar Hello from command line
    Note
    		 For Windows, use the WILDFLY_HOME\bin\appclient.bat script.

  3. Review the result. The client outputs the following information, which is 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

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

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

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

Access the Remote Client Application from a Different Machine

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

Configure Machine_1 (Remote Server Machine)

  1. Install WildFly on this machine.

  2. Add the authorized application and management users to the WildFly server on this machine as described above.

  3. Start the WildFly server with the following command, replacing MACHINE_1_IP_ADDRESS with the IP address of this machine. These arguments make the server accessible to the network.

    $ WILDFLY_HOME/bin/standalone.sh -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS
    Note
    		 For Windows, use the WILDFLY_HOME\bin\standalone.bat script.

Configure Machine_2 (Local Client Machine)

  1. Install WildFly on this server. There is no need to add the application users to this server.

  2. Download the app-client quickstart to this machine.

  3. Create a jboss-ejb-client.properties file. This file can be located anywhere in the file system, but for ease of demonstration, we create it in the root directory of this quickstart. Add the following content, replacing MACHINE_1_IP_ADDRESS with the IP address of Machine_1.

    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=quickstartUser
remote.connection.default.password=quickstartPwd1!

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

  5. Deploy the app-client quickstart to the remote machine using the following command. Make sure you replace MACHINE_1_IP_ADDRESS with the IP address of Machine_1.

    $ mvn clean install wildfly:deploy -Dwildfly.hostname=MACHINE_1_IP_ADDRESS [-Dwildfly.port=9099] -Dwildfly.username=quickstartAdmin -Dwildfly.password=adminPwd1!

  6. Verify that the quickstart deployed successfully and the server is running on Machine_1 as described above.

  7. Type the following command to run the app-client application.

    $ WILDFLY_HOME/bin/appclient.sh --ejb-client-properties=ejb-client.properties ear/target/app-client.ear#simpleClient.jar Hello from command
    Note
    		 For Windows, use the WILDFLY_HOME\bin\appclient.bat script.

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

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

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

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

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

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

Undeploy the Archive from the Local Machine

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

  1. Make sure you have started the WildFly server on the machine where the quickstart is deployed as described above.

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

  3. When you are finished testing, type this command to undeploy the archive from the local machine.

    $ mvn wildfly:undeploy

Undeploy the Archive from the Remote Machine

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

  1. Make sure you have started the WildFly server on the remote server machine, Machine_1, where the quickstart is deployed as described above.

  2. Open a terminal on the local client machine, Machine_2, and navigate to the root directory of this quickstart.

  3. When you are finished testing, type this command to undeploy the archive from the remote server machine, Machine_1.

    $ mvn wildfly:undeploy -Dwildfly.hostname=MACHINE_1_IP_ADDRESS [-Dwildfly.port=9099] -Dwildfly.username=quickstartAdmin -Dwildfly.password=adminPwd1!