cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/TypeDesignationBase.java

   1 /**
   2 * Copyright (C) 2007 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.model.name;
  11
  12 import java.util.HashSet;
  13 import java.util.Set;
  14
  15 import javax.persistence.Entity;
  16 import javax.persistence.FetchType;
  17 import javax.persistence.Inheritance;
  18 import javax.persistence.InheritanceType;
  19 import javax.persistence.ManyToMany;
  20 import javax.persistence.ManyToOne;
  21 import javax.xml.bind.annotation.XmlElement;
  22 import javax.xml.bind.annotation.XmlElementWrapper;
  23 import javax.xml.bind.annotation.XmlIDREF;
  24 import javax.xml.bind.annotation.XmlRootElement;
  25 import javax.xml.bind.annotation.XmlSchemaType;
  26 import javax.xml.bind.annotation.XmlType;
  27
  28 import org.apache.log4j.Logger;
  29 import org.hibernate.annotations.Cascade;
  30 import org.hibernate.annotations.CascadeType;
  31 import org.hibernate.envers.Audited;
  32
  33 import eu.etaxonomy.cdm.model.common.ReferencedEntityBase;
  34 import eu.etaxonomy.cdm.model.reference.ReferenceBase;
  35
  36 /**
  37  * The (abstract) class representing a typification of one or several {@link TaxonNameBase taxon names}.<BR>
  38  * All taxon names which have a {@link Rank rank} "species aggregate" or lower
  39  * can only be typified by specimens (a {@link SpecimenTypeDesignation specimen type designation}), but taxon
  40  * names with a higher rank might be typified by an other taxon name with
  41  * rank "species" or "genus" (a {@link NameTypeDesignation name type designation}).
  42  *
  43  * @see         TaxonNameBase
  44  * @see         NameTypeDesignation
  45  * @see         SpecimenTypeDesignation
  46  * @author  a.mueller
  47  * @created 07.08.2008
  48  * @version 1.0
  49  */
  50 @XmlRootElement(name = "TypeDesignationBase")
  51 @XmlType(name = "TypeDesignationBase", propOrder = {
  52     "typifiedNames",
  53     "homotypicalGroup",
  54     "notDesignated",
  55     "typeStatus"
  56 })
  57 @Entity
  58 @Audited
  59 @Inheritance(strategy=InheritanceType.SINGLE_TABLE)
  60 public abstract class TypeDesignationBase<T extends TypeDesignationStatusBase> extends ReferencedEntityBase implements ITypeDesignation {
  61         private static final Logger logger = Logger.getLogger(TypeDesignationBase.class);
  62
  63         @XmlElement(name = "IsNotDesignated")
  64         private boolean notDesignated;
  65
  66         @XmlElementWrapper(name = "TypifiedNames")
  67         @XmlElement(name = "TypifiedName")
  68         @XmlIDREF
  69         @XmlSchemaType(name = "IDREF")
  70     // Need these references (bidirectional) to fill table TypeDesignationBase_TaxonNameBase
  71         @ManyToMany(fetch = FetchType.LAZY)
  72         private Set<TaxonNameBase> typifiedNames = new HashSet<TaxonNameBase>();
  73
  74         @XmlElement(name = "HomotypicalGroup")
  75         @XmlIDREF
  76         @XmlSchemaType(name = "IDREF")
  77         @ManyToOne(fetch = FetchType.LAZY)
  78         @Cascade(CascadeType.SAVE_UPDATE)
  79         private HomotypicalGroup homotypicalGroup;
  80
  81         @XmlElement(name = "TypeStatus")
  82         @XmlIDREF
  83         @XmlSchemaType(name = "IDREF")
  84         @ManyToOne(fetch = FetchType.LAZY)
  85         private T typeStatus;
  86
  87 // **************** CONSTRUCTOR *************************************/
  88
  89         /**
  90          * Class constructor: creates a new empty type designation.
  91          *
  92          * @see #TypeDesignationBase(ReferenceBase, String, String, Boolean)
  93          */
  94         protected TypeDesignationBase(){
  95                 super();
  96         }
  97
  98         /**
  99          * Class constructor: creates a new type designation
 100          * (including its {@link ReferenceBase reference source} and eventually
 101          * the taxon name string originally used by this reference when establishing
 102          * the former designation).
 103          *
 104          * @param citation                              the reference source for the new designation
 105          * @param citationMicroReference        the string with the details describing the exact localisation within the reference
 106          * @param originalNameString    the taxon name string used originally in the reference source for the new designation
 107          * @param isNotDesignated               the boolean flag indicating whether there is no type at all for
 108          *                                                              <i>this</i> type designation
 109          * @see                                                 #TypeDesignationBase()
 110          * @see                                                 #isNotDesignated()
 111          * @see                                                 TaxonNameBase#getTypeDesignations()
 112          */
 113         protected TypeDesignationBase(ReferenceBase citation, String citationMicroReference, String originalNameString, boolean notDesignated){
 114                 super(citation, citationMicroReference, originalNameString);
 115                 this.notDesignated = notDesignated;
 116         }
 117
 118
 119 // **************** METHODS *************************************/
 120
 121
 122         /**
 123          * Returns the {@link SpecimenTypeDesignationStatus type designation status} for <i>this</i> specimen type
 124          * designation. This status describes which of the possible categories of
 125          * types like "holotype", "neotype", "syntype" or "isotype" applies to <i>this</i>
 126          * specimen type designation.
 127          */
 128         public T getTypeStatus(){
 129                 return this.typeStatus;
 130         }
 131         /**
 132          * @see  #getTypeStatus()
 133          */
 134         public void setTypeStatus(T typeStatus){
 135                 this.typeStatus = typeStatus;
 136         }
 137
 138         /* (non-Javadoc)
 139          * @see eu.etaxonomy.cdm.model.name.ITypeDesignation#getHomotypicalGroup()
 140          */
 141         /**
 142          * Returns the {@link HomotypicalGroup homotypical group} to which all (in <i>this</i>
 143          * type designation) typified {@link TaxonNameBase taxon names} belong.
 144          *
 145          * @see   #getTypifiedNames()
 146          */
 147         public HomotypicalGroup getHomotypicalGroup() {
 148                 return homotypicalGroup;
 149         }
 150
 151         /* (non-Javadoc)
 152          * @see eu.etaxonomy.cdm.model.name.ITypeDesignation#getTypifiedNames()
 153          */
 154         /**
 155          * Returns the set of {@link TaxonNameBase taxon names} typified in <i>this</i>
 156          * type designation. This is a subset of the taxon names belonging to the
 157          * corresponding {@link #getHomotypicalGroup() homotypical group}.
 158          */
 159         public Set<TaxonNameBase> getTypifiedNames() {
 160                 return typifiedNames;
 161         }
 162
 163         /**
 164          * Returns the boolean value "true" if it is known that a type does not
 165          * exist and therefore the {@link TaxonNameBase taxon name} to which <i>this</i>
 166          * type designation is assigned must still be typified. Two
 167          * cases must be differentiated: <BR><ul>
 168          * <li> a) it is unknown whether a type exists and
 169          * <li> b) it is known that no type exists
 170          *  </ul>
 171          * If a) is true there should be no TypeDesignation instance at all
 172          * assigned to the "typified" taxon name.<BR>
 173          * If b) is true there should be a TypeDesignation instance with the
 174          * flag isNotDesignated set. The typeName attribute, in case of a
 175          * {@link NameTypeDesignation name type designation}, or the typeSpecimen attribute,
 176          * in case of a {@link SpecimenTypeDesignation specimen type designation}, should then be "null".
 177          */
 178         public boolean isNotDesignated() {
 179                 return notDesignated;
 180         }
 181
 182         /**
 183          * @see   #isNotDesignated()
 184          */
 185         public void setNotDesignated(boolean notDesignated) {
 186                 this.notDesignated = notDesignated;
 187         }
 188
 189         @Deprecated //for bidirectional use only
 190         protected void addTypifiedName(TaxonNameBase taxonName){
 191                 this.typifiedNames.add(taxonName);
 192         }
 193 }