Home

Authors:

BOWS

User guide for BOWS installation and usage

Authors:

Henrique Velloso
Ricardo A Vialle
J Miguel Ortega

1. Introduction

BOWS is a generic system based on Web Services which allows programmatic access to applications running on HPC clusters. BOWS allows incorporation of several independent applications since programmers can install them in HPC clusters in any programming language. The lonely requirement is to write a script named “arrow” which calls BOWS back-end services periodically in order to check for new processes and their required parameters. If a new process is found, the “arrow” script should change the requisition status from waiting to running, run the process in the HPC cluster and, when the job is complete, call a BOWS back-end service to send the results. The results will then be available to the requestor. BOWS is called from the front-end by Web Services, therefore a program running in a simple computer can benefit of high performance computation executed elsewhere.

2. Installation

2.1. Requirements

Before downloading and installing BOWS, make sure that the following requirements are satisfied:

UNIX platform;
MySQL;
Java 1.7;
Apache Tomcat.

2.1.1. MySQL

BOWS requires MySQL. To install MySQL in a UNIX platform, follow these steps:
For Fedora, CentOS or RedHat operating systems, type the following command to download and install MySQL:

> sudo yum install mysql mysql-server

For Debian or Ubuntu operating systems, use this command:

> sudo apt-get install mysql mysql-server

After the installation, type these commands to configure your MySQL appropriately:

> chkconfig  mysqld on
> mysql_install_db
> service mysqld start

Then, create an administrator account (usually referred as root) and a password for it by typing:

> mysqladmin -u root password “[yourpassword]”

Now access the administrator account of MySQL with the username “root” and password “[yourpassword]” by typing in the Terminal:

> mysql -u root -p

mysql> CREATE USER 'bows'@'localhost' IDENTIFIED BY 'bows123';
mysql> GRANT ALL PRIVILEGES ON bows.* TO 'bows'@'localhost';

This user account is required by BOWS (see 2.3. Creating and configuring BOWS database).

2.1.2. Java

To install Java type on Terminal the following command line according to your Unix distribution:
Debian, Ubuntu, etc.

> sudo apt-get install openjdk-7-jre

Fedora, Oracle Linux, Red Hat Enterprise Linux, CentOS, etc.

> sudo yum install java-1.7.0-openjdk

2.1.3. Apache Tomcat

To install Tomcat type on Terminal the following command line according to your Unix distribution:
Debian, Ubuntu, etc.

> sudo apt-get install tomcat7

Fedora, Oracle Linux, Red Hat Enterprise Linux, CentOS, etc.

> sudo yum install tomcat

2.2. Downloading BOWS

BOWS is available at https://sourceforge.net/projects/bows/files/latest/download
After downloading the file, open a terminal, go to the directory where BOWS was downloaded and extract the content of BOWS.tar.gz by typing:

> tar -xzvf BOWS.tar.gz

2.3. Creating and configuring BOWS database

BOWS is configured to access MySQL as user "bows" with password "bows123" (see section MySQL in Requirements). To create and fill a MySQL database for BOWS usage, follow this procedures:

2.3.1. Creating a database for BOWS

Open a Terminal and access the bows account on MySQL by typing the command:

> mysql -u bows -pbows123

In the MySQL environment, create a database named bows by typing this command:

mysql> create database bows;

2.3.2. Populating the database

The file "bows.sql" corresponds to the database dump. To restore the tables into database, type the following command in the Terminal:

> mysql --user=bows --password=bows123 bows < bows.sql

2.4. Installing BOWS

To install the BOWS service, copy the file "BOWS.war" file into "webapps" folder of Apache Tomcat:

> cp BOWS.war /usr/share/tomcat/webapps/

Then restart the tomcat service by typing:

> service tomcat restart

After that BOWS will be working at address http://localhost:8080/BOWS/
WSDL descriptions will be available at: http://localhost:8080/BOWS/services/BOWS?wsdl and http://localhost:8080/BOWS/services/BOWSAdmin?wsdl

3. BOWS usage

3.1. Enrolling one application

To Create an application use the BOWSAdmin WSDL description.
An example code in java is shown below:

// Declare web service object
BOWSAdminServicePortTypeProxy service = new BOWSAdminServicePortTypeProxy();
// Parameters object
ApplicationParamConfig parameters = new ApplicationParamConfig();
parameters.setDefaultValue("defaultValue");
parameters.setDescription("description");
parameters.setExamples("examples");
parameters.setMandatory(true);
parameters.setMatcher("matcher");
parameters.setName("Parameter Name");
parameters.setValueBinary(false);
ApplicationParamConfig[] parametersList  = new ApplicationParamConfig[1];
parametersList[0] = parameters;
// Create app
service.createApplication("Author Code", "App Code", "App Name", "App Description", parametersList);

