Package org.biojava.nbio.ws.alignment.qblast

Class NCBIQBlastService

java.lang.Object

org.biojava.nbio.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

Fields

Modifier and Type	Field	Description
static long	WAIT_INCREMENT	Number of milliseconds by which expected job execution time is incremented if it is not finished yet.

Constructor Summary

Constructors

Constructor	Description
NCBIQBlastService()	Constructs a service object that targets the public NCBI BLAST network service.
NCBIQBlastService(String svcUrl)	Constructs a service object which targets a custom NCBI BLAST network service (e.g.: an instance of BLAST in the cloud).

Method Summary

Modifier and Type	Method	Description
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(String query, RemotePairwiseAlignmentProperties alignmentProperties)	Sends the Blast request via the Put command of the CGI-BIN interface.
String	sendAlignmentRequest(Sequence<Compound> seq, RemotePairwiseAlignmentProperties rpa)	Converts given sequence to String and calls sendAlignmentRequest(String, RemotePairwiseAlignmentProperties)
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()

Constructs a service object that targets the public NCBI BLAST network service.

NCBIQBlastService

public NCBIQBlastService(String svcUrl)

Constructs a service object which targets a custom NCBI BLAST network service (e.g.: an instance of BLAST in the cloud).

Parameters:

svcUrl - : a String containing the base URL to send requests to, e.g.: http://host.my.cloud.service.provider.com/cgi-bin/blast.cgi

See Also:

BLAST on the cloud documentation

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 "biojava5"

Parameters:

tool - the new identifier

getTool

public String getTool()

Get the tool identifier for QBlast. Defaults to "biojava5"

Returns:

the identifier

setEmail

public void setEmail(String email)

Set the email for QBlast. Defaults to "anonymous@biojava.org"

Parameters:

email - the new email

getEmail

public String getEmail()

Get the email for QBlast. Defaults to "anonymous@biojava.org".

Returns:

the email