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

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