001/**
002 * Copyright (C) 2010-2015 The Roslin Institute <contact andy.law@roslin.ed.ac.uk>
003 *
004 * This file is part of JEnsembl: a Java API to Ensembl data sources developed by the
005 * Bioinformatics Group at The Roslin Institute, The Royal (Dick) School of
006 * Veterinary Studies, University of Edinburgh.
007 *
008 * Project hosted at: http://jensembl.sourceforge.net
009 *
010 * This is free software: you can redistribute it and/or modify
011 * it under the terms of the GNU General Public License (version 3) as published by
012 * the Free Software Foundation.
013 *
014 * This software is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
017 * GNU General Public License for more details.
018 *
019 * You should have received a copy of the GNU General Public License
020 * in this software distribution. If not, see: http://opensource.org/licenses/gpl-3.0.html
021 */
022package uk.ac.roslin.ensembl.dao.compara;
023
024import java.util.HashMap;
025import java.util.List;
026import uk.ac.roslin.ensembl.exception.DAOException;
027import uk.ac.roslin.ensembl.model.Coordinate;
028import uk.ac.roslin.ensembl.model.MappingSet;
029import uk.ac.roslin.ensembl.model.compara.HomologyPairRelationship;
030import uk.ac.roslin.ensembl.model.core.DNASequence;
031import uk.ac.roslin.ensembl.model.core.Gene;
032import uk.ac.roslin.ensembl.model.core.Species;
033
034public interface HomologyDAO {
035
036    /**
037     * Specification of Data Access method to retrieve all of the homologies
038     * (i.e. to all species) for a given gene with a stableID.
039     * @param g The query Gene
040     * @return List of HomologyPairRelationships
041     * @throws DAOException 
042     */
043    public List<? extends HomologyPairRelationship>
044            getHomologiesForGene(Gene g) throws DAOException;
045
046    /**
047     * Specification of Data Access method to retrieve all of the homologies
048     * in the specified target species for a List of genes with stableIDs. The
049     * query may be restricted by specifying a target chromosome Name (In effect a filter 
050     * on the full query, for efficiency where the target chromosome is already known.        
051     * @param genes theList of query genes
052     * @param target_sp The target Species
053     * @param chrName The target chromosome name
054     * @return List of HomologyPairRelationships
055     * @throws DAOException 
056     */
057    public List<? extends HomologyPairRelationship> 
058            getHomologiesForGenesBySpecies(List<? extends Gene> genes, Species target_sp, String chrName) throws DAOException;
059
060   /**
061    * Specification of Data Access method to retrieve all of the regions on DNASequences
062    * for the specified target species, holding genes with homologies to genes found
063    * in the given region of the source query sequence. 
064    * @param source DNASequence to be queried
065    * @param range Coordinate range of query sequence to be queried
066    * @param target the target species
067    * @return HashMap of Syntenic regions against the set of Mappings holding homologous genes
068    * @throws DAOException 
069    */
070    public HashMap<? extends DNASequence, ? extends MappingSet>
071            getRegionsOfConservedSynteny(DNASequence source, Coordinate range, Species target) throws DAOException;
072    
073   /**
074    * Specification of Data Access method to retrieve any potential region of 
075    * conserved synteny on a given Chromosome/fragment 
076    * for the specified target species, holding genes with homologies to genes found
077    * in the given region of the source query sequence. In effect a filter 
078    * on the full query, for efficiency where the target chromosome is already known.  
079    * @param source DNASequence to be queried
080    * @param range Coordinate range of query sequence to be queried
081    * @param target the target species
082    * @param chrName the target chromosome name
083    * @return HashMap of Syntenic regions against the set of Mappings holding homologous genes
084    * @throws DAOException 
085    */
086    public HashMap<? extends DNASequence, ? extends MappingSet>
087            getRegionsOfConservedSynteny(DNASequence source, Coordinate range, Species target, String chrName) throws DAOException;
088    
089}