BiBiServ Logo
Attention:
Due to technical maintenance some tools might be unavailable.
See maintenance information.
BiBiServ -
                                    Bielefeld         University Bioinformatic Service
Tools
Education
Administration
Tools
Genome Comparison
Gecko
REPuter
...more
Alignments
PoSSuMsearch2
ChromA
...more
Primer Design
GeneFisher2
RNA Studio
RNAshapes
KnotInFrame
RNAhybrid
...more
Evolutionary Relationship
ROSE
...more
Others
XenDB
jPREdictor
...more

RNAshapes - WebService

This is a short introduction using RNAshapes WebServices offered by BiBiServ. If you're not familiar with using webservices in general you should have a closer look to our webservice related linklist.

WSDL - methods, parameters and datatypes

If you've a closer look at the WSDL file describing the RNAshapes webservice, you can see two methods belonging together.

request and response
request_orig and response_orig

Bioinformatic programs often perform computation on large data sets and therefore require much CPU time. This can cause problems like http connection timeouts (usually after 5 minutes) during online usage. To avoid such problems when using RNAshapes WebService we use a technique called Request and Reply with polling based on BiBiWS. First the client side (e.g. your program) requests a RNAshapes job submitting the necessary data (parameter and data) and gets an id after the job is started. Afterwards the client can request the result by calling the corresponding response method with the id returned earlier. If the RNAshapes job is not finished, the user gets a status code with an enhanced description of current status back (see HOBIT status codes for more information).

request / request_orig
The request method expects the following parameters: An email address for mail notification (may be an empty String), one or more RNA sequences in SequenceML format and an object array containing "key"-"value" pairs (see table below for an example param array - default values in bold). The request method returns either a unique id or in case of an error a fault message.
The request_orig method requires quite similar parameters: An email address for mail notification (may be an empty String), one or more RNA sequences in plain text or in fasta format and an object array containing "key"-"value" pairs (see table below for an example param array - default values in bold). The request_orig method returns either a unique id or in case of an error a fault message.

key value description
mode String - one of the following chars: aspqPiC program mode of RNAshapes
shape Integer - 1 to 5 shape type
energy Double - 0 to 100 energy range, used with energy_mode
energy_mode String - one of the following chars: ce energy mode, used with energy
prob_number Integer - 1 to 1000 sets the max number of probabilities to calculate (probability mode: best)
prob_cutoff Double - 0 to 1 probability cutoff (probability mode)
prob_output Double - 0 to 1 probability output cutoff (probability mode)
sampling Integer - 1 to 100000 number of iterations (sampling mode)
calc_struct_prob Boolean calculate probabilities for structures
ignore_unstable Boolean ignore unstable structures
match_shape String - shape declared using the symbols '[', ']' and '_'. max 1000 chars sets a shape, that all structures have to match
window_size Integer - 1 to 1000000 size of the window
window_incr Integer - 1 to 1000000 increment of the window
note:
While only two parameters (mode and shape) are required and all other parameters are optional, some parameter imply that other parameters are set:
energy and energy_mode should be used as a pair. One does not make sense without the other.
mode with value 'p' for probability mode (best) implies prob_number to be set
mode with value 'i' for sampling mode implies sampling to be set

reponse
The response method expects the bibiid returned by an earlier request or request_orig call. It returns a Document containing the results of the RNAshapes computation in RNAML format. Some information cannot be represented in this format (e.g. shape probabilities), such information is currently lost. If you require the complete results use response_orig method instead.

response_orig
The response_orig method expects the bibiid returned by an earlier request or request_orig call. It returns a String containing the results of the RNAshapes computation in plain text.

Example Perl clients

The example perl client implementation for all methods is based on SOAP::Lite.

Example Client for the requestOrig method (Download Source):


  
#!/usr/bin/env perl 
use SOAP::Lite;
use Data::Dumper;
use Getopt::Long;

#production system
$wsdlurl = "http://bibiserv.techfak.uni-bielefeld.de/wsdl/RNAshapes.wsdl";
#test system
#$wsdlurl = "http://bibitest.techfak.uni-bielefeld.de/wsdl/RNAshapes.wsdl";

my $mode = "a";
my $shape = 5;
my $energy = -1;
my $energy_mode = "";
my $prob_number = -1;
my $prob_cutoff = -1;
my $prob_output = -1;
my $sampling = -1;
my $calc_struc_prob;
my $ignore_unstable;
my $match_shape = "";
my $window_incr = -1;
my $window_size = -1;
my $sequencefile = "";
my $email="";

GetOptions("mode=s" => \$mode,                        #char
"shape=i" => \$shape,                   #int
"energy=i" => \$energy,                 #double
"energy_mode=s" => \$energy_mode,               #char
"prob_number=i" => \$prob_number,               #int
"prob_cutoff=f" => \$prob_cutoff,               #double
"prob_output=f" => \$prob_output,               #double
"sampling=i" => \$sampling,                     #int
"calc_struct_prob" => \$calc_struct_prob,       #boolean
"ignore_unstable" => \$ignore_unstable, #boolean
"match_shape=s" => \$match_shape,               #String
"window_size=i" => \$window_size,               #int
"window_incr=i" => \$window_incr,               #int
"sequencefile=s" => \$sequencefile,             #file
"email=s" => \$email                             #String
);

