$Author: bastafidli $
$Date: 2006/08/27 07:52:11 $
$Revision: 1.7 $
$RCSfile: j2eesetup_jboss.html,v $
This document will help you get started with JBoss application server supported by OpenSubsystems. It will walk you through obtaining, installing and configuring the application server so that it can be used to run OpenSubsystems components and applications. It also describes how OpenSubsystems can integrate with and utilize transaction manager and connection pools provided by the application server to access your databases.
JBoss Application Server is one of the most popular open source application servers. It is J2EE 1.4 certified and used by many open source projects and commercial clients.
Download the installation package of JBoss Application Server from the official website. The binary versions are available as either .jar, .zip, .tar.gz, .bz2 files. The contents are the same so grab whichever flavor is the most convenient for the platform you are running on. We recommend to use the graphical installer available in the jar package. The only additional requirement to run JBoss (and the jar installer) is to have an up-to-date version of Java on your machine. JBoss 4.0.x requires at least a JDK 1.4 to run. Make sure to get the JDK and not the JRE. Although JBoss will start with JRE only, you'll experience problems compiling JSP pages. You should also make sure that the JAVA_HOME environment variable is set to point to your JDK installation.
Once Java is installed and setup you can start the graphical installation wizard by doubleclicking on the downloaded jar file. Be aware that if you have already installed a previous version of JBoss in this location the new installation will overwrite the existing files, thus customized configuration files may be lost. It is prudent to save these files before starting the installation process. The wizard will guide you through the installation process on your machine. It is safe to accept all the default options except the installation profile. Make sure you choose the All profile to ensure all the necessary components are installed.
Before you can use OpenSubsystems with JBoss you will have to
configure the persistence layer so that OpenSubsystems can access
your database. Following steps assume that you are using the
default instance of JBoss server located under server/default
subdirectory of JBoss installation directory. Copy the JDBC
driver for the database you want to use into directory
You should have this driver available if you have followed the Database Setup instructions.
Next configure settings
required to access your database. You have to include the
default OpenSubsystems configuration file
on JBoss classpath or configure JBoss to tell OpenSubsystems
where to look for a configuration file. The classpath used
by JBoss is displayed in the console when JBoss server starts.
You can include the directory containing the default
configuration file oss.properties on JBoss classpath by setting
environment variable JBOSS_CLASSPATH to point to this directory.
For example, in Windows environment execute following command
just before you start JBoss application server
Alternatively you can modify file
and after uncommenting Properties section include there property oss.config.file pointing to an OpenSubsystems configuration file you want to use, e.g.
<attribute name="Properties"> oss.config.file=\Development\OpenSubsystems\sources\config\oss.properties </attribute>
Once the OpenSubsystem configuration file is setup, make sure that the uncommented database related settings in this file match the database you want to use. If you decide to use third party transaction manager or connection pool supported by OpenSubsystems, uncomment them in the configuration file as well. If all the connection pools and transaction managers supported by OpenSubsystems are commented out OpenSubsystems will detect if it is running inside of J2EE server and it will use the transaction management and connection pooling capabilities provided by JBoss as part of the J2EE implementation.
If the JBoss connection pool is being used you have to
configure JBoss data source that matches the database enabled
in the configuration file. In the directory
locate the example datasource configuration file for your database. The files are named [databaseidentifier]-ds.xml in case the datasource uses regular connections and [databaseidentifier]-xa-ds.xml in case the datasource uses XA connections. The database identifier should correspond to your database, e.g. use db2-ds.xml if you use IBM DB2 database. In case there is no such file for your database, use file generic-ds.xml and rename it to replace generic with your database identifier. Copy the file of your choice to directory
Open the [databaseidentifier]-ds.xml file in your favorite
editor and change it's settings to correspond to the values in
the OpenSubsystems configuration file you have setup
previously. For example, if you have configured OpenSubsystems
to use MySQL database after the change the mysql-ds.xml should
look similar to
<datasources> <local-tx-datasource< <jndi-name>OSSDS</jndi-name> <connection-url>jdbc:mysql://localhost/OSS</connection-url> <driver-class>com.mysql.jdbc.Driver</driver-class> <user-name>bastatest</user-name> <password>fidli</password> </local-tx-datasource> </datasources>
Notice that the <jndi-name> property should be set to
OSSDS. This is because if no other datasource name is specified
in the requestConnection or setDefaultDataSourceName methods of
interface the default connection pool is always looked up for OSSDS JNDI datasource name. If your application sets different default datasource name, adjust this property accordingly. For more information about configuring datasources refer to Using other Databases chapter in Getting Started with JBoss user guide.
Ability to debug applications or subsystems running inside of
JBoss application server is essential during the development
and the testing phase. To enable this capability, open in your
favorite editor file
locate the line configuring JAVA_OPTS with settings for remote socket debuging and uncomment it. The setting may look for example like this
JAVA_OPTS="$JAVA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y"
For more information about particular options read the Java application launcher documentation. You can use Eclipse IDE to debug application running under JBoss that was started in the debug mode. Follow the Debugging Remote Application guide for step by step instructions to configure your environment.
The last step is to deploy your application to JBoss
application server. Locate the war or ear file for the
OpenSubsystems-based application or subsystem and copy it to
Remember the name of the file you have deployed, since the application or subsystem deployed using file [applicationname].ear or [applicationname].war can be by default accessed using url
once the JBoss application server is started. If you are deploying one of the default OpenSubsystem demo applications with names such as [subsystemname].ear, [subsystemname].war, [subsystemname]-app.ear or [subsystemname]-app.war, the default url is
At this time you are ready to start JBoss application server. On the command line go to the bin subdirectory of the JBoss installation directory and execute the run script (run.bat if you're on Windows, run.sh if you're on Linux, OS X, or another UNIX-like system). You should see the log messages from all the JBoss components as they are deployed and started. It is possible that you can encounter exception
16:44:56,228 WARN [JBossManagedConnectionPool] Throwable while attempting to get a new connection: null org.jboss.resource.JBossResourceException: Could not create connection; - nested throwable: (java.sql.SQLException: Login failed for user '[username you have configured]'.)
if the database user for the user name you have configured in the configuration file doesn't exist. It is safe to ignore this exception since as the application is deployed, OpenSubsystems creates the user for you and then connects to the database as the specified user. The last message (obviously with different values for the time and start-up speed) should look similar to this
16:44:57,009 INFO [Server] JBoss (MX MicroKernel) [4.0.3SP1 (build: CVSTag=JBoss_4_0_3_SP1 date=200510231751)] Started in 22s:903ms
Now you can go to you browser and access url http://localhost:8080/ to verify that the JBoss server is in fact up and running. The default page has links to a few useful JBoss resources. You can get a live view of the server by going to the JMX console or to JBoss Web Console (only 4.0.x series). To access the deployed application copy the URL http://localhost:8080/[applicationname]/ to your browser address bar and modify it to reference your application.