From a4702d3711e8ad2ac5ef455e4182f2da80011c86 Mon Sep 17 00:00:00 2001 From: Robert Muir Date: Thu, 30 Aug 2012 14:33:44 +0000 Subject: [PATCH] javadocs git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1378959 13f79535-47bb-0310-9956-ffa450edef68 --- lucene/build.xml | 1 + .../lucene/document/ByteDocValuesField.java | 9 +++ .../lucene/document/CompressionTools.java | 8 +++ .../org/apache/lucene/document/DateTools.java | 15 ++++- .../document/DerefBytesDocValuesField.java | 26 ++++++++ .../document/DocumentStoredFieldVisitor.java | 7 +++ .../lucene/document/DoubleDocValuesField.java | 9 +++ .../apache/lucene/document/DoubleField.java | 24 +++++++- .../org/apache/lucene/document/Field.java | 55 ++++++++++++++++- .../org/apache/lucene/document/FieldType.java | 48 ++++++++++++++- .../lucene/document/FloatDocValuesField.java | 9 +++ .../apache/lucene/document/FloatField.java | 24 +++++++- .../lucene/document/IntDocValuesField.java | 9 +++ .../org/apache/lucene/document/IntField.java | 24 +++++++- .../lucene/document/LongDocValuesField.java | 9 +++ .../org/apache/lucene/document/LongField.java | 24 +++++++- .../document/PackedLongDocValuesField.java | 9 +++ .../lucene/document/ShortDocValuesField.java | 9 +++ .../document/SortedBytesDocValuesField.java | 25 ++++++++ .../apache/lucene/document/StoredField.java | 59 +++++++++++++++++++ .../document/StraightBytesDocValuesField.java | 26 ++++++++ .../apache/lucene/document/StringField.java | 7 ++- .../org/apache/lucene/document/TextField.java | 21 ++++++- 23 files changed, 442 insertions(+), 15 deletions(-) diff --git a/lucene/build.xml b/lucene/build.xml index e4f2b9b189e..7f394e3eefb 100644 --- a/lucene/build.xml +++ b/lucene/build.xml @@ -251,6 +251,7 @@ + diff --git a/lucene/core/src/java/org/apache/lucene/document/ByteDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/ByteDocValuesField.java index 915f5f15c4e..076af30f530 100644 --- a/lucene/core/src/java/org/apache/lucene/document/ByteDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/ByteDocValuesField.java @@ -38,12 +38,21 @@ import org.apache.lucene.index.DocValues; public class ByteDocValuesField extends Field { + /** + * Type for 8-bit byte DocValues. + */ public static final FieldType TYPE = new FieldType(); static { TYPE.setDocValueType(DocValues.Type.FIXED_INTS_8); TYPE.freeze(); } + /** + * Creates a new DocValues field with the specified 8-bit byte value + * @param name field name + * @param value 8-bit byte value + * @throws IllegalArgumentException if the field name is null. + */ public ByteDocValuesField(String name, byte value) { super(name, TYPE); fieldsData = Byte.valueOf(value); diff --git a/lucene/core/src/java/org/apache/lucene/document/CompressionTools.java b/lucene/core/src/java/org/apache/lucene/document/CompressionTools.java index 5fcee267cf0..09dc91faf12 100644 --- a/lucene/core/src/java/org/apache/lucene/document/CompressionTools.java +++ b/lucene/core/src/java/org/apache/lucene/document/CompressionTools.java @@ -92,10 +92,14 @@ public class CompressionTools { return compress(result.bytes, 0, result.length, compressionLevel); } + /** Decompress the byte array previously returned by + * compress (referenced by the provided BytesRef) */ public static byte[] decompress(BytesRef bytes) throws DataFormatException { return decompress(bytes.bytes, bytes.offset, bytes.length); } + /** Decompress the byte array previously returned by + * compress */ public static byte[] decompress(byte[] value) throws DataFormatException { return decompress(value, 0, value.length); } @@ -130,6 +134,8 @@ public class CompressionTools { return decompressString(value, 0, value.length); } + /** Decompress the byte array previously returned by + * compressString back into a String */ public static String decompressString(byte[] value, int offset, int length) throws DataFormatException { final byte[] bytes = decompress(value, offset, length); CharsRef result = new CharsRef(bytes.length); @@ -137,6 +143,8 @@ public class CompressionTools { return new String(result.chars, 0, result.length); } + /** Decompress the byte array (referenced by the provided BytesRef) + * previously returned by compressString back into a String */ public static String decompressString(BytesRef bytes) throws DataFormatException { return decompressString(bytes.bytes, bytes.offset, bytes.length); } diff --git a/lucene/core/src/java/org/apache/lucene/document/DateTools.java b/lucene/core/src/java/org/apache/lucene/document/DateTools.java index 1cc3a4d8589..89f6ccff789 100644 --- a/lucene/core/src/java/org/apache/lucene/document/DateTools.java +++ b/lucene/core/src/java/org/apache/lucene/document/DateTools.java @@ -185,7 +185,20 @@ public class DateTools { /** Specifies the time granularity. */ public static enum Resolution { - YEAR(4), MONTH(6), DAY(8), HOUR(10), MINUTE(12), SECOND(14), MILLISECOND(17); + /** Limit a date's resolution to year granularity. */ + YEAR(4), + /** Limit a date's resolution to month granularity. */ + MONTH(6), + /** Limit a date's resolution to day granularity. */ + DAY(8), + /** Limit a date's resolution to hour granularity. */ + HOUR(10), + /** Limit a date's resolution to minute granularity. */ + MINUTE(12), + /** Limit a date's resolution to second granularity. */ + SECOND(14), + /** Limit a date's resolution to millisecond granularity. */ + MILLISECOND(17); final int formatLen; final SimpleDateFormat format;//should be cloned before use, since it's not threadsafe diff --git a/lucene/core/src/java/org/apache/lucene/document/DerefBytesDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/DerefBytesDocValuesField.java index 99d68291463..bc846a443fe 100644 --- a/lucene/core/src/java/org/apache/lucene/document/DerefBytesDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/DerefBytesDocValuesField.java @@ -44,23 +44,49 @@ import org.apache.lucene.util.BytesRef; public class DerefBytesDocValuesField extends Field { // TODO: ideally indexer figures out var vs fixed on its own!? + /** + * Type for indirect bytes DocValues: all with the same length + */ public static final FieldType TYPE_FIXED_LEN = new FieldType(); static { TYPE_FIXED_LEN.setDocValueType(DocValues.Type.BYTES_FIXED_DEREF); TYPE_FIXED_LEN.freeze(); } + /** + * Type for indirect bytes DocValues: can have variable lengths + */ public static final FieldType TYPE_VAR_LEN = new FieldType(); static { TYPE_VAR_LEN.setDocValueType(DocValues.Type.BYTES_VAR_DEREF); TYPE_VAR_LEN.freeze(); } + /** + * Create a new variable-length indirect DocValues field. + *

+ * This calls + * {@link DerefBytesDocValuesField#DerefBytesDocValuesField(String, BytesRef, boolean) + * DerefBytesDocValuesField(name, bytes, false}, meaning by default + * it allows for values of different lengths. If your values are all + * the same length, use that constructor instead. + * @param name field name + * @param bytes binary content + * @throws IllegalArgumentException if the field name is null + */ public DerefBytesDocValuesField(String name, BytesRef bytes) { super(name, TYPE_VAR_LEN); fieldsData = bytes; } + /** + * Create a new fixed or variable length indirect DocValues field. + *

+ * @param name field name + * @param bytes binary content + * @param isFixedLength true if all values have the same length. + * @throws IllegalArgumentException if the field name is null + */ public DerefBytesDocValuesField(String name, BytesRef bytes, boolean isFixedLength) { super(name, isFixedLength ? TYPE_FIXED_LEN : TYPE_VAR_LEN); fieldsData = bytes; diff --git a/lucene/core/src/java/org/apache/lucene/document/DocumentStoredFieldVisitor.java b/lucene/core/src/java/org/apache/lucene/document/DocumentStoredFieldVisitor.java index 5a8f4d2c25a..2f79c411f1f 100644 --- a/lucene/core/src/java/org/apache/lucene/document/DocumentStoredFieldVisitor.java +++ b/lucene/core/src/java/org/apache/lucene/document/DocumentStoredFieldVisitor.java @@ -96,6 +96,13 @@ public class DocumentStoredFieldVisitor extends StoredFieldVisitor { return fieldsToAdd == null || fieldsToAdd.contains(fieldInfo.name) ? Status.YES : Status.NO; } + /** + * Retrieve the visited document. + * @return Document populated with stored fields. Note that only + * the stored information in the field instances is valid, + * data such as boosts, indexing options, term vector options, + * etc is not set. + */ public Document getDocument() { return doc; } diff --git a/lucene/core/src/java/org/apache/lucene/document/DoubleDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/DoubleDocValuesField.java index 1a0c225ee38..bb4d1f57187 100644 --- a/lucene/core/src/java/org/apache/lucene/document/DoubleDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/DoubleDocValuesField.java @@ -38,12 +38,21 @@ import org.apache.lucene.index.DocValues; public class DoubleDocValuesField extends Field { + /** + * Type for 64-bit double DocValues. + */ public static final FieldType TYPE = new FieldType(); static { TYPE.setDocValueType(DocValues.Type.FLOAT_64); TYPE.freeze(); } + /** + * Creates a new DocValues field with the specified 64-bit double value + * @param name field name + * @param value 64-bit double value + * @throws IllegalArgumentException if the field name is null + */ public DoubleDocValuesField(String name, double value) { super(name, TYPE); fieldsData = Double.valueOf(value); diff --git a/lucene/core/src/java/org/apache/lucene/document/DoubleField.java b/lucene/core/src/java/org/apache/lucene/document/DoubleField.java index 32a01460d38..77ebdd511a2 100644 --- a/lucene/core/src/java/org/apache/lucene/document/DoubleField.java +++ b/lucene/core/src/java/org/apache/lucene/document/DoubleField.java @@ -114,6 +114,10 @@ import org.apache.lucene.util.NumericUtils; public final class DoubleField extends Field { + /** + * Type for a DoubleField that is not stored: + * normalization factors, frequencies, and positions are omitted. + */ public static final FieldType TYPE_NOT_STORED = new FieldType(); static { TYPE_NOT_STORED.setIndexed(true); @@ -124,6 +128,10 @@ public final class DoubleField extends Field { TYPE_NOT_STORED.freeze(); } + /** + * Type for a stored DoubleField: + * normalization factors, frequencies, and positions are omitted. + */ public static final FieldType TYPE_STORED = new FieldType(); static { TYPE_STORED.setIndexed(true); @@ -137,14 +145,26 @@ public final class DoubleField extends Field { /** Creates a stored or un-stored DoubleField with the provided value * and default precisionStep {@link - * NumericUtils#PRECISION_STEP_DEFAULT} (4). */ + * NumericUtils#PRECISION_STEP_DEFAULT} (4). + * @param name field name + * @param value 64-bit double value + * @param stored Store.YES if the content should also be stored + * @throws IllegalArgumentException if the field name is null. + */ public DoubleField(String name, double value, Store stored) { super(name, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED); fieldsData = Double.valueOf(value); } /** Expert: allows you to customize the {@link - * FieldType}. */ + * FieldType}. + * @param name field name + * @param value 64-bit double value + * @param type customized field type: must have {@link FieldType#numericType()} + * of {@link FieldType.NumericType#DOUBLE}. + * @throws IllegalArgumentException if the field name or type is null, or + * if the field type does not have a DOUBLE numericType() + */ public DoubleField(String name, double value, FieldType type) { super(name, type); if (type.numericType() != FieldType.NumericType.DOUBLE) { diff --git a/lucene/core/src/java/org/apache/lucene/document/Field.java b/lucene/core/src/java/org/apache/lucene/document/Field.java index 0f0a8cc8c7f..8328e0719f8 100644 --- a/lucene/core/src/java/org/apache/lucene/document/Field.java +++ b/lucene/core/src/java/org/apache/lucene/document/Field.java @@ -90,6 +90,10 @@ public class Field implements IndexableField { /** * Expert: creates a field with no initial value. * Intended only for custom Field subclasses. + * @param name field name + * @param type field type + * @throws IllegalArgumentException if either the name or type + * is null. */ protected Field(String name, FieldType type) { if (name == null) { @@ -104,6 +108,13 @@ public class Field implements IndexableField { /** * Create field with Reader value. + * @param name field name + * @param reader reader value + * @param type field type + * @throws IllegalArgumentException if either the name or type + * is null, or if the field's type is stored(), or + * if tokenized() is false. + * @throws NullPointerException if the reader is null */ public Field(String name, Reader reader, FieldType type) { if (name == null) { @@ -129,6 +140,13 @@ public class Field implements IndexableField { /** * Create field with TokenStream value. + * @param name field name + * @param tokenStream TokenStream value + * @param type field type + * @throws IllegalArgumentException if either the name or type + * is null, or if the field's type is stored(), or + * if tokenized() is false, or if indexed() is false. + * @throws NullPointerException if the tokenStream is null */ public Field(String name, TokenStream tokenStream, FieldType type) { if (name == null) { @@ -152,6 +170,15 @@ public class Field implements IndexableField { /** * Create field with binary value. + * + *

NOTE: the provided byte[] is not copied so be sure + * not to change it until you're done with this field. + * @param name field name + * @param value byte array pointing to binary content (not copied) + * @param type field type + * @throws IllegalArgumentException if the field name is null, + * or the field's type is indexed() + * @throws NullPointerException if the type is null */ public Field(String name, byte[] value, FieldType type) { this(name, value, 0, value.length, type); @@ -159,6 +186,17 @@ public class Field implements IndexableField { /** * Create field with binary value. + * + *

NOTE: the provided byte[] is not copied so be sure + * not to change it until you're done with this field. + * @param name field name + * @param value byte array pointing to binary content (not copied) + * @param offset starting position of the byte array + * @param length valid length of the byte array + * @param type field type + * @throws IllegalArgumentException if the field name is null, + * or the field's type is indexed() + * @throws NullPointerException if the type is null */ public Field(String name, byte[] value, int offset, int length, FieldType type) { this(name, new BytesRef(value, offset, length), type); @@ -169,6 +207,12 @@ public class Field implements IndexableField { * *

NOTE: the provided BytesRef is not copied so be sure * not to change it until you're done with this field. + * @param name field name + * @param bytes BytesRef pointing to binary content (not copied) + * @param type field type + * @throws IllegalArgumentException if the field name is null, + * or the field's type is indexed() + * @throws NullPointerException if the type is null */ public Field(String name, BytesRef bytes, FieldType type) { if (name == null) { @@ -186,6 +230,13 @@ public class Field implements IndexableField { /** * Create field with String value. + * @param name field name + * @param value string value + * @param type field type + * @throws IllegalArgumentException if either the name or value + * is null, or if the field's type is neither indexed() nor stored(), + * or if indexed() is false but storeTermVectors() is true. + * @throws NullPointerException if the type is null */ public Field(String name, String value, FieldType type) { if (name == null) { @@ -389,7 +440,9 @@ public class Field implements IndexableField { } /** - * Sets the boost factor on this field. + * Sets the boost factor on this field. + * @throws IllegalArgumentException if this field is not indexed, + * or if it omits norms. * @see #boost() */ public void setBoost(float boost) { diff --git a/lucene/core/src/java/org/apache/lucene/document/FieldType.java b/lucene/core/src/java/org/apache/lucene/document/FieldType.java index 6a46995c7ce..a47641116b1 100644 --- a/lucene/core/src/java/org/apache/lucene/document/FieldType.java +++ b/lucene/core/src/java/org/apache/lucene/document/FieldType.java @@ -32,7 +32,16 @@ public class FieldType implements IndexableFieldType { /** Data type of the numeric value * @since 3.2 */ - public static enum NumericType {INT, LONG, FLOAT, DOUBLE} + public static enum NumericType { + /** 32-bit integer numeric type */ + INT, + /** 64-bit long numeric type */ + LONG, + /** 32-bit float numeric type */ + FLOAT, + /** 64-bit double numeric type */ + DOUBLE + } private boolean indexed; private boolean stored; @@ -99,6 +108,9 @@ public class FieldType implements IndexableFieldType { /** * Set to true to index (invert) this field. + * @param value true if this field should be indexed. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #indexed() */ public void setIndexed(boolean value) { @@ -118,6 +130,9 @@ public class FieldType implements IndexableFieldType { /** * Set to true to store this field. + * @param value true if this field should be stored. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #stored() */ public void setStored(boolean value) { @@ -138,6 +153,9 @@ public class FieldType implements IndexableFieldType { /** * Set to true to tokenize this field's contents via the * configured {@link Analyzer}. + * @param value true if this field should be tokenized. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #tokenized() */ public void setTokenized(boolean value) { @@ -158,6 +176,9 @@ public class FieldType implements IndexableFieldType { /** * Set to true if this field's indexed form should be also stored * into term vectors. + * @param value true if this field should store term vectors. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #storeTermVectors() */ public void setStoreTermVectors(boolean value) { @@ -178,6 +199,9 @@ public class FieldType implements IndexableFieldType { /** * Set to true to also store token character offsets into the term * vector for this field. + * @param value true if this field should store term vector offsets. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #storeTermVectorOffsets() */ public void setStoreTermVectorOffsets(boolean value) { @@ -198,6 +222,9 @@ public class FieldType implements IndexableFieldType { /** * Set to true to also store token positions into the term * vector for this field. + * @param value true if this field should store term vector positions. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #storeTermVectorPositions() */ public void setStoreTermVectorPositions(boolean value) { @@ -218,6 +245,9 @@ public class FieldType implements IndexableFieldType { /** * Set to true to also store token payloads into the term * vector for this field. + * @param value true if this field should store term vector payloads. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #storeTermVectorPayloads() */ public void setStoreTermVectorPayloads(boolean value) { @@ -237,6 +267,9 @@ public class FieldType implements IndexableFieldType { /** * Set to true to omit normalization values for the field. + * @param value true if this field should omit norms. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #omitNorms() */ public void setOmitNorms(boolean value) { @@ -256,6 +289,9 @@ public class FieldType implements IndexableFieldType { /** * Sets the indexing options for the field: + * @param value indexing options + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #indexOptions() */ public void setIndexOptions(IndexOptions value) { @@ -265,6 +301,9 @@ public class FieldType implements IndexableFieldType { /** * Set's the field's DocValues.Type + * @param type DocValues type, or null if no DocValues should be stored. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #docValueType() */ public void setDocValueType(DocValues.Type type) { @@ -285,6 +324,9 @@ public class FieldType implements IndexableFieldType { /** * Specifies the field's numeric type. + * @param type numeric type, or null if the field has no numeric type. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #numericType() */ public void setNumericType(NumericType type) { @@ -306,6 +348,10 @@ public class FieldType implements IndexableFieldType { /** * Sets the numeric precision step for the field. + * @param precisionStep numeric precision step for the field + * @throws IllegalArgumentException if precisionStep is less than 1. + * @throws IllegalStateException if this FieldType is frozen against + * future modifications. * @see #numericPrecisionStep() */ public void setNumericPrecisionStep(int precisionStep) { diff --git a/lucene/core/src/java/org/apache/lucene/document/FloatDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/FloatDocValuesField.java index 6add5e56866..dd4f1c20d6a 100644 --- a/lucene/core/src/java/org/apache/lucene/document/FloatDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/FloatDocValuesField.java @@ -37,12 +37,21 @@ import org.apache.lucene.index.DocValues; public class FloatDocValuesField extends Field { + /** + * Type for 32-bit float DocValues. + */ public static final FieldType TYPE = new FieldType(); static { TYPE.setDocValueType(DocValues.Type.FLOAT_32); TYPE.freeze(); } + /** + * Creates a new DocValues field with the specified 32-bit float value + * @param name field name + * @param value 32-bit float value + * @throws IllegalArgumentException if the field name is null + */ public FloatDocValuesField(String name, float value) { super(name, TYPE); fieldsData = Float.valueOf(value); diff --git a/lucene/core/src/java/org/apache/lucene/document/FloatField.java b/lucene/core/src/java/org/apache/lucene/document/FloatField.java index dcb5ea76cfc..c32394808b1 100644 --- a/lucene/core/src/java/org/apache/lucene/document/FloatField.java +++ b/lucene/core/src/java/org/apache/lucene/document/FloatField.java @@ -114,6 +114,10 @@ import org.apache.lucene.util.NumericUtils; public final class FloatField extends Field { + /** + * Type for a FloatField that is not stored: + * normalization factors, frequencies, and positions are omitted. + */ public static final FieldType TYPE_NOT_STORED = new FieldType(); static { TYPE_NOT_STORED.setIndexed(true); @@ -124,6 +128,10 @@ public final class FloatField extends Field { TYPE_NOT_STORED.freeze(); } + /** + * Type for a stored FloatField: + * normalization factors, frequencies, and positions are omitted. + */ public static final FieldType TYPE_STORED = new FieldType(); static { TYPE_STORED.setIndexed(true); @@ -137,14 +145,26 @@ public final class FloatField extends Field { /** Creates a stored or un-stored FloatField with the provided value * and default precisionStep {@link - * NumericUtils#PRECISION_STEP_DEFAULT} (4). */ + * NumericUtils#PRECISION_STEP_DEFAULT} (4). + * @param name field name + * @param value 32-bit double value + * @param stored Store.YES if the content should also be stored + * @throws IllegalArgumentException if the field name is null. + */ public FloatField(String name, float value, Store stored) { super(name, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED); fieldsData = Float.valueOf(value); } /** Expert: allows you to customize the {@link - * FieldType}. */ + * FieldType}. + * @param name field name + * @param value 32-bit float value + * @param type customized field type: must have {@link FieldType#numericType()} + * of {@link FieldType.NumericType#FLOAT}. + * @throws IllegalArgumentException if the field name or type is null, or + * if the field type does not have a FLOAT numericType() + */ public FloatField(String name, float value, FieldType type) { super(name, type); if (type.numericType() != FieldType.NumericType.FLOAT) { diff --git a/lucene/core/src/java/org/apache/lucene/document/IntDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/IntDocValuesField.java index 7b10662a7e3..28914bce434 100644 --- a/lucene/core/src/java/org/apache/lucene/document/IntDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/IntDocValuesField.java @@ -37,12 +37,21 @@ import org.apache.lucene.index.DocValues; public class IntDocValuesField extends Field { + /** + * Type for 32-bit integer DocValues. + */ public static final FieldType TYPE = new FieldType(); static { TYPE.setDocValueType(DocValues.Type.FIXED_INTS_32); TYPE.freeze(); } + /** + * Creates a new DocValues field with the specified 32-bit integer value + * @param name field name + * @param value 32-bit integer value + * @throws IllegalArgumentException if the field name is null + */ public IntDocValuesField(String name, int value) { super(name, TYPE); fieldsData = Integer.valueOf(value); diff --git a/lucene/core/src/java/org/apache/lucene/document/IntField.java b/lucene/core/src/java/org/apache/lucene/document/IntField.java index 648da431b78..ac348f46805 100644 --- a/lucene/core/src/java/org/apache/lucene/document/IntField.java +++ b/lucene/core/src/java/org/apache/lucene/document/IntField.java @@ -114,6 +114,10 @@ import org.apache.lucene.util.NumericUtils; public final class IntField extends Field { + /** + * Type for an IntField that is not stored: + * normalization factors, frequencies, and positions are omitted. + */ public static final FieldType TYPE_NOT_STORED = new FieldType(); static { TYPE_NOT_STORED.setIndexed(true); @@ -124,6 +128,10 @@ public final class IntField extends Field { TYPE_NOT_STORED.freeze(); } + /** + * Type for a stored IntField: + * normalization factors, frequencies, and positions are omitted. + */ public static final FieldType TYPE_STORED = new FieldType(); static { TYPE_STORED.setIndexed(true); @@ -137,14 +145,26 @@ public final class IntField extends Field { /** Creates a stored or un-stored IntField with the provided value * and default precisionStep {@link - * NumericUtils#PRECISION_STEP_DEFAULT} (4). */ + * NumericUtils#PRECISION_STEP_DEFAULT} (4). + * @param name field name + * @param value 32-bit integer value + * @param stored Store.YES if the content should also be stored + * @throws IllegalArgumentException if the field name is null. + */ public IntField(String name, int value, Store stored) { super(name, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED); fieldsData = Integer.valueOf(value); } /** Expert: allows you to customize the {@link - * FieldType}. */ + * FieldType}. + * @param name field name + * @param value 32-bit integer value + * @param type customized field type: must have {@link FieldType#numericType()} + * of {@link FieldType.NumericType#INT}. + * @throws IllegalArgumentException if the field name or type is null, or + * if the field type does not have a INT numericType() + */ public IntField(String name, int value, FieldType type) { super(name, type); if (type.numericType() != FieldType.NumericType.INT) { diff --git a/lucene/core/src/java/org/apache/lucene/document/LongDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/LongDocValuesField.java index 0b78eb93c4a..e3484bd60a7 100644 --- a/lucene/core/src/java/org/apache/lucene/document/LongDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/LongDocValuesField.java @@ -37,12 +37,21 @@ import org.apache.lucene.index.DocValues; public class LongDocValuesField extends Field { + /** + * Type for 64-bit long DocValues. + */ public static final FieldType TYPE = new FieldType(); static { TYPE.setDocValueType(DocValues.Type.FIXED_INTS_64); TYPE.freeze(); } + /** + * Creates a new DocValues field with the specified 64-bit long value + * @param name field name + * @param value 64-bit long value + * @throws IllegalArgumentException if the field name is null + */ public LongDocValuesField(String name, long value) { super(name, TYPE); fieldsData = Long.valueOf(value); diff --git a/lucene/core/src/java/org/apache/lucene/document/LongField.java b/lucene/core/src/java/org/apache/lucene/document/LongField.java index fb41558f66b..7535a53b94b 100644 --- a/lucene/core/src/java/org/apache/lucene/document/LongField.java +++ b/lucene/core/src/java/org/apache/lucene/document/LongField.java @@ -124,6 +124,10 @@ import org.apache.lucene.util.NumericUtils; public final class LongField extends Field { + /** + * Type for a LongField that is not stored: + * normalization factors, frequencies, and positions are omitted. + */ public static final FieldType TYPE_NOT_STORED = new FieldType(); static { TYPE_NOT_STORED.setIndexed(true); @@ -134,6 +138,10 @@ public final class LongField extends Field { TYPE_NOT_STORED.freeze(); } + /** + * Type for a stored LongField: + * normalization factors, frequencies, and positions are omitted. + */ public static final FieldType TYPE_STORED = new FieldType(); static { TYPE_STORED.setIndexed(true); @@ -147,14 +155,26 @@ public final class LongField extends Field { /** Creates a stored or un-stored LongField with the provided value * and default precisionStep {@link - * NumericUtils#PRECISION_STEP_DEFAULT} (4). */ + * NumericUtils#PRECISION_STEP_DEFAULT} (4). + * @param name field name + * @param value 64-bit long value + * @param stored Store.YES if the content should also be stored + * @throws IllegalArgumentException if the field name is null. + */ public LongField(String name, long value, Store stored) { super(name, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED); fieldsData = Long.valueOf(value); } /** Expert: allows you to customize the {@link - * FieldType}. */ + * FieldType}. + * @param name field name + * @param value 64-bit long value + * @param type customized field type: must have {@link FieldType#numericType()} + * of {@link FieldType.NumericType#LONG}. + * @throws IllegalArgumentException if the field name or type is null, or + * if the field type does not have a LONG numericType() + */ public LongField(String name, long value, FieldType type) { super(name, type); if (type.numericType() != FieldType.NumericType.LONG) { diff --git a/lucene/core/src/java/org/apache/lucene/document/PackedLongDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/PackedLongDocValuesField.java index eceff093ab5..8d3f2ba652f 100644 --- a/lucene/core/src/java/org/apache/lucene/document/PackedLongDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/PackedLongDocValuesField.java @@ -41,12 +41,21 @@ import org.apache.lucene.index.AtomicReader; // javadocs public class PackedLongDocValuesField extends Field { + /** + * Type for packed long DocValues. + */ public static final FieldType TYPE = new FieldType(); static { TYPE.setDocValueType(DocValues.Type.VAR_INTS); TYPE.freeze(); } + /** + * Creates a new DocValues field with the specified long value + * @param name field name + * @param value 64-bit long value + * @throws IllegalArgumentException if the field name is null + */ public PackedLongDocValuesField(String name, long value) { super(name, TYPE); fieldsData = Long.valueOf(value); diff --git a/lucene/core/src/java/org/apache/lucene/document/ShortDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/ShortDocValuesField.java index 2b08803197e..45dafc99664 100644 --- a/lucene/core/src/java/org/apache/lucene/document/ShortDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/ShortDocValuesField.java @@ -38,12 +38,21 @@ import org.apache.lucene.index.DocValues; public class ShortDocValuesField extends Field { + /** + * Type for 16-bit short DocValues. + */ public static final FieldType TYPE = new FieldType(); static { TYPE.setDocValueType(DocValues.Type.FIXED_INTS_16); TYPE.freeze(); } + /** + * Creates a new DocValues field with the specified 16-bit short value + * @param name field name + * @param value 16-bit short value + * @throws IllegalArgumentException if the field name is null + */ public ShortDocValuesField(String name, short value) { super(name, TYPE); fieldsData = Short.valueOf(value); diff --git a/lucene/core/src/java/org/apache/lucene/document/SortedBytesDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/SortedBytesDocValuesField.java index 07892ced7c6..594e26da733 100644 --- a/lucene/core/src/java/org/apache/lucene/document/SortedBytesDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/SortedBytesDocValuesField.java @@ -40,22 +40,47 @@ import org.apache.lucene.util.BytesRef; public class SortedBytesDocValuesField extends Field { // TODO: ideally indexer figures out var vs fixed on its own!? + /** + * Type for sorted bytes DocValues: all with the same length + */ public static final FieldType TYPE_FIXED_LEN = new FieldType(); static { TYPE_FIXED_LEN.setDocValueType(DocValues.Type.BYTES_FIXED_SORTED); TYPE_FIXED_LEN.freeze(); } + /** + * Type for sorted bytes DocValues: can have variable lengths + */ public static final FieldType TYPE_VAR_LEN = new FieldType(); static { TYPE_VAR_LEN.setDocValueType(DocValues.Type.BYTES_VAR_SORTED); TYPE_VAR_LEN.freeze(); } + /** + * Create a new variable-length sorted DocValues field. + *

+ * This calls + * {@link SortedBytesDocValuesField#SortedBytesDocValuesField(String, BytesRef, boolean) + * SortedBytesDocValuesField(name, bytes, false}, meaning by default + * it allows for values of different lengths. If your values are all + * the same length, use that constructor instead. + * @param name field name + * @param bytes binary content + * @throws IllegalArgumentException if the field name is null + */ public SortedBytesDocValuesField(String name, BytesRef bytes) { this(name, bytes, false); } + /** + * Create a new fixed or variable length sorted DocValues field. + * @param name field name + * @param bytes binary content + * @param isFixedLength true if all values have the same length. + * @throws IllegalArgumentException if the field name is null + */ public SortedBytesDocValuesField(String name, BytesRef bytes, boolean isFixedLength) { super(name, isFixedLength ? TYPE_FIXED_LEN : TYPE_VAR_LEN); fieldsData = bytes; diff --git a/lucene/core/src/java/org/apache/lucene/document/StoredField.java b/lucene/core/src/java/org/apache/lucene/document/StoredField.java index ccfa540cf41..6ffa81a8cce 100644 --- a/lucene/core/src/java/org/apache/lucene/document/StoredField.java +++ b/lucene/core/src/java/org/apache/lucene/document/StoredField.java @@ -26,6 +26,9 @@ import org.apache.lucene.util.BytesRef; * return the field and its value. */ public final class StoredField extends Field { + /** + * Type for a stored-only field. + */ public final static FieldType TYPE; static { TYPE = new FieldType(); @@ -33,38 +36,94 @@ public final class StoredField extends Field { TYPE.freeze(); } + /** + * Create a stored-only field with the given binary value. + *

NOTE: the provided byte[] is not copied so be sure + * not to change it until you're done with this field. + * @param name field name + * @param value byte array pointing to binary content (not copied) + * @throws IllegalArgumentException if the field name is null. + */ public StoredField(String name, byte[] value) { super(name, value, TYPE); } + /** + * Create a stored-only field with the given binary value. + *

NOTE: the provided byte[] is not copied so be sure + * not to change it until you're done with this field. + * @param name field name + * @param value byte array pointing to binary content (not copied) + * @param offset starting position of the byte array + * @param length valid length of the byte array + * @throws IllegalArgumentException if the field name is null. + */ public StoredField(String name, byte[] value, int offset, int length) { super(name, value, offset, length, TYPE); } + /** + * Create a stored-only field with the given binary value. + *

NOTE: the provided BytesRef is not copied so be sure + * not to change it until you're done with this field. + * @param name field name + * @param value BytesRef pointing to binary content (not copied) + * @throws IllegalArgumentException if the field name is null. + */ public StoredField(String name, BytesRef value) { super(name, value, TYPE); } + /** + * Create a stored-only field with the given string value. + * @param name field name + * @param value string value + * @throws IllegalArgumentException if the field name or value is null. + */ public StoredField(String name, String value) { super(name, value, TYPE); } // TODO: not great but maybe not a big problem? + /** + * Create a stored-only field with the given integer value. + * @param name field name + * @param value integer value + * @throws IllegalArgumentException if the field name is null. + */ public StoredField(String name, int value) { super(name, TYPE); fieldsData = value; } + /** + * Create a stored-only field with the given float value. + * @param name field name + * @param value float value + * @throws IllegalArgumentException if the field name is null. + */ public StoredField(String name, float value) { super(name, TYPE); fieldsData = value; } + /** + * Create a stored-only field with the given long value. + * @param name field name + * @param value long value + * @throws IllegalArgumentException if the field name is null. + */ public StoredField(String name, long value) { super(name, TYPE); fieldsData = value; } + /** + * Create a stored-only field with the given double value. + * @param name field name + * @param value double value + * @throws IllegalArgumentException if the field name is null. + */ public StoredField(String name, double value) { super(name, TYPE); fieldsData = value; diff --git a/lucene/core/src/java/org/apache/lucene/document/StraightBytesDocValuesField.java b/lucene/core/src/java/org/apache/lucene/document/StraightBytesDocValuesField.java index a59dd47f188..cdca59b1c9e 100644 --- a/lucene/core/src/java/org/apache/lucene/document/StraightBytesDocValuesField.java +++ b/lucene/core/src/java/org/apache/lucene/document/StraightBytesDocValuesField.java @@ -43,23 +43,49 @@ import org.apache.lucene.util.BytesRef; public class StraightBytesDocValuesField extends Field { // TODO: ideally indexer figures out var vs fixed on its own!? + /** + * Type for direct bytes DocValues: all with the same length + */ public static final FieldType TYPE_FIXED_LEN = new FieldType(); static { TYPE_FIXED_LEN.setDocValueType(DocValues.Type.BYTES_FIXED_STRAIGHT); TYPE_FIXED_LEN.freeze(); } + /** + * Type for direct bytes DocValues: can have variable lengths + */ public static final FieldType TYPE_VAR_LEN = new FieldType(); static { TYPE_VAR_LEN.setDocValueType(DocValues.Type.BYTES_VAR_STRAIGHT); TYPE_VAR_LEN.freeze(); } + /** + * Create a new variable-length direct DocValues field. + *

+ * This calls + * {@link StraightBytesDocValuesField#StraightBytesDocValuesField(String, BytesRef, boolean) + * StraightBytesDocValuesField(name, bytes, false}, meaning by default + * it allows for values of different lengths. If your values are all + * the same length, use that constructor instead. + * @param name field name + * @param bytes binary content + * @throws IllegalArgumentException if the field name is null + */ public StraightBytesDocValuesField(String name, BytesRef bytes) { super(name, TYPE_VAR_LEN); fieldsData = bytes; } + /** + * Create a new fixed or variable length direct DocValues field. + *

+ * @param name field name + * @param bytes binary content + * @param isFixedLength true if all values have the same length. + * @throws IllegalArgumentException if the field name is null + */ public StraightBytesDocValuesField(String name, BytesRef bytes, boolean isFixedLength) { super(name, isFixedLength ? TYPE_FIXED_LEN : TYPE_VAR_LEN); fieldsData = bytes; diff --git a/lucene/core/src/java/org/apache/lucene/document/StringField.java b/lucene/core/src/java/org/apache/lucene/document/StringField.java index 372b34b4ace..ad96298006c 100644 --- a/lucene/core/src/java/org/apache/lucene/document/StringField.java +++ b/lucene/core/src/java/org/apache/lucene/document/StringField.java @@ -50,7 +50,12 @@ public final class StringField extends Field { TYPE_STORED.freeze(); } - /** Creates a new StringField. */ + /** Creates a new StringField. + * @param name field name + * @param value String value + * @param stored Store.YES if the content should also be stored + * @throws IllegalArgumentException if the field name or value is null. + */ public StringField(String name, String value, Store stored) { super(name, value, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED); } diff --git a/lucene/core/src/java/org/apache/lucene/document/TextField.java b/lucene/core/src/java/org/apache/lucene/document/TextField.java index d8c66956f62..80e5f39c18e 100644 --- a/lucene/core/src/java/org/apache/lucene/document/TextField.java +++ b/lucene/core/src/java/org/apache/lucene/document/TextField.java @@ -46,17 +46,32 @@ public final class TextField extends Field { // TODO: add sugar for term vectors...? - /** Creates a new un-stored TextField with Reader value. */ + /** Creates a new un-stored TextField with Reader value. + * @param name field name + * @param reader reader value + * @throws IllegalArgumentException if the field name is null + * @throws NullPointerException if the reader is null + */ public TextField(String name, Reader reader) { super(name, reader, TYPE_NOT_STORED); } - /** Creates a new TextField with String value. */ + /** Creates a new TextField with String value. + * @param name field name + * @param value string value + * @param store Store.YES if the content should also be stored + * @throws IllegalArgumentException if the field name or value is null. + */ public TextField(String name, String value, Store store) { super(name, value, store == Store.YES ? TYPE_STORED : TYPE_NOT_STORED); } - /** Creates a new un-stored TextField with TokenStream value. */ + /** Creates a new un-stored TextField with TokenStream value. + * @param name field name + * @param stream TokenStream value + * @throws IllegalArgumentException if the field name is null. + * @throws NullPointerException if the tokenStream is null + */ public TextField(String name, TokenStream stream) { super(name, stream, TYPE_NOT_STORED); }