+/**\r
+* Copyright (C) 2009 EDIT\r
+* European Distributed Institute of Taxonomy\r
+* http://www.e-taxonomy.eu\r
+*\r
+* The contents of this file are subject to the Mozilla Public License Version 1.1\r
+* See LICENSE.TXT at the top of this package for the full license terms.\r
+*/ \r
+\r
package eu.etaxonomy.cdm.strategy.parser;\r
\r
-import eu.etaxonomy.cdm.model.name.BotanicalName;\r
import eu.etaxonomy.cdm.model.name.NomenclaturalCode;\r
+import eu.etaxonomy.cdm.model.name.NonViralName;\r
import eu.etaxonomy.cdm.model.name.Rank;\r
import eu.etaxonomy.cdm.model.name.TaxonNameBase;\r
import eu.etaxonomy.cdm.strategy.IStrategy;\r
+import eu.etaxonomy.cdm.strategy.exceptions.StringNotParsableException;\r
\r
\r
/**\r
+ * Supplies several parser methods for non viral taxon name strings and for nomenclatural\r
+ * reference strings. If the parser method for taxon names is not successful\r
+ * the {@link eu.etaxonomy.cdm.model.name.TaxonNameBase#getHasProblem() hasProblem} flag\r
+ * of the {@link eu.etaxonomy.cdm.model.name.TaxonNameBase TaxonNameBase} instance will be set. \r
+ * Some of the parser methods for taxon names create also a TaxonNameBase\r
+ * instance while other ones only fill the result into an existing\r
+ * TaxonNameBase instance.\r
+ * \r
* @author a.mueller\r
*\r
*/\r
public interface INonViralNameParser<T extends TaxonNameBase> extends IStrategy {\r
\r
/**\r
- * Parses the taxonname String and returns a TaxonNameBase. \r
+ * Parses the taxon name String and returns a TaxonNameBase. \r
* If the String is not parseable the "hasProblem" bit is set to true.\r
* Returns null if fullName == null.\r
- * @param fullName TaxonNameBase without Author, Year, Reference etc.\r
+ * \r
+ * @param simpleName the scientific name string without authorship, year, reference etc.\r
* @param rank\r
* @return TaxonNameBase, with rank = Rank.GENUS for all Uninomials \r
*/\r
- public T parseSimpleName(String simpleName, Rank rank);\r
+ public T parseSimpleName(String simpleName, NomenclaturalCode code, Rank rank);\r
\r
/**\r
- * Parses the taxonname String and returns a TaxonNameBase. \r
+ * Parses the taxon name String and returns a TaxonNameBase. \r
* If the String is not parseable the "hasProblem" bit is set to true.\r
* Returns null if fullName == null.\r
- * @param fullName TaxonNameBase without Author, Year, Reference etc.\r
+ * \r
+ * @param simpleName the scientific name string without authorship, year, reference etc.\r
* @return TaxonNameBase name, with name.rank = rank for all Uninomials and name.rank = Rank.GENUS for rank = null \r
*/\r
public T parseSimpleName(String simpleName);\r
\r
\r
/**\r
- * Parses the taxonname String and returns a TaxonNameBase. \r
+ * Parses the taxon name String and returns a TaxonNameBase. \r
* If the String is not parseable the "hasProblem" bit is set to true.\r
* Returns null if fullName == null.\r
- * @param fullName TaxonNameBase with Author, Year, Reference etc.,\r
+ * \r
+ * @param fullName the string containing the scientific name with authorship but without year, reference etc.\r
* @return TaxonNameBase, with rank = Rank.GENUS for all Uninomials. \r
*/\r
public T parseFullName(String fullName);\r
\r
/**\r
- * Parses the taxonname String and returns a TaxonNameBase. \r
+ * Parses the taxon name String and returns a TaxonNameBase. \r
* If the String is not parseable the "hasProblem" bit is set to true.\r
* Returns null if fullName == null.\r
- * @param fullName TaxonNameBase with Author, Year, Reference etc.,\r
+ * \r
+ * @param fullName the string containing the scientific name with authorship but without year, reference etc.\r
* @param rank\r
* @return TaxonNameBase name, with name.rank = rank for all Uninomials and name.rank = Rank.GENUS for rank = null \r
*/\r
public T parseFullName(String fullName, NomenclaturalCode nomCode, Rank rank);\r
\r
/**\r
- * Parses the taxonname String and fills the result into the existing TaxonNameBase nameToBeFilled. \r
+ * Parses the taxon name String and fills the result into the existing TaxonNameBase nameToBeFilled. \r
* Name related fields are set to default (null for Strings and other objects like Authors and References and false for booleans).\r
* NameRelations are not changed.\r
* If the String is not parseable the "hasProblem" bit is set to true.\r
* No change is done to nameToBeFilled if fullName == null.\r
- * @param fullName TaxonNameBase with Author, Year, Reference etc.,\r
+ * \r
+ * @param fullName the string containing the scientific name with authorship but without year, reference etc.\r
* @param rank\r
* @param nameToBeFilled The TaxonNameBaseToBeFilled\r
*/\r
public void parseFullName(T nameToBeFilled, String fullName, Rank rank, boolean makeEmpty);\r
\r
/**\r
- * @param fullReference\r
+ * @param fullReference the string containing the scientific name with authorship, year, reference etc.\r
* @return\r
*/\r
- public T parseFullReference(String fullReference);\r
+ public T parseReferencedName(String fullReference);\r
\r
/**\r
- * @param fullReference\r
+ * @see INonViralNameParser.parseFullReference(T nameToBeFilled, String fullReference, Rank rank, boolean makeEmpty)\r
+ * @param fullReference \r
* @param nomCode\r
* @param rank\r
* @return\r
*/\r
- public T parseFullReference(String fullReference, NomenclaturalCode nomCode, Rank rank);\r
+ public T parseReferencedName(String fullReference, NomenclaturalCode nomCode, Rank rank);\r
\r
/**\r
- * @param nameToBeFilled\r
- * @param fullReference\r
+ * Parses a String (fullReference) assuming that it represents a taxonomic name, it's reference,\r
+ * and it's nomenclatural status.<BR>\r
+ * <ol>\r
+ * <li><strong>Status:</strong> First the last part of the string is checked if it represents a nomenclatural status (e.g. nom. inval.).\r
+ * If so, this part of the string is separated and the according status is added to the name.</li>\r
+ * <li><strong>Name:</strong> The starting part of the remaining string is checked if it represent a name according to the rules \r
+ * of the underlying nomenclatural code.</li> \r
+ * <li>\r
+ * <ol>\r
+ * <li>Non-atomized Name: If the name can not be parsed the title cache as well as the full\r
+ * title cache of the name is filled and the hasProblem flag is set to <code>true</code>. The same applies\r
+ * if the name can be parsed but is followed by a not empty String that does not start with a \r
+ * reference separator ("," of " in ").</li>\r
+ * <li>Atomized name: Otherwise the name part is separated and parsed. The according name attributes are set and \r
+ * the name's protectedTitleCache flag is set to <code>false</code>.</li>\r
+ * </ol>\r
+ * </li>\r
+ * <li><strong>Reference:</strong> From the remaining string the reference separator is separated.\r
+ * The remaining string is parsed for beeing a valid (according to the parsers rules) reference String.\r
+ * <ol>\r
+ * <li>If the reference part could not be parsed, the references title cache is set by the remaining string and the \r
+ * references protected title cache is set to <code>true</code>.</li>\r
+ * <li>If the reference could be parsed the reference is separated and parsed. The according reference attributes are\r
+ * set and the reference's protectedTitleCache flag as well as the hasProblem flag is set to <code>false</code>.\r
+ * Then, and only then, the name's hasProblem flag is set to <code>false</code>.</li>\r
+ * </ol>\r
+ * </li>\r
+ * </ol>\r
+ * \r
+ * @param nameToBeFilled \r
+ * an existing name object\r
+ * @param fullReference \r
+ * the string containing the scientific name with authorship, year, reference etc.\r
* @param rank\r
- * @param makeEmpty\r
+ * @param makeEmpty \r
+ * if this parameter is set to true, the name objects will nulled. All information \r
+ * formerly attached to this name will be lost.\r
*/\r
- public void parseFullReference(T nameToBeFilled, String fullReference, Rank rank, boolean makeEmpty);\r
+ public void parseReferencedName(T nameToBeFilled, String fullReference, Rank rank, boolean makeEmpty);\r
+\r
+ public void parseAuthors(NonViralName nonViralName, String authorString) throws StringNotParsableException;\r
\r
}\r
BGBM BDI Projects / cdmlib.git / blobdiff