JBoss.org Community Documentation

Chapter 4. Using services

4.1. Bootstrapping the microcontainer
4.2. Deploying the service
4.3. Direct access
4.4. Indirect access
4.5. Dynamic classloading

In the previous chapter we looked at how to create, configure, test and package a service. It is now time to move on and create a client so that we can use the service to perform actual work.

In order to keep things simple the client uses a Text User Interface (TUI) to accept input from the user and output results. In the real-world a Graphical User Interface (GUI) would almost certainly be used but here we are more concerned with demonstrating how the client interacts with the service than showing how to develop a rich desktop application.

You will find all of the necessary files in the examples/User_Guide/gettingstarted/commandLineClient directory. As with the previous example this follows the Maven Standard Directory Layout:


The client consists of 3 classes and 1 interface, located in the src/main/java directory:


UserInterface describes methods that the client will call at runtime to request data from the user. ConsoleInput is an implementation of this that creates a TUI allowing the user to operate the client from the command line. The advantage of this design is that we can easily create a Swing implementation of UserInterface at a later date and replace the TUI with a GUI if we decide to improve usability. We can also create a mock implementation for testing purposes that simulates a user entering data. This allows us to check the behaviour of the client automatically using conventional JUnit test cases as demonstrated by the code in the src/test/java directory:


To compile the source code, run the unit tests, build a client JAR and assemble a distribution containing all of the necessary files simply type mvn package from the commandLineClient directory.


For the build to work you must first have built and installed auditAspect.jar from the examples/User_Guide/gettingStarted/auditAspect directory using the mvn install command. This is because we actually create a number of different client distributions including one based on AOP which relies on auditAspect.jar being available in the local maven repositiory.

If you previously typed mvn install from the examples/User_Guide/gettingStarted directory then you will have already built and installed humanResourcesService.jar together with auditAspect.jar and the client will have already been packaged so this step will not be necessary.

Once you have successfully compiled and packaged the client you will find the following subdirectories in the commandLineClient/target directory:

Each of these represents a different distribution containing all of the shell scripts, JARs, and XML deployment descriptors that we need to run the client in different configurations. For the moment we will use the client-pojo distribution which can be found in the client-pojo.dir subdirectory:


To run the client simply cd into client-pojo.dir and type ./run.sh. You will then be presented with the following menu of options:

To select an option enter the letter shown on the left-hand side and press return. For example to redisplay the menu options enter 'm' followed by return. This is useful if they scroll off the top of the screen as you input data and read results. Entering more than one letter or entering an invalid option will result in an appropriate error message.


The run.sh script sets up the runtime environment by adding all of the JARs found in the lib directory to the classpath using the java.ext.dirs system property. It also adds the current directory and the client-1.0.0.jar using the -cp flag so that the jboss-beans.xml deployment descriptor can be found at runtime together with the org.jboss.example.client.Client class which is called to start the application.