lucene-java-3.5.0/lucene/src/java/org/apache/lucene/search/Explanation.java

   1 package org.apache.lucene.search;
   2
   3 /**
   4  * Licensed to the Apache Software Foundation (ASF) under one or more
   5  * contributor license agreements.  See the NOTICE file distributed with
   6  * this work for additional information regarding copyright ownership.
   7  * The ASF licenses this file to You under the Apache License, Version 2.0
   8  * (the "License"); you may not use this file except in compliance with
   9  * the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 import java.io.Serializable;
  21 import java.util.ArrayList;
  22
  23 /** Expert: Describes the score computation for document and query. */
  24 public class Explanation implements java.io.Serializable {
  25   private float value;                            // the value of this node
  26   private String description;                     // what it represents
  27   private ArrayList<Explanation> details;                      // sub-explanations
  28
  29   public Explanation() {}
  30
  31   public Explanation(float value, String description) {
  32     this.value = value;
  33     this.description = description;
  34   }
  35
  36   /**
  37    * Indicates whether or not this Explanation models a good match.
  38    *
  39    * <p>
  40    * By default, an Explanation represents a "match" if the value is positive.
  41    * </p>
  42    * @see #getValue
  43    */
  44   public boolean isMatch() {
  45     return (0.0f < getValue());
  46   }
  47
  48
  49
  50   /** The value assigned to this explanation node. */
  51   public float getValue() { return value; }
  52   /** Sets the value assigned to this explanation node. */
  53   public void setValue(float value) { this.value = value; }
  54
  55   /** A description of this explanation node. */
  56   public String getDescription() { return description; }
  57   /** Sets the description of this explanation node. */
  58   public void setDescription(String description) {
  59     this.description = description;
  60   }
  61
  62   /**
  63    * A short one line summary which should contain all high level
  64    * information about this Explanation, without the "Details"
  65    */
  66   protected String getSummary() {
  67     return getValue() + " = " + getDescription();
  68   }
  69
  70   /** The sub-nodes of this explanation node. */
  71   public Explanation[] getDetails() {
  72     if (details == null)
  73       return null;
  74     return details.toArray(new Explanation[0]);
  75   }
  76
  77   /** Adds a sub-node to this explanation node. */
  78   public void addDetail(Explanation detail) {
  79     if (details == null)
  80       details = new ArrayList<Explanation>();
  81     details.add(detail);
  82   }
  83
  84   /** Render an explanation as text. */
  85   @Override
  86   public String toString() {
  87     return toString(0);
  88   }
  89   protected String toString(int depth) {
  90     StringBuilder buffer = new StringBuilder();
  91     for (int i = 0; i < depth; i++) {
  92       buffer.append("  ");
  93     }
  94     buffer.append(getSummary());
  95     buffer.append("\n");
  96
  97     Explanation[] details = getDetails();
  98     if (details != null) {
  99       for (int i = 0 ; i < details.length; i++) {
 100         buffer.append(details[i].toString(depth+1));
 101       }
 102     }
 103
 104     return buffer.toString();
 105   }
 106
 107
 108   /** Render an explanation as HTML. */
 109   public String toHtml() {
 110     StringBuilder buffer = new StringBuilder();
 111     buffer.append("<ul>\n");
 112
 113     buffer.append("<li>");
 114     buffer.append(getSummary());
 115     buffer.append("<br />\n");
 116
 117     Explanation[] details = getDetails();
 118     if (details != null) {
 119       for (int i = 0 ; i < details.length; i++) {
 120         buffer.append(details[i].toHtml());
 121       }
 122     }
 123
 124     buffer.append("</li>\n");
 125     buffer.append("</ul>\n");
 126
 127     return buffer.toString();
 128   }
 129
 130   /**
 131    * Small Util class used to pass both an idf factor as well as an
 132    * explanation for that factor.
 133    *
 134    * This class will likely be held on a {@link Weight}, so be aware
 135    * before storing any large or un-serializable fields.
 136    *
 137    */
 138   public static abstract class IDFExplanation implements Serializable {
 139     /**
 140      * @return the idf factor
 141      */
 142     public abstract float getIdf();
 143     /**
 144      * This should be calculated lazily if possible.
 145      *
 146      * @return the explanation for the idf factor.
 147      */
 148     public abstract String explain();
 149   }
 150 }