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   }