2 * Copyright (C) 2009 EDIT
3 * European Distributed Institute of Taxonomy
4 * http://www.e-taxonomy.eu
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.
10 package eu
.etaxonomy
.cdm
.strategy
.parser
;
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
;
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.
30 public interface INonViralNameParser
<T
extends TaxonNameBase
> extends IStrategy
{
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.
37 * @param simpleName the scientific name string without authorship, year, reference etc.
39 * @return TaxonNameBase, with rank = Rank.GENUS for all Uninomials
41 public T
parseSimpleName(String simpleName
, NomenclaturalCode code
, Rank rank
);
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.
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
51 public T
parseSimpleName(String simpleName
);
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.
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.
63 public T
parseFullName(String fullName
);
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.
70 * @param fullName the string containing the scientific name with authorship but without year, reference etc.
72 * @return TaxonNameBase name, with name.rank = rank for all Uninomials and name.rank = Rank.GENUS for rank = null
74 public T
parseFullName(String fullName
, NomenclaturalCode nomCode
, Rank rank
);
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.
83 * @param fullName the string containing the scientific name with authorship but without year, reference etc.
85 * @param nameToBeFilled The TaxonNameBaseToBeFilled
87 public void parseFullName(T nameToBeFilled
, String fullName
, Rank rank
, boolean makeEmpty
);
90 * @param fullReference the string containing the scientific name with authorship, year, reference etc.
93 public T
parseReferencedName(String fullReference
);
96 * @see INonViralNameParser.parseFullReference(T nameToBeFilled, String fullReference, Rank rank, boolean makeEmpty)
97 * @param fullReference
102 public T
parseReferencedName(String fullReference
, NomenclaturalCode nomCode
, Rank rank
);
105 * Parses a String (fullReference) assuming that it represents a taxonomic name, it's reference,
106 * and it's nomenclatural status.<BR>
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>
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>
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.
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>
134 * @param nameToBeFilled
135 * an existing name object
136 * @param fullReference
137 * the string containing the scientific name with authorship, year, reference etc.
140 * if this parameter is set to true, the name objects will nulled. All information
141 * formerly attached to this name will be lost.
143 public void parseReferencedName(T nameToBeFilled
, String fullReference
, Rank rank
, boolean makeEmpty
);