a s k e s i s
Askesis start >  Documentation >  Software index >  JBoss

Description

JBoss is an open source J2EE application server. It provides an infrastructure for deploying J2EE application files (EAR). It is bundled with either the Jetty (default) or the Tomcat webcontainer, and so can also be used for deploying web application files (WAR).

Files

There are several stable versions available. The current version is 3.2.1, which can be downloaded with Jetty or with Tomcat as webcontainer.

Installation

The basic installation of JBoss consists of unzipping the downloaded archive into a directory and setting the environment variable JBOSS_HOME to point to the base directory of the unzipped distribution. It can then be started by running the "run script" in the bin subdirectory. The only other prerequisite is that you have the environment variable JAVA_HOME set to your java installation directory.

Configuration

The following configuration items are available:

Running JBoss as a service or deamon

After installing JBoss by unzipping the binary distribution (or after compiling JBoss from a source distribution) JBoss is ready to run. However you must start JBoss from the command prompt yourself. To solve this problem, you can start JBoss as a deamon (Linux) or as a service (Windows NT/2k/XP) so that upon system bootup, JBoss will be started.

JBoss service on Windows

On Windows, JBoss can be installed as a service, so that it will be automatically started upon system startup. For this, you'll need the JavaService program. Install it in a directory in your path, along with a batch file containing this: 

@echo off

if "%1" == "uninstall" goto uninstall
if "%1" == "-uninstall" goto uninstall
if "%1" == "" goto usage
if "%2" == "" goto usage
if "%3" == "" goto usage
if "%1" == "-help" goto usage
if "%1" == "-?" goto usage
if "%1" == "/?" goto usage

:install
JavaService.exe \
-install JBoss30 %1\jre\bin\%3\jvm.dll \
-Djava.class.path=%1\lib\tools.jar;%2\bin\run.jar \
-start org.jboss.Main \
-stop org.jboss.Main \
-method systemExit \
-out %2\bin\out.txt \
-current %2\bin
goto eof

:uninstall
JavaService.exe -uninstall JBoss30
goto eof

:usage
echo ************** To install JBoss 3.0 as a service ***********
echo Installation:
echo   %0 jdk_home jboss_home (classic/hotspot/server)
echo   ---
echo   Example: %0 c:\jdk1.3.1 c:\jboss-3.0.0 server
echo   Do NOT use a pathname with spaces!
echo De-installation:
echo   %0 uninstall
goto eof

:eof

You can now run this batch file with the appropriate arguments to install the service. Once the service is succesfully installed, you should be able to start it from the services control panel (or reboot your machine to have it start automatically).

JBoss deamon on Linux (RedHat 8.0)

On Linux, JBoss can be installed as a daemon, so that it will be automatically started upon system startup. The description that followes assumes that you use RedHat. For this, you'll need two scripts. The first script, jboss, is the script that will be installed in the /etc/init.d/ directory. Manually or by using the chkconfig tool you can create links in the rcX.d directories, depending on youre needs. The second script, go.sh, must be copied into the $JBOSS_ROOT/bin directory. The jboss script depends on the go.sh script to do the actual startup. Both scripts are taken from the jBoss Quick Start book which is downloadable from the same place you downloaded JBoss from.

The jboss script 

#!/bin/sh
#
# Startup script for JBOSS, the J2EE EJB Server
#
# chkconfig: 2345 95 15
# description: JBoss is an EJB Server
# processname: jboss
# pidfile: /var/run/jboss.pid
# config: /usr/local/jboss/conf/default/jboss.conf
# logfile: /usr/local/jboss/log/server.log
#
# version 1.0 -
# version 1.1 - kjenks - Start Tomcat, too.
#

# Source function library.
. /etc/rc.d/init.d/functions

