JABAWS MANUAL

JABAWS Server Web Application aRchive (WAR)

Troubleshooting

System Requirements

JABAWS requires a Java web application server compliant with version 2.4 of the Java Servlet specification, and a Java 6 runtime environment. We recommend using an official Oracle Java 6 runtime environment, and Apache-Tomcat web application server version 7, but older Tomcat versions above 5.5 would work too.
Please Note: The JABAWS WAR is not generally compatible with older Mac systems based on the PowerPC architecture, since Java 1.6 is not available to run JABAWS.

JABAWS Web Application aRchive can run on any host operating system that supports Java 1.6. However JABAWS depends on a number of third party programs which are not available for all operating systems. In particular, not all web services are currently available for MS Windows platform.

JABAWS comes with pre-compiled MS Windows and Linux x86 binaries, as well as the source code and build scripts necessary to recompile them.

To run JABAWS on the cluster you must have shared disk space accessible from all cluster nodes.

Installing the JABAWS WAR file

JABAWS is distributed as a web application archive (WAR). To deploy JABAWS in Apache-Tomcat - simply drop the war file into the webapps directory of a running Tomcat, and it will do the rest. If you used this deployment procedure, do not remove the jabaws WAR file, otherwise Tomcat will undeploy your application! The context path for your deployed application will be the same as the name of the war file. For example, assuming the Tomcat server is running on the localhost:8080 and jaba.war file is put into the <tomcat server root>/webapps directory, the deployed application from the jaba.war file then can be accessed by this URL http://localhost:8080/jaba.

For any other web application server, please follow your server's specific deployment procedure for 'WAR' files. If you install JABAWS on a MS Windows machine, then at this point your JABAWS installation will already be up and running, and you can try its services out as described here. If you install JABAWS on Linux you will need to set an executable flag for binaries. This is described here. If your host operating system is different from Windows or Linux then read on.

Preparing executables for use with JABAWS

JABAWS's web services use command line programs to do the actual analysis, so it must have access to programs which can be executed on your platform. The native executables bundled with JABAWS for Windows (32-bit) and Linux (i386, 32-bit) should be OK for those systems. The source code for these programs is also provided so you can recompile for your own architecture and exploit any optimizations that your system can provide. Alternately, if you have already got binaries on your system, then you can simply change the paths in JABAWS's configuration files so these are used instead.

Using the pre-compiled i386 binaries on Linux

JABAWS comes with pre-compiled x86 Linux binaries, thus on such systems JABAWS should work straight out of the box. If you are in any doubts or experience problems you may want to make sure that the binaries supplied work under your OS. To do this just execute each binary, without any command line options or input files. If you see an error message complaining about missing libraries or other problems, then you probably need to recompile the binaries.

You can try the JABAWS functionality with the JABAWS test client or have a look at deploying on Tomcat tips if you experience any problems.
Note: You may want to enable logging, as described here.

Recompiling the bundled programs for your system

If you have a fully equipped build environment on your (POSIX-like) system, then you should be able to recompile the programs from the source distributions which are included in the JABAWS war file. A script called 'compilebin.sh' is provided to automate this task.

  1. In a terminal window, change the working directory to binaries/src
  2. execute the compilebin.sh script,
    either use: chmod +x compilebin.sh; compilebin.sh > compilebin.out;
    or: sh compilebin.sh > compilebin.out
  3. Now run sh setexecflag.sh
    If any of the binaries was not recompiled, then a 'file not found' error will be raised.
  4. Finally, restart your Tomcat server (or JABAWS application only), and test JABAWS to check that it can use the new binaries.

If you couldn't compile everything, then it may be that your system does not have all the tools required for compiling the programs. At the very least check that you have gcc, g++ and make installed in your system. If not install these packages and repeat the compilation steps again. You should also review the compilebin.sh output - which was redirected to compilebin.out, and any errors output to the terminal. Finally, try obtaining the pre compiled binaries for your OS.

Reuse the binaries that are already in your system

If you would like to use the binaries you already have then you just need to let JABAWS know there they are. To do this, edit: conf/Executable.properties

When specifying paths to executables that already exist on your system, make sure you provide an absolute path, or one relative to the JABAWS directory inside webapps. For example, the default path for clustalw is defined aslocal.clustalw.bin=binaries/src/clustalw/src/clustalw2 Alternatively, instead of changing Executable.properties you could also replace the executables bundled with JABAWS with the ones that you have, or make symbolic links to them. Then the default configuration will work for you. More information about the Executable.properties file is given in the JABAWS Configuration chapter.

Obtaining command line binaries for your operating system

You could search for pre-packaged compiled executable in your system package repository or alternately, download pre-compiled binaries from each alignment program's home page. Then, either replace the executables supplied with the downloaded ones, or modify the paths in executable.properties as described above. Below are some suggestions on where you may be able to get the binaries for your system.

Testing JABAWS Server