if($sequencefile eq ""){
print "At least sequencefile must be given! (-sequencefile <filename>)";
exit 1;
}
my $sequence = readFile($sequencefile);
my @params = ("mode", SOAP::Data->type(string => $mode), "shape", SOAP::Data->type(int => $shape));

if(($energy!=-1)&&($energy_mode ne "")){
@params = (@params, "energy_mode", SOAP::Data->type(string => $energy_mode), 
"energy", SOAP::Data->type(double => $energy));
}

if($prob_number!=-1){
@params = (@params, "prob_number", SOAP::Data->type(int => $prob_number));
}

if($prob_cutoff!=-1){
@params = (@params, "prob_cutoff", SOAP::Data->type(double => $prob_cutoff));
}

if($prob_output!=-1){
@params = (@params, "prob_output", SOAP::Data->type(double => $prob_output));
}

if($sampling!=-1){
@params = (@params, "sampling", SOAP::Data->type(int => $sampling));
}

if($calc_struct_prob){
@params = (@params, "calc_struct_prob", SOAP::Data->type(boolean => $calc_struct_prob));
}

if($ignore_unstable){
@params = (@params, "ignore_unstable", SOAP::Data->type(boolean => $ignore_unstable));
}

if($match_shape ne ""){
@params =(@params, "match_shape", SOAP::Data->type(string => $match_shape));
}

if($window_size!=-1){
@params =(@params, "window_size", SOAP::Data->type(int => $window_size));
}

if($window_incr!=-1){
@params =(@params, "window_incr", SOAP::Data->type(int => $window_incr));
}

print "Submitting your request ...\n";
$result = SOAP::Lite->service($wsdlurl)
->on_fault(sub {soapFaultHandler(@_)})
->request_orig($email, $sequence, \@params);
print "got id: '$result'\n";


sub soapFaultHandler {
print "\n Error:\n";
my($soap, $res) = @_;

if (ref $res) {
print "Statuscode:".$res->faultcode."\n";
print "Description:".$res->faultstring."\n";
$detail = $res->faultdetail;

if(defined($detail->{"hobitStatuscode"})) {
print Dumper $detail->{"hobitStatuscode"}->{"statuscode"};
print Dumper $detail->{"hobitStatuscode"}->{"description"};
} else {
print "Sevlet Error - no Hobit Statuscode\n";
}
} else {
print "http layer Error: ";
print $soap->transport->status;
}
exit 1;
}


sub readFile{
my $file = shift;
my $content = "";
open(FILE, $file) or die("Cannot open file $file !");
foreach my $line (<FILE>){
$content .= $line;
}
close FILE;
return $content;
}

        

Example Client for the responseOrig method (Download Source):


#!/usr/bin/env perl 

use SOAP::Lite;
use Data::Dumper;
#production system
$wsdlurl = "http://bibiserv.techfak.uni-bielefeld.de/wsdl/RNAshapes.wsdl";
#test system
#$wsdlurl = "http://bibitest.techfak.uni-bielefeld.de/wsdl/RNAshapes.wsdl";

if(!defined $ARGV[0]) {
print "call with id\n";
exit 1;
}
print "Submitting your id... ";
$result = SOAP::Lite->service($wsdlurl)
->on_fault(sub {soapFaultHandler(@_)})
->response_orig($ARGV[0]);
print Dumper $result;


sub soapFaultHandler {
my($soap, $res) = @_;
if (ref $res) {
print "Statuscode:".$res->faultcode."\n";
print "Description:".$res->faultstring."\n";
$detail = $res->faultdetail;
print Dumper $detail->{"hobitStatuscode"}->{"statuscode"};
print Dumper $detail->{"hobitStatuscode"}->{"description"};
} else {
print "http layer Error: ";
print $soap->transport->status;
}
exit 1;
}
                

Example Java client

This Example Java client is based on Apache Axis (dependencies : Apache common and Xerces) and combines the methods request and response through active waiting (Download Source):

import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLClassLoader;
import java.rmi.RemoteException;
import javax.xml.namespace.QName;
import javax.xml.rpc.ServiceException;
import javax.xml.parsers.*;
import javax.xml.transform.*;
import javax.xml.transform.dom.*;
import javax.xml.transform.stream.*;
import org.apache.axis.AxisFault;
import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import org.apache.xerces.dom.DOMImplementationImpl;
import org.w3c.dom.*;
import org.xml.sax.*;
import java.io.*;
import java.util.*;

/**
 * @author Kai Loewenthal <kloewent@techfak.uni-bielefeld.de> 
 */
public class RNAshapesCRequestResponse {

