lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mikemcc...@apache.org
Subject svn commit: r1553670 - in /lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server: ./ handlers/ params/
Date Fri, 27 Dec 2013 13:15:04 GMT
Author: mikemccand
Date: Fri Dec 27 13:15:04 2013
New Revision: 1553670

URL: http://svn.apache.org/r1553670
Log:
LUCENE-5376: javadocs

Removed:
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/NoType.java
Modified:
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/FromFileTermFreqIterator.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/IndexState.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/Handler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ReleaseSnapshotHandler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SearchHandler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ShutdownHandler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StartIndexHandler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StatsHandler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StopIndexHandler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SuggestLookupHandler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/UpdateDocumentHandler.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/package.html
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/AnyType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/BooleanType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/EnumType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/FloatType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/IntType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/ListType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/LongType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/OrType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Param.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/PolyType.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Request.java
    lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Type.java

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/FromFileTermFreqIterator.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/FromFileTermFreqIterator.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/FromFileTermFreqIterator.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/FromFileTermFreqIterator.java
Fri Dec 27 13:15:04 2013
@@ -28,7 +28,7 @@ import org.apache.lucene.search.suggest.
 import org.apache.lucene.util.BytesRef;
 
 /** An {@link InputIterator} that pulls from a line file,
- *  using \u001f to join the suggestion, weight and payload. */
+ *  using U+001f to join the suggestion, weight and payload. */
 public class FromFileTermFreqIterator implements InputIterator, Closeable {
   private final BufferedReader reader;
   private long weight;

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/IndexState.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/IndexState.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/IndexState.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/IndexState.java
Fri Dec 27 13:15:04 2013
@@ -719,7 +719,10 @@ public class IndexState implements Close
 
   /** Holds a document and its facets. */
   public static class DocumentAndFacets {
+    /** Document. */
     public final Document doc = new Document();
+
+    /** Facets. */
     public List<CategoryPath> facets;
   }
 
@@ -857,7 +860,11 @@ public class IndexState implements Close
     synchronized(liveSettingsSaveState) {
       liveSettingsSaveState.put("indexRAMBufferSizeMB", d);
     }
+
+    // nocommit sync: what if closeIndex is happening in
+    // another thread:
     if (writer != null) {
+      // Propogate the change to the open IndexWriter
       writer.getIndexWriter().getConfig().setRAMBufferSizeMB(d);
     }
   }
