$Revision: 1.1 $

$Date: 2002/02/22 19:49:08 $

Setting up JBoss

Contents
  1. Overview
  2. Install the JBoss software
  3. Install JDBC drivers
  4. Configure JDBC datasources
  5. Configure JBoss security
  6. Start the JBoss server
  7. Next step: Build and deploy the CLRA application

Overview

This document describes how to set JBoss for the CLRA web application.

PREREQUISITES:

This document assumes that an environment variable $CLRA_HOME has been set up which corresponds to the clra/clra-java directory, so that source code resides in $CLRA_HOME/src; web pages in $CLRA_HOME/web; shell scripts in $CLRA_HOME/bin; and so on.

The CLRA web application uses version 2.4.4 of JBoss with the Embedded Tomcat service. The basic steps for JBoss configuration are 1) installation of the server software; 2) configuration of JDBC drivers and data sources; and 3) configuration of JBoss security.

Back to Top

Install the JBoss software

Download JBoss with the Embedded Tomcat Service from www.jboss.org.

The CLRA web application has been tested under JBoss version 2.4.4 with Tomcat 4.0.1 (Catalina). The binary release file on the JBoss site is JBoss-2.4.4_Tomcat-4.0.1.zip

Install per directions on the JBoss website.

Create a system environment variable called JBOSS_DIST to point to the jboss subdirectory of the unpacked file. The JBoss binaries will be located at $JBOSS_DIST/bin; the JBoss configuration files at $JBOSS_DIST/conf; the JBoss deployment directory at $JBOSS_DIST/deploy; and the Tomcat 4.0.1 files at $JBOSS_DIST/../catalina.

NOTE: the CLRA build scripts require the $JBOSS_DIST environment variable to be defined.

Back to Top

Install JDBC drivers

As mentioned above in the document on database setup, the CLRA web application is developed against an Oracle database but runs against a MySQL database for production. Unlike the document on database setup, this document discusses how to configure both MySQL and Oracle drivers and datasources for use with JBoss. You won't be able to use the Oracle drivers and datasources unless you have set up an Oracle database for the CLRA application. Conversely, if you're not going to use Oracle, you may skip steps that are related to Oracle.

MySQL

Oracle

Back to Top

Configure JDBC datasources

Placing a JDBC driver in the $JBOSS_DIST/lib/ext directory makes the driver available to application classes. For example, a direct JDBC call from the CLRA application to MySQL will find the jdbc:mysql JDBC driver in Java classpath.

However, JBoss itself requires two extra steps to use JDBC drivers. First, the JDBC driver must be loaded by the JBoss JdbcProvider service, and second, a pooled, transactional datasource must be configured to use the driver.

Both the JdbcProvider service and datasources are configured as entries in a file named jboss.jcml. There will be at least two copies of this file in the JBoss/Tomcat distribution. The first copy will be located at $JBOSS_DIST/conf/default/conf/jboss.jcml, and the second copy will be located at $JBOSS_DIST/conf/catalina/jboss.jcml. The first copy is used if the default (non-Tomcat) configuration of JBoss is started. The second copy is used if the catalina (Embeddd Tomcat) configuration of JBoss is started. Since the CLRA application uses the Embedded Tomcat service, the second copy is the one that needs to be modified. (See the JBoss documentation for more information about configuring a JBoss server.)

The jboss.jcml file is an XML document. It specifies the configuration of (non-bootstrap) JBoss services by naming managed beans in the order in which they should be loaded when JBoss starts up. Each managed bean corresponds to an <mbean>...</mbean> entry in jboss.jcml

JdbcProvider service

The JdbcProvider service is about the eighth mbean listed in the jboss.jcml file; in the 2.4.4 distribution, it is proceeded by a "JDBC" comment.

The JBoss/Tomcat distribution ships with the following configuration: 

  <mbean code="org.jboss.jdbc.JdbcProvider" name="DefaultDomain:service=JdbcProvider">
     <attribute name="Drivers">
       org.hsqldb.jdbcDriver
     </attribute>
  </mbean>
The JdbcProvider configuration should be modified to include the MySQL (and optionally the Oracle) JDBC drivers: 
  <mbean code="org.jboss.jdbc.JdbcProvider" name="DefaultDomain:service=JdbcProvider">
     <attribute name="Drivers">
       org.hsqldb.jdbcDriver,
       org.gjt.mm.mysql.Driver,
       oracle.jdbc.driver.OracleDriver
     </attribute>
  </mbean>
Note that driver names should be separated by a comma.

CLRA datasource(s)

A datasource must be configured for the MySQL database, and optionally for the Oracle database.

