LUCENE-3606: merge trunk to r1211182

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/branches/lucene3606@1211200 13f79535-47bb-0310-9956-ffa450edef68

dev-tools/eclipse/dot.classpath

@@ -13,7 +13,6 @@
 	<classpathentry kind="src" path="lucene/contrib/memory/src/java"/>
 	<classpathentry kind="src" path="lucene/contrib/memory/src/test"/>
 	<classpathentry kind="src" path="lucene/contrib/misc/src/java"/>
-	<classpathentry kind="src" output="bin.misc" path="lucene/contrib/misc/src/resources"/>
 	<classpathentry kind="src" path="lucene/contrib/misc/src/test"/>
 	<classpathentry kind="src" path="lucene/contrib/sandbox/src/java"/>
 	<classpathentry kind="src" path="lucene/contrib/sandbox/src/test"/>

lucene/contrib/misc/src/resources/META-INF/services/org.apache.lucene.index.codecs.Codec

@@ -1,16 +0,0 @@
-#  Licensed to the Apache Software Foundation (ASF) under one or more
-#  contributor license agreements.  See the NOTICE file distributed with
-#  this work for additional information regarding copyright ownership.
-#  The ASF licenses this file to You under the Apache License, Version 2.0
-#  (the "License"); you may not use this file except in compliance with
-#  the License.  You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS,
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#  See the License for the specific language governing permissions and
-#  limitations under the License.
-
-org.apache.lucene.index.codecs.appending.AppendingCodec

lucene/src/java/org/apache/lucene/index/IndexReader.java

@@ -31,6 +31,7 @@ import org.apache.lucene.document.DocumentStoredFieldVisitor;
 import org.apache.lucene.index.codecs.PerDocValues;
 import org.apache.lucene.index.values.IndexDocValues;
 import org.apache.lucene.search.FieldCache; // javadocs
+import org.apache.lucene.search.SearcherManager; // javadocs
 import org.apache.lucene.store.*;
 import org.apache.lucene.util.ArrayUtil;
 import org.apache.lucene.util.Bits;
@@ -372,8 +373,7 @@ public abstract class IndexReader implements Cloneable,Closeable {
    * for doing so); if a new reader is returned you also
    * must eventually close it.  Be sure to never close a
    * reader while other threads are still using it; see
-   * <code>SearcherManager</code> in
-   * <code>contrib/misc</code> to simplify managing this.
+   * {@link SearcherManager} to simplify managing this.
    *
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error

lucene/src/java/org/apache/lucene/index/codecs/appending/AppendingCodec.java

