cdmlib-model/src/main/java/eu/etaxonomy/cdm/strategy/parser/INonViralNameParser.java

   1 /**
   2 * Copyright (C) 2009 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9
  10 package eu.etaxonomy.cdm.strategy.parser;
  11
  12 import eu.etaxonomy.cdm.model.name.NomenclaturalCode;
  13 import eu.etaxonomy.cdm.model.name.NonViralName;
  14 import eu.etaxonomy.cdm.model.name.Rank;
  15 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  16 import eu.etaxonomy.cdm.strategy.IStrategy;
  17 import eu.etaxonomy.cdm.strategy.exceptions.StringNotParsableException;
  18
  19
  20 /**
  21  * Supplies several parser methods for non viral taxon name strings and for nomenclatural
  22  * reference strings. If the parser method for taxon names is not successful
  23  * the {@link eu.etaxonomy.cdm.model.name.TaxonNameBase#getHasProblem() hasProblem} flag
  24  * of the {@link eu.etaxonomy.cdm.model.name.TaxonNameBase TaxonNameBase} instance will be set.
  25  * Some of the parser methods for taxon names create also a TaxonNameBase
  26  * instance while other ones only fill the result into an existing
  27  * TaxonNameBase instance.
  28  *
  29  * @author a.mueller
  30  *
  31  */
  32 public interface INonViralNameParser<T extends TaxonNameBase> extends IStrategy {
  33
  34         /**
  35          * Parses the taxon name String and returns a TaxonNameBase.
  36          * If the String is not parseable the "hasProblem" bit is set to true.
  37          * Returns null if fullName == null.
  38          *
  39          * @param simpleName the scientific name string without authorship, year, reference etc.
  40          * @param rank
  41          * @return TaxonNameBase, with rank = Rank.GENUS for all Uninomials
  42          */
  43         public T parseSimpleName(String simpleName, NomenclaturalCode code, Rank rank);
  44
  45         /**
  46          * Parses the taxon name String and returns a TaxonNameBase.
  47          * If the String is not parseable the "hasProblem" bit is set to true.
  48          * Returns null if fullName == null.
  49          *
  50          * @param simpleName the scientific name string without authorship, year, reference etc.
  51          * @return TaxonNameBase name, with name.rank = rank for all Uninomials and name.rank = Rank.GENUS for rank = null
  52          */
  53         public T parseSimpleName(String simpleName);
  54
  55
  56
  57         /**
  58          * Parses the taxon name String and returns a TaxonNameBase.
  59          * If the String is not parseable the "hasProblem" bit is set to true.
  60          * Returns null if fullName == null.
  61          *
  62          * @param fullName the string containing the scientific name with authorship but without year, reference etc.
  63          * @return TaxonNameBase, with rank = Rank.GENUS for all Uninomials.
  64          */
  65         public T parseFullName(String fullName);
  66
  67         /**
  68          * Parses the taxon name String and returns a TaxonNameBase.
  69          * If the String is not parseable the "hasProblem" bit is set to true.
  70          * Returns null if fullName == null.
  71          *
  72          * @param fullName the string containing the scientific name with authorship but without year, reference etc.
  73          * @param rank
  74          * @return TaxonNameBase name, with name.rank = rank for all Uninomials and name.rank = Rank.GENUS for rank = null
  75          */
  76         public T parseFullName(String fullName, NomenclaturalCode nomCode, Rank rank);
  77
  78         /**
  79          * Parses the taxon name String and fills the result into the existing TaxonNameBase nameToBeFilled.
  80          * Name related fields are set to default (null for Strings and other objects like Authors and References and false for booleans).
  81          * NameRelations are not changed.
  82          * If the String is not parseable the "hasProblem" bit is set to true.
  83          * No change is done to nameToBeFilled if fullName == null.
  84          *
  85          * @param fullName the string containing the scientific name with authorship but without year, reference etc.
  86          * @param rank
  87          * @param nameToBeFilled The TaxonNameBaseToBeFilled
  88          */
  89         public void parseFullName(T nameToBeFilled, String fullName, Rank rank, boolean makeEmpty);
  90
  91         /**
  92          * @param fullReference the string containing the scientific name with authorship, year, reference etc.
  93          * @return
  94          */
  95         public T parseReferencedName(String fullReference);
  96
  97         /**
  98          * @see INonViralNameParser.parseFullReference(T nameToBeFilled, String fullReference, Rank rank, boolean makeEmpty)
  99          * @param fullReference
 100          * @param nomCode
 101          * @param rank
 102          * @return
 103          */
 104         public T parseReferencedName(String fullReference, NomenclaturalCode nomCode, Rank rank);
 105
 106         /**
 107          * Parses a String (fullReference) assuming that it represents a taxonomic name, it's reference,
 108          * and it's nomenclatural status.<BR>
 109          * <ol>
 110          *              <li><strong>Status:</strong> First the last part of the string is checked if it represents a nomenclatural status (e.g. nom. inval.).
 111          * If so, this part of the string is separated and the according status is added to the name.</li>
 112          *              <li><strong>Name:</strong> The starting part of the remaining string is checked if it represent a name according to the rules
 113          * of the underlying nomenclatural code.</li>
 114          *              <li>
 115          *                      <ol>
 116          *                              <li>Non-atomized Name: If the name can not be parsed the title cache as well as the full
 117          * title cache of the name is filled and the hasProblem flag is set to <code>true</code>. The same applies
 118          * if the name can be parsed but is followed by a not empty String that does not start with a
 119          * reference separator ("," of " in ").</li>
 120          *                              <li>Atomized name: Otherwise the name part is separated and parsed. The according name attributes are set and
 121          * the name's protectedTitleCache flag is set to <code>false</code>.</li>
 122          *                      </ol>
 123          *              </li>
 124          *              <li><strong>Reference:</strong> From the remaining string the reference separator is separated.
 125          * The remaining string is parsed for beeing a valid (according to the parsers rules) reference String.
 126          *                      <ol>
 127          *                              <li>If the reference part could not be parsed, the references title cache is set by the remaining string and the
 128          * references protected title cache is set to <code>true</code>.</li>
 129          *                              <li>If the reference could be parsed the reference is separated and parsed. The according reference attributes are
 130          * set and the reference's protectedTitleCache flag as well as the hasProblem flag is set to <code>false</code>.
 131          * Then, and only then, the name's hasProblem flag is set to <code>false</code>.</li>
 132          *                      </ol>
 133          *              </li>
 134          * </ol>
 135          *
 136          * @param nameToBeFilled
 137          *                              an existing name object
 138          * @param fullReference
 139          *                              the string containing the scientific name with authorship, year, reference etc.
 140          * @param rank
 141          * @param makeEmpty
 142          *                              if this parameter is set to true, the name objects will nulled. All information
 143          *                              formerly attached to this name will be lost.
 144          */
 145         public void parseReferencedName(T nameToBeFilled, String fullReference, Rank rank, boolean makeEmpty);
 146
 147         public void parseAuthors(NonViralName nonViralName, String authorString) throws StringNotParsableException;
 148
 149 }