Return-Path: X-Original-To: apmail-lucene-commits-archive@www.apache.org Delivered-To: apmail-lucene-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id ED0501031B for ; Fri, 27 Dec 2013 13:15:30 +0000 (UTC) Received: (qmail 85323 invoked by uid 500); 27 Dec 2013 13:15:30 -0000 Mailing-List: contact commits-help@lucene.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@lucene.apache.org Delivered-To: mailing list commits@lucene.apache.org Received: (qmail 85316 invoked by uid 99); 27 Dec 2013 13:15:29 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 27 Dec 2013 13:15:28 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 27 Dec 2013 13:15:26 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id A43F623888FE; Fri, 27 Dec 2013 13:15:05 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@lucene.apache.org From: mikemccand@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20131227131505.A43F623888FE@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 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> 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.
  • Limited infrastructure for plugins. - + 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 types = new HashMap(); - // 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 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> 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); }