/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 */
package org.biojava.nbio.structure.scop;

import java.util.List;

/** General API how to interact with SCOP
 *
 * @author Andreas Prlic
 * @since 3.0.2
 * @see LocalScopDatabase
 */
public interface ScopDatabase {

	/** Get all records of a particular classification.
	 *
	 * @param category e.g. "superfamily"
	 * @return all records of this type
	 */
	public abstract List<ScopDescription> getByCategory(ScopCategory category);

	/** Get all scop descriptions that start with a classification ID, e.g. b.1.18
	 *
	 * @param query
	 * @return list of scop descriptions
	 */
	public abstract List<ScopDescription> filterByClassificationId(String query);

	/** get the SCOP sub-tree for a particular domain.
	 *
	 * @param domain
	 * @return list of ScopNodes providing the path to this domain
	 */
	public abstract List<ScopNode> getTree(ScopDomain domain);


	/** search through SCOP and filter based on domain name
	 *
	 * @param query a (part) of a name
	 * @return list of matchin ScopDomains
	 */
	public abstract List<ScopDomain> filterByDomainName(String query);

	/** Get all scop descriptions that start with a certain name. e.g. Globin
	 *
	 * @param query
	 * @return list of scop descriptions
	 */
	public abstract List<ScopDescription> filterByDescription(String query);

	/** Return the SCOP description for a node in the hierarchy by its "sunid" id.
	 *
	 * @param sunid
	 * @return a ScopDescription object
	 */
	public abstract ScopDescription getScopDescriptionBySunid(int sunid);

	/** Get a list of ScopDomains that have been assigned to a PDB ID
	 *
	 * @param pdbId the PDB entry
	 * @return a list of ScopDomains
	 */
	public abstract List<ScopDomain> getDomainsForPDB(String pdbId);

	/** get a ScopDomain by its SCOP ID (warning, they are not stable between releases!)
	 *
	 *
	 * @param scopId e.g. d2bq6a1
	 * @return a ScopDomain or null if no domain with the particular ID could be found
	 */
	public abstract ScopDomain getDomainByScopID(String scopId);

	/** Access a particular ScopNode. The scopNode then allows to traverse through the scop hierarchy...
	 *
	 * @param sunid the scop unique id
	 * @return a ScopNode that matches this sunid
	 */
	public abstract ScopNode getScopNode(int sunid);

	/** Returns the SCOP version
	 *
	 * @return version of SCOP
	 */

	public abstract String getScopVersion();

	/**
	 * Sets the scop version used.
	 * @param version
	 * @throws UnsupportedOperationException If the version cannot be changed
	 */
	public abstract void setScopVersion(String version);

	/** Get a SCOP domain by its sunid
	 *
	 * @param sunid the scop unique id
	 * @return a list of scop domains that match this sunid
	 */
	public abstract List<ScopDomain> getScopDomainsBySunid(Integer sunid);

	/**
	 * Get comments about a SCOP domain by its sunid
	 * @param sunid
	 * @return
	 */
	public abstract List<String> getComments(int sunid);
}