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 */
021
022package org.biojava.nbio.core.sequence.features;
023
024import java.util.List;
025import java.util.Map;
026
027import org.biojava.nbio.core.sequence.location.template.AbstractLocation;
028import org.biojava.nbio.core.sequence.template.AbstractSequence;
029import org.biojava.nbio.core.sequence.template.Compound;
030
031/**
032 * Interface class to handle describing arbitrary features. A feature can be found at multiple locations in a sequence such as
033 * the surface of a protein where different sequence positions make up that feature. Ligand binding pocket is another example.
034 * The location in its current form knows the start and stop position in a sequence and thus should contain knowledge about the
035 * actual sequence.
036 * <p>
037 * A feature can contain features to handle cases where a domain is a feature and the secondary structures covered by that domain
038 * and other requirements for grouping.
039 *
040 * @author Scooter Willis 
041 * @author Paolo Pavan
042 */
043public interface FeatureInterface<S extends AbstractSequence<C>, C extends Compound> {
044
045        /**
046         * Get the short description that can be used to describe the feature
047         * @return
048         */
049        String getShortDescription();
050
051        /**
052         * Set the short description that can be used to describe the feature
053         * @param shortDescription
054         */
055        void setShortDescription(String shortDescription);
056
057         /**
058         * Get the description that can be used to describe the feature
059         * @return
060         */
061        String getDescription();
062
063         /**
064         * Set the description that can be used to describe the feature
065         */
066        void setDescription(String description);
067
068        /**
069         * The location(s) of this feature where the location should contain a reference to parent and sequence etc.
070         * <p>
071         * The location may be complicated, or simply a range.
072         * The annotation is assumed to apply to all the region contained
073         * within the location.
074         *
075         * @return a Location anchoring this feature
076         */
077        AbstractLocation getLocations();
078
079                /**
080         * The new location for this feature.
081         * <p>
082         * The location may be complicated or simply a range. The annotation is
083         * assumed to apply to the entire region contained within the location.
084         * Any values returned from methods that rely on the old location must
085         * not be affected.
086         *
087         * @param loc the new Location for this feature
088         *
089         */
090        void setLocation(AbstractLocation loc);
091
092        /**
093         * The type of the feature.
094         *
095         * @return the type of this sequence
096         */
097        String getType();
098
099        /**
100         * Change the type of this feature.
101         *
102         * @param type  new type String
103         *
104         */
105        void setType(String type);
106
107
108        /**
109         * The source of the feature. This may be a program or process.
110         *
111         * @return the source, or generator
112         */
113        String getSource();
114
115        /**
116         * Change the source of the FeatureInterface.
117         *
118         * @param source the new source String
119         *
120         */
121        void setSource(String source);
122
123        /**
124         * Set the parent feature
125         * @param feature
126         */
127        void setParentFeature(FeatureInterface<S, C> feature);
128
129        /**
130         * Get the parent feature
131         * @return
132         */
133        FeatureInterface<S, C> getParentFeature();
134
135        /**
136         * Get the features contained by this feature
137         * @return
138         */
139        List<FeatureInterface<S, C>> getChildrenFeatures();
140
141        /**
142         * Set the children features
143         * @param features
144         */
145        void setChildrenFeatures(List<FeatureInterface<S, C>> features);
146
147
148        /**
149         * @return the userObject
150         */
151        Object getUserObject();
152
153        /**
154         * @param userObject the userObject to set
155         */
156        void setUserObject(Object userObject);
157
158        /**
159         * Get the qualifiers for this feature
160         * @return
161         */
162
163        Map<String, List<Qualifier>> getQualifiers();
164
165        /**
166         * Set the qualifiers
167         * @param qualifiers
168         */
169        void setQualifiers(Map<String, List<Qualifier>> qualifiers);
170
171        /**
172         * Add a qualifier
173         * @param qualifier
174         */
175        void addQualifier(String key, Qualifier qualifier);
176
177}