# change this according to your own situation
export JAVA_HOME=/usr/local/java/j2sdk1.4.1_01
export JBOSS_HOME=/usr/local/java/jboss-3.0.4_jetty
export PATH=$PATH:$JBOSS_HOME/bin:$JAVA_HOME/bin:$JAVA_HOME/jre/bin

RETVAL=0

# See how we were called.
case "$1" in
        start)
                cd $JBOSS_HOME/bin
                echo -n "Starting jboss daemon: "
                daemon $JBOSS_HOME/bin/go.sh start
                RETVAL=$?
                echo
                [ $RETVAL -eq 0 ] && touch /var/lock/subsys/jboss
                ;;
        stop)
                echo -n "Stopping jboss daemon: "
                killproc jboss
                RETVAL=$?
                echo
                [ $RETVAL -eq 0 ] && rm -f /var/lock/subsys/jboss
                ;;
        restart)
                echo -n "Restarting jboss daemon: "
                $0 stop
                sleep 2
                $0 start
                ;;
esac

The go.sh script 

#!/bin/sh
#
# Shell script to start and stop integrated JBoss/Jetty

# change this according to your own situation
export JAVA_HOME=/usr/local/java/j2sdk1.4.1_01
export JBOSS_HOME=/usr/local/java/jboss-3.0.4_jetty

JAVACMD=$JAVA_HOME/bin/java

# Minimal jar file to get JBoss started.
CLASSPATH=$CLASSPATH:$JBOSS_HOME/bin/run.jar

# Add the tools.jar file so that Tomcat can find the Java compiler.
CLASSPATH="$CLASSPATH:$JAVA_HOME/lib/tools.jar"

if [ "$1" = "start" ] ; then
        shift
        $JAVACMD $JBOSS_OPTS -classpath $CLASSPATH org.jboss.Main > /dev/null 2>&1 &
        echo $! > /var/run/jboss.pid

elif [ "$1" = "stop" ] ; then
        shift
        kill -15 `cat /var/run/jboss.pid`
        rm -rf /var/run/jboss.pid

elif [ "$1" = "run" ] ; then
        shift
        $JAVACMD $JBOSS_OPTS -classpath $CLASSPATH org.jboss.Main "$@"

else
        echo "Usage:"
        echo "jboss (start|run|stop)"
        echo " start - start jboss in the background"
        echo " run - start jboss in the foreground"
        echo " stop - stop jboss"
        exit 0
fi

Using a web container as http service

JBoss comes with two kind of web containers (Jetty or Tomcat) that are both capable HTTP servers. There is no need to use a web server to serve static HTML, JSP or Servlets. Both Jetty and Tomcat are capable of doing CGI. However if your requirements are not met by Jetty and/or Tomcat you can run JBoss behind Apache or IIS as it's web service (see here)

Using Jetty as HTTP service

If you want to use Jetty as your HTTP service the only thing you have to do is download the binary JBoss distribution with the embedded Jetty. By default Jetty listens on port 8080. If you want to use port 80, there are one or two possiblities, depending on the platform you run JBoss on.

  • Linux and Windows
    One can change the port Jetty uses. You must change the jboss-service.xml file that can typically be found in the JBossType/deploy/jbossweb-jetty.sar/META-INF/jboss-service.xml file where JBossType is one of "all", "default" or "minimal". You must adapt the ones you use. Notice that you can also start JBoss with a -DJetty.port=80 argument instead of changing this file, overruling the setting in this file. 
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- Add and configure a HTTP listener to port 8080                  -->
<!-- The default port can be changed using: java -Djetty.port=80     -->
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<Call name="addListener">
   <Arg>
      <New class="org.mortbay.http.SocketListener">
      <!-- <Set name="Port"><SystemProperty name="jetty.port" default="8080"/>/Set> -->
      <Set name="Port"><SystemProperty name="jetty.port" default="80"/>/Set>
      <Set name="MinThreads">10</Set>
      <Set name="MaxThreads">100</Set>
      <Set name="MaxIdleTimeMs">30000</Set>
      <Set name="LowResourcePersistTimeMs">5000</Set>
      </New>
   </Arg> 
