cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/occurrence/MaterialOrMethodEvent.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 package eu.etaxonomy.cdm.model.occurrence;
  10
  11 import javax.persistence.Entity;
  12 import javax.persistence.FetchType;
  13 import javax.persistence.Inheritance;
  14 import javax.persistence.InheritanceType;
  15 import javax.persistence.ManyToOne;
  16 import javax.persistence.Transient;
  17 import javax.xml.bind.annotation.XmlAccessType;
  18 import javax.xml.bind.annotation.XmlAccessorType;
  19 import javax.xml.bind.annotation.XmlElement;
  20 import javax.xml.bind.annotation.XmlIDREF;
  21 import javax.xml.bind.annotation.XmlRootElement;
  22 import javax.xml.bind.annotation.XmlSchemaType;
  23 import javax.xml.bind.annotation.XmlType;
  24
  25 import org.apache.log4j.Logger;
  26 import org.hibernate.envers.Audited;
  27 import org.hibernate.search.annotations.IndexedEmbedded;
  28
  29 import eu.etaxonomy.cdm.model.common.EventBase;
  30 import eu.etaxonomy.cdm.model.molecular.Cloning;
  31 import eu.etaxonomy.cdm.model.term.DefinedTerm;
  32 import eu.etaxonomy.cdm.model.term.TermType;
  33 import eu.etaxonomy.cdm.model.term.TermVocabulary;
  34
  35 /**
  36  * A material or method event handles data on materials or methods used for handling specimen or derived units
  37  * in general. It stores information on what material or method was used, who used it and when it was used.
  38  * For reusable data on materials or methods it is best practice to define these first as {@link DefinedTerm
  39  * defined terms} of type {@link TermType#MaterialOrMethod} TODO and then use this term as {@link #getDefinedMaterialOrMethod()
  40  * material or method term}. If this is not possible or if additional data needs to be added one may also
  41  * use {@link #getDescription() freetext} field inherited from {@link EventBase}. Actor and Date information
  42  * are also handled via {@link EventBase} fields.
  43  * This class may be extended by more specific classes which require structured handling of additional parameters.
  44  *
  45  * In general material or method data is not considered to be CDM core data. Therefore the decision was made to handle
  46  * all the data with a common base class which is {@link MaterialOrMethodEvent} to reduce the number of tables required
  47  * in the underlying databases.
  48  *
  49  * @author a.mueller
  50  * @since 2013-07-08
  51  *
  52  */
  53 @XmlAccessorType(XmlAccessType.FIELD)
  54 @XmlType(name = "MaterialOrMethod", propOrder = {
  55         "definedMaterialOrMethod"
  56 })
  57 @XmlRootElement(name = "MaterialOrMethod")
  58 @Entity
  59 @Inheritance(strategy=InheritanceType.SINGLE_TABLE)
  60 @Audited
  61 public class MaterialOrMethodEvent extends EventBase {
  62
  63     private static final long serialVersionUID = -4799205199942053585L;
  64         private static final Logger logger = Logger.getLogger(MaterialOrMethodEvent.class);
  65
  66     @XmlElement(name = "DefinedMaterialOrMethod")
  67     @XmlIDREF
  68     @XmlSchemaType(name = "IDREF")
  69     @ManyToOne(fetch=FetchType.LAZY)
  70     @IndexedEmbedded // no depth for terms
  71         private DefinedTerm definedMaterialOrMethod;
  72
  73         //TODO citation / link
  74
  75
  76 // ******************** FACTORY METHOD ******************/
  77
  78     public static MaterialOrMethodEvent NewInstance(){
  79         return new MaterialOrMethodEvent();
  80     }
  81
  82     public static MaterialOrMethodEvent NewInstance(DefinedTerm definedMaterialOrMethod, String methodText){
  83         return new MaterialOrMethodEvent(definedMaterialOrMethod, methodText);
  84     }
  85
  86 // ********************* CONSTRUCTOR ********************/
  87
  88     protected MaterialOrMethodEvent(){};
  89
  90     protected MaterialOrMethodEvent(DefinedTerm definedMaterialOrMethod, String methodText){
  91         this.definedMaterialOrMethod = definedMaterialOrMethod;
  92         this.setDescription(methodText);
  93     }
  94
  95
  96 // ********************* GETTER / SETTER ********************/
  97
  98
  99         /**
 100          * The {@link #getDescription()} method is inherited from {@link EventBase}.
 101          * In this class it is used as freetext describing the material or method used
 102          * or if a {@link #getDefinedMaterialOrMethod() defined method} is given as
 103          * an additional information about how this defined method was used.
 104          *
 105          * @see #getMaterialMethodText()
 106          */
 107     @Override
 108         public String getDescription() {
 109                 return super.getDescription();
 110         }
 111
 112
 113         /**
 114          * @see #getDescription()
 115          * @see #setMaterialMethodText(String)
 116          */
 117     @Override
 118         public void setDescription(String materialMethodText) {
 119                 super.setDescription(materialMethodText);
 120         }
 121
 122
 123
 124         /**
 125          * A freetext describing the material or method or if
 126          * a {@link #getDefinedMaterialOrMethod() defined method} is given
 127          * an additional information about how this method was used.
 128          * In future this method could be removed to decrease the number
 129          * of transient getters in the CDM.
 130          */
 131         @Transient
 132     public String getMaterialMethodText() {
 133                 return this.getDescription();
 134         }
 135
 136
 137         /**
 138          * @see #getMaterialMethodText()
 139          */
 140         public void setMaterialMethodText(String materialMethodText) {
 141                 this.setDescription(materialMethodText);
 142         }
 143
 144
 145         /**
 146          * A defined material or method given as a defined term in a materialOrMethod
 147          * {@link TermVocabulary term vocabulary}. If such a defined material or method is used
 148          * the {@link #getDescription() description} should primarily focus on describing
 149          * deviation from this method rather then repeating it.
 150          *
 151          * @see #getDescription()
 152          * @see #getMaterialMethodText()
 153          * @return the material or method term
 154          */
 155         public DefinedTerm getDefinedMaterialOrMethod() {
 156                 return definedMaterialOrMethod;
 157         }
 158
 159         /**
 160          * @see #getDefinedMaterialOrMethod()
 161          * @param materialMethodTerm
 162          */
 163         public void setDefinedMaterialOrMethod(DefinedTerm definedMaterialOrMethod) {
 164                 this.definedMaterialOrMethod = definedMaterialOrMethod;
 165         }
 166
 167 // ********************* CLONE ********************/
 168         /**
 169          * Clones <i>this</i> {@link Cloning}. This is a shortcut that enables to create
 170          * a new instance that differs only slightly from <i>this</i> cloning by
 171          * modifying only some of the attributes.<BR><BR>
 172          *
 173          * @see EventBase#clone()
 174          * @see java.lang.Object#clone()
 175          */
 176         @Override
 177         public MaterialOrMethodEvent clone()  {
 178                 try{
 179                         MaterialOrMethodEvent result = (MaterialOrMethodEvent)super.clone();
 180
 181                         //don't change materialMethodTerm
 182                         return result;
 183                 }catch (CloneNotSupportedException e) {
 184                         logger.warn("Object does not implement cloneable");
 185                         e.printStackTrace();
 186                         return null;
 187                 }
 188         }
 189 }