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 })
  56 @Entity
  57 @Audited
  58 @Inheritance(strategy=InheritanceType.SINGLE_TABLE)
  59 public abstract class TypeDesignationBase extends ReferencedEntityBase implements ITypeDesignation {
  60         private static final Logger logger = Logger.getLogger(TypeDesignationBase.class);
  61
  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 // **************** CONSTRUCTOR *************************************/
  82
  83         /**
  84          * Class constructor: creates a new empty type designation.
  85          *
  86          * @see #TypeDesignationBase(ReferenceBase, String, String, Boolean)
  87          */
  88         protected TypeDesignationBase(){
  89                 super();
  90         }
  91
  92         /**
  93          * Class constructor: creates a new type designation
  94          * (including its {@link ReferenceBase reference source} and eventually
  95          * the taxon name string originally used by this reference when establishing
  96          * the former designation).
  97          *
  98          * @param citation                              the reference source for the new designation
  99          * @param citationMicroReference        the string with the details describing the exact localisation within the reference
 100          * @param originalNameString    the taxon name string used originally in the reference source for the new designation
 101          * @param isNotDesignated               the boolean flag indicating whether there is no type at all for
 102          *                                                              <i>this</i> type designation
 103          * @see                                                 #TypeDesignationBase()
 104          * @see                                                 #isNotDesignated()
 105          * @see                                                 TaxonNameBase#getTypeDesignations()
 106          */
 107         protected TypeDesignationBase(ReferenceBase citation, String citationMicroReference, String originalNameString, boolean notDesignated){
 108                 super(citation, citationMicroReference, originalNameString);
 109                 this.notDesignated = notDesignated;
 110         }
 111
 112
 113 // **************** METHODS *************************************/
 114
 115
 116         /* (non-Javadoc)
 117          * @see eu.etaxonomy.cdm.model.name.ITypeDesignation#getHomotypicalGroup()
 118          */
 119         /**
 120          * Returns the {@link HomotypicalGroup homotypical group} to which all (in <i>this</i>
 121          * type designation) typified {@link TaxonNameBase taxon names} belong.
 122          *
 123          * @see   #getTypifiedNames()
 124          */
 125         public HomotypicalGroup getHomotypicalGroup() {
 126                 return homotypicalGroup;
 127         }
 128
 129         /* (non-Javadoc)
 130          * @see eu.etaxonomy.cdm.model.name.ITypeDesignation#getTypifiedNames()
 131          */
 132         /**
 133          * Returns the set of {@link TaxonNameBase taxon names} typified in <i>this</i>
 134          * type designation. This is a subset of the taxon names belonging to the
 135          * corresponding {@link #getHomotypicalGroup() homotypical group}.
 136          */
 137         public Set<TaxonNameBase> getTypifiedNames() {
 138                 return typifiedNames;
 139         }
 140
 141         /**
 142          * Returns the boolean value "true" if it is known that a type does not
 143          * exist and therefore the {@link TaxonNameBase taxon name} to which <i>this</i>
 144          * type designation is assigned must still be typified. Two
 145          * cases must be differentiated: <BR><ul>
 146          * <li> a) it is unknown whether a type exists and
 147          * <li> b) it is known that no type exists
 148          *  </ul>
 149          * If a) is true there should be no TypeDesignation instance at all
 150          * assigned to the "typified" taxon name.<BR>
 151          * If b) is true there should be a TypeDesignation instance with the
 152          * flag isNotDesignated set. The typeName attribute, in case of a
 153          * {@link NameTypeDesignation name type designation}, or the typeSpecimen attribute,
 154          * in case of a {@link SpecimenTypeDesignation specimen type designation}, should then be "null".
 155          */
 156         public boolean isNotDesignated() {
 157                 return notDesignated;
 158         }
 159
 160         /**
 161          * @see   #isNotDesignated()
 162          */
 163         public void setNotDesignated(boolean notDesignated) {
 164                 this.notDesignated = notDesignated;
 165         }
 166
 167         @Deprecated //for bidirectional use only
 168         protected void addTypifiedName(TaxonNameBase taxonName){
 169                 this.typifiedNames.add(taxonName);
 170         }
 171 }