</Call>
    Be aware that on Linux, JBoss must run as root to allow this: only root can start deamons that use ports below 1024.This can be a security risk.
  • Linux only
    One can use "iptables" or "ipchains" to map port 80 to port 8080. The example is for "iptables" which is used in Linux kernels 2.4 en up. For "ipchains": see the documentation of "ipchains". 
    		  
iptables -t nat -A PREROUTING -p tcp --dport 80 -d LISTEN_IP -j DNAT --to LISTEN_IP:8080
    where LISTEN_IP is the IP address on which Jetty is listening. If your computer has multiple IP addresses you might want to do this for every address you machine has. You can this line to the file /etc/sysconfig/iptables so that the changes stay after a reboot of your computer.

Using Tomcat as HTTP service

If you want to use Tomcat as your HTTP service the only thing you have to do is download the binary JBoss distribution with the embedded Tomcat. By default Tomcat listens on port 8080. If you want to use port 80, there are one or two possiblities, depending on the platform you run JBoss on.

  • Linux and Windows
    One can change the port Tomcat uses. You must change the jboss-service.xml file that can typically be found in the JBossType/deploy/jbossweb-tomcat.sar/META-INF/jboss-service.xml file where JBossType is one of "all", "default" or "minimal". You must adapt the ones you use. 
    		  
<!-- A HTTP/1.1 Connector on port 8080 -->
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
          port="8080" minProcessors="3" maxProcessors="10"
          enableLookups="true" acceptCount="10" debug="0" 
          connectionTimeout="20000" useURIValidationHack="false" />
    Be aware that on Linux JBoss must run as root to allow this: only root can start deamons that use ports below 1024.This can be a security risk.
  • Linux only
    One can use "iptables" or "ipchains" to map port 80 to port 8080. The example is for "iptables" which is used in Linux kernels 2.4 en up. For "ipchains": see the documentation of "ipchains". 
    		  
iptables -t nat -A PREROUTING -p tcp --dport 80 -d LISTEN_IP -j DNAT --to LISTEN_IP:8080
    where LISTEN_IP is the IP address on which Jetty is listening. If your computer has multiple IP addresses you might want to do this for every address you machine has. You can this line to the file /etc/sysconfig/iptables so that the changes stay after a reboot of your computer.

Using a web server as http service

Allthough JBoss comes with two kind of web containers (Jetty or Tomcat) that are both capable HTTP servers, there may be a need to use a real web server. It is possible to use either Apache or IIS as the main webserver and have the requests for servlets en JSPs handed over to JBoss' integrated web application server.

Using Apache as HTTP service

IF you want to use Apache as your HTTP service you must install a connector. A connector is a piece of software that connects a web server with a web container. We use the AJP 13 Connector (JK2) from the Apache project. For installation and configuration instructions see here.

Using IIS as HTTP service

IF you want to use Apache as your HTTP service you must install a connector. A connector is a piece of software that connects a web server with a web container. We use the AJP 13 Connector (JK2) from the Apache project. For installation and configuration instructions see here.

Running JBoss behind a firewal using HTTP

If there are firewalls between JBoss and it's clients we have some problems. JBoss makes use of several ports to communicate between the client and the server. Some of these ports are configurable static ports but some ports are randomly assigned at runtime. The problems concentrate on JNDI and RMI.

JBoss and a firewall
Figure 1: The firewalls between the client and the server

There are several strategies to handle this kind of problem but the easiest one is using JBoss JNDI and RMI over HTTP options.

JNDI over HTTP

JNDI over HTTP requires two adaptions. One adaption is in the jboss-service.xml file that can typically be found in the JBossType/deploy/http-invoker.sar/META-INF/jboss-service.xml where JBossType is one of "all", "default" or "minimal". You must adapt the ones you use.

