org.biojava3.ws.alignment.qblast
Class NCBIQBlastService

java.lang.Object
  extended by org.biojava3.ws.alignment.qblast.NCBIQBlastService
All Implemented Interfaces:
RemotePairwiseAlignmentService

public class NCBIQBlastService
extends Object
implements RemotePairwiseAlignmentService

Provides a simple way of submitting BLAST request to the QBlast service at NCBI.

NCBI provides a Blast server through a CGI-BIN interface. This service simply encapsulates an access to it by giving users access to get/set methods to fix sequence, program and database as well as advanced options.

The philosophy behind this service is to disconnect submission of Blast requests from collection of Blast results. This is done so to allow a user to submit multiple Blast requests while allowing recovery of the reports at a later time.

Presently, only blastall programs are accessible.

Author:
Sylvain Foisy, Diploide BioIT, Gediminas Rimsa

Field Summary
static long WAIT_INCREMENT
          Number of milliseconds by which expected job execution time is incremented if it is not finished yet.
 
Constructor Summary
NCBIQBlastService()
           
 
Method Summary
 InputStream getAlignmentResults(String id, RemotePairwiseAlignmentOutputProperties outputProperties)
          Extracts the actual Blast report for given request id according to options provided in outputProperties argument.
 String getEmail()
          Get the email for QBlast.
 String getRemoteBlastInfo()
          A simple method to check the availability of the QBlast service.
 String getTool()
          Get the tool identifier for QBlast.
 boolean isReady(String id)
          Wrapper method for isReady(String, long), omitting unnecessary present property.
 boolean isReady(String id, long present)
          Checks for completion of request.
 String sendAlignmentRequest(int gid, RemotePairwiseAlignmentProperties rpa)
          Converts given GenBank GID to String and calls sendAlignmentRequest(String, RemotePairwiseAlignmentProperties)
 String sendAlignmentRequest(Sequence<Compound> seq, RemotePairwiseAlignmentProperties rpa)
          Converts given sequence to String and calls sendAlignmentRequest(String, RemotePairwiseAlignmentProperties)
 String sendAlignmentRequest(String query, RemotePairwiseAlignmentProperties alignmentProperties)
          Sends the Blast request via the Put command of the CGI-BIN interface.
 void sendDeleteRequest(String id)
          Sends a delete request for given request id.
 void setEmail(String email)
          Set the email for QBlast.
 void setTool(String tool)
          Set the tool identifier for QBlast.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

WAIT_INCREMENT

public static final long WAIT_INCREMENT
Number of milliseconds by which expected job execution time is incremented if it is not finished yet. Subsequent calls to isReady(String, long) method will return false until at least this much time passes.

See Also:
Constant Field Values
Constructor Detail

NCBIQBlastService

public NCBIQBlastService()
Method Detail

getRemoteBlastInfo

public String getRemoteBlastInfo()
                          throws Exception
A simple method to check the availability of the QBlast service. Sends Info command to QBlast

Returns:
QBlast info output concatenated to String
Throws:
Exception - if unable to connect to the NCBI QBlast service

sendAlignmentRequest

public String sendAlignmentRequest(Sequence<Compound> seq,
                                   RemotePairwiseAlignmentProperties rpa)
                            throws Exception
Converts given sequence to String and calls sendAlignmentRequest(String, RemotePairwiseAlignmentProperties)

Specified by:
sendAlignmentRequest in interface RemotePairwiseAlignmentService
Throws:
Exception

sendAlignmentRequest

public String sendAlignmentRequest(int gid,
                                   RemotePairwiseAlignmentProperties rpa)
                            throws Exception
Converts given GenBank GID to String and calls sendAlignmentRequest(String, RemotePairwiseAlignmentProperties)

Throws:
Exception

sendAlignmentRequest

public String sendAlignmentRequest(String query,
                                   RemotePairwiseAlignmentProperties alignmentProperties)
                            throws Exception
Sends the Blast request via the Put command of the CGI-BIN interface. Uses all of the parameters specified in alignmentProperties (parameters PROGRAM and DATABASE are required).

Specified by:
sendAlignmentRequest in interface RemotePairwiseAlignmentService
Parameters:
query - : a String representing a sequence or Genbank ID
alignmentProperties - : a RemotePairwiseAlignmentProperties object representing alignment properties
Returns:
the request id for this sequence, necessary to fetch results after completion
Throws:
Exception - if unable to connect to the NCBI QBlast service or if no sequence or required parameters PROGRAM and DATABASE are not set

isReady

public boolean isReady(String id)
                throws Exception
Wrapper method for isReady(String, long), omitting unnecessary present property.

Throws:
Exception
See Also:
isReady(String, long)

isReady

public boolean isReady(String id,
                       long present)
                throws Exception
Checks for completion of request.

If expected execution time (RTOE) is available for request, this method will always return false until that time passes. This is done to prevent sending unnecessary requests to the server.

Specified by:
isReady in interface RemotePairwiseAlignmentService
Parameters:
id - : request id, which was returned by sendAlignmentRequest method
present - : is not used, can be any value
Returns:
a boolean value telling if the request has been completed
Throws:
Exception - if the ID does not exist.

getAlignmentResults

public InputStream getAlignmentResults(String id,
                                       RemotePairwiseAlignmentOutputProperties outputProperties)
                                throws Exception
Extracts the actual Blast report for given request id according to options provided in outputProperties argument.

If the results are not ready yet, sleeps until they are available. If sleeping is not desired, call this method after isReady returns true

Specified by:
getAlignmentResults in interface RemotePairwiseAlignmentService
Parameters:
id - : request id, which was returned by sendAlignmentRequest method
outputProperties - : an object specifying output formatting options
Returns:
an InputStream of results
Throws:
Exception - if it is not possible to recover the results

sendDeleteRequest

public void sendDeleteRequest(String id)
Sends a delete request for given request id. Optional operation, ignores IOExceptions.
Can be used after results of given search are no longer needed to be kept on Blast server

Parameters:
id - request id, as returned by sendAlignmentRequest method

setTool

public void setTool(String tool)
Set the tool identifier for QBlast. Defaults to

Parameters:
tool - the new identifier

getTool

public String getTool()
Get the tool identifier for QBlast. Defaults to

Returns:
the identifier

setEmail

public void setEmail(String email)
Set the email for QBlast. Defaults to

Parameters:
email - the new email

getEmail

public String getEmail()
Get the email for QBlast. Defaults to .

Returns:
the email