Java Bioinformatics Analyses Web Services (JABAWS) developers documentation

Date: Tue, 2 Aug 2011 16:50:27 +0000 Subject: [PATCH] Updates to a web site git-svn-id: link to svn.lifesci.dundee.ac.uk/svn/barton/ptroshin/JABA2@4441 e3abac25-378b-4346-85de-24260fe3988d --- website/index.html | 4 +- website/man_about.html | 1 + website/man_client.html | 1 + website/man_configuration.html | 1 + website/man_dev.html | 1 + website/man_jaba_internals.html | 144 ------------------------ website/man_server_dev.html | 230 +++++++++++++++++++++++++++++++++++++++ website/man_servervm.html | 1 + website/man_serverwar.html | 1 + website/man_stats.html | 1 + 10 files changed, 239 insertions(+), 146 deletions(-) delete mode 100644 website/man_jaba_internals.html create mode 100644 website/man_server_dev.html diff --git a/website/index.html b/website/index.html index c2ed799..e8713c4 100644 --- a/website/index.html +++ b/website/index.html @@ -106,8 +106,8 @@ title="http://www.compbio.dundee.ac.uk/jabaws/ClustalWS?" rel= -

Last update: 19 May 2011
- This site is best viewed in Firefox 3.6, Google Chrome 10 or Internet Explorer 8

Last update: 2 August 2011
+ This site is best viewed in Firefox 3.6, Google Chrome 10, Internet Explorer 8 or above

diff --git a/website/man_about.html b/website/man_about.html index 3758bfe..bea4ae6 100644 --- a/website/man_about.html +++ b/website/man_about.html @@ -34,6 +34,7 @@ Usage Statistics Accessing
JABAWS + JABAWS Development Download Contact Us diff --git a/website/man_client.html b/website/man_client.html index 2f2fc53..5738114 100644 --- a/website/man_client.html +++ b/website/man_client.html @@ -36,6 +36,7 @@ Usage Statistics Accessing
JABAWS + JABAWS Development Download Contact Us diff --git a/website/man_configuration.html b/website/man_configuration.html index 4e20c50..77a873c 100644 --- a/website/man_configuration.html +++ b/website/man_configuration.html @@ -36,6 +36,7 @@ Usage Statistics Accessing
JABAWS + JABAWS Development Download Contact Us diff --git a/website/man_dev.html b/website/man_dev.html index e468309..491ebc5 100644 --- a/website/man_dev.html +++ b/website/man_dev.html @@ -36,6 +36,7 @@ Usage Statistics Accessing
JABAWS + JABAWS Development Download Contact Us diff --git a/website/man_jaba_internals.html b/website/man_jaba_internals.html deleted file mode 100644 index 50f66ed..0000000 --- a/website/man_jaba_internals.html +++ /dev/null @@ -1,144 +0,0 @@ - - - - -Java Bioinformatics Analyses Web Services (JABAWS) developers documentation - - - - - - - -

- - -

-Home - Getting Started - Manual -

- About - Server VA - Server WAR - Server
- Configuration - JABAWS Internals - CMD Client - Usage Statistics - Accessing
- JABAWS -

-Download -Contact Us -Usage Statistics -Barton Group -

- -

JABAWS Javadoc

Data model javadoc- read this if your are coding against JABA Web Services

Complete javadoc - for developers who want to use JABAWS framework and use Engines and Executables directly

Starting up from the source code

SVN source repository:https://svn.lifesci.dundee.ac.uk/svn/barton/ptroshin/JABA_r1
-The repository contains a complete JABAWS Eclipse 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 http://subclipse.tigris.org/update_1.4.x 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 http://testng.org/doc/download.html. 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 build-server task from wsbuild.xml ant script, than you could use build.xml tasks to generate any of the distributives you need.

Structure of the project

Layers in the source code are defined in a different source folders which are: -
/webservices
- /runner
- /engine
- /datamodel

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.

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.

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.

Finally, the upper layer contains the web services, that depend on all the layers below.

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 "Compile" or "Complile_with_debug" tasks to perform the staged compilation.

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.

- -

Running tests

The test results for the JABAWS package offered for download can be found here: Test Results
-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.

The best way to ensure that JABAWS framework is completely functional on your system is to run all test cases. -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. -Several testing groups are supported: -

