+++ /dev/null
-package org.apache.lucene.document;
-
-/**
- * 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.
- */
-
-import org.apache.lucene.analysis.TokenStream;
-import org.apache.lucene.index.IndexWriter; // for javadoc
-import org.apache.lucene.util.StringHelper;
-
-import java.io.Reader;
-import java.io.Serializable;
-
-import org.apache.lucene.index.FieldInfo.IndexOptions;
-
-/**
- A field is a section of a Document. Each field has two parts, a name and a
- value. Values may be free text, provided as a String or as a Reader, or they
- may be atomic keywords, which are not further processed. Such keywords may
- be used to represent dates, urls, etc. Fields are optionally stored in the
- index, so that they may be returned with hits on the document.
- */
-
-public final class Field extends AbstractField implements Fieldable, Serializable {
-
- /** Specifies whether and how a field should be stored. */
- public static enum Store {
-
- /** Store the original field value in the index. This is useful for short texts
- * like a document's title which should be displayed with the results. The
- * value is stored in its original form, i.e. no analyzer is used before it is
- * stored.
- */
- YES {
- @Override
- public boolean isStored() { return true; }
- },
-
- /** Do not store the field value in the index. */
- NO {
- @Override
- public boolean isStored() { return false; }
- };
-
- public abstract boolean isStored();
- }
-
- /** Specifies whether and how a field should be indexed. */
- public static enum Index {
-
- /** Do not index the field value. This field can thus not be searched,
- * but one can still access its contents provided it is
- * {@link Field.Store stored}. */
- NO {
- @Override
- public boolean isIndexed() { return false; }
- @Override
- public boolean isAnalyzed() { return false; }
- @Override
- public boolean omitNorms() { return true; }
- },
-
- /** Index the tokens produced by running the field's
- * value through an Analyzer. This is useful for
- * common text. */
- ANALYZED {
- @Override
- public boolean isIndexed() { return true; }
- @Override
- public boolean isAnalyzed() { return true; }
- @Override
- public boolean omitNorms() { return false; }
- },
-
- /** Index the field's value without using an Analyzer, so it can be searched.
- * As no analyzer is used the value will be stored as a single term. This is
- * useful for unique Ids like product numbers.
- */
- NOT_ANALYZED {
- @Override
- public boolean isIndexed() { return true; }
- @Override
- public boolean isAnalyzed() { return false; }
- @Override
- public boolean omitNorms() { return false; }
- },
-
- /** Expert: Index the field's value without an Analyzer,
- * and also disable the indexing of norms. Note that you
- * can also separately enable/disable norms by calling
- * {@link Field#setOmitNorms}. No norms means that
- * index-time field and document boosting and field
- * length normalization are disabled. The benefit is
- * less memory usage as norms take up one byte of RAM
- * per indexed field for every document in the index,
- * during searching. Note that once you index a given
- * field <i>with</i> norms enabled, disabling norms will
- * have no effect. In other words, for this to have the
- * above described effect on a field, all instances of
- * that field must be indexed with NOT_ANALYZED_NO_NORMS
- * from the beginning. */
- NOT_ANALYZED_NO_NORMS {
- @Override
- public boolean isIndexed() { return true; }
- @Override
- public boolean isAnalyzed() { return false; }
- @Override
- public boolean omitNorms() { return true; }
- },
-
- /** Expert: Index the tokens produced by running the
- * field's value through an Analyzer, and also
- * separately disable the storing of norms. See
- * {@link #NOT_ANALYZED_NO_NORMS} for what norms are
- * and why you may want to disable them. */
- ANALYZED_NO_NORMS {
- @Override
- public boolean isIndexed() { return true; }
- @Override
- public boolean isAnalyzed() { return true; }
- @Override
- public boolean omitNorms() { return true; }
- };
-
- /** Get the best representation of the index given the flags. */
- public static Index toIndex(boolean indexed, boolean analyzed) {
- return toIndex(indexed, analyzed, false);
- }
-
- /** Expert: Get the best representation of the index given the flags. */
- public static Index toIndex(boolean indexed, boolean analyzed, boolean omitNorms) {
-
- // If it is not indexed nothing else matters
- if (!indexed) {
- return Index.NO;
- }
-
- // typical, non-expert
- if (!omitNorms) {
- if (analyzed) {
- return Index.ANALYZED;
- }
- return Index.NOT_ANALYZED;
- }
-
- // Expert: Norms omitted
- if (analyzed) {
- return Index.ANALYZED_NO_NORMS;
- }
- return Index.NOT_ANALYZED_NO_NORMS;
- }
-
- public abstract boolean isIndexed();
- public abstract boolean isAnalyzed();
- public abstract boolean omitNorms();
- }
-
- /** Specifies whether and how a field should have term vectors. */
- public static enum TermVector {
-
- /** Do not store term vectors.
- */
- NO {
- @Override
- public boolean isStored() { return false; }
- @Override
- public boolean withPositions() { return false; }
- @Override
- public boolean withOffsets() { return false; }
- },
-
- /** Store the term vectors of each document. A term vector is a list
- * of the document's terms and their number of occurrences in that document. */
- YES {
- @Override
- public boolean isStored() { return true; }
- @Override
- public boolean withPositions() { return false; }
- @Override
- public boolean withOffsets() { return false; }
- },
-
- /**
- * Store the term vector + token position information
- *
- * @see #YES
- */
- WITH_POSITIONS {
- @Override
- public boolean isStored() { return true; }
- @Override
- public boolean withPositions() { return true; }
- @Override
- public boolean withOffsets() { return false; }
- },
-
- /**
- * Store the term vector + Token offset information
- *
- * @see #YES
- */
- WITH_OFFSETS {
- @Override
- public boolean isStored() { return true; }
- @Override
- public boolean withPositions() { return false; }
- @Override
- public boolean withOffsets() { return true; }
- },
-
- /**
- * Store the term vector + Token position and offset information
- *
- * @see #YES
- * @see #WITH_POSITIONS
- * @see #WITH_OFFSETS
- */
- WITH_POSITIONS_OFFSETS {
- @Override
- public boolean isStored() { return true; }
- @Override
- public boolean withPositions() { return true; }
- @Override
- public boolean withOffsets() { return true; }
- };
-
- /** Get the best representation of a TermVector given the flags. */
- public static TermVector toTermVector(boolean stored, boolean withOffsets, boolean withPositions) {
-
- // If it is not stored, nothing else matters.
- if (!stored) {
- return TermVector.NO;
- }
-
- if (withOffsets) {
- if (withPositions) {
- return Field.TermVector.WITH_POSITIONS_OFFSETS;
- }
- return Field.TermVector.WITH_OFFSETS;
- }
-
- if (withPositions) {
- return Field.TermVector.WITH_POSITIONS;
- }
- return Field.TermVector.YES;
- }
-
- public abstract boolean isStored();
- public abstract boolean withPositions();
- public abstract boolean withOffsets();
- }
-
-
- /** The value of the field as a String, or null. If null, the Reader value or
- * binary value is used. Exactly one of stringValue(),
- * readerValue(), and getBinaryValue() must be set. */
- public String stringValue() { return fieldsData instanceof String ? (String)fieldsData : null; }
-
- /** The value of the field as a Reader, or null. If null, the String value or
- * binary value is used. Exactly one of stringValue(),
- * readerValue(), and getBinaryValue() must be set. */
- public Reader readerValue() { return fieldsData instanceof Reader ? (Reader)fieldsData : null; }
-
- /** The TokesStream for this field to be used when indexing, or null. If null, the Reader value
- * or String value is analyzed to produce the indexed tokens. */
- public TokenStream tokenStreamValue() { return tokenStream; }
-
-
- /** <p>Expert: change the value of this field. This can
- * be used during indexing to re-use a single Field
- * instance to improve indexing speed by avoiding GC cost
- * of new'ing and reclaiming Field instances. Typically
- * a single {@link Document} instance is re-used as
- * well. This helps most on small documents.</p>
- *
- * <p>Each Field instance should only be used once
- * within a single {@link Document} instance. See <a
- * href="http://wiki.apache.org/lucene-java/ImproveIndexingSpeed">ImproveIndexingSpeed</a>
- * for details.</p> */
- public void setValue(String value) {
- if (isBinary) {
- throw new IllegalArgumentException("cannot set a String value on a binary field");
- }
- fieldsData = value;
- }
-
- /** Expert: change the value of this field. See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
- public void setValue(Reader value) {
- if (isBinary) {
- throw new IllegalArgumentException("cannot set a Reader value on a binary field");
- }
- if (isStored) {
- throw new IllegalArgumentException("cannot set a Reader value on a stored field");
- }
- fieldsData = value;
- }
-
- /** Expert: change the value of this field. See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
- public void setValue(byte[] value) {
- if (!isBinary) {
- throw new IllegalArgumentException("cannot set a byte[] value on a non-binary field");
- }
- fieldsData = value;
- binaryLength = value.length;
- binaryOffset = 0;
- }
-
- /** Expert: change the value of this field. See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
- public void setValue(byte[] value, int offset, int length) {
- if (!isBinary) {
- throw new IllegalArgumentException("cannot set a byte[] value on a non-binary field");
- }
- fieldsData = value;
- binaryLength = length;
- binaryOffset = offset;
- }
-
- /** Expert: sets the token stream to be used for indexing and causes isIndexed() and isTokenized() to return true.
- * May be combined with stored values from stringValue() or getBinaryValue() */
- public void setTokenStream(TokenStream tokenStream) {
- this.isIndexed = true;
- this.isTokenized = true;
- this.tokenStream = tokenStream;
- }
-
- /**
- * Create a field by specifying its name, value and how it will
- * be saved in the index. Term vectors will not be stored in the index.
- *
- * @param name The name of the field
- * @param value The string to process
- * @param store Whether <code>value</code> should be stored in the index
- * @param index Whether the field should be indexed, and if so, if it should
- * be tokenized before indexing
- * @throws NullPointerException if name or value is <code>null</code>
- * @throws IllegalArgumentException if the field is neither stored nor indexed
- */
- public Field(String name, String value, Store store, Index index) {
- this(name, value, store, index, TermVector.NO);
- }
-
- /**
- * Create a field by specifying its name, value and how it will
- * be saved in the index.
- *
- * @param name The name of the field
- * @param value The string to process
- * @param store Whether <code>value</code> should be stored in the index
- * @param index Whether the field should be indexed, and if so, if it should
- * be tokenized before indexing
- * @param termVector Whether term vector should be stored
- * @throws NullPointerException if name or value is <code>null</code>
- * @throws IllegalArgumentException in any of the following situations:
- * <ul>
- * <li>the field is neither stored nor indexed</li>
- * <li>the field is not indexed but termVector is <code>TermVector.YES</code></li>
- * </ul>
- */
- public Field(String name, String value, Store store, Index index, TermVector termVector) {
- this(name, true, value, store, index, termVector);
- }
-
- /**
- * Create a field by specifying its name, value and how it will
- * be saved in the index.
- *
- * @param name The name of the field
- * @param internName Whether to .intern() name or not
- * @param value The string to process
- * @param store Whether <code>value</code> should be stored in the index
- * @param index Whether the field should be indexed, and if so, if it should
- * be tokenized before indexing
- * @param termVector Whether term vector should be stored
- * @throws NullPointerException if name or value is <code>null</code>
- * @throws IllegalArgumentException in any of the following situations:
- * <ul>
- * <li>the field is neither stored nor indexed</li>
- * <li>the field is not indexed but termVector is <code>TermVector.YES</code></li>
- * </ul>
- */
- public Field(String name, boolean internName, String value, Store store, Index index, TermVector termVector) {
- if (name == null)
- throw new NullPointerException("name cannot be null");
- if (value == null)
- throw new NullPointerException("value cannot be null");
- if (name.length() == 0 && value.length() == 0)
- throw new IllegalArgumentException("name and value cannot both be empty");
- if (index == Index.NO && store == Store.NO)
- throw new IllegalArgumentException("it doesn't make sense to have a field that "
- + "is neither indexed nor stored");
- if (index == Index.NO && termVector != TermVector.NO)
- throw new IllegalArgumentException("cannot store term vector information "
- + "for a field that is not indexed");
-
- if (internName) // field names are optionally interned
- name = StringHelper.intern(name);
-
- this.name = name;
-
- this.fieldsData = value;
-
- this.isStored = store.isStored();
-
- this.isIndexed = index.isIndexed();
- this.isTokenized = index.isAnalyzed();
- this.omitNorms = index.omitNorms();
- if (index == Index.NO) {
- // note: now this reads even wierder than before
- this.indexOptions = IndexOptions.DOCS_AND_FREQS_AND_POSITIONS;
- }
-
- this.isBinary = false;
-
- setStoreTermVector(termVector);
- }
-
- /**
- * Create a tokenized and indexed field that is not stored. Term vectors will
- * not be stored. The Reader is read only when the Document is added to the index,
- * i.e. you may not close the Reader until {@link IndexWriter#addDocument(Document)}
- * has been called.
- *
- * @param name The name of the field
- * @param reader The reader with the content
- * @throws NullPointerException if name or reader is <code>null</code>
- */
- public Field(String name, Reader reader) {
- this(name, reader, TermVector.NO);
- }
-
- /**
- * Create a tokenized and indexed field that is not stored, optionally with
- * storing term vectors. The Reader is read only when the Document is added to the index,
- * i.e. you may not close the Reader until {@link IndexWriter#addDocument(Document)}
- * has been called.
- *
- * @param name The name of the field
- * @param reader The reader with the content
- * @param termVector Whether term vector should be stored
- * @throws NullPointerException if name or reader is <code>null</code>
- */
- public Field(String name, Reader reader, TermVector termVector) {
- if (name == null)
- throw new NullPointerException("name cannot be null");
- if (reader == null)
- throw new NullPointerException("reader cannot be null");
-
- this.name = StringHelper.intern(name); // field names are interned
- this.fieldsData = reader;
-
- this.isStored = false;
-
- this.isIndexed = true;
- this.isTokenized = true;
-
- this.isBinary = false;
-
- setStoreTermVector(termVector);
- }
-
- /**
- * Create a tokenized and indexed field that is not stored. Term vectors will
- * not be stored. This is useful for pre-analyzed fields.
- * The TokenStream is read only when the Document is added to the index,
- * i.e. you may not close the TokenStream until {@link IndexWriter#addDocument(Document)}
- * has been called.
- *
- * @param name The name of the field
- * @param tokenStream The TokenStream with the content
- * @throws NullPointerException if name or tokenStream is <code>null</code>
- */
- public Field(String name, TokenStream tokenStream) {
- this(name, tokenStream, TermVector.NO);
- }
-
- /**
- * Create a tokenized and indexed field that is not stored, optionally with
- * storing term vectors. This is useful for pre-analyzed fields.
- * The TokenStream is read only when the Document is added to the index,
- * i.e. you may not close the TokenStream until {@link IndexWriter#addDocument(Document)}
- * has been called.
- *
- * @param name The name of the field
- * @param tokenStream The TokenStream with the content
- * @param termVector Whether term vector should be stored
- * @throws NullPointerException if name or tokenStream is <code>null</code>
- */
- public Field(String name, TokenStream tokenStream, TermVector termVector) {
- if (name == null)
- throw new NullPointerException("name cannot be null");
- if (tokenStream == null)
- throw new NullPointerException("tokenStream cannot be null");
-
- this.name = StringHelper.intern(name); // field names are interned
- this.fieldsData = null;
- this.tokenStream = tokenStream;
-
- this.isStored = false;
-
- this.isIndexed = true;
- this.isTokenized = true;
-
- this.isBinary = false;
-
- setStoreTermVector(termVector);
- }
-
-
- /**
- * Create a stored field with binary value. Optionally the value may be compressed.
- *
- * @param name The name of the field
- * @param value The binary value
- * @param store Must be Store.YES
- * @throws IllegalArgumentException if store is <code>Store.NO</code>
- * @deprecated Use {@link #Field(String, byte[]) instead}
- */
- @Deprecated
- public Field(String name, byte[] value, Store store) {
- this(name, value, 0, value.length);
-
- if (store == Store.NO) {
- throw new IllegalArgumentException("binary values can't be unstored");
- }
- }
-
- /**
- * Create a stored field with binary value. Optionally the value may be compressed.
- *
- * @param name The name of the field
- * @param value The binary value
- */
- public Field(String name, byte[] value) {
- this(name, value, 0, value.length);
- }
-
- /**
- * Create a stored field with binary value. Optionally the value may be compressed.
- *
- * @param name The name of the field
- * @param value The binary value
- * @param offset Starting offset in value where this Field's bytes are
- * @param length Number of bytes to use for this Field, starting at offset
- * @param store How <code>value</code> should be stored (compressed or not)
- * @throws IllegalArgumentException if store is <code>Store.NO</code>
- * @deprecated Use {@link #Field(String, byte[], int, int) instead}
- */
- @Deprecated
- public Field(String name, byte[] value, int offset, int length, Store store) {
- this(name, value, offset, length);
-
- if (store == Store.NO) {
- throw new IllegalArgumentException("binary values can't be unstored");
- }
- }
-
- /**
- * Create a stored field with binary value. Optionally the value may be compressed.
- *
- * @param name The name of the field
- * @param value The binary value
- * @param offset Starting offset in value where this Field's bytes are
- * @param length Number of bytes to use for this Field, starting at offset
- */
- public Field(String name, byte[] value, int offset, int length) {
-
- if (name == null)
- throw new IllegalArgumentException("name cannot be null");
- if (value == null)
- throw new IllegalArgumentException("value cannot be null");
-
- this.name = StringHelper.intern(name); // field names are interned
- fieldsData = value;
-
- isStored = true;
- isIndexed = false;
- isTokenized = false;
- indexOptions = IndexOptions.DOCS_AND_FREQS_AND_POSITIONS;
- omitNorms = true;
-
- isBinary = true;
- binaryLength = length;
- binaryOffset = offset;
-
- setStoreTermVector(TermVector.NO);
- }
-}
fnp / pylucene.git / blobdiff