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.DefinedTerm;
  30 import eu.etaxonomy.cdm.model.common.EventBase;
  31 import eu.etaxonomy.cdm.model.common.TermType;
  32 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  33 import eu.etaxonomy.cdm.model.molecular.Cloning;
  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  * @created 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 implements Cloneable{
  62         private static final long serialVersionUID = -4799205199942053585L;
  63         private static final Logger logger = Logger.getLogger(MaterialOrMethodEvent.class);
  64
  65     @XmlElement(name = "DefinedMaterialOrMethod")
  66     @XmlIDREF
  67     @XmlSchemaType(name = "IDREF")
  68     @ManyToOne(fetch=FetchType.LAZY)
  69     @IndexedEmbedded // no depth for terms
  70         private DefinedTerm definedMaterialOrMethod;
  71
  72         //TODO citation / link
  73
  74
  75 // ******************** FACTORY METHOD ******************/
  76
  77     public static MaterialOrMethodEvent NewInstance(){
  78         return new MaterialOrMethodEvent();
  79     }
  80
  81     public static MaterialOrMethodEvent NewInstance(DefinedTerm definedMaterialOrMethod, String methodText){
  82         return new MaterialOrMethodEvent(definedMaterialOrMethod, methodText);
  83     }
  84
  85 // ********************* CONSTRUCTOR ********************/
  86
  87     protected MaterialOrMethodEvent(){};
  88
  89     protected MaterialOrMethodEvent(DefinedTerm definedMaterialOrMethod, String methodText){
  90         this.definedMaterialOrMethod = definedMaterialOrMethod;
  91         this.setDescription(methodText);
  92     }
  93
  94
  95 // ********************* GETTER / SETTER ********************/
  96
  97
  98         /**
  99          * The {@link #getDescription()} method is inherited from {@link EventBase}.
 100          * In this class it is used as freetext describing the material or method used
 101          * or if a {@link #getDefinedMaterialOrMethod() defined method} is given as
 102          * an additional information about how this defined method was used.
 103          *
 104          * @see #getMaterialMethodText()
 105          */
 106     @Override
 107         public String getDescription() {
 108                 return super.getDescription();
 109         }
 110
 111
 112         /**
 113          * @see #getDescription()
 114          * @see #setMaterialMethodText(String)
 115          */
 116     @Override
 117         public void setDescription(String materialMethodText) {
 118                 super.setDescription(materialMethodText);
 119         }
 120
 121
 122
 123         /**
 124          * A freetext describing the material or method or if
 125          * a {@link #getDefinedMaterialOrMethod() defined method} is given
 126          * an additional information about how this method was used.
 127          * In future this method could be removed to decrease the number
 128          * of transient getters in the CDM.
 129          */
 130         @Transient
 131     public String getMaterialMethodText() {
 132                 return this.getDescription();
 133         }
 134
 135
 136         /**
 137          * @see #getMaterialMethodText()
 138          */
 139         public void setMaterialMethodText(String materialMethodText) {
 140                 this.setDescription(materialMethodText);
 141         }
 142
 143
 144         /**
 145          * A defined material or method given as a defined term in a materialOrMethod
 146          * {@link TermVocabulary term vocabulary}. If such a defined material or method is used
 147          * the {@link #getDescription() description} should primarily focus on describing
 148          * deviation from this method rather then repeating it.
 149          *
 150          * @see #getDescription()
 151          * @see #getMaterialMethodText()
 152          * @return the material or method term
 153          */
 154         public DefinedTerm getDefinedMaterialOrMethod() {
 155                 return definedMaterialOrMethod;
 156         }
 157
 158         /**
 159          * @see #getDefinedMaterialOrMethod()
 160          * @param materialMethodTerm
 161          */
 162         public void setDefinedMaterialOrMethod(DefinedTerm definedMaterialOrMethod) {
 163                 this.definedMaterialOrMethod = definedMaterialOrMethod;
 164         }
 165
 166 // ********************* CLONE ********************/
 167         /**
 168          * Clones <i>this</i> {@link Cloning}. This is a shortcut that enables to create
 169          * a new instance that differs only slightly from <i>this</i> cloning by
 170          * modifying only some of the attributes.<BR><BR>
 171          *
 172          * @see EventBase#clone()
 173          * @see java.lang.Object#clone()
 174          */
 175         @Override
 176         public Object clone()  {
 177                 try{
 178                         MaterialOrMethodEvent result = (MaterialOrMethodEvent)super.clone();
 179
 180                         //don't change materialMethodTerm
 181                         return result;
 182                 }catch (CloneNotSupportedException e) {
 183                         logger.warn("Object does not implement cloneable");
 184                         e.printStackTrace();
 185                         return null;
 186                 }
 187         }
 188 }