merged 1.1 branch into head

[mir.git] / source / mircoders / search / SearchTerm.java

diff --git a/source/mircoders/search/SearchTerm.java b/source/mircoders/search/SearchTerm.java
index 6ed5079..af2de1c 100755 (executable)
--- a/source/mircoders/search/SearchTerm.java
+++ b/source/mircoders/search/SearchTerm.java
@@ -31,11 +31,42 @@
 package mircoders.search;
 
 import java.util.Map;
+
 import javax.servlet.http.HttpServletRequest;
+
 import mir.entity.Entity;
+
 import org.apache.lucene.document.Document;
 
+/**
+ * The SearchTerm class attempts to encapsulate the relationships
+ * between:
+ * <ul>
+ * <li>A fields or property of Content Entities</li> 
+ * <li>A field of Lucene Documents</li>
+ * <li>An HTTP Query Parameter</li>
+ * <li>And a bit of HTML on a Search Results Page</li>
+ * </ul>
+ * The  basic  idea  is that  how  you  index,  query, and  display  a
+ * particular field in a resource are all intimately related, possibly
+ * more  so  than how  you  index two  different  fields  of the  same
+ * resource.
+ *
+ * <p>Instances of classes implementing SearchTerm are created when a Mir
+ * content entity  is indexed by the  IndexingProducerNode Class.  The
+ * index  method of  each class  is called  in turn  to add  a  bit of
+ * information  to the  Lucene documents  which will  be added  to the
+ * index after it is created  and all its fields specified.  Instances
+ * of the same classes are created by ServletModuleOpenIndy so that it
+ * can construct a  query to match against the  lucene index, here the
+ * makeTerm methods are called in  turn to pick out the parameter they
+ * want from  the request and then construct  the appropriate fragment
+ * of lucene query, which are ultimately concatenated together.  These
+ * classes  are  also  used  to  return  appropriate  template  models
+ * representing any hits to be displayed as a result of processing the
+ * query.</p>
 
+ */
 abstract public class SearchTerm {
   protected String  partOfEntity;
   protected String  paramName;