All tests (Test)
Cluster tests (Run_cluster_dependent_test)
Cluster independent tests ()
Windows only tests (All_cluster_independent_windows_only_tests)
Performance and stability tests (Long_tests)
Re-run failed tests (Rerun_failed_tests)
Run custom test (CustomTest)

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: - ant -f build.xml <test group name>

. Make sure you have Apache Ant - 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: ant -f build.xml Run_cluster_dependent_test - If you work under Linux you could use a simple script from the root folder of repository called runtests.sh 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. -

A handy feature of TestNG is its ability to re-run failed tests. Failed test ant file is stored in test-output/testng-failed.xml. and is used in the ant task called Rerun_failed_tests. So re-running failed tests requires no more work than running any other test group and could be accomplished with the command: ant -f build.xml Rerun_failed_tests CustomTest runs the test defined in the project root directory file called temp-testng-customsuite.xml. 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.

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.

- -

Preparing distributive's

There are a number of ant tasks aimed for preparing distributives for download. - Currently a few types of JABAWS packages are offered -

Client only (contains classes required to access JABA Web Services)
Platform specific JABAWS (windows and other)
JABA Web Services without JAXWS libraries ( a the runtime dependency)
JABAWS without binaries
JABAWS without binaries and jax-ws
JABAWS framework

- Corresponding build task names are: -

min-jaba-client
jaba-windows, jaba-complete
jaba-without-jaxws
jaba-no-binaries
jaba-no-jaxws-no-binaries
full-jaba-client

- -

The easiest way to build all distributives is to call build-all ant task. There are more tasks defined in build.xml than described here. They are mostly self explanatory.

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.

Building web services artifacts

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 webservices/compbio/ws/server/resource 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, <soap:address location="REPLACE_WITH_ACTUAL_URL"/>

- -

must be replaced with an actual server URL including the web services context path. For example:

http://www.compbio.ac.uk:8080/ws

JABAWS are the standard JAX-WS web services, which are WS-I basic profile compatible.

- -

Last update: 19 August 2010
Peter Troshin, The Barton Group, University of Dundee, UK

- - - - - - diff --git a/website/man_server_dev.html b/website/man_server_dev.html new file mode 100644 index 0000000..f95b23a --- /dev/null +++ b/website/man_server_dev.html @@ -0,0 +1,230 @@ + + + + +Java Bioinformatics Analyses Web Services (JABAWS) developers documentation + + + + + + + +

+ + +

+Home + Getting Started + Manual +

+ About + Server VA + Server WAR + Server
+ Configuration + CMD Client + Usage Statistics + Accessing
+ JABAWS + JABAWS Development +

+Download +Contact Us +Usage Statistics +Barton Group +

+ +

For JABAWS Developers

The JABAWS project

This page is for anyone who wants to add a new webservice into the JABAWS framework.

The API
The source code
Structure of the project
The code structure
Running tests
Preparing distributive's
Building web services artifacts
Rough guide - adding a new web service

+ +

The API

Data model javadoc- read this if your are coding against JABA Web Services

Complete javadoc - for developers who want to use JABAWS framework and use Engines and Executables directly

The source code

Private (most up-to-date) SVN source repository:https://svn.lifesci.dundee.ac.uk/svn/barton/ptroshin/JABA2_r1

The JABAWS public code repository containing the code for each JABAWS public release is located at https://jabaws.googlecode.com/

The repository contains a complete JABAWS Eclipse project.

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 build-server task from wsbuild.xml ant script, than you could use build.xml tasks to generate any of the distributives you need.

Structure of the project

+ binaries contains native executables e.g. clustalw

src contains sources of native executables
windows contains pre-compiled Windows binaries
compilebin.sh - the script to complile binaries
setexecflag.sh - the script to set executable flag for the binaries

conf contains JABAWS configuration files
ExecutionStatistics the database for storing collected execution statistics
jobsout a default folder for temporary job directories
statpages the web pages for execution statistics display
WEB-INF default
website contains the JABAWS web pages

archive contains JABAWS packages, the WAR and JAR files

The code structure

datamodel contains the JABAWS datamodel
engine contains the JABAWS engine - the code that abstract the execution environment and executes native binaries
runner contains the JABAWS runners - thin wrappers for native binaries
webservices contains the JABAWS SOAP web services
testsrc contains the JABAWS unit tests

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.

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.

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.

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.

Finally, the upper layer contains the web services, that depend on all the layers below.

+ +

Running tests

JABAWS uses TestNG framework for testing. The test results for the JABAWS package offered for download can be found here: Test Results
+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.

