1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
\r
2 <html xmlns="http://www.w3.org/1999/xhtml">
\r
4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
\r
5 <meta name="Last-modified" content="Mon, 11 Oct 2010 01:03:33 GMT"/>
\r
6 <title>Java Bioinformatics Analyses Web Services (JABAWS) developers howto</title>
\r
7 <link href="ws.css" rel="stylesheet" type="text/css" media="screen, projection, handheld, tv" />
\r
8 <link rel="stylesheet" type="text/css" media="print" href="print.css"/>
\r
10 <script type="text/javascript" src="prototype-1.6.0.3.js"></script>
\r
14 <div id="banner"><table>
\r
15 <tr><td style="width:130px;"><a href="http://www.dundee.ac.uk"><img class="logo" src="images/uod_lt.gif" alt="University of Dundee" title="University of Dundee" longdesc="http://www.dundee.ac.uk"/></a></td>
\r
16 <td class="bg"><h2><span class="headeru">JA</span>va <span class=
\r
17 "headeru">B</span>ioinformatics <span class="headeru">A</span>nalysis <span class="headeru">W</span>eb <span
\r
18 class="headeru">S</span>ervices</h2></td>
\r
21 </div><!-- banner end-->
\r
24 <a href="index.html">Home</a>
\r
25 <a href="manual.html">Manual</a>
\r
26 <a class="selected" href="howto.html">How To</a>
\r
27 <a href="dm_javadoc/index.html" title="Data model javadoc">Javadoc</a>
\r
28 <a href="download.html">Download</a>
\r
29 <a href="http://www.compbio.dundee.ac.uk">Barton Group</a></div>
\r
35 <h2 align="center">JABAWS How To</h2>
\r
36 <h3>Table of Content </h3>
\r
39 <li><a href="#wisjaba">What is JABAWS?</a></li>
\r
40 <li><a href="#wjaba">Why JABAWS?</a></li>
\r
41 <li><a href="#alprog">Which Alignment programs are supported?</a></li>
\r
42 <li><a href="#dmjavadoc">Is there a documentation for client library methods?</a></li>
\r
43 <li><a href="#usingcclient">Is there a command line client to JABAWS? </a></li>
\r
44 <li><a href="#cmdclient">Can I program against JABAWS? </a></li>
\r
45 <li><a href="#nomaffttcoffee">There are versions of Mafft and Tcoffee for windows, so why you do not support them?</a></li>
\r
47 <h4>Installation</h4>
\r
49 <li><a href="#hdjaba">How to deploy JABAWS? </a></li>
\r
50 <li><a href="#usingWsTester">I deployed JABAWS, how to make sure it is working?</a></li>
\r
51 <li><a href="#whichjaba">I want to use JABAWS. Which JABAWS distribution should I choose?</a></li>
\r
52 <li><a href="#opforjaba">What operation system JABAWS can run on?</a></li>
\r
53 <li><a href="#diffcontexts">Can I run many JABAWS instances on the same server?</a></li>
\r
54 <li><a href="#nocluster">Can I run my own JABAWS if I do not have a cluster?</a></li>
\r
55 <li><a href="#clustsubsys">My cluster uses LSF/PBS/SGE etc can I run JABAWS on my cluster?</a> </li>
\r
56 <li><a href="#noshareddisk">My cluster does not have shared disk space can I run JABAWS?</a></li>
\r
57 <li><a href="#wworkonwin">If I install JABAWS on windows which web services will work?</a></li>
\r
58 <li><a href="#nonwinbin">I do not use Windows and I am having troubles compiling binaries. Where can I get the pre compiled binaries for my system?</a></li>
\r
60 <h4>Configuration </h4>
\r
62 <li><a href="#diffbin"> Can I use a different version of the alignment program with JABAWS?</a></li>
\r
63 <li><a href="#cmdclientuse">Can I use a JABAWS command line client to connect and use JABAWS web services in Dundee and my local lab? </a></li>
\r
64 <li><a href="#mixuse">My cluster is quite busy so the waiting times in the task queue is significant. At the same time I have powerful server with many cores. Can I use the server for small tasks and send really big ones to the cluster? </a></li>
\r
65 <li><a href="#difflimits">I installed JABAWS in my lab. I would like to define different limits for public and lab users</a></li>
\r
66 <li><a href="#jabaonwin">I deployed JABAWS on windows why not all alignment programs work?</a><br />
\r
68 <li><a href="#logs">I would like to keep and eye on who is using JABAWS services on my server. </a></li>
\r
69 <li><a href="#canyouhelp">Sometimes something goes wrong with JABAWS, but I cannot figure out why. Can you help?</a></li>
\r
70 <li><a href="#execstat">I would like to know how much of the CPU time has been consumed and which tasks were the longest</a></li>
\r
71 <li><a href="#confaccessright">I noticed that jobsout, conf and binaries directories are not placed in WEB-INF directory are they not accessible to anyone?</a></li>
\r
72 <li><a href="#toomanyreqs">What happens if the number of requests to my JABAWS installation is greater the the server can process?</a></li>
\r
73 <li><a href="#canlimit">Sometimes users sent very large number of sequences to JABAWS server, so that it becomes unresponsive. Can I limit the number of sequences users can submit to my server. </a></li>
\r
75 <h4>Using JABAWS in your program (examples in java) </h4>
\r
77 <li><a href="#connectto">Connecting to JABAWS</a></li>
\r
78 <li><a href="#validnames">Valid JABAWS service names and WSDL files</a></li>
\r
79 <li><a href="#defalign">Aligning sequences</a></li>
\r
80 <li><a href="#checkresults">Checking the status of the calculation </a></li>
\r
81 <li><a href="#presetalign">Aligning with presets</a></li>
\r
82 <li><a href="#customalign">Aligning with custom parameters</a></li>
\r
83 <li><a href="#writingaltofile">Writing alignments to a file</a></li>
\r
84 <li><a href="#compex">A complete client example </a></li>
\r
85 <li><a href="#buildart">Building web services artifacts</a></li>
\r
87 <h4>JABAWS on Apache-Tomcat</h4>
\r
89 <li><a href="#tomdeploy">I dropped jaba.war file into web application directory but nothing happened. What do I do next?</a></li>
\r
90 <li><a href="#tomautoundeploy">I removed the JABAWS war file after it was deployed from the webapps directory and my JABAWS web application folder disappear. Where it has gone to?</a></li>
\r
91 <li><a href="#tomstopundeploy">I want to make sure that Tomcat will not undeploy/delete JABAWS directory from the server. What should I do?<br />
\r
95 <h4><a/>JABAWS on VM (Virtual Machine)</h4>
\r
97 <li><a href="#vmbexc">I cannot open VM using VirtualBox due to VERR_VMX_MSR_LOCKED_OR_DISABLED exception. Can you help?</a></li>
\r
98 <li><a href="#ovfOnVmware">VMWare Player - Failed to query source for information / I cannot open OVF file using VMware player. Why is this?</a></li>
\r
99 <li><a href="#vmiaccess">I want to connect to the Internet from my VM. Can I do that?</a></li>
\r
103 <h4><a name="wisjaba" id="wisjaba"></a>What is JABAWS?</h4>
\r
104 <p>JABAWS stands for JAva Bioinformatics Analysis Web Services. It is a collection of web services for multiple sequence alignment. For simplicity we referrer to them as JABAWS. It is a successor of Jalview Web Services. JABAWS makes it easy to access well-known multiple sequence alignment programs from JalView. However, the scope of JABAWS is not limited to multiple sequence alignment programs. Future versions of JABAWS will incorporate protein disorder prediction, BLAST, PSIBLAST and HMMER database searches and many other tools. For the list of currently supported programs see <a href="#alprog">below</a></p>
\r
105 <h4><a name="wjaba" id="wjaba"></a>Why JABAWS?</h4>
\r
106 <p>JABA Web Services has a number of distinct features that are not
\r
107 found in other bioinformatics web services systems. In particular,
\r
110 <li><strong>Provides uniform remote access to a number of popular command line
\r
111 tools.</strong><br />
\r
112 <span class="body"> JABAWS enable you to access your favorite research tools anywhere, at any time. For instance, all multiple sequence
\r
113 alignment services can be accessed with a single command line
\r
114 interface, simplifying their invocation. At the same time most of the
\r
115 command line options for each program are supported, so you have
\r
116 nearly the same level of control as if you were running them on the
\r
117 command line yourself.</span></li>
\r
118 <li><strong>Enables web based or stand-alone applications, like Jalview, to
\r
119 access a variety of bioinformatics analysis methods.</strong> <br />
\r
121 "body">The JABAWS client library makes it very easy to
\r
122 connect to one or more instances of JABAWS, so if one server is off
\r
123 line, all you need to know is the URL of another server that will
\r
124 do the job for you.
\r
125 Moreover you are not limited to JABAWS own client as JABAWS are <a href="http://www.ws-i.org/">WS-I basic
\r
126 profile</a> v. 1.1 compatible, which means that clients
\r
127 can be created for them in almost any programming
\r
128 language.</span></li>
\r
129 <li><strong>Can be easily deployed as a server on a variety of platforms,
\r
130 with command line tools run on the same machine or on a
\r
131 cluster.</strong><span class="body"><strong>This allow you keeping your private data safe. </strong></span><br />
\r
132 You don't need to send your data to the
\r
133 Internet anymore. Simply <a href="download.html">download</a> and <a href=
\r
134 "howto.html#hdjaba">install</a> JABAWS on a trusted machine in your
\r
135 lab or institute, and use its web address instead of the public
\r
136 JABAWS services. No data will leave your lab any longer! The JABAWS server can run programs on a single machine or on a
\r
137 cluster, and are easy to install.
\r
138 If your server is going to be heavily used, then it is better to <a
\r
139 href="howto.html#clustsubsys">configure JABAWS to access your
\r
140 cluster</a>, which is straightforward<strong>.
\r
141 </strong><span class="body"><a href="howto.html#clustsubsys"> JABAWS
\r
142 integrates with a number of cluster job management systems (e.g.
\r
143 GridEngine, PBS, LSF, Condor).</a> It also intelligently manages
\r
144 task scheduling depending on their size, eliminating the scalability
\r
145 issues and let you focus on your research. </span></li>
\r
146 <li><strong>Support custom parameters, unlike other web services </strong><br />
\r
147 JABAWS includes a comprehensive parameter model and validation
\r
148 mechanism, allowing you to specify additional options and
\r
149 arguments. Want to use PAM200 substitution matrix, set the number
\r
150 of iterations, or sequence clustering method? No problem - JABAWS
\r
151 lets you do that. You are no longer limited to defaults!</li>
\r
153 <h3>Installation</h3>
\r
154 <h4><a name="hdjaba" id="hdjaba"></a>How to deploy JABAWS? </h4>
\r
155 <p>Download JABAWS Web Application Archive (war file). Deploy it on any Servlet 2.4 compatible container. We have tested deployment on Apache-Tomcat version 6. On windows servers just drop a JABAWS war file into the web application directory. On Linux unpack the war file into web application directory , cd to <span class="hightlight"><webapplicationpath>/binaries/src</span> directory and run setexecflag.sh script to set an executable flag for binaries. Start Tomcat. That is it. This should give you working JABAWS stack with tasks executed locally on the server. If you have cluster you may want to enable JABAWS to submit jobs to the cluster. To find out more about this and to find out about other configuration options read the <a href="manual.html">manual</a>. </p>
\r
156 <h4><a name="usingWsTester" id="usingWsTester"></a>I deployed JABAWS, how to make sure it is working? </h4>
\r
157 <p>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. <span class="code">http://myhost.compbio.ac.uk:8080/jabaws</span>If you see it, then it is time to make sure that web services are working too. Assuming that you have unpacked/deployed JABAWS from the server war file, you should be able to navigate to the test program which can be found in <webapplicationpath>/WEB-INF/lib/jabaws-client.jar file. To run the tests type:<span class="code"> java -jar jabaws-client.jar -h=<Your web application server host name, port and JABAWS context path></span></p>
\r
158 <p>For example to test all JABAWS web services on host myhost.compbio.ac.uk type: </p>
\r
159 <p class="code">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws </p>
\r
160 <p>You can choose a particular web server using -s option like this <span class="code">java -jar jabaws-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws -s=ClustalWS </span>This command line assumes that java executable is in your path and jabaws-client.jar is located in the current directory.</p>
\r
161 <p>An example of the report testing tool produces for operating web service looks like this: </p>
\r
162 <p><span class="code"> Connecting to service MuscleWS on http://myhost.compbio.ac.uk:8080/jabaws ... OK<br />
\r
163 Testing alignment with default parameters:<br />
\r
164 Queering job status...OK<br />
\r
165 Retrieving results...OK<br />
\r
166 Testing alignment with presets:<br />
\r
167 Aligning with preset 'Protein alignment(Fastest speed)'... OK<br />
\r
168 Aligning with preset 'Nucleotide alignment(Fastest speed)'... OK<br />
\r
169 Aligning with preset 'Huge alignments (speed-oriented)'... OK<br />
\r
170 Queering presets...OK<br />
\r
171 Queering Parameters...OK<br />
\r
172 Queering Limits...OK<br />
\r
173 Queering Local Engine Limits...OK<br />
\r
174 Check is completed service MuscleWS IS WORKING</span>An example of the response of a web service which is deployed but is not operating is below: </p>
\r
175 <p><span class="code">Connecting to service ProbconsWS on http://localhost:8080/ws ... OK<br />
\r
176 Testing alignment with default parameters:FAILED<br />
\r
177 Service ProbconsWS IS NOT FUNCTIONAL</span>If the web server did not respond the message looks like following: <span class="code">Connecting to service TcoffeeWS on http://localhost:8080/ws ... FAILED</span></p>
\r
178 <h4><a name="alprog"/>Which Alignment programs are supported?</h4>
\r
179 <p> JABAWS provide access to the following programs </p>
\r
181 <li><a href="http://www.clustal.org/">ClustalW</a> (version 2.0.12)</li>
\r
182 <li><a href="http://align.bmr.kyushu-u.ac.jp/mafft/software/">Mafft</a> (version 6.713)</li>
\r
183 <li><a href="http://www.drive5.com/muscle">Muscle</a> (version 3.7) </li>
\r
184 <li><a href="http://www.tcoffee.org/Projects_home_page/t_coffee_home_page.html">Tcoffee</a> (version 8.14) </li>
\r
185 <li><a href="http://probcons.stanford.edu/">Probcons</a> (version 1.12)</li>
\r
187 <h4><a name="nonwinbin" id="nonwinbin"></a>I do not use windows and I am having troubles compiling binaries. Where can I get the pre compiled binaries for my system?</h4>
\r
189 <li><a href="ftp://ftp.ebi.ac.uk/pub/software/clustalw2/2.0.12/">ClustalW</a></li>
\r
190 <li><a href="http://align.bmr.kyushu-u.ac.jp/mafft/software/">Mafft</a></li>
\r
191 <li><a href="http://www.drive5.com/muscle/download3.6.html">Muscle</a></li>
\r
192 <li><a href="http://www.tcoffee.org/Packages/Binaries/">Tcoffee</a></li>
\r
193 <li>Probcons (Linux <a href="http://www.compbio.dundee.ac.uk/jabaws/archive/binaries/linuxI386/probcons/">I386</a> | <a href="http://www.compbio.dundee.ac.uk/jabaws/archive/binaries/linuxAMD64/probcons/">AMD64</a>)</li>
\r
195 <p>We would however recommend to compile the binaries for your system whenever possible. This is likely to give you a significant performance gain.</p>
\r
196 <h3>Configuration </h3>
\r
197 <h4><a name="diffbin" id="diffbin"></a>Can I use a different version of the alignment program with JABAWS?</h4>
\r
198 <p>JABAWS supplied with binaries and source code of the executables which version it supports. So normally you would not need to install your own executables. However, if you have a different version of an executable (e.g. an alignment program) which you prefer, you could use it as long as it supports all the functions JABAWS executable supported. This could be the case with more recent executable. If the options supported by your chosen executable is different when the standard JABAWS executable, than you need to edit <em>ExecutableName</em>Paramaters.xml configuration file. </p>
\r
199 <h4><a name="dmjavadoc" id="dmjavadoc"></a>Is there a documentation for client library methods? </h4>
\r
200 <p><a href="dm_javadoc/index.html">Yes there is</a>. Javadoc is available for all methods of the library and data structures. </p>
\r
201 <h4><a name="whichjaba" id="whichjaba"></a>I want to use JABAWS. Which JABAWS distribution should I choose?</h4>
\r
202 <p>There are two main packages you could use</p>
\r
204 <li>A client package - for anyone who wants to use JABAWS from your own code, without Jalview. </li>
\r
205 <li>Web Services package (there are a few platform specific variants of this one) - for anyone who wants to run they own copy of JABA Web Services. </li>
\r
206 <li>Virtual Appliance - for anyone who wants to run JABAWS locally, but work on Windows or have configuration problems. </li>
\r
208 <p>A client only package (1) contains the code sufficient to connect to a third party version of JABAWS and use it. This is the package for anyone who wants to connect to and to use JABAWS from their own software. The package also includes a command line client tool. Read more about how to use command line client <a href="#cmdclient">below</a>.
\r
209 JABAWS are fully WS-I compliant, so one could use any language to access them. However, a client package offer additional convenience methods, which is not available otherwise. For example methods to read Clustal formatted sequence alignment files and convert them to the List of FastaSequence objects, which JABAWS will be happy to consume. The trade off is that the client package is written in java, which may not be the language of your choice. </p>
\r
210 <p>Web Services package (2) contains JABAWS web services. There are versions for Unix/Linux and Windows operation systems. JABAWS will work on any operation system which has web application server like Tomcat, and GNU compatible C/C++ compiler. This includes Mac. If you are interested in running JABAWS on Mac you would need to recompile binaries JABAWS depends on, in particular <a href="#alprog">these executables</a>. You can configure JalView to use your version of JABAWS, or a any combinations of publicly available instance of JABAWS with your local. </p>
\r
211 <p>Finally, you can download core JABAWS package, which contains the code for executing programs locally or on the variety of clusters. This is likely to be of interest for developers only.</p>
\r
212 <p>Virtual Appliance package (3) contains TurnKey Linux with JABAWS installed. You can use this package as long as you can run a virtual appliance on your computer. You can find out more about JABAWS virtual appliance in the relevant <a href="manual.html#whenvm">manual</a> and <a href="howto.html#vmbexc">how to</a> sections. </p>
\r
213 <h4><a name="cmdclient" id="cmdclient"></a>Can I program against JABAWS? </h4>
\r
214 <p>Yes. The simplest way to do it is to download a <a href="download.html#minclient">client package</a>, and use it to access JABAWS. This package contains value object which you could alternatively generate with <span class="hightlight">wsimport</span> in java, or similar tool in other languages. It offers some additional manually developed methods which further simplify working with JABAWS. For more information please refer to the <a href="dm_javadoc/index.html">data model javadoc</a>. However should you wish to generate the code using <span class="hightlight">wsimport </span>tool you will be able to do so. As JABAWS are WS-I basic profile compliant, they can be accessed in a standard way as any other web service. </p>
\r
215 <h4><a name="usingcclient" id="usingcclient"></a>Is there a command line client to JABAWS? </h4>
\r
216 <p>Yes, it comes as a part of <a href="download.html#minclient"> client package</a> which you are welcome to download. </p>
\r
217 <p>The command client can be used to align sequences using any of JABAWS supported web services. The client is OS independent and supports most of the functions which can be accessed programmatically via JABAWS API. Using this client you could align sequences using presets or custom parameters, please see examples of this below. Here is the list of options supported by the command line client. </p>
\r
218 <span class="code"><strong>Usage:</strong> java -jar <path_to_jar_file> -h=host_and_context -s=serviceName ACTION [OPTIONS]
\r
219 -h=<host_and_context> - a full URL to the JABAWS web server including context path e.g. http://10.31.10.159:8080/ws<br />
\r
220 -s=<ServiceName> - one of [MafftWS, MuscleWS, ClustalWS, TcoffeeWS, ProbconsWS]
\r
223 <strong>ACTIONS:</strong><br />
\r
224 -i=<inputFile> - full path to fasta formatted sequence file, from which to align sequences<br />
\r
225 -parameters - lists parameters supported by web service<br />
\r
226 -presets - lists presets supported by web service<br />
\r
227 -limits - lists web services limits<br />
\r
228 Please note that if input file is specified other actions are ignored
\r
231 <strong> OPTIONS:</strong> (only for use with -i action):<br />
\r
232 -r=<presetName> - name of the preset to use<br />
\r
233 -o=<outputFile> - full path to the file where to write an alignment<br />
\r
234 -f=<parameterInputFile> - the name of the file with the list of parameters to use.<br />
\r
235 Please note that -r and -f options cannot be used together. Alignment is done with either preset or a parameters from the file, but not both!</span>
\r
236 <p>Align sequences from input.fasta file using Mafft web service with default settings, print alignment in Clustal format to console. </p>
\r
237 <p class="code">java -jar jabaws-min-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws -s=MafftWS -i=d:\input.fasta</p>
\r
238 <p>Content of input.fasta file is show below (please note sequences has been trimmed for clarity)<span class="code">>Foobar<br />
\r
239 MTADGPRELLQLRAAVRHRPQDFVAWL <br />
\r
241 MGDTTAGEMAVQRGLALHQ<br />
\r
242 QRHAEAAVLLQQASDAAPE<br />
\r
243 >Foofriend<br />
\r
244 MTADGPRELLQLRAAV</span></p>
\r
245 <p>Align as in above example, but write output alignment in a file out.clustal, using parameters defined in prm.in file</p>
\r
246 <p><span class="code">java -jar jabaws-min-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws -s=MafftWS -i=d:\input.fasta -o=d:\out.clustal -f=prm.in </span></p>
\r
247 <p>The content of the prm.in file is shown below <span class="code">--nofft<br />
\r
249 --fastaparttree<br />
\r
251 --op=2.2</span></p>
\r
252 <p>The format of the file is the same for all JABAWS web services. Parameters are specified in exactly the same way as for native executables - alignment programs like Mafft etc. So parameters which you can use with command line version of an alignment program can be used with JABAWS. Most of the settings controlling alignment process are supported, but the setting controlling output are not. This is due to the fact the output have to be handled by JABAWS, so must remain within its control. For a list of parameters supported by a web service see the next example. In <span class="hightlight">prm.in</span> parameters are separated by the new line, and name of the parameter is separated from its value with an equal sign. This format is constant no matter which JABAWS web service is used. <br />
\r
253 <span class="code"> java -jar jabaws-min-client.jar -h=http://myhost.compbio.ac.uk:8080/jabaws -s=MafftWS -parameters</span></p>
\r
254 <h4><a name="cmdclientuse" id="cmdclientuse"></a>Can I use a JABAWS command line client to connect and use JABAWS web services in Dundee and my local lab? </h4>
\r
255 <p>Yes, just point it to the host you want to use by changing the value of -h key. For example you used <span class="hightlight">-h=http://myhost.compbio.ac.uk:8080/jabaws</span> server, now you want to use another server to <span class="hightlight">-h=http://mylabserver.myuni.edu.</span> This comes handy if you want to align many sequence or do not want to sent some of your data to the internet. </p>
\r
256 <h4><a name="canlimit" id="canlimit"></a>Sometimes users sent very large number of sequences to JABAWS server, so that it becomes unresponsive. Can I limit the number of sequences users can submit to my server.</h4>
\r
257 <p>Yes, JABAWS can be configured to reject the requests based the number of sequences as well as the number of sequence and they average length per single align request. Look at the <a href="#">Restricting JABAWS section</a> for further details. </p>
\r
258 <h4><a name="mixuse" id="mixuse"></a>My cluster is quite busy so the waiting times in the task queue is significant. At the same time I have powerful server with many cores. Can I use the server for small tasks and send really big ones to the cluster? </h4>
\r
259 <p>Yes, you can. For this you need to enable and configure both the cluster and the local engines. Once this is done decide on the maximum size of a task to be run on the server locally. In JABAWS the size of the task can be defined as a number of sequences and an average sequence length. Edit <span class="hightlight">"# LocalEngineExecutionLimit #" </span>preset in<span class="hightlight"> <ServiceName>Limits.xml</span> file accordingly. </p>
\r
260 <h4><a name="nocluster" id="nocluster"></a>Can I run my own JABAWS if I do not have a cluster?</h4>
\r
261 <p>Yes, JABAWS can be run 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. </p>
\r
262 <h4><a name="clustsubsys" id="clustsubsys"></a>My cluster uses LSF/PBS/SGE etc can I run JABAWS on my cluster? </h4>
\r
263 <p>JABAWS uses <a href="http://drmaa.org/">DRMAA</a> 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.</p>
\r
264 <h4><a name="noshareddisk" id="noshareddisk"></a>My cluster does not have shared disk space can I run JABAWS?</h4>
\r
265 <p>No, not on the cluster. At the moment to operate on the cluster JABAWS require a disk space each cluster nodes have access to. However, you could still run JABAWS on a single server.</p>
\r
266 <h4><a name="difflimits" id="difflimits"></a>I installed JABAWS in my lab. I would like to define different limits for public and lab users</h4>
\r
267 <p>Currently only one set of limits is supported per a web service. If you need to provide different quality of service for different group of users it is best to make a second JABAWS installation on a different server (<a href="#diffcontexts">could be on the same server but in the different context</a>) and define different limits on a second server. So the lab users could use one server, and public another.</p>
\r
268 <h4 style="display:none"><a name="align5000" id="align5000"></a>I tried aligning 5000 sequences using Jalview on my laptop. It crashed. Why JalView allowed me to do that?</h4>
\r
269 <p>Jalview uses the same code for local task execution as JABAWS. Currently JABAWS machinery supports limits on web services level only. If you execute the task locally or make direct submission to the cluster no limits are applied. </p>
\r
270 <h4><a name="diffcontexts"/>Can I run many JABAWS instances on the same server?</h4>
\r
271 <p>Yes. JABAWS is supplied as one Web Application Archive which can be dealt with as any other web applications. 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. </p>
\r
272 <h4><a name="jabaonwin" id="jabaonwin"></a>I deployed JABAWS on windows why not all alignment programs work?</h4>
\r
273 <p>JABAWS are platform independent, and thus can be deployed on any operation system which supports java. However, the executables which do the calculations are platform specific. JABAWS uses different versions of executables for different platforms under the hood. However, if executable is not available for a particular platform, then this service will not function. </p>
\r
274 <h4><a name="wworkonwin" id="wworkonwin"></a>If I install JABAWS on windows which web services will work?</h4>
\r
275 <p>From all supported only Clustal and Muscle will work. This is due to the fact that only these two executables supports windows natively.</p>
\r
276 <h4><a name="nomaffttcoffee" id="nomaffttcoffee"></a>There are versions of Mafft and Tcoffee for windows, so why you do not support them?</h4>
\r
277 <p>Indeed Mafft and Tcoffee can be executed on windows platform but only in the Linux environment provided by Cygwin. They setup is very complicated and performance will suffer in such an environment. We do not support such a configuration and unlikely to support it in the future. JABAWS are best installed on Unix like environment after this is done they can be accessed from any operation system. </p>
\r
278 <h4><a name="opforjaba" id="opforjaba"></a>What operation system JABAWS can run on?</h4>
\r
279 <p>JABAWS can be run on any operation system that support java. However, its best to be run on unix like operation system as all the programs JABAWS uses are available for unix platform, and only a few are available on windows. Currently only Clustal and Muscle are available for windows platform.</p>
\r
280 <h4><a name="toomanyreqs" id="toomanyreqs"></a>What happens if the number of requests to my JABAWS installation is greater the the server can process?</h4>
\r
281 <p>That depends on your configuration. If only cluster submission is enabled, than tasks will be sent to the cluster and you will experience a longer wait as a result of a task queuing. It is common, that the number of tasks that web server can send to the cluster is unlimited, but the number of tasks that can be run in parallel is controlled, hence the queue.
\r
283 If only local execution is enabled, the number of tasks that can be executed in parallel are limited to the number of threads, which is equal to the number of cores available on the server by default, but can be defined declaratively too. The tasks that cannot be executed immediately will be waiting in the queue. You can expect a greater execution time. If both local and cluster submission is enabled, then when the task cannot be immediately executed locally it gets sent to the cluster.</p>
\r
286 <h4><a name="logs" id="logs"></a>I would like to keep and eye on who is using JABAWS services on my server. </h4>
\r
287 <p>Enable Tomcat log valve. To do this uncomment the following section of <span class="hightlight"><tomcat_root>/conf/server.xml</span> configuration file. </p>
\r
288 <p class="code"> <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" <br />
\r
289 prefix="localhost_access_log." suffix=".txt" pattern="common" resolveHosts="false"/></p>
\r
290 <p> The following information will be logged:</p>
\r
291 <table width="100%" border="0" style="margin:0">
\r
295 <th>Method server_URL protocol </th>
\r
296 <th>HTTP status </th>
\r
297 <th>Response size in bytes </th>
\r
300 <td>10.31.11.159</td>
\r
301 <td>[10/Feb/2010:16:51:32 +0000]</td>
\r
302 <td>"POST /jws2/MafftWS HTTP/1.1"</td>
\r
307 <p>Which can be processed in various programs for log analysis , such as <a href="http://www.webalizer.org/">WebAlizer</a>, <a href="http://www.analog.cx/">Analog</a>, <a href="http://awstats.sourceforge.net/">AWStats</a>. </p>
\r
308 <h4><a name="execstat" id="execstat"></a>I would like to know how much of the CPU time has been consumed and which tasks were the longest.</h4>
\r
309 <p>JABAWS stores cluster task ids for all tasks which were run on the cluster. Using cluster ids the detailed statistics can be extracted from cluster accounting system. Due to the fact that each cluster supported by JABAWS have different accounting system it was not possible to provide ready to use statistics. <br />
\r
310 For the local execution the starting and finishing time in nano seconds can be found in STARTED and FINISHED files respectively. In time we will provide the tools to extract execution time statistics, so keep the content of your working directory ready! </p>
\r
311 <h4><a name="confaccessright" id="confaccessright"></a>I noticed that jobsout, conf and binaries directories are not placed in WEB-INF directory are they not accessible to anyone?</h4>
\r
312 <p>Access to these directories is prohibited to any unauthorized users by means of security constrain defined in web application descriptor file. There is a special user role called <span class="hightlight">admin</span> who can access these directories. This comes handy if you would like to keep an eye on any of the task outputs stored in jobsout, or would like to view the configuration files. To access these directories add admin user into your application server. The way you do it will depends on where you would like the user passwords to come from and you web application server. If you use Tomcat, than the simplest way is to use Tomcat Memory Realm which is linked to a plain text configuration file. To define the user in Tomcat server add an entry in <span class="hightlight">conf/tomcat-user.xml</span> file. <span class="code"><role rolename="admin"/><br />
\r
313 <user username="admin" password="your password here " roles="admin"/></span></p>
\r
314 <p>Once this is done make sure the servlet that returns the web application directory listings is enabled. Look in the <span class="hightlight"><tomcatroot>/conf/web.xml</span> file for the following <span class="code"><param-name>listings</param-name><br />
\r
315 <param-value>true</param-value></span></p>
\r
316 <p>The whole section that defined default listing servlet is below</p>
\r
317 <p class="code"> <servlet><br />
\r
318 <servlet-name>default</servlet-name><br />
\r
319 <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class><br />
\r
320 <init-param><br />
\r
321 <param-name>debug</param-name><br />
\r
322 <param-value>0</param-value><br />
\r
323 </init-param><br />
\r
324 <init-param><br />
\r
325 <param-name>listings</param-name><br />
\r
326 <param-value>true</param-value><br />
\r
327 </init-param><br />
\r
328 <load-on-startup>1</load-on-startup><br />
\r
329 </servlet><br />
\r
331 These listings are read only by default.
\r
332 <h4><a name="canyouhelp" id="canyouhelp"></a>Sometimes something goes wrong with JABAWS, but I cannot figure out why. Can you help?</h4>
\r
333 <p>JABAWS logs all errors to the stdout and in the file called activity.log if <a href="manual.html#logfiles">logging is enabled</a>. Stdout is usually recorded in web server log files. Have a look there and you may find the reason for the problems. If it is still unclear what went wrong try increasing the logging level. Setting the logging level to TRACE or DEBUG will give you a lot of insights in what goes on behind the scene. We would need this log if you need us to help you, or if you would like to report the bug. To change the log level, replace ERROR keyword in ACTIVITY logger to TRACE. </p>
\r
334 <h3>Using JABAWS in your program</h3>
\r
335 <h4><a name="connectto" id="connectto"></a>Connecting to JABAWS</h4>
\r
336 <p class="attention">For a complete working example of JABAWS command line client please see compbio.ws.client.Jws2Client class. JABAWS command line client source code is available from the <a href="download.html">download page</a>. Please note that for now all the examples are in Java other languages will follow given a sufficient demand. </p>
\r
337 <p>Download a binary JABAWS <a href="download.html">client</a>. Add the client to the class path. The following code excerpt will connect your program to Clustal web service deployed in the University of Dundee. </p>
\r
338 <p class="code"> import java.net.URL;<br />
\r
339 import javax.xml.namespace.QName;<br />
\r
340 import javax.xml.ws.Service;<br />
\r
341 ...............<br />
\r
342 1) String qualifiedName = "http://msa.data.compbio/01/01/2010/";<br />
\r
343 2) URL url = new URL("http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?wsdl");<br />
\r
344 3) QName qname = new QName(, "ClustalWS");<br />
\r
345 4) Service serv = Service.create(url, qname);<br />
\r
346 5) MsaWS msaws = serv.getPort(new QName(qualifiedName, "ClustalWSPort"),
\r
348 <p>Line 1 makes a qualified name for JABA web services.<br />
\r
350 constructs the URL to the web services WSDL. <br />
\r
351 Line 3 makes a qualified name instance for Clustal JABA web service. <br />
\r
352 Line 4 creates a service instance.<br />
\r
353 Line 5 makes a connection to the server. </p>
\r
354 <p>A more generic connection method would look like this </p>
\r
355 <p class="code"> import java.net.URL;<br />
\r
356 import javax.xml.namespace.QName;<br />
\r
357 import javax.xml.ws.Service;<br />
\r
358 import compbio.ws.client.Services<br />
\r
361 String qualifiedServiceName = "http://msa.data.compbio/01/01/2010/";<br />
\r
362 String host = "http://www.compbio.dundee.ac.uk/jabaws";<br />
\r
363 // In real life the service name can come from args<br />
\r
364 Services clustal = Services.ClustalWS;<br />
\r
365 URL url = new URL(host + "/" + clustal.toString() + "?wsdl");<br />
\r
366 QName qname = new QName(qualifiedServiceName, clustal.toString());<br />
\r
367 Service serv = Service.create(url, qname);<br />
\r
368 MsaWS msaws = serv.getPort(new QName(qualifiedServiceName, clustal<br />
\r
369 + "Port"), MsaWS.class);</p>
\r
370 <p>Where Services is enumeration of JABAWS web services. All JABAWS multiple sequence alignment methods confirm to MsaWS specification, thus from the caller point of view all JABAWS web services can be represented by MsaWS interface. The full documentation of MsaWS functions is available from the <a href="file:///D:/workspace/JWS2/website/dm_javadoc/compbio/data/msa/MsaWS.html">javadoc</a>. </p>
\r
371 <h4><a name="validnames" id="validnames"></a>Valid JABAWS service names and WSDL files </h4>
\r
373 <li><a href="http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?wsdl">ClustalWS</a> (http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?wsdl) </li>
\r
374 <li><a href="http://www.compbio.dundee.ac.uk/jabaws/MuscleWS?wsdl">MuscleWS</a> (http://www.compbio.dundee.ac.uk/jabaws/MuscleWS?wsdl) </li>
\r
375 <li><a href="http://www.compbio.dundee.ac.uk/jabaws/MafftWS?wsdl">MafftWS</a> (http://www.compbio.dundee.ac.uk/jabaws/MafftWS?wsdl) </li>
\r
376 <li><a href="http://www.compbio.dundee.ac.uk/jabaws/TcoffeeWS?wsdl">TcoffeeWS</a> (http://www.compbio.dundee.ac.uk/jabaws/TcoffeeWS?wsdl) </li>
\r
377 <li><a href="http://www.compbio.dundee.ac.uk/jabaws/ProbconsWS?wsdl">ProbconsWS</a> (http://www.compbio.dundee.ac.uk/jabaws/ProbconsWS?wsdl) </li>
\r
379 <h4><a name="defalign" id="defalign"></a>Aligning sequences </h4>
\r
380 <p>Given that <span class="hightlight">msaws</span> is web service proxy, created as described in "Connecting to JABAWS" section, the actual alignment can be obtained as follows: </p>
\r
381 <p class="code">1) List<FastaSequence> fastalist = SequenceUtil.readFasta(new FileInputStream(file));<br />
\r
382 2) String jobId = msaws.align(fastalist);
\r
384 3) Alignment alignment = msaws.getResult(jobId);</p>
\r
385 <p>Line one loads FASTA sequence from the file<br />
\r
386 Line two submits them to web service represented by msaws proxy <br />
\r
387 Line three retrieves the alignment from a web service. This line will block the execution until the result is available. Use this with caution. In general, you should make sure that the calculation has been completed before attempting retrieving results. This is to avoid keeping the connection to the server on hold for a prolonged periods of time. While this may be ok with your local server, our public server (<a href="http://www.compbio.dundee.ac.uk/jabaws">www.compbio.dundee.ac.uk/jabaws</a>) will not let you hold the connection for longer than 10 minutes. This is done to prevent excessive load on the server. The next section describes how to check the status of the calculation.<br />
\r
388 Methods and classes mentioned in the excerpt are available from the JABAWS client library. </p>
\r
389 <h4><a name="checkresults" id="checkresults"></a>Checking the status of the calculation </h4>
\r
390 <p> You may have noticed that there was no pause between submitting the job and retrieving of the results. This is because <span class="hightlight">getResult(jobId)</span> method block the processing until the calculation is completed. However, taking into account that the connection holds server resources, our public server (<a href="http://www.compbio.dundee.ac.uk/jabaws">www.compbio.dundee.ac.uk/jabaws</a>) is configured to reset the connection after 10 minutes of waiting. To work around the connection reset you are encouraged to check whether the calculation has been completed before accessing the results. You can do it like this: </p>
\r
391 <p> <span class="code">while (msaws.getJobStatus(jobId) != JobStatus.FINISHED) {<br />
\r
392 Thread.sleep(2000); // wait two seconds, then recheck the status
\r
395 <h4><a name="presetalign" id="presetalign"></a>Aligning with presets</h4>
\r
396 <p class="code">1) PresetManager presetman = msaws.getPresets();<br />
\r
397 2) Preset preset = presetman.getPresetByName(presetName);<br />
\r
398 3) List<FastaSequence> fastalist = SequenceUtil.readFasta(new FileInputStream(file));<br />
\r
399 4) String jobId = msaws.presetAlign(fastalist, preset);<br />
\r
400 5) Alignment alignment = msaws.getResult(jobId);</p>
\r
401 <p>Line one obtains the lists of presets supported by a web service.<br />
\r
402 Line two return a particular Preset
\r
404 Lines three to five are doing the same job as in the first <a href="#defalign"> aligning sequences example</a>.</p>
\r
405 <h4><a name="customalign" id="customalign"></a>Aligning with custom parameters</h4>
\r
406 <p class="code"> 1) RunnerConfig options = msaws.getRunnerOptions();<br />
\r
407 2) Argument matrix = options.getArgument("MATRIX");<br />
\r
408 3) matrix.setValue("PAM300");<br />
\r
409 4) Argument gapopenpenalty = options.getArgument("GAPOPEN");<br />
\r
410 5) gapopenpenalty.setValue("20");<br />
\r
411 6) List<Argument> arguments = new ArrayList<Argument>();
\r
413 7) arguments.add(matrix);
\r
414 arguments.add(gapopenpenalty);<br />
\r
415 8) List<FastaSequence> fastalist = SequenceUtil.readFasta(new FileInputStream(file));<br />
\r
416 9) String jobId = msaws.customAlign(fastalist, arguments);<br />
\r
417 10) Alignment alignment = msaws.getResult(jobId);</p>
\r
418 <p>Line one obtains the RunnerConfig object that holds information on supported parameters and their values<br />
\r
419 Line two retrieve a particular parameter from the holder by its name<br />
\r
420 Lines three sets a value to this parameter which will be used in the calculation. <br />
\r
421 Line four and five do the same but for another parameter<br />
\r
422 Line 6 makes a List to hold the parameters <br />
\r
423 Line seven puts the parameters into that list<br />
\r
425 and ten is the same as in previous examples<br />
\r
426 Line nine submit an alignment request with the sequences and the parameters <br />
\r
427 The names of all the parameters supported by a web service e.g. "PAM300" can be obtained using options.getArguments() method. Further details on the methods available from RunnerConfig object are available from the <a href="dm_javadoc/index.html">javadoc</a>. </p>
\r
428 <h4><a name="writingaltofile" id="writingaltofile"></a>Writing alignments to a file</h4>
\r
429 <p>There is a utility method in the client library that does exactly that. </p>
\r
430 <p> <span class="code">Alignment alignment = align(...) <br />
\r
431 FileOutputStream outStream = new FileOutputStream(file);<br />
\r
432 ClustalAlignmentUtil.writeClustalAlignment(outStream, align);</span></p>
\r
433 <h4><a name="compex" id="compex"></a>A complete client example </h4>
\r
434 <p>Finally, a complete example of the program that connects to JABAWS Clustal service and aligns sequences using one of the Clustal web service preset. Three is also a nicely colorized <a href="Example_template.pdf">PDF version</a> of this example. The text comments are commented by block style comments e.g. /* comment */, the alternatives given in the code are line commented // comment. You may want to remove line style comments to test alternatives of the functions. All you need for this to work is a <a href="download.html">JABAWS binary client</a>. Please make sure that the client is in the Java class path before running this example.</p>
\r
435 <pre class="code" style="line-height:1em;">
\r
436 import java.io.ByteArrayInputStream;
\r
437 import java.io.FileNotFoundException;
\r
438 import java.io.IOException;
\r
439 import java.net.URL;
\r
440 import java.util.List;
\r
442 import javax.xml.namespace.QName;
\r
443 import javax.xml.ws.Service;
\r
445 import compbio.data.msa.MsaWS;
\r
446 import compbio.data.sequence.Alignment;
\r
447 import compbio.data.sequence.FastaSequence;
\r
448 import compbio.data.sequence.SequenceUtil;
\r
449 import compbio.metadata.JobSubmissionException;
\r
450 import compbio.metadata.LimitExceededException;
\r
451 import compbio.metadata.Preset;
\r
452 import compbio.metadata.PresetManager;
\r
453 import compbio.metadata.ResultNotAvailableException;
\r
454 import compbio.metadata.UnsupportedRuntimeException;
\r
455 import compbio.metadata.WrongParameterException;
\r
457 public class Example {
\r
460 * Input sequences for alignment
\r
462 static final String input = ">Foo\r\n"
\r
463 + "MTADGPRELLQLRAAVRHRPQDFVAWLMLADAELGMGDTTAGEMAVQRGLALHPGHPEAVARLGR"
\r
464 + "VRWTQQRHAEAAVLLQQASDAAPEHPGIALWLGHALEDAGQAEAAAAAYTRAHQLLPEEPYITAQ"
\r
465 + "LLNWRRRLCDWRALDVLSAQVRAAVAQGVGAVEPFAFLSEDASAAEQLACARTRAQAIAASVRPL"
\r
466 + "APTRVRSKGPLRVGFVSNGFGAHPTGLLTVALFEALQRRQPDLQMHLFATSGDDGSTLRTRLAQA"
\r
467 + "STLHDVTALGHLATAKHIRHHGIDLLFDLRGWGGGGRPEVFALRPAPVQVNWLAYPGTSGAPWMD"
\r
468 + "YVLGDAFALPPALEPFYSEHVLRLQGAFQPSDTSRVVAEPPSRTQCGLPEQGVVLCCFNNSYKLN"
\r
469 + "PQSMARMLAVLREVPDSVLWLLSGPGEADARLRAFAHAQGVDAQRLVFMPKLPHPQYLARYRHAD"
\r
470 + "LFLDTHPYNAHTTASDALWTGCPVLTTPGETFAARVAGSLNHHLGLDEMNVADDAAFVAKAVALAS"
\r
471 + "DPAALTALHARVDVLRRESGVFEMDGFADDFGALLQALARRHGWLGI\r\n"
\r
473 + ">Bar\r\n"
\r
474 + "MGDTTAGEMAVQRGLALHQQRHAEAAVLLQQASDAAPEHPGIALWLHALEDAGQAEAAAAYTRAH"
\r
475 + "QLLPEEPYITAQLLNAVAQGVGAVEPFAFLSEDASAAESVRPLAPTRVRSKGPLRVGFVSNGFGA"
\r
476 + "HPTGLLTVALFEALQRRQPDLQMHLFATSGDDGSTLRTRLAQASTLHDVTALGHLATAKHIRHHG"
\r
477 + "IDLLFDLRGWGGGGRPEVFALRPAPVQVNWLAYPGTSGAPWMDYVLGDAFALPPALEPFYSEHVL"
\r
478 + "RLQGAFQPSDTSRVVAEPPSRTQCGLPEQGVVLCCFNNSYKLNPQSMARMLAVLREVPDSVLWLL"
\r
479 + "SGPGEADARLRAFAHAQGVDAQRLVFMPKLPHPQYLARYRHADLFLDTHPYNAHTTASDALWTGC"
\r
480 + "PVLTTPGETFAARVAGSLNHHLGLDEMNVADDAAFVAKAVALASDPAALTALHARVDVLRRESGV"
\r
481 + "FEMDGFADDFGALLQALARRHGWLGI\r\n"
\r
483 + ">Friends\r\n"
\r
484 + "MTADGPRELLQLRAAVRHRPQDVAWLMLADAELGMGDTTAGEMAVQRGLALHPGHPEAVARLGRV"
\r
485 + "RWTQQRHAEAAVLLQQASDAAPEHPGIALWLGHALEDHQLLPEEPYITAQLDVLSAQVRAAVAQG"
\r
486 + "VGAVEPFAFLSEDASAAEQLACARTRAQAIAASVRPLAPTRVRSKGPLRVGFVSNGFGAHPTGLL"
\r
487 + "TVALFEALQRRQPDLQMHLFATSGDDGSTLRTRLAQASTLHDVTALGHLATAKHIRHHGIDLLFD"
\r
488 + "LRGWGGGGRPEVFALRPAPVQVNWLAYPGTSGAPWMDYVLGDAFALPPALEPFYSEHVLRLQGAF"
\r
489 + "QPSDTSRVVAEPPSRTQCGLPEQGVVLCCFNNSYKLNPQSMARMLAVLREVPDSVLWLLSGPGEA"
\r
490 + "DARLRAFAHAQGVDAQRLVFMPKLPHPQYLARYRHADLFLDTHPYNAHTTASDALWTGCPVLTTP"
\r
491 + "GETFAARVAGSLNHHLGLDEMNVADDAAFVAKAVALASDPAALTALHARVDVLRRESI";
\r
493 public static void main(String[] args) throws UnsupportedRuntimeException,
\r
494 LimitExceededException, JobSubmissionException,
\r
495 WrongParameterException, FileNotFoundException, IOException,
\r
496 ResultNotAvailableException, InterruptedException {
\r
498 String qualifiedServiceName = "http://msa.data.compbio/01/01/2010/";
\r
500 /* Make a URL pointing to web service WSDL */
\r
502 "http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?wsdl");
\r
505 * If you are making a client that connects to different web services
\r
506 * you can use something like this:
\r
508 // URL url = new URL(host + "/" + Services.ClustalWS.toString() +
\r
509 // "?wsdl");
\r
511 QName qname = new QName(qualifiedServiceName, "ClustalWS");
\r
512 Service serv = Service.create(url, qname);
\r
514 * Multiple sequence alignment interface for Clustal web service
\r
517 MsaWS msaws = serv.getPort(new QName(qualifiedServiceName, "ClustalWS"
\r
518 + "Port"), MsaWS.class);
\r
520 /* Get the list of available presets */
\r
521 PresetManager presetman = msaws.getPresets();
\r
523 /* Get the Preset object by preset name */
\r
524 Preset preset = presetman
\r
525 .getPresetByName("Disable gap weighting (Speed-oriented)");
\r
528 * Load sequences in FASTA format from the file You can use something
\r
529 * like new FileInputStream(<filename>) to load sequence from the file
\r
531 List<FastaSequence> fastalist = SequenceUtil
\r
532 .readFasta(new ByteArrayInputStream(input.getBytes()));
\r
535 * Submit loaded sequences for an alignment using preset. The job
\r
536 * identifier is returned by this method, you can retrieve the results
\r
537 * with it sometime later.
\r
539 String jobId = msaws.presetAlign(fastalist, preset);
\r
541 /* This method will block for the duration of the calculation */
\r
542 Alignment alignment = msaws.getResult(jobId);
\r
545 * This is a better way of obtaining results, it does not involve
\r
546 * holding the connection open for the duration of the calculation,
\r
547 * Besides, as the University of Dundee public server will reset the
\r
548 * connection after 10 minutes of idling, this is the only way to obtain
\r
549 * the results of long running task from our public server.
\r
551 // while (msaws.getJobStatus(jobId) != JobStatus.FINISHED) {
\r
552 // Thread.sleep(1000); // wait a second, then recheck the status
\r
555 /* Output the alignment to standard out */
\r
556 System.out.println(alignment);
\r
558 // Alternatively, you can record retrieved alignment into the file in
\r
561 // ClustalAlignmentUtil.writeClustalAlignment(new FileOutputStream(
\r
562 // "output.al"), alignment);
\r
567 For a more detailed description of all available types and their functions please refer to the <a href="dm_javadoc/index.html">data model javadoc</a>.
\r
568 <h4><a name="buildart" id="buildart"></a>Building web services artifacts</h4>
\r
569 <p>JABAWS are the standard <a href="http://jax-ws.java.net/">JAX-WS</a> SOAP web services, which are <a href="http://www.ws-i.org/">WS-I</a> basic profile compatible. This means that you could use whatever tool your language has to work with web services. Below is how you can generate portable artifacts to work with JABAWS from Java. However, if programming in Java we recommend using our <a href="#connectto"> client library</a> as it provides a handful of useful methods in addition to plain data types. </p>
\r
570 <p class="code">wsimport -keep http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?wsdl</p>
\r
571 <h3>JABAWS on Apache-Tomcat</h3>
\r
572 <h4><a name="tomdeploy" id="tomdeploy"></a>I dropped jaba.war file into web application directory but nothing happened. What do I do next?</h4>
\r
574 <li>Make sure tomcat have sufficient access rights to read your war file. </li>
\r
575 <li>Restart the tomcat, sometimes it will not since that the new war file is added without restart</li>
\r
576 <li>If tomcat still refuses to unpack the war file, unpack it manually into web application folder. Set executable flag for native executables (alignment programs) as described <a href="manual.html#setexecflag">here. </a> Restart tomcat. </li>
\r
578 <h4><a name="tomautoundeploy" id="tomautoundeploy"></a>I removed the JABAWS war file after it was deployed from the webapps directory and my JABAWS web application folder disappear. Where it has gone to?</h4>
\r
579 <p>If you used tomcat automated deployment for JABAWS, which is when you just drop a war file in to webapps directory than, if the war file is removed, tomcat will automatically undeploy your application. So <span class="attention">do not remove the war file </span>if you intend to keep JABAWS running. </p>
\r
580 <h4><a name="tomstopundeploy" id="tomstopundeploy"></a>I want to make sure that tomcat will not undeploy/delete JABAWS directory from the server. What should I do?</h4>
\r
581 <p>Use an explicit application descriptor. It could come in different flavors, the one I prefer if to drop a context descriptor file into <span class="hightlight"><tomcatRoot>conf/Catalina/localhost</span> directory. Name your context file the same as your application folder e.g. if you JABAWS resides in webappl/jaba folder, then call the context file jaba.xml. Below is an example of content this file might have.</p>
\r
582 <p class="code"><?xml version="1.0" encoding="UTF-8"?><br />
\r
583 <Context antiResourceLocking="false" privileged="true" /></p>
\r
584 <p>This should be sufficient to prevent tomcat from removing your JABAWS deployment folder. For more information about tomcat deployer <a href="http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html">read this documentation on the tomcat web site</a>.</p>
\r
586 <h3>JABAWS on VM (Virtual Machine)</h3>
\r
587 <h4><a name="vmbexc" id="vmbexc"/>I cannot open VM using VirtualBox due to VERR_VMX_MSR_LOCKED_OR_DISABLED exception. Can you help?</h4>
\r
588 <p>VERR_VMX_MSR_LOCKED_OR_DISABLED exception means that Intel Virtualization technology is disabled or not supported by your computer. If you have such problem, please make sure you have configured JABAWS VM with 1 CPU and disabled VT-X extensions. Alternatively you can enable virtualization extensions ion from the BIOS of your computer. Unfortunately, we cannot give you exact instructions on how to do this, as this would depend on your computer BIOS manufacturer. For MACs it may not be possible at all. </p>
\r
589 <h4><a name="ovfOnVmware" id="ovfOnVmware"/>VMWare Player - Failed to query source for information. I cannot open OVF file using VMware player. Why is this?</h4>
\r
590 <p>At a time of writing, the latest version of VMware Player 3.1.2 support only a legacy OVF version 0.9. Whereas OVF packaged with JABAWS VM is version 1.0. Please use VMX - VMware specific configuration file with all VMware products. </p>
\r
591 <h4><a name="vmiaccess" id="vmiaccess"/>I want to connect to the Internet from my VM. Can I do that?</h4>
\r
593 <p>By default JABAWS VM is configured to use host-only networking. This means that the host can communicate with the VM via network, but no other machines can. Similarly, the VM cannot communicate with any other computers apart from the host. If you want to connect to the Internet from the VM, configure your VM to use NAT network. However, you will not be able to connect to the VM from the host in such case. If you want to be able to connect to your VM and let VM connect to the internet at the same time you would have to use Bridged network. In such case you would have to configure the VM IP address manually (unless of cause your network have a DHCP server to do that). </p>
\r
595 <!-- content end-->
\r
596 <div id="copyright">Last update: 17 November 2010<br/>
\r
597 Peter Troshin and Geoff Barton, The Barton Group, University of Dundee, UK</div>
\r
598 </div><!-- wrapper end-->
\r
599 </div> <!-- page end-->
\r
600 <!-- Google analitics -->
\r
601 <!-- Google analitics -->
\r
602 <script type="text/javascript">
\r
603 var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
\r
604 document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
\r
606 <script type="text/javascript">
\r
608 var pageTracker = _gat._getTracker("UA-5356328-1");
\r
609 pageTracker._trackPageview();
\r
git://source.jalview.org / jabaws.git / blob