lucene-java-3.5.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/search/results/MutableFacetResultNode.java

   1 package org.apache.lucene.facet.search.results;
   2
   3 import java.io.IOException;
   4 import java.util.ArrayList;
   5 import java.util.List;
   6
   7 import org.apache.lucene.facet.taxonomy.CategoryPath;
   8 import org.apache.lucene.facet.taxonomy.TaxonomyReader;
   9
  10 /**
  11  * Licensed to the Apache Software Foundation (ASF) under one or more
  12  * contributor license agreements.  See the NOTICE file distributed with
  13  * this work for additional information regarding copyright ownership.
  14  * The ASF licenses this file to You under the Apache License, Version 2.0
  15  * (the "License"); you may not use this file except in compliance with
  16  * the License.  You may obtain a copy of the License at
  17  *
  18  *     http://www.apache.org/licenses/LICENSE-2.0
  19  *
  20  * Unless required by applicable law or agreed to in writing, software
  21  * distributed under the License is distributed on an "AS IS" BASIS,
  22  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  23  * See the License for the specific language governing permissions and
  24  * limitations under the License.
  25  */
  26
  27 /**
  28  * Mutable implementation for Result of faceted search for a certain taxonomy node.
  29  *
  30  * @lucene.experimental
  31  */
  32 public class MutableFacetResultNode implements FacetResultNode {
  33
  34   /**
  35    * Empty sub results to be returned when there are no results.
  36    * We never return null, so that code using this can remain simpler.
  37    */
  38   private static final ArrayList<FacetResultNode> EMPTY_SUB_RESULTS = new ArrayList<FacetResultNode>();
  39
  40   private int ordinal;
  41   private CategoryPath label = null;
  42   private double value;
  43   private double residue;
  44   private List<FacetResultNode> subResults;
  45
  46   /**
  47    * Create a Facet Result Node.
  48    *
  49    * @param ordinal
  50    *          ordinal in the taxonomy of the category of this result.
  51    * @param value
  52    *          value this result.
  53    */
  54   public MutableFacetResultNode(int ordinal, double value) {
  55     this(ordinal, value, 0, null, null);
  56   }
  57
  58   /**
  59    * Reset a facet Result Node.
  60    * <p>
  61    * Used at the population of facet results, not intended for regular use by
  62    * applications.
  63    *
  64    * @param ordinal
  65    *          ordinal in the taxonomy of the category of this result.
  66    * @param value
  67    *          value of this result.
  68    */
  69   public void reset(int ordinal, double value) {
  70     this.ordinal = ordinal;
  71     this.value = value;
  72     if (subResults != null) {
  73       subResults.clear();
  74     }
  75     label = null;
  76     residue = 0;
  77   }
  78
  79   /**
  80    * Create a Facet Result Node.
  81    *
  82    * @param ordinal
  83    *          ordinal in the taxonomy of the category of this result.
  84    * @param value
  85    *          value of this result.
  86    * @param residue
  87    *          Value of screened out sub results.
  88    * @param label
  89    *          label of the category path of this result.
  90    * @param subResults
  91    *          - sub results, usually descendants, sometimes child results, of
  92    *          this result - depending on the request.
  93    */
  94   public MutableFacetResultNode(int ordinal, double value, double residue,
  95       CategoryPath label, List<FacetResultNode> subResults) {
  96     this.ordinal = ordinal;
  97     this.value = value;
  98     this.residue = residue;
  99     this.label = label;
 100     this.subResults = subResults;
 101   }
 102
 103   /**
 104    * Create a mutable facet result node from another result node
 105    * @param other other result node to copy from
 106    * @param takeSubResults set to true to take also sub results of other node
 107    */
 108   public MutableFacetResultNode(FacetResultNode other, boolean takeSubResults) {
 109     this(other.getOrdinal(), other.getValue(), other.getResidue(), other
 110         .getLabel(), takeSubResults ? resultsToList(other.getSubResults())
 111         : null);
 112   }
 113
 114   private static List<FacetResultNode> resultsToList(
 115       Iterable<? extends FacetResultNode> subResults) {
 116     if (subResults == null) {
 117       return null;
 118     }
 119     ArrayList<FacetResultNode> res = new ArrayList<FacetResultNode>();
 120     for (FacetResultNode r : subResults) {
 121       res.add(r);
 122     }
 123     return res;
 124   }
 125
 126   @Override
 127   public String toString() {
 128     return toString("");
 129   }
 130
 131   /**
 132    * Number of sub results.
 133    */
 134   private int numSubResults() {
 135     if (subResults == null) {
 136       return 0;
 137     }
 138     return subResults.size();
 139   }
 140
 141   /*
 142    * (non-Javadoc)
 143    *
 144    * @see
 145    * org.apache.lucene.facet.search.results2.FacetResultNode#toString(java.lang.
 146    * String)
 147    */
 148   public String toString(String prefix) {
 149     StringBuilder sb = new StringBuilder(prefix);
 150
 151     sb.append("Facet Result Node with ").append(numSubResults()).append(
 152         " sub result nodes.\n");
 153
 154     // label
 155     sb.append(prefix).append("Name: ").append(getLabel()).append("\n");
 156
 157     // value
 158     sb.append(prefix).append("Value: ").append(value).append("\n");
 159
 160     // residue
 161     sb.append(prefix).append("Residue: ").append(residue).append("\n");
 162
 163     if (subResults != null) {
 164       int i = 0;
 165       for (FacetResultNode subRes : subResults) {
 166         sb.append("\n").append(prefix).append("Subresult #").append(i++)
 167             .append("\n").append(subRes.toString(prefix + "\t"));
 168       }
 169     }
 170
 171     return sb.toString();
 172   }
 173
 174   public final int getOrdinal() {
 175     return ordinal;
 176   }
 177
 178   public final CategoryPath getLabel() {
 179     return label;
 180   }
 181
 182   /**
 183    * Set the label of the category of this result.
 184    * @param label the label to set.
 185    * @see #getLabel()
 186    */
 187   public void setLabel(CategoryPath label) {
 188     this.label = label;
 189   }
 190
 191   public final double getValue() {
 192     return value;
 193   }
 194
 195   /**
 196    * Set the value of this result.
 197    *
 198    * @param value
 199    *          the value to set
 200    * @see #getValue()
 201    */
 202   public void setValue(double value) {
 203     this.value = value;
 204   }
 205
 206   /**
 207    * increase the value for this result.
 208    * @param addedValue the value to add
 209    * @see #getValue()
 210    */
 211   public void increaseValue(double addedValue) {
 212     this.value += addedValue;
 213   }
 214
 215   public final double getResidue() {
 216     return residue;
 217   }
 218
 219   /**
 220    * Set the residue.
 221    * @param residue the residue to set
 222    * @see #getResidue()
 223    */
 224   public void setResidue(double residue) {
 225     this.residue = residue;
 226   }
 227
 228   /**
 229    * increase the residue for this result.
 230    * @param addedResidue the residue to add
 231    * @see #getResidue()
 232    */
 233   public void increaseResidue(double addedResidue) {
 234     this.residue += addedResidue;
 235   }
 236
 237   public final Iterable<? extends FacetResultNode> getSubResults() {
 238     return subResults != null ? subResults : EMPTY_SUB_RESULTS;
 239   }
 240
 241   /**
 242    * Trim sub results to a given size.
 243    * <p>
 244    * Note: Although the {@link #getResidue()} is not guaranteed to be
 245    * accurate, it is worth fixing it, as possible, by taking under account the
 246    * trimmed sub-nodes.
 247    */
 248   public void trimSubResults(int size) {
 249     if (subResults == null || subResults.size() == 0) {
 250       return;
 251     }
 252
 253     ArrayList<FacetResultNode> trimmed = new ArrayList<FacetResultNode>(size);
 254     for (int i = 0; i < subResults.size() && i < size; i++) {
 255       MutableFacetResultNode trimmedNode = toImpl(subResults.get(i));
 256       trimmedNode.trimSubResults(size);
 257       trimmed.add(trimmedNode);
 258     }
 259
 260     /*
 261      * If we are trimming, it means Sampling is in effect and the extra
 262      * (over-sampled) results are being trimmed. Although the residue is not
 263      * guaranteed to be accurate for Sampling, we try our best to fix it.
 264      * The node's residue now will take under account the sub-nodes we're
 265      * trimming.
 266      */
 267     for (int i = size; i < subResults.size(); i++) {
 268       increaseResidue(subResults.get(i).getValue());
 269     }
 270
 271     subResults = trimmed;
 272   }
 273
 274   /**
 275    * Set the sub results.
 276    * @param subResults the sub-results to set
 277    */
 278   public void setSubResults(List<FacetResultNode> subResults) {
 279     this.subResults = subResults;
 280   }
 281
 282   /**
 283    * Append a sub result (as last).
 284    * @param subRes sub-result to be appended
 285    */
 286   public void appendSubResult(FacetResultNode subRes) {
 287     if (subResults == null) {
 288       subResults = new ArrayList<FacetResultNode>();
 289     }
 290     subResults.add(subRes);
 291   }
 292
 293   /**
 294    * Insert sub result (as first).
 295    * @param subRes sub-result to be inserted
 296    */
 297   public void insertSubResult(FacetResultNode subRes) {
 298     if (subResults == null) {
 299       subResults = new ArrayList<FacetResultNode>();
 300     }
 301     subResults.add(0, subRes);
 302   }
 303
 304   /*
 305    * (non-Javadoc)
 306    *
 307    * @see
 308    * org.apache.lucene.facet.search.results.FacetResultNode#getLabel(org.apache.lucene
 309    * .facet.taxonomy.TaxonomyReader)
 310    */
 311   public final CategoryPath getLabel(TaxonomyReader taxonomyReader)
 312       throws IOException {
 313     if (label == null) {
 314       label = taxonomyReader.getPath(ordinal);
 315     }
 316     return label;
 317   }
 318
 319   /*
 320    * (non-Javadoc)
 321    *
 322    * @see org.apache.lucene.facet.search.results.FacetResultNode#getNumSubResults()
 323    */
 324   public final int getNumSubResults() {
 325     return subResults == null ? 0 : subResults.size();
 326   }
 327
 328   /**
 329    * Internal utility: turn a result node into an implementation class
 330    * with richer API that allows modifying it.
 331    * <p>
 332    * In case that input result node is already of an implementation
 333    * class only casting is done, but in any case we pay the price
 334    * of checking "instance of".
 335    * @param frn facet result node to be turned into an implementation class object
 336    */
 337   public static MutableFacetResultNode toImpl(FacetResultNode frn) {
 338     if (frn instanceof MutableFacetResultNode) {
 339       return (MutableFacetResultNode) frn;
 340     }
 341     return new MutableFacetResultNode(frn, true);
 342   }
 343
 344 }