@@ -879,6 +886,8 @@ public class IndexState implements Close
 
   /** Get the current save state. */
   public synchronized JSONObject getSaveState() throws IOException {
+    // nocommit this is the wrong sync (the setters all sync
+    // on each individually)
     JSONObject o = new JSONObject();
     o.put("settings", settingsSaveState);
     o.put("liveSettings", liveSettingsSaveState);
@@ -892,9 +901,10 @@ public class IndexState implements Close
     if (writer == null) {
       throw new IllegalStateException("index \"" + name + "\" isn't started: cannot commit");
     }
-    // hmm: two phase commit?
-    writer.getIndexWriter().commit();
+
+    // nocommit: two phase commit?
     taxoWriter.commit();
+    writer.getIndexWriter().commit();
 
     JSONObject saveState = new JSONObject();
     saveState.put("state", getSaveState());

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/Handler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/Handler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/Handler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/Handler.java
Fri Dec 27 13:15:04 2013
@@ -34,10 +34,13 @@ import org.apache.lucene.server.params.*
 
 public abstract class Handler {
 
-  /** Processes request into a FinishRequest, which is then
+  /** Processes request into a {@link FinishRequest}, which is then
    *  invoked to actually make changes.  We do this two-step
    *  process so that we can fail if there are unhandled
-   *  params, without having made any changes to the index. */
+   *  params, without having made any changes to the
+   *  index.  When this returns, it must have retrieved all
+   *  parameters it needs to use from the provided {@link
+   *  Request}. */
   public abstract FinishRequest handle(IndexState state, Request request, Map<String,List<String>>
params) throws Exception;
 
   /** Returns the {@link StructType} describing the
@@ -45,7 +48,7 @@ public abstract class Handler {
   public abstract StructType getType();
 
   /** Returns the brief summary documentation for this
-   *  method. */
+   *  method (English). */
   public abstract String getTopDoc();
 
   /** The {@link GlobalState} instance. */

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ReleaseSnapshotHandler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ReleaseSnapshotHandler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ReleaseSnapshotHandler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ReleaseSnapshotHandler.java
Fri Dec 27 13:15:04 2013
@@ -29,6 +29,7 @@ import org.apache.lucene.server.params.R
 import org.apache.lucene.server.params.StringType; 
 import org.apache.lucene.server.params.StructType; 
 
+/** Handles {@code releaseSnapshot}. */
 public class ReleaseSnapshotHandler extends Handler {
 
   final static StructType TYPE = new StructType(  
@@ -45,6 +46,7 @@ public class ReleaseSnapshotHandler exte
     return TYPE;
   }
 
+  /** Sole constructor. */
   public ReleaseSnapshotHandler(GlobalState state) {
     super(state);
   }

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SearchHandler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SearchHandler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SearchHandler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SearchHandler.java
Fri Dec 27 13:15:04 2013
@@ -126,6 +126,7 @@ import net.minidev.json.JSONObject;
 import net.minidev.json.JSONValue;
 import net.minidev.json.parser.ParseException;
 
+/** Handles {@code search}. */
 public class SearchHandler extends Handler {
 
   /** If a browse-only facet request asks for more than this
@@ -393,6 +394,7 @@ public class SearchHandler extends Handl
     return TYPE;
   }
 
+  /** Sole constructor. */
   public SearchHandler(GlobalState state) {
     super(state);
   }
@@ -867,6 +869,7 @@ public class SearchHandler extends Handl
     return sorted;
   }
 
+  /** Records configuration for a block join query. */
   static class BlockJoinQueryChild {
     public Sort sort;
     public int maxChildren;
@@ -1244,10 +1247,19 @@ public class SearchHandler extends Handl
     }
   }
 
+  /** Highlight configuration. */
   static class FieldHighlightConfig {
+    /** Number of passages. */
     public int maxPassages = -1;
+
+    // nocommit use enum:
+    /** Snippet or whole. */
     public String mode;
+
+    /** True if field is single valued. */
     public boolean singleValued;
+
+    /** {@link BreakIterator} to use. */
     public BreakIterator breakIterator;
   }
 
@@ -2413,6 +2425,7 @@ public class SearchHandler extends Handl
     };
   }
 