The best way to ensure that JABAWS framework is completely functional on your system is to run all test cases. +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. +Several testing groups are supported: +

All tests (Test)

Cluster tests (Run_cluster_dependent_test)

Cluster independent tests ()

Windows only tests (All_cluster_independent_windows_only_tests)

Performance and stability tests (Long_tests)

Re-run failed tests (Rerun_failed_tests)

Run custom test (CustomTest)

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: + ant -f build.xml <test group name>

. Make sure you have Apache Ant + 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: ant -f build.xml Run_cluster_dependent_test + If you work under Linux you could use a simple script from the root folder of repository called runtests.sh 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.

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.

+ +

Preparing distributive's

There are a number of ant tasks aimed for preparing distributives for download. + Currently a few types of JABAWS packages are offered +

Client only (contains classes required to access JABA Web Services)

Platform specific JABAWS (windows and other)

JABAWS without binaries

JABAWS framework

+ Corresponding build task names are: +

min-jaba-client

jaba-windows, jaba-complete

jaba-no-binaries

full-jaba-client

The easiest way to build all distributives is to call build-all ant task. There are more tasks defined in build.xml than described here. They are mostly self explanatory.

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.

Building web services artifacts

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 webservices/compbio/ws/server/resource 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.

Rough guide - adding a new web service

Add a new executable which you'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 binaries/src. + Edit binaries/src setexecutableflag.sh and compilebin.sh scripts accordingly.
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 subfolder for the main executable. Update compilebin and setexecflag
Make sure that the new executable
Describe executable in conf/Exectuable.properties 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. local.clustalw.bin. + The same property for Mafft will be called local.mafft.bin. For more help please refer to the Executable.properties file.
Describe the executable supported parameters in the <ExecutableName>Parameters.xml, presets in the <ExecutableName>Presets.xml and the execution limits in the <ExecutableName>Limit.xml. By convention these files are stored in conf/settings. All of these are optional. If the + executable does not support parameters you do not have to mention the + XXXParameter.xml file in the Executable.properties file at all. The same is true for + Presets and Limits.
Create a Java wrapper class for your executable. Create it within runner + source directory. Examples of other wrappers can be found in compbio.runner.msa + or compbio.runner.disorder packages. Wrapper should extend SkeletalExecutable<T> + implements PipedExecutable<T> 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 SkeletalExecutable<T> if input/output can be set as a parameter + for an executable. Please see ClustalW code as example.
Create a testcase suit for your wrapper and run the test cases.
Create parser for the output files of your executable. Suggested location + compbio.data.sequence.SequenceUtil
Test the parser
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.
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.
Register web service in WEB-INF/ web.xml and sun-jaxws.xml
Add generated wsdl to wsbuild.xml ant script to generate the stubs.
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
+ - you do not have interfaces to serialize. JAXB cannot serialize them.
+ - you have a default no args constructor (can be private if you do not need it)
+ - JAXB cannot serialize a Map, use custom data structure instead!
+ - Enum cannot be serialized as its abstract class (do not confuse with enum
+ which is fine)
+ - Fields serialization leave a little more space for manoeuvre, so use it. If
+ you do then you can accept and return interfaces, e.g. List, Map; abstract
+ classes etc, from your methods.
+
+ 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!
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 + (client_help.txt) and insert it into the Constraints class.
Test the web service with the client
Test on the cluster.

+ +

Last update: 2 August 2011
+ Peter Troshin, The Barton Group, University of Dundee, UK

+ + + + + + + diff --git a/website/man_servervm.html b/website/man_servervm.html index dad2ebf..1a14d3d 100644 --- a/website/man_servervm.html +++ b/website/man_servervm.html @@ -36,6 +36,7 @@ Usage Statistics Accessing
JABAWS + JABAWS Development Download Contact Us diff --git a/website/man_serverwar.html b/website/man_serverwar.html index 8c6d18f..61801cf 100644 --- a/website/man_serverwar.html +++ b/website/man_serverwar.html @@ -36,6 +36,7 @@ Usage Statistics Accessing
JABAWS + JABAWS Development Download Contact Us diff --git a/website/man_stats.html b/website/man_stats.html index 8c24989..da8036f 100644 --- a/website/man_stats.html +++ b/website/man_stats.html @@ -36,6 +36,7 @@ Usage Statistics Accessing
JABAWS + JABAWS Development Download Contact Us -- 1.7.10.2