001// CandyFinder.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;
030
031/**
032 * <p>
033 * This interface is a main entry point to a set of controlled
034 * vocabularies.
035 * </p>
036 *
037 * <p>
038 * The implementation is supposed to behave as a Java bean (usually an
039 * invisible bean unless it implements some additional GUI methods
040 * which are not defined in this interface).
041 * </p>
042 *
043 * @author <A HREF="mailto:senger@ebi.ac.uk">Martin Senger</A>
044 * @author Matthew Pocock
045 * @version $Id$
046 */
047
048public interface CandyFinder
049    extends PropertyChangeListener {
050
051    /**************************************************************************
052     * <p>
053     * It creates a connection to an object representing a vocabulary
054     * finder, or/and it makes all necessary initialization steps
055     * needed for further communication.
056     * </p>
057     *
058     * <p>
059     * However, there should be no need to call this method
060     * explicitly, the other methods should do it automatically before
061     * they need to use the finder.
062     * </p>
063     *
064     * @throws CandyException if the connection/initialization cannot
065     *         be established
066     *************************************************************************/
067    void connect() throws CandyException;
068
069    /**************************************************************************
070     * It checks if a vocabulary finder object is available. The semantic of 
071     * <em>available</em>depends on the implementation.
072     *************************************************************************/
073    boolean isReady();
074
075    /**************************************************************************
076     * It closes connection with the finder object. Implementations may
077     * choose to use this method for freeing resources.
078     *************************************************************************/
079    void disconnect();
080
081    /*************************************************************************
082     * <p>
083     * It returns names of all vocabularies known to this vocabulary
084     * finder. Any of the returned names can be later used in the method
085     * {@link #getVocabularyByName getVocabularyByName}.
086     * </p>
087     *
088     * @return a list of available vocabulary names
089     * @throws CandyException if the finder fails to communicate
090     *         with its vocabularies
091     *************************************************************************/
092    String[] getAllVocabularyNames() throws CandyException;
093
094    /*************************************************************************
095     * It returns a selected vocabulary.
096     *
097     * @see #getAllVocabularyNames
098     * @param name a name of a vocabulary to be returned
099     * @return a selected vocabulary
100     * @throws CandyException when the vocabulary cannot be found (likely the
101     *         given name is wrong)
102     *************************************************************************/
103    CandyVocabulary getVocabularyByName (String name)
104      throws CandyException;
105
106    /*************************************************************************
107     * It returns all available vocabularies.
108     *
109     * @return all available vocabularies
110     * @throws CandyException if the finder fails to communicate
111     *         with its vocabularies
112     *************************************************************************/
113    CandyVocabulary[] getAllVocabularies() throws CandyException;
114
115    /*************************************************************************
116     * It returns the number of available vocabularies.
117     *
118     * @throws CandyException if the finder fails to communicate
119     *         with its vocabularies
120     *************************************************************************/
121    int getNumCount() throws CandyException;
122
123    /*************************************************************************
124     * 
125     *    P r o p e r t i e s
126     *
127     *************************************************************************/
128
129    /** A default name of this (and any) finder.
130     *  It is used when no other name was given by the finder
131     *  implementation.
132     */
133    static final String DEFAULT_FINDER_NAME = "Default vocabulary finder";
134
135    //
136    // Property names
137    //
138
139    /**
140     * <p>
141     * A property name.
142     * </p>
143     *
144     * <p>
145     * Its value is of type {@link CandyVocabulary}.
146     * It this property is set a given vocabulary becomes part of
147     * this finder.
148     * </p>
149     */
150    static final String PROP_VOCABULARY = CandyVocabulary.PROP_VOCABULARY;
151
152    //
153    // Property access methods
154    //
155
156    /*************************************************************************
157     * It returns a name of this vocabulary finder.
158     *
159     * @throws CandyException if the finder fails to return its name
160     *************************************************************************/
161    String getFinderName() throws CandyException;
162
163}