Rbde

From Icbwiki

Revision as of 23:24, 16 August 2010; view current revision
←Older revision | Newer revision→
Jump to: navigation, search

Contents

About RbDe

RbDe is a web application to create and edit residue-based diagrams of (mostly transmembrane) proteins.

Getting RbDe

Please contact us to license RbDe (free for academic research, commercial licenses available).

Binary Distribution

Rbde is distributed as a zip file with the naming convention "rbde_xxx-bin.zip" where "xxx" represents a specific version number of the build. The distribution can be extracted to a location of your choosing. The zip file will extract to a directory named "rbde_xxx". This directory shall be referenced by the name "<install-dir>" for the remainder of this document and will contain the following files:

  • README.html - A local copy of this file
  • rbdg.jar - Pre-Compiled program that generates residue-based diagrams of proteins
  • rbde.war - Pre-Compiled Web Application Archive (.war)
  • nrdb/ - Sample data for use with RbDg
  • sql/ - sql scripts used to create the database tables for the RbDe web application

Subversion Access from the ICB local environment

This project's Subversion repository can be checked out through SVN with the following instruction set:

 https://pbtech-vc.med.cornell.edu/public/svn/icb/trunk/rbde/

Browse RbDe in the Subversion repository.

Building RbDe

Note that this section is meant only for those with access to the RbDe source distribution. Users of the binary distribution should skip this section.

Software Requirements

Running JUnit Tests

RbDe is built using ant and a build.xml file located in the <install-dir>. The default target will compile rbde and run the junit tests.

Building the RbDe Web Application

The target used to build the Rbde web application is called "war". Executing ant war will produce a file called "rbde.war" in the <install-dir>.

Building the RbDg application

The target used to build Rbdg is called "jar". Executing ant jar will produce a file called "rbdg.jar" in the <install-dir>.

Installing RbDe

Software Requirements

  • Java Runtime 1.4+ (note: version 1.5 or better is recommended)
  • A SQL database such as Oracle or MySQL and appropriate JDBC drivers. (note: Only Oracle has been officially tested)
  • A servlet container such as Apache Tomcat.
  • The JavaMail package.

Database Setup

You must create a SQL database before running RbDe. Your database adminstrator should set up a user and tablespace for RbDe to use. Once the database and appropriate permissions are set up, a sql script is provided that may be used to create the proper tables and indexes.

Assuming a user called 'rbde' with a password of 'mypassword' for a database running on the local machine, the script can be executed with the following command from the <install-dir>/sql directory:

 sqlplus rbde/mypassword@localhost @create-oracle.sql

Servlet Container (Tomcat) Configuration

RbDe has been tested using the Apache Tomcat servlet container. RbDe has been deployed successfully to Tomcat version 6.0.29.

Rather than "hardcoding" various site specific settings for RbDe, the web application will look for various JNDI resources. See the Tomcat JNDI Resources documentation for information. The settings below describe entries in the Tomcat "server.xml" configuration file. You will need to define the following parameters in Tomcat in order for RbDe to function properly.

Database Connection

RbDe uses a JDBC database to store items needed for the web application. In order for RbDe to make a connection to the database, a JNDI datasource must be made available to the web application. RbDe will look for an entry called "jdbc/rbde" in order to get a database connection. Assuming an Oracle database server running on "foobar.com" with a tablespace "rbde", add an entry such as the following to the GlobalNamingResources section of the server.xml:

 <Resource name="jdbc/rbde" type="javax.sql.DataSource"
           maxActive="4" maxIdle="2" username="RBDE" maxWait="5000"
           driverClassName="oracle.jdbc.driver.OracleDriver"
           password="mypassword" url="jdbc:oracle:thin:@foobar.com:1521:orcl"/>

