This page shortly introduces to the JBoss Application Server (JBoss AS) and Enterprise JavaBeans (EJB) and should allow you to setup the server, run the examples, and start developing Java enterprise applications. JBoss AS is an open source Java Application Server for the Java Platform, Enterprise Edition (Java EE). Enterprise JavaBeans (EJBs) are part of Java EE. If you are just getting started with EJB, the book Mastering Enterprise JavaBeans is certainly a good starting point for you.

This introduction is based on versions 4.0.x of the JBoss AS but might work for other versions as well.

Client setup

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:

1. Create a file named jndi.properties in the root of your application's classpath.
2. Set the required properties via System.setProperty(...)
3. 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 IDE plugin for Eclipse.

Deploying an application

To deploy Java Enterprise Application, just copy the file (*.jar, *.ear, *.ware, 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.

Database Manager

JBoss includes the HSQLDB Database. The easiest way to manually query this database is to open the Hypersonic Database Manager via the Java Management Extensions (JMX) Console of the JBoss AS found at http://localhost:8080/jmx-console/. To start the database manager, search for the word "Hypersonic" and click on the corresponding link. Thereafter, search for the word "startDatabaseManager()" and click on the corresponding "Invoke" button. After this, the database manager should show up and you can query the database via SQL statements.

• Mastering Enterprise JavaBeans 3.0 and probably Mastering Enterprise JavaBeans for EJB2.1
  
• Java Enterprise Edition tutorial
• The JBoss 4 Application Server Guide