Class NCBIQBlastService

  • All Implemented Interfaces:
    RemotePairwiseAlignmentService

    public class NCBIQBlastService
    extends java.lang.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 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​(java.lang.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 java.lang.String getRemoteBlastInfo()
                                            throws java.lang.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:
        java.lang.Exception - if unable to connect to the NCBI QBlast service
      • sendAlignmentRequest

        public java.lang.String sendAlignmentRequest​(java.lang.String query,
                                                     RemotePairwiseAlignmentProperties alignmentProperties)
                                              throws java.lang.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:
        java.lang.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​(java.lang.String id)
                        throws java.lang.Exception
        Wrapper method for isReady(String, long), omitting unnecessary present property.
        Throws:
        java.lang.Exception
        See Also:
        isReady(String, long)
      • isReady

        public boolean isReady​(java.lang.String id,
                               long present)
                        throws java.lang.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:
        java.lang.Exception - if the ID does not exist.
      • getAlignmentResults

        public java.io.InputStream getAlignmentResults​(java.lang.String id,
                                                       RemotePairwiseAlignmentOutputProperties outputProperties)
                                                throws java.lang.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:
        java.lang.Exception - if it is not possible to recover the results
      • sendDeleteRequest

        public void sendDeleteRequest​(java.lang.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​(java.lang.String tool)
        Set the tool identifier for QBlast. Defaults to "biojava5"
        Parameters:
        tool - the new identifier
      • getTool

        public java.lang.String getTool()
        Get the tool identifier for QBlast. Defaults to "biojava5"
        Returns:
        the identifier
      • setEmail

        public void setEmail​(java.lang.String email)
        Set the email for QBlast. Defaults to "anonymous@biojava.org"
        Parameters:
        email - the new email
      • getEmail

        public java.lang.String getEmail()
        Get the email for QBlast. Defaults to "anonymous@biojava.org".
        Returns:
        the email