cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/description/StateData.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
  13 import java.util.HashMap;
  14 import java.util.HashSet;
  15 import java.util.Map;
  16 import java.util.Set;
  17
  18 import javax.persistence.Entity;
  19 import javax.persistence.FetchType;
  20 import javax.persistence.ManyToMany;
  21 import javax.persistence.ManyToOne;
  22 import javax.persistence.OneToMany;
  23 import javax.validation.constraints.NotNull;
  24 import javax.xml.bind.annotation.XmlAccessType;
  25 import javax.xml.bind.annotation.XmlAccessorType;
  26 import javax.xml.bind.annotation.XmlElement;
  27 import javax.xml.bind.annotation.XmlElementWrapper;
  28 import javax.xml.bind.annotation.XmlIDREF;
  29 import javax.xml.bind.annotation.XmlRootElement;
  30 import javax.xml.bind.annotation.XmlSchemaType;
  31 import javax.xml.bind.annotation.XmlType;
  32 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
  33
  34 import org.apache.log4j.Logger;
  35 import org.hibernate.annotations.Cascade;
  36 import org.hibernate.annotations.CascadeType;
  37 import org.hibernate.envers.Audited;
  38
  39 import eu.etaxonomy.cdm.jaxb.MultilanguageTextAdapter;
  40 import eu.etaxonomy.cdm.model.common.IMultiLanguageTextHolder;
  41 import eu.etaxonomy.cdm.model.common.Language;
  42 import eu.etaxonomy.cdm.model.common.LanguageString;
  43 import eu.etaxonomy.cdm.model.common.MultilanguageText;
  44 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  45 import eu.etaxonomy.cdm.model.common.VersionableEntity;
  46
  47 /**
  48  * This class represents the assignment of values ({@link State state terms}) to {@link Feature features}
  49  * corresponding to {@link CategoricalData categorical data}. A state data instance
  50  * constitutes an atomized part of an information piece (categorical data) so
  51  * that several state data instances may belong to one categorical data
  52  * instance.
  53  * <P>
  54  * This class corresponds to CharacterStateDataType according to the SDD schema.
  55  *
  56  * @author m.doering
  57  * @version 1.0
  58  * @created 08-Nov-2007 13:06:53
  59  */
  60 @XmlAccessorType(XmlAccessType.FIELD)
  61 @XmlType(name = "StateData", propOrder = {
  62     "state",
  63     "modifiers",
  64     "modifyingText"
  65 })
  66 @XmlRootElement(name = "StateData")
  67 @Entity
  68 @Audited
  69 public class StateData extends VersionableEntity implements IModifiable, IMultiLanguageTextHolder, Cloneable{
  70         private static final long serialVersionUID = -4380314126624505415L;
  71         private static final Logger logger = Logger.getLogger(StateData.class);
  72
  73         @XmlElement(name = "State")
  74     @XmlIDREF
  75     @XmlSchemaType(name = "IDREF")
  76     @ManyToOne(fetch = FetchType.LAZY)
  77         private State state;
  78
  79         @XmlElementWrapper(name = "Modifiers")
  80         @XmlElement(name = "Modifier")
  81         @ManyToMany(fetch = FetchType.LAZY)
  82         @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE})
  83 //      @NotNull // avoids creating a UNIQUE key for this field -> not needed for ManyToMany
  84         private Set<Modifier> modifiers = new HashSet<Modifier>();
  85
  86         @XmlElement(name = "ModifyingText")
  87         @XmlJavaTypeAdapter(MultilanguageTextAdapter.class)
  88         @OneToMany(fetch = FetchType.LAZY)
  89         private Map<Language,LanguageString> modifyingText = new HashMap<Language,LanguageString>();
  90
  91         /**
  92          * Class constructor: creates a new empty state data instance.
  93          */
  94         public StateData() {
  95                 super();
  96         }
  97
  98         /**
  99          * Creates a new empty state data instance.
 100          */
 101         public static StateData NewInstance(){
 102                 return new StateData();
 103         }
 104
 105         /**
 106          * Returns the {@link State state term} used in <i>this</i> state data.
 107          */
 108         public State getState(){
 109                 return this.state;
 110         }
 111         /**
 112          * @see #getState()
 113          */
 114         public void setState(State state){
 115                 this.state = state;
 116         }
 117
 118
 119         /**
 120          * Returns the set of {@link Modifier modifiers} used to qualify the validity
 121          * of <i>this</i> state data. This is only metainformation.
 122          */
 123         public Set<Modifier> getModifiers(){
 124                 return this.modifiers;
 125         }
 126
 127         /**
 128          * Adds a {@link Modifier modifier} to the set of {@link #getModifiers() modifiers}
 129          * used to qualify the validity of <i>this</i> state data.
 130          *
 131          * @param modifier      the modifier to be added to <i>this</i> state data
 132          * @see                         #getModifiers()
 133          */
 134         public void addModifier(Modifier modifier){
 135                 this.modifiers.add(modifier);
 136         }
 137         /**
 138          * Removes one element from the set of {@link #getModifiers() modifiers}
 139          * used to qualify the validity of <i>this</i> state data.
 140          *
 141          * @param  modifier     the modifier which should be removed
 142          * @see                 #getModifiers()
 143          * @see                 #addModifier(Modifier)
 144          */
 145         public void removeModifier(Modifier modifier){
 146                 this.modifiers.remove(modifier);
 147         }
 148
 149
 150         /**
 151          * Returns the {@link MultilanguageText multilanguage text} used to qualify the validity
 152          * of <i>this</i> state data.  The different {@link LanguageString language strings}
 153          * contained in the multilanguage text should all have the same meaning.<BR>
 154          * A multilanguage text does not belong to a controlled {@link TermVocabulary term vocabulary}
 155          * as a {@link Modifier modifier} does.
 156          * <P>
 157          * NOTE: the actual content of <i>this</i> state data is NOT
 158          * stored in the modifying text. This is only metainformation
 159          * (like "Some experts express doubt about this assertion").
 160          */
 161         public Map<Language,LanguageString> getModifyingText(){
 162                 return this.modifyingText;
 163         }
 164
 165         /**
 166          * Creates a {@link LanguageString language string} based on the given text string
 167          * and the given {@link Language language} and adds it to the {@link MultilanguageText multilanguage text}
 168          * used to qualify the validity of <i>this</i> state data.
 169          *
 170          *
 171          * @param text          the string describing the validity
 172          *                                      in a particular language
 173          * @param language      the language in which the text string is formulated
 174          *
 175          * @see                         #getModifyingText()
 176          * @see                         #putModifyingText(LanguageString)
 177          * @deprecated          should follow the put semantic of maps, this method will be removed in v4.0
 178          *                                      Use the {@link #putModifyingText(Language, String) putModifyingText} method instead
 179          */
 180         @Deprecated
 181         public LanguageString addModifyingText(String text, Language language){
 182                 return this.putModifyingText(language, text);
 183         }
 184
 185         /**
 186          * Creates a {@link LanguageString language string} based on the given text string
 187          * and the given {@link Language language} and adds it to the {@link MultilanguageText multilanguage text}
 188          * used to qualify the validity of <i>this</i> state data.
 189          *
 190          * @param language      the language in which the text string is formulated
 191          * @param text          the string describing the validity
 192          *                                      in a particular language
 193          *
 194          * @see                         #getModifyingText()
 195          * @see                         #addModifyingText(LanguageString)
 196          */
 197         public LanguageString putModifyingText(Language language, String text){
 198                 return this.modifyingText.put(language, LanguageString.NewInstance(text, language));
 199         }
 200         /**
 201          * Adds a translated {@link LanguageString text in a particular language}
 202          * to the {@link MultilanguageText multilanguage text} used to qualify the validity
 203          * of <i>this</i> state data.
 204          *
 205          * @param text  the language string describing the validity
 206          *                              in a particular language
 207          * @see                 #getModifyingText()
 208          * @see                 #putModifyingText(Language, String)
 209          * @deprecated  should follow the put semantic of maps, this method will be removed in v4.0
 210          *                              Use the {@link #putModifyingText(LanguagString) putModifyingText} method instead
 211          */
 212         @Deprecated
 213         public LanguageString addModifyingText(LanguageString text){
 214                 return this.putModifyingText(text);
 215         }
 216
 217         /**
 218          * Adds a translated {@link LanguageString text in a particular language}
 219          * to the {@link MultilanguageText multilanguage text} used to qualify the validity
 220          * of <i>this</i> state data.
 221          *
 222          * @param text  the language string describing the validity
 223          *                              in a particular language
 224          * @see                 #getModifyingText()
 225          * @see                 #putModifyingText(Language, String)
 226          */
 227         public LanguageString putModifyingText(LanguageString text){
 228                 return this.modifyingText.put(text.getLanguage(),text);
 229         }
 230         /**
 231          * Removes from the {@link MultilanguageText multilanguage text} used to qualify the validity
 232          * of <i>this</i> state data the one {@link LanguageString language string}
 233          * with the given {@link Language language}.
 234          *
 235          * @param  lang the language in which the language string to be removed
 236          *                              has been formulated
 237          * @see         #getModifyingText()
 238          */
 239         public LanguageString removeModifyingText(Language lang){
 240                 return this.modifyingText.remove(lang);
 241         }
 242
 243 //*********************************** CLONE *****************************************/
 244
 245         /**
 246          * Clones <i>this</i> state data. This is a shortcut that enables to create
 247          * a new instance that differs only slightly from <i>this</i> state data by
 248          * modifying only some of the attributes.
 249          *
 250          * @see eu.etaxonomy.cdm.model.common.VersionableEntity#clone()
 251          * @see java.lang.Object#clone()
 252          */
 253         @Override
 254         public Object clone() {
 255
 256                 try {
 257                         StateData result = (StateData)super.clone();
 258
 259                         //modifiers
 260                         result.modifiers = new HashSet<Modifier>();
 261                         for (Modifier modifier : getModifiers()){
 262                                 result.modifiers.add(modifier);
 263                         }
 264
 265                         //modifying text
 266                         result.modifyingText = new HashMap<Language, LanguageString>();
 267                         for (Language language : getModifyingText().keySet()){
 268                                 //TODO clone needed? See also IndividualsAssociation
 269                                 LanguageString newLanguageString = (LanguageString)getModifyingText().get(language).clone();
 270                                 result.modifyingText.put(language, newLanguageString);
 271                         }
 272
 273                         return result;
 274                         //no changes to: state
 275                 } catch (CloneNotSupportedException e) {
 276                         logger.warn("Object does not implement cloneable");
 277                         e.printStackTrace();
 278                         return null;
 279                 }
 280         }
 281 }