001// CandyVocabulary.java
002//
003//    senger@ebi.ac.uk
004//    February 2001
005//
006
007/*
008 *                    BioJava development code
009 *
010 * This code may be freely distributed and modified under the
011 * terms of the GNU Lesser General Public Licence.  This should
012 * be distributed with the code.  If you do not have a copy,
013 * see:
014 *
015 *      http://www.gnu.org/copyleft/lesser.html
016 *
017 * Copyright for this code is held jointly by the individual
018 * authors.  These should be listed in @author doc comments.
019 *
020 * For more information on the BioJava project and its aims,
021 * or to join the biojava-l mailing list, visit the home page
022 * at:
023 *
024 *      http://www.biojava.org/
025 *
026 */
027package org.biojava.utils.candy;
028
029import java.beans.PropertyChangeListener;
030import java.util.Enumeration;
031
032/**
033 * <p>
034 * This interface defines functionality of a controlled vocabulary.
035 * The implementation is supposed to behave as a Java bean
036 * (regarding accessing vocabulary properties).
037 * </p>
038 *
039 * <p>
040 * Each vocabulary consists of (usually many) vocabulary entries
041 * which are represented by {@link CandyEntry CandyEntries}.
042 * </p>
043 *
044 * @version $Id$
045 * @author Martin Senger
046 * @author Matthew Pocock
047 */
048
049public interface CandyVocabulary
050    extends PropertyChangeListener {
051
052    /*************************************************************************
053     * It checks if a given entry exists in this vocabulary.
054     *
055     * @param name of a vocabulary entry to be checked
056     * @return true if the given entry exists in this vocabulary
057     * @throws CandyException if the vocabulary is suddenly not available
058     *************************************************************************/
059    boolean contains (String name)
060        throws CandyException;
061
062    /*************************************************************************
063     * It returns a selected vocabulary entry.
064     *
065     * @see #getAllEntries getAllEntries
066     * @param name a name of a vocabulary entry to be looked up
067     * @return a vocabulary entry
068     * @throws CandyException when the given vocabulary entry does not exist
069     *************************************************************************/
070    CandyEntry getEntryByName (String name)
071        throws CandyException;
072
073    /*************************************************************************
074     * It returns all available vocabulary entries.
075     *
076     * @see #getEntryByName getEntryByName
077     * @return an Enumeration object containing all available entries
078     * @throws CandyException if the vocabulary is suddenly not available
079     *************************************************************************/
080    Enumeration getAllEntries()
081        throws CandyException;
082
083    /*************************************************************************
084     * It return all names (entry identifiers) available in this vocabulary.
085     *
086     * @return an Enumeration object containing all available names
087     * @throws CandyException if the vocabulary is suddenly not available
088     *************************************************************************/
089    Enumeration getAllNames()
090        throws CandyException;
091
092    /*************************************************************************
093     * It frees all resources related to this vocabulary.
094     *
095     * @throws CandyException if the vocabulary is suddenly not available
096     *************************************************************************/
097    void destroy()
098        throws CandyException;
099
100    /*************************************************************************
101     * 
102     *    P r o p e r t i e s
103     *
104     *************************************************************************/
105
106    //
107    // Property names
108    //
109
110    /** A property name. Its value is a name of this vocabulary. */
111    static final String PROP_VOCAB_NAME     = "vocab_name";
112
113    /** A property name. Its value is a short description of the whole vocabulary. */
114    static final String PROP_VOCAB_DESC     = "vocab_description";
115
116    /** A property name. Its value contains a version of this vocabulary. */
117    static final String PROP_VOCAB_VERSION  = "vocab_version";
118
119    /** A property name. Its boolean value is <tt>true</tt>
120     *  if the vocabulary entries names should be considered as case-sensitive.
121     */ 
122    static final String PROP_CASE_SENSITIVE = "vocab_case_sensitive";
123
124    /** A property name. Its value is a number of vocabulary entries
125     *  in this vocabulary.
126     */
127    static final String PROP_ENTRY_COUNT    = "entry_count";
128
129    /** A property name. Its type is {@link CandyVocabulary} and
130     *  it can be used to set an entire vocabulary.
131     *  An implementation may use it together with an empty
132     *  constructor.
133     */
134    static final String PROP_VOCABULARY     = "vocabulary";
135
136    //
137    // Property access methods
138    //
139
140    /** It returns a name of this vocabulary.
141     *  The name should be unique within a {@link CandyFinder}
142     *  instance who delivers this vocabulary.
143     */
144    String getName() throws CandyException;
145
146    /** It returns a description of this vocabulary. */
147    String getDescription() throws CandyException;
148
149    /** It returns a vesrion of this vocabulary. */
150    String getVersion() throws CandyException;
151
152    /** It returns a number of entries contained in this vocabulary. */
153    int getCount() throws CandyException;
154
155    /** It returns <tt>true</tt> if the vocabulary entries should
156     *  be considered as case-sensitive.
157     */
158    boolean isCaseSensitive() throws CandyException;
159
160    /**
161     * <p>
162     * A property name.
163     * </p>
164     *
165     * <p>
166     * An implementation may use this boolean property to make sure that
167     * returned vocabulary entries are in the same order as they were
168     * read from its original source.
169     * </p>
170     */
171    static final String CANDIES_NOT_SORTED = "candies_not_sorted";
172
173}