001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021package org.biojavax.bio.alignment;
022
023import java.io.InputStream;
024
025import org.biojava.bio.BioException;
026import org.biojavax.bio.seq.RichSequence;
027
028/**
029 * This interface specifies minimal information needed to execute a pairwise alignment on a remote service.
030 * 
031 * Example of service: QBlast service at NCBI
032 *                     Web Service at EBI
033 * 
034 * @author Sylvain Foisy
035 * @since 1.8
036 *
037 */
038public interface RemotePairwiseAlignmentService {
039
040        /**
041         * Doing the actual analysis on the instantiated service using specified parameters and the RichSequence object
042         * 
043         * @throws BioException
044         */
045        public String sendAlignmentRequest(RichSequence rs, RemotePairwiseAlignmentProperties rpa) throws BioException;
046        
047        /**
048         * Doing the actual analysis on the instantiated service using specified parameters on the string representation
049         * of the Sequence object
050         * 
051         * @throws BioException
052         */
053        public String sendAlignmentRequest(String str, RemotePairwiseAlignmentProperties rpa) throws BioException;
054        
055        /**
056         * Simple method to check if the specified request has been completed by the service used.
057         * 
058         * @param id :an ID for an alignment request 
059         * @param present :a long integer value representing the actual time  
060         * @return a boolean value telling if this requestID has been completed or not.
061         * @throws BioException if the ID does not exist.
062         */
063        public boolean isReady(String id,long present) throws BioException;
064        
065        /**
066         * Getting the actual alignment results from this instantiated service for a given ID with specific
067         * formatting parameters held in a RemotePairwiseAlignmentOutputProperties-implemented object. 
068         * 
069         * @param rid :a String with the request ID for this single alignment run
070         * @param out :a RemotePairwiseAlignmentOutputProperties with the specific output instructions.
071         * @return : an <code>InputStream</code> with the actual alignment results
072         * @throws BioException
073         */
074        public InputStream getAlignmentResults(String rid,RemotePairwiseAlignmentOutputProperties out) throws BioException;
075}