The jboss-service file contains the following entry (the changes you have to make are marked by comment): 

		  
<!-- Expose the Naming service interface via HTTP -->
<mbean code="org.jboss.invocation.http.server.HttpProxyFactory" name="jboss:service=invoker,type=http,target=Naming">
   <!-- The Naming service we are proxying -->
   <attribute name="InvokerName">jboss:service=Naming</attribute>
   <!-- Compose the invoker URL from the cluster node address -->
   
   <!-- Replace our IP address with your IP address -->
   <!-- If you use a hostname here, make sure that the clients can resolve the hostname correctly  -->
   <attribute name="InvokerURL">http://213.46.144.131:8080/invoker/JMXInvokerServlet</attribute>
   
   <!-- If you do not provide the invokerURL, an URL will be build using these attributes and -->
   <!-- the InetAddress.getHostname value on which the server is running. -->
   <attribute name="InvokerURLPrefix">http://</attribute>
   <attribute name="InvokerURLSuffix">:8080/invoker/JMXInvokerServlet</attribute>
   
   <!-- If you used a hostname above set this property to true-->
   <attribute name="UseHostName">false</attribute>
   <attribute name="ExportedInterface">org.jnp.interfaces.Naming</attribute>
   <attribute name="JndiName"></attribute>
</mbean>

s

The second change you will have to make is a change in the source to some JNDI context properties. The properties you have to change are INITIAL_CONTEXT_FACTORY and PROVIDER_URL. The following code shows the changes.

From 

properties.put( Context.INITIAL_CONTEXT_FACTORY,
                "org.jnp.interfaces.NamingContextFactory" );
properties.put( Context.PROVIDER_URL, "Petitbonum:1099" );
To 
properties.put( Context.INITIAL_CONTEXT_FACTORY,
                "org.jboss.naming.HttpNamingContextFactory" );
properties.put( Context.PROVIDER_URL,
                "http://213.46.144.131:8080/invoker/JNDIFactory" );

You can also change the jndi.properties file [Note is this correct?]

RMI over HTTP

RMI over HTTP requires an adaption in the jboss-service.xml file that can typically be found in the JBossType/deploy/http-invoker.sar/META-INF/jboss-service.xml where JBossType is one of "all", "default" or "minimal". You must adapt the ones you use.

The jboss-service file contains the following entry (the changes you have to make are marked by comment): 

<!-- The HTTP invoker service configration -->
<bean code="org.jboss.invocation.http.server.HttpInvoker" name="jboss:service=invoker,type=http">
   <!-- Use a URL of the form http://<hostname>:8080/invoker/EJBInvokerServlet
   where <hostname> is InetAddress.getHostname value on which the server
   is running.
   -->
	
   <!-- Replace our IP address with your IP address -->
   <!-- If you use a hostname here, make sure that the clients can resolve the hostname correctly  -->	
   <attribute name="InvokerURL">http://213.46.144.131:8080/invoker/EJBInvokerServlet</attribute>
   
   <!-- If you do not provide the invokerURL, an URL will be build using these attributes and -->
   <!-- the InetAddress.getHostname value on which the server is running. -->
   <attribute name="InvokerURLPrefix">http://</attribute>
   <attribute name="InvokerURLSuffix">:8080/invoker/EJBInvokerServlet</attribute>
   
   <!-- If you used a hostname above set this property to true-->   
   <attribute name="UseHostName">false</attribute>
</mbean>

RedHat special

Depending on what you did during installation RedHat Linux creates a /etc/hosts file that does not work with JBoss. If your host file contains: 

127.0.0.1 yourhostname yourhostname.yourdomain localhost.localdomain localhost
then change that into 
127.0.0.1  localhost.localdomain localhost
your.ip.addres yourhostname yourhostname.yourdomain
It appears that it has something to do with the way JBoss matches IP addresses and hostnames. Downside of this change is that there are reports that your sendmail might stop working.