3.2. Back-end

Back-end also use the BOWSAdmin.
An example code in java is shown below:

// Declare web service object
BOWSAdminServicePortTypeProxy service = new BOWSAdminServicePortTypeProxy();
// Retrieve process information
ProcessDetailsResponse toRun = new ProcessDetailsResponse();
toRun = service.nextQueuedProcess("Author Code", "App Code", true);
long processId = toRun.getProcessId();
SubmissionParam[] params = new SubmissionParam[1];
params = toRun.getParams();
// Run app
//****code here****
// Insert result
DefaultResponse response = new DefaultResponse();
ProcessResultParam result = new ProcessResultParam();
result.setApplicationCode("App Code");
result.setIsBinary(false);
result.setMimeType("");
result.setProcessId(processId);
result.setResultBinary(null);
result.setResultText("Result text");
response = service.insertProcessResult(result);
System.out.println(response.getMessage());
// Change status
response = service.changeProcessStatus("Author Code", processId, "App Code", ProcessStatus.FINISHED , "No Error");

3.3. Front-end

To create the Front-end interface, use the BOWSService WSDL.
An example code to submit a new job in java is shown below:

// Declare web service object
BOWSServicePortTypeProxy service = new BOWSServicePortTypeProxy();
// Parameters object
SubmissionParam submitProcessParam = new SubmissionParam();
submitProcessParam.setBinary(false);
submitProcessParam.setBinaryValue(null);
submitProcessParam.setMimeType("");
submitProcessParam.setName("Parameter Name");
submitProcessParam.setTextValue("Parameter Value");
SubmissionParam[] submitProcessParamArray  = new SubmissionParam[1];
submitProcessParamArray[0] = submitProcessParam;        
// Submit job
SubmissionResponse submitResponse = new SubmissionResponse();
submitResponse = service.submitProcess("User Code","App Code",submitProcessParamArray);
// Return process id
long processId = submitResponse.getProcessId();

An example code to retrieve job result in java is shown below:

long processId = Long.parseLong(inputId);
// Declare webservice object
BOWSServicePortTypeProxy service = new BOWSServicePortTypeProxy();
// Check Status
if (new String("FINISHED").equals(service.checkProcessStatus("User Code",processId).getStatus().toString())){
    // Retrieve result
    ProcessResultResponse resultResponse = new ProcessResultResponse();
resultResponse = service.getProcessResult("User Code",processId);
System.out.println(resultResponse.getResultText());
return;
}else{
    System.out.println("Process status: " + service.checkProcessStatus("User Code",processId).getStatus().toString());
return;         
}

4. BOWS management interface and clients generator

4.1. BOWS Website

A website to enroll, visualize and remove applications registered in BOWS server is available through the file BOWSWeb.war. Install it in the same server that contains the BOWS.war, through the command:

cp BOWSWeb.war /usr/local/apache-tomcat-7.0.57/webapps/

The Apache Tomcat needs to use the default port 8080 for all features work properly.

4.2. BOWS auto-generated clients

The website will access the registered applications show their information and create java clients to back-end and front-end for each one.

4.2.1. Back-end auto-generated clients (Arrow)

The Arrow client is a executable jar that runs in loop looking for queued jobs to run, then it pass the parameters to a shell script that run the application and save the result into a file with an expected name.

Below there is an example of shell script generated:

#!/bin/sh
# Auto-generated BOWS arrow running script.
# Edit this script to run your app.
# If output is a TEXT value, write the result as $OUTTXT
# If output is a BINARY value, write the result as $OUTBIN
OUTTXT="${1}_out.txt"
OUTBIN="${1}_out.bin"
input=$2
# Write below your app running command

This script needs to be edit adding the command line that executes the application passing the parameters and sending the result to one of the output files ($OUTTXT for TEXT value result or $OUTBIN for BINARY value result), for example:

./run_app $input > $OUTTXT

After edit this script save it and let the jar client running on server. The jar receives the path to application as parameter:

> java -jar Arrow_yourapp.jar pathtoapp/

We recommend to register the arrow on crontab. To add to your crontab just run the script:

./add_to_crontab.sh

4.2.2. Front-end auto-generated clients

The website also creates the java clients for the end-user. On the application details page, it is available for download the Submit Job and the Get Results clients. The Get Results clients are the same for all applications registered, it receives only the job pid as parameter. To run it in use the command:

> java -jar getresults.jar -user usercode -pid 111

A GUI client for the Get Results are also available. Just double click on icon to run.

The Submit Job client receives the defined parameters and returns to user the job pid. To run it, for example:

> java -jar prankSubmitJob.jar -user usercode -fasta file.fasta

