package jalview.ws2.actions.annotation;

import java.io.IOException;
import java.util.List;
import java.util.Map;

import jalview.api.FeatureColourI;
import jalview.datamodel.AlignmentAnnotation;
import jalview.datamodel.SequenceI;
import jalview.datamodel.features.FeatureMatcherSetI;
import jalview.ws2.api.WebServiceJobHandle;
import jalview.ws2.client.api.AnnotationWebServiceClientI;
import jalview.ws2.client.api.WebServiceClientI;

/**
 * An interface for providing annotation results to the annotation services. It
 * declares a method to attach annotations fetched from the server to sequences.
 * Web service clients wanting to support annotation acitons must implement this
 * interface in addition to {@link WebServiceClientI}
 * 
 * @author mmwarowny
 *
 * @see AnnotationWebServiceClientI
 */
public interface AnnotationProviderI
{
  /**
   * Retrieves annotations from the job result on the server and attaches them
   * to provided sequences. Additionally, adds feature colours and filters to
   * provided containers.
   * 
   * @param job
   *          web service job
   * @param sequences
   *          features and alignment annotation added to these will be
   *          imported to the dataset for the alignment
   * @param colours
   *          container for feature colours
   * @param filters
   *          container for feature filters
   * @return sequence and alignment annotation rows that should be made
   *         visible/updated on alignment
   * @throws IOException
   *           annotation retrieval failed
   */
  public List<AlignmentAnnotation> attachAnnotations(WebServiceJobHandle job,
      List<SequenceI> sequences, Map<String, FeatureColourI> colours,
      Map<String, FeatureMatcherSetI> filters) throws IOException;
}