cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/agent/Person.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.agent;
  11
  12 import eu.etaxonomy.cdm.model.common.TimePeriod;
  13 import eu.etaxonomy.cdm.model.common.Keyword;
  14 import eu.etaxonomy.cdm.strategy.cache.PersonDefaultCacheStrategy;
  15 import org.apache.log4j.Logger;
  16 import org.hibernate.annotations.Cascade;
  17 import org.hibernate.annotations.CascadeType;
  18 import java.util.*;
  19 import javax.persistence.*;
  20
  21 /**
  22  * A representation of a human being, living or dead.
  23  * It includes name parts, {@link Contact contact} details, {@link InstitutionalMembership institutional membership},
  24  * and other possible information such as life {@link common.TimePeriod time period},
  25  * taxonomic and/or geographical {@link common.Keyword specialization}.
  26  * For a short abbreviated name the inherited attribute {@link TeamOrPersonBase#getNomenclaturalTitle() nomenclaturalTitle}
  27  * is to be used.
  28  * For other alternative (string-)names {@link common.OriginalSource OriginalSource} instances must be created
  29  * and the inherited attribute {@link common.ReferencedEntityBase#getOriginalNameString() originalNameString} must be used.
  30  * <p>
  31  * See also the <a href="http://rs.tdwg.org/ontology/voc/Person.rdf">TDWG Ontology</a>
  32  *
  33  * @author m.doering
  34  * @version 1.0
  35  * @created 08-Nov-2007 13:06:42
  36  */
  37 @Entity
  38 public class Person extends TeamOrPersonBase {
  39         static Logger logger = Logger.getLogger(Person.class);
  40
  41         private String prefix;
  42         private String firstname;
  43         private String lastname;
  44         private String suffix;
  45         private TimePeriod lifespan;
  46         protected Set<InstitutionalMembership> institutionalMemberships;
  47         private Contact contact;
  48         private Set<Keyword> keywords = new HashSet<Keyword>();
  49
  50         /**
  51          * Creates a new empty instance for a person whose existence is all what is known.
  52          * This can be a provisional solution until more information about this person
  53          * can be gathered, for instance in case a member of a nomenclatural author team
  54          * is not explicitly mentioned. It also includes the cache strategy defined in
  55          * {@link eu.etaxonomy.cdm.strategy.cache.PersonDefaultCacheStrategy PersonDefaultCacheStrategy}.
  56          */
  57         public static Person NewInstance(){
  58                 return new Person();
  59         }
  60
  61         /**
  62          * Creates a new instance for a person for whom an "identification" string
  63          * is all what is known. This string is generally a short or a complete name.
  64          * As this string is kept in the {@link common.IdentifiableEntity#getTitleCache() titleCache}
  65          * attribute and should not be overwritten by the {@link #generateTitle() generateTitle} method
  66          * the {@link common.IdentifiableEntity#isProtectedTitleCache() protectedTitleCache} flag will be turned on.
  67          */
  68         public static Person NewTitledInstance(String titleCache){
  69                 Person result = new Person();
  70                 result.setTitleCache(titleCache);
  71                 return result;
  72         }
  73
  74
  75         /**
  76          * Class constructor.
  77          *
  78          * @see #Person(String, String, String)
  79          */
  80         private Person() {
  81                 super();
  82                 this.cacheStrategy = PersonDefaultCacheStrategy.NewInstance();
  83
  84         }
  85
  86         /**
  87          * Class constructor using a "forenames" string (including initials),
  88          * a surname (family name) and an abbreviated name as used in nomenclature.
  89          * For the abbreviated name the inherited attribute {@link TeamOrPersonBase#getNomenclaturalTitle() nomenclaturalTitle}
  90          * is used.
  91          *
  92          * @param  firstname                    the given name
  93          * @param  lastname                     the hereditary name
  94          * @param  nomenclaturalTitel   the abbreviated name
  95          * @see                                 #Person()
  96          * @see                                 #NewInstance()
  97          */
  98         public Person(String firstname, String lastname, String nomenclaturalTitel) {
  99                 this.setFirstname(firstname);
 100                 this.setLastname(lastname);
 101                 this.setNomenclaturalTitle(nomenclaturalTitel);
 102         }
 103
 104
 105         /**
 106          * Returns the set of {@link InstitutionalMembership institution memberships} corresponding to this person.
 107          *
 108          * @see     InstitutionalMembership
 109          */
 110         @OneToMany
 111         @Cascade({CascadeType.SAVE_UPDATE, CascadeType.DELETE})
 112         public Set<InstitutionalMembership> getInstitutionalMemberships(){
 113                 return this.institutionalMemberships;
 114         }
 115         /**
 116          * @see     #getInstitutionalMemberships()
 117          */
 118         protected void setInstitutionalMemberships(Set<InstitutionalMembership> institutionalMemberships){
 119                 this.institutionalMemberships = institutionalMemberships;
 120         }
 121
 122         /**
 123          * Adds a new {@link InstitutionalMembership membership} of this person in an {@link Institution institution}
 124          * to the set of his institution memberships.
 125          * This method also creates a new institutional membership instance.
 126          *
 127          * @param  institution  the institution this person belongs to
 128          * @param  period       the time period for which this person has been a member of the institution
 129          * @param  department   the string label for the department this person belongs to,
 130          *                                          within the institution
 131          * @param  role         the string label for the persons's role within the department or institution
 132          * @see                             #getInstitutionalMemberships()
 133          * @see                             InstitutionalMembership#InstitutionalMembership(Institution, Person, TimePeriod, String, String)
 134          */
 135         public void addInstitutionalMembership(Institution institution, TimePeriod period, String department, String role){
 136                 //TODO to be implemented?
 137                 logger.warn("not yet fully implemented?");
 138                 InstitutionalMembership ims = new InstitutionalMembership(institution, this, period, department, role);
 139         }
 140
 141         /**
 142          * Removes one element from the set of institutional memberships of this person.
 143          *
 144          * @param  ims  the institutional membership of this person which should be deleted
 145          * @see         #getInstitutionalMemberships()
 146          */
 147         public void removeInstitutionalMembership(InstitutionalMembership ims){
 148                 //TODO to be implemented?
 149                 logger.warn("not yet fully implemented?");
 150                 ims.setInstitute(null);
 151                 ims.setPerson(null);
 152                 this.institutionalMemberships.remove(ims);
 153         }
 154
 155
 156         /**
 157          * Returns the set of {@link common.Keyword keywords} mostly representing a taxonomic or
 158          * a geographical specialization of this person.
 159          * Keywords are items of a controlled {@link common.TermVocabulary vocabulary}.
 160          *
 161          * @see         common.Keyword
 162          */
 163         @OneToMany
 164         @Cascade({CascadeType.SAVE_UPDATE, CascadeType.DELETE_ORPHAN})
 165         public Set<Keyword> getKeywords(){
 166                 return this.keywords;
 167         }
 168         /**
 169          * @see     #getKeywords()
 170          */
 171         public void setKeywords(Set<Keyword> keywords){
 172                 this.keywords = keywords;
 173         }
 174         /**
 175          * Adds a new keyword from the keyword vocabulary to the set of keywords
 176          * describing or circumscribing this person's activities.
 177          *
 178          * @param  keyword  any keyword
 179          * @see                         #getKeywords()
 180          * @see                         common.Keyword
 181          */
 182         public void addKeyword(Keyword keyword){
 183                 this.keywords.add(keyword);
 184         }
 185         /**
 186          * Removes one element from the set of keywords for this person.
 187          *
 188          * @param  keyword  the keyword which should be deleted
 189          * @see             #getKeywords()
 190          */
 191         public void removeKeyword(Keyword keyword){
 192                 this.keywords.remove(keyword);
 193         }
 194
 195
 196
 197         /**
 198          * Returns the {@link Contact contact} of this person.
 199          * The contact contains several ways to approach this person.
 200          *
 201          * @see         Contact
 202          */
 203         @ManyToOne
 204         @Cascade({CascadeType.SAVE_UPDATE})
 205         public Contact getContact(){
 206                 return this.contact;
 207         }
 208         /**
 209          * @see  #getContact()
 210          */
 211         public void setContact(Contact contact){
 212                 this.contact = contact;
 213         }
 214
 215
 216         /**
 217          * Returns the string representing the prefix (for instance "Prof.&nbsp;Dr.<!-- -->")
 218          * to this person's name.
 219          */
 220         public String getPrefix(){
 221                 return this.prefix;
 222         }
 223         /**
 224          * @see  #getPrefix()
 225          */
 226         public void setPrefix(String prefix){
 227                 this.prefix = prefix;
 228         }
 229
 230
 231         /**
 232          * Returns the string representing the given name or forename
 233          * (for instance "John") of this person.
 234          * This is the part of his name which is not shared with other
 235          * family members. Actually it may be just initials (for instance "G. Jr."),
 236          * all forenames in full or a combination of expanded names and initials.
 237          */
 238         public String getFirstname(){
 239                 return this.firstname;
 240         }
 241         /**
 242          * @see  #getFirstname()
 243          */
 244         public void setFirstname(String firstname){
 245                 this.firstname = firstname;
 246         }
 247
 248
 249         /**
 250          * Returns the string representing the hereditary name (surname or family name)
 251          * (for instance "Smith") of this person.
 252          * This is the part of his name which is common to (all) other
 253          * members of his family, as distinct from the given name or forename.
 254          */
 255         public String getLastname(){
 256                 return this.lastname;
 257         }
 258         /**
 259          * @see  #getLastname()
 260          */
 261         public void setLastname(String lastname){
 262                 this.lastname = lastname;
 263         }
 264
 265
 266         /**
 267          * Returns the string representing the suffix (for instance "Junior")
 268          * of this person's name.
 269          */
 270         public String getSuffix(){
 271                 return this.suffix;
 272         }
 273         /**
 274          * @see  #getSuffix()
 275          */
 276         public void setSuffix(String suffix){
 277                 this.suffix = suffix;
 278         }
 279
 280
 281         /**
 282          * Returns the {@link common.TimePeriod period of time}
 283          * in which this person was alive (life span).
 284          * The general form is birth date - death date
 285          * (XXXX - YYYY; XXXX - or - YYYY as appropriate),
 286          * but a simple flourished date (fl. XXXX) is also possible
 287          * if that is all what is known.
 288          *
 289          * @see  common.TimePeriod
 290          */
 291         public TimePeriod getLifespan(){
 292                 return this.lifespan;
 293         }
 294         /**
 295          * @see  #getLifespan()
 296          */
 297         public void setLifespan(TimePeriod lifespan){
 298                 this.lifespan = lifespan;
 299         }
 300
 301         /**
 302          * Generates the "full" name string of this person according to the strategy
 303          * defined in {@link eu.etaxonomy.cdm.strategy.cache.PersonDefaultCacheStrategy PersonDefaultCacheStrategy}.
 304          * The used attributes are:
 305          * {@link #prefix prefix}, {@link #firstname firstname}, {@link #lastname lastname} and {@link #suffix suffix}.
 306          * This method overrides {@link common.IdentifiableEntity#generateTitle() generateTitle}.
 307          * The result might be kept as {@link common.IdentifiableEntity#setTitleCache(String) titleCache} if the
 308          * flag {@link common.IdentifiableEntity#protectedTitleCache protectedTitleCache} is not set.
 309          *
 310          * @return  the string with the full name of this person
 311          */
 312         @Override
 313         public String generateTitle(){
 314                 return cacheStrategy.getTitleCache(this);
 315         }
 316
 317 }