JBoss ships with the DefaultDS pre-configured. This service is about the tenth bean listed in jboss.jcml, just below the JdbcProvider service.

The ClraMySqlDS datasource (and optionally the ClraOracleDS datasource) should be added immediately after the DefaultDS datasource: 

  <mbean code="org.jboss.jdbc.XADataSourceLoader" name="DefaultDomain:service=XADataSource,name=ClraMySqlDS">
    <attribute name="PoolName">ClraMySqlDS</attribute>
    <attribute name="DataSourceClass">
            org.jboss.pool.jdbc.xa.wrapper.XADataSourceImpl</attribute>
    <attribute name="URL">jdbc:mysql://localhost/clra</attribute>
    <attribute name="JDBCUser">muze</attribute>
    <attribute name="Password">muz3</attribute>
    <attribute name="MaxSize">20</attribute>
    <attribute name="MinSize">0</attribute>
  </mbean>

  <mbean code="org.jboss.jdbc.XADataSourceLoader" name="DefaultDomain:service=XADataSource,name=ClraOracleDS">
    <attribute name="PoolName">ClraOracleDS</attribute>
    <attribute name="DataSourceClass">
            org.jboss.pool.jdbc.xa.wrapper.XADataSourceImpl</attribute>
    <attribute name="URL">jdbc:oracle:oci8:@</attribute>
    <attribute name="JDBCUser">muze</attribute>
    <attribute name="Password">muz3</attribute>
    <attribute name="MaxSize">20</attribute>
    <attribute name="MinSize">0</attribute>
  </mbean>

Note that the URL, JDBCUser, and Password entries should be customized for your particular database. The MaxSize and MinSize entries are suggested values, and may also be customized depending on your requirements.

Back to Top

Configure JBoss security

JBoss security is an extension of the Java Authentication and Authorization Service, which in turn is based on the Pluggable Authorization Framework (PAM). JBoss enables declarative security, in which security restrictions are specified outside of application logic via configuration files.

Security is specified separately for web components and EJB components. Security for web components such as servlets, JSP's, HTML documents and other elements addressable via a URL is specified via application-specific web.xml and jboss-web.xml files. Security for EJB's is specified via application-specific ejb-jar.xml and jboss.xml files. Both web and EJB security constraints are mapped to security domains that are configured on a per-server basis (i.e. commonly across all applications hosted by a server) via the $JBOSS_DIST/conf//auth.conf file.

The CLRA web.xml, jboss-web.xml, ejb-jar.xml and jboss files assume that two security domains are configured for the JBoss server on which the CLRA application is deployed:

The distribution file $CLRA_HOME/etc/server-auth.conf contains the following definitions for these domains: 


  // This file defines security domains which must be added to
  // $JBOSS_DIST/conf//auth.conf

  // The CLRA login module for MySql
  clra-test-mysql {
      org.jboss.security.auth.spi.DatabaseServerLoginModule required
      dsJndiName="java:/ClraMySqlDS"
      principalsQuery="select account_passwd from Member where account_name=?"
      rolesQuery="select b.Role, b.RoleGroup from Member a, MemberRole b
                  where a.account_name=? and a.member_id=b.member_id"
          ;
  };

  // The CLRA login module for Oracle
  clra-test-oracle {
      org.jboss.security.auth.spi.DatabaseServerLoginModule required
      dsJndiName="java:/ClraOracleDS"
      principalsQuery="select account_passwd from Member
                       where UPPER(account_name)=UPPER(?)"
      rolesQuery="select b.Role, b.RoleGroup from Member a, MemberRole b
                       where UPPER(a.account_name)=UPPER(?)
                       and a.member_id=b.member_id"
          ;
  };

  // END OF FILE
(Long lines have been broken in this HTML document, but should not be broken in *.conf files.)

These definitions must be added to the top of the $JBOSS_DIST/conf/catalina/auth.conf file.

Back to Top

Start the JBoss server

After the $JBOSS_DIST/conf/catalina/jboss.jcml and $JBOSS_DIST/conf/catalina/auth.conf files have been configured for the CLRA application, you may start the server. (If the server was running when the changes were made, the server should be restarted.)

The server should be started with the $JBOSS_DIST/bin/run_with_catalina.sh script. This script must be started from the $JBOSS_DIST/bin directory. (The script name is very long, therefore you may wish to rename it, say something like "start_clra.sh".)

There are a couple of tricks to running JBoss under Linux:

Back to Top

Next step: Build and deploy the CLRA application

Now that the CLRA software has been unpacked, the CLRA database has been setup, and the JBoss server has been configured and started, the next steps are to build the CLRA application (if you did not already do so already) and deploy the application to JBoss. These final steps are covered in a separate document, Build Process.


Back to Top