Additionally, the appropriate JDBC driver jar file (such as must be made available to the web application. For example, when using Oracle, the ojdbc14.jar file should be placed into the "common/lib" directory of Tomcat. See the Tomcat JNDI Datasource documentation and your local database administrator for further information.

SMTP Mail Server

RbDe requires access to an SMTP mail server in order to send registration information to users of RbDe. RbDe will look for this information using JNDI under the name "mail/Session". Assuming the smtp mail server is called "mail.foobar.com", add an entry such as the following to the GlobalNamingResources section of the server.xml:

 <Resource name="mail/Session" type="javax.mail.Session"
           mail.smtp.host="mail.foobar.com"/>

Additionally, the mail.jar file from the JavaMail must be made available to RbDe. The mail.jar file from the Javamail distribution should be placed into the "common/lib" directory of Tomcat. Note that if you are not using Java 6 you will need to also place the activation.jar file from JavaBeans Activation Framework (JAF) into the "common/lib" directory of Tomcat. See the section titled JavaMail Sessions in the Tomcat JNDI Resources documentation for further information.

Diagram Layout Storage Directory

RbDe stores diagram layout information as plain text files. Typically the location of this directory should be somewhere outside the web application directory of Tomcat since this directory will get destroyed when the web application is undeployed or redeployed. Assuming the directory is called "/somedir/rbde/layouts", add an entry such as the following to the GlobalNamingResources section of the server.xml:

 <Environment description="Location where layout files should be stored for RbDe"
              name="rbde.layout.directory" type="java.lang.String"
              value="/somedir/rbde/layouts"/>

Note: If you have a previous version of RbDe installed, please copy the contents of the layouts directory from within the web application area (i.e., CATALINA_HOME/webapps/rbde/layouts) to the directory specified above. Redeploying RbDe will remove the contents of the layout directory if it is within the web application area.

HMMTOP (optional)

RbDe can be configured to predict transmembrane elements with a locally installed version of HMMTOP. Instructions for acquiring and installing HMMTOP can be found at the HMMTOP web site. RbDe needs to be made aware of the binary executable location, the location of the file containing the architecture of the model (i.e., HMMTOP_ARCH) and the file containing the pseudo count vector corresponding to the given architecture (i.e., HMMTOP_PSV). Assuming, the hmmtop files are all located in a directory called "/somedir/hmmtop", add entries such as the following to the GlobalNamingResources section of the server.xml:

 <Environment description="Full path to the HMMTOP executable"
              name="hmmtop.executable" type="java.lang.String"
              value="/somedir/hmmtop/hmmtop"/>
 <Environment description="Full path to the file containing the architecture for the HMMTOP model"
              name="hmmtop.arch" type="java.lang.String"
              value="/somedir/hmmtop/hmmtop.arch"/>
 <Environment description="Full path to the file containing the pseudo count for HMMTOP"
              name="hmmtop.psv" type="java.lang.String"
              value="/somedir/hmmtop/hmmtop.psv"/>

Deploying the RbDe web application

The RbDe web application is contained in rbde.war. This can easily be deployed to the Tomcat servlet engine through the use of the Tomcat Manager App or by simply placing the rbde.war file in the "webapps" directory for Tomcat. See the Tomcat Web Application Deployment documentation for further information.

Troubleshooting

Log Files

RbDe is configured to use Log4j to log informational and debug messages. By default, a file called "rbde.log" will be written to the Tomcat "logs" directory. Look here for any error or warning messages. Be sure to check other log files in the Tomcat log directory such as stdout.log, stderr.log and catalina.log for messages if the rbde.log file is not informative enough. The Log4j configuration file used by RbDe is located at WEB-INF/classes/log4j.properties in the web application archive. Consult the Log4j Documentation for information on how to change the log file location or change the verbosity of the messages.

Common Errors

The most common problems are related to the JNDI configuration. Check the log files for "Class not found" errors. This generally indicates that an external library is missing.

RbDg

RbDg is packaged as an executable jar file and should require no additional libraries or classpath settings beyond what the Java runtime includes. RbDg can be thought of as a batch version of RbDe. RbDg does not require any backend database or web server.

Testing

Sample input files

Some input files are included in the distribution. They are located in <install-dir>/nrdb/

For GPCRs, see <install-dir>/nrdb/gpcr-tm.xml. Sample files are also provided on the RbDg web pages.

Trying the sample files

From the rbde installation directory try:

 java -jar rbdg.jar -i nrdb/gpcr-tm.xml -verbose

This should produce some output on the standard output and generate gif, jpg and svg diagrams as well as the RbDg output file.

Otherwise, please see the help message for further options:

 java -jar rbdg.jar -help

Troubleshooting

Log Files

RbDg is configured to use Log4j to log informational and debug messages. By default, a file called "rbde.log" will be written to the "logs" directory inside the <install-dir>. Look here and at any console output for error or warning messages.

Memory issues

If you get an "out of memory" exception, try increasing the amount of memory available to the Java virtual machine. This can be done by adding -Xmxn where "n" is the maximum size, in bytes, of the memory allocation pool. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes. For example:

 java -Xmx600m -jar rbdg.jar -i nrdb/gpcr-tm.xml

means that the maximum memory available to the program is 600 megabytes.

More Information

RbDe Project Page
RbDg Project Page
RbDe Web Application
RbDg Javadocs
RbDe CruiseControl Test Results

RbDe CruiseControl Test Deployment

Personal tools