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.biojava.nbio.structure.scop;
022
023import java.util.List;
024
025/** General API how to interact with SCOP
026 *
027 * @author Andreas Prlic
028 * @since 3.0.2
029 * @see LocalScopDatabase
030 */
031public interface ScopDatabase {
032
033        /** Get all records of a particular classification.
034         *
035         * @param category e.g. "superfamily"
036         * @return all records of this type
037         */
038        public abstract List<ScopDescription> getByCategory(ScopCategory category);
039
040        /** Get all scop descriptions that start with a classification ID, e.g. b.1.18
041         *
042         * @param query
043         * @return list of scop descriptions
044         */
045        public abstract List<ScopDescription> filterByClassificationId(String query);
046
047        /** get the SCOP sub-tree for a particular domain.
048         *
049         * @param domain
050         * @return list of ScopNodes providing the path to this domain
051         */
052        public abstract List<ScopNode> getTree(ScopDomain domain);
053
054
055        /** search through SCOP and filter based on domain name
056         *
057         * @param query a (part) of a name
058         * @return list of matchin ScopDomains
059         */
060        public abstract List<ScopDomain> filterByDomainName(String query);
061
062        /** Get all scop descriptions that start with a certain name. e.g. Globin
063         *
064         * @param query
065         * @return list of scop descriptions
066         */
067        public abstract List<ScopDescription> filterByDescription(String query);
068
069        /** Return the SCOP description for a node in the hierarchy by its "sunid" id.
070         *
071         * @param sunid
072         * @return a ScopDescription object
073         */
074        public abstract ScopDescription getScopDescriptionBySunid(int sunid);
075
076        /** Get a list of ScopDomains that have been assigned to a PDB ID
077         *
078         * @param pdbId the PDB entry
079         * @return a list of ScopDomains
080         */
081        public abstract List<ScopDomain> getDomainsForPDB(String pdbId);
082
083        /** get a ScopDomain by its SCOP ID (warning, they are not stable between releases!)
084         *
085         *
086         * @param scopId e.g. d2bq6a1
087         * @return a ScopDomain or null if no domain with the particular ID could be found
088         */
089        public abstract ScopDomain getDomainByScopID(String scopId);
090
091        /** Access a particular ScopNode. The scopNode then allows to traverse through the scop hierarchy...
092         *
093         * @param sunid the scop unique id
094         * @return a ScopNode that matches this sunid
095         */
096        public abstract ScopNode getScopNode(int sunid);
097
098        /** Returns the SCOP version
099         *
100         * @return version of SCOP
101         */
102
103        public abstract String getScopVersion();
104
105        /**
106         * Sets the scop version used.
107         * @param version
108         * @throws UnsupportedOperationException If the version cannot be changed
109         */
110        public abstract void setScopVersion(String version);
111
112        /** Get a SCOP domain by its sunid
113         *
114         * @param sunid the scop unique id
115         * @return a list of scop domains that match this sunid
116         */
117        public abstract List<ScopDomain> getScopDomainsBySunid(Integer sunid);
118
119        /**
120         * Get comments about a SCOP domain by its sunid
121         * @param sunid
122         * @return
123         */
124        public abstract List<String> getComments(int sunid);
125}