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.biojavax.bio.taxa.io;
023
024import java.io.BufferedReader;
025import java.io.IOException;
026
027import org.biojava.bio.seq.io.ParseException;
028import org.biojavax.bio.taxa.NCBITaxon;
029
030/**
031 * Implementors are able to load taxonomy files and generate sets of NCBITaxon objects
032 * that represent them. Taxon objects should be generated using RichObjectFactory.
033 * @author Richard Holland
034 * @since 1.5
035 */
036public interface NCBITaxonomyLoader {
037    
038    /**
039     * Reads the next entry from the nodes.dmp file and returns the corresponding 
040     * NCBITaxon object.
041     * @param nodes something that reads the nodes.dmp file
042     * @return the next NCBITaxon object in the file, or null if the file has ended.
043     */
044    public NCBITaxon readNode(BufferedReader nodes) throws IOException, ParseException;
045    
046    /**
047     * Reads the next entry from the names.dmp file and returns the corresponding 
048     * NCBITaxon object with the name added in already. Note that this does not clear
049     * out existing names from the taxon, it only adds them. Use the code snippet
050     * below if you want to clear out the names first:
051     * <code>
052     * for (Iterator i = taxon.getNameClasses().iterator(); i.hasNext(); ) {
053     *      taxon.getNames((String)i.next()).clear();
054     * }
055     * </code>
056     * @param names something that reads the names.dmp file
057     * @return the NCBITaxon object corresponding to the next entry in the file, 
058     * or null if the file has ended.
059     */
060    public NCBITaxon readName(BufferedReader names) throws IOException, ParseException;
061}