cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/description/CategoricalData.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.description;
  11
  12 import java.util.ArrayList;
  13 import java.util.HashSet;
  14 import java.util.List;
  15
  16 import javax.persistence.Entity;
  17 import javax.persistence.FetchType;
  18 import javax.persistence.ManyToMany;
  19 import javax.xml.bind.annotation.XmlAccessType;
  20 import javax.xml.bind.annotation.XmlAccessorType;
  21 import javax.xml.bind.annotation.XmlElement;
  22 import javax.xml.bind.annotation.XmlElementWrapper;
  23 import javax.xml.bind.annotation.XmlRootElement;
  24 import javax.xml.bind.annotation.XmlType;
  25
  26 import org.apache.log4j.Logger;
  27 import org.hibernate.annotations.Cascade;
  28 import org.hibernate.annotations.CascadeType;
  29 import org.hibernate.envers.Audited;
  30 import org.hibernate.search.annotations.Indexed;
  31 import org.hibernate.search.annotations.IndexedEmbedded;
  32 import org.hibernate.validator.constraints.NotEmpty;
  33
  34 import eu.etaxonomy.cdm.model.name.NomenclaturalStatus;
  35 import eu.etaxonomy.cdm.validation.Level2;
  36
  37 /**
  38  * This class represents information pieces expressed in categorical type of
  39  * data (in opposition to {@link QuantitativeData quantitative data} on one side and to literal data on
  40  * the other side). Only {@link TaxonDescription taxon descriptions} and
  41  * {@link SpecimenDescription specimen descriptions} may contain categorical data.<BR>
  42  * The "color of petals" {@link Feature feature} for instance can be described with
  43  * {@link State state terms} such as "blue" or "white". If the color of petals of a
  44  * particular tree is described as "mostly blue" and "exceptionally white" two
  45  * {@link StateData state data} instances must be assigned to an instance of the
  46  * present class: the first one with the state "blue" and the {@link Modifier modifier}
  47  * "mostly" and the second one with the state "white" and the modifier "exceptionally".
  48  * Whenever more than one state data belongs to a categorical data they should be
  49  * interpreted as being related by the inclusive disjunction "or".
  50  * <P>
  51  * This class corresponds partially to CodedDescriptionType according to
  52  * the SDD schema.
  53  *
  54  * @author m.doering
  55  * @version 1.0
  56  * @created 08-Nov-2007 13:06:15
  57  */
  58 @XmlAccessorType(XmlAccessType.FIELD)
  59 @XmlType(name = "CategoricalData", propOrder = {
  60     "orderRelevant",
  61     "states"
  62 })
  63 @XmlRootElement(name = "CategoricalData")
  64 @Entity
  65 @Audited
  66 @Indexed(index = "eu.etaxonomy.cdm.model.description.DescriptionElementBase")
  67 public class CategoricalData extends DescriptionElementBase implements Cloneable{
  68         private static final long serialVersionUID = -6298361966947668998L;
  69         private static final Logger logger = Logger.getLogger(CategoricalData.class);
  70
  71         //whether the sequence of ordered states is important
  72         @XmlElement(name = "OrderRelevant")
  73         private boolean orderRelevant;
  74
  75         @XmlElementWrapper(name = "States")
  76         @XmlElement(name = "State")
  77         @ManyToMany(fetch = FetchType.LAZY)
  78         @Cascade({ CascadeType.SAVE_UPDATE, CascadeType.MERGE, CascadeType.DELETE,CascadeType.DELETE_ORPHAN })
  79         @IndexedEmbedded(depth = 2)
  80         @NotEmpty(groups = Level2.class)
  81         private List<StateData> states = new ArrayList<StateData>();
  82
  83
  84         /**
  85          * Class constructor: creates a new empty categorical data instance.
  86          */
  87         protected CategoricalData() {
  88                 super(null);
  89         }
  90
  91         /**
  92          * Creates a new empty categorical data instance.
  93          */
  94         public static CategoricalData NewInstance(){
  95                 logger.debug("NewInstance");
  96                 return new CategoricalData();
  97         }
  98
  99         /**
 100          * Returns the (ordered) list of {@link State states} describing the {@link Feature feature}
 101          * corresponding to <i>this</i> categorical data.
 102          */
 103
 104         public List<StateData> getStates(){
 105                 return this.states;
 106         }
 107
 108         protected void setStates(List<StateData> states){
 109                 this.states = states;
 110         }
 111
 112         /**
 113          * Adds a {@link State state} to the list of {@link #getStates() states}
 114          * describing the {@link Feature feature} corresponding to <i>this</i> categorical data.
 115          *
 116          * @param state the state to be added to <i>this</i> categorical data
 117          * @see                 #getStates()
 118          */
 119         public void addState(StateData state){
 120                 this.states.add(state);
 121         }
 122         /**
 123          * Removes one element from the set of {@link #getStates() states}
 124          * describing the {@link Feature feature} corresponding to <i>this</i> categorical data.
 125          *
 126          * @param  state        the state which should be removed
 127          * @see                 #getStates()
 128          * @see                 #addState(State)
 129          */
 130         public void removeState(StateData state){
 131                 this.states.remove(state);
 132         }
 133
 134         //rename to isStateSequenceIntentional ??
 135         /**
 136          * Returns the boolean value of the flag indicating whether the sequence of
 137          * {@link StateData state data} belonging to <i>this</i> categorical data is intentional
 138          * (true) and therefore relevant for interpretation or analysis or not (false).
 139          * The use of this flag depends mostly on the {@link Feature feature} of <i>this</i> categorical data.
 140          *
 141          * @return  the boolean value of the orderRelevant flag
 142          */
 143         public boolean getOrderRelevant(){
 144                 return this.orderRelevant;
 145         }
 146         /**
 147          * @see #getOrderRelevant()
 148          */
 149         public void setOrderRelevant(boolean orderRelevant){
 150                 this.orderRelevant = orderRelevant;
 151         }
 152
 153
 154 //*********************************** CLONE *****************************************/
 155
 156         /**
 157          * Clones <i>this</i> categorical data. This is a shortcut that enables to create
 158          * a new instance that differs only slightly from <i>this</i> categorical data by
 159          * modifying only some of the attributes.
 160          *
 161          * @see eu.etaxonomy.cdm.model.description.DescriptionElementBase#clone()
 162          * @see java.lang.Object#clone()
 163          */
 164         @Override
 165         public Object clone() {
 166
 167                 try {
 168                         CategoricalData result = (CategoricalData)super.clone();
 169
 170                         //states
 171                         result.states = new ArrayList<StateData>();
 172                         for (StateData stateData : getStates()){
 173                                 //TODO do we need to clone here?
 174                                 StateData newState = (StateData)stateData.clone();
 175                                 result.states.add(newState);
 176                         }
 177
 178                         return result;
 179                         //no changes to: orderRelevant
 180                 } catch (CloneNotSupportedException e) {
 181                         logger.warn("Object does not implement cloneable");
 182                         e.printStackTrace();
 183                         return null;
 184                 }
 185         }
 186
 187 }