     /** main method */
    public static void main(String[] args) {
  if(args.length < 1){
    System.err.println("You have to specify a SequenceML-file as argument!\n
    Usage : java RNAshapesCRequestResponse <filename>");
    System.exit(0);
  }
  
        try {
            /* wsdl location of rnahybrid ws */
            final URL wsdl = new URL(
                    "http://bibiserv.techfak.uni-bielefeld.de/wsdl/RNAshapes.wsdl");

      /* Creating DOM from the XML (ARGS[0]) */
      System.out.println("Opening xml file");
      File file = new File( args[0] );
      InputSource src = new InputSource( new FileInputStream( file ) );
      System.out.println("Building DOM from xml");
      org.apache.xerces.parsers.DOMParser prsr = new org.apache.xerces.parsers.DOMParser();
      prsr.parse( src );
      Document sequenceDoc = prsr.getDocument();
  
      /* sample parameter array */
      final Object[] parameter = { "mode", "a", "shape", new Integer(5),
                    "energy_mode", "e", "energy", new Double(2.3)};
            
      /* statuscode */
            int statuscode;
            
      /* statusdescription */
            String statusdescription;
            
      /* contains result of request */
            String result;
            
      /*
             * create a new Service Object reading RNAhybrid WSDL file and
             * according WSDL namespace
             */
            Service service = new Service(
                    wsdl,
                    new QName(
                            "http://bibiwsserv.techfak.uni-bielefeld.de//RNAshapes/axis/RNAshapesPort",
                            "RNAshapesImplementationService"));
            
      /* create a Call object using method "request" */
            Call call = (Call) service.createCall(new QName("RNAshapesPort"),
                    "request");
            
      /* call and get id */
            String id = (String) call.invoke(new Object[] { null, sequenceDoc,
                    parameter });
            
      /* print id to STDERR - for test purpose only */
            System.err.println("get ID :: " + id);
            
      /* set statuscode and description to 601,submitted */
            statuscode = 601;
            statusdescription = "submitted";
            
      /* create a Call object using method "response" */
            call = (Call) service.createCall(new QName("RNAshapesPort"),
                    "response");
            
            /*
             * implement a simple polling to get result of request; A statuscode
             * between 600 and 700 means that the job is still calculating; and
             * we have to try again
             */
            while ((statuscode > 600) && (statuscode < 700)) {
                try {
                    // print result to STDOUT
                    Document out = (Document) call.invoke(new Object[] { id });

                    /////////////////
                    //Output the XML

                    //set up a transformer
                    TransformerFactory transfac = TransformerFactory
                            .newInstance();
                    Transformer trans = transfac.newTransformer();
                    trans.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION,
                            "yes");
                    trans.setOutputProperty(OutputKeys.INDENT, "yes");

                    //create string from xml tree
                    StringWriter sw = new StringWriter();
                    StreamResult res = new StreamResult(sw);
                    DOMSource source = new DOMSource(out);
                    trans.transform(source, res);
                    String xmlString = sw.toString();

                    //print xml
                    System.out.println("Here's the xml:\n\n" + xmlString);

                    // set statuscode and description to finished
                    statuscode = 600;
                    statusdescription = "finished ok";
                } catch (RemoteException e) {
                    Object[] tmp = parseFault((AxisFault) e);
                    statuscode = ((Integer) tmp[0]).intValue();
                    statusdescription = (String) tmp[1];
                    // print a dot to STDERR and wait five seconds
                    System.err.println(statuscode + "(" + statusdescription
                            + ") polling...");
                    Thread.sleep(5000);
                } catch (Exception allother) {
                    allother.printStackTrace();
                }
            }
            /*
             * In the case an error occurred (statuscode >= 700) print
             * statuscode and description to STDERR
             */
            if (statuscode >= 700) {
                System.err.println("An error occurred calling RNAshapes WebService :");
                System.err.println("StatusCode :" + statuscode);
                System.err.println("Description :" + statusdescription);
            }
        } catch (MalformedURLException e) {
            System.err.println("A malformed URL Exception occurred:\n"
                    + e.getMessage());
        } catch (ServiceException e) {
            System.err.println("A Service Exception occurred:\n"
                    + e.getMessage());
        } catch (RemoteException e) {
            Object[] tmp = parseFault((AxisFault) e);
            System.err
                    .println("An error occurred calling RNAshapes WebService :");
            System.err.println("StatusCode :" + ((Integer) tmp[0]));
            System.err.println("Description :" + (String) tmp[1]);
        } catch (InterruptedException e) {
            System.err.println("A Interrupted Exception occurred:\n"
                    + e.getMessage());
        } catch (Exception e) {
      System.err.println("Some other exception occured:\n" 
        + e.getMessage());
  }
    }
    
    /** method, that provides parsing AxisFault */
    public static Object[] parseFault(AxisFault e) {
        Element root = e.lookupFaultDetail(new QName(
                "http://hobit.sourceforge.net/xsds/hobitStatuscode.xsd",
                "hobitStatuscode"));
        if (root == null) {
            System.err.println("WebService remote error \n\nmessage:\n"
                    + e.getMessage() + "\n\n");
            System.exit(1);
        }
        String description = root.getLastChild().getFirstChild().getNodeValue();
        Integer statuscode = new Integer(Integer.parseInt(root.getFirstChild()
                .getFirstChild().getNodeValue()));
        return new Object[] { statuscode, description };
    }
}
Welcome
Submission
WebService
References
Manual
Download
Contact
Fri May 3 15:04:54 2013