Configuring a DB2 datasource in JBoss

Changing the default database to DB2 in JBoss

In order to change the default database that JBoss uses from HyperSonic to DB2 (you actually want it to do real work, right?), take the following steps:

  • In your ${DB2}/java directory you'll find a file called db2java.zip which contains the DB2 jdbc driver classes. Copy this to the JBoss deploy directory and rename it to db2java.jar.
  • Create an empty database in DB2 and call it, for example, JBOSS.
  • Open the file ${JBOSS_HOME}/docs/examples/jca/db2-service.xml, copy it to the deployment directory and edit line 43 to point to the name of this database. You may also need to supply a username and password in the property-tags below line 43.
  • Open the file ${JBOSS_HOME}/server/default/conf/standardjbosscmp-jdbc.xml en change the <datasource> to "java:/DB2DS" and the <datasource-mapping> to "DB2".

Now, whenever you deploy a CMP bean to the default datasource, it will be stored in your newly created JBOSS database in DB2.

Adding a datasource to JBoss

Some applications may require access to multiple databases. It is possible to configure each EJB to use a specific datasource, or to leave it unconfigured and have it use the default datasource (see the previous paragraph). In order to tell an EntityBean to use a specific datasource, you need to take the following steps:

  • First, add the JDBC-drivers to the deployment directory, create a database to be used and create a [yourdatabase]-service.xml file in the deployment directory that defines the name of a datasource (similar to the first steps in the previous paragraph). To add a second datasource from the same RDBMS you can copy the mbeam tag that introduces a new service and change the names in that tag to your new datasource
  • Create a jbosscmp-jdbc.xml deployment descriptor for your ejb-jar with the following content: 
    <jbosscmp-jdbc>
  <enterprise-beans>
    <entity>
      <ejb-name>your_context/YourBean</ejb-name>
      <datasource>java:/YourDataSourceDS</datasource>
      <datasource-mapping>YourDatabaseMapping</datasource-mapping>
      <table-name>your_table_name</table-name>
    </entity>
  </enterprise-beans>
</jbosscmp-jdbc>
    This will connect your EntityBean with the given table name in the given datasource. This datasource has to have the same name as the one you defined in the [yourdatabase]-service.xml file in your deployment directory.

Configuring a PostgreSQL datasource in JBoss

Changing the default database to PostgreSQL in JBoss

In order to change the default database that JBoss uses from HyperSonic to PostgreSQL (you actually want it to do real work, right?), take the following steps:

  • Download the PostgreSQL JDB driver from here. We used the PostgreSQL 7.3 driver for the JDBC3 platform.
  • Copy the file to the JBoss deploy directory.
  • Create an empty database in PostgreSQL and call it, for example, JBOSS.
  • Open the file ${JBOSS_HOME}/docs/examples/jca/postgres-service.xml, copy it to the deployment directory and edit line 44 to point to the name of this database. You may also need to supply a username and password in the property-tags below on line 47.
  • Open the file ${JBOSS_HOME}/server/default/conf/standardjbosscmp-jdbc.xml en change the <datasource> to "java:/PostgresDS" and the <datasource-mapping> to "Postgres".

Now, whenever you deploy a CMP bean to the default datasource, it will be stored in your newly created JBOSS database in PostgreSQL.

Removal

If you have installed JBoss to run as a service, you must first stop the service and then uninstall it. After this, you should be able to simply remove the complete directory in which JBoss lives. If you have integrated the webserver component with either Apache or IIS, you'll have to remove these mappings as well, before stopping the running instance of JBoss.

Homepage

The homepage for JBoss is at http://www.jboss.org.

Manual

The JBoss project manual is for sale at http://www.jboss.org/docs. At the same place a free “JBoss getting started” is available.

FAQ

The JBoss FAQ is at http://www.jboss.org/faq.jsp

Links

www.jboss.org/forums in addition to the JBoss-user mailing list