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