adding doc on search framework

diff --git a/source/mircoders/search/AudioSearchTerm.java b/source/mircoders/search/AudioSearchTerm.java
index 1f67847..b68ee0b 100755 (executable)
--- a/source/mircoders/search/AudioSearchTerm.java
+++ b/source/mircoders/search/AudioSearchTerm.java
@@ -45,6 +45,9 @@ import mircoders.storage.DatabaseAudio;
 import org.apache.lucene.document.Document;
 import org.apache.lucene.document.Field;
 
+/**
+ * indexes whether an Enity has audio 
+ */
 public class AudioSearchTerm extends SearchTerm{
   public AudioSearchTerm() {
     super(null, "search_hasAudio", "hasAudio", null, "hasAudio");

diff --git a/source/mircoders/search/ContentSearchTerm.java b/source/mircoders/search/ContentSearchTerm.java
index 9b74640..2e52ebd 100755 (executable)
--- a/source/mircoders/search/ContentSearchTerm.java
+++ b/source/mircoders/search/ContentSearchTerm.java
@@ -40,7 +40,10 @@ import mir.entity.Entity;
 import org.apache.lucene.document.Document;
 import org.apache.lucene.document.Field;
 
-
+/**
+ * Tokenizes a string field in an Entity and indexes
+ * it, but does not store it for retrieval (used for content_data) 
+ */
 public class ContentSearchTerm extends SearchTerm{
   protected ContentSearchTerm() {
   }

diff --git a/source/mircoders/search/ImagesSearchTerm.java b/source/mircoders/search/ImagesSearchTerm.java
index ee404ec..55cde5c 100755 (executable)
--- a/source/mircoders/search/ImagesSearchTerm.java
+++ b/source/mircoders/search/ImagesSearchTerm.java
@@ -47,7 +47,11 @@ import mircoders.storage.DatabaseImages;
 import org.apache.lucene.document.Document;
 import org.apache.lucene.document.Field;
 
-
+/**
+ * Indexes whether or not an Entity has associated
+ * images, and also stores urls of those images for 
+ * retrieval in the search results
+ */
 public class ImagesSearchTerm extends SearchTerm{
   public ImagesSearchTerm() {
     super (null, "search_hasImages", "hasImages", "images", "images");

diff --git a/source/mircoders/search/KeywordSearchTerm.java b/source/mircoders/search/KeywordSearchTerm.java
index 3486f71..a07dfe5 100755 (executable)
--- a/source/mircoders/search/KeywordSearchTerm.java
+++ b/source/mircoders/search/KeywordSearchTerm.java
@@ -40,7 +40,11 @@ import org.apache.lucene.document.Document;
 import org.apache.lucene.document.Field;
 
 
-
+/**
+ * indexes a field and stores it for retrieval, but
+ * does not tokenize it.  useful for things 
+ * like strings representing
+ */
 public class KeywordSearchTerm extends SearchTerm{
 
 

diff --git a/source/mircoders/search/MediaSearchTerm.java b/source/mircoders/search/MediaSearchTerm.java
index e2f4561..5f38aeb 100755 (executable)
--- a/source/mircoders/search/MediaSearchTerm.java
+++ b/source/mircoders/search/MediaSearchTerm.java
@@ -39,7 +39,9 @@ import mir.storage.DatabaseFailure;
 
 import org.apache.lucene.document.Document;
 
-
+/**
+ * not used
+ */
 public class MediaSearchTerm extends SearchTerm{
   public MediaSearchTerm() {
     super(null, "search_hasMedia", "", null, "");

diff --git a/source/mircoders/search/SearchTerm.java b/source/mircoders/search/SearchTerm.java
index 6e7bdca..af2de1c 100755 (executable)
--- a/source/mircoders/search/SearchTerm.java
+++ b/source/mircoders/search/SearchTerm.java
@@ -38,7 +38,35 @@ 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;

diff --git a/source/mircoders/search/TextSearchTerm.java b/source/mircoders/search/TextSearchTerm.java
index 3b5cd44..61fe91a 100755 (executable)
--- a/source/mircoders/search/TextSearchTerm.java
+++ b/source/mircoders/search/TextSearchTerm.java
@@ -39,7 +39,10 @@ import mir.entity.Entity;
 import org.apache.lucene.document.Document;
 import org.apache.lucene.document.Field;
 
-
+/**
+ * tokenizes a string field in an Entity and indexes
+ * it, and stores it for retrieval (used for description)
+ */
 public class TextSearchTerm extends SearchTerm{
   public TextSearchTerm(String anEntityPart,String aParamName,String aMatchField,String aDataField, String aTemplateVariable){
     partOfEntity = anEntityPart;

diff --git a/source/mircoders/search/TopicSearchTerm.java b/source/mircoders/search/TopicSearchTerm.java
index 113fbd5..70ba1f4 100755 (executable)
--- a/source/mircoders/search/TopicSearchTerm.java
+++ b/source/mircoders/search/TopicSearchTerm.java
@@ -42,7 +42,10 @@ import mircoders.storage.DatabaseContentToTopics;
 import org.apache.lucene.document.Document;
 import org.apache.lucene.document.Field;
 
-
+/**
+ * used by indexing and querying 
+ * documents based on Topic
+ */
 public class TopicSearchTerm extends SearchTerm{
   public TopicSearchTerm() {
     super(null, "search_topic", "topic", null, null);

diff --git a/source/mircoders/search/UnIndexedSearchTerm.java b/source/mircoders/search/UnIndexedSearchTerm.java
index ced2c02..4e48a4b 100755 (executable)
--- a/source/mircoders/search/UnIndexedSearchTerm.java
+++ b/source/mircoders/search/UnIndexedSearchTerm.java
@@ -39,7 +39,10 @@ import org.apache.lucene.document.Document;
 import org.apache.lucene.document.Field;
 
 
-
+/**
+ * Stores some metatdata for retrieval with a 
+ * hit (for example a URL)  
+ */
 public class UnIndexedSearchTerm extends SearchTerm{
   public UnIndexedSearchTerm(String anEntityPart,String aParamName,String aMatchField,String aDataField, String aTemplateVariable){
     partOfEntity = anEntityPart;

diff --git a/source/mircoders/search/UnStoredSearchTerm.java b/source/mircoders/search/UnStoredSearchTerm.java
index 55db890..09b6c23 100755 (executable)
--- a/source/mircoders/search/UnStoredSearchTerm.java
+++ b/source/mircoders/search/UnStoredSearchTerm.java
@@ -38,7 +38,9 @@ import mir.entity.Entity;
 import org.apache.lucene.document.Document;
 import org.apache.lucene.document.Field;
 
-
+/**
+ * not currently used
+ */
 public class UnStoredSearchTerm extends SearchTerm{
   public UnStoredSearchTerm(String anEntityPart,String aParamName,String aMatchField,String aDataField, String aTemplateVariable){
       partOfEntity = anEntityPart;

diff --git a/source/mircoders/search/VideoSearchTerm.java b/source/mircoders/search/VideoSearchTerm.java
index c754e54..2268854 100755 (executable)
--- a/source/mircoders/search/VideoSearchTerm.java
+++ b/source/mircoders/search/VideoSearchTerm.java
@@ -46,7 +46,9 @@ import org.apache.lucene.document.Field;
 
 
 
-
+/**
+ * indexes whether an Enity has video
+ */
 public class VideoSearchTerm extends SearchTerm {
   public VideoSearchTerm() {
     super(null, "search_hasVideo", "hasVideo", null, "hasVideo");