OpenSubsystems

Business Components for Java Applications

J2EE Application Server Setup

JBoss

Last modified

$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 4.0

Official page | Download | Documentation
Tested version: JBoss Application Server 4.0.3SP1

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.

Installation

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.

Database Configuration
JDBC driver

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

[JBOSS_ROOT]/server/default/lib

You should have this driver available if you have followed the Database Setup instructions.

OpenSubsystems

Next configure settings required to access your database. You have to include the default OpenSubsystems configuration file oss.properties 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

set JBOSS_CLASSPATH=\Development\OpenSubsystems\sources\config

Alternatively you can modify file

[JBOSS_ROOT]/server/default/deploy/properties-service.xml

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.

Data source

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

[JBOSS_ROOT]/docs/examples/jca/

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

[JBOSS_ROOT]/server/default/deploy

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

org.opensubsystems.core.persist.db.DatabaseConnectionFactory

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.

Server Configuration

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

[JBOSS_ROOT]/bin/run.conf

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.

Deploying Application

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 directory

[JBOSS_ROOT]/server/default/deploy

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

http://localhost:8080/[applicationname]/

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

http://localhost:8080/[subsystemname]/

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.