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