lucene-java-3.5.0/lucene/src/java/org/apache/lucene/document/Fieldable.java

   1 package org.apache.lucene.document;
   2
   3 /**
   4  * Copyright 2004 The Apache Software Foundation
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 import org.apache.lucene.analysis.TokenStream;
  20 import org.apache.lucene.index.FieldInfo.IndexOptions;
  21 import org.apache.lucene.index.FieldInvertState; // for javadocs
  22 import org.apache.lucene.search.PhraseQuery; // for javadocs
  23 import org.apache.lucene.search.spans.SpanQuery; // for javadocs
  24
  25 import java.io.Reader;
  26 import java.io.Serializable;
  27
  28 /**
  29  * Synonymous with {@link Field}.
  30  *
  31  * <p><bold>WARNING</bold>: This interface may change within minor versions, despite Lucene's backward compatibility requirements.
  32  * This means new methods may be added from version to version.  This change only affects the Fieldable API; other backwards
  33  * compatibility promises remain intact. For example, Lucene can still
  34  * read and write indices created within the same major version.
  35  * </p>
  36  *
  37  **/
  38 public interface Fieldable extends Serializable {
  39   /** Sets the boost factor hits on this field.  This value will be
  40    * multiplied into the score of all hits on this this field of this
  41    * document.
  42    *
  43    * <p>The boost is multiplied by {@link org.apache.lucene.document.Document#getBoost()} of the document
  44    * containing this field.  If a document has multiple fields with the same
  45    * name, all such values are multiplied together.  This product is then
  46    * used to compute the norm factor for the field.  By
  47    * default, in the {@link
  48    * org.apache.lucene.search.Similarity#computeNorm(String,
  49    * FieldInvertState)} method, the boost value is multiplied
  50    * by the {@link
  51    * org.apache.lucene.search.Similarity#lengthNorm(String,
  52    * int)} and then rounded by {@link org.apache.lucene.search.Similarity#encodeNormValue(float)} before it is stored in the
  53    * index.  One should attempt to ensure that this product does not overflow
  54    * the range of that encoding.
  55    *
  56    * @see org.apache.lucene.document.Document#setBoost(float)
  57    * @see org.apache.lucene.search.Similarity#computeNorm(String, FieldInvertState)
  58    * @see org.apache.lucene.search.Similarity#encodeNormValue(float)
  59    */
  60   void setBoost(float boost);
  61
  62   /** Returns the boost factor for hits for this field.
  63    *
  64    * <p>The default value is 1.0.
  65    *
  66    * <p>Note: this value is not stored directly with the document in the index.
  67    * Documents returned from {@link org.apache.lucene.index.IndexReader#document(int)} and
  68    * {@link org.apache.lucene.search.Searcher#doc(int)} may thus not have the same value present as when
  69    * this field was indexed.
  70    *
  71    * @see #setBoost(float)
  72    */
  73   float getBoost();
  74
  75   /** Returns the name of the field as an interned string.
  76    * For example "date", "title", "body", ...
  77    */
  78   String name();
  79
  80   /** The value of the field as a String, or null.
  81    * <p>
  82    * For indexing, if isStored()==true, the stringValue() will be used as the stored field value
  83    * unless isBinary()==true, in which case getBinaryValue() will be used.
  84    *
  85    * If isIndexed()==true and isTokenized()==false, this String value will be indexed as a single token.
  86    * If isIndexed()==true and isTokenized()==true, then tokenStreamValue() will be used to generate indexed tokens if not null,
  87    * else readerValue() will be used to generate indexed tokens if not null, else stringValue() will be used to generate tokens.
  88    */
  89   public String stringValue();
  90
  91   /** The value of the field as a Reader, which can be used at index time to generate indexed tokens.
  92    * @see #stringValue()
  93    */
  94   public Reader readerValue();
  95
  96   /** The TokenStream for this field to be used when indexing, or null.
  97    * @see #stringValue()
  98    */
  99   public TokenStream tokenStreamValue();
 100
 101   /** True if the value of the field is to be stored in the index for return
 102     with search hits. */
 103   boolean  isStored();
 104
 105   /** True if the value of the field is to be indexed, so that it may be
 106     searched on. */
 107   boolean  isIndexed();
 108
 109   /** True if the value of the field should be tokenized as text prior to
 110     indexing.  Un-tokenized fields are indexed as a single word and may not be
 111     Reader-valued. */
 112   boolean  isTokenized();
 113
 114   /** True if the term or terms used to index this field are stored as a term
 115    *  vector, available from {@link org.apache.lucene.index.IndexReader#getTermFreqVector(int,String)}.
 116    *  These methods do not provide access to the original content of the field,
 117    *  only to terms used to index it. If the original content must be
 118    *  preserved, use the <code>stored</code> attribute instead.
 119    *
 120    * @see org.apache.lucene.index.IndexReader#getTermFreqVector(int, String)
 121    */
 122   boolean isTermVectorStored();
 123
 124   /**
 125    * True if terms are stored as term vector together with their offsets
 126    * (start and end positon in source text).
 127    */
 128   boolean isStoreOffsetWithTermVector();
 129
 130   /**
 131    * True if terms are stored as term vector together with their token positions.
 132    */
 133   boolean isStorePositionWithTermVector();
 134
 135   /** True if the value of the field is stored as binary */
 136   boolean  isBinary();
 137
 138   /** True if norms are omitted for this indexed field */
 139   boolean getOmitNorms();
 140
 141   /** Expert:
 142    *
 143    * If set, omit normalization factors associated with this indexed field.
 144    * This effectively disables indexing boosts and length normalization for this field.
 145    */
 146   void setOmitNorms(boolean omitNorms);
 147
 148   /**
 149    * Indicates whether a Field is Lazy or not.  The semantics of Lazy loading are such that if a Field is lazily loaded, retrieving
 150    * it's values via {@link #stringValue()} or {@link #getBinaryValue()} is only valid as long as the {@link org.apache.lucene.index.IndexReader} that
 151    * retrieved the {@link Document} is still open.
 152    *
 153    * @return true if this field can be loaded lazily
 154    */
 155   boolean isLazy();
 156
 157   /**
 158    * Returns offset into byte[] segment that is used as value, if Field is not binary
 159    * returned value is undefined
 160    * @return index of the first character in byte[] segment that represents this Field value
 161    */
 162   abstract int getBinaryOffset();
 163
 164   /**
 165    * Returns length of byte[] segment that is used as value, if Field is not binary
 166    * returned value is undefined
 167    * @return length of byte[] segment that represents this Field value
 168    */
 169   abstract int getBinaryLength();
 170
 171   /**
 172    * Return the raw byte[] for the binary field.  Note that
 173    * you must also call {@link #getBinaryLength} and {@link
 174    * #getBinaryOffset} to know which range of bytes in this
 175    * returned array belong to the field.
 176    * @return reference to the Field value as byte[].
 177    */
 178   abstract byte[] getBinaryValue();
 179
 180   /**
 181    * Return the raw byte[] for the binary field.  Note that
 182    * you must also call {@link #getBinaryLength} and {@link
 183    * #getBinaryOffset} to know which range of bytes in this
 184    * returned array belong to the field.<p>
 185    * About reuse: if you pass in the result byte[] and it is
 186    * used, likely the underlying implementation will hold
 187    * onto this byte[] and return it in future calls to
 188    * {@link #getBinaryValue()}.
 189    * So if you subsequently re-use the same byte[] elsewhere
 190    * it will alter this Fieldable's value.
 191    * @param result  User defined buffer that will be used if
 192    *  possible.  If this is null or not large enough, a new
 193    *  buffer is allocated
 194    * @return reference to the Field value as byte[].
 195    */
 196   abstract byte[] getBinaryValue(byte[] result);
 197
 198   /** @see #setIndexOptions */
 199   IndexOptions getIndexOptions();
 200
 201   /** Expert:
 202   *
 203   * If set, omit term freq, and optionally positions and payloads from
 204   * postings for this field.
 205   *
 206   * <p><b>NOTE</b>: While this option reduces storage space
 207   * required in the index, it also means any query
 208   * requiring positional information, such as {@link
 209   * PhraseQuery} or {@link SpanQuery} subclasses will
 210   * silently fail to find results.
 211   */
 212   void setIndexOptions(IndexOptions indexOptions);
 213 }