You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by mi...@apache.org on 2013/12/27 14:15:04 UTC
svn commit: r1553670 - in
/lucene/dev/branches/lucene5376/lucene/server/src/java/org/apache/lucene/server:
./ handlers/ params/
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);
}