+  /** Parses the {@link Request} into a {@link Locale}. */
   public static Locale getLocale(Request r) {
     Locale locale;
     if (!r.hasParam("variant")) {

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ShutdownHandler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ShutdownHandler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ShutdownHandler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/ShutdownHandler.java
Fri Dec 27 13:15:04 2013
@@ -26,8 +26,10 @@ import org.apache.lucene.server.GlobalSt
 import org.apache.lucene.server.IndexState;
 import org.apache.lucene.server.params.*;
 
+/** Handles {@code shutdown}. */
 public class ShutdownHandler extends Handler {
 
+  /** Sole constructor. */
   public ShutdownHandler(GlobalState globalState) {
     super(globalState);
     requiresIndexName = false;

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StartIndexHandler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StartIndexHandler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StartIndexHandler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StartIndexHandler.java
Fri Dec 27 13:15:04 2013
@@ -32,6 +32,7 @@ import org.apache.lucene.server.params.S
 import org.apache.lucene.server.params.StructType;
 import net.minidev.json.JSONObject;
 
+/** Handles {@code startIndex}. */
 public class StartIndexHandler extends Handler {
   private static StructType TYPE = new StructType(
                                        new Param("indexName", "Index name", new StringType()));
@@ -46,6 +47,7 @@ public class StartIndexHandler extends H
     return "Starts an index";
   }
 
+  /** Sole constructor. */
   public StartIndexHandler(GlobalState state) {
     super(state);
   }

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StatsHandler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StatsHandler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StatsHandler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StatsHandler.java
Fri Dec 27 13:15:04 2013
@@ -38,6 +38,7 @@ import org.apache.lucene.util.RamUsageEs
 import net.minidev.json.JSONArray;
 import net.minidev.json.JSONObject;
 
+/** Handles {@code stats}. */
 public class StatsHandler extends Handler {
 
   StructType TYPE = new StructType(new Param("indexName", "Index name", new StringType()));
@@ -52,6 +53,7 @@ public class StatsHandler extends Handle
     return TYPE;
   }
 
+  /** Sole constructor. */
   public StatsHandler(GlobalState state) {
     super(state);
   }

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StopIndexHandler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StopIndexHandler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StopIndexHandler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/StopIndexHandler.java
Fri Dec 27 13:15:04 2013
@@ -29,6 +29,7 @@ import org.apache.lucene.server.params.R
 import org.apache.lucene.server.params.StringType;
 import org.apache.lucene.server.params.StructType;
 
+/** Handles {@code stopIndex}. */
 public class StopIndexHandler extends Handler {
   private static StructType TYPE = new StructType(
                                        new Param("indexName", "Index name", new StringType()));
@@ -43,6 +44,7 @@ public class StopIndexHandler extends Ha
     return "Stops an index";
   }
 
+  /** Sole constructor. */
   public StopIndexHandler(GlobalState state) {
     super(state);
   }

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SuggestLookupHandler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SuggestLookupHandler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SuggestLookupHandler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/SuggestLookupHandler.java
Fri Dec 27 13:15:04 2013
@@ -32,6 +32,7 @@ import org.apache.lucene.server.params.*
 import net.minidev.json.JSONArray;
 import net.minidev.json.JSONObject;
 
+/** Handles {@code suggestLookup}. */
 public class SuggestLookupHandler extends Handler {
 
   private final static StructType TYPE =
@@ -54,6 +55,7 @@ public class SuggestLookupHandler extend
     return "Perform an auto-suggest lookup.";
   }
 
+  /** Sole constructor. */
   public SuggestLookupHandler(GlobalState state) {
     super(state);
   }

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/UpdateDocumentHandler.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/UpdateDocumentHandler.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/UpdateDocumentHandler.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/handlers/UpdateDocumentHandler.java
Fri Dec 27 13:15:04 2013
@@ -32,6 +32,7 @@ import net.minidev.json.JSONArray;
 import net.minidev.json.JSONObject;
 import net.minidev.json.JSONValue;
 
+/** Handles {@code updateDocument}. */
 public class UpdateDocumentHandler extends Handler {
   final StructType TYPE = new StructType(
                                new Param("indexName", "Index Name", new StringType()),
@@ -50,6 +51,7 @@ public class UpdateDocumentHandler exten
     return "Replaces one document in the index.  Returns the index generation (indexGen)
that contains this added document.";
   }
 
+  /** Sole constructor. */
   public UpdateDocumentHandler(GlobalState state) {
     super(state);
     TYPE.params.putAll(AddDocumentHandler.DOCUMENT_TYPE.params);

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/package.html?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/package.html
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/package.html
Fri Dec 27 13:15:04 2013
@@ -69,6 +69,6 @@
 	  settings, which cannot.
 
 	<li> Limited infrastructure for plugins.
-
+      </ul>
   </body>
 </html>

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/AnyType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/AnyType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/AnyType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/AnyType.java
Fri Dec 27 13:15:04 2013
@@ -17,6 +17,7 @@ package org.apache.lucene.server.params;
  * limitations under the License.
  */
 
+/** Accepts any object. */
 public class AnyType extends Type {
 
   @Override

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/BooleanType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/BooleanType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/BooleanType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/BooleanType.java
Fri Dec 27 13:15:04 2013
@@ -17,6 +17,7 @@ package org.apache.lucene.server.params;
  * limitations under the License.
  */
 
+/** Type for booleans. */
 public class BooleanType extends Type {
 
   @Override

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/EnumType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/EnumType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/EnumType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/EnumType.java
Fri Dec 27 13:15:04 2013
@@ -19,11 +19,16 @@ package org.apache.lucene.server.params;
 
 import java.util.Arrays;
 
+/** Type for an enumeration. */
 public class EnumType extends Type {
-  // value, desc, value, desc, ...:
+  /** Enum labels. */
   final String[] values;
+
+  /** Enum descriptions (English). */
   final String[] descriptions;
 
+  /** Sole constructor, values is alternating label1,
+   *  desc1, label2, desc2, ... */
   public EnumType(String ... values) {
     if ((values.length & 1) != 0) {
       throw new IllegalArgumentException("input must be value/desc pairs");
@@ -41,6 +46,7 @@ public class EnumType extends Type {
     if (!(o instanceof String)) {
       throw new IllegalArgumentException("expected String but got " + o.getClass());
     }
+    // nocommit use Set?
     for(int i=0;i<values.length;i++) {
       if (o.equals(values[i])) {
         return;

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/FloatType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/FloatType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/FloatType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/FloatType.java
Fri Dec 27 13:15:04 2013
@@ -19,6 +19,7 @@ package org.apache.lucene.server.params;
 
 import java.math.BigDecimal;
 
+/** Type for any number that could be a double. */
 public class FloatType extends Type {
 
   @Override

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/IntType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/IntType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/IntType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/IntType.java
Fri Dec 27 13:15:04 2013
@@ -17,6 +17,7 @@ package org.apache.lucene.server.params;
  * limitations under the License.
  */
 
+/** Type for an integer. */
 public class IntType extends Type {
 
   @Override

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/ListType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/ListType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/ListType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/ListType.java
Fri Dec 27 13:15:04 2013
@@ -19,9 +19,11 @@ package org.apache.lucene.server.params;
 
 import java.util.List;
 
+/** Type for a list of items of fixed subType. */
 public class ListType extends Type {
   public final Type subType;
 
+  /** Sole constructor. */
   public ListType(Type subType) {
     this.subType = subType;
   }
@@ -36,6 +38,7 @@ public class ListType extends Type {
     }
   }
 
+  /** Returns item subType. */
   public Type getSubType() {
     return subType;
   }

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/LongType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/LongType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/LongType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/LongType.java
Fri Dec 27 13:15:04 2013
@@ -17,6 +17,7 @@ package org.apache.lucene.server.params;
  * limitations under the License.
  */
 
+/** Type for a long. */
 public class LongType extends Type {
 
   @Override

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/OrType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/OrType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/OrType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/OrType.java
Fri Dec 27 13:15:04 2013
@@ -17,9 +17,11 @@ package org.apache.lucene.server.params;
  * limitations under the License.
  */
 
+/** Type that accepts any of the provided list of types. */
 public class OrType extends Type {
   public final Type[] types;
 
+  /** Sole constructor. */
   public OrType(Type... types) {
     this.types = types;
   }

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Param.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Param.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Param.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Param.java
Fri Dec 27 13:15:04 2013
@@ -17,12 +17,22 @@ package org.apache.lucene.server.params;
  * limitations under the License.
  */
 
+/** Represents one paramater to a method. */
 public class Param {
+
+  /** Name. */
   public final String name;
+
+  /** Description (English). */
   public final String desc;
+
+  /** Type description. */
   public final Type type;
+
+  /** Default value; if null the parameter is required. */
   public final Object defaultValue;
 
+  /** Creates this, with a default value. */
   public Param(String name, String desc, Type type, Object defaultValue) {
     this.name = name;
     this.desc = desc;
@@ -33,6 +43,7 @@ public class Param {
     }
   }
 
+  /** Creates this, with no default value. */
   public Param(String name, String desc, Type type) {
     this(name, desc, type, null);
   }

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/PolyType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/PolyType.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/PolyType.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/PolyType.java
Fri Dec 27 13:15:04 2013
@@ -21,33 +21,43 @@ import java.util.HashMap;
 import java.util.Map;
 
 /** Allows one parameter in a struct (usually named class)
- *  to define/refine the type of the struct (like
- *  polymorphism). For example, this is used for a generic
- *  "similarity": the "class" param will specify a concrete
- *  class (DefaultSim, BM25Sim, etc.), and switch the struct
- *  to other types (because each sim impl takes different
- *  params) based on that.  */
+ *  to define/refine the type of the struct.  For example,
+ *  this is used for a generic "similarity": the "class"
+ *  param will specify a concrete class (DefaultSim,
+ *  BM25Sim, etc.), and switch the struct to other types
+ *  (because each sim impl takes different params) based on
+ *  that. */
 
 @SuppressWarnings("rawtypes")
 public class PolyType extends Type {
 
+  /** Maps parameter name to the {@link PolyEntry}
+   *  describing the sub type. */
   public final Map<String,PolyEntry> types = new HashMap<String,PolyEntry>();
 
-  // NOTE: not yet used but ... could be used in the future
-  // to allow custom (plugin) classes to be accepted
+  /** Not yet used but ... could be used in the future
+   *  to allow custom (plugin) classes to be accepted. */
   public final Class baseClass;
 
+  /** Describes one sub type. */
   public static class PolyEntry {
+
+    /** Name of the sub-type, e.g. BM25Similarity. */
     public final String name;
+
+    /** Defines the sub type. */
     public final StructType type;
+
+    /** Description of this entry (English). */
     public final String desc;
 
+    /** Creates this, folding the provided params into a
+     *  new {@link StructType}. */
     public PolyEntry(String name, String desc, Param... params) {
-      this.name = name;
-      this.desc = desc;
-      this.type = new StructType(params);
+      this(name, desc, new StructType(params));
     }
 
+    /** Creates this. */
     public PolyEntry(String name, String desc, StructType type) {
       this.name = name;
       this.desc = desc;
@@ -59,6 +69,7 @@ public class PolyType extends Type {
   public void validate(Object o) {
   }
 
+  /** Sole constructor. */
   public PolyType(Class baseClass, PolyEntry... entries) {
     this.baseClass = baseClass;
     for(PolyEntry e : entries) {

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Request.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Request.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Request.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Request.java
Fri Dec 27 13:15:04 2013
@@ -26,18 +26,35 @@ import org.apache.lucene.server.params.P
 import net.minidev.json.JSONArray;
 import net.minidev.json.JSONObject;
 
-/** Just pairs up the actual request with its type. */
+// nocommit instead of removing as we getXXX, we could do a
+// Set<String> seen?
+
+/** Pairs up the actual parameters with its type.  For
+ *  complex requests, e.g. {@code search}, this is used
+ *  recursively.  For example, the top-most Request is
+ *  created, but then when a sub-struct parameter is
+ *  retrieved with {@link #getStruct}, that returns another
+ *  {@code Request} wrapping that value. */
+
 public class Request {
 
-  // Type describing the expected object
+  /** Type describing the expected object. */
   private final StructType type;
 
-  // A particular request:
+  /** The actual request parameters. */
   private final JSONObject params;
 
+  /** Parent, if this is a sub Request, else null for the
+   *  top-level request.  This is used for back-trace for
+   *  error reporting. */
   private final Request parent;
+
+  /** Our parameter name from our parent, or null if we are
+   *  a top request.  This is used for back-trace for error
+   *  reporting. */
   private final String name;
 
+  /** Sole constructor. */
   public Request(Request parent, String name, JSONObject params, StructType type) {
     this.params = params;
     this.type = type;
@@ -45,41 +62,48 @@ public class Request {
     this.name = name;
   }
 
+  /** Clears all parameters. */
   public void clearParams() {
     params.clear();
   }
 
+  /** Clear a specific parameter. */
   public void clearParam(String param) {
     params.remove(param);
   }
 
+  /** Get the type for this request. */
   public StructType getType() {
     return type;
   }
 
-  // nocommit remove after full cutover to PolyType
-  public Request newType(StructType otherType) {
-    return new Request(parent, name, params, otherType);
-  }
-
+  /** True if this param was specified. */
   public boolean hasParam(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
     return params.containsKey(name);
   }
 
+  /** Returns an iterator over all parameters and their
+   *  values. */
   public Iterator<Map.Entry<String,Object>> getParams() {
     return params.entrySet().iterator();
   }
 
+  /** Returns the parameters. */
   public JSONObject getRawParams() {
     return params;
   }
 
+  @Override
   public String toString() {
     return params.toString();
   }
 
+  /** Returns the raw (un type cast) value for this
+   *  parameter.  Once this is called
+   *  for a given parameter it cannot be called again on
+   *  that parameter.*/
   public Object getAny(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
@@ -103,6 +127,9 @@ public class Request {
     }
   }
 
+  /** Retrieve a boolean parameter.  Once this is called
+   *  for a given parameter it cannot be called again on
+   *  that parameter. */
   public boolean getBoolean(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
@@ -130,6 +157,9 @@ public class Request {
     }
   }
 
+  /** Retrieve a float parameter.  Once this is called
+   *  for a given parameter it cannot be called again on
+   *  that parameter. */
   public float getFloat(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
@@ -157,6 +187,9 @@ public class Request {
     }
   }
 
+  /** Retrieve an int parameter.  Once this is called
+   *  for a given parameter it cannot be called again on
+   *  that parameter. */
   public int getInt(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
@@ -183,6 +216,9 @@ public class Request {
     }
   }
 
+  /** Retrieve a long parameter.  Once this is called
+   *  for a given parameter it cannot be called again on
+   *  that parameter. */
   public long getLong(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
@@ -209,10 +245,10 @@ public class Request {
     }
   }
 
+  /** True if the parameter is a string value. */
   public boolean isString(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
-    //assert p.type instanceof StringType: "name \"" + name + "\" is not StringType: got
" + p.type;
     Object v = params.get(name);
     return v instanceof String;
   }
@@ -221,6 +257,9 @@ public class Request {
   // here ... maybe we need isEnumValue(name, X)?  having
   // else/if chain in the code can hide a sneaky bug
 
+  /** Retrieve a string parameter.  Once this is called
+   *  for a given parameter it cannot be called again on
+   *  that parameter. */
   public String getString(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
@@ -247,7 +286,14 @@ public class Request {
     }
   }
 
+  /** Retrieve an enum parameter.  Once this is called
+   *  for a given parameter it cannot be called again on
+   *  that parameter. */
   public String getEnum(String name) {
+    // nocommit bad that enum values is not strongly typed
+    // here ... maybe we need isEnumValue(name, X)?  having
+    // else/if chain in the code can hide a sneaky bug
+
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
     assert p.type instanceof EnumType: "name \"" + name + "\" is not EnumType: got " + p.type;
@@ -274,16 +320,24 @@ public class Request {
     }
   }
 
+  /** A result returned from {@link #getPoly}. */
   public static class PolyResult {
+    /** The name of the poly parameter. */
     public final String name;
+
+    /** The new request, cast to the poly sub type */
     public final Request r;
 
+    /** Sole constructor. */
     PolyResult(String name, Request r) {
       this.name = name;
       this.r = r;
     }
   }
 
+  /** Retrieve a poly typed parameter.  Once this is called
+   *  for a given parameter it cannot be called again on
+   *  that parameter. */
   public PolyResult getPoly(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter";
@@ -305,14 +359,19 @@ public class Request {
         fail(name, "unrecognized value \"" + value + "\"; must be one of: " + pt.types.keySet());
       }
       params.remove(name);
-      return new PolyResult((String) v, newType(sub.type));
+      return new PolyResult((String) v, new Request(parent, name, params, sub.type));
     }
   }
 
+  /** Retrieve the raw object for a parameter, or null if
+   *  the parameter was not specified.  This can be called
+   *  multiple types for a given parameter. */
   public Object getRaw(String name) {
     return params.get(name);
   }
 
+  /** Retrieve a struct parameter.  This can be called
+   *  multiple times for a given parameter name. */
   public Request getStruct(String name) {
     Param p = type.params.get(name);
     assert p != null: "name \"" + name + "\" is not a known parameter; valid params=" + type.params.keySet()
+ "; path=" + getPath();
@@ -347,6 +406,9 @@ public class Request {
         fail(name, "expected Object but got " + v.getClass());
       }
 
+      // nocommit does this mean we fail to detect when a
+      // whole extra struct was specified
+
       // Don't remove, so that we can recurse and make sure
       // all structs had all their params visited too
       //params.remove(name);

Modified: lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Type.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Type.java?rev=1553670&r1=1553669&r2=1553670&view=diff
==============================================================================
--- lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Type.java
(original)
+++ lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server/params/Type.java
Fri Dec 27 13:15:04 2013
@@ -17,10 +17,15 @@ package org.apache.lucene.server.params;
  * limitations under the License.
  */
 
+/** Base class for al types. */
 public abstract class Type {
 
+  /** Sole constructor. */
   protected Type() {
   }
 
+  /** Confirms that the object is a valid item matching the
+   *  type; if it is not, throw {@code
+   *  IllegalArgumentException}. */
   public abstract void validate(Object o);
 }



Mime
View raw message