cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/description/FeatureTree.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.ArrayList;
  13 import java.util.List;
  14 import java.util.UUID;
  15
  16 import javax.persistence.Entity;
  17 import javax.persistence.FetchType;
  18 import javax.persistence.OneToOne;
  19 import javax.persistence.Transient;
  20 import javax.xml.bind.annotation.XmlAccessType;
  21 import javax.xml.bind.annotation.XmlAccessorType;
  22 import javax.xml.bind.annotation.XmlElement;
  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.envers.Audited;
  32 import org.hibernate.search.annotations.Indexed;
  33
  34 import eu.etaxonomy.cdm.model.common.TermBase;
  35
  36 /**
  37  * The class to arrange {@link Feature features} (characters) in a tree structure.
  38  * Feature trees are essential as interactive multiple-access keys for
  39  * determination process and for systematical output arrangement of
  40  * {@link DescriptionElementBase description elements} according to different goals but may also be used
  41  * to define flat feature subsets for filtering purposes.<BR>
  42  * A feature tree is build on {@link FeatureNode feature nodes}.
  43  * <P>
  44  * This class corresponds partially to ConceptTreeDefType according to the SDD
  45  * schema.
  46  * <P>
  47  * Note: The tree structure of features used for purposes described above has
  48  * nothing in common with the possible hierarchical structure of features
  49  * depending on their grade of precision.
  50  *
  51  * @see         MediaKey
  52  * @author  m.doering
  53  * @version 1.0
  54  * @created 08-Nov-2007 13:06:16
  55  */
  56 @XmlAccessorType(XmlAccessType.FIELD)
  57 @XmlType(name = "FeatureTree", propOrder = {
  58     "descriptionSeparated",
  59     "root"
  60 })
  61 @XmlRootElement(name = "FeatureTree")
  62 @Entity
  63 @Indexed(index = "eu.etaxonomy.cdm.model.description.FeatureTree")
  64 @Audited
  65 public class FeatureTree extends TermBase {
  66         private static final long serialVersionUID = -6713834139003172735L;
  67         @SuppressWarnings("unused")
  68         private static final Logger logger = Logger.getLogger(FeatureTree.class);
  69         //private Set<FeatureNode> nodes = new HashSet<FeatureNode>();
  70
  71         @XmlElement(name = "Root")
  72         @OneToOne(fetch = FetchType.LAZY)
  73         @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE})
  74         private FeatureNode root;
  75
  76         @XmlElement(name = "IsDescriptionSeparated")
  77         private boolean descriptionSeparated = false;
  78
  79         /**
  80          * Class constructor: creates a new feature tree instance with an empty
  81          * {@link #getRoot() root node}.
  82          */
  83         protected FeatureTree() {
  84                 super();
  85                 root = FeatureNode.NewInstance();
  86         }
  87
  88         /**
  89          * Creates a new feature tree instance with an empty {@link #getRoot() root node}.
  90          *
  91          * @see #NewInstance(UUID)
  92          * @see #NewInstance(List)
  93          */
  94         public static FeatureTree NewInstance(){
  95                 return new FeatureTree();
  96         }
  97
  98         /**
  99          * Creates a new feature tree instance with an empty {@link #getRoot() root node}
 100          * and assigns to the new feature tree the given
 101          * UUID (universally unique identifier).
 102          *
 103          * @param       uuid    the universally unique identifier
 104          * @see                         #NewInstance()
 105          * @see                         #NewInstance(List)
 106          */
 107         public static FeatureTree NewInstance(UUID uuid){
 108                 FeatureTree result =  new FeatureTree();
 109                 result.setUuid(uuid);
 110                 return result;
 111         }
 112
 113         /**
 114          * Creates a new feature tree instance with a {@link #getRoot() root node}
 115          * the children of which are the feature nodes build on the base of the
 116          * given list of {@link Feature features}. This corresponds to a flat feature tree.
 117          * For each feature within the list a new {@link FeatureNode feature node} without
 118          * children nodes will be created.
 119          *
 120          * @param       featureList     the feature list
 121          * @see                                 #NewInstance()
 122          * @see                                 #NewInstance(UUID)
 123          */
 124         public static FeatureTree NewInstance(List<Feature> featureList){
 125                 FeatureTree result =  new FeatureTree();
 126                 FeatureNode root = result.getRoot();
 127
 128                 for (Feature feature : featureList){
 129                         FeatureNode child = FeatureNode.NewInstance(feature);
 130                         root.addChild(child);
 131                 }
 132
 133                 return result;
 134         }
 135
 136         // Delete the isDescriptionSeparated flag ??
 137         /**
 138          * Returns the boolean value of the flag indicating whether the
 139          * {@link DescriptionElementBase description elements} associated with the {@link Feature features}
 140          * belonging to <i>this</i> feature tree should be treated separately (true)
 141          * or not (false).
 142          *
 143          * @return  the boolean value of the isDescriptionSeparated flag
 144          */
 145         public boolean isDescriptionSeparated() {
 146                 return descriptionSeparated;
 147         }
 148
 149         /**
 150          * @see #isDescriptionSeparated()
 151          */
 152         public void setDescriptionSeparated(boolean descriptionSeperated) {
 153                 this.descriptionSeparated = descriptionSeperated;
 154         }
 155
 156 //      @OneToMany
 157 //      @Cascade({CascadeType.SAVE_UPDATE})
 158 //      public Set<FeatureNode> getNodes() {
 159 //              return nodes;
 160 //      }
 161 //      public void setNodes(Set<FeatureNode> nodes) {
 162 //              this.nodes = nodes;
 163 //      }
 164
 165         /**
 166          * Returns the topmost {@link FeatureNode feature node} (root node) of <i>this</i>
 167          * feature tree. The root node does not have any parent. Since feature nodes
 168          * recursively point to their child nodes the complete feature tree is
 169          * defined by its root node.
 170          */
 171         public FeatureNode getRoot() {
 172                 return root;
 173         }
 174         /**
 175          * @see #getRoot()
 176          */
 177         public void setRoot(FeatureNode root) {
 178                 this.root = root;
 179         }
 180
 181         /**
 182          * Returns the (ordered) list of {@link FeatureNode feature nodes} which are immediate
 183          * children of the root node of <i>this</i> feature tree.
 184          */
 185         @Transient
 186         public List<FeatureNode> getRootChildren(){
 187                 List<FeatureNode> result = new ArrayList<FeatureNode>();
 188                 result.addAll(root.getChildren());
 189                 return result;
 190         }
 191
 192 }