website/docs/v_2_2_0/develop.html

   1
   2
   3 <!DOCTYPE html>
   4 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
   5 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
   6 <head>
   7   <meta charset="utf-8">
   8
   9   <meta name="viewport" content="width=device-width, initial-scale=1.0">
  10
  11   <title>For Developers &mdash; JABAWS 2.2 documentation</title>
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29     <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  30
  31
  32
  33
  34
  35         <link rel="index" title="Index"
  36               href="genindex.html"/>
  37         <link rel="search" title="Search" href="search.html"/>
  38     <link rel="top" title="JABAWS 2.2 documentation" href="index.html"/>
  39         <link rel="next" title="Usage Statistics" href="stats.html"/>
  40         <link rel="prev" title="Advanced Usage" href="advanced.html"/>
  41
  42
  43   <script src="_static/js/modernizr.min.js"></script>
  44
  45 </head>
  46
  47 <body class="wy-body-for-nav" role="document">
  48
  49
  50   <div class="wy-grid-for-nav">
  51
  52
  53     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
  54       <div class="wy-side-scroll">
  55         <div class="wy-side-nav-search">
  56
  57
  58
  59             <a href="index.html" class="icon icon-home"> JABAWS
  60
  61
  62
  63           </a>
  64
  65
  66
  67
  68               <div class="version">
  69                 2.2
  70               </div>
  71
  72
  73
  74
  75 <div role="search">
  76   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
  77     <input type="text" name="q" placeholder="Search docs" />
  78     <input type="hidden" name="check_keywords" value="yes" />
  79     <input type="hidden" name="area" value="default" />
  80   </form>
  81 </div>
  82
  83
  84         </div>
  85
  86         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
  87
  88
  89
  90
  91
  92
  93               <p class="caption"><span class="caption-text">Contents:</span></p>
  94 <ul class="current">
  95 <li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting Started</a></li>
  96 <li class="toctree-l1"><a class="reference internal" href="included_tools.html">Included Tools</a></li>
  97 <li class="toctree-l1"><a class="reference internal" href="client.html">Command Line Client (CLI)</a></li>
  98 <li class="toctree-l1"><a class="reference internal" href="war.html">Web Application Archive (WAR)</a></li>
  99 <li class="toctree-l1"><a class="reference internal" href="va.html">Virtual Appliance (VA)</a></li>
 100 <li class="toctree-l1"><a class="reference internal" href="advanced.html">Advanced Usage</a></li>
 101 <li class="toctree-l1 current"><a class="current reference internal" href="#">For Developers</a><ul>
 102 <li class="toctree-l2"><a class="reference internal" href="#source-code">Source Code</a></li>
 103 <li class="toctree-l2"><a class="reference internal" href="#the-api">The API</a></li>
 104 <li class="toctree-l2"><a class="reference internal" href="#structure-of-the-project">Structure of the project</a></li>
 105 <li class="toctree-l2"><a class="reference internal" href="#the-code-structure">The code structure</a></li>
 106 <li class="toctree-l2"><a class="reference internal" href="#unit-testing">Unit Testing</a></li>
 107 <li class="toctree-l2"><a class="reference internal" href="#accessing-jabaws-from-your-program">Accessing JABAWS from your program</a><ul>
 108 <li class="toctree-l3"><a class="reference internal" href="#web-services-functions-overview">Web services functions overview</a></li>
 109 <li class="toctree-l3"><a class="reference internal" href="#structure-of-the-template-command-line-client">Structure of the template command line client</a></li>
 110 <li class="toctree-l3"><a class="reference internal" href="#connecting-to-jabaws">Connecting to JABAWS</a></li>
 111 <li class="toctree-l3"><a class="reference internal" href="#aligning-sequences">Aligning Sequences</a></li>
 112 <li class="toctree-l3"><a class="reference internal" href="#checking-the-status-of-the-calculation">Checking the status of the calculation</a></li>
 113 <li class="toctree-l3"><a class="reference internal" href="#aligning-with-presets">Aligning with presets</a></li>
 114 <li class="toctree-l3"><a class="reference internal" href="#aligning-with-custom-parameters">Aligning with custom parameters</a></li>
 115 <li class="toctree-l3"><a class="reference internal" href="#writing-alignments-to-a-file">Writing alignments to a file</a></li>
 116 <li class="toctree-l3"><a class="reference internal" href="#a-complete-client-example">A complete client example</a></li>
 117 </ul>
 118 </li>
 119 <li class="toctree-l2"><a class="reference internal" href="#adding-new-web-services">Adding new web-services</a><ul>
 120 <li class="toctree-l3"><a class="reference internal" href="#brief-guide">Brief Guide</a></li>
 121 <li class="toctree-l3"><a class="reference internal" href="#building-web-services-artifacts">Building web services artifacts</a></li>
 122 <li class="toctree-l3"><a class="reference internal" href="#preparing-distributives">Preparing Distributives</a></li>
 123 </ul>
 124 </li>
 125 </ul>
 126 </li>
 127 <li class="toctree-l1"><a class="reference internal" href="stats.html">Usage Statistics</a></li>
 128 <li class="toctree-l1"><a class="reference internal" href="citations.html">Citations</a></li>
 129 <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
 130 </ul>
 131
 132
 133
 134         </div>
 135       </div>
 136     </nav>
 137
 138     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
 139
 140
 141       <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
 142
 143           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
 144           <a href="index.html">JABAWS</a>
 145
 146       </nav>
 147
 148
 149
 150       <div class="wy-nav-content">
 151         <div class="rst-content">
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168 <div role="navigation" aria-label="breadcrumbs navigation">
 169
 170   <ul class="wy-breadcrumbs">
 171
 172       <li><a href="index.html">Docs</a> &raquo;</li>
 173
 174       <li>For Developers</li>
 175
 176
 177       <li class="wy-breadcrumbs-aside">
 178
 179
 180             <!-- <a href="_sources/develop.rst.txt" rel="nofollow"> View page source</a> -->
 181             <a href="../../">Return to the JABAWS homepage</a>
 182
 183
 184       </li>
 185
 186   </ul>
 187
 188
 189   <hr/>
 190 </div>
 191           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
 192            <div itemprop="articleBody">
 193
 194   <div class="section" id="for-developers">
 195 <h1>For Developers<a class="headerlink" href="#for-developers" title="Permalink to this headline">¶</a></h1>
 196 <div class="section" id="source-code">
 197 <span id="jabaws-source"></span><h2>Source Code<a class="headerlink" href="#source-code" title="Permalink to this headline">¶</a></h2>
 198 <div class="admonition note">
 199 <p class="first admonition-title">Note</p>
 200 <p class="last">This is an open source project. If you want to contribute or report an issue have a look at our  <a class="reference external" href="https://source.jalview.org/crucible/changelog/jabaws">Git-tracker</a>.</p>
 201 </div>
 202 <p>Publicly available Git repository: <a class="reference external" href="http://source.jalview.org/gitweb/?p=jabaws.git">http://source.jalview.org/gitweb/?p=jabaws.git</a></p>
 203 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">source</span><span class="o">.</span><span class="n">jalview</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">jabaws</span><span class="o">.</span><span class="n">git</span>
 204 </pre></div>
 205 </div>
 206 <hr class="docutils" />
 207 </div>
 208 <div class="section" id="the-api">
 209 <span id="jabaws-api"></span><h2>The API<a class="headerlink" href="#the-api" title="Permalink to this headline">¶</a></h2>
 210 <p><a class="reference external" href="../dm_javadoc/index.html">Data Model JavaDoc</a> - read this if your are coding against JABA Web Services</p>
 211 <p><a class="reference external" href="../full_javadoc/index.html">Complete JavaDoc</a> - for developers who want to use JABAWS framework and use Engines and Executables directly</p>
 212 <hr class="docutils" />
 213 </div>
 214 <div class="section" id="structure-of-the-project">
 215 <span id="jabaws-structure"></span><h2>Structure of the project<a class="headerlink" href="#structure-of-the-project" title="Permalink to this headline">¶</a></h2>
 216 <div class="line-block">
 217 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>binaries</em> contains native executables e.g. clustalw</div>
 218 <div class="line-block">
 219 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>src</em> contains sources of native executables</div>
 220 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>windows</em> contains pre-compiled Windows binaries</div>
 221 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>compilebin.sh</em> the script to complile binaries</div>
 222 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>setexecflag.sh</em> the script to set executable flag for the binaries</div>
 223 </div>
 224 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>conf</em>       contains JABAWS configuration files</div>
 225 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>ExecutionStatistics</em>        the database for storing collected execution statistics</div>
 226 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>jobsout</em> a default folder for temporary job directories</div>
 227 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>statpages</em> the web pages for execution statistics display</div>
 228 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>WEB-INF</em> default</div>
 229 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>docs</em> contains the reStructuredText documentation files</div>
 230 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>website</em> contains the JABAWS web pages</div>
 231 <div class="line-block">
 232 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>archive</em> contains JABAWS packages, the WAR and JAR files</div>
 233 </div>
 234 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>datamodel</em> contains the JABAWS datamodel</div>
 235 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>engine</em> contains the JABAWS engine - the code that abstract the execution environment and executes native binaries</div>
 236 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>runner</em> contains the JABAWS runners - thin wrappers for native binaries</div>
 237 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>webservices</em> contains the JABAWS SOAP web services</div>
 238 <div class="line"><a class="reference internal" href="_images/folder-small.png"><img alt="folder" class="align-middle" src="_images/folder-small.png" style="width: 15px;" /></a> <em>testsrc</em> contains the JABAWS unit tests</div>
 239 </div>
 240 <hr class="docutils" />
 241 </div>
 242 <div class="section" id="the-code-structure">
 243 <span id="jabaws-code"></span><h2>The code structure<a class="headerlink" href="#the-code-structure" title="Permalink to this headline">¶</a></h2>
 244 <a class="reference internal image-reference" href="_images/ws-structure.png"><img alt="_images/ws-structure.png" class="align-left" src="_images/ws-structure.png" style="width: 267.9px; height: 393.29999999999995px;" /></a>
 245 <p>Each source folder depends on the upper folders for compilation. For example, the datamodel is the top level folder so it has no other dependencies on other JABAWS code. The Engine level depends on the datamodel to compile etc. The web services folder is the bottom layer and depends on all the other source code.</p>
 246 <p>So the JABAWS project is split into 4 layers. From bottom-up the first layer consists from the value classes used by all other layers of the hierarchy, in particular web services. So, to be able to use JABAWS one needs to have these classes. At the same time classes on this layer does not have any dependencies on the layers above.</p>
 247 <p>The second layer contains code for execution of the wrappers, which are the abstraction describing native executables. JABAWS can execute tasks locally that is on the same machine as JVM and on the cluster. Thus currently code on this layer contain two engines. This layer depends on the layer underneath, the data model layer, but is completely independent from the code above.</p>
 248 <p>The third layer consists of the wrappers for the native executables and classes to handle their configuration. It depends on the engines and the data model, but know nothing about the web services.</p>
 249 <p>Finally, the upper layer contains the web services, that depend on all the layers below.</p>
 250 <p>The layer isolation is archived though specially designed compilation task which is executed sequentially in several stages so that the first layer compiles before any other layers, second layer compiles after that and process continies before all the code is compiled. Any violation of the layer boundaries results in the compilation failure. Use Ant &#8220;Compile&#8221; or &#8220;Complile_with_debug&#8221; tasks to perform the staged compilation.</p>
 251 <p>A client package contains only classes from data model layer and a simple web services client. Framework package is for anyone who want to use JABAWS framework for controlling native executables in local or cluster environments. Framework exclude the web services layer. Server package contains all the code.</p>
 252 <hr class="docutils" />
 253 </div>
 254 <div class="section" id="unit-testing">
 255 <span id="jabaws-tests"></span><h2>Unit Testing<a class="headerlink" href="#unit-testing" title="Permalink to this headline">¶</a></h2>
 256 <p>JABAWS uses <a class="reference external" href="http://testng.org/doc/index.html">TestNG</a> framework for testing. The test results for the JABAWS package offered for download can be found at: <a class="reference external" href="http://www.compbio.dundee.ac.uk/user/www-jws2/tests/index.html">Test Results</a>
 257 JABAWS uses TestNG for testing. There is a TestNG plugin available for Eclipse which has functionality similar to JUnit. However, no plugins are necessary to run the test cases, as testng jar is supplied with JABAWS together with an ant tasks to run the test cases.</p>
 258 <p>Several testing groups are supported:</p>
 259 <ul class="simple">
 260 <li>All tests (&#8216;Test&#8217;)</li>
 261 <li>Cluster tests (&#8216;Run_cluster_dependent_test&#8217;)</li>
 262 <li>Cluster independent tests (&#8216;All_cluster_independent_tests&#8217;)</li>
 263 <li>Windows only tests (&#8216;All_cluster_independent_windows_only_tests&#8217;)</li>
 264 <li>Performance and stability tests (&#8216;Long_tests&#8217;)</li>
 265 <li>Re-run failed tests (&#8216;Rerun_failed_tests&#8217;)</li>
 266 <li>Run custom test (&#8216;CustomTest&#8217;)</li>
 267 </ul>
 268 <p>To run the tests you need to download all sources from repository. Once you have done that, enter into the command line mode, change directory to the project directory and type:</p>
 269 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">ant</span> <span class="o">-</span><span class="n">f</span> <span class="n">build</span><span class="o">.</span><span class="n">xml</span> <span class="o">&lt;</span><span class="n">test</span> <span class="n">group</span> <span class="n">name</span><span class="o">&gt;</span>
 270 </pre></div>
 271 </div>
 272 <p>Make sure you have <a class="reference external" href="http://ant.apache.org/">Apache Ant</a> installed and path to ant executable is defined in your path environmental variable. Replace test group name with the one of the names given in the list above to run required group of tests e.g for running cluster only tests use the following command:</p>
 273 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">ant</span> <span class="o">-</span><span class="n">f</span> <span class="n">build</span><span class="o">.</span><span class="n">xml</span> <span class="n">Run_cluster_dependent_test</span>
 274 </pre></div>
 275 </div>
 276 <p>If you work under Linux you could use a simple script from the root folder of repository called <code class="docutils literal"><span class="pre">runtests.sh</span></code>. This script simply contains a collection of the test commands described above and paths to java home directory and an ant executable, which you can define once for your system and then reuse.</p>
 277 <p>A handy feature of TestNG is its ability to re-run failed tests. Failed test ant file is stored in <code class="docutils literal"><span class="pre">test-output/testng-failed.xml</span></code>. and is used in the ant task called <code class="docutils literal"><span class="pre">Rerun_failed_tests</span></code>. So re-running failed tests requires no more work than running any other test group and could be accomplished with the command:</p>
 278 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">ant</span> <span class="o">-</span><span class="n">f</span> <span class="n">build</span><span class="o">.</span><span class="n">xml</span> <span class="n">Rerun_failed_tests</span>
 279 </pre></div>
 280 </div>
 281 <p>CustomTest runs the test defined in the project root directory file called <code class="docutils literal"><span class="pre">temp-testng-customsuite.xml</span></code>. This file is generated by TestNG plugin every time you run the test from Eclipse. Thus an easy way to run a test in a different environment is to run it from Eclipse first and then from ant using a custom test procedure.</p>
 282 <p>For cluster execution make sure that the property <code class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></code> defined in build.xml points to cluster engine LD libraries directory in your local system.</p>
 283 <hr class="docutils" />
 284 </div>
 285 <div class="section" id="accessing-jabaws-from-your-program">
 286 <span id="jabaws-conn-services"></span><h2>Accessing JABAWS from your program<a class="headerlink" href="#accessing-jabaws-from-your-program" title="Permalink to this headline">¶</a></h2>
 287 <div class="section" id="web-services-functions-overview">
 288 <span id="jabaws-conn-functions"></span><h3>Web services functions overview<a class="headerlink" href="#web-services-functions-overview" title="Permalink to this headline">¶</a></h3>
 289 <p>All JABAWS multiple sequence alignment web services comply to the same interface, thus the function described below are available from all the services.</p>
 290 <p>Functions for initiating the alignment</p>
 291 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">String</span> <span class="nb">id</span> <span class="o">=</span> <span class="n">align</span><span class="p">(</span><span class="n">List</span><span class="o">&lt;</span><span class="n">FastaSequence</span><span class="o">&gt;</span> <span class="nb">list</span><span class="p">)</span>
 292 <span class="n">String</span> <span class="nb">id</span> <span class="o">=</span> <span class="n">customAlign</span><span class="p">(</span><span class="n">List</span><span class="o">&lt;</span><span class="n">FastaSequence</span><span class="o">&gt;</span> <span class="n">sequenceList</span><span class="p">,</span> <span class="n">List</span><span class="o">&lt;</span><span class="n">Option</span><span class="o">&gt;</span> <span class="n">optionList</span><span class="p">)</span>
 293 <span class="n">String</span> <span class="nb">id</span> <span class="o">=</span> <span class="n">presetAlign</span><span class="p">(</span><span class="n">List</span><span class="o">&lt;</span><span class="n">FastaSequence</span><span class="o">&gt;</span> <span class="n">sequenceList</span><span class="p">,</span> <span class="n">Preset</span> <span class="n">preset</span><span class="p">)</span>
 294 </pre></div>
 295 </div>
 296 <p>Functions pertaining to job monitoring and control</p>
 297 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">JobStatus</span> <span class="n">status</span> <span class="o">=</span> <span class="n">getJobStatus</span><span class="p">(</span><span class="n">String</span> <span class="nb">id</span><span class="p">)</span>
 298 <span class="n">Alignment</span> <span class="n">al</span> <span class="o">=</span> <span class="n">getResult</span><span class="p">(</span><span class="n">String</span> <span class="nb">id</span><span class="p">)</span>
 299 <span class="n">boolean</span> <span class="n">cancelled</span> <span class="o">=</span> <span class="n">cancelJob</span><span class="p">(</span><span class="n">String</span> <span class="nb">id</span><span class="p">)</span>
 300 <span class="n">ChunkHolder</span> <span class="n">chunk</span> <span class="o">=</span> <span class="n">pullExecStatistics</span><span class="p">(</span><span class="n">String</span> <span class="nb">id</span><span class="p">,</span> <span class="n">long</span> <span class="n">marker</span><span class="p">)</span>
 301 </pre></div>
 302 </div>
 303 <p>Functions relating to service features discovery</p>
 304 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">RunnerConfig</span> <span class="n">rc</span> <span class="o">=</span> <span class="n">getRunnerOptions</span><span class="p">()</span>
 305 <span class="n">Limit</span> <span class="n">limit</span> <span class="o">=</span> <span class="n">getLimit</span><span class="p">(</span><span class="n">String</span> <span class="n">name</span><span class="p">)</span>
 306 <span class="n">LimitsManager</span> <span class="n">lm</span> <span class="o">=</span> <span class="n">getLimits</span><span class="p">()</span>
 307 <span class="n">PresetManager</span> <span class="n">pm</span> <span class="o">=</span> <span class="n">getPresets</span><span class="p">()</span>
 308 </pre></div>
 309 </div>
 310 <p>Please refer to a Data Model JavaDoc for a detailed description of each methods.</p>
 311 <hr class="docutils" />
 312 </div>
 313 <div class="section" id="structure-of-the-template-command-line-client">
 314 <span id="jabaws-conn-functions2"></span><h3>Structure of the template command line client<a class="headerlink" href="#structure-of-the-template-command-line-client" title="Permalink to this headline">¶</a></h3>
 315 <table border="1" class="docutils">
 316 <colgroup>
 317 <col width="25%" />
 318 <col width="75%" />
 319 </colgroup>
 320 <thead valign="bottom">
 321 <tr class="row-odd"><th class="head">Packages</th>
 322 <th class="head">Classes and Interfaces</th>
 323 </tr>
 324 </thead>
 325 <tbody valign="top">
 326 <tr class="row-even"><td>compbio.data.msa</td>
 327 <td>MsaWS the interface for all multiple sequence alignment web services</td>
 328 </tr>
 329 <tr class="row-odd"><td>compbio.data.sequence</td>
 330 <td>JABAWS data types</td>
 331 </tr>
 332 <tr class="row-even"><td>compbio.metadata</td>
 333 <td>JABAWS meta data types</td>
 334 </tr>
 335 <tr class="row-odd"><td>compbio.ws.client</td>
 336 <td>JABAWS command line client</td>
 337 </tr>
 338 </tbody>
 339 </table>
 340 <p>Additional utility libraries that this client depend upon is the compbio-util-1.3.jar and compbio-annotation-1.0.jar.</p>
 341 <p>Please refer to a <a class="reference external" href="../dm_javadoc/index.html">Data Model JavaDoc</a> for a detailed description of each class and its methods.</p>
 342 <hr class="docutils" />
 343 </div>
 344 <div class="section" id="connecting-to-jabaws">
 345 <span id="jabaws-conn-conn"></span><h3>Connecting to JABAWS<a class="headerlink" href="#connecting-to-jabaws" title="Permalink to this headline">¶</a></h3>
 346 <p>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 class="reference external" href="download.jsp">download page</a>. Please note that for now all the examples are in Java, other languages will follow if there is sufficient demand.</p>
 347 <p>Download a binary JABAWS client. 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>
 348 <div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">java.net.URL</span><span class="o">;</span>
 349 <span class="kn">import</span> <span class="nn">javax.xml.namespace.QName</span><span class="o">;</span>
 350 <span class="kn">import</span> <span class="nn">javax.xml.ws.Service</span><span class="o">;</span>
 351 <span class="c1">// (...)</span>
 352 <span class="n">String</span> <span class="n">qualifiedName</span> <span class="o">=</span> <span class="s">&quot;http://msa.data.compbio/01/01/2010/&quot;</span><span class="o">;</span>
 353 <span class="n">URL</span> <span class="n">url</span> <span class="o">=</span> <span class="k">new</span> <span class="n">URL</span><span class="o">(</span><span class="s">&quot;http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?wsdl&quot;</span><span class="o">);</span>
 354 <span class="n">QName</span> <span class="n">qname</span> <span class="o">=</span> <span class="k">new</span> <span class="n">QName</span><span class="o">(,</span> <span class="s">&quot;ClustalWS&quot;</span><span class="o">);</span>
 355 <span class="n">Service</span> <span class="n">serv</span> <span class="o">=</span> <span class="n">Service</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">url</span><span class="o">,</span> <span class="n">qname</span><span class="o">);</span>
 356 <span class="n">MsaWS</span> <span class="n">msaws</span> <span class="o">=</span> <span class="n">serv</span><span class="o">.</span><span class="na">getPort</span><span class="o">(</span><span class="k">new</span> <span class="n">QName</span><span class="o">(</span><span class="n">qualifiedName</span><span class="o">,</span> <span class="s">&quot;ClustalWSPort&quot;</span><span class="o">),</span>
 357 <span class="n">MsaWS</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
 358 </pre></div>
 359 </div>
 360 <p>Line 1 makes a qualified name for JABA web services.</p>
 361 <p>Line 2 constructs the URL to the web services WSDL.</p>
 362 <p>Line 3 makes a qualified name instance for Clustal JABA web service.</p>
 363 <p>Line 4 creates a service instance.</p>
 364 <p>Line 5 makes a connection to the server.</p>
 365 <p>A more generic connection method would look like this</p>
 366 <div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">java.net.URL</span><span class="o">;</span>
 367 <span class="kn">import</span> <span class="nn">javax.xml.namespace.QName</span><span class="o">;</span>
 368 <span class="kn">import</span> <span class="nn">javax.xml.ws.Service</span><span class="o">;</span>
 369 <span class="kn">import</span> <span class="nn">compbio.ws.client.Services</span>
 370 <span class="c1">// (...)</span>
 371 <span class="n">String</span> <span class="n">qualifiedServiceName</span> <span class="o">=</span> <span class="s">&quot;http://msa.data.compbio/01/01/2010/&quot;</span><span class="o">;</span>
 372 <span class="n">String</span> <span class="n">host</span> <span class="o">=</span> <span class="s">&quot;http://www.compbio.dundee.ac.uk/jabaws&quot;</span><span class="o">;</span>
 373 <span class="c1">// In real life the service name can come from args</span>
 374 <span class="n">Services</span> <span class="n">clustal</span> <span class="o">=</span> <span class="n">Services</span><span class="o">.</span><span class="na">ClustalWS</span><span class="o">;</span>
 375 <span class="n">URL</span> <span class="n">url</span> <span class="o">=</span> <span class="k">new</span> <span class="n">URL</span><span class="o">(</span><span class="n">host</span> <span class="o">+</span> <span class="s">&quot;/&quot;</span> <span class="o">+</span> <span class="n">clustal</span><span class="o">.</span><span class="na">toString</span><span class="o">()</span> <span class="o">+</span> <span class="s">&quot;?wsdl&quot;</span><span class="o">);</span>
 376 <span class="n">QName</span> <span class="n">qname</span> <span class="o">=</span> <span class="k">new</span> <span class="n">QName</span><span class="o">(</span><span class="n">qualifiedServiceName</span><span class="o">,</span> <span class="n">clustal</span><span class="o">.</span><span class="na">toString</span><span class="o">());</span>
 377 <span class="n">Service</span> <span class="n">serv</span> <span class="o">=</span> <span class="n">Service</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">url</span><span class="o">,</span> <span class="n">qname</span><span class="o">);</span>
 378 <span class="n">MsaWS</span> <span class="n">msaws</span> <span class="o">=</span> <span class="n">serv</span><span class="o">.</span><span class="na">getPort</span><span class="o">(</span><span class="k">new</span> <span class="n">QName</span><span class="o">(</span><span class="n">qualifiedServiceName</span><span class="o">,</span> <span class="n">clustal</span> <span class="o">+</span> <span class="s">&quot;Port&quot;</span><span class="o">),</span> <span class="n">MsaWS</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
 379 </pre></div>
 380 </div>
 381 <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 class="reference external" href="http://www.compbio.dundee.ac.uk/jabaws/full_javadoc/index.html">JavaDoc</a>.</p>
 382 <hr class="docutils" />
 383 </div>
 384 <div class="section" id="aligning-sequences">
 385 <span id="jabaws-conn-aln"></span><h3>Aligning Sequences<a class="headerlink" href="#aligning-sequences" title="Permalink to this headline">¶</a></h3>
 386 <p>Given that <em>msaws</em> is web service proxy, created as described in &#8220;Connecting to JABAWS&#8221; section, the actual alignment can be obtained as follows:</p>
 387 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">List</span><span class="o">&lt;</span><span class="n">FastaSequence</span><span class="o">&gt;</span> <span class="n">fastalist</span> <span class="o">=</span> <span class="n">SequenceUtil</span><span class="o">.</span><span class="n">readFasta</span><span class="p">(</span><span class="n">new</span> <span class="n">FileInputStream</span><span class="p">(</span><span class="n">file</span><span class="p">));</span>
 388 <span class="n">String</span> <span class="n">jobId</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="n">align</span><span class="p">(</span><span class="n">fastalist</span><span class="p">);</span>
 389 <span class="n">Alignment</span> <span class="n">alignment</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="n">getResult</span><span class="p">(</span><span class="n">jobId</span><span class="p">);</span>
 390 <span class="n">Line</span> <span class="n">one</span> <span class="n">loads</span> <span class="n">FASTA</span> <span class="n">sequence</span> <span class="kn">from</span> <span class="nn">the</span> <span class="n">file</span><span class="o">.</span>
 391 </pre></div>
 392 </div>
 393 <p>Line two submits them to web service represented by msaws proxy.</p>
 394 <p>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 (www.compbio.dundee.ac.uk/jabaws) 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.
 395 Methods and classes mentioned in the excerpt are available from the JABAWS client library.</p>
 396 <hr class="docutils" />
 397 </div>
 398 <div class="section" id="checking-the-status-of-the-calculation">
 399 <span id="jabaws-conn-status"></span><h3>Checking the status of the calculation<a class="headerlink" href="#checking-the-status-of-the-calculation" title="Permalink to this headline">¶</a></h3>
 400 <p>You may have noticed that there was no pause between submitting the job and retrieving of the results. This is because getResult(jobId) method block the processing until the calculation is completed. However, taking into account that the connection holds server resources, our public server (www.compbio.dundee.ac.uk/jabaws) 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>
 401 <div class="highlight-java"><div class="highlight"><pre><span></span><span class="k">while</span> <span class="o">(</span><span class="n">msaws</span><span class="o">.</span><span class="na">getJobStatus</span><span class="o">(</span><span class="n">jobId</span><span class="o">)</span> <span class="o">!=</span> <span class="n">JobStatus</span><span class="o">.</span><span class="na">FINISHED</span><span class="o">)</span> <span class="o">{</span>
 402     <span class="n">Thread</span><span class="o">.</span><span class="na">sleep</span><span class="o">(</span><span class="mi">2000</span><span class="o">);</span> <span class="c1">// wait two  seconds, then recheck the status</span>
 403 <span class="o">}</span>
 404 </pre></div>
 405 </div>
 406 <hr class="docutils" />
 407 </div>
 408 <div class="section" id="aligning-with-presets">
 409 <span id="jabaws-conn-aln-presets"></span><h3>Aligning with presets<a class="headerlink" href="#aligning-with-presets" title="Permalink to this headline">¶</a></h3>
 410 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">PresetManager</span> <span class="n">presetman</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="n">getPresets</span><span class="p">();</span>
 411 <span class="n">Preset</span> <span class="n">preset</span> <span class="o">=</span> <span class="n">presetman</span><span class="o">.</span><span class="n">getPresetByName</span><span class="p">(</span><span class="n">presetName</span><span class="p">);</span>
 412 <span class="n">List</span><span class="o">&lt;</span><span class="n">FastaSequence</span><span class="o">&gt;</span> <span class="n">fastalist</span> <span class="o">=</span> <span class="n">SequenceUtil</span><span class="o">.</span><span class="n">readFasta</span><span class="p">(</span><span class="n">new</span> <span class="n">FileInputStream</span><span class="p">(</span><span class="n">file</span><span class="p">));</span>
 413 <span class="n">String</span> <span class="n">jobId</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="n">presetAlign</span><span class="p">(</span><span class="n">fastalist</span><span class="p">,</span> <span class="n">preset</span><span class="p">);</span>
 414 <span class="n">Alignment</span> <span class="n">alignment</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="n">getResult</span><span class="p">(</span><span class="n">jobId</span><span class="p">);</span>
 415 </pre></div>
 416 </div>
 417 <p>Line one obtains the lists of presets supported by a web service.</p>
 418 <p>Line two return a particular Preset by its name.</p>
 419 <p>Lines three to five are doing the same job as in the <a class="reference external" href="develop.html#aligning-sequences">first aligning sequences example</a>.</p>
 420 <hr class="docutils" />
 421 </div>
 422 <div class="section" id="aligning-with-custom-parameters">
 423 <span id="jabaws-conn-aln-params"></span><h3>Aligning with custom parameters<a class="headerlink" href="#aligning-with-custom-parameters" title="Permalink to this headline">¶</a></h3>
 424 <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">RunnerConfig</span> <span class="n">options</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="n">getRunnerOptions</span><span class="p">();</span>
 425 <span class="n">Argument</span> <span class="n">matrix</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">getArgument</span><span class="p">(</span><span class="s2">&quot;MATRIX&quot;</span><span class="p">);</span>
 426 <span class="n">matrix</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s2">&quot;PAM300&quot;</span><span class="p">);</span>
 427 <span class="n">Argument</span> <span class="n">gapopenpenalty</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">getArgument</span><span class="p">(</span><span class="s2">&quot;GAPOPEN&quot;</span><span class="p">);</span>
 428 <span class="n">gapopenpenalty</span><span class="o">.</span><span class="n">setValue</span><span class="p">(</span><span class="s2">&quot;20&quot;</span><span class="p">);</span>
 429 <span class="n">List</span><span class="o">&lt;</span><span class="n">Argument</span><span class="o">&gt;</span> <span class="n">arguments</span> <span class="o">=</span> <span class="n">new</span> <span class="n">ArrayList</span><span class="o">&lt;</span><span class="n">Argument</span><span class="o">&gt;</span><span class="p">();</span>
 430 <span class="n">arguments</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">matrix</span><span class="p">);</span> <span class="n">arguments</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">gapopenpenalty</span><span class="p">);</span>
 431 <span class="n">List</span><span class="o">&lt;</span><span class="n">FastaSequence</span><span class="o">&gt;</span> <span class="n">fastalist</span> <span class="o">=</span> <span class="n">SequenceUtil</span><span class="o">.</span><span class="n">readFasta</span><span class="p">(</span><span class="n">new</span> <span class="n">FileInputStream</span><span class="p">(</span><span class="n">file</span><span class="p">));</span>
 432 <span class="n">String</span> <span class="n">jobId</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="n">customAlign</span><span class="p">(</span><span class="n">fastalist</span><span class="p">,</span> <span class="n">arguments</span><span class="p">);</span>
 433 <span class="n">Alignment</span> <span class="n">alignment</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="n">getResult</span><span class="p">(</span><span class="n">jobId</span><span class="p">);</span>
 434 </pre></div>
 435 </div>
 436 <p>Line one obtains the <code class="docutils literal"><span class="pre">RunnerConfig</span></code> object that holds information on supported parameters and their values</p>
 437 <p>Line two retrieve a particular parameter from the holder by its name.</p>
 438 <p>Lines three sets a value to this parameter which will be used in the calculation.</p>
 439 <p>Line four and five do the same but for another parameter.</p>
 440 <p>Line six makes a List to hold the parameters.</p>
 441 <p>Line seven puts the parameters into that list.</p>
 442 <p>Line eight and ten is the same as in previous examples.</p>
 443 <p>Line nine submit an alignment request with the sequences and the parameters.</p>
 444 <p>The names of all the parameters supported by a web service e.g. &#8220;PAM300&#8221; can be obtained using <code class="docutils literal"><span class="pre">options.getArguments()</span></code> method. Further details on the methods available from <code class="docutils literal"><span class="pre">RunnerConfig</span></code> object are available from the JavaDoc.</p>
 445 <hr class="docutils" />
 446 </div>
 447 <div class="section" id="writing-alignments-to-a-file">
 448 <span id="jabaws-conn-aln-file"></span><h3>Writing alignments to a file<a class="headerlink" href="#writing-alignments-to-a-file" title="Permalink to this headline">¶</a></h3>
 449 <p>There is a utility method in the client library that does exactly that.</p>
 450 <div class="highlight-java"><div class="highlight"><pre><span></span><span class="n">Alignment</span> <span class="n">alignment</span> <span class="o">=</span> <span class="n">align</span><span class="o">(...)</span>
 451 <span class="n">FileOutputStream</span> <span class="n">outStream</span> <span class="o">=</span> <span class="k">new</span> <span class="n">FileOutputStream</span><span class="o">(</span><span class="n">file</span><span class="o">);</span>
 452 <span class="n">ClustalAlignmentUtil</span><span class="o">.</span><span class="na">writeClustalAlignment</span><span class="o">(</span><span class="n">outStream</span><span class="o">,</span> <span class="n">align</span><span class="o">);</span>
 453 </pre></div>
 454 </div>
 455 <hr class="docutils" />
 456 </div>
 457 <div class="section" id="a-complete-client-example">
 458 <span id="jabaws-conn-aln-example"></span><h3>A complete client example<a class="headerlink" href="#a-complete-client-example" title="Permalink to this headline">¶</a></h3>
 459 <p>Finally, a complete example of the program that connects to JABAWS Clustal service and aligns sequences using one of the Clustal web service presets. All you need for this to work is a <a class="reference external" href="download.jsp#client">JABAWS CLI client</a>. Please make sure that the client is in the Java class path before running this example.</p>
 460 <div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">java.io.ByteArrayInputStream</span><span class="o">;</span>
 461 <span class="kn">import</span> <span class="nn">java.io.FileNotFoundException</span><span class="o">;</span>
 462 <span class="kn">import</span> <span class="nn">java.io.IOException</span><span class="o">;</span>
 463 <span class="kn">import</span> <span class="nn">java.net.URL</span><span class="o">;</span>
 464 <span class="kn">import</span> <span class="nn">java.util.List</span><span class="o">;</span>
 465
 466 <span class="kn">import</span> <span class="nn">javax.xml.namespace.QName</span><span class="o">;</span>
 467 <span class="kn">import</span> <span class="nn">javax.xml.ws.Service</span><span class="o">;</span>
 468
 469 <span class="kn">import</span> <span class="nn">compbio.data.msa.MsaWS</span><span class="o">;</span>
 470 <span class="kn">import</span> <span class="nn">compbio.data.sequence.Alignment</span><span class="o">;</span>
 471 <span class="kn">import</span> <span class="nn">compbio.data.sequence.FastaSequence</span><span class="o">;</span>
 472 <span class="kn">import</span> <span class="nn">compbio.data.sequence.SequenceUtil</span><span class="o">;</span>
 473 <span class="kn">import</span> <span class="nn">compbio.metadata.JobSubmissionException</span><span class="o">;</span>
 474 <span class="kn">import</span> <span class="nn">compbio.metadata.LimitExceededException</span><span class="o">;</span>
 475 <span class="kn">import</span> <span class="nn">compbio.metadata.Preset</span><span class="o">;</span>
 476 <span class="kn">import</span> <span class="nn">compbio.metadata.PresetManager</span><span class="o">;</span>
 477 <span class="kn">import</span> <span class="nn">compbio.metadata.ResultNotAvailableException</span><span class="o">;</span>
 478 <span class="kn">import</span> <span class="nn">compbio.metadata.UnsupportedRuntimeException</span><span class="o">;</span>
 479 <span class="kn">import</span> <span class="nn">compbio.metadata.WrongParameterException</span><span class="o">;</span>
 480
 481 <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Example</span> <span class="o">{</span>
 482
 483   <span class="cm">/*</span>
 484 <span class="cm">   * Input sequences for alignment</span>
 485 <span class="cm">   */</span>
 486   <span class="kd">static</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">input</span> <span class="o">=</span> <span class="s">&quot;&gt;Foo\r\n&quot;</span>
 487             <span class="o">+</span> <span class="s">&quot;MTADGPRELLQLRAAVRHRPQDFVAWLMLADAELGMGDTTAGEMAVQRGLALHPGHPEAVARLGR&quot;</span>
 488             <span class="o">+</span> <span class="s">&quot;VRWTQQRHAEAAVLLQQASDAAPEHPGIALWLGHALEDAGQAEAAAAAYTRAHQLLPEEPYITAQ&quot;</span>
 489             <span class="o">+</span> <span class="s">&quot;LLNWRRRLCDWRALDVLSAQVRAAVAQGVGAVEPFAFLSEDASAAEQLACARTRAQAIAASVRPL&quot;</span>
 490             <span class="o">+</span> <span class="s">&quot;APTRVRSKGPLRVGFVSNGFGAHPTGLLTVALFEALQRRQPDLQMHLFATSGDDGSTLRTRLAQA&quot;</span>
 491             <span class="o">+</span> <span class="s">&quot;STLHDVTALGHLATAKHIRHHGIDLLFDLRGWGGGGRPEVFALRPAPVQVNWLAYPGTSGAPWMD&quot;</span>
 492             <span class="o">+</span> <span class="s">&quot;YVLGDAFALPPALEPFYSEHVLRLQGAFQPSDTSRVVAEPPSRTQCGLPEQGVVLCCFNNSYKLN&quot;</span>
 493             <span class="o">+</span> <span class="s">&quot;PQSMARMLAVLREVPDSVLWLLSGPGEADARLRAFAHAQGVDAQRLVFMPKLPHPQYLARYRHAD&quot;</span>
 494             <span class="o">+</span> <span class="s">&quot;LFLDTHPYNAHTTASDALWTGCPVLTTPGETFAARVAGSLNHHLGLDEMNVADDAAFVAKAVALAS&quot;</span>
 495             <span class="o">+</span> <span class="s">&quot;DPAALTALHARVDVLRRESGVFEMDGFADDFGALLQALARRHGWLGI\r\n&quot;</span>
 496             <span class="o">+</span> <span class="s">&quot;\r\n&quot;</span>
 497             <span class="o">+</span> <span class="s">&quot;&gt;Bar\r\n&quot;</span>
 498             <span class="o">+</span> <span class="s">&quot;MGDTTAGEMAVQRGLALHQQRHAEAAVLLQQASDAAPEHPGIALWLHALEDAGQAEAAAAYTRAH&quot;</span>
 499             <span class="o">+</span> <span class="s">&quot;QLLPEEPYITAQLLNAVAQGVGAVEPFAFLSEDASAAESVRPLAPTRVRSKGPLRVGFVSNGFGA&quot;</span>
 500             <span class="o">+</span> <span class="s">&quot;HPTGLLTVALFEALQRRQPDLQMHLFATSGDDGSTLRTRLAQASTLHDVTALGHLATAKHIRHHG&quot;</span>
 501             <span class="o">+</span> <span class="s">&quot;IDLLFDLRGWGGGGRPEVFALRPAPVQVNWLAYPGTSGAPWMDYVLGDAFALPPALEPFYSEHVL&quot;</span>
 502             <span class="o">+</span> <span class="s">&quot;RLQGAFQPSDTSRVVAEPPSRTQCGLPEQGVVLCCFNNSYKLNPQSMARMLAVLREVPDSVLWLL&quot;</span>
 503             <span class="o">+</span> <span class="s">&quot;SGPGEADARLRAFAHAQGVDAQRLVFMPKLPHPQYLARYRHADLFLDTHPYNAHTTASDALWTGC&quot;</span>
 504             <span class="o">+</span> <span class="s">&quot;PVLTTPGETFAARVAGSLNHHLGLDEMNVADDAAFVAKAVALASDPAALTALHARVDVLRRESGV&quot;</span>
 505             <span class="o">+</span> <span class="s">&quot;FEMDGFADDFGALLQALARRHGWLGI\r\n&quot;</span>
 506             <span class="o">+</span> <span class="s">&quot;\r\n&quot;</span>
 507             <span class="o">+</span> <span class="s">&quot;&gt;Friends\r\n&quot;</span>
 508             <span class="o">+</span> <span class="s">&quot;MTADGPRELLQLRAAVRHRPQDVAWLMLADAELGMGDTTAGEMAVQRGLALHPGHPEAVARLGRV&quot;</span>
 509             <span class="o">+</span> <span class="s">&quot;RWTQQRHAEAAVLLQQASDAAPEHPGIALWLGHALEDHQLLPEEPYITAQLDVLSAQVRAAVAQG&quot;</span>
 510             <span class="o">+</span> <span class="s">&quot;VGAVEPFAFLSEDASAAEQLACARTRAQAIAASVRPLAPTRVRSKGPLRVGFVSNGFGAHPTGLL&quot;</span>
 511             <span class="o">+</span> <span class="s">&quot;TVALFEALQRRQPDLQMHLFATSGDDGSTLRTRLAQASTLHDVTALGHLATAKHIRHHGIDLLFD&quot;</span>
 512             <span class="o">+</span> <span class="s">&quot;LRGWGGGGRPEVFALRPAPVQVNWLAYPGTSGAPWMDYVLGDAFALPPALEPFYSEHVLRLQGAF&quot;</span>
 513             <span class="o">+</span> <span class="s">&quot;QPSDTSRVVAEPPSRTQCGLPEQGVVLCCFNNSYKLNPQSMARMLAVLREVPDSVLWLLSGPGEA&quot;</span>
 514             <span class="o">+</span> <span class="s">&quot;DARLRAFAHAQGVDAQRLVFMPKLPHPQYLARYRHADLFLDTHPYNAHTTASDALWTGCPVLTTP&quot;</span>
 515             <span class="o">+</span> <span class="s">&quot;GETFAARVAGSLNHHLGLDEMNVADDAAFVAKAVALASDPAALTALHARVDVLRRESI&quot;</span><span class="o">;</span>
 516
 517   <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">UnsupportedRuntimeException</span><span class="o">,</span>
 518             <span class="n">LimitExceededException</span><span class="o">,</span> <span class="n">JobSubmissionException</span><span class="o">,</span>
 519             <span class="n">WrongParameterException</span><span class="o">,</span> <span class="n">FileNotFoundException</span><span class="o">,</span> <span class="n">IOException</span><span class="o">,</span>
 520             <span class="n">ResultNotAvailableException</span><span class="o">,</span> <span class="n">InterruptedException</span> <span class="o">{</span>
 521
 522             <span class="n">String</span> <span class="n">qualifiedServiceName</span> <span class="o">=</span> <span class="s">&quot;http://msa.data.compbio/01/01/2010/&quot;</span><span class="o">;</span>
 523
 524             <span class="cm">/* Make a URL pointing to web service WSDL */</span>
 525             <span class="n">URL</span> <span class="n">url</span> <span class="o">=</span> <span class="k">new</span> <span class="n">URL</span><span class="o">(</span><span class="s">&quot;http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?wsdl&quot;</span><span class="o">);</span>
 526
 527             <span class="cm">/*</span>
 528 <span class="cm">             * If you are making a client that connects to different web services</span>
 529 <span class="cm">             * you can use something like this:</span>
 530 <span class="cm">             */</span>
 531             <span class="c1">// URL url = new URL(host + &quot;/&quot; + Services.ClustalWS.toString() +</span>
 532             <span class="c1">// &quot;?wsdl&quot;);</span>
 533
 534     <span class="n">QName</span> <span class="n">qname</span> <span class="o">=</span> <span class="k">new</span> <span class="n">QName</span><span class="o">(</span><span class="n">qualifiedServiceName</span><span class="o">,</span> <span class="s">&quot;ClustalWS&quot;</span><span class="o">);</span>
 535     <span class="n">Service</span> <span class="n">serv</span> <span class="o">=</span> <span class="n">Service</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">url</span><span class="o">,</span> <span class="n">qname</span><span class="o">);</span>
 536     <span class="cm">/*</span>
 537 <span class="cm">     * Multiple sequence alignment interface for Clustal web service</span>
 538 <span class="cm">     * instance</span>
 539 <span class="cm">     */</span>
 540     <span class="n">MsaWS</span> <span class="n">msaws</span> <span class="o">=</span> <span class="n">serv</span><span class="o">.</span><span class="na">getPort</span><span class="o">(</span><span class="k">new</span> <span class="n">QName</span><span class="o">(</span><span class="n">qualifiedServiceName</span><span class="o">,</span> <span class="s">&quot;ClustalWS&quot;</span>
 541                     <span class="o">+</span> <span class="s">&quot;Port&quot;</span><span class="o">),</span> <span class="n">MsaWS</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
 542
 543     <span class="cm">/* Get the list of available presets */</span>
 544     <span class="n">PresetManager</span> <span class="n">presetman</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="na">getPresets</span><span class="o">();</span>
 545
 546     <span class="cm">/* Get the Preset object by preset name */</span>
 547     <span class="n">Preset</span> <span class="n">preset</span> <span class="o">=</span> <span class="n">presetman</span>
 548                     <span class="o">.</span><span class="na">getPresetByName</span><span class="o">(</span><span class="s">&quot;Disable gap weighting (Speed-oriented)&quot;</span><span class="o">);</span>
 549
 550     <span class="cm">/*</span>
 551 <span class="cm">     * Load sequences in FASTA format from the file You can use something</span>
 552 <span class="cm">     * like new FileInputStream(&lt;filename&gt;) to load sequence from the file</span>
 553 <span class="cm">     */</span>
 554     <span class="n">List</span><span class="o">&lt;</span><span class="n">FastaSequence</span><span class="o">&gt;</span> <span class="n">fastalist</span> <span class="o">=</span> <span class="n">SequenceUtil</span>
 555                     <span class="o">.</span><span class="na">readFasta</span><span class="o">(</span><span class="k">new</span> <span class="n">ByteArrayInputStream</span><span class="o">(</span><span class="n">input</span><span class="o">.</span><span class="na">getBytes</span><span class="o">()));</span>
 556
 557     <span class="cm">/*</span>
 558 <span class="cm">     * Submit loaded sequences for an alignment using preset. The job</span>
 559 <span class="cm">     * identifier is returned by this method, you can retrieve the results</span>
 560 <span class="cm">     * with it sometime later.</span>
 561 <span class="cm">     */</span>
 562     <span class="n">String</span> <span class="n">jobId</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="na">presetAlign</span><span class="o">(</span><span class="n">fastalist</span><span class="o">,</span> <span class="n">preset</span><span class="o">);</span>
 563
 564     <span class="cm">/* This method will block for the duration of the calculation */</span>
 565     <span class="n">Alignment</span> <span class="n">alignment</span> <span class="o">=</span> <span class="n">msaws</span><span class="o">.</span><span class="na">getResult</span><span class="o">(</span><span class="n">jobId</span><span class="o">);</span>
 566
 567     <span class="cm">/*</span>
 568 <span class="cm">     * This is a better way of obtaining results, it does not involve</span>
 569 <span class="cm">     * holding the connection open for the duration of the calculation,</span>
 570 <span class="cm">     * Besides, as the University of Dundee public server will reset the</span>
 571 <span class="cm">     * connection after 10 minutes of idling, this is the only way to obtain</span>
 572 <span class="cm">     * the results of long running task from our public server.</span>
 573 <span class="cm">     */</span>
 574     <span class="c1">// while (msaws.getJobStatus(jobId) != JobStatus.FINISHED) {</span>
 575     <span class="c1">// Thread.sleep(1000); // wait a second, then recheck the status</span>
 576     <span class="c1">// }</span>
 577
 578     <span class="cm">/* Output the alignment to standard out */</span>
 579     <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">alignment</span><span class="o">);</span>
 580
 581     <span class="c1">// Alternatively, you can record retrieved alignment into the file in</span>
 582     <span class="c1">// ClustalW format</span>
 583
 584     <span class="c1">// ClustalAlignmentUtil.writeClustalAlignment(new FileOutputStream(</span>
 585     <span class="c1">// &quot;output.al&quot;), alignment);</span>
 586
 587   <span class="o">}</span>
 588 <span class="o">}</span>
 589 </pre></div>
 590 </div>
 591 <p>For a more detailed description of all available types and their functions please refer to the <a class="reference external" href="../dm_javadoc/index.html">Data Model JavaDoc</a>.</p>
 592 <hr class="docutils" />
 593 </div>
 594 </div>
 595 <div class="section" id="adding-new-web-services">
 596 <span id="jabaws-new-services"></span><h2>Adding new web-services<a class="headerlink" href="#adding-new-web-services" title="Permalink to this headline">¶</a></h2>
 597 <div class="section" id="brief-guide">
 598 <span id="jabaws-new-guide"></span><h3>Brief Guide<a class="headerlink" href="#brief-guide" title="Permalink to this headline">¶</a></h3>
 599 <ol class="arabic">
 600 <li><p class="first">Add a new executable which you&#8217;d like to wrap as a JABAWS web service to the binaries folder. If it has the source code and can be recompiled for different platforms include it under <code class="docutils literal"><span class="pre">binaries/src</span></code>. Edit <code class="docutils literal"><span class="pre">setexecutableflag.sh</span></code> and <code class="docutils literal"><span class="pre">compilebin.sh</span></code> scripts in <code class="docutils literal"><span class="pre">binaries/src</span></code> accordingly.</p>
 601 </li>
 602 <li><p class="first">Make sure that all the dependencies of the software being installed are satisfied. If there are other binaries they should be included as well. Keep the dependent binaries in a subfolder for the main executable. Update <code class="docutils literal"><span class="pre">compilebin.sh</span></code> and <code class="docutils literal"><span class="pre">setexecflag.sh</span></code> scripts accordingly.</p>
 603 </li>
 604 <li><p class="first">Make sure that the new executable does not have any hard links to its dependencies, e.g. is able to run from any installation folder and does not contain any hard coded paths.</p>
 605 </li>
 606 <li><p class="first">Describe executable in <code class="docutils literal"><span class="pre">conf/Exectuable.properties</span></code> file. The lowercase name of the wrapper should be included in the name of the property for example Clustal properties all include clustal as a part of the name e.g. <code class="docutils literal"><span class="pre">local.clustalw.bin</span></code>. The same property for MAFFT will be called <code class="docutils literal"><span class="pre">local.mafft.bin</span></code>. For more help please refer to the Executable.properties file.</p>
 607 </li>
 608 <li><p class="first">Describe the executable supported parameters in the <code class="docutils literal"><span class="pre">&lt;ExecutableName&gt;Parameters.xml</span></code>, presets in the <code class="docutils literal"><span class="pre">&lt;ExecutableName&gt;Presets.xml</span></code> and the execution limits in the <code class="docutils literal"><span class="pre">&lt;ExecutableName&gt;Limit.xml</span></code>. By convention these files are stored in <code class="docutils literal"><span class="pre">conf/settings</span></code>. All of these are optional. If the executable does not support parameters you do not have to mention the <code class="docutils literal"><span class="pre">XXXParameter.xml</span></code> file in the <code class="docutils literal"><span class="pre">Executable.properties</span></code> file at all. The same is true for Presets and Limits.</p>
 609 </li>
 610 <li><p class="first">Create a Java wrapper class for your executable. Create it within runner source directory. Examples of other wrappers can be found in <code class="docutils literal"><span class="pre">compbio.runner.msa</span></code> or in other <code class="docutils literal"><span class="pre">compbio.runner.*</span></code> packages. Wrapper should extend <code class="docutils literal"><span class="pre">SkeletalExecutable&lt;T&gt;</span></code> and implement <code class="docutils literal"><span class="pre">PipedExecutable&lt;T&gt;</span></code> if you need to pass the input or collect the results from the standard in/out. Please see Mafft code as example. Wrapper should expend <code class="docutils literal"><span class="pre">SkeletalExecutable&lt;T&gt;</span></code> if input/output can be set as a parameter for an executable. Please see the ClustalW code as example.</p>
 611 </li>
 612 <li><p class="first">Create a testcase suit for your wrapper in <code class="docutils literal"><span class="pre">testsrc</span></code> and run the test cases.</p>
 613 </li>
 614 <li><p class="first">Create parser for the output files of your executable. Suggested location <code class="docutils literal"><span class="pre">compbio.data.sequence.SequenceUtil</span></code>.</p>
 615 </li>
 616 <li><p class="first">Test the parser.</p>
 617 </li>
 618 <li><p class="first">Decide which web services interfaces your executable is going to match. For example if the executable output can be represented as SequenceAnnotation then SequenceAnnotation interface might be appropriate. For multiple sequence alignment an Msa interface should be used.</p>
 619 </li>
 620 <li><p class="first">If you find a web interface that matches your returning data type, then implement a web service which confirms to it within a webservices source folder.</p>
 621 </li>
 622 <li><p class="first">Register web service in <code class="docutils literal"><span class="pre">WEB-INF/web.xml</span></code> and <code class="docutils literal"><span class="pre">WEB-INF/sun-jaxws.xml</span></code>.</p>
 623 </li>
 624 <li><p class="first">Add generated wsdl to wsbuild.xml ant script to generate the stubs.</p>
 625 </li>
 626 <li><p class="first">Run build-server task in wsbuild file. Watch for errors. If the task fails that means that JAXB cannot serialize some of your new data structures. Add appropriate annotations to your data types. Also check that:</p>
 627 <blockquote>
 628 <div><ul class="simple">
 629 <li>you do not have interfaces to serialize, since JAXB cannot serialize them</li>
 630 <li>you have a default no args constructor (can be private if you do not need it)</li>
 631 <li>JAXB cannot serialize Java Map class, use a custom data structure instead</li>
 632 <li>Enum cannot be serialized as its abstract class (do not confuse with enum which is fine)</li>
 633 <li>Fields serialization leaves a little more space for manoeuvre. If you do this then you may accept and return interfaces, e.g. List, Map; abstract classes etc, from your methods</li>
 634 </ul>
 635 </div></blockquote>
 636 <p>If you have the data on the server side, but nothing is coming through to the client, this is a JAXB serialization problem. They tend to be very silent and thus hard to debug. Check your data structure can be serialized!</p>
 637 </li>
 638 <li><p class="first">Modify the client to work with your new web service. Update Services enumeration to include new service and ensure that all the methods of this enumeration take into account the new service. Update the client help text (<code class="docutils literal"><span class="pre">client_help.txt</span></code>) and insert it into the Constraints class.</p>
 639 </li>
 640 <li><p class="first">Test the web service with the client.</p>
 641 </li>
 642 <li><p class="first">Test on the cluster.</p>
 643 </li>
 644 </ol>
 645 <hr class="docutils" />
 646 </div>
 647 <div class="section" id="building-web-services-artifacts">
 648 <span id="jabaws-artifacts"></span><h3>Building web services artifacts<a class="headerlink" href="#building-web-services-artifacts" title="Permalink to this headline">¶</a></h3>
 649 <p>JABAWS are the standard <a class="reference external" href="http://jax-ws.java.net/">JAX-WS</a> SOAP web services, which are <a class="reference external" 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 client library as it provides a handful of useful methods in addition to plain data types.</p>
 650 <div class="code bash highlight-default"><div class="highlight"><pre><span></span>wsimport -keep http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?wsdl
 651 </pre></div>
 652 </div>
 653 <p>Server side artifacts should be rebuild whenever the data model, meta model or MSA interface were changed. To do that run build-server task from wsbuild.xml ant build file. WSDL files will be generated in <code class="docutils literal"><span class="pre">webservices/compbio/ws/server/resource</span></code> directory. It is not necessary to edit them if any of the JABAWS clients are used. JABAWS are the standard JAX-WS web services, which are WS-I basic profile compatible.</p>
 654 <hr class="docutils" />
 655 </div>
 656 <div class="section" id="preparing-distributives">
 657 <span id="jabaws-distributives"></span><h3>Preparing Distributives<a class="headerlink" href="#preparing-distributives" title="Permalink to this headline">¶</a></h3>
 658 <p>There are a number of ant tasks aimed for preparing distributives for download. Currently a few types of JABAWS packages are offered:</p>
 659 <ol class="arabic simple">
 660 <li>Client only (contains classes required to access JABA Web Services)</li>
 661 <li>Platform specific JABAWS (windows and other)</li>
 662 <li>JABAWS with and without binaries</li>
 663 <li>JABAWS framework and complete project</li>
 664 </ol>
 665 <p>The easiest way to build all distributives is to call <code class="docutils literal"><span class="pre">build-all</span></code> ant task. There are more tasks defined in build.xml than described here. They are mostly self explanatory.</p>
 666 <p>If you made any changes to the data model and would like to generate a complete JABAWS distro make sure you have rebuilt jaxws artifact as described below.</p>
 667 </div>
 668 </div>
 669 </div>
 670
 671
 672            </div>
 673            <div class="articleComments">
 674
 675            </div>
 676           </div>
 677           <footer>
 678
 679     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 680
 681         <a href="stats.html" class="btn btn-neutral float-right" title="Usage Statistics" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
 682
 683
 684         <a href="advanced.html" class="btn btn-neutral" title="Advanced Usage" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
 685
 686     </div>
 687
 688
 689   <hr/>
 690
 691   <div role="contentinfo">
 692     <p><a href="../../">JABAWS 2.2</a>
 693         &copy; Copyright 2017, Peter Troshin, Alexander Sherstnev, Jim Procter, Daniel Barton, Fábio Madeira, Alexey Drozdetskiy, Suzanne Duce and Geoff Barton.
 694
 695     </p>
 696   </div>
 697   Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
 698
 699 </footer>
 700         </div>
 701       </div>
 702
 703     </section>
 704
 705   </div>
 706
 707
 708
 709
 710
 711     <script type="text/javascript">
 712         var DOCUMENTATION_OPTIONS = {
 713             URL_ROOT:'./',
 714             VERSION:'2.2',
 715             LANGUAGE:'None',
 716             COLLAPSE_INDEX:false,
 717             FILE_SUFFIX:'.html',
 718             HAS_SOURCE:  true,
 719             SOURCELINK_SUFFIX: '.txt'
 720         };
 721     </script>
 722       <script type="text/javascript" src="_static/jquery.js"></script>
 723       <script type="text/javascript" src="_static/underscore.js"></script>
 724       <script type="text/javascript" src="_static/doctools.js"></script>
 725
 726
 727
 728
 729
 730     <script type="text/javascript" src="_static/js/theme.js"></script>
 731
 732
 733
 734
 735   <script type="text/javascript">
 736       jQuery(function () {
 737           SphinxRtdTheme.StickyNav.enable();
 738       });
 739   </script>
 740
 741
 742 </body>
 743 </html>