# I-SPY Post Analysis Portal  {#i-spy-post-analysis-portal .Style-Chapter-Title-+-Right:--0.03\"}

# caIntegrator Install Guide {#caintegrator-install-guide .Style-Chapter-Title-+-Right:--0.03\"}

18 January 2008

# Table of Contents {#table-of-contents .Style-Chapter-Title-+-Right:--0.03\"}

[I-SPY Post Analysis Portal 1](#i-spy-post-analysis-portal)

[caIntegrator Install Guide 1](#caintegrator-install-guide)

[Table of Contents 2](#table-of-contents)

[Introduction to caIntegrator 3](#introduction-to-caintegrator)

[Introduction to I-SPY 3](#introduction-to-i-spy)

[How to use the installation guide
4](#how-to-use-the-installation-guide)

[General Requirements 4](#general-requirements)

[Targeted Developer 5](#targeted-developer)

[General Hardware Requirements 5](#general-hardware-requirements)

[Server Configuration 6](#server-configuration)

[Obtaining the caIntegrator Source
7](#obtaining-the-caintegrator-source)

[Database Technology 8](#database-technology)

[Assumptions and Requirements 8](#assumptions-and-requirements)

[Initialization 8](#initialization)

[Verification 9](#verification)

[I-SPY Application 11](#i-spy-application)

[Assumptions and Requirements 11](#assumptions-and-requirements-1)

[Installation/Deployment 12](#installationdeployment)

[Step 1: Building caintegrator-analysis-commons
12](#step-1-building-caintegrator-analysis-commons)

[Step 2: Building caintegrator-spec
12](#step-2-building-caintegrator-spec)

[Step 3: Building caintegrator-application-commons
13](#step-3-building-caintegrator-application-commons)

[Step 4: Building ispy.war 13](#step-4-building-ispy.war)

[Step 5: Configure JBOSS for I-SPY application
14](#step-5-configure-jboss-for-i-spy-application)

[Step 6: Deploy I-SPY application under JBoss
15](#step-7-deploy-i-spy-application-under-jboss)

[Verification 15](#verification-1)

[Appendex: Configure Common Security Module (CSM) 3.1 for I-SPY
application 16](#__RefHeading___Toc188757456)

[Analysis Server 17](#analysis-server)

[Assumptions and Requirements 17](#assumptions-and-requirements-2)

[Installation 18](#installation)

[Running the Analysis Server 19](#running-the-analysis-server)

[Troubleshooting 20](#troubleshooting)

[Appendix A: 3rd Party Tools 22](#appendix-a-3rd-party-tools)

# Introduction to caIntegrator {#introduction-to-caintegrator .Style-Chapter-Title-+-Right:--0.03\"}

"Informatics tools to integrate clinical trials and high throughput
molecular analysis"

The caIntegrator knowledge framework provides researchers with the
ability to perform ad hoc querying and reporting across multiple
domains. This application framework comprises an n-tier service oriented
architecture that allows pluggable web-based graphical user interfaces,
a business object layer, server components that process the queries and
result sets, a data access layer and a robust data warehouse.

caIntegrator is envisioned to be the foundation for a number of
translational applications. One such reference implementation at NCICB
is called I-SPY Post Analysis Portal--
http://caintegrator.nci.nih.gov/ispy. This knowledge framework offers a
paradigm for rapid sharing of information and accelerates the process of
analyzing results from various biomedical studies with the ultimate goal
to rapidly change routine patient care.

More information is available at the caIntegrator website:
[http://caintegrator-info.nci.nih.gov]{.underline}.

# Introduction to I-SPY

Progress in finding better therapies for breast cancer treatment is
hampered by the lack of opportunity to integrate and rapidly test novel
therapeutics in the clinical setting. In order to catalyze the
transition from uniform to tailored care, clinical trials to identify
markers and mechanisms of resistance to therapy are critical. A
collaboration of physicians, researcher and cooperative groups are
conducting one such study, the I-SPY Trial, a multi-center clinical
trial of women undergoing neoadjuvant chemotherapy from breast cancer.
In order to assist in the conduct of the trial and the analysis of
results, a great deal of attention has been paid to facilitating
collaboration, providing infrastructure for data management, analysis,
and communication, and developing a commitment to sharing information
and developing data standards.

# How to use the installation guide

The primary components of I-SPY application which will be elaborated
upon include: the database, the caintegrator-analysis-commons, the
caIntegrator-spec module, the caintegrator-application-commons, and the
I-SPY Application. The guide will include specific sequential
instructions on how to obtain, install, configure, and manage each
component.

Throughout the guide, specific elements will be highlighted with a
unique style, in order to emphasize and categorize these elements.

Please refer to the key below for definitions of the elements and their
corresponding style:

  ---------------------- ---------------------------------------------------
  Element                Style

  Links                  URL's and paths will be styled as [blue
                         underlined]{.underline}

  Commands               OS console commands will be styled as **courier new
                         bold red**

  Messages               expected messages during installation **bold
                         green**

  *Filenames*            file names will by styled in ***italics***

  Properties/Variables   property and variable names will be styled in
                         **bold orange**

  Code                   code or XML (typically for configuration) will be
                         styled as **courier new bold gray**
  ---------------------- ---------------------------------------------------

# General Requirements

The general requirements common to multiple components of caIntegrator
are a prerequisite, and must be installed on your machine prior to
attempting to work with the caIntegrator framework. The following are
open source technologies which power caIntegrator:

• Java Software Development Kit (JDK) version 1.5.0_0X
[http://java.sun.com/j2se/1.5.0/download.jsp]{.underline}

• JBoss Container (recommended: JBoss version 4.0.4)
[http://www.jboss.com/products/jbossas/downloads]{.underline}

• Jakarta Ant version 1.6.5

http://archive.apache.org/dist/ant/binaries/

• Oracle 9i

http://www.oracle.com

Please acquire each of these and follow the installation instructions
provided with each respective product for your environment.

# Targeted Developer

Although we have tried to make every effort to simply these instructions
as much as possible, we feel that this installation guide is best suited
for an experienced java developer who is familiar with the following
J2EE technologies:

• Unix/Linux environment

(Configuring environment variables; Installing Ant, JDK, and JBOSS
server)

• Ant build scripts

• J2EE web application development using the Struts framework,
Servlet/JSP's, javascript, AJAX, and XML/XSLT.

• J2EE middle-ware technologies such as n-tier service oriented
architecture, design patterns and Hibernate.

In addition, you will need assistance / access from an Oracle 9i
database administrator to properly configure the database.

# General Hardware Requirements

caIntegrator has been tested with the following configuration, as 3
separate machines.

**Analysis Server:**

The hardware currently supporting the analysis server for the Rembrandt
application consists of a cluster of three HP Proliant DL140 G2
machines, with dual 3.60 GHz Xeon 64T cpus, 4 GB ram, mirrored 36 GB
SCSI hard drives running the Red Hat EL 3.0 operating system.

The analysis computations can take a significant amount of memory and
therefore it is recommended that the machine(s) running the analysis
server have at least 2 GB of memory. In addition, the analysis server is
intended to be run on a Unix based operating system.

If the analysis server is to be hosted on the same machine that is
hosting the Rembrandt application then is recommended that machine have
more than one cpu and have at least 4 GB ram (i.e., 2GB dedicated to the
analysis server and 2GB dedicated to the application).

**Application Server:**

Red Hat EL 3.0 on HP Proliant DL360 G4, with dual 3.40 GHz Xeon 64T
cpus, 8 GB ram, mirrored 144 GB SCSI hard drives.

**Database Server:**

Sun Solaris 8.0 on Sun v1280, with four 900 MHz US-III cpus, 8 GB ram,
mirrored local and SAN disks.

# 

# 

# Server Configuration

We recommend the following configuration: [( should we add gene pattern
server to it?)]{.mark}

![](media/image1.wmf){width="1.2255905511811023in"
height="1.3070866141732282in"}![](media/image1.wmf){width="1.2255905511811023in"
height="1.3090551181102361in"}![](media/image1.wmf){width="1.2255905511811023in"
height="1.3090551181102361in"}![](media/image1.wmf){width="1.2255905511811023in"
height="1.3055118110236221in"}![](media/image1.wmf){width="1.2255905511811023in"
height="1.3090551181102361in"}

# Obtaining the caIntegrator Source

The caIntegrator I-SPY source code can be downloaded from the nci cvs
repository.

**CVS**

:pserver:anonymous@cbiocvs2.nci.nih.gov:/share/content/cvsroot

All repositories on cbiocvs2 are available through read-only anonymous
access (anonymous/anonymous) using the ext protocol.

For the I-SPY webapp, check out the following modules:

            ispyportal

            caintegrator-spec

            caintegrator-analysis-commons

            caintegrator-application-commons

  

For the analysis server, check out the following modules:

            caintegrator-analysis-commons

            caintegrator-analysis-server

Each of these modules will be referenced in the subsequent portions of
this guide.

**[Database Download]{.mark}**

[The file below contains all necessary instructions and information for
importing the database file for the I-SPY implementation.]{.mark}

[]{.mark}

# Database Technology {#database-technology .Style-Chapter-Title-+-Right:--0.03\"}

caIntegrator employs a basic star schema with modification for the Study
data warehouse design that supports the integration of clinical and
genomic data. It is a generic, query optimized schema that contains fact
tables. Look up entities make up the dimensions in the schema. This
schema provides a highly de-normalized view of the data and a data
neutral framework from which queries can be executed with quick
retrieval time.

# Assumptions and Requirements

Oracle database 9i has been set up and you have access to the
administrator account. You have proper privileges to create a named
tablespace and you are familiar with the oracle DB technology.

In addition to the above assumptions, it is also required that you have
properly downloaded the
[ispy_samples.zip](https://gforge.nci.nih.gov/frs/download.php/3160/ispy_samples.zip)
file from the caIntegrator gForge site
<https://gforge.nci.nih.gov/frs/?group_id=406>

# Initialization

Login into Oracle as database the administrator

1\. Create a user with proper privilege for import.

2\. Download the
[ispy_samples.zip](https://gforge.nci.nih.gov/frs/download.php/3160/ispy_samples.zip)
file from gForge to the desire drive, such as c:\\

3\. In the command line, issue the following:

C:\\\>imp \<user_name\>/\<password\>@DB file=ispy_samples_012208.dmp
full=y log=ispy.log

4\. Check the log to verify the load is successful. Sample log file is
part of the zip.

Note: You/DBA can verify this database import by checking the log file
for errors.

# Verification

Once the database has been created through importing, it can be verified
by comparing the number of the objects in current database with the
number of the objects from the original database. This verification
process can be performed through a SQL query in the SQL Plus or TOAD
environment. Verity there should be 4 indexes, 7 triggers and 12
sequences in DB.

In addition, most of the tables in the database should contain seed data
for the public to view.

# I-SPY Application {#i-spy-application .Style-Chapter-Title-+-Right:--0.03\"}

# Assumptions and Requirements

The database component listed in this guide must be installed,
configured, and deployed prior to installing this component.

There is currently a 2GB RAM minimum requirement for any server that
this application is deployed on. This is due to the extremely large data
sets that are being processed and returned to the user.

The following components are required.

Application Software: Source Code download from cvs

  ----------------------------------------------------- -----------------
  Software                                              [CVS Tag]{.mark}

  caintegrator-application-commons                      [1.5]{.mark}

  caintegrator-analysis-commons                         [1.5]{.mark}

  caintegrator-spec                                     [1.5]{.mark}

  Ispyportal                                            [1.5]{.mark}

  weka.jar                                              [3-4-\*]{.mark}
  ----------------------------------------------------- -----------------

**Download weka.jar**

1.  Go to <http://www.cs.waikato.ac.nz/~ml/weka/index.html>

```{=html}
<!-- -->
```
1.  Read their licensing terms and conditions.

2.  Download a weka zip archive containing the weka source files and
    instructions to build the *weka.jar*

3.  The latest file at the time this guide was written was
    *weka-3-4-10.zip* located on the Download page under the "**Other
    platforms (Linux, etc.)"** heading**.**

Unzip the archive under *\<work-area\>*.. This will create a new
directory called *\<work-area\>/[weka-3-4-10]{.underline}.*

In step 2 of installation, you will extract this file into the
caintegrator-spec package.

# Installation/Deployment

The I-SPY web application is dependent on the following jars, as
mentioned above: *caintegrator-analysis-commons.jar*.
*caintegrator-application-commons.jar* and *caintegrator-spec.jar*. The
application requires these jars to be built prior to the
build/deployment of *ispy.war*. In this section, Steps 1 through 3
provides instructions to build these dependent jars. Step 4 & 5 provides
instructions to build, configure and deploy the ISPY application.

Note: The build script creates a directory called "artifacts" in the
same level as the directory where each of the components was extracted.
E.g., if you checkout *caintegrator-analysis-commons.zip* under the
folder c:\\dev, the build script will create a folder c:\\dev\\artifacts
which will contain the binaries from the builds.

In the subsequent sections *\<work-area\>* will refer the work area
where the component has been checked out (such as c:\\dev).

## Step 1: Building caintegrator-analysis-commons

1.  From CVS, check out *caintegrator-analysis-commons module* under
    *\<work-area\>*. Verify that the "src" and "lib" folders are
    available under *\<work-area\>/ caintegrator-analysis-commons.*

2.  From the command shell (like cmd, bash, sh etc.), change working
    directory to *\<work-area\>/ caintegrator-analysis-commons.*

3.  To build caintegrator-analysis-commons, run **ant build_dependency**

4.  Verify that there were no errors and that
    *caintegrator-analysis-commons.jar* has been created under
    *\<work-area\>/artifacts* folder.

## Step 2: Building caintegrator-spec

Note: Recall that the *weka.jar* was been extracted earlier. This file
and *caintegrator-analysis-commons.jar* are required to build
*caintegrator-spec.jar*

1.  From cvs, check out *caintegrator-spec* module under
    *\<work-area\>*. Verify that the "src" and "deployed_jars" folders
    are available under *\<work-area\>/ caintegrator-spec.*

2.  Copy the *\<work-area\>/*[weka-3-4-10/]{.underline}*weka.jar* file
    to the *\<work-area\>/ caintegrator-spec/deployed_jars* directory.

3.  From the shell prompt, change working directory to *\<work-area\>/
    caintegrator-spec.*

4.  Build caintegrator-spec, by running **ant build_dependency**

5.  Verify that there were no errors and that *caintegrator-spec.jar*
    has been created under *\<work-area\>/artifacts* folder.

## Step 3: Building caintegrator-application-commons

Note: *caintegrator-spec.jar and caintegrator-analysis-commons.jar* are
required to build caintegrator-application-commons.

1.  From cvs, check out *caintegrator-application-commons* file under
    *\<work-area\>*. Verify that the "src" and "lib" folders are
    available under *\<work-area\>/ caintegrator-application-commons.*

2.  From the shell prompt, change working directory to *\<work-area\>/
    caintegrator-application-commons.*

3.  Build caintegrator-application-commons, by running **ant
    build_dependency**

4.  Verify that there were no errors and that
    *caintegrator-application-commons.jar* has been created under
    *\<work-area\>/artifacts* folder.

## Step 4: Building ispy.war

Note: *caintegrator-spec.jar , caintegrator-analysis-commons.jar and
caintegrator-application-commons.jar* are required to build *ispy.war.*

1.  From cvs, check out *ispyportal* under *\<work-area\>*. Verify that
    the "src", "not_deployed_jars" , test, "conf" and "WebRoot" folders
    are available under *\<work-area\>/ispyportal.*

2.  From the shell prompt, change working directory to *\<work-area\>/
    ispyportal*

3.  Build ispy.war file, by running **ant build_war_anthill**

4.  Verify that there were no errors and that *ispyportal.war* has been
    created under *\<work-area\>/artifacts* folder.

5.  Go to the artifacts folder artifacts folder (which was created by
    running the ant build right from step 1 mentioned above and is
    located at /\<work-area\> /artifacts/ ) and you should see the
    following files:

> [ApplicationSecurityConfig.xml]{.mark}
>
> [ oracle-ds.xml]{.mark}
>
> [ properties-service.xml]{.mark}
>
> [login-config.xml]{.mark}

## Step 5: Configure JBOSS for I-SPY application

Setup Externalized Properties

Assume JBoss is installed in the directory **/usr/local/jboss404/**
.Denoted by \<JBOSS_HOME\>

Create a folder for ispy external properties, such as
/**local/content/ispyportal/config**

**Denoted by \<EXTERNAL\>**

1\. Edit /\<JBOSS_HOME\>/deploy/properties-service.xml file, Scroll down
to

\<mbean code=\"org.jboss.varia.property.SystemPropertiesService\"
name=\"jboss:type=Service,name=SystemProperties\"\>

2\. Add the following attribute tags exist inside the node

Assume the JBoss is installed in the directory
/\<JBOSS_HOME\>/deploy/properties-service.xml

**\<attribute name=\"Properties\"\>**

**gov.nih.nci.caintegrator.configFile=/\<JBOSS_HOME\>/server/default/conf/caIntegratorConfig.xml**

**\</attribute\>**

**\<attribute name=\"Properties\"\>**

**gov.nih.nci.ispyportal.propertiesFile=/\<EXTERNAL\>/ispyportal.properties**

**\</attribute\>**

3\. Copy the caIntegratorConfig.xml file provided by the ispy.war build
process into the directory **/\<JBOSS_HOME\>/server/default/conf .**

4\. Copy the files ispy-domain-hibernate.cfg.xml and
ispyportal.properties provided by the ispy.war build process into the
directory /\<**EXTERNAL\>**

5\. Modify "ispy-domain-hibernate.cfg.xml" to have the proper database
url, username and password by setting the following properties

**\<property name=\"connection.url\"\>YOUR_CONNECTION_URL\</property\>**

**\<property
name=\"connection.username\"\>YOUR_CONNECTION_USERNAME\</property\>**

**\<property
name=\"connection.password\"\>YOUR_CONNECTION_PASSWORD\</property\>**

6\. Modify the ispyportal.properties file and set the JNDI port in the
property

gov.nih.nci.ispyportal.jms.jboss.url=localhost:YOUR_JNDI_PORT

gov.nih.nci.ispyportal.agilent_data_matrix= ISPY.fake.Rda

7\. Go to the directory /local/content/ispyportal/data and remove all
files in the directory. Next, download [newDataFile.zip]{.underline}
from the
[[https://gforge.nci.nih.gov/frs/download.php/2609/newDataFile.zip]{.underline}](https://gforge.nci.nih.gov/frs/download.php/2609/newDataFile.zip)
and place it in the directory /local/content/ispyportal/data . Extract
the data files from the **newDataFile.zip**

8\. Verify that the files ispy-jbossmq-destinations-service.xml and
caintegrator-jbossmq-destinations-service.xml exist in the directory
**/usr/local/jboss404/server/default/deploy/jms**

## Step 6: Configure CSM v3.1

1\. Copy ispy.hibernate.cfg.xml to /\<JBOSS_HOME\>/server/default/conf

2\. Add the following content into
/\<JBOSS_HOME\>/server/default/conf/login-config.xml

\<application-policy name=\"ispy\"\>

\<authentication\>

\<login-module
code=\"gov.nih.nci.security.authentication.loginmodules.LDAPLoginModule\"
flag=\"required\"\>

\<module-option
name=\"ldapHost\"\>ldaps://\<LDAP_SERVER\>:\<LDAP_PORT\>\</module-option\>

\<module-option
name=\"ldapSearchableBase\"\>ou=nci,o=nih\</module-option\>

\<module-option name=\"ldapUserIdLabel\"\>cn\</module-option\>

\</login-module\>

\</authentication\>

\</application-policy\>

3\. Copy the following contents in to
/\<JBOSS_HOME\>/server/default/deploy/oracle-ds.xml

\<local-tx-datasource\>

\<jndi-name\>ispycsm\</jndi-name\>

\<connection-url\>jdbc:url\</connection-url\>

\<user-name\>user name\</user-name\>

\<password\>password\</password\>

\<driver-class\>oracle.jdbc.driver.OracleDriver\</driver-class\>

\<exception-sorter-class-name\>

org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter

> \</exception-sorter-class-name\>

\</local-tx-datasource\>

4\. if the following does not exist in
/\<JBOSS_HOME\>/server/default/deploy/properties-service.xml, then add
it

\<attribute name=\"Properties\"\>

gov.nih.nci.security.configFile=/\<JBOSS_HOME\>/server/default/conf/ApplicationSecurityConfig.xml

\</attribute\>

5\. copy the following into /\<JBOSS_HOME\>/server/default/conf/
ApplicationSecurityConfig

\<application\>

\<context-name\>

ispy

\</context-name\>

\<authentication\>

\<authentication-provider-class\>

\<!\-- Fully qualified class name\--\>

\</authentication-provider-class\>

\</authentication\>

\<authorization\>

\<authorization-provider-class\>

\<!\-- Fully qualified class name\--\>

\</authorization-provider-class\>

\<hibernate-config-file\>

/usr/local/jboss-4.0.4.GA/server/default/conf/ispy.hibernate.cfg.xml

\</hibernate-config-file\>

\</authorization\>

\</application\>

## Step 7: Deploy I-SPY application under JBoss

The *ispy.war* is ready to be deployed to JBoss. Copy the *ispy.war*
file, located at */artifacts/,* to the proper location
*/\<JBOSS_HOME\>/server/default/deploy/*

Restart the JBoss container that owns the directory where this file was
placed.

# Verification

1)  Start JBOSS and navigate your web browser to:
    http://\<JBOSS_SERVER:PORT\>/ispy/ (for example
    <http://localhost:8080/ispy>).

2)  Login using the guest login: [NCIISPYGuest]{.mark}

3)  Verify that you can login correctly (You should see the legal rules
    of the road page). Click the Agreement Link and then click on the
    search tab.

4)  Select the IHC Level Of Expression button. Select EGFR biomarker and
    name the result C1. Then click submit.

5)  When the query finishes click on C1 under the Report Results. An IHC
    Level of Expression report should popup.

[]{.mark}

[]{.mark}

# Analysis Server {#analysis-server .Style-Chapter-Title-+-Right:--0.03\"}

The Analysis Server performs on-the-fly statistical calculations for the
caIntegartor application. It can be hosted on the same machine that runs
the I-SPY application or it can be run on any number of remote compute
machines. In the remote configuration, each compute machine communicates
with the Rembrandt application via the JBossMQ Java Messaging Service
(JMS) provided by JBoss. It is important to note that each compute
machine does not require its own JBoss instance. The Analysis Server
relies on the JMS queues defined in the JBoss instance running the
caIntegator application, such as I-SPY.

This installation was developed and tested on Linux RedHat 3.0.

If configuring multiple compute machines, step 2 only needs to be
performed once since all of the compute machines rely on the JBoss
instance hosting the application. Steps 1, 3, and 4 should be performed
on each compute machine.

# Assumptions and Requirements

The following assumptions are in place:

You have checked out the *caintegrator-analysis-server*. This archive
contains the data, code, and necessary libraries to build and run the
analysis server from the following cvs module

:pserver:anonymous@cbiocvs2.nci.nih.gov:/share/content/cvsroot

All repositories on cbiocvs2 are available through read-only anonymous
access (anonymous/anonymous) using the ext protocol.

  

For the analysis server, check out the following modules:

            caintegrator-analysis-commons

            caintegrator-analysis-server

You have Java and Ant installed, as listed in the general requirements.

R and Rserve have been installed. Please see the Rserve homepage at:

http://stats.math.uni-augsburg.de/Rserve/

And the Rserve installation instructions:

http://stats.math.uni-augsburg.de/Rserve/doc.shtml

It is recommended that you read the Rserve installation instructions
before installing R. Specifically, the Rserve instructions recommend
building the R distribution from source using the **\--enable-R-shlib**
flag.

The R source distribution can be obtained from R project site:

[http://www.r-project.org/]{.underline} (click the link under download)

# Installation

Follow the sequence to properly install the Analysis Server.

1\) Unzip the file *caintegrator-analysis-server.zip*

On the machine(s) that will be used to run the analysis server, extract
the file

*caintegrator-analysis-server.zip* to the directory where the software
is to be installed.

The subdirectory named [caintegrator-analysis-server]{.underline} which
is located under the [caintegrator-ver1.0]{.underline} directory will be
referred to as the "analysis server install directory" in subsequent
steps.

2\) Configure the Java Messaging Service (JMS) queue destinations

Copy the file *ispy-jbossmq-destinations-service.xml* from the conf
directory and place it in the
[\<JBOSS_HOME\>/server/default/deploy/jms/]{.underline} directory on the
machine where ISPY is to be deployed (this may or may not be the same
machine running the analysis server).

Restart JBoss.

Two JMS queue destinations named AnalysisRequest and AnalysisResponse
will now be available.

3\) Configure the Analysis Server Build

Open the file [basic-build.properties]{.underline} file in a text
editor.

Change the property: **jms.location** to point to the machine hosting
the Rembrandt application. The port number is the JBoss jnpPort number.
For example, if the JBoss instance hosting Rembrandt is located on a
machine called:

rembrandt-server.myinstitution.org and jnpPort=1099 then the
**jms.location** property would look like:

jms.location=ispy-server.myinstitution.org:1099

The jnpPort number can be found by looking at the JBoss startup output
line containing the text **"INFO \[NamingService\]".**

Change the property: **analysis-server.install.dir** to contain the full
path to the analysis server install directory. For example, if the
*caintegrator-analysis-server.zip* file was downloaded and extracted
into the directory [/usr/applications]{.underline} then the
**analysis-server.install.dir** property would look like:

**analysis-server.install.dir=/usr/applications/caintegrator-ver1.0/caintegrator-analysis-server**

Download the latest client jar file (use the exceptions version) from:

[http://stats.math.uni-augsburg.de/Rserve/down.shtml]{.underline} after
agreeing to their licensing terms and conditions. The latest file at
this time is: *JRclient-RE817.jar*

Copy the downloaded file into the lib directory under the analysis
server install directory and rename it to *Rserve.jar* .

4\) Build the Analysis Server

Change to the analysis server install directory and type **ant**. When
the build completes successfully, the analysis server will be ready to
run.

5\) cd to /local/content/caintegrator.

Copy ISPY.fake.Rda to that folder.

# Running the Analysis Server

1\) Go to the [bin]{.underline} subdirectory of the analysis server
install directory.

2\) Enable permission to execute the script files using the Unix command
**chmod**. For example, to give the owner of the files permission to
execute the scripts type:

chmod u+x \*.sh

3\) Execute the Unix command: **dos2unix \*.sh**

4\) Make sure that the JAVA_HOME environment variable is set to point to
the directory where the Java SDK is installed. For example if the Java
SDK is installed in the directory [/usr/j2sdk1.5.0_05]{.underline} then
issuing the command:

echo \$JAVA_HOME should give output: /usr/j2sdk1.5.0_05

The Unix **export** or **set** command (depending on your shell) can be
used to set the JAVA_HOME environment variable.

5\) Start Rserve by typing: **./startRserve.sh**

Rserve should now be running. The last line printed on the console
should be:

"**Rserv started in daemon mode**."

6\) Start the Analysis Server by typing: **./runAnalysisServer.sh**

You should see the output: **"nohup: appending output to \`nohup.out'"**

(Hit the enter key to get to the Unix prompt)

The Analysis Server should now be running and listening for requests. To
verify that it is running, change to the log directory and type the
command: **tail analysisServer.log**. You should see a line with: **"Now
listening for requests\..."**. If instead, you see a line with: **"could
not establish connection with provider.."** see the troubleshooting
section below.

7\) The analysis server will run continuously listening for and
responding to requests. If the JMS provider (JBossMQ) goes down (for
example if JBoss is restarted) it will automatically reconnect when
JBossMQ becomes available.

To stop the analysis server, find the process ids associated with the
analysis server and Rserve using the Unix **ps** command. The analysis
server command name will start with java and the Rserve processes will
start with Rserve. Then **kill** the processes using the Unix **kill**
command.

# Troubleshooting

-   "**could not establish connection with provider..**" when starting
    the Analysis Server.

This error can occur when the Java Messaging Service (JMS) provider is
not running or has not fully initialized. Make sure that the JMS
provider that is configured in the analysis server build file is
running. If it is running but has not fully initialized the analysis
server will automatically connect when it is fully initialized.

-   Analysis Server appears to be running but no results are returned.

Using the jmx-console (see the JBoss documentation) application go to
the jboss.mq.destination section and inspect the AnalysisResponseQueue.
Make sure that the receivers count equals 1. If it is greater than 1
then there is another listener on the queue which is stealing the
results from application.

Next inspect the AnalysisRequestQueue. Make sure that the receivers
count is equal to the number of analysis server machines. For example if
you have configured four analysis server machines then the receivers
count should equal four.

If the receiver counts are not as expected then the problem may stem
from network/firewall issues or from a conflicting instance of the
application.

-   If you are using a version of JBoss other than 4.0.2, you should
    replace the following jar files:

> *concurrent.jar*
>
> *jbossmq-client.jar*
>
> *jboss-common-client.jar*
>
> *jboss-system-client.jar*
>
> *jnp-client.jar*

in the [lib]{.underline} directory under the analysis server install
directory, with the corresponding jar files from the JBoss distribution.

# Appendix A: 3rd Party Tools {#appendix-a-3rd-party-tools .Style-Chapter-Title-+-Right:--0.03\"}

+--------------+------+-------------------------+---------------------+
| 3rd Party    | Ver  | URL                     | License Info/URL    |
| Tool         | sion |                         |                     |
+--------------+------+-------------------------+---------------------+
| ehCache      | 1.1  | [[http://eh             | [[ht                |
|              |      | cache.sourceforge.net/] | tp://ehcache.source |
|              |      | {.underline}](http://eh | forge.net/]{.underl |
|              |      | cache.sourceforge.net/) | ine}](http://ehcach |
|              |      |                         | e.sourceforge.net/) |
|              |      |                         |                     |
|              |      |                         | Available under the |
|              |      |                         | Apache 1.1license.  |
|              |      |                         | Ehcache\'s          |
|              |      |                         | copyright and       |
|              |      |                         | licensing has been  |
|              |      |                         | reviewed and        |
|              |      |                         | approved by the     |
|              |      |                         | Apache Software     |
|              |      |                         | Foundation, making  |
|              |      |                         | ehcache suitable    |
|              |      |                         | for use in Apache   |
|              |      |                         | projects.           |
+--------------+------+-------------------------+---------------------+
| JFreechart   | 1    | [[http:/                | [[http://www.jfree. |
|              | .0.0 | /www.jfree.org/jfreecha | org/lgpl.php]{.unde |
|              | rc1  | rt/index.php]{.underlin | rline}](http://www. |
|              |      | e}](http://www.jfree.or | jfree.org/lgpl.php) |
|              |      | g/jfreechart/index.php) |                     |
|              |      |                         | complete source     |
|              |      |                         | code is included,   |
|              |      |                         | under the terms of  |
|              |      |                         | the [[GNU Lesser    |
|              |      |                         | General Public      |
|              |      |                         | Licence]{.under     |
|              |      |                         | line}](http://www.j |
|              |      |                         | free.org/lgpl.php); |
|              |      |                         |                     |
|              |      |                         | [[htt               |
|              |      |                         | p://www.jfree.org/j |
|              |      |                         | freechart/index.php |
|              |      |                         | ]{.underline}](http |
|              |      |                         | ://www.jfree.org/jf |
|              |      |                         | reechart/index.php) |
+--------------+------+-------------------------+---------------------+
| Apache       | 1.1  | [[http://struts.apache  |                     |
| Struts       |      | .org/]{.underline}](htt |                     |
|              |      | p://struts.apache.org/) |                     |
+--------------+------+-------------------------+---------------------+
| Rserve       |      | [[http:/                | GPL software        |
|              |      | /stats.math.uni-augsbur | **license**         |
|              |      | g.de/Rserve/]{.underlin |                     |
|              |      | e}](http://stats.math.u |                     |
|              |      | ni-augsburg.de/Rserve/) |                     |
+--------------+------+-------------------------+---------------------+
| DWR          | 1.0  | [[h                     | [[http://www.apac   |
|              |      | ttp://getahead.ltd.uk/h | he.org/licenses/LIC |
|              |      | ome]{.underline}](http: | ENSE-2.0.html]{.und |
|              |      | //getahead.ltd.uk/home) | erline}](http://www |
|              |      |                         | .apache.org/license |
|              |      |                         | s/LICENSE-2.0.html) |
+--------------+------+-------------------------+---------------------+
| DOM4J        | 1    | [[http://www.d          | [[http:/            |
|              | .5.2 | om4j.org/]{.underline}] | /www.dom4j.org/lice |
|              |      | (http://www.dom4j.org/) | nse.html]{.underlin |
|              |      |                         | e}](http://www.dom4 |
|              |      |                         | j.org/license.html) |
|              |      |                         | BSD License         |
+--------------+------+-------------------------+---------------------+
| Hibernate    | 2.   | [[http://www.hibernat   | [[http:/            |
|              | 1.7c | e.org]{.underline}](htt | /www.hibernate.org/ |
|              |      | p://www.hibernate.org/) | 356.html]{.underlin |
|              |      |                         | e}](http://www.hibe |
|              |      |                         | rnate.org/356.html) |
|              |      |                         | BSD License         |
+--------------+------+-------------------------+---------------------+
| Krys         | 1    | [[http:/                | [[http://           |
| alis-jCharts | .0.0 | /jcharts.sourceforge.ne | jcharts.sourceforge |
|              | -alp | t/index.html]{.underlin | .net/license.html]{ |
|              | ha-1 | e}](http://jcharts.sour | .underline}](http:/ |
|              |      | ceforge.net/index.html) | /jcharts.sourceforg |
|              |      |                         | e.net/license.html) |
|              |      |                         | BSD License         |
+--------------+------+-------------------------+---------------------+
| log4j        | 1    | [[http://logging.apache | [[http://vmgump     |
|              | .2.8 | .org/log4j/docs/]{.unde | .apache.org/gump/pu |
|              |      | rline}](http://logging. | blic-jars/nlog4j/ja |
|              |      | apache.org/log4j/docs/) | rs/LICENSE.txt]{.un |
|              |      |                         | derline}](http://vm |
|              |      |                         | gump.apache.org/gum |
|              |      |                         | p/public-jars/nlog4 |
|              |      |                         | j/jars/LICENSE.txt) |
+--------------+------+-------------------------+---------------------+
| p6spy        |      | [[http://www.p          | [[http://www.i      |
|              |      | 6spy.com/]{.underline}] | biblio.org/maven/p6 |
|              |      | (http://www.p6spy.com/) | spy/licenses/licens |
|              |      |                         | e.htm]{.underline}] |
|              |      |                         | (http://www.ibiblio |
|              |      |                         | .org/maven/p6spy/li |
|              |      |                         | censes/license.htm) |
+--------------+------+-------------------------+---------------------+
| velocity     | 1    | [[http://jakarta.ap     | [[http:/            |
|              | .3.1 | ache.org/velocity/]{.un | /jakarta.apache.org |
|              |      | derline}](http://jakart | /velocity/docs/lice |
|              |      | a.apache.org/velocity/) | nse.html]{.underlin |
|              |      |                         | e}](http://jakarta. |
|              |      |                         | apache.org/velocity |
|              |      |                         | /docs/license.html) |
+--------------+------+-------------------------+---------------------+
| xdoclet      | 1    | [[http://xd             | BSD                 |
|              | .2b3 | oclet.sourceforge.net/] | [[                  |
|              | -dev | {.underline}](http://xd | http://xdoclet.sour |
|              |      | oclet.sourceforge.net/) | ceforge.net/xdoclet |
|              |      |                         | /licenses/xdoclet-l |
|              |      |                         | icense.html]{.under |
|              |      |                         | line}](http://xdocl |
|              |      |                         | et.sourceforge.net/ |
|              |      |                         | xdoclet/licenses/xd |
|              |      |                         | oclet-license.html) |
+--------------+------+-------------------------+---------------------+
| xjavadoc     | 1.0  | [[http                  |                     |
|              |      | ://xdoclet.sourceforge. |                     |
|              |      | net/xjavadoc/]{.underli |                     |
|              |      | ne}](http://xdoclet.sou |                     |
|              |      | rceforge.net/xjavadoc/) |                     |
+--------------+------+-------------------------+---------------------+
| db-ojb-1.0   | 1.0  |                         |                     |
| .rc4-src.jar | .rc4 |                         |                     |
+--------------+------+-------------------------+---------------------+
| jakarta      | 1.2  | [[http://jakart         |                     |
| regexp       |      | a.apache.org/regexp/]{. |                     |
|              |      | underline}](http://jaka |                     |
|              |      | rta.apache.org/regexp/) |                     |
+--------------+------+-------------------------+---------------------+
| Java API for |      |                         |                     |
| Servlets -   |      |                         |                     |
| javax        |      |                         |                     |
| .servlet.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| javax.ser    |      |                         |                     |
| vlet.jsp.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| JBOSS -j2ee  |      | [[http://www.j          |                     |
|              |      | boss.org/]{.underline}] |                     |
|              |      | (http://www.jboss.org/) |                     |
+--------------+------+-------------------------+---------------------+
| Java Data    | jdo  | [[http://www.javara     |                     |
| Objects      | .jar | nch.com/newsletter/2004 |                     |
|              |      | 01/IntroToJDO.html]{.un |                     |
|              |      | derline}](http://www.ja |                     |
|              |      | varanch.com/newsletter/ |                     |
|              |      | 200401/IntroToJDO.html) |                     |
+--------------+------+-------------------------+---------------------+
| Sun's        | j    |                         |                     |
| reference    | dori |                         |                     |
| im           | .jar |                         |                     |
| plementation |      |                         |                     |
| of the JDO   |      |                         |                     |
| s            |      |                         |                     |
| pecification |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| antlr.jar    |      | [[http://www.a          | [[http:/            |
|              |      | ntlr.org/]{.underline}] | /www.antlr.org/lice |
|              |      | (http://www.antlr.org/) | nse.html]{.underlin |
|              |      |                         | e}](http://www.antl |
|              |      |                         | r.org/license.html) |
+--------------+------+-------------------------+---------------------+
| appSta       |      |                         |                     |
| teClient.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| batik-       |      | [[htt                   |                     |
| awt-util.jar |      | p://xml.apache.org/bati |                     |
|              |      | k/]{.underline}](http:/ |                     |
|              |      | /xml.apache.org/batik/) |                     |
+--------------+------+-------------------------+---------------------+
| b            |      | [[htt                   |                     |
| atik-dom.jar |      | p://xml.apache.org/bati |                     |
|              |      | k/]{.underline}](http:/ |                     |
|              |      | /xml.apache.org/batik/) |                     |
+--------------+------+-------------------------+---------------------+
| bati         |      | [[htt                   |                     |
| k-svggen.jar |      | p://xml.apache.org/bati |                     |
|              |      | k/]{.underline}](http:/ |                     |
|              |      | /xml.apache.org/batik/) |                     |
+--------------+------+-------------------------+---------------------+
| ba           |      | [[htt                   |                     |
| tik-util.jar |      | p://xml.apache.org/bati |                     |
|              |      | k/]{.underline}](http:/ |                     |
|              |      | /xml.apache.org/batik/) |                     |
+--------------+------+-------------------------+---------------------+
| b            |      | [[htt                   |                     |
| atik-xml.jar |      | p://xml.apache.org/bati |                     |
|              |      | k/]{.underline}](http:/ |                     |
|              |      | /xml.apache.org/batik/) |                     |
+--------------+------+-------------------------+---------------------+
| c3p0         |      |                         |                     |
| -0.8.4.5.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| caBIO        | c    | [[http://ncicb          |                     |
|              | aBIO | .nci.nih.gov/NCICB/infr |                     |
|              | .jar | astructure/cacore_overv |                     |
|              |      | iew/caBIO]{.underline}] |                     |
|              |      | (http://ncicb.nci.nih.g |                     |
|              |      | ov/NCICB/infrastructure |                     |
|              |      | /cacore_overview/caBIO) |                     |
+--------------+------+-------------------------+---------------------+
| cglib-fu     | 2    |                         |                     |
| ll-2.0.2.jar | .0.2 |                         |                     |
+--------------+------+-------------------------+---------------------+
| commons-b    |      | [[http://jakar          |                     |
| eanutils.jar |      | ta.apache.org/commons/b |                     |
|              |      | eanutils/]{.underline}] |                     |
|              |      | (http://jakarta.apache. |                     |
|              |      | org/commons/beanutils/) |                     |
+--------------+------+-------------------------+---------------------+
| com          | 3.1  | [[htt                   |                     |
| mons-collect |      | p://jakarta.apache.org/ |                     |
| ions-3.1.jar |      | site/downloads/download |                     |
|              |      | s_commons-collections.c |                     |
|              |      | gi]{.underline}](http:/ |                     |
|              |      | /jakarta.apache.org/sit |                     |
|              |      | e/downloads/downloads_c |                     |
|              |      | ommons-collections.cgi) |                     |
+--------------+------+-------------------------+---------------------+
| comm         |      |                         |                     |
| ons-dbcp.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| commons-     |      | [[http://jak            |                     |
| digester.jar |      | arta.apache.org/commons |                     |
|              |      | /digester/]{.underline} |                     |
|              |      | ](http://jakarta.apache |                     |
|              |      | .org/commons/digester/) |                     |
+--------------+------+-------------------------+---------------------+
| commons-fi   |      |                         |                     |
| leupload.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| commons-     |      |                         |                     |
| lang-2.0.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| com          | 1    | [[http://j              |                     |
| mons-logging | .0.4 | akarta.apache.org/commo |                     |
|              | .jar | ns/logging/]{.underline |                     |
|              |      | }](http://jakarta.apach |                     |
|              |      | e.org/commons/logging/) |                     |
+--------------+------+-------------------------+---------------------+
| comm         |      |                         |                     |
| ons-pool.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| commons-v    |      |                         |                     |
| alidator.jar |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| csmapi.jar   |      | [[http://nci            |                     |
|              |      | cb.nci.nih.gov/NCICB/in |                     |
|              |      | frastructure/cacore_ove |                     |
|              |      | rview/csm/]{.underline} |                     |
|              |      | ](http://ncicb.nci.nih. |                     |
|              |      | gov/NCICB/infrastructur |                     |
|              |      | e/cacore_overview/csm/) |                     |
+--------------+------+-------------------------+---------------------+
| jaas.jar     |      | [[http:                 |                     |
|              |      | //java.sun.com/products |                     |
|              |      | /jaas/install_notes.htm |                     |
|              |      | l]{.underline}](http:// |                     |
|              |      | java.sun.com/products/j |                     |
|              |      | aas/install_notes.html) |                     |
+--------------+------+-------------------------+---------------------+
| jak          |      | [[http://               |                     |
| arta-oro.jar |      | jakarta.apache.org/oro/ |                     |
|              |      | ]{.underline}](http://j |                     |
|              |      | akarta.apache.org/oro/) |                     |
+--------------+------+-------------------------+---------------------+
| jcommon-1    | 1    |                         |                     |
| .0.0-rc1.jar | .0.0 |                         |                     |
+--------------+------+-------------------------+---------------------+
| jcs.jar      |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| jdo.jar      |      |                         |                     |
+--------------+------+-------------------------+---------------------+
| odmg-3.0.jar | 3.0  |                         |                     |
+--------------+------+-------------------------+---------------------+
| ojdbc14.jar  |      |                         |                     |
+--------------+------+-------------------------+---------------------+