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.

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.

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;
}
                

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 };
    }
}