cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/description/DescriptionElementBase.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 eu.etaxonomy.cdm.jaxb.MultilanguageTextAdapter;
  14 import eu.etaxonomy.cdm.model.media.IMediaEntity;
  15 import eu.etaxonomy.cdm.model.media.Media;
  16 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  17 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;
  18 import eu.etaxonomy.cdm.model.taxon.Taxon;
  19 import eu.etaxonomy.cdm.model.common.Language;
  20 import eu.etaxonomy.cdm.model.common.LanguageString;
  21 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  22
  23 import eu.etaxonomy.cdm.model.common.MultilanguageText;
  24 import eu.etaxonomy.cdm.model.common.ReferencedEntityBase;
  25
  26 import org.apache.log4j.Logger;
  27 import org.hibernate.annotations.Cascade;
  28 import org.hibernate.annotations.CascadeType;
  29
  30 import java.util.*;
  31
  32 import javax.persistence.*;
  33 import javax.xml.bind.annotation.XmlAccessType;
  34 import javax.xml.bind.annotation.XmlAccessorType;
  35 import javax.xml.bind.annotation.XmlElement;
  36 import javax.xml.bind.annotation.XmlElementWrapper;
  37 import javax.xml.bind.annotation.XmlIDREF;
  38 import javax.xml.bind.annotation.XmlSchemaType;
  39 import javax.xml.bind.annotation.XmlType;
  40 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
  41
  42 /**
  43  * The upmost (abstract) class for a piece of information) about
  44  * a {@link SpecimenOrObservationBase specimen}, a {@link Taxon taxon} or even a {@link TaxonNameBase taxon name}.
  45  * A concrete description element assigns descriptive data to one {@link Feature feature}.<BR>
  46  * Experts use the word feature for the property itself but not for the actual
  47  * description element. Therefore naming this class FeatureBase would have
  48  * leaded to confusion.
  49  * <P>
  50  * This class corresponds to: <ul>
  51  * <li> DescriptionsBaseType according to the the SDD schema
  52  * <li> InfoItem according to the TDWG ontology
  53  * <li> MeasurementOrFact according to the ABCD schema
  54  * </ul>
  55  *
  56  * @author m.doering
  57  * @version 1.0
  58  * @created 08-Nov-2007 13:06:24
  59  */
  60 @XmlAccessorType(XmlAccessType.FIELD)
  61 @XmlType(name = "DescriptionElementBase", propOrder = {
  62             "feature",
  63             "modifiers",
  64             "modifyingText",
  65             "media"
  66 })
  67 @Entity
  68 @Inheritance(strategy=InheritanceType.SINGLE_TABLE)
  69 public abstract class DescriptionElementBase extends ReferencedEntityBase implements IMediaEntity{
  70         private static final Logger logger = Logger.getLogger(DescriptionElementBase.class);
  71
  72
  73         // ************* CONSTRUCTORS *************/
  74         /**
  75          * Class constructor: creates a new empty description element instance.
  76          *
  77          * @see #DescriptionElementBase(Feature)
  78          */
  79         protected DescriptionElementBase(){
  80         }
  81
  82         /**
  83          * Class constructor: creates a new description element instance with the
  84          * given {@link Feature feature} that is described or measured.
  85          *
  86          * @param       feature the feature described or measured
  87          * @see                         #DescriptionElementBase()
  88          */
  89         protected DescriptionElementBase(Feature feature){
  90                 if (feature == null){
  91                         feature = Feature.UNKNOWN();
  92                 }
  93                 this.feature = feature;
  94         }
  95
  96         //type, category of information. In structured descriptions characters
  97         @XmlElement(name = "Feature")
  98     @XmlIDREF
  99     @XmlSchemaType(name = "IDREF")
 100         private Feature feature;
 101
 102         @XmlElementWrapper(name = "Modifiers")
 103         @XmlElement(name = "Modifier")
 104         private Set<Modifier> modifiers = new HashSet<Modifier>();
 105
 106         @XmlElement(name = "ModifyingText")
 107     @XmlJavaTypeAdapter(MultilanguageTextAdapter.class)
 108         private MultilanguageText modifyingText;
 109
 110         @XmlElementWrapper(name = "Media")
 111         @XmlElement(name = "Medium")
 112     @XmlIDREF
 113     @XmlSchemaType(name = "IDREF")
 114         private Set<Media> media = new HashSet<Media>();
 115
 116
 117         /**
 118          * Returns the set of {@link Media media} (that is pictures, movies,
 119          * recorded sounds ...) <i>this</i> description element is based on.
 120          */
 121         @OneToMany
 122         @Cascade({CascadeType.SAVE_UPDATE})
 123         public Set<Media> getMedia(){
 124                 return this.media;
 125         }
 126         /**
 127          * @see #getMedia()
 128          */
 129         protected void setMedia(Set<Media> media) {
 130                 this.media = media;
 131         }
 132         /**
 133          * Adds a {@link Media media} to the set of {@link #getMedia() media}
 134          * <i>this</i> description element is based on.
 135          *
 136          * @param media the media to be added to <i>this</i> description element
 137          * @see                 #getMedia()
 138          */
 139         public void addMedia(Media media){
 140                 this.media.add(media);
 141         }
 142         /**
 143          * Removes one element from the set of {@link #getMedia() media}
 144          * <i>this</i> description element is based on.
 145          *
 146          * @param  media        the media which should be removed
 147          * @see                 #getMedia()
 148          * @see                 #addMedia(Media)
 149          */
 150         public void removeMedia(Media media){
 151                 this.media.remove(media);
 152         }
 153
 154
 155         /**
 156          * Does exactly the same as getFeature().
 157          *
 158          * @see #getFeature()
 159          */
 160         @Transient
 161         public Feature getType(){
 162                 return this.getFeature();
 163         }
 164         /**
 165          * Does exactly the same as setFeature(Feature).
 166          *
 167          * @param type  the feature to be described or measured
 168          * @see                 #setFeature(Feature)
 169          * @see                 #getFeature()
 170          */
 171         public void setType(Feature type){
 172                 this.setFeature(type);
 173         }
 174
 175         /**
 176          * Returns the {@link Feature feature} <i>this</i> description element is for.
 177          * A feature is a property that can be described or measured but not the
 178          * description or the measurement itself.
 179          */
 180         @ManyToOne
 181         @Cascade(CascadeType.SAVE_UPDATE)
 182         public Feature getFeature(){
 183                 return this.feature;
 184         }
 185         /**
 186          * @see #getFeature()
 187          */
 188         public void setFeature(Feature feature){
 189                 this.feature = feature;
 190         }
 191
 192
 193         /**
 194          * Returns the set of {@link Modifier modifiers} which modulate
 195          * <i>this</i> description element.
 196          */
 197         @OneToMany
 198         public Set<Modifier> getModifiers(){
 199                 return this.modifiers;
 200         }
 201         /**
 202          * @see #getModifiers()
 203          */
 204         protected void setModifiers(Set<Modifier> modifiers){
 205                 this.modifiers = modifiers;
 206         }
 207         /**
 208          * Adds a {@link Modifier modifier} to the set of {@link #getModifiers() modifiers}
 209          * which modulate <i>this</i> description element.
 210          *
 211          * @param modifier      the modifier to be added to <i>this</i> description element
 212          * @see                         #getModifiers()
 213          */
 214         public void addModifier(Modifier modifier){
 215                 this.modifiers.add(modifier);
 216         }
 217         /**
 218          * Removes one element from the set of {@link #getModifiers() modifiers}
 219          * which modulate <i>this</i> description element.
 220          *
 221          * @param  modifier     the modifier which should be removed
 222          * @see                 #getModifiers()
 223          * @see                 #addModifier(Modifier)
 224          */
 225         public void removeModifier(Modifier modifier){
 226                 this.modifiers.remove(modifier);
 227         }
 228
 229
 230         /**
 231          * Returns the {@link MultilanguageText multilanguage text} used to modulate
 232          * <i>this</i> description element. A multilanguage text does not belong to
 233          * a controlled {@link TermVocabulary term vocabulary} as a {@link Modifier modifier} does.
 234          */
 235         public MultilanguageText getModifyingText(){
 236                 return this.modifyingText;
 237         }
 238         /**
 239          * @see #getModifyingText()
 240          */
 241         protected void setModifyingText(MultilanguageText modifyingText){
 242                 this.modifyingText = modifyingText;
 243         }
 244         /**
 245          * Adds a translated {@link LanguageString text in a particular language}
 246          * to the {@link MultilanguageText multilanguage text} used to modulate
 247          * <i>this</i> description element.
 248          *
 249          * @param description   the language string describing the modulation
 250          *                                              in a particular language
 251          * @see                                 #getModifyingText()
 252          * @see                                 #addModifyingText(String, Language)
 253          */
 254         public LanguageString addModifyingText(LanguageString description){
 255                 return this.modifyingText.add(description);
 256         }
 257         /**
 258          * Creates a {@link LanguageString language string} based on the given text string
 259          * and the given {@link Language language} and adds it to the {@link MultilanguageText multilanguage text}
 260          * used to modulate <i>this</i> description element. The different language
 261          * strings contained in the multilanguage text should all have
 262          * the same meaning.
 263          *
 264          * @param text          the string describing the modulation
 265          *                                      in a particular language
 266          * @param language      the language in which the text string is formulated
 267          * @see                         #getModifyingText()
 268          * @see                         #addModifyingText(LanguageString)
 269          */
 270         public LanguageString addModifyingText(String text, Language language){
 271                 return this.modifyingText.put(language, LanguageString.NewInstance(text, language));
 272         }
 273         /**
 274          * Removes from the {@link MultilanguageText multilanguage text} used to modulate
 275          * <i>this</i> description element the one {@link LanguageString language string}
 276          * with the given {@link Language language}.
 277          *
 278          * @param  language     the language in which the language string to be removed
 279          *                                      has been formulated
 280          * @see                 #getModifyingText()
 281          */
 282         public LanguageString removeModifyingText(Language language){
 283                 return this.modifyingText.remove(language);
 284         }
 285 }