cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/description/TextData.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.HashMap;
  13 import java.util.Iterator;
  14 import java.util.List;
  15 import java.util.Map;
  16
  17 import javax.persistence.Entity;
  18 import javax.persistence.FetchType;
  19 import javax.persistence.ManyToOne;
  20 import javax.persistence.OneToMany;
  21 import javax.validation.constraints.NotNull;
  22 import javax.xml.bind.annotation.XmlAccessType;
  23 import javax.xml.bind.annotation.XmlAccessorType;
  24 import javax.xml.bind.annotation.XmlElement;
  25 import javax.xml.bind.annotation.XmlIDREF;
  26 import javax.xml.bind.annotation.XmlRootElement;
  27 import javax.xml.bind.annotation.XmlSchemaType;
  28 import javax.xml.bind.annotation.XmlType;
  29 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
  30
  31 import org.apache.log4j.Logger;
  32 import org.hibernate.annotations.Cascade;
  33 import org.hibernate.annotations.CascadeType;
  34 import org.hibernate.envers.Audited;
  35 import org.hibernate.search.annotations.Indexed;
  36 import org.hibernate.search.annotations.IndexedEmbedded;
  37
  38 import eu.etaxonomy.cdm.jaxb.MultilanguageTextAdapter;
  39 import eu.etaxonomy.cdm.model.common.Language;
  40 import eu.etaxonomy.cdm.model.common.LanguageString;
  41 import eu.etaxonomy.cdm.model.common.MultilanguageTextHelper;
  42 import eu.etaxonomy.cdm.model.common.TermBase;
  43
  44
  45 /**
  46  * This class represents information pieces expressed in one or several natural
  47  * languages (for the {@link Feature feature} "medical use" for instance).
  48  * A {@link TextFormat format} used for structuring the text may also be stated.
  49  * <P>
  50  * This class corresponds partially to NaturalLanguageDescriptionType according
  51  * to the SDD schema.
  52  *
  53  * @author m.doering
  54  * @version 1.0
  55  * @created 08-Nov-2007 13:06:59
  56  */
  57 @XmlAccessorType(XmlAccessType.FIELD)
  58 @XmlType(name = "TextData", propOrder = {
  59     "multilanguageText",
  60     "format"
  61 })
  62 @XmlRootElement(name = "TextData")
  63 @Entity
  64 @Audited
  65 @Indexed(index = "eu.etaxonomy.cdm.model.description.DescriptionElementBase")
  66 public class TextData extends DescriptionElementBase {
  67         private static final long serialVersionUID = -2165015581278282615L;
  68         @SuppressWarnings("unused")
  69         private static final Logger logger = Logger.getLogger(TextData.class);
  70
  71         //@XmlElement(name = "MultiLanguageText", type = MultilanguageText.class)
  72         @XmlElement(name = "MultiLanguageText")
  73     @XmlJavaTypeAdapter(MultilanguageTextAdapter.class)
  74     @OneToMany (fetch= FetchType.LAZY)
  75     @Cascade({CascadeType.SAVE_UPDATE,CascadeType.MERGE, CascadeType.DELETE, CascadeType.DELETE_ORPHAN })
  76     @IndexedEmbedded
  77     @NotNull
  78         private Map<Language, LanguageString> multilanguageText = new HashMap<Language,LanguageString>();
  79
  80         @XmlElement(name = "Format")
  81         @XmlIDREF
  82         @XmlSchemaType(name = "IDREF")
  83         @ManyToOne(fetch = FetchType.LAZY)
  84         private TextFormat format;
  85
  86         // ************* CONSTRUCTORS *************/
  87         /**
  88          * Class constructor: creates a new empty text data instance.
  89          *
  90          * @see #TextData(Feature)
  91          */
  92         public TextData(){
  93                 this(null);
  94         }
  95
  96         /**
  97          * Class constructor: creates a new text data instance with the {@link Feature feature}
  98          * to be described.
  99          *
 100          * @param       feature the feature the text data refer to
 101          * @see                         #TextData()
 102          */
 103         public TextData(Feature feature){
 104                 super(feature);
 105         }
 106
 107         //********* METHODS **************************************/
 108         /**
 109          * Creates a new empty text data instance.
 110          *
 111          * @see #NewInstance(Feature)
 112          * @see #NewInstance(String, Language, TextFormat)
 113          */
 114         public static TextData NewInstance(){
 115                 return new TextData();
 116         }
 117
 118         /**
 119          * Creates a new text data instance with the {@link Feature feature}
 120          * to be described.
 121          *
 122          * @param       feature the feature the text data refer to
 123          * @see                         #NewInstance()
 124          * @see                         #NewInstance(String, Language, TextFormat)
 125          */
 126         public static TextData NewInstance(Feature feature){
 127                 return new TextData(feature);
 128         }
 129
 130         /**
 131          * Creates a new text data instance with a given text in a given particular
 132          * {@link Language language} and with the given text format for structuring it.
 133          *
 134          * @param       text            the text string with the content of the description
 135          * @param       language        the language in which the text string is formulated
 136          * @param       format          the text format used to structure the text string
 137          * @see                                 #NewInstance()
 138          * @see                                 #NewInstance(Feature)
 139          */
 140         public static TextData NewInstance(String text, Language language, TextFormat format){
 141                 TextData result =  new TextData();
 142                 result.putText(text, language);
 143                 result.setFormat(format);
 144                 return result;
 145         }
 146
 147         /**
 148          * Returns the multilanguage text with the content of <i>this</i> text data.
 149          * The different {@link LanguageString language strings} (texts) contained in the
 150          * multilanguage text should all have the same meaning.
 151          *
 152          * @see #getText(Language)
 153          */
 154     public Map<Language, LanguageString> getMultilanguageText() {
 155                 return multilanguageText;
 156         }
 157
 158     /**
 159      * Returns the multilanguage text with the content of <i>this</i> text data for
 160      * a specific language.
 161      *
 162      * @param language the language in which the text string looked for is formulated
 163      * @return
 164      */
 165     public LanguageString getLanguageText(Language language){
 166         return multilanguageText.get(language);
 167     }
 168
 169     /**
 170      * @deprecated Method name is misleading. Use {@link #getLanguageText(Language)} instead.
 171      */
 172     @Deprecated
 173     public LanguageString getMultilanguageText(Language language){
 174         return multilanguageText.get(language);
 175     }
 176     public void setMultilanguageText(Map<Language,LanguageString> multilanguageText) {
 177         this.multilanguageText = multilanguageText;
 178     }
 179
 180         /**
 181          * Returns the text string in the given {@link Language language} with the content
 182          * of <i>this</i> text data.
 183          *
 184          * @param language      the language in which the text string looked for is formulated
 185          * @see                         #getMultilanguageText(Language)
 186          */
 187         public String getText(Language language) {
 188                 LanguageString languageString = multilanguageText.get(language);
 189                 if (languageString == null){
 190                         return null;
 191                 }else{
 192                         return languageString.getText();
 193                 }
 194         }
 195
 196     /**
 197          * Returns the LanguageString in the preferred language. Preferred languages
 198          * are specified by the parameter languages, which receives a list of
 199          * Language instances in the order of preference. If no representation in
 200          * any preferred languages is found the method falls back to return the
 201          * Representation in Language.DEFAULT() and if neccesary further falls back
 202          * to return the first element found if any.
 203          *
 204          * TODO think about this fall-back strategy &
 205          * see also {@link TermBase#getPreferredRepresentation(List)}
 206          *
 207          * @param languages
 208          * @return
 209          * @deprecated replaced by static method  {@link MultilanguageTextHelper#getPreferredLanguageString(Map, List)}
 210          */
 211         @Deprecated
 212         public LanguageString getPreferredLanguageString(List<Language> languages) {
 213
 214                 LanguageString languageString = null;
 215                 if(languages != null){
 216                         for(Language language : languages) {
 217                                 languageString = multilanguageText.get(language);
 218                                 if(languageString != null){
 219                                         return languageString;
 220                                 }
 221                         }
 222                 }
 223                 languageString = multilanguageText.get(Language.DEFAULT());
 224
 225                 if(languageString == null && multilanguageText.size() > 0){
 226                         Iterator<LanguageString> it = multilanguageText.values().iterator();
 227                         if(it.hasNext()){
 228                                 languageString = it.next();
 229                         }
 230                 }
 231                 return languageString;
 232         }
 233
 234         /**
 235          * Creates a {@link LanguageString language string} based on the given text string
 236          * and the given {@link Language language}, returns it and adds it to the multilanguage
 237          * text representing the content of <i>this</i> text data.
 238          *
 239          * @param text          the string representing the content of the text data
 240          *                                      in a particular language
 241          * @param language      the language in which the text string is formulated
 242          * @return                      the language string
 243          * @see                         #getMultilanguageText()
 244          * @see                         #putText(LanguageString)
 245          */
 246         public LanguageString putText(String text, Language language) {
 247                 LanguageString result = this.multilanguageText.put(language , LanguageString.NewInstance(text, language));
 248                 return (result == null ? null : result);
 249         }
 250         /**
 251          * Adds a translated {@link LanguageString text in a particular language}
 252          * to the multilanguage text representing the content of <i>this</i> text data.
 253          * The given language string will be returned.
 254          *
 255          * @param languageString        the language string representing the content of
 256          *                                                      the text data in a particular language
 257          * @return                                      the language string
 258          * @see                                         #getMultilanguageText()
 259          * @see                                         #putText(String, Language)
 260          */
 261         public LanguageString putText(LanguageString languageString) {
 262
 263                 if (languageString == null){
 264                         return null;
 265                 }else{
 266                         Language language = languageString.getLanguage();
 267                         return this.multilanguageText.put(language, languageString);
 268                 }
 269         }
 270         /**
 271          * Removes from the multilanguage representing the content of
 272          * <i>this</i> text data the one {@link LanguageString language string}
 273          * with the given {@link Language language}. Returns the removed
 274          * language string.
 275          *
 276          * @param  language     the language in which the language string to be removed
 277          *                                      has been formulated
 278          * @return                      the language string associated with the given language
 279          * @see                 #getMultilanguageText()
 280          */
 281         public LanguageString removeText(Language language) {
 282                 return this.multilanguageText.remove(language);
 283         }
 284
 285         /**
 286          * Returns the number of {@link Language languages} in which the content
 287          * of <i>this</i> text data has been formulated.
 288          *
 289          * @see #getMultilanguageText()
 290          */
 291         public int countLanguages(){
 292                 return multilanguageText.size();
 293         }
 294
 295
 296         /**
 297          * Returns the {@link TextFormat format} used for structuring the text representing
 298          * the content of <i>this</i> text data.
 299          *
 300          * @see #getMultilanguageText()
 301          */
 302         public TextFormat getFormat() {
 303                 return format;
 304         }
 305         /**
 306          * @see #getFormat()
 307          */
 308         public void setFormat(TextFormat format) {
 309                 this.format = format;
 310         }
 311
 312 }