Attention for the parameter type, if it is registered as binary, the file name must to be used. If is text just pass the values inline.

5. BOWS Client: DEMOS

Three BOWS demos registered at http://biodados.icb.ufmg.br:8080/BOWS/services are available into file BOWS_DEMO.tar.gz

To retrieve the result for all demos, run the Get Results client with sending the process id parameter with the flag -pid, as shown below:

> java -jar getresults.jar -user usercode -pid 111

For each one there is also graphical user interface clients, that can be used by just double clicking on jar file.

5.1. Multiple Alignment with PRANK

Perform the PRANK multiple alignment remotely using BOWS management.
A file with sequences for example is available, to use just type:

> java -jar prankalignSubmitJob.jar -user usercode -fasta myoglobins

5.2. BLAST on UniProt Complete

Performs a BLASTp search on UniProt complete database (Fragment sequences removed).
BLASTp is configured with e-value of 1e-10 and maximum 200 hits. Results are available on BLAST output tabular format with comment lines with default columns adding the query and subject lengths and query coverage.

A file with sequences for example is available, to use just type:
> java -jar blastonuekoSubmitJob.jar -user usercode -fasta sequence.fasta

5.3. Clustering with SeedLinkage

SeedLinkage is a method to cluster cognate proteins from multiple organisms beginning with only one sequence, through connectivity saturation with that Seed sequence. To use just type:

> java -jar seedserverSubmitJob.jar -user usercode -seed Q01860,Q10589

The output contain three columns:
CLUSTER NUMBER TAX ID SEQUENCE ID
Cluster number refers to the number of the cluster that this particular sequence belongs, tax id is the taxon id for that same sequence and sequence id is the sequence id provided.

6. Troubleshooting

6.1

If you experience some problems with clients presenting the message:

"could not roll back hibernate transaction; nested exception is org.hibernate.transactionexception: jdbc rollback failed"

Try to restart your tomcat service to fix it.

> service tomcat restart

6.2

If you are having problems of disk usage by some tomcat files, try the command below:

> mv /etc/tomcat/logging.properties /etc/tomcat/logging.properties_OFF

7. License

BOWS software development: Henrique Velloso and Ricardo A. Vialle.

Laboratory of Biodados
Federal University of Minas Gerais Department of Biochemistry
Av. Antonio Carlos, 6627, Pampulha
Belo Horizonte – MG Brazil

The BOWS software is only available for download from https://sourceforge.net/projects/bows/
By installing BOWS, you are agreeing to be bound by this agreement ("Agreement"). If you do not agree with all of the terms of this Agreement, reject the Agreement by refusing to install the BOWS software.

1) Definitions

1.1) "DEVs" means the developers and copyright owners of BOWS software, as defined at the beginning of this License Agreement.

2) Ownership

2.1) The Software is owned and copyrighted by DEVs. This Agreement confers no title or ownership in the Software and is not a sale of any rights in the Software.

2.2) This Agreement does not grant you and/or any person(s) acting with you or for you, any rights or license with respect to the source code of the Software.

3) Disclaimer of Warranties & Limitation of Liability

THE SOFTWARE IS PROVIDED BY DEVs "AS IS" WITHOUT A WARRANTY OF ANY KIND, AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DEVs BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. NO WARRANTY IS MADE THAT THE SOFTWARE WILL MEET YOUR REQUIREMENTS.

4) Indemnification

You agree to fully indemnify and hold harmless DEVs from and against any and all claims, liabilities, demands, suits, losses, damages, costs, settlement amounts, and/or expenses, including but not limited to attorneys' fees, arising out of your use of the Software.

The following BSD LICENSE applies to these custom functions only, referred to as "THIS SOFTWARE":

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

BOWS Wiki

Bioinformatics Open Web Services

Home

BOWS

User guide for BOWS installation and usage

Authors:

1. Introduction

2. Installation

2.1. Requirements

2.1.1. MySQL

2.1.2. Java

2.1.3. Apache Tomcat

2.2. Downloading BOWS

2.3. Creating and configuring BOWS database

2.3.1. Creating a database for BOWS

2.3.2. Populating the database

2.4. Installing BOWS

3. BOWS usage

3.1. Enrolling one application

3.2. Back-end

3.3. Front-end

4. BOWS management interface and clients generator

4.1. BOWS Website

4.2. BOWS auto-generated clients

4.2.1. Back-end auto-generated clients (Arrow)

4.2.2. Front-end auto-generated clients

5. BOWS Client: DEMOS

5.1. Multiple Alignment with PRANK

5.2. BLAST on UniProt Complete

5.3. Clustering with SeedLinkage

6. Troubleshooting

6.1

6.2

7. License