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