website/develhome.html

   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
   3 <head>\r
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />\r
   5 <title>Java Bioinformatics Analyses Web Services (JABAWS) developers documentation</title>\r
   6 <link href="ws.css" rel="stylesheet" type="text/css" media="screen,  projection, handheld, tv" />\r
   7 <link rel="stylesheet" type="text/css" media="print" href="print.css"/>\r
   8 \r
   9 <script type="text/javascript" src="prototype-1.6.0.3.js"></script>\r
  10 \r
  11 </head>\r
  12 <body>\r
  13 <div id="page">\r
  14 <div id="banner">\r
  15 <table> \r
  16 <tr><td style="width:130px;"><a href="http://www.dundee.ac.uk"><img src="images/uod_lt.gif"  alt="University of Dundee" class="logo"  title="University of Dundee" longdesc="http://www.dundee.ac.uk"/></a></td>\r
  17 <td class="bg"><img src="images/jabaws.png" title="JABAWS:MSA" alt="JABAWS:MSA"/></td>\r
  18 <td class="bg"><img src="images/align.png"/></td>\r
  19 </tr>\r
  20 </table>\r
  21 </div><!-- banner end-->\r
  22 \r
  23 <div id="wrapper">\r
  24 <div id="panel">\r
  25         <a class="selected" href="index.html">Devel Home</a>\r
  26         <a href="http://www.compbio.dundee.ac.uk/jabaws">JABAWS Production</a>\r
  27 <a href="http://www.compbio.dundee.ac.uk/user/www-jws2/wbstat" title="http://www.compbio.dundee.ac.uk/user/www-jws2/wbstat" rel="nofollow">Webalizer Access Stats</a>\r
  28 <a href="http://www.compbio.dundee.ac.uk/user/www-jws2/awstat_index.html" title="http://www.compbio.dundee.ac.uk/user/www-jws2" rel="nofollow">Awstat Access Stats</a></div>\r
  29 <!-- panel end-->\r
  30 <div id="content">\r
  31 \r
  32   <h4>JABAWS Javadoc</h4>\r
  33   <p><a href="dm_javadoc/index.html">Data model</a> javadoc- read this if your are coding against JABA Web Services</p>\r
  34   <p><a href="full_javadoc/index.html">Complete</a> javadoc - for developers who want to use JABAWS framework and use Engines and Executables directly</p>\r
  35   <h4>Starting up from the source code</h4>\r
  36 <p><a name="svn">SVN source repository:</a><a href="link to svn.lifesci.dundee.ac.uk/svn/barton/ptroshin/JABA_r1">https://svn.lifesci.dundee.ac.uk/svn/barton/ptroshin/JABA_r1</a><br/>\r
  37 The repository contains a complete JABAWS <a href="http://www.eclipse.org">Eclipse</a> project. To use Eclipse with this repository you need to install Eclipse SVN plugin which could be found here: http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA. Eclipse update web site address is <a href="http://subclipse.tigris.org/update_1.4.x">http://subclipse.tigris.org/update_1.4.x</a> Take care to install 1.4.x version of the plugin, as SVN repository will not work with more recent clients. it would help to install TestNG plugin as well which could be downloaded from <a href="http://testng.org/doc/download.html">http://testng.org/doc/download.html</a>. Please note however that no generated code is stored in the repository. That is to say that if you like to obtain client or server packages it is better to download them from the download section of this web site. Of cause If you want to make a modification to the source code you would need to generate distributives yourself. To do that first generate JAX-WS artifacts using <span class="hightlight">build-server</span> task from <span class="hightlight">wsbuild.xml</span> ant script, than you could use build.xml tasks to generate any of the distributives you need. </p>\r
  38 <h4>Structure of the project</h4>\r
  39 <img style="padding:0 1em;" align="left" src="images/ws-structure.png" alt="JABAWS layers" />\r
  40 <p>Layers in the source code are defined in a different source folders which are: \r
  41 <br/><span class="hightlight">/webservices<br />\r
  42   /runner<br />\r
  43   /engine<br />\r
  44   /datamodel</span></p>\r
  45 <p style="clear:both">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>\r
  46 <p>The second layer contains code for execution of the wrappers, which are the abstraction describing native executables. The code on this level code engine. 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>\r
  47 <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>\r
  48 <p>Finally, the upper layer contains the web services, that depend on all the layers below.</p>\r
  49 <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 &quot;Compile&quot; or &quot;Complile_with_debug&quot; tasks to perform the staged compilation.</p>\r
  50 <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>\r
  51 \r
  52 <h4>Running tests</h4>\r
  53 <p>The test results for the JABAWS package offered for download can be found here: <a href="http://www.compbio.dundee.ac.uk/user/www-jws2/tests/index.html">Test Results</a><br/>\r
  54 JABAWS uses <a href="http://testng.org/doc/index.html">TestNG</a> 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>\r
  55 <p>The best way to ensure that JABAWS framework is completely functional on your system is to run all test cases. \r
  56 Test cases tests all aspects of JABAWS functionality. Consequently, one need to have non windows operation system and support of the cluster to be able to run all tests. If your system does not support cluster, then you could run all test excluding those that depends on the cluster.\r
  57 Several testing groups are supported: \r
  58 <ul>\r
  59 <li>All tests (Test)</li>\r
  60 <li>Cluster tests (Run_cluster_dependent_test)</li>\r
  61 <li>Cluster independent tests () </li>\r
  62 <li>Windows only tests (All_cluster_independent_windows_only_tests) </li>\r
  63 <li>Performance and stability tests (Long_tests) </li>\r
  64 <li>Re-run failed tests (Rerun_failed_tests) </li>\r
  65 <li>Run custom test (CustomTest) </li>\r
  66 </ul>\r
  67 <p>To run the tests you need to download all sources from <a href="#svn">repository</a>. Once you have done that, enter into the command line mode, change directory to the project directory and type: \r
  68   <span class="code">ant -f build.xml &lt;test group name&gt;</span>    </p>\r
  69   <p>. Make sure you have <a href="http://ant.apache.org/">Apache Ant</a> \r
  70     installed and path to ant executable is defined in your path environmental variable. \r
  71     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 \r
  72     use the following \r
  73     command: <span class="code">ant -f build.xml Run_cluster_dependent_test</span>\r
  74     If you work under Linux you could use a simple script from the root folder of repository called <span class="hightlight">runtests.sh</span> 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.\r
  75     </p>\r
  76   </p>\r
  77   <p>A handy feature of TestNG is its ability to re-run failed tests. Failed test ant file is stored in <span class="hightlight">test-output/testng-failed.xml</span>. and is used in the ant task called <span class="hightlight">Rerun_failed_tests</span>. So re-running failed tests requires no more work than running any other test group and could be accomplished with the command: <span class="code">ant -f build.xml Rerun_failed_tests</span> CustomTest runs the test defined in the project root directory file called <span class="hightlight">temp-testng-customsuite.xml</span>. 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>\r
  78   <p class="hightlight">For cluster execution make sure that the property LD_LIBRARY_PATH defined in build.xml points to cluster engine LD libraries directory in your local system.</p>\r
  79 \r
  80  <h4>Preparing distributive's</h4>\r
  81   <p>There are a number of ant tasks aimed for preparing distributives for download.\r
  82   Currently a few types of JABAWS packages are offered \r
  83   <ol>\r
  84           <li>Client only (contains classes required to access JABA Web Services)</li>\r
  85           <li>Platform specific JABAWS (windows and other)</li>\r
  86           <li>JABA Web Services without JAXWS libraries ( a the runtime dependency) </li>\r
  87           <li>JABAWS without binaries</li>\r
  88           <li>JABAWS without binaries and jax-ws </li>\r
  89           <li>JABAWS framework </li>\r
  90   </ol>\r
  91   </p>\r
  92   Corresponding build task names are: \r
  93   <ol>\r
  94          <li>min-jaba-client</li>\r
  95          <li>jaba-windows, jaba-complete</li>\r
  96          <li>jaba-without-jaxws</li>\r
  97      <li>jaba-no-binaries</li>\r
  98      <li>jaba-no-jaxws-no-binaries</li>\r
  99      <li>full-jaba-client</li>\r
 100   </ol>\r
 101 \r
 102   <p>The easiest way to build all distributives is to call <span class="hightlight">build-all </span>ant task. There are more tasks defined in build.xml than described here. They are mostly self explanatory.  </p>\r
 103   <p class="hightlight">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>\r
 104   <h4>Building web services artifacts</h4>\r
 105 <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 <span class="hightlight">webservices/compbio/ws/server/resource</span> directory. It is not necessary to edit them if any of the JABAWS clients are used. However, if you would like to generate portable artifacts using wsimport based on the generated WSDL files then, <span class="code">&lt;soap:address location=&quot;REPLACE_WITH_ACTUAL_URL&quot;/&gt;</span></p>\r
 106 \r
 107 <p>must be replaced with an actual server URL including the web services context path. For example: </p>\r
 108 <p class="code">http://www.compbio.ac.uk:8080/ws</p>\r
 109 <p>JABAWS are the standard JAX-WS web services, which are WS-I basic profile compatible. </p>\r
 110 </div>\r
 111 <!-- content end--> \r
 112 <div id="copyright">Last update: 16 September 2011<br/>\r
 113   Peter Troshin, The Barton Group, University of Dundee, UK</div>\r
 114 </div><!-- wrapper end-->\r
 115 </div> <!-- page end-->\r
 116 <!-- Google analitics -->\r
 117 <script type="text/javascript">\r
 118 var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");\r
 119 document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));\r
 120 </script>\r
 121 <script type="text/javascript">\r
 122 try{\r
 123 var pageTracker = _gat._getTracker("UA-5356328-1");\r
 124 pageTracker._trackPageview();\r
 125 } catch(err) {}\r
 126 </script>\r
 127 </body>\r
 128 </html>\r
 129 \r