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         @XmlIDREF
  73         @XmlSchemaType(name="IDREF")
  74         @OneToOne(fetch = FetchType.LAZY)
  75         @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE})
  76         private FeatureNode root;
  77
  78         @XmlElement(name = "IsDescriptionSeparated")
  79         private boolean descriptionSeparated = false;
  80
  81         /**
  82          * Class constructor: creates a new feature tree instance with an empty
  83          * {@link #getRoot() root node}.
  84          */
  85         protected FeatureTree() {
  86                 super();
  87                 root = FeatureNode.NewInstance();
  88         }
  89
  90         /**
  91          * Creates a new feature tree instance with an empty {@link #getRoot() root node}.
  92          *
  93          * @see #NewInstance(UUID)
  94          * @see #NewInstance(List)
  95          */
  96         public static FeatureTree NewInstance(){
  97                 return new FeatureTree();
  98         }
  99
 100         /**
 101          * Creates a new feature tree instance with an empty {@link #getRoot() root node}
 102          * and assigns to the new feature tree the given
 103          * UUID (universally unique identifier).
 104          *
 105          * @param       uuid    the universally unique identifier
 106          * @see                         #NewInstance()
 107          * @see                         #NewInstance(List)
 108          */
 109         public static FeatureTree NewInstance(UUID uuid){
 110                 FeatureTree result =  new FeatureTree();
 111                 result.setUuid(uuid);
 112                 return result;
 113         }
 114
 115         /**
 116          * Creates a new feature tree instance with a {@link #getRoot() root node}
 117          * the children of which are the feature nodes build on the base of the
 118          * given list of {@link Feature features}. This corresponds to a flat feature tree.
 119          * For each feature within the list a new {@link FeatureNode feature node} without
 120          * children nodes will be created.
 121          *
 122          * @param       featureList     the feature list
 123          * @see                                 #NewInstance()
 124          * @see                                 #NewInstance(UUID)
 125          */
 126         public static FeatureTree NewInstance(List<Feature> featureList){
 127                 FeatureTree result =  new FeatureTree();
 128                 FeatureNode root = result.getRoot();
 129
 130                 for (Feature feature : featureList){
 131                         FeatureNode child = FeatureNode.NewInstance(feature);
 132                         root.addChild(child);
 133                 }
 134
 135                 return result;
 136         }
 137
 138         // Delete the isDescriptionSeparated flag ??
 139         /**
 140          * Returns the boolean value of the flag indicating whether the
 141          * {@link DescriptionElementBase description elements} associated with the {@link Feature features}
 142          * belonging to <i>this</i> feature tree should be treated separately (true)
 143          * or not (false).
 144          *
 145          * @return  the boolean value of the isDescriptionSeparated flag
 146          */
 147         public boolean isDescriptionSeparated() {
 148                 return descriptionSeparated;
 149         }
 150
 151         /**
 152          * @see #isDescriptionSeparated()
 153          */
 154         public void setDescriptionSeparated(boolean descriptionSeperated) {
 155                 this.descriptionSeparated = descriptionSeperated;
 156         }
 157
 158 //      @OneToMany
 159 //      @Cascade({CascadeType.SAVE_UPDATE})
 160 //      public Set<FeatureNode> getNodes() {
 161 //              return nodes;
 162 //      }
 163 //      public void setNodes(Set<FeatureNode> nodes) {
 164 //              this.nodes = nodes;
 165 //      }
 166
 167         /**
 168          * Returns the topmost {@link FeatureNode feature node} (root node) of <i>this</i>
 169          * feature tree. The root node does not have any parent. Since feature nodes
 170          * recursively point to their child nodes the complete feature tree is
 171          * defined by its root node.
 172          */
 173         public FeatureNode getRoot() {
 174                 return root;
 175         }
 176         /**
 177          * @see #getRoot()
 178          */
 179         public void setRoot(FeatureNode root) {
 180                 this.root = root;
 181         }
 182
 183         /**
 184          * Returns the (ordered) list of {@link FeatureNode feature nodes} which are immediate
 185          * children of the root node of <i>this</i> feature tree.
 186          */
 187         @Transient
 188         public List<FeatureNode> getRootChildren(){
 189                 List<FeatureNode> result = new ArrayList<FeatureNode>();
 190                 result.addAll(root.getChildren());
 191                 return result;
 192         }
 193
 194 }