package jalview.api;

import jalview.datamodel.Mapping;

//JBPComment: this is a datamodel API - so it should be in datamodel (it's a peer of SequenceI)

public interface DBRefEntryI
{
  public boolean equalRef(DBRefEntryI entry);

  /**
   * 
   * @return Source DB name for this entry
   */
  public String getSource();

  /**
   * 
   * @return Accession Id for this entry
   */
  public String getAccessionId();

  /**
   * 
   * @param accessionId
   *          Accession Id for this entry
   */
  public void setAccessionId(String accessionId);

  /**
   * 
   * @param source
   *          Source DB name for this entry
   */
  public void setSource(String source);

  /**
   * 
   * @return Source DB version for this entry
   */
  public String getVersion();

  /**
   * 
   * @param version
   *          Source DB version for this entry
   */
  public void setVersion(String version);

  /**
   * 
   * @param startRes
   *          index of start residue in the source DB
   */
  public void setStartRes(int startRes);

  /**
   * 
   * @return index of start residue in the source DB
   */
  public int getStartRes();

  /**
   * 
   * @param endRes
   *          index of end residue in the source DB
   */
  public void setEndRes(int endRes);

  /**
   * 
   * @return index of end residue in the source DB
   */
  public int getEndRes();

  /**
   * access a mapping, if present that can be used to map positions from the
   * associated dataset sequence to the DBRef's sequence frame.
   * 
   * @return null or a valid mapping.
   */
  public Mapping getMap();

  /**
   * Answers true if this object is either equivalent to, or can be 'improved'
   * by, the given entry. Specifically, answers true if
   * <ul>
   * <li>source and accession are identical</li>
   * <li>version is identical, or this version is of the format "someSource:0",
   * in which case the version for the other entry replaces it</li>
   * <li>mappings are not compared but if this entry has no mapping, replace
   * with that for the other entry</li>
   * </ul>
   * 
   * @param otherEntry
   * @return
   */
  public boolean updateFrom(DBRefEntryI otherEntry);
}