cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/reference/BookSection.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.reference;
  11
  12
  13 import javax.persistence.Entity;
  14 import javax.persistence.Transient;
  15 import javax.xml.bind.annotation.XmlAccessType;
  16 import javax.xml.bind.annotation.XmlAccessorType;
  17 import javax.xml.bind.annotation.XmlRootElement;
  18 import javax.xml.bind.annotation.XmlType;
  19
  20 import org.apache.log4j.Logger;
  21 import org.hibernate.envers.Audited;
  22 import org.hibernate.search.annotations.Indexed;
  23 import org.springframework.beans.factory.annotation.Configurable;
  24
  25 import eu.etaxonomy.cdm.model.agent.TeamOrPersonBase;
  26 import eu.etaxonomy.cdm.model.common.CdmBase;
  27 import eu.etaxonomy.cdm.model.common.TimePeriod;
  28 import eu.etaxonomy.cdm.strategy.cache.reference.BookSectionDefaultCacheStrategy;
  29 import eu.etaxonomy.cdm.strategy.cache.reference.INomenclaturalReferenceCacheStrategy;
  30
  31 /**
  32  * This class represents isolated sections (parts or chapters) within a {@link Book book}.
  33  * <P>
  34  * This class corresponds, according to the TDWG ontology, to the publication type
  35  * term (from PublicationTypeTerm): "BookSection".
  36  *
  37  * @author m.doering
  38  * @version 1.0
  39  * @created 08-Nov-2007 13:06:14
  40  */
  41 @XmlAccessorType(XmlAccessType.FIELD)
  42 @XmlType(name = "BookSection", propOrder = {
  43 //    "inBook"
  44 })
  45 @XmlRootElement(name = "BookSection")
  46 @Entity
  47 @Indexed(index = "eu.etaxonomy.cdm.model.reference.ReferenceBase")
  48 @Audited
  49 @Configurable
  50 @Deprecated
  51 public class BookSection extends SectionBase<INomenclaturalReferenceCacheStrategy<BookSection>> implements INomenclaturalReference, Cloneable {
  52         private static final long serialVersionUID = -1066199749700092670L;
  53         private static final Logger logger = Logger.getLogger(BookSection.class);
  54
  55 //    @XmlElement(name = "InBook")
  56 //    @XmlIDREF
  57 //    @XmlSchemaType(name = "IDREF")
  58 //    @ManyToOne(fetch = FetchType.LAZY)
  59 //    @IndexedEmbedded
  60 //    @Cascade(CascadeType.SAVE_UPDATE)
  61 //      private Book inBook;
  62
  63 //    @XmlTransient
  64 //    @Transient
  65 //      private NomenclaturalReferenceHelper nomRefBase = NomenclaturalReferenceHelper.NewInstance(this);
  66
  67
  68         /**
  69          * Class constructor: creates a new empty book section instance only containing the
  70          * {@link eu.etaxonomy.cdm.strategy.cache.reference.BookSectionDefaultCacheStrategy default cache strategy}.
  71          *
  72          * @see eu.etaxonomy.cdm.strategy.cache.reference.BookSectionDefaultCacheStrategy
  73          */
  74         protected BookSection(){
  75                 super();
  76                 this.type = ReferenceType.BookSection;
  77                 this.cacheStrategy = BookSectionDefaultCacheStrategy.NewInstance();
  78         }
  79
  80
  81         /**
  82          * Creates a new empty book section instance only containing the
  83          * {@link eu.etaxonomy.cdm.strategy.cache.reference.BookSectionDefaultCacheStrategy default cache strategy}.
  84          *
  85          * @see #NewInstance(Book, TeamOrPersonBase, String, String)
  86          * @see eu.etaxonomy.cdm.strategy.cache.reference.BookSectionDefaultCacheStrategy
  87          */
  88         public static BookSection NewInstance(){
  89                 BookSection result = new BookSection();
  90                 return result;
  91         }
  92
  93         /**
  94          * Creates a new book section instance with its given book, title, pages and
  95          * author (team) and its {@link eu.etaxonomy.cdm.strategy.cache.reference.BookSectionDefaultCacheStrategy default cache strategy}.
  96          *
  97          * @param       inBook                  the book <i>this</i> book section belongs to
  98          * @param       author                  the team or person who wrote <i>this</i> book section
  99          * @param       sectionTitle    the string representing the title of <i>this</i>
 100          *                                                      book section
 101          * @param       pages                   the string representing the pages in the book
 102          *                                                      where <i>this</i> book section can be found
 103          * @see                                         #NewInstance()
 104          * @see                                         eu.etaxonomy.cdm.strategy.cache.reference.BookSectionDefaultCacheStrategy
 105          */
 106         public static BookSection NewInstance(Book inBook, TeamOrPersonBase author, String sectionTitle, String pages ){
 107                 BookSection result = new BookSection();
 108                 result.setInBook(inBook);
 109                 result.setTitle(sectionTitle);
 110                 result.setPages(pages);
 111                 result.setAuthorTeam(author);
 112                 return result;
 113         }
 114
 115
 116         /**
 117          * Returns the {@link Book book} <i>this</i> book section belongs to.
 118          *
 119          * @return  the book containing <i>this</i> book section
 120          * @see         Book
 121          */
 122         @Transient
 123         public Book getInBook(){
 124                 if (inReference == null){
 125                         return null;
 126                 }
 127                 if (! this.inReference.isInstanceOf(Book.class)){
 128                         throw new IllegalStateException("The in-reference of a BookSection may only be of type Book");
 129                 }
 130                 return CdmBase.deproxy(this.inReference,Book.class);
 131         }
 132
 133         /**
 134          * @see #getInBook()
 135          */
 136         public void setInBook(Book inBook){
 137                 this.inReference = inBook;
 138         }
 139
 140
 141         /**
 142          * Returns a formatted string containing the entire reference citation,
 143          * including authors, title, book authors, book title, pages, corresponding to <i>this</i>
 144          * book section.<BR>
 145          * This method overrides the generic and inherited getCitation method
 146          * from {@link StrictReferenceBase StrictReferenceBase}.
 147          *
 148          * @see  #getNomenclaturalCitation(String)
 149          * @see  StrictReferenceBase#getCitation()
 150          */
 151 //      @Transient
 152 //      @Override
 153 //      public String getCitation(){
 154 //              return nomRefBase.getCitation();
 155 //      }
 156
 157         /**
 158          * Returns a formatted string containing the entire citation used for
 159          * nomenclatural purposes based on <i>this</i> book section - including
 160          * (abbreviated) book title, book authors, book section title but not its
 161          * authors - and on the given details.
 162          *
 163          * @param  microReference       the string with the details (generally pages)
 164          *                                                      within t<i>this</i> book section
 165          * @return                                      the formatted string representing the
 166          *                                                      nomenclatural citation
 167          * @see                                         #getCitation()
 168          */
 169         @Transient
 170         public String getNomenclaturalCitation(String microReference) {
 171                 if (cacheStrategy == null){
 172                         logger.warn("No CacheStrategy defined for "+ this.getClass() + ": " + this.getUuid());
 173                         return null;
 174                 }else{
 175                         return cacheStrategy.getNomenclaturalCitation(this,microReference);
 176                 }
 177         }
 178
 179          /**
 180           * If the publication date of a book section and it's inBook do differ this is usually
 181          * caused by the fact that a book has been published during a period, because originally
 182          * it consisted of several parts that only later where put together to one book.
 183          * If so, the book section's publication date may be a point in time (year or month of year)
 184          * whereas the books publication date may be a period of several years.
 185          * Therefore a valid nomenclatural reference string should use the book sections
 186          * publication date rather then the book's publication date.
 187          *
 188          * @see         StrictReferenceBase#getDatePublished()
 189          **/
 190          @Transient
 191          @Override
 192          // This method overrides StrictReferenceBase.getDatePublished() only to have
 193          // a specific Javadoc for BookSection.getDatePublished().
 194         public TimePeriod getDatePublished(){
 195                 return super.getDatePublished();
 196         }
 197
 198
 199         /**
 200          * Generates, according to the {@link strategy.cache.reference.BookSectionDefaultCacheStrategy default cache strategy}
 201          * assigned to <i>this</i> book section, a string that identifies <i>this</i>
 202          * book section and returns it. This string may be stored in the inherited
 203          * {@link common.IdentifiableEntity#getTitleCache() titleCache} attribute.<BR>
 204          * This method overrides the generic and inherited generateTitle method
 205          * from {@link ReferenceBase ReferenceBase}.
 206          *
 207          * @return  the string identifying <i>this</i> book section
 208          * @see         #getCitation()
 209          * @see         eu.etaxonomy.cdm.model.common.IdentifiableEntity#getTitleCache()
 210          * @see         eu.etaxonomy.cdm.model.common.IdentifiableEntity#generateTitle()
 211          */
 212 //      @Override
 213 //      public String generateTitle(){
 214 //              return nomRefBase.generateTitle();
 215 //      }
 216
 217
 218
 219         /**
 220          * Clones <i>this</i> book section. This is a shortcut that enables to
 221          * create a new instance that differs only slightly from <i>this</i> book
 222          * section by modifying only some of the attributes.<BR>
 223          * This method overrides the clone method from {@link StrictReferenceBase StrictReferenceBase}.
 224          *
 225          * @see StrictReferenceBase#clone()
 226          * @see eu.etaxonomy.cdm.model.media.IdentifiableMediaEntity#clone()
 227          * @see java.lang.Object#clone()
 228          */
 229         @Override
 230         public Object clone(){
 231                 BookSection result = (BookSection)super.clone();
 232                 result.cacheStrategy = BookSectionDefaultCacheStrategy.NewInstance();
 233                 //no changes to: inBook
 234                 return result;
 235         }
 236 }