cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/agent/Team.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 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.persistence.Transient;
  19 import javax.xml.bind.annotation.XmlAccessType;
  20 import javax.xml.bind.annotation.XmlAccessorType;
  21 import javax.xml.bind.annotation.XmlElement;
  22 import javax.xml.bind.annotation.XmlElementWrapper;
  23 import javax.xml.bind.annotation.XmlIDREF;
  24 import javax.xml.bind.annotation.XmlRootElement;
  25 import javax.xml.bind.annotation.XmlSchemaType;
  26 import javax.xml.bind.annotation.XmlType;
  27
  28 import org.apache.log4j.Logger;
  29 import org.hibernate.annotations.Cascade;
  30 import org.hibernate.annotations.CascadeType;
  31 import org.hibernate.annotations.IndexColumn;
  32 import org.hibernate.envers.Audited;
  33 import org.hibernate.search.annotations.Indexed;
  34 import org.springframework.beans.factory.annotation.Configurable;
  35
  36 import eu.etaxonomy.cdm.strategy.cache.agent.TeamDefaultCacheStrategy;
  37
  38 /**
  39  * This class represents teams of {@link Person persons}. A team exists either for itself
  40  * or is built with the list of (distinct) persons who belong to it.
  41  * In the first case the inherited attribute {@link eu.etaxonomy.cdm.model.common.IdentifiableEntity#getTitleCache() titleCache} is to be used.
  42  * In the second case at least all abbreviated names
  43  * (the inherited attributes {@link TeamOrPersonBase#getNomenclaturalTitle() nomenclaturalTitle})
  44  * or all full names (the strings returned by Person.generateTitle)
  45  * of the persons must exist. A team is a {@link java.util.List list} of persons.
  46  * <P>
  47  * This class corresponds to: <ul>
  48  * <li> Team according to the TDWG ontology
  49  * <li> AgentNames (partially) according to the TCS
  50  * <li> MicroAgent (partially) according to the ABCD schema
  51  * </ul>
  52  *
  53  * @author m.doering
  54  * @version 1.0
  55  * @created 08-Nov-2007 13:06:58
  56  */
  57 @XmlAccessorType(XmlAccessType.FIELD)
  58 @XmlType(name = "Team", propOrder = {
  59         "protectedNomenclaturalTitleCache",
  60     "teamMembers"
  61 })
  62 @XmlRootElement
  63 @Entity
  64 @Indexed(index = "eu.etaxonomy.cdm.model.agent.AgentBase")
  65 @Audited
  66 @Configurable
  67 public class Team extends TeamOrPersonBase<Team> {
  68         private static final long serialVersionUID = 97640416905934622L;
  69         public static final Logger logger = Logger.getLogger(Team.class);
  70
  71     @XmlElement(name = "ProtectedNomenclaturalTitleCache")
  72         private boolean protectedNomenclaturalTitleCache;
  73
  74         //An abreviated name for the team (e. g. in case of nomenclatural authorteams). A non abreviated name for the team (e. g.
  75         //in case of some bibliographical references)
  76     @XmlElementWrapper(name = "TeamMembers")
  77     @XmlElement(name = "TeamMember")
  78     @XmlIDREF
  79     @XmlSchemaType(name = "IDREF")
  80     @IndexColumn(name="sortIndex", base = 0)
  81         @ManyToMany(fetch = FetchType.LAZY)
  82         @Cascade(CascadeType.SAVE_UPDATE)
  83         private List<Person> teamMembers = new ArrayList<Person>();
  84
  85
  86         /**
  87          * Creates a new team instance without any concrete {@link Person members}.
  88          */
  89         static public Team NewInstance(){
  90                 return new Team();
  91         }
  92
  93         /**
  94          * Class constructor (including the cache strategy defined in
  95          * {@link eu.etaxonomy.cdm.strategy.cache.agent.TeamDefaultCacheStrategy TeamDefaultCacheStrategy}).
  96          */
  97         public Team() {
  98                 super();
  99                 this.cacheStrategy = TeamDefaultCacheStrategy.NewInstance();
 100         }
 101
 102         /**
 103          * Returns the list of {@link Person members} belonging to <i>this</i> team.
 104          * A person may be a member of several distinct teams.
 105          */
 106         public List<Person> getTeamMembers(){
 107                 return this.teamMembers;
 108         }
 109
 110         /**
 111          * Adds a new {@link Person person} to <i>this</i> team at the end of the members' list.
 112          *
 113          * @param  person  the person who should be added to the other team members
 114          * @see            #getTeamMembers()
 115          * @see                    Person
 116          */
 117         public void addTeamMember(Person person){
 118                 this.teamMembers.add(person);
 119         }
 120
 121         /**
 122          * Adds a new {@link Person person} to <i>this</i> team
 123          * at the given index place of the members' list. If the person is already
 124          * a member of the list he will be moved to the given index place.
 125          * The index must be a positive integer. If the index is bigger than
 126          * the present number of members the person will be added at the end of the list.
 127          *
 128          * @param  person  the person who should be added to the other team members
 129          * @param  index   the position at which the new person should be placed within the members' list
 130          * @see            #getTeamMembers()
 131          * @see                    Person
 132          */
 133         public void addTeamMember(Person person, int index){
 134                 // TODO is still not fully implemented (range for index!)
 135                 logger.warn("not yet fully implemented (range for index!)");
 136                 int oldIndex = teamMembers.indexOf(person);
 137                 if (oldIndex != -1 ){
 138                         teamMembers.remove(person);
 139                 }
 140                 this.teamMembers.add(index, person);
 141         }
 142
 143         /**
 144          * Removes one person from the list of members of <i>this</i> team.
 145          *
 146          * @param  person  the person who should be deleted from <i>this</i> team
 147          * @see            #getTeamMembers()
 148          */
 149         public void removeTeamMember(Person person){
 150                 this.teamMembers.remove(person);
 151         }
 152
 153         /**
 154          * Generates an identification string for <i>this</i> team according to the strategy
 155          * defined in {@link eu.etaxonomy.cdm.strategy.cache.agent.TeamDefaultCacheStrategy TeamDefaultCacheStrategy}. This string is built
 156          * with the full names of all persons belonging to its (ordered) members' list.
 157          * This method overrides {@link eu.etaxonomy.cdm.model.common.IdentifiableEntity#generateTitle() generateTitle}.
 158          * The result might be kept as {@link eu.etaxonomy.cdm.model.common.IdentifiableEntity#setTitleCache(String) titleCache} if the
 159          * flag {@link eu.etaxonomy.cdm.model.common.IdentifiableEntity#protectedTitleCache protectedTitleCache} is not set.
 160          *
 161          * @return  a string which identifies <i>this</i> team
 162          */
 163 //      @Override
 164 //      public String generateTitle() {
 165 //              return cacheStrategy.getTitleCache(this);
 166 //      }
 167
 168
 169         /**
 170          * Generates or returns the {@link TeamOrPersonBase#getnomenclaturalTitle() nomenclatural identification} string for <i>this</i> team.
 171          * This method overrides {@link TeamOrPersonBase#getNomenclaturalTitle() getNomenclaturalTitle}.
 172          * This string is built with the {@link TeamOrPersonBase#getNomenclaturalTitle() abbreviated names}
 173          * of all persons belonging to its (ordered) members' list if the flag
 174          * {@link #protectedNomenclaturalTitleCache protectedNomenclaturalTitleCache} is not set.
 175          * Otherwise this method returns the present nomenclatural abbreviation.
 176          * In case the string is generated the cache strategy used is defined in
 177          * {@link eu.etaxonomy.cdm.strategy.cache.agent.TeamDefaultCacheStrategy TeamDefaultCacheStrategy}.
 178          * The result might be kept as nomenclatural abbreviation
 179          * by using the {@link #setNomenclaturalTitle(String) setNomenclaturalTitle} method.
 180          *
 181          * @return  a string which identifies <i>this</i> team for nomenclature
 182          */
 183         @Override
 184         @Transient
 185         public String getNomenclaturalTitle() {
 186                 if (protectedNomenclaturalTitleCache == PROTECTED){
 187                         return this.nomenclaturalTitle;
 188                 }
 189                 if (nomenclaturalTitle == null){
 190                         this.nomenclaturalTitle = cacheStrategy.getNomenclaturalTitle(this);
 191                 }
 192                 return nomenclaturalTitle;
 193         }
 194
 195         /**
 196          * Assigns a {@link TeamOrPersonBase#nomenclaturalTitle nomenclatural identification} string to <i>this</i> team
 197          * and protects it from overwriting.
 198          * This method overrides {@link TeamOrPersonBase#setNomenclaturalTitle(String) setNomenclaturalTitle}.
 199          *
 200          * @see  #getNomenclaturalTitle()
 201          * @see  #setNomenclaturalTitle(String, boolean)
 202          */
 203         @Override
 204         public void setNomenclaturalTitle(String nomenclaturalTitle) {
 205                 setNomenclaturalTitle(nomenclaturalTitle, PROTECTED);
 206                 this.nomenclaturalTitle = nomenclaturalTitle;
 207         }
 208
 209         /**
 210          * Assigns a {@link TeamOrPersonBase#nomenclaturalTitle nomenclatural identification} string to <i>this</i> team
 211          * and a protection flag status to this string.
 212          *
 213          * @see  #getNomenclaturalTitle()
 214          */
 215         public void setNomenclaturalTitle(String nomenclaturalTitle, boolean protectedNomenclaturalTitleCache) {
 216                 this.nomenclaturalTitle = nomenclaturalTitle;
 217                 this.protectedNomenclaturalTitleCache = protectedNomenclaturalTitleCache;
 218         }
 219 }