Introduction

This is a guide to get you started with SPECj.  We have created a custom JBoss kit to make it easier to setup SPECj, however, you should still be familiar with the official SPECj documentation.  It will be invaluable to your tuning efforts.

-

Requirements

SPECj Application

Firstly, you will need a license to run Specj2004 from Spec.org.

JBoss Application server.

You can download this from www.jboss.com.  Our SPECj configuration requires at least Jboss-4.0.2+. Don't use JBoss-4.0.2-RC1.

There are some required changes in JBoss-4.0.2 related to the default classloader model.

This thread shows a workaround.

JBoss SPECj kit

You can grab our latest kit from here http://jira.jboss.com/jira/browse/JBBENCH-21.  This is used to build the custom JBoss descriptors for SPECj, and configure the app server with some reasonable default values.

PLEASE NOTE!  This kit is provided in the hopes that it will help ease the pain of configuring SpecJ.  It should not be expected to work on all versions of the app server, and some manual steps may be needed for your particular version.

-

Installation and Setup

Directory Layout

You should have your directory tree setup as follows:

specj   |- jboss-x.x.x - JBoss Application server   |- jboss-specj-kit - Current JBoss kit for SPECj   |- SPECjAppServer - SPECj application.  Contact SPEC to obtain a license.

Database

Scripts to setup your database are in jboss-specj-kit/schema/$DB_NAME.  We use mysql as the example here:

Create the specj and jms users.  You must use a mysql admin user to do this step.

mysql -u username -p -h dbhost < createUser.sql

Create the specj2004 database and tables.  The jms database is created empty.  It will be populated with tables on jboss startup.

mysql -u username -p -h dbhost < create_specj_tables.sql

Now, to populate the db run the following command in the jboss-specj-kit directory.replacing xx with your transaction rate:

ant -DSCALE=xx loaddb

If you have a multiprocessor machine, the threads option can decrease loading time.  This example loads the db using 8 threads:

ant -DSCALE=xx -DTHREADS=8 loaddb

If you are using MySQL, you will need to set the following options in your my.cnf:

lower_case_table_names = 1  # MySQL is case-sensitive by default
sql-mode = IGNORE_SPACE     # Allow spaces between function names and the '(' character

Kit

After you have extracted these archives into a directory, go into the jboss-specj-kit directory.  There are two properties files:  One for mysql and one for oracle.  You will need to edit one of these files to match your environment.  The main variables are documented below:

After you have edited the files to your liking, you run the command 'ant' in the jboss-specj-kit directory.  This does a few things

1. Creates the jboss deployment archives for specj

2. Creates the specj and emulator server directories under $JBOSS_HOME/server

3. Creates the driver configuration files in $SPECJ_HOME/config to match your environment.

-

Running SPECj

The first steps are to start the emulator and SUT.  It is possible to run both the emulator and SUT in the same jboss instance by setting the variables 'server-name' and 'JBOSS_EMULATOR_SERVER_NAME' documented

above to the same value.  This would not be a valid run for submission, but it is fine if you are just testing.  If you do things this way, you only need to start one jboss intance.

Start the JBoss instance on the Emulator

cd $JBOSS_HOME/bin
./run.sh -c $JBOSS_EMULATOR_SERVER_NAME -b $JBOSS_EMULATOR_HOST

The '-b' is optional, but useful for binding jboss to a specific interface rather than all of them.

Start the JBoss instance on the SUT

cd $JBOSS_HOME/bin
./run.sh -c $server-name -b $APPLICATION_HOST

Start the Driver

cd SPECjAppServer/bin
./driver.sh

Now, if you have set everything up correctly, you should see the driver go through various stages (Starting threads, Ramp Up, Steady State, Ramp Down) and output a summary.  You can now view the results of the run in

$OUTDIR/xxx (replace xxx with the run number output by the driver).  The meanings of the files in this directory are explained thoroughly in the SPECj documentation.

-

Useful stuff

SPECj documentation

You can find the official SPECj documentation at:

http://www.spec.org/jAppServer2004/

Reset the DB between runs

If you are repeatedly doing runs with the same transaction rate, there is no need to reload the db in between every run.  To reset a loaded DB back to its clean state, you can simply drop all rows from the table 'm_largeorder'.  This is exactly the same as if you had reloaded the db and is even mentioned in the official SPECj documentation.  The following example uses mysql:

mysql $SPECJ_DB_NAME
delete from m_largeorder where 1=1;

Reset the JMS DB between runs

Occasionally, if jboss is not shut down correctly, it can leave stale messages in the JMS database.  These will cause tons of error messages to be spammed to the console when starting JBoss.  To fix this problem, simply drop the jms database and re-add it.  JBoss will recreate the JMS tables on startup.  MySQL example below:

mysql
drop database $JMS_DB_NAME
create database $JMS_DB_NAME;

-

Feedback

Please let us know about your experience.  You can contact us at qa@jboss.com or through the benchmark forums.

Release Notes

• 1.0

• 1.3