@@ -80,7 +80,7 @@ public class AppendingCodec extends Codec {
   public FieldInfosFormat fieldInfosFormat() {
     return fieldInfos;
   }
-
+  
   @Override
   public NormsFormat normsFormat() {
     return norms;

lucene/src/resources/META-INF/services/org.apache.lucene.index.codecs.Codec

@@ -16,3 +16,4 @@
 org.apache.lucene.index.codecs.lucene40.Lucene40Codec
 org.apache.lucene.index.codecs.lucene3x.Lucene3xCodec
 org.apache.lucene.index.codecs.simpletext.SimpleTextCodec
+org.apache.lucene.index.codecs.appending.AppendingCodec

lucene/src/test-framework/java/org/apache/lucene/util/LuceneTestCase.java

@@ -40,6 +40,7 @@ import org.apache.lucene.document.FieldType;
 import org.apache.lucene.index.*;
 import org.apache.lucene.index.codecs.Codec;
 import org.apache.lucene.index.codecs.PostingsFormat;
+import org.apache.lucene.index.codecs.appending.AppendingCodec;
 import org.apache.lucene.index.codecs.lucene40.Lucene40Codec;
 import org.apache.lucene.index.codecs.preflexrw.PreFlexRWCodec;
 import org.apache.lucene.index.codecs.simpletext.SimpleTextCodec;
@@ -286,6 +287,8 @@ public abstract class LuceneTestCase extends Assert {
       PREFLEX_IMPERSONATION_IS_ACTIVE = true;
     } else if ("SimpleText".equals(TEST_CODEC) || ("random".equals(TEST_CODEC) && randomVal == 9)) {
       codec = new SimpleTextCodec();
+    } else if ("Appending".equals(TEST_CODEC) || ("random".equals(TEST_CODEC) && randomVal == 8)) {
+      codec = new AppendingCodec();
     } else if (!"random".equals(TEST_CODEC)) {
       codec = Codec.forName(TEST_CODEC);
     } else if ("random".equals(TEST_POSTINGSFORMAT)) {

solr/core/src/java/org/apache/solr/schema/ByteField.java

@@ -28,7 +28,21 @@ import java.io.IOException;
 import java.util.Map;
 
 /**
+ * A numeric field that can contain 8-bit signed two's complement integer 
+ * values, encoded as simple Strings.
  *
+ * <p>
+ * Field values will sort numerically, but Range Queries (and other features 
+ * that rely on numeric ranges) will not work as expected: values will be 
+ * evaluated in unicode String order, not numeric order.
+ * </p>
+ *
+ * <ul>
+ *  <li>Min Value Allowed: -128</li>
+ *  <li>Max Value Allowed: 127</li>
+ * </ul>
+ *
+ * @see Byte
  */
 public class ByteField extends FieldType {
   @Override

solr/core/src/java/org/apache/solr/schema/DoubleField.java

@@ -28,7 +28,18 @@ import java.io.IOException;
 import java.util.Map;
 
 /**
+ * A legacy numeric field type that encodes "Double" values as simple Strings.
+ * This class should not be used except by people with existing indexes that
+ * contain numeric values indexed as Strings.  
+ * New schemas should use {@link TrieDoubleField}.
  *
+ * <p>
+ * Field values will sort numerically, but Range Queries (and other features 
+ * that rely on numeric ranges) will not work as expected: values will be 
+ * evaluated in unicode String order, not numeric order.
+ * </p>
+ * 
+ * @see TrieDoubleField
  */
 public class DoubleField extends FieldType {
   @Override

solr/core/src/java/org/apache/solr/schema/FloatField.java

@@ -27,7 +27,18 @@ import org.apache.solr.response.TextResponseWriter;
 import java.util.Map;
 import java.io.IOException;
 /**
+ * A legacy numeric field type that encodes "Float" values as simple Strings.
+ * This class should not be used except by people with existing indexes that
+ * contain numeric values indexed as Strings.  
+ * New schemas should use {@link TrieFloatField}.
  *
+ * <p>
+ * Field values will sort numerically, but Range Queries (and other features 
+ * that rely on numeric ranges) will not work as expected: values will be 
+ * evaluated in unicode String order, not numeric order.
+ * </p>
+ * 
+ * @see TrieFloatField
  */
 public class FloatField extends FieldType {
   @Override

solr/core/src/java/org/apache/solr/schema/IntField.java

@@ -27,7 +27,18 @@ import org.apache.solr.response.TextResponseWriter;
 import java.util.Map;
 import java.io.IOException;
 /**
+ * A legacy numeric field type that encodes "Integer" values as simple Strings.
+ * This class should not be used except by people with existing indexes that
+ * contain numeric values indexed as Strings.  
+ * New schemas should use {@link TrieIntField}.
  *
+ * <p>
+ * Field values will sort numerically, but Range Queries (and other features 
+ * that rely on numeric ranges) will not work as expected: values will be 
+ * evaluated in unicode String order, not numeric order.
+ * </p>
+ * 
+ * @see TrieIntField
  */
 public class IntField extends FieldType {
   @Override

solr/core/src/java/org/apache/solr/schema/LongField.java

@@ -27,7 +27,18 @@ import org.apache.solr.search.QParser;
 import java.io.IOException;
 import java.util.Map;
 /**
+ * A legacy numeric field type that encodes "Long" values as simple Strings.
+ * This class should not be used except by people with existing indexes that
+ * contain numeric values indexed as Strings.  
+ * New schemas should use {@link TrieLongField}.
  *
+ * <p>
+ * Field values will sort numerically, but Range Queries (and other features 
+ * that rely on numeric ranges) will not work as expected: values will be 
+ * evaluated in unicode String order, not numeric order.
+ * </p>
+ * 
+ * @see TrieLongField
  */
 public class LongField extends FieldType {
   @Override

solr/core/src/java/org/apache/solr/schema/ShortField.java

@@ -29,8 +29,21 @@ import java.util.Map;
 
 
 /**
+ * A numeric field that can contain 16-bit signed two's complement integer
+ * values, encoded as simple Strings.
  *
+ * <p>
+ * Field values will sort numerically, but Range Queries (and other features 
+ * that rely on numeric ranges) will not work as expected: values will be 
+ * evaluated in unicode String order, not numeric order.
+ * </p>
  *
+ * <ul>
+ *  <li>Min Value Allowed: -32768</li>
+ *  <li>Max Value Allowed: 32767</li>
+ * </ul>
+ *
+ * @see Short
  **/
 public class ShortField extends FieldType {
   @Override

solr/core/src/java/org/apache/solr/schema/SortableDoubleField.java

@@ -36,8 +36,19 @@ import org.apache.solr.response.TextResponseWriter;
 import java.util.Map;
 import java.io.IOException;
 /**
+ * A legacy numeric field type that encodes "Double" values as Strings such 
+ * that Term enumeration order matches the natural numeric order.  This class 
+ * should not be used except by people with existing indexes that already 
+ * contain fields of this type.  New schemas should use {@link TrieDoubleField}.
  *
+ * <p>
+ * The naming convention "Sortable" comes from the fact that both the numeric 
+ * values and encoded String representations Sort identically (as opposed to 
+ * a direct String representation where values such as "11" sort before values 
+ * such as "2").
+ * </p>
  * 
+ * @see TrieDoubleField
  * @deprecated use {@link DoubleField} or {@link TrieDoubleField} - will be removed in 5.x
  */
 @Deprecated

solr/core/src/java/org/apache/solr/schema/SortableFloatField.java

@@ -35,9 +35,21 @@ import org.apache.solr.response.TextResponseWriter;
 
 import java.util.Map;
 import java.io.IOException;
+
 /**
+ * A legacy numeric field type that encodes "Float" values as Strings such 
+ * that Term enumeration order matches the natural numeric order.  This class 
+ * should not be used except by people with existing indexes that already 
+ * contain fields of this type.  New schemas should use {@link TrieFloatField}.
  *
- * 
+ * <p>
+ * The naming convention "Sortable" comes from the fact that both the numeric 
+ * values and encoded String representations Sort identically (as opposed to 
+ * a direct String representation where values such as "11" sort before values 
+ * such as "2").
+ * </p>
+ *
+ * @see TrieFloatField
  * @deprecated use {@link FloatField} or {@link TrieFloatField} - will be removed in 5.x
  */
 @Deprecated

solr/core/src/java/org/apache/solr/schema/SortableIntField.java

@@ -35,9 +35,21 @@ import org.apache.solr.response.TextResponseWriter;
 
 import java.util.Map;
 import java.io.IOException;
+
 /**
+ * A legacy numeric field type that encodes "Integer" values as Strings such 
+ * that Term enumeration order matches the natural numeric order.  This class 
+ * should not be used except by people with existing indexes that already 
+ * contain fields of this type.  New schemas should use {@link TrieIntField}.
  *
+ * <p>
+ * The naming convention "Sortable" comes from the fact that both the numeric 
+ * values and encoded String representations Sort identically (as opposed to 
+ * a direct String representation where values such as "11" sort before values 
+ * such as "2").
+ * </p>
  * 
+ * @see TrieIntField
  * @deprecated use {@link IntField} or {@link TrieIntField} - will be removed in 5.x
  */
 @Deprecated

solr/core/src/java/org/apache/solr/schema/SortableLongField.java

@@ -36,8 +36,19 @@ import org.apache.solr.response.TextResponseWriter;
 import java.util.Map;
 import java.io.IOException;
 /**
+ * A legacy numeric field type that encodes "Long" values as Strings such 
+ * that Term enumeration order matches the natural numeric order.  This class 
+ * should not be used except by people with existing indexes that already 
+ * contain fields of this type.  New schemas should use {@link TrieLongField}.
  *
+ * <p>
+ * The naming convention "Sortable" comes from the fact that both the numeric 
+ * values and encoded String representations Sort identically (as opposed to 
+ * a direct String representation where values such as "11" sort before values 
+ * such as "2").
+ * </p>
  * 
+ * @see TrieLongField
  * @deprecated use {@link LongField} or {@link TrieLongField} - will be removed in 5.x
  */
 @Deprecated

solr/core/src/java/org/apache/solr/schema/TrieDoubleField.java

@@ -17,6 +17,22 @@
 
 package org.apache.solr.schema;
 
+/**
+ * A numeric field that can contain double-precision 64-bit IEEE 754 floating 
+ * point values.
+ *
+ * <ul>
+ *  <li>Min Value Allowed: 4.9E-324</li>
+ *  <li>Max Value Allowed: 1.7976931348623157E308</li>
+ * </ul>
+ *
+ * <b>NOTE:</b> The behavior of this class when given values of 
+ * {@link Double#NaN}, {@link Double#NEGATIVE_INFINITY}, or 
+ * {@link Double#POSITIVE_INFINITY} is undefined.
+ * 
+ * @see Double
+ * @see <a href="http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3">Java Language Specification, s4.2.3</a>
+ */
 public class TrieDoubleField extends TrieField {
   {
     type=TrieTypes.DOUBLE;

solr/core/src/java/org/apache/solr/schema/TrieFloatField.java

@@ -17,6 +17,22 @@
 
 package org.apache.solr.schema;
 
+/**
+ * A numeric field that can contain single-precision 32-bit IEEE 754 
+ * floating point values.
+ *
+ * <ul>
+ *  <li>Min Value Allowed: 1.401298464324817E-45</li>
+ *  <li>Max Value Allowed: 3.4028234663852886E38</li>
+ * </ul>
+ *
+ * <b>NOTE:</b> The behavior of this class when given values of 
+ * {@link Float#NaN}, {@link Float#NEGATIVE_INFINITY}, or 
+ * {@link Float#POSITIVE_INFINITY} is undefined.
+ * 
+ * @see Float
+ * @see <a href="http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3">Java Language Specification, s4.2.3</a>
+ */
 public class TrieFloatField extends TrieField {
   {
     type=TrieTypes.FLOAT;

solr/core/src/java/org/apache/solr/schema/TrieIntField.java

@@ -17,6 +17,16 @@
 
 package org.apache.solr.schema;
 
+/**
+ * A numeric field that can contain 32-bit signed two's complement integer values.
+ *
+ * <ul>
+ *  <li>Min Value Allowed: -2147483648</li>
+ *  <li>Max Value Allowed: 2147483647</li>
+ * </ul>
+ * 
+ * @see Integer
+ */
 public class TrieIntField extends TrieField {
   {
     type=TrieTypes.INTEGER;

solr/core/src/java/org/apache/solr/schema/TrieLongField.java

@@ -17,6 +17,16 @@
 
 package org.apache.solr.schema;
 
+/**
+ * A numeric field that can contain 64-bit signed two's complement integer values.
+ *
+ * <ul>
+ *  <li>Min Value Allowed: -9223372036854775808</li>
+ *  <li>Max Value Allowed: 9223372036854775807</li>
+ * </ul>
+ * 
+ * @see Long
+ */
 public class TrieLongField extends TrieField {
   {
     type=TrieTypes.LONG;