1 package org.apache.lucene.search;
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
20 import java.io.Serializable;
21 import java.util.ArrayList;
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
29 public Explanation() {}
31 public Explanation(float value, String description) {
33 this.description = description;
37 * Indicates whether or not this Explanation models a good match.
40 * By default, an Explanation represents a "match" if the value is positive.
44 public boolean isMatch() {
45 return (0.0f < getValue());
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; }
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;
63 * A short one line summary which should contain all high level
64 * information about this Explanation, without the "Details"
66 protected String getSummary() {
67 return getValue() + " = " + getDescription();
70 /** The sub-nodes of this explanation node. */
71 public Explanation[] getDetails() {
74 return details.toArray(new Explanation[0]);
77 /** Adds a sub-node to this explanation node. */
78 public void addDetail(Explanation detail) {
80 details = new ArrayList<Explanation>();
84 /** Render an explanation as text. */
86 public String toString() {
89 protected String toString(int depth) {
90 StringBuilder buffer = new StringBuilder();
91 for (int i = 0; i < depth; i++) {
94 buffer.append(getSummary());
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));
104 return buffer.toString();
108 /** Render an explanation as HTML. */
109 public String toHtml() {
110 StringBuilder buffer = new StringBuilder();
111 buffer.append("<ul>\n");
113 buffer.append("<li>");
114 buffer.append(getSummary());
115 buffer.append("<br />\n");
117 Explanation[] details = getDetails();
118 if (details != null) {
119 for (int i = 0 ; i < details.length; i++) {
120 buffer.append(details[i].toHtml());
124 buffer.append("</li>\n");
125 buffer.append("</ul>\n");
127 return buffer.toString();
131 * Small Util class used to pass both an idf factor as well as an
132 * explanation for that factor.
134 * This class will likely be held on a {@link Weight}, so be aware
135 * before storing any large or un-serializable fields.
138 public static abstract class IDFExplanation implements Serializable {
140 * @return the idf factor
142 public abstract float getIdf();
144 * This should be calculated lazily if possible.
146 * @return the explanation for the idf factor.
148 public abstract String explain();