Two steps are required to enable a Java application to become a JBoss client. You have to include the required libraries in the classpath of your application and you have to configure the Java Naming and Directory Service (JNDI) appropriately:
Required libraries
To get started, it suffices to include the library JBOSS_HOME/client/jbossall-client.jar
in the classpath of your application.
JNDI configuration
EJB components as well as other components/objects are looked up via the JNDI by using an InitialContext. However, the JNDI has to be configured appropriately to let the client access the JNDI provided by the JBoss AS. For JBoss, you have to specify the following properties with the given values:
java.naming.factory.initial = org.jnp.interfaces.NamingContextFactory
#Change the following IP address according to your settings
java.naming.provider.url = jnp://127.0.0.1:1099
java.naming.factory.url.pkgs = org.jboss.naming.client
The specification of these properties can be performed in three different ways:
- Create a file named
jndi.properties
in the root of your application's classpath. - Set the required properties via
System.setProperty(...)
- Put the required properties in a Hashtable and pass it to the constructor of the
InitialContext
.
After that, JNDI lookups should work correctly.
JBoss configuration
Configuration of JBoss is not trivial because of the huge amount of configuration options. However, your primary configuration directory will most probably be the JBOSS_HOME/server/{profile}/deploy
directory. Within this directory, you might want to configure data sources etc.
If you are interested in the Java Messaging Service (JMS), you should have a look at the file JBOSS_HOME/server/{profile}/deploy/jms/jbossmq-destinations-service.xml
in order to get started with your own definition of queues or topics.
The configuration directory for JBoss itself is located under JBOSS_HOME/server/{profile}/conf
. However, you will most probably not have to change the files contained in this directory.
Running JBoss
Running JBoss is simple: Open a console window, change to the directory JBOSS_HOME/bin
and execute run.bat
or run.sh
. This will run the default profile in the directory JBOSS_HOME/server/default
. To run an other profile, e.g. "all" located under JBOSS_HOME/server/all
, execute run.sh -c all
for Linux or run.bat -c all
on Windows.
Developing Java enterprise applications
You can greatly benefit from an Integrated Development Environment with support for developing Java Enterprise Applications. NetBeans is an excellent free and open source solution with support for the JBoss AS. If you use NetBeans, preferably run JBoss outside the IDE as it otherwise becomes slow. However, you are still able to debug your applications in this case -- see below. Alternatively, you may want to have a look at the JBoss Tools plugin for Eclipse.
Deploying an application
To deploy Java Enterprise Application, just copy the file (*.jar, *.ear, *.war, etc.) to the JBOSS_HOME/server/{profile}/deploy
directory. JBoss will automatically detect this and deploy your application.
JBoss debugging
Although the following text is written for the NetBeans development environment, the steps are generally applicable to other development environments as well.
To enable the debugging of components running in JBoss (e.g., EJBs) or even JBoss itself, move to the JBOSS_HOME/bin directory and open "run.bat" or "run.conf" (depending on whether you are using Windows or Linux). Within this file, activate a line that reads like: "set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n %JAVA_OPTS%"
. This line specifies that a debugger can be attached to the Java Virtual Machine (JVM) via port 8787. Take care that you set suspend=n. Otherwise, the JVM and hence JBoss will only start running after a debugger is attached to the JVM.
To attach the NetBeans debugger to the JVM, follow the menu entries "Run –> Attach debugger ...", provide the right configuration parameters and confirm. After the debugger is attached to the JVM, NetBeans will already stop program execution at defined breakpoints. However, in order to successfully step through the source code, make sure you include the required libraries for your NetBeans project, e.g. jbossall-client.jar, log4j-*.jar, commons-logging-*.jar, etc. If you have difficulties in debugging – for example, setting breakpoints works but you cannot step through the code with single-stepping (F7 or F8) – please make sure you included all required sources and libraries within your NetBeans project. Debugging does not work for sources where the required libraries are not correctly configured.