First of all make sure that Tomcat server is started successfully. If this was the case, then you should see JABAWS home page when you navigate to your Tomcat JABAWS context path e.g. http://myhost.compbio.ac.uk:8080/jabaws

Using JABAWS service status checker

If you see it, then it is time to make sure that web services are working too. The easiest way to do so is to access Services Status page available from the main JABAWS web page menu.

If you need to monitor web service health automatically when the best option is to use service checker that responds with the standard HTTP status code. To access this checker use the following URL: <jabaws_server>/HttpCodeResponseServiceStatus This page returns code 200, and no page context if all services are operational, 503 if one of the services have problems. You can also check each web service individually by providing the name of the web service to check at the end of the service checker URL like this: <jabaws_server>/HttpCodeResponseServiceStatus/ClustalWS

Upon request, the service status checker will examine the health of the ClustalWS web service only. If the service name is not valid, then the service checker will return code 400.

Using command line client

Alternatively, you should be able to use the test program which can be found in <webapplicationpath>/WEB-INF/lib/jabaws-client.jar file. To run the tests type: java -jar jabaws-client.jar -h=<Your web application server host name, port and JABAWS context path>

For example to test all JABAWS web services on host myhost.compbio.ac.uk type:

java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws

You can choose a particular web server using -s option like this java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws -s=ClustalWS This command line assumes that java executable is in your path and jabaws-client.jar is located in the current directory.

An example of the report testing tool produces for operating web service looks like this:

Connecting to service MuscleWS on http://myhost.compbio.ac.uk:8080/jabaws ... OK
Testing alignment with default parameters:
Queering job status...OK
Retrieving results...OK
Testing alignment with presets:
Aligning with preset 'Protein alignment(Fastest speed)'... OK
Aligning with preset 'Nucleotide alignment(Fastest speed)'... OK
Aligning with preset 'Huge alignments (speed-oriented)'... OK
Queering presets...OK
Queering Parameters...OK
Queering Limits...OK
Queering Local Engine Limits...OK
Check is completed service MuscleWS IS WORKINGAn example of the response of a web service which is deployed but is not operating is below:

Connecting to service ProbconsWS on http://localhost:8080/ws ... OK
Testing alignment with default parameters:FAILED
Service ProbconsWS IS NOT FUNCTIONALIf the web server did not respond the message looks like following: Connecting to service TcoffeeWS on http://localhost:8080/ws ... FAILED

Running many JABAWS instances on the same server

JABAWS is supplied as a Web Application aRchive which can be dealt with as any other web applications. So it is perfectly possible to run two JABAWS instances from the same server. Just make two different contexts on your application server and unpack JABAWS in both of them. For example if your server name is http://www.align.ac.uk, and the context names are public and private. Than one group of users could be given a URL http://www.align.ac.uk/public and another http://www.align.ac.uk/private. These contexts will be served by two independent JABAWS instances, and could be configured differently. If you keep local engine enabled, make sure you reduce the number of threads local engine is allowed to use to avoid overloading the server. Alternatively two completely separate web application server instances (e.g. Apache-Tomcat) could be used. This will give you a better resilience and more flexibility in memory settings.

JABAWS on a single server

You can run JABAWS on a single server. Obviously the capacity will be limited, but may be sufficient for a small lab. Installed on a single server, JABAWS executes tasks in parallel, so the more cores the server has the more requests it will be able to handle.

JABAWS supported cluster batch management systems

JABAWS uses DRMAA v. 1.0 library to send and manage jobs on the cluster. DRMAA supports many different cluster job management systems. Namely Sun Grid Engine, Condor, PBS, GridWay, Globus 2/4, PBSPro, LSF. For up to date information please consult DRMAA web site. We found that DRMAA implementation differ from platform to platform and were trying to use only the basic functions. We have only tested JABAWS on Sun Grid Engine v 6.2. Please let use know if you have any experience of running JABAWS on other platforms.

Manually deploying JABAWS application on Apache-Tomcat

To stop Tomcat from automatically undeploying your application if the war file is removed use an explicit application descriptor. It could come in different flavors, the one I prefer if to drop a context descriptor file into <tomcatRoot>conf/Catalina/localhost directory. Name your context file the same as your application folder e.g. if you JABAWS resides in webappl/jabaws folder, then call the context file jabaws.xml. Below is an example of content this file might have.

<?xml version="1.0" encoding="UTF-8"?>
<Context antiResourceLocking="false" privileged="true" />

This should be sufficient to prevent Tomcat from removing your JABAWS from WEBAPPS. For more information about the Tomcat deployer read this documentation on the Apache-Tomcat web site.

Apache-Tomcat fails to deploy jabaws.war file

  • Make sure Tomcat have sufficient access rights to read your war file.
  • Restart the Tomcat, sometimes it will not since that the new war file is added without restart
  • If Tomcat still refuses to unpack the war file, unpack it manually into web application folder (the war file is just a zip